@@ -4,8 +4,6 @@ weight = 5
44template = "doc.html"
55+++
66
7−PR: https://github.com/urbit/azimuth/pull/43
8−
97This document provides technical detail on Azimuth's "Layer 2" scaling solution
108for Azimuth, known more formally as "naive rollups". We focus here primarily on the
119"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.
2826## Summary
2927
3028Naive 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.
32+
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.
3235
3336### Layer 1
3437
35−We first review how "Layer 1", i.e. the [Azimuth](/docs/glossary/azimuth) smart
36−contract suite, functions. This happens with four steps.
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
40+occurs with four steps:
3741
3842 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/)
4044 calculates the resulting state transition and checks its validity, then
4145 updates the state if it is a valid transition.
4246 3. Your urbit downloads the new state from an Ethereum node.
4347 4. Your urbit makes the final decision on whether the new state is valid.
4448
45−In practice, this step four never occurred but has always been possible in
46−theory. By default, your urbit accepts the Azimuth state obtained from the
47−blockchain as valid.
49+By default, step four always succeeds. It has always been possible in theory for
50+your urbit to dispute what it read on Ethereum, but there has never been any
51+reason to do so.
4852
4953### Layer 2
5054
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
5256rollups work via the following process.
5357
5458 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.
5660 2. Your urbit downloads the transactions from an Ethereum node.
5761 3. Your urbit computes the resulting state transitions from the transactions
5862 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
6064 from the batch that have been deemed valid.
6165
6266 In comparison with Layer 1, the EVM no longer checks the validity or computes
@@ -73,15 +77,16 @@ detail.
7377A roller is any urbit node - even a moon, comet, or fakezod will do - to which
7478batches of transactions are submitted. You could use your own ship as a roller
7579if 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.
7781We expect this to either happen on a regular interval, or once some minimum
7882threshold of transactions is reached, but the decision on when to submit is
7983ultimately up to the roller.
8084
8185Computing the resulting state transitions obtained from downloaded Ethereum
82−transactions is done using `naive.hoon`, which is a gate that accepts both layer
83−1 transactions and layer 2 batches, and then computes the resulting state
84−transitions and updates the ship's internal Azimuth data accordingly.
86+transactions is done using `/lib/naive.hoon`, which is a gate that accepts both layer
87+1 transaction logs and layer 2 batches, and then computes the resulting state
88+transitions and updates the ship's internal Azimuth data held in
89+the Gall agent `/app/azimuth.hoon` accordingly.
8590
8691### Savings in gas costs
8792
@@ -93,97 +98,441 @@ They are:
9398 2. Layer 2 Azimuth state is not stored on Ethereum, so the only data storage
9499 gas costs is for the transactions themselves.
95100 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`.
97102 4. By collecting multiple layer 2 transactions and submitting them as a single
98103 "batch transaction", additional gas savings are achieved by not needing to
99104 duplicate information such as which smart contract the transactions are
100105 intended for.
101106
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.
103110
104111### One way trip
105112
106−NOTE: Depositing to L2 clears proxies to get a gas cost discount. It also zeroes
107−out escapes, keys, and claims? I'm guessing these all still remain on L2 though.
113+Moving to layer 2 is a one-way trip for now. This means that once a ship moves
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.
108117
109118## Interacting with L2
110119
111120Layer 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
113122more complex, and has its own [section](#sponsorship).
114123
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`.
128+
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.
135+
136+### Moving a pre-existing ship to L2
137+
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.
143+
144+### Dominion
145+
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.
151+
115152### Planets
116153
117−A layer 1 planet can move to layer 2 by transferring ownership of the planet to
118−the layer 2 deposit address. The owner will still utilize the same private keys
119−they used before this transfer to perform actions. This includes both the
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.
154+*Permitted dominions:* `%l1`, `%l2`.
155+
156+#### `%l1` planets
123157
124−Once on layer 2, the planet may perform all Azimuth actions utilizing their
125−ownership key. This includes transferring ownership to a new address and setting
126−a management proxy. Their management proxy may be utilized to perform all
127−actions allowed by the management proxy - changing keys, breaching, and changing
128−sponsors.
158+*Permitted layer 2 actions:* owner: `%escape`, `%cancel-escape`. management
159+proxy: `%escape`, `%cancel-escape`. transfer proxy: none.
160+
161+A planet in dominion `%l1` is said to exist on layer 1, which is the default
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
167+sponsorship actions.
168+
169+Layer 1 planets may also move to dominion `%l2` by depositing their ownership to
170+the layer 2 deposit address.
171+
172+#### `%l2` planets
173+
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`.
178+
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.
183+
184+A layer 2 planet is no longer capable of performing any layer 1 actions, and
185+cannot move to layer 1.
129186
130187### Stars
131188
132−Naive rollups permit three possible states for stars. They may exist entirely on
133−layer 1, they may have their ownership and management proxy on layer 1 with
134−their spawn proxy on layer 2, or they may exist entirely on layer 2.
189+*Permitted dominions:* `%l1`, `%spawn`, `%l2`.
190+
191+#### `%l1` stars
192+
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.
135196
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.
137201
138−A star may change its spawn proxy to layer 2. This allows the star to spawn
139−planets directly on layer 2 with the accompanying gas cost savings. A star with
140−its spawn proxy on layer 2 will no longer be able to spawn layer 1 planets, but
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.
202+A `%l1` dominion star may move to dominion `%spawn` by depositing its spawn proxy to the
203+layer 2 deposit address, or may move to dominion `%l2` by depositing its ownership
204+to the layer 2 deposit address. Both actions are irreversible.
145205
146−#### Layer 2 ownership
206+#### `%spawn` stars
147207
148−A star entirely on layer 1, or a star on layer 1 with a layer 2 spawn proxy, may
149−transfer ownership to layer 2 by transferring ownership to the layer 2 deposit
150−address. This will allow the star to perform all Azimuth actions as layer 2
151−actions with the associated gas cost savings.
208+*Permitted layer 2 actions:* owner: `%escape`, `%cancel-escape`, `%adopt`,
209+`%reject`, `%detach`, `%spawn`, `%set-spawn-proxy`. management proxy: `%escape`,
210+`%cancel-escape`, `%adopt`, `%reject`, `%detach`. spawn proxy: `%spawn`,
211+`%set-spawn-proxy`. transfer proxy: none.
152212
153−Transferring ownership to layer 2 automatically moves the spawn proxy to layer 2
154−(if it is not already there), as well as the management proxy. Thus the star
155−owner may then perform management proxy tasks on layer 2. Layer 1 actions are no
156−longer accessible to a star whose ownership exists on layer 2.
213+A star in dominion `%spawn` is said to exist on layer 1.
214+
215+A star in dominion `%spawn` may spawn planets directly on layer 2, but will no
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
218+by the star.
219+
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`.
223+
224+#### `%l2` stars
225+
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`.
232+
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.
236+
237+A star in dominion `%l2` cannot perform any layer 1 actions.
157238
158239### Galaxies
159240
160−Note: actually maybe galaxies can put their spawn proxy on layer 2?
241+*Permitted dominions:* `%l1`, `%spawn`.
242+
243+#### `%l1` galaxies
244+
245+*Permitted layer 2 actions:* owner: `%adopt`, `%reject`, `%detach`. management
246+proxy: `%adopt`, `%reject`, `%detach`. spawn proxy: none. transfer proxy: none.
247+voting proxy: none.
161248
162−Galaxies may not have ownership, managment, spawn, or voting proxy on layer 2.
163−They must remain entirely on layer 1. However, they are still eligible to
164−perform layer 2 sponsorship actions - see the following section.
249+A galaxy in dominion `%l1` is said to exist on layer 1, which is the default state
250+for all galaxies prior to the introduction of naive rollups. In addition to the
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.
254+
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
258+Star Release
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.
263+
264+#### `%spawn` galaxies
265+
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.
269+
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.
165275
166276### Sponsorship
167277
168278Due 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
170−if either the sponsor or sponsee are on layer 2, then sponsorship actions must occur on
171−layer 2. If both sponsor and sponsee are on layer 1, then sponsorship actions
172−may occur on either layer. For most scenarios, this is sufficient. However there are
173−a number of edge cases that make this more complicated.
174−
175−For instance, what happens if a layer 1 planet has an oustanding escape that has
176−not yet been accepted, and then transfers to layer 2. Is the escape still valid?
177−All potential scenarios are outline as follows. The typical user need not
178−concern themselves with these complications - this is primarily for developers.
279+the precise logic of how sponsorship works is complex. However, under common
280+circumstances it is simple.
281+
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.
290+
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.
294+
295+In most cases this is sufficient to understand how sponsorship works. However
296+there are a number of edge cases that make this more complicated that developers
297+may need to concern themselves with in scenarios where layer 1 sponsor and
298+sponsees are mixing layer 1 and layer 2 actions. In the [Sponsorship state
299+transitions](#sponsorship-state-transitions) section below, we give a table that
300+shows how the sponsor and escape status of a ship changes according to which
301+actions are taken.
179302
180303## Azimuth state
181304
305+The introduction of layer 2 presents additional complication in understanding
306+Azimuth state. In order to be precise we define the following terminology:
307+
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
312+ them afterward.
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.
327+
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.
332+
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.
344+
345+### Sponsorship state transitions
346+
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.
352+
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
358+section.
359+
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
367+ought to read on.
368+
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`.
376+
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.
381+```
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 | * | * | * | ~ | -> | * | * | * | ~
403+```
404+
182405## Processing L1 transactions
183406
184407## Processing L2 batches
185408
186409## Aggregators
187410
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
415+ship as a roller.
416+
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)
423+
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.
428+
429+## Multi-keyfiles
430+
431+Maybe this section goes in operating manual?
432+
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.
438+
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.
443+
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.
457+
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.
467+
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.
470+
188471## Security measures
189472
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.
480+
481+### Arvo is deterministic
482+
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".
489+
490+### Restricted standard library
491+
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`).
504+
505+### Unit tests
506+
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%
511+
512+### Nonces
513+
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.
525+
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.
531+
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
537+wrong nonce.
538+