@@ -1,174 +0,0 @@
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/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.