@@ -4,8 +4,6 @@ weight = 5
4template = "doc.html"
4template = "doc.html"
7−PR: https://github.com/urbit/azimuth/pull/43
9This document provides technical detail on Azimuth's "Layer 2" scaling solution
7This document provides technical detail on Azimuth's "Layer 2" scaling solution
10for Azimuth, known more formally as "naive rollups". We focus here primarily on the
8for Azimuth, known more formally as "naive rollups". We focus here primarily on the
11"Hoon smart contract" located at `/lib/naive.hoon` in your ship's pier, as well
9"Hoon smart contract" located at `/lib/naive.hoon` in your ship's pier, as well
@@ -28,27 +26,33 @@ essential background information for anybody in this category.
30Naive rollups were developed in response to rising gas costs for performing
28Naive rollups were developed in response to rising gas costs for performing
31−Azimuth actions.
29+Azimuth actions. They also serve the dual purpose of making onboarding easier,
30+as it is now possible to acquire a planet and get on Urbit without any knowledge
31+of Ethereum or cryptocurrency.
33+In this section we give a high-level summary of how naive rollups function and
34+how they affect the end user. Later sections elaborate on this summary.
33### Layer 1
36### Layer 1
35−We first review how "Layer 1", i.e. the [Azimuth](/docs/glossary/azimuth) smart
38+We briefly review how "Layer 1", i.e. the [Azimuth](/docs/glossary/azimuth) smart
39+contract suite, functions. An update to the Azimuth PKI data stored on your urbit
36−contract suite, functions. This happens with four steps.
40+occurs with four steps:
38 1. A transaction is posted to the Ethereum blockchain.
42 1. A transaction is posted to the Ethereum blockchain.
39− 2. The [Ethereum Virtual MAchine](https://ethereum.org/en/developers/docs/evm/)
43+ 2. The [Ethereum Virtual Machine](https://ethereum.org/en/developers/docs/evm/)
40 calculates the resulting state transition and checks its validity, then
44 calculates the resulting state transition and checks its validity, then
41 updates the state if it is a valid transition.
45 updates the state if it is a valid transition.
42 3. Your urbit downloads the new state from an Ethereum node.
46 3. Your urbit downloads the new state from an Ethereum node.
43 4. Your urbit makes the final decision on whether the new state is valid.
47 4. Your urbit makes the final decision on whether the new state is valid.
45−In practice, this step four never occurred but has always been possible in
49+By default, step four always succeeds. It has always been possible in theory for
46−theory. By default, your urbit accepts the Azimuth state obtained from the
50+your urbit to dispute what it read on Ethereum, but there has never been any
47−blockchain as valid.
51+reason to do so.
49### Layer 2
53### Layer 2
51−Layer 1 still works identically today as it did before naive rollups. Naive
55+Layer 1 still functions identically today as it did before naive rollups. Naive
52rollups work via the following process.
56rollups work via the following process.
54 1. A batch of one or more transactions is posted to the Ethereum blockchain by
58 1. A batch of one or more transactions is posted to the Ethereum blockchain by
@@ -56,7 +60,7 @@ rollups work via the following process.
56 2. Your urbit downloads the transactions from an Ethereum node.
60 2. Your urbit downloads the transactions from an Ethereum node.
57 3. Your urbit computes the resulting state transitions from the transactions
61 3. Your urbit computes the resulting state transitions from the transactions
58 and checks them for validity.
62 and checks them for validity.
59− 4. Your urbit updates your locally stored Azimuth state with state transitions
63+ 4. Your urbit updates its locally stored Azimuth state using state transitions
60 from the batch that have been deemed valid.
64 from the batch that have been deemed valid.
62 In comparison with Layer 1, the EVM no longer checks the validity or computes
66 In comparison with Layer 1, the EVM no longer checks the validity or computes
@@ -73,15 +77,16 @@ detail.
73A roller is any urbit node - even a moon, comet, or fakezod will do - to which
77A roller is any urbit node - even a moon, comet, or fakezod will do - to which
74batches of transactions are submitted. You could use your own ship as a roller
78batches of transactions are submitted. You could use your own ship as a roller
75if you wanted. The roller collects batches of transactions from whichever
79if you wanted. The roller collects batches of transactions from whichever
76−parties they choose, and submits them to the Ethereum blockchain all at once.
80+parties they choose and submits them to the Ethereum blockchain all at once.
77We expect this to either happen on a regular interval, or once some minimum
81We expect this to either happen on a regular interval, or once some minimum
78threshold of transactions is reached, but the decision on when to submit is
82threshold of transactions is reached, but the decision on when to submit is
79ultimately up to the roller.
83ultimately up to the roller.
81Computing the resulting state transitions obtained from downloaded Ethereum
85Computing the resulting state transitions obtained from downloaded Ethereum
82−transactions is done using `naive.hoon`, which is a gate that accepts both layer
86+transactions is done using `/lib/naive.hoon`, which is a gate that accepts both layer
83−1 transactions and layer 2 batches, and then computes the resulting state
87+1 transaction logs and layer 2 batches, and then computes the resulting state
84−transitions and updates the ship's internal Azimuth data accordingly.
88+transitions and updates the ship's internal Azimuth data held in
89+the Gall agent `/app/azimuth.hoon` accordingly.
86### Savings in gas costs
91### Savings in gas costs
@@ -93,97 +98,441 @@ They are:
93 2. Layer 2 Azimuth state is not stored on Ethereum, so the only data storage
98 2. Layer 2 Azimuth state is not stored on Ethereum, so the only data storage
94 gas costs is for the transactions themselves.
99 gas costs is for the transactions themselves.
95 3. Layer 2 transactions are written in a highly compressed form. E.g., instead
100 3. Layer 2 transactions are written in a highly compressed form. E.g., instead
96− of calling the spawn action by name, it is simply referred to as action `1`.
101+ of calling the spawn action by name, it is simply referred to as action `%1`.
97 4. By collecting multiple layer 2 transactions and submitting them as a single
102 4. By collecting multiple layer 2 transactions and submitting them as a single
98 "batch transaction", additional gas savings are achieved by not needing to
103 "batch transaction", additional gas savings are achieved by not needing to
99 duplicate information such as which smart contract the transactions are
104 duplicate information such as which smart contract the transactions are
100 intended for.
105 intended for.
102−Put together, these create a reduction in gas costs of at least 65x.
107+Put together, these create a reduction in gas costs of at least 65x. This is
108+true even for batches of L2 transactions that contain only a single transaction.
109+Thus there is reason to use one's own ship as an aggregator.
104### One way trip
111### One way trip
106−NOTE: Depositing to L2 clears proxies to get a gas cost discount. It also zeroes
113+Moving to layer 2 is a one-way trip for now. This means that once a ship moves
107−out escapes, keys, and claims? I'm guessing these all still remain on L2 though.
114+to layer 2, it cannot be moved back to layer 1. We believe it to be technically
115+possible to engineer a return trip, and expect that someday this will be the
116+case, but there are no plans to implement this in the near future.
109## Interacting with L2
118## Interacting with L2
111Layer 2 affects all Azimuth points on the network, even if they are on layer 1. Here we
120Layer 2 affects all Azimuth points on the network, even if they are on layer 1. Here we
112−outline what the changes are to each class. How sponsorship works on layer 2 is
121+outline what each sort of ship may perform on layer 2. How sponsorship works on layer 2 is
113more complex, and has its own [section](#sponsorship).
122more complex, and has its own [section](#sponsorship).
124+There are a total of eleven layer 2 actions, each corresponding to a familiar
125+layer 1 action: `%transfer-point`, `%spawn`, `%configure-keys`, `%escape`,
126+`%cancel-escape`, `%adopt`, `%reject`, `%detach`, `%set-management-proxy`,
127+`%set-spawn-proxy`, and `%set-transfer-proxy`.
129+Once a ship moves to layer 2, the owner will still utilize the same private keys
130+they used before the transfer to perform Azimuth actions. This includes the ownership
131+key as well as proxies. Stars and galaxies may move their spawn proxy to layer 2
132+while otherwise remaining on layer 1, but it is not possible to transfer only
133+the management proxy to layer 2; it may only happen as a side-effect of
134+transferring ownership to layer 2.
136+### Moving a pre-existing ship to L2
138+In order to move your ship from layer 1 to layer 2, you use
139+[Bridge](/docs/glossary/bridge) to transfer ownership of your ship to the
140+address `0x1111111111111111111111111111111111111111` TODO: Presumably this is
141+surfaced in the UI in Bridge, and one doesn't need to know the address. Probably
142+this should just be a link to the Operator's Manual.
146+Layer 2 Azimuth data for a given ship includes which layer that ship is on. We
147+call this the ship's _dominion_. There are three dominions: `%l1`, `l2`, and
148+`%spawn`. Planets may exist in dominion `%l1` or `%l2`, stars may exist in any
149+of the three dominions, and galaxies may exist in dominion `%l1` or `%spawn`. We
150+detail what this means in each case in the following.
115### Planets
152### Planets
117−A layer 1 planet can move to layer 2 by transferring ownership of the planet to
154+*Permitted dominions:* `%l1`, `%l2`.
118−the layer 2 deposit address. The owner will still utilize the same private keys
155+
119−they used before this transfer to perform actions. This includes both the
156+#### `%l1` planets
120−ownership address as well as the management proxy, if it has one. It is not
121−possible to transfer only the management proxy to layer 2; it may only happen as
122−a side-effect of transferring ownership to layer 2.
124−Once on layer 2, the planet may perform all Azimuth actions utilizing their
158+*Permitted layer 2 actions:* owner: `%escape`, `%cancel-escape`. management
125−ownership key. This includes transferring ownership to a new address and setting
159+proxy: `%escape`, `%cancel-escape`. transfer proxy: none.
126−a management proxy. Their management proxy may be utilized to perform all
160+
127−actions allowed by the management proxy - changing keys, breaching, and changing
161+A planet in dominion `%l1` is said to exist on layer 1, which is the default
128−sponsors.
162+state for all planets prior to the introduction of naive rollups. In addition to
163+the ordinary layer 1 Azimuth actions a planet can perform, they may also choose to
164+`%escape` or `%cancel-escape` on layer 2 using either their ownership key or
165+[management proxy](/docs/glossary/proxies). See the [sponsorship](#sponsorship)
166+section below for more information on layer 1 ships performing layer 2
169+Layer 1 planets may also move to dominion `%l2` by depositing their ownership to
170+the layer 2 deposit address.
174+*Permitted layer 2 actions:* owner: `%transfer-point`, `%configure-keys`,
175+`%escape`, `%cancel-escape`, `%set-management-proxy`, `%set-transfer-proxy`.
176+management proxy: `%configure-keys`, `%escape`, `%cancel-escape`,
177+`%set-management-proxy`. transfer proxy: `%transfer-point`, `%set-transfer-proxy`.
179+A planet in dominion `%l2` is said to exist on layer 2. A planet may be on layer
180+2 either by previously being a layer 1 planet deposited to the layer 2 address,
181+or by being spawned by a star in dominion `%spawn` or `%l2`, in which case it
182+will always be on layer 2.
184+A layer 2 planet is no longer capable of performing any layer 1 actions, and
185+cannot move to layer 1.
132−Naive rollups permit three possible states for stars. They may exist entirely on
189+*Permitted dominions:* `%l1`, `%spawn`, `%l2`.
133−layer 1, they may have their ownership and management proxy on layer 1 with
190+
134−their spawn proxy on layer 2, or they may exist entirely on layer 2.
191+#### `%l1` stars
193+*Permitted layer 2 actions:* owner: `%escape`, `%cancel-escape`, `%adopt`,
194+`%reject`, `%detach`. management proxy: `%escape`, `%cancel-escape`, `%adopt`,
195+`%reject`, `%detach`. spawn proxy: none. transfer proxy: none.
136−#### Layer 2 spawn proxy
197+A star in dominion `%l1` is said to exist on layer 1, which is the default state
198+for all stars prior to the introduction of naive rollups. In addition to the
199+ordinary Azimuth actions a star can perform, they may also perform any
200+sponsorship-related actions on layer 2.
138−A star may change its spawn proxy to layer 2. This allows the star to spawn
202+A `%l1` dominion star may move to dominion `%spawn` by depositing its spawn proxy to the
139−planets directly on layer 2 with the accompanying gas cost savings. A star with
203+layer 2 deposit address, or may move to dominion `%l2` by depositing its ownership
140−its spawn proxy on layer 2 will no longer be able to spawn layer 1 planets, but
204+to the layer 2 deposit address. Both actions are irreversible.
141−any layer 1 planets sponsored by the star will remain so. This action is
142−currently irreversible - the only further change to layer 2 status that is
143−possible would be to transfer ownership to layer 2 as well. All actions besides
144−spawning and sponsorship (see [below](#sponsorship)) must be performed on layer 1.
146−#### Layer 2 ownership
206+#### `%spawn` stars
148−A star entirely on layer 1, or a star on layer 1 with a layer 2 spawn proxy, may
208+*Permitted layer 2 actions:* owner: `%escape`, `%cancel-escape`, `%adopt`,
149−transfer ownership to layer 2 by transferring ownership to the layer 2 deposit
209+`%reject`, `%detach`, `%spawn`, `%set-spawn-proxy`. management proxy: `%escape`,
150−address. This will allow the star to perform all Azimuth actions as layer 2
210+`%cancel-escape`, `%adopt`, `%reject`, `%detach`. spawn proxy: `%spawn`,
151−actions with the associated gas cost savings.
211+`%set-spawn-proxy`. transfer proxy: none.
153−Transferring ownership to layer 2 automatically moves the spawn proxy to layer 2
213+A star in dominion `%spawn` is said to exist on layer 1.
154−(if it is not already there), as well as the management proxy. Thus the star
214+
155−owner may then perform management proxy tasks on layer 2. Layer 1 actions are no
215+A star in dominion `%spawn` may spawn planets directly on layer 2, but will no
156−longer accessible to a star whose ownership exists on layer 2.
216+longer be able to spawn layer 1 planets and will no longer be able to set its
217+spawn proxy on layer 1. All other layer 1 Azimuth actions may still be performed
220+A star moving from `%l1` to `%spawn` has no effect on sponsorship status of any
221+of its sponsored planets. Moving to `%spawn` from `%l1` is currently
222+irreversible - the only further change to dominion permitted is moving to `%l2`.
226+*Permitted layer 2 actions:* owner: `%transfer-point`, `%spawn`, `%configure-keys`, `%escape`,
227+`%cancel-escape`, `%adopt`, `%reject`, `%detach`, `%set-management-proxy`,
228+`%set-spawn-proxy`,`%set-transfer-proxy`. management proxy: `%escape`,
229+`%cancel-escape`, `%adopt`, `%reject`, `%detach`, `%configure-keys`,
230+`%set-management-proxy`. spawn proxy: `%spawn`, `%set-spawn-proxy`. transfer
231+proxy: `%transfer-point`, `%set-transfer-proxy`.
233+A star in dominion `%l2` is said to exist on layer 2. A star may exist on layer
234+2 by being deposited to the layer 2 deposit address from layer 1, or by being
235+spawned by a `%spawn` dominion galaxy.
237+A star in dominion `%l2` cannot perform any layer 1 actions.
158### Galaxies
239### Galaxies
160−Note: actually maybe galaxies can put their spawn proxy on layer 2?
241+*Permitted dominions:* `%l1`, `%spawn`.
245+*Permitted layer 2 actions:* owner: `%adopt`, `%reject`, `%detach`. management
246+proxy: `%adopt`, `%reject`, `%detach`. spawn proxy: none. transfer proxy: none.
162−Galaxies may not have ownership, managment, spawn, or voting proxy on layer 2.
249+A galaxy in dominion `%l1` is said to exist on layer 1, which is the default state
163−They must remain entirely on layer 1. However, they are still eligible to
250+for all galaxies prior to the introduction of naive rollups. In addition to the
164−perform layer 2 sponsorship actions - see the following section.
251+ordinary Azimuth actions a galaxy can perform, they may also perform any
252+sponsorship-related actions on layer 2. `%l1` galaxies can perform all the usual
253+layer 1 Azimuth actions, and may also perform layer 2 sponsorship actions.
255+A `%l1` dominion galaxy may move to dominion `%spawn` by depositing its spawn proxy to the
256+layer 2 deposit address. This action is irreversible. Note, however that the
257+majority of galaxies already have all of their stars spawned in the [Linear
259+Contract](https://etherscan.io/address/0x86cd9cd0992f04231751e3761de45cecea5d1801).
260+Layer 2 has no interactions with this contract - all stars released in this
261+manner are `%l1` dominion stars. Moving to the `%spawn` dominion has no effect
262+on sponsorship status.
264+#### `%spawn` galaxies
266+*Permitted layer 2 actions:* owner: `%adopt`, `%reject`, `%detach`, `%spawn`,
267+`%set-spawn-proxy`. management proxy: `%adopt`, `%reject`, `%detach`. spawn
268+proxy: `%spawn`, `%set-spawn-proxy`. transfer proxy: none. voting proxy: none.
270+Galaxies may either remain on layer 1, or, similar to stars, they may
271+deposit their spawn proxy to layer 2. They cannot move their ownership,
272+management proxy, or voting proxy to layer 2. However, as with stars,
273+sponsorship actions may be performed on layer 2 using the ownership or
274+management proxies regardless of the dominion status of the galaxy.
166### Sponsorship
276### Sponsorship
168Due to the possibility of sponsors and sponsees existing on different layers,
278Due to the possibility of sponsors and sponsees existing on different layers,
169−the exact logic on how sponsorship works is complex. The short summary is that
279+the precise logic of how sponsorship works is complex. However, under common
280+circumstances it is simple.
170−if either the sponsor or sponsee are on layer 2, then sponsorship actions must occur on
282+If either the sponsor or sponsee are on layer 2, then sponsorship actions must
283+occur on layer 2. The only exception to this is detaching. A sponsor on layer 1
284+may perform a layer 1 detach action on a layer 2 sponsee, and this will result
285+in the sponsee having no sponsor on layer 1, and layer 2 as well if they were
286+the sponsor on layer 2. This is necessary for logical reasons, but it also
287+guarantees that there is no hard requirement to ever utilize layer 2. Without
288+this exception, sponsors with sponsees that move to layer 2 would be forced to
289+detach them as a layer 2 action if they wanted to cease sponsorship.
171−layer 2. If both sponsor and sponsee are on layer 1, then sponsorship actions
291+If both sponsor and sponsee are on layer 1 then sponsorship actions may occur on
292+either layer. As long as all sponsorship actions betweeen the two parties occur
293+on a single layer, behavior will be as expected.
172−may occur on either layer. For most scenarios, this is sufficient. However there are
295+In most cases this is sufficient to understand how sponsorship works. However
173−a number of edge cases that make this more complicated.
296+there are a number of edge cases that make this more complicated that developers
174−
297+may need to concern themselves with in scenarios where layer 1 sponsor and
175−For instance, what happens if a layer 1 planet has an oustanding escape that has
298+sponsees are mixing layer 1 and layer 2 actions. In the [Sponsorship state
176−not yet been accepted, and then transfers to layer 2. Is the escape still valid?
299+transitions](#sponsorship-state-transitions) section below, we give a table that
177−All potential scenarios are outline as follows. The typical user need not
300+shows how the sponsor and escape status of a ship changes according to which
178−concern themselves with these complications - this is primarily for developers.
301+actions are taken.
180## Azimuth state
303## Azimuth state
305+The introduction of layer 2 presents additional complication in understanding
306+Azimuth state. In order to be precise we define the following terminology:
308+ - _Layer 1 Azimuth state_ refers to the state of Azimuth as reflected on the
309+ Ethereum blockchain. This excludes all layer 2 transactions. Depositing to
310+ layer 2 is considered a layer 1 action, so the layer 1 Azimuth state is aware
311+ of which ships are on layer 2, but is blind to everything that happens to
313+ - _Layer 2 Azimuth state_ refers to the state of Azimuth as stored in
314+ `/app/azimuth.hoon` on your ship. The state here takes into account
315+ transactions that occur on both layers. No distinction between the
316+ layers is made in the state here - e.g. a ship only has one sponsor in Layer 2
317+ Azimuth state, not a layer 1 sponsor and a layer 2 sponsor. This is the state
318+ actually in use by Urbit. Layer 1 Azimuth state is now only an input for
319+ generating Layer 2 Azimuth state, so any time a ship needs to check e.g. the
320+ public key of a ship (regardless of which layer it is on), it will check the
321+ Layer 2 Azimuth state, not the Layer 1 Azimuth state.
322+ - _Layer-2-Only Azimuth state_ refers to the state of Azimuth as reflected
323+ solely by layer 2 transactions. This state is not explicitly stored anywhere,
324+ but is computed as part of the process to create the Layer 2 Azimuth state.
325+ We do not make any further references to this state, but it is important to
326+ keep in mind conceptually.
328+Layer 1 Azimuth state is computed by the Ethereum Virtual Machine. Layer 2
329+Azimuth state is computed by taking in the Layer 1 Azimuth state and modifying
330+it according to layer 2 transactions using `/lib/naive.hoon`. When we are being
331+precise about which state we are referring to we will utilize capitalization as above.
333+Layer 2 Azimuth state is held by the Azimuth Gall app located at
334+`/lib/azimuth.hoon`. Layer 1 and layer 2 state are not held separately - your
335+ship holds only one canonical Azimuth state, generated by parsing both layer 1
336+and layer 2 Ethereum transactions using `/lib/naive.hoon`. It is important to
337+keep in mind that Layer 1 Azimuth state is entirely unaware of Layer 2 Azimuth
338+state. Thus, for instance, the Azimuth PKI on Ethereum (Layer 1 Azimuth state)
339+may claim that the sponsor of `~sampel-palnet` is `~marzod`, while the Azimuth
340+state held on your ship (Layer 2 Azimuth state) claims that the sponsor of
341+`~sampel-palnet` is `~dopzod`. Under this circumstance, this would mean that the
342+sponsor of `~sampel-palnet` was `~marzod` before `~sampel-palnet` was deposited
343+to layer 2, and thus the Azimuth PKI on Ethereum will forever reflect this.
345+### Sponsorship state transitions
347+When either a sponsor or sponsee is on layer 2, then all sponsorship actions
348+occur on layer 2 and layer 1 Azimuth state is ignored. The exception to this, as
349+noted [above](#sponsorship), is when a layer 1 sponsor performs a layer 1 detach
350+action on a layer 2 sponsee. Furthermore, any time a ship moves from layer 1 to
351+layer 2, its sponsorship status is automatically maintained in layer 2.
353+The only potentially complicated scenario is when both sponsee and (potential)
354+sponsor exist on layer 1. Then because layer 1 actions can modify layer 2 state,
355+careful consideration is required for interactions that mix the two. If you
356+and your sponsor/sponsee are not mixing layer 1 and layer 2 sponsorship actions
357+between yourselves, then you have nothing to worry about and may safely ignore this
360+But, for instance, if both `~sampel-palnet` and `~dopzod` are on layer 1, it is
361+technically possible for `~sampel-palnet` to escape to `~dopzod` on layer 1, and
362+then `~dopzod` can accept the escape on layer 2. This will result in `~dopzod`
363+appearing as the sponsor in the Layer 2 Azimuth state (and thus be
364+`~sampel-palnet`'s "true" sponsor), and the sponsor in the Layer 1 Azimuth state
365+will remain unchanged. While it is difficult to imagine a good reason to do
366+this, developers working with layer 2 need to keep in mind these edge cases and
369+In the following table, columns `E_1` and `S_1` represent the escape status and
370+sponsor of a given ship as reflected by the Layer 1 Azimuth state. Columns `E_2`
371+and `S_2` represent the escape status and sponsor of a given ship as reflected
372+in the Layer 2 Azimuth State. The "true" escape status and sponsor of a ship is
373+always what is listed in the Layer 2 Azimuth state. In other words, at the end
374+of the day, `S_2` is always the sponsor that matters, but layer 1 actions can
375+affect the values of `E_2` and `S_2`.
377+A tar `*` entry represents any value and if an event shows a transition
378+from `*` to `*` that means that value is not altered by the transition. The
379+transitions marked with `!!` are prohibited by the layer 1 Azimuth smart
380+contract and thus never occur. `A1` and `A2` represent two distinct ships.
382+Event | E_1 | E_2 | S_1 | S_2 | -> | E_1 | E_2 | S_1 | S_2
383+L1-escape A1 | * | * | * | * | -> | A1 | A1 | * | *
384+L1-cancel A1 | ~ | * | * | * | -> !! :: no cancel if not escaping
385+L1-cancel A1 | A1 | * | * | * | -> | ~ | ~ | * | *
386+L1-adopt A1 | A1 | * | * | * | -> | ~ | ~ | A1 | A2
387+L1-adopt A1 | ~ | * | * | * | -> !! :: no adopt if not escaping
388+L1-adopt A1 | A2 | * | * | * | -> !! :: no adopt if not escaping
389+L1-detach A1 | * | * | A1 | A1 | -> | * | * | ~ | ~
390+L1-detach A1 | * | * | A1 | A2 | -> | * | * | ~ | A2
391+L1-detach A1 | * | * | A1 | ~ | -> | * | * | ~ | ~
392+L2-escape A1 | * | * | * | * | -> | * | A1 | * | *
393+L2-cancel A1 | * | * | * | * | -> | * | ~ | * | *
394+L2-adopt A1 | * | A1 | * | * | -> | * | ~ | * | A1
395+L2-adopt A1 | * | A2 | * | * | -> | * | A2 | * | *
396+L2-adopt A1 | * | ~ | * | * | -> | * | ~ | * | *
397+L2-reject A1 | * | A1 | * | * | -> | * | ~ | * | *
398+L2-reject A1 | * | A2 | * | * | -> | * | A2 | * | *
399+L2-reject A1 | * | ~ | * | * | -> | * | ~ | * | *
400+L2-detach A1 | * | * | * | A1 | -> | * | * | * | ~
401+L2-detach A1 | * | * | * | A2 | -> | * | * | * | A2
402+L2-detach A1 | * | * | * | ~ | -> | * | * | * | ~
182## Processing L1 transactions
405## Processing L1 transactions
184## Processing L2 batches
407## Processing L2 batches
186## Aggregators
409## Aggregators
411+An "aggregator" or "roller" is any Urbit node that collects signed layer 2
412+transactions (typically via `/app/azimuth-rpc.hoon`), combines them into a
413+"batch", and then submits the batch as an Ethereum transaction. Any urbit can be
414+a roller, including moons, comets, and even fakezods. You can also use your own
417+Tlon has set up our own roller that is free to use by the community. Using
418+Bridge, a ship may submit X transactions to Tlon's roller per Y period free of
419+charge. Tlon's roller submits on a regular schedule: a submission occurs when a
420+total of A layer 2 transactions have been submitted to it since the the previous
421+submitted Ethereum transaction, or every Z time, whichever occurs first. (this
422+should probably go in the operations manual)
424+There are no security risks in utilizing an aggregator. The transactions you
425+submit to it are signed with your private key, and so if an aggregator alters
426+them the signature will no longer match and `naive.hoon` will reject it as an
427+invalid transaction. The worst an aggregator can do is not submit your transaction.
431+Maybe this section goes in operating manual?
433+As part of the layer 2 upgrade, Tlon has expanded the role of
434+[keyfiles](/docs/glossary/keyfile). One of our goals with layer 2 was to reduce
435+the amount of friction experienced when getting onto Urbit. The enormous
436+reduction in fees has made a new boot method which allows instantaneous sale of
437+layer 2 planets or stars to be cost effective.
439+The ideal situation would be for the end user to be able to buy or receive a
440+planet and immediately boot it without having to wait for an aggregator to
441+submit a transaction that spawns the planet. In order to bring about this
442+circumstance, "multi-keyfiles" have been introduced.
444+Multi-keyfiles are keyfiles used to boot an urbit for first time that contains
445+more than one set of keys, the purpose of which is to initially utilize one set
446+of keys on a temporary basis, and then the other set of keys soon after. This
447+works as follows. A star owner prespawns a number of layer 2 planets ready to be
448+sold at any time for which they posess the initial key. When a user acquires a
449+planet from a star owner, the star owner immediately hands the initial keys to
450+boot the planet to the buyer. The buyer then queues a transaction at a roller to
451+rotate the keys to a new value only known by the buyer (this step is performed
452+automatically by Bridge). The buyer then downloads a keyfile from Bridge
453+containing both keys and uses that to boot their planet for the first time.
454+After the transaction setting the new keys is submitted by the roller to
455+Ethereum, the purchased planet will automatically switch to them once it reads
456+the corresponding transaction from Ethereum.
458+This process introduces a short period of time in which both the buyer and
459+seller are in possession of the keys of a planet. A malicious seller could
460+theoretically sell a planet to more than one party in this time period. However,
461+they would quickly be found out as two identical ships on the network
462+immediately creates problems, and the seller's reputation would be tarnished.
463+Due to the expense or effort needed to acquire a star, this seems an unlikely
464+scenario as the reward is much less than the cost. Nonetheless, buyers should
465+always make an effort to purchase from a reputable star, as is the case with all
466+transactions in life.
468+Multi-keyfiles were possible before layer 2, but as the cost of configuring keys
469+was comparable to the cost of buying a planet, they were not practical.
188## Security measures
471## Security measures
473+In the process of designing naive rollups, we felt it to be of the utmost
474+importance that there not be any loss in the security of a layer 2 ship over a
475+layer 1 ship. In this section we outline several relevant facets of Urbit as
476+well as particular measures that were taken to ensure that naive rollups were
477+free of bugs and exploits. We think of `naive.hoon` as being the first "Hoon
478+smart contract", and thus its functionality needs to be as rock-solid and
479+guaranteed as the Azimuth Ethereum smart contracts.
481+### Arvo is deterministic
483+Crucial to the functionality of Ethereum smart contracts is they work the same
484+way every time since the Ethereum Virtual Machine is determinsistic. Similarly,
485+as the state of Arvo is evolved via [a single pure function](/docs/arvo/overview#an-operating-function), Urbit is
486+deterministic as well. This property makes it well-suited for cases where side
487+effects are unacceptable such as smart contracts, and thus `naive.hoon` is
488+worthy of the name "Hoon smart contract".
490+### Restricted standard library
492+A standard security practice is to reduce the surface area of attack to be as
493+minimal as possible. One common source of exploits among all programming
494+languages are issues with the standard library of functions, and this often
495+leads to there being multiple implementations of standard library functions for
496+a given programming language. For instance, `glibc` is the most widely used
497+standard library for the C programming language, but sheer size gives a large
498+surface area in which to find exploits. Thus, other standard libraries have been
499+written such as `musl` that are much smaller, and some argue to be more secure
500+at least partially due to fewer lines of code. Hoon is not yet popular to have
501+multiple standard library implementations, but `naive.hoon` shucks the usual
502+standard library and so its subjects contains only the exact standard library
503+functions needed for it to function (`/lib/std.hoon`).
507+`naive.hoon` is among the most well-tested software in Urbit. The test suite,
508+which may be run with `-test %/lib/tests/naive ~` from dojo, is larger than any
509+other test suite both in number of lines of code and number of tests. We believe
510+branch coverage to be at or very close to 100%
514+In the Layer 2 Azimuth state, each proxy belonging to a given ship (including
515+the ownership "proxy") has a non-negative integer associated to it called a
516+"nonce". Each transaction submitted by a given proxy also have a nonce value. If
517+the current nonce of a proxy in the Layer 2 Azimuth state is `n`, then only a
518+transaction from that proxy with a nonce of `n+1` will be considered valid.
519+Otherwise the transaction is discarded. A valid transaction, by which we
520+mean one in which the nonce and signature are correct, will increment the nonce
521+of the proxy in the Layer 2 Azimuth state by one once processed by `naive.hoon`.
522+Note that "valid transactions" also include ones where the action will fail,
523+such as a planet attempting to `%spawn` another planet. For the purposes of
524+incrementing the nonce, only the nonce and signature matter.
526+The use of nonces prevents "replay attacks", which is when a malicious party collects
527+valid transactions and attempts to resubmit them in order to perform the action
528+again. Since a valid transaction increments the nonce associated to the proxy
529+that submitted it, it is only ever possible for a given transaction to alter the
530+Layer 2 Azimuth state once.
532+The use of nonces also eliminates potential issues caused by submitting a
533+transaction to more than one roller. This might happen if the first roller
534+submitted to is taking too long for your liking, and you want to try again with
535+another. If both rollers end up submitting the transaction, only the first one
536+will succeed, as the second one will be ignored by `naive.hoon` for having the