@@ -0,0 +1,182 @@
1++++
2+title = "Layer 2 Overview"
3+weight = 5
4+template = "doc.html"
5++++
6+
7+This document provides technical detail on Azimuth's "Layer 2" scaling solution
8+for Azimuth, known more formally as "naive rollups". We focus here primarily on the
9+"Hoon smart contract" located at `/lib/naive.hoon` in your ship's pier, as well
10+as other proximal topis.
11+
12+This is intended for developers that desire a deeper understanding of how this
13+protocol works, how secure it is, and how to extract data from layer 2 to obtain
14+a complete picture of the Arvo network.
15+
16+This is not intended for everyday users who only wish to know how
17+to either transfer their ship to layer 2 or perform layer 2 actions. For that,
18+see ((bridge documentation yet to be written)). For a casual overview of the
19+rationale and functionality of layer 2, please see this [blog
20+post](/blog/rollups).
21+
22+This page is also not where to find instruction on how to run your own "aggregator"/"roller".
23+Documentation for this process is forthcoming. However, this page does contain
24+essential background information for anybody in this category.
25+
26+## Summary
27+
28+Naive rollups were developed in response to rising gas costs for performing
29+Azimuth actions.
30+
31+### Layer 1
32+
33+We first review how "Layer 1", i.e. the [Azimuth](/docs/glossary/azimuth) smart
34+contract suite, functions. This happens with four steps.
35+
36+ 1. A transaction is posted to the Ethereum blockchain.
37+ 2. The [Ethereum Virtual MAchine](https://ethereum.org/en/developers/docs/evm/)
38+ calculates the resulting state transition and checks its validity, then
39+ updates the state if it is a valid transition.
40+ 3. Your urbit downloads the new state from an Ethereum node.
41+ 4. Your urbit makes the final decision on whether the new state is valid.
42+
43+In practice, this step four never occurred but has always been possible in
44+theory. By default, your urbit accepts the Azimuth state obtained from the
45+blockchain as valid.
46+
47+### Layer 2
48+
49+Layer 1 still works identically today as it did before naive rollups. Naive
50+rollups work via the following process.
51+
52+ 1. A batch of one or more transactions is posted to the Ethereum blockchain by
53+ an urbit node called a roller or aggregator.
54+ 2. Your urbit downloads the transactions from an Ethereum node.
55+ 3. Your urbit computes the resulting state transitions from the transactions
56+ and checks them for validity.
57+ 4. Your urbit updates your locally stored Azimuth state with state transitions
58+ from the batch that have been deemed valid.
59+
60+ In comparison with Layer 1, the EVM no longer checks the validity or computes
61+ the state transitions for any given transaction. It is now being used solely as
62+ a database of submitted transactions, and the business logic of computing what
63+ these transactions mean has been offloaded to your urbit. Thus we think of
64+ `naive.hoon` as being the first "Hoon smart contract". You could also consider
65+steps 3 and 4 of the Layer 2 process as being a fattening of the trivial step 4
66+ of the layer 1 process.
67+
68+Here we briefly elaborate on the layer 2 steps, but see below for more technical
69+detail.
70+
71+A roller is any urbit node - even a moon, comet, or fakezod will do - to which
72+batches of transactions are submitted. You could use your own ship as a roller
73+if you wanted. The roller collects batches of transactions from whichever
74+parties they choose, and submits them to the Ethereum blockchain all at once.
75+We expect this to either happen on a regular interval, or once some minimum
76+threshold of transactions is reached, but the decision on when to submit is
77+ultimately up to the roller.
78+
79+Computing the resulting state transitions obtained from downloaded Ethereum
80+transactions is done using `naive.hoon`, which is a gate that accepts both layer
81+1 transactions and layer 2 batches, and then computes the resulting state
82+transitions and updates the ship's internal Azimuth data accordingly.
83+
84+### Savings in gas costs
85+
86+There are several dimensions by which naive rollups saves on gas over layer 1.
87+They are:
88+
89+ 1. Gas is not spent on instructing the EVM to compute state transitions and
90+ confirm validity.
91+ 2. Layer 2 Azimuth state is not stored on Ethereum, so the only data storage
92+ gas costs is for the transactions themselves.
93+ 3. Layer 2 transactions are written in a highly compressed form. E.g., instead
94+ of calling the spawn action by name, it is simply referred to as action `1`.
95+ 4. By collecting multiple layer 2 transactions and submitting them as a single
96+ "batch transaction", additional gas savings are achieved by not needing to
97+ duplicate information such as which smart contract the transactions are
98+ intended for.
99+
100+Put together, these create a reduction in gas costs of at least 65x.
101+
102+### One way trip
103+
104+## Interacting with L2
105+
106+Layer 2 affects all Azimuth points on the network, even if they are on layer 1. Here we
107+outline what the changes are to each class. How sponsorship works on layer 2 is
108+more complex, and has its own [section](#sponsorship).
109+
110+### Planets
111+
112+A layer 1 planet can move to layer 2 by transferring ownership of the planet to
113+the layer 2 deposit address. The owner will still utilize the same private keys
114+they used before this transfer to perform actions. This includes both the
115+ownership address as well as the management proxy, if it has one. It is not
116+possible to transfer only the management proxy to layer 2; it may only happen as
117+a side-effect of transferring ownership to layer 2.
118+
119+Once on layer 2, the planet may perform all Azimuth actions utilizing their
120+ownership key. This includes transferring ownership to a new address and setting
121+a management proxy. Their management proxy may be utilized to perform all
122+actions allowed by the management proxy - changing keys, breaching, and changing
123+sponsors.
124+
125+### Stars
126+
127+Naive rollups permit three possible states for stars. They may exist entirely on
128+layer 1, they may have their ownership and management proxy on layer 1 with
129+their spawn proxy on layer 2, or they may exist entirely on layer 2.
130+
131+#### Layer 2 spawn proxy
132+
133+A star may change its spawn proxy to layer 2. This allows the star to spawn
134+planets directly on layer 2 with the accompanying gas cost savings. A star with
135+its spawn proxy on layer 2 will no longer be able to spawn layer 1 planets, but
136+any layer 1 planets sponsored by the star will remain so. This action is
137+currently irreversible - the only further change to layer 2 status that is
138+possible would be to transfer ownership to layer 2 as well. All actions besides
139+spawning and sponsorship (see [below](#sponsorship)) must be performed on layer 1.
140+
141+#### Layer 2 ownership
142+
143+A star entirely on layer 1, or a star on layer 1 with a layer 2 spawn proxy, may
144+transfer ownership to layer 2 by transferring ownership to the layer 2 deposit
145+address. This will allow the star to perform all Azimuth actions as layer 2
146+actions with the associated gas cost savings.
147+
148+Transferring ownership to layer 2 automatically moves the spawn proxy to layer 2
149+(if it is not already there), as well as the management proxy. Thus the star
150+owner may then perform management proxy tasks on layer 2. Layer 1 actions are no
151+longer accessible to a star whose ownership exists on layer 2.
152+
153+### Galaxies
154+
155+Galaxies may not have ownership, managment, spawn, or voting proxy on layer 2.
156+They must remain entirely on layer 1. However, they are still eligible to
157+perform layer 2 sponsorship actions - see the following section.
158+
159+### Sponsorship
160+
161+Due to the possibility of sponsors and sponsees existing on different layers,
162+the exact logic on how sponsorship works is complex. The short summary is that
163+if either the sponsor or sponsee are on layer 2, then sponsorship actions must occur on
164+layer 2. If both sponsor and sponsee are on layer 1, then sponsorship actions
165+may occur on either layer. For most scenarios, this is sufficient. However there are
166+a number of edge cases that make this more complicated.
167+
168+For instance, what happens if a layer 1 planet has an oustanding escape that has
169+not yet been accepted, and then transfers to layer 2. Is the escape still valid?
170+All potential scenarios are outline as follows. The typical user need not
171+concern themselves with these complications - this is primarily for developers.
172+
173+## Azimuth state
174+
175+## Processing L1 transactions
176+
177+## Processing L2 batches
178+
179+## Aggregators
180+
181+## Security measures
182+