@@ -0,0 +1,174 @@
2+title = "Technical overview"
5+aliases = ["/understanding-urbit/technical-overview"]
8+Urbit is a clean-slate software stack designed to implement an encrypted P2P
9+network of general-purpose personal servers. Each server on this network is a
10+deterministic computer called an 'urbit' that runs on a Unix-based virtual
13+The current Urbit stack includes (among other things):
15+- Arvo: the functional operating system of each urbit, written in Hoon.
16+- Azimuth: the Urbit identity layer, built on the Ethereum blockchain.
17+- Hoon: a strictly typed functional programming language whose standard library
18+ includes a Hoon-to-Nock compiler.
19+- Nock: a low-level combinator language whose formal specification fits readably on a t-shirt.
20+- Vere: a Nock interpreter and Unix-based virtual machine that mediates between
21+ each urbit and the Unix software layer.
23+## Anatomy of a personal server
25+Your urbit is a deterministic computer in the sense that its state is a pure
26+function of its event history. Every event in this history is a
27+[transaction](https://en.wikipedia.org/wiki/Transaction_processing); your
28+urbit's state is effectively an [ACID database](https://en.wikipedia.org/wiki/ACID).
30+Because each urbit is deterministic we can describe its role appropriately in
31+purely functional terms: it maps an input event and the old urbit state to a
32+list of output actions and the subsequent state. This is the Urbit transition
36+<input event, old state> -> <output actions, new state>
39+For example, one input event could be a keystroke from the terminal, say
40+`[enter]` after having already typed `(add 2 2)`; and an output action could be
41+to print in the terminal window the resulting value of a computation performed
42+when the user hit `[enter]`, in this case `4`. The input event is stored in the
43+urbit's event history.
45+Events always start from outside of your urbit, whether they're local to the
46+computer running the urbit (e.g., a keystroke in the terminal) or they originate
47+elsewhere (e.g., a packet received from another urbit). When an event is
48+processed, various parts of the urbit state can be modified before the resulting
49+list of output actions is returned.
51+Can output actions from your urbit cause side-effects in the outside world?
52+The answer had better be "yes," because a personal server without side effects
53+isn't useful for much. In another sense the answer had better be "no," or else
54+there is a risk of losing functional purity; your urbit cannot _guarantee_ that
55+the side effects in question actually occur. What's the solution?
58+[sandboxed](https://en.wikipedia.org/wiki/Sandbox_%28computer_security%29) in a
59+virtual machine, Vere, which runs on Unix. Code running in your urbit cannot
60+make Unix system calls or otherwise directly affect the underlying platform.
61+Strictly speaking, internal urbit code can only change internal urbit state; it
62+has no way of sending events outside of its runtime environment. Functional
65+In practical terms, however, you don't want your urbit to be an impotent
66+[brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's why
67+Vere also serves as the intermediary between your urbit and Unix. Vere observes
68+the list of output events, and when external action is called for makes the
69+appropriate system calls itself. When external events relevant to your urbit
70+occur in the Unix layer, Vere encodes and delivers them as input events.
74+Arvo is a purely functional, [non-preemptive](https://en.wikipedia.org/wiki/Cooperative_multitasking)
75+OS, written in Hoon, that serves as the event manager of your urbit.
76+It can upgrade itself from over the network without downtime. The Arvo kernel
77+proper is quite simple -- it's only about 600 lines of code, excluding its
80+The Urbit transition function is implemented in Arvo. Upon being 'poked' by
81+Vere with the pair of `<input event, state>`, Arvo directs the event to the
82+appropriate OS module. The result of each Vere 'poke' is a pair of
83+`<output events, new state>`. Events are typed, and each has an explicit
84+call-stack structure indicating the event's source module in Arvo.
86+Arvo modules are also called 'vanes'. Arvo's vanes are:
88+- Ames: defines and implements Urbit's encrypted P2P network protocol, as well
89+ as Urbit's identity protocol.
90+- Behn: manages timer events for other vanes.
91+- Clay: global, version-controlled, and referentially-transparent file system.
92+- Dill: terminal driver.
93+- Eyre: HTTP web client and server.
94+- Ford: typed functional build system.
95+- Gall: application sandbox and manager.
96+ - Dojo (app): Shell and Hoon REPL.
97+ - Talk (app): Chat client.
101+Hoon is a strictly typed functional programming language that compiles itself
102+to Nock and is designed to support higher-order functional programming without
103+requiring knowledge of category theory or other advanced mathematics. Haskell
104+is fun but it isn't for everybody.
106+Hoon aspires to a concrete, imperative feel. To discourage the creation of
107+write-only code, Hoon forbids user-level macros and uses ASCII digraphs instead
108+of keywords. The type system infers only forward and does not use unification,
109+but is not much weaker than Haskell's. The compiler and inference engine is
110+about 3000 lines of Hoon.
114+Nock is a low-level [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity)
115+combinator language. It's so simple that its [specification](@/docs/tutorials/nock/definition.md)
116+fits on a t-shirt. In some ways Nock resembles a nano-Lisp but its ambitions
117+are more narrow. Most Lisps are one-layer: a practical language is to be
118+created by extending a theoretically simple interpreter. The abstraction is
119+simple and the implementation is practical. Unfortunately it's far more difficult
120+to enforce both simplicity and practicality in an actual Lisp codebase. Hoon
121+and Nock are two layers: Hoon, the practical layer, compiles itself to Nock, the
122+simple layer. Your urbit runs in Vere, which includes a Nock interpreter, so it
123+can upgrade Hoon over the network without downtime.
125+The Nock data model is quite simple. Every piece of data is a 'noun'. A [noun](/docs/glossary/noun/)
126+is an [atom](/docs/glossary/atom/) or a cell. An atom is any unsigned integer. A cell is an ordered
127+pair of nouns. Nouns are acyclic and expose no pointer equality test.
131+Vere is the Nock runtime environment and Urbit VM. It's written in C, runs on
132+Unix, and is the intermediate layer between your urbit and Unix. As noted
133+earlier, Unix system calls are made by Vere, not Arvo; Vere must also encode
134+and deliver relevant external events to Arvo. Vere is also responsible for
135+implementing jets and maintaining the persistent state of each urbit.
137+In principle, Vere keeps a comprehensive log of every event from the time you
138+initially booted your urbit. What happens if the physical machine loses power
139+and your urbit's state is 'lost' from memory? When your urbit restarts it will
140+replay its entire event history and totally recover its latest state from
143+In practice, event logs become large and unwieldy over time. Periodically a
144+snapshot of the permanent state is taken and the logs are pruned. You're still
145+able to rebuild your state in case of power outage, down to the last keystroke.
147+Vere is not essential to the Urbit stack; one can imagine using Urbit on a
148+hypervisor, or even bare metal. One member of the community is even working on
149+an independent implementation of Urbit using Graal/Truffle on the JVM.
151+The Urbit stack (compiler, standard library, kernel, modules, and applications,
152+but excluding Vere) is about 30,000 lines of Hoon. Urbit is patent-free and MIT
157+Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum
158+blockchain, used as a decentralized ledger for what are known as **Urbit
159+identities**, or simply **identities**. Having an identity is necessary to use
160+the Urbit network, which makes it important to have a neutral ledger to
161+determine who owns what.
163+Azimuth is not, however, part of the Urbit stack. Azimuth is a parallel system
164+that can be used as a generalized identity system for other projects. Azimuth
165+"touches" the Urbit ecosystem when an Urbit identity is used to boot a virtual
166+computer on the Arvo network for the first time. When that happens, the identity
167+considered **linked** to Azimuth and the identity's full powers are available
168+for use. Once an identity is linked, it cannot be unlinked.
170+A metaphor might make the relationship between these two systems to understand:
171+Azimuth is the bank vault that stores the deed to your house. The Urbit network
172+is the neighborhood that you live in.