git.iko.soy/urbit.org
on master help sign in
more layer 2 docs
11210c1drbeefsupreme
content/docs/azimuth/_index.md+33−3
compare with master
unifiedsplit
@@ -7,16 +7,46 @@ insert_anchor_links = "right"
7+++
7+++
8
8
9
9
10−## [Azimuth](/docs/azimuth/azimuth)
10+### [Azimuth](/docs/azimuth/azimuth)
11
11
12An overview of the Ethereum-based public key infrastructure utilized by Urbit.
12An overview of the Ethereum-based public key infrastructure utilized by Urbit.
13
13
14−## [Life and Rift](/docs/azimuth/azimuth)
14+### [Life and Rift](/docs/azimuth/azimuth)
15
15
16An explanation of how Azimuth keeps track of the most recent set of networking
16An explanation of how Azimuth keeps track of the most recent set of networking
17keys necessary to communicate with a ship.
17keys necessary to communicate with a ship.
18
18
19−## [Advanced Azimuth Tools](/docs/azimuth/advanced-azimuth-tools)
19+### [Advanced Azimuth Tools](/docs/azimuth/advanced-azimuth-tools)
20
20
21Expert-level tooling for generating, signing, and sending Azimuth-related
21Expert-level tooling for generating, signing, and sending Azimuth-related
22transactions from within Urbit itself.
22transactions from within Urbit itself.
23+
24+## Layer 2
25+
26+Documentation of the technical details of naive rollups, our Layer 2 solution
27+for the reduction of Urbit ID gas prices and friction associated with the usage
28+of cryptocurrency.
29+
30+### [Layer 2 Overview](/docs/azimuth/layer-2)
31+
32+A high-level technical description of the functionality of the naive rollups
33+"Hoon smart contract" and associated apps, such as Bridge and the roller.
34+
35+### [Layer 2 Actions](/docs/azimuth/l2-actions)
36+
37+An exhaustive list of what Azimuth actions can be performed for any given tuple
38+`(ship rank, layer 2 status)`.
39+
40+### [Data Flow]
41+
42+Diagrams and explanations of how data flows between Bridge and the various
43+components inside Urbit involved with layer 2.
44+
45+### [Bytestrings](/docs/azimuth/bytestring)
46+
47+The bytestring format for layer 2 transactions and batches.
48+
49+### [Roller HTTP RPC API](/docs/azimuth/layer2-api)
50+
51+Documentation on the HTTP RPC API used for Urbit to communicate with Bridge to
52+manage layer 2 transactions.
content/docs/azimuth/bytestring.md+15−10
@@ -1,6 +1,6 @@
1+++
1+++
2title = "Bytestring Format"
2title = "Bytestring Format"
3−weight = 7
3+weight = 8
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
@@ -134,7 +134,7 @@ Each of these actions have the same argument - an Ethereum address:
1341 bit: padding
1341 bit: padding
135```
135```
136
136
137−### Unsigned transactions
137+### Unsigned transactions {#unsigned}
138
138
139An unsigned transaction is an atom consisting of the concatentation of an Ethereum signed
139An unsigned transaction is an atom consisting of the concatentation of an Ethereum signed
140message header, an Urbit ID header, a chain ID, a nonce, and an action. This has the following format:
140message header, an Urbit ID header, a chain ID, a nonce, and an action. This has the following format:
@@ -158,10 +158,13 @@ each cell (which are `octs`) in the arguments that follow is the number of block
158in this scenario) of each entry, with the tail being the actual data. The reason
158in this scenario) of each entry, with the tail being the actual data. The reason
159to use `octs` rather than just atoms is to account for padding.
159to use `octs` rather than just atoms is to account for padding.
160
160
161−`len` is the length in bytes of everything following it except the signature.
161+`len` is the length measured in bytes of everything following it except the
162−`chain-t` is the chain ID, which is to distinguish between e.g. the Ethereum
162+signature. `chain-t` is the chain ID, which is to distinguish between e.g. the
163−test net and main net, to ensure that transaction used in one cannot be
163+Ethereum test net and main net, to ensure that transaction used in one cannot be
164−rebroadcast on the other.
164+rebroadcast on the other (see
165+[EIP-155](https://eips.ethereum.org/EIPS/eip-155)). We note that `len` and
166+`chain-t` are both ASCII decimals (`@t` in Hoon), while `nonce` and `action` are
167+`@ud`s.
165
168
166Again we emphasize that unsigned transactions are _not_ what is submitted in a
169Again we emphasize that unsigned transactions are _not_ what is submitted in a
167batch - an action and a signature are. A ship submitting a layer 2 transaction
170batch - an action and a signature are. A ship submitting a layer 2 transaction
@@ -172,8 +175,10 @@ the additional data to the action and verifies the signature against that.
172
175
173### Signature
176### Signature
174
177
175−The signature is a 65-byte ECDSA signature. The precise format of the signature depends
178+The signature is a 65-byte ECDSA signature as described in
179+[EIP-191](https://eips.ethereum.org/EIPS/eip-191) and is compatible with
180+`personal_sign`. The precise format of the signature depends on which wallet was
176−on which wallet was used to sign it. Layer 2 supports all major signature
181+used to sign it. Layer 2 supports all major signature formats, including
177−formats, including Metamask, Trezor, Ledger, and others. Signatures in batches
182+Metamask, Trezor, Ledger, and others. Signatures in batches are obtained by signing
178−are got by signing an unsigned transaction.
183+an [unsigned transaction](#unsigned).
179
184
content/docs/azimuth/l2-actions.md+6−5
@@ -18,11 +18,12 @@ transferring ownership to layer 2.
18
18
19### Moving a pre-existing ship to L2
19### Moving a pre-existing ship to L2
20
20
21−In order to move your ship from layer 1 to layer 2, you use
21+In order to move your ship from layer 1 to layer 2, transfer ownership of your
22+ship to the address `0x1111111111111111111111111111111111111111`. The easiest
22−[Bridge](/docs/glossary/bridge) to transfer ownership of your ship to the
23+way to accomplish this is using [Bridge](/docs/glossary/bridge) (TODO link to L2
23−address `0x1111111111111111111111111111111111111111` TODO: Presumably this is
24+Bridge guide), but Urbit-native CLI tools to accomplish this are available as
24−surfaced in the UI in Bridge, and one doesn't need to know the address. Probably
25+well (link). The Azimuth smart contracts interpret any ship at this address as
25−this should just be a link to the Operator's Manual.
26+being on Layer 2.
26
27
27### Dominion
28### Dominion
28
29
content/docs/azimuth/l2-flow.mdnew file+202
@@ -0,0 +1,202 @@
1++++
2+title = "Azimuth Data Flow"
3+weight = 7
4+template = "doc.html"
5++++
6+
7+This document summarizes the various components involved with Azimuth and
8+how they communicate with each other. This also constitutes an explanation for
9+how Urbit implements the data flow of naive rollups.
10+
11+The following diagram illustrates the high-level structure of Azimuth as seen
12+from the perspective of Urbit.
13+
14+![High level overview](https://media.urbit.org/docs/layer2/l2-high.svg)
15+
16+## Bridge
17+
18+The primary way in which users interact with Layer 2 is via Bridge. Bridge is
19+responsible for collecting transactions from users, signing them, and forwarding
20+them to a roller via an HTTP API.
21+
22+## Azimuth
23+
24+Azimuth is a set of smart contracts that exists on Ethereum that defines the
25+state and logic of the PKI. With the advent of naive rollups, this has also come
26+to include the set of components used for dealing with the PKI within Urbit. The
27+following sections outline what each component is responsible for and how it
28+communicates with the others.
29+
30+![Azimuth overview](https://media.urbit.org/docs/layer2/l2-azimuth.svg)
31+
32+As seen in the above diagram, there are three Gall agents responsible for
33+managing the PKI state: `azimuth.hoon`, `aggregator.hoon`, and `aggregator-rpc.hoon`.
34+
35+### `azimuth.hoon`
36+
37+`/app/azimuth.hoon` is a Gall agent and thread handler responsible for keeping
38+track of the PKI state, and exposing that data via scries.
39+
40+The following diagram illustrates `azimuth.hoon`'s role in the system.
41+
42+![Azimuth components](https://media.urbit.org/docs/layer2/l2-azimuth-azimuth.svg)
43+
44+The state held in `azimuth.hoon` is the following.
45+
46+```hoon
47+++ app-state
48+ $: %3
49+ url=@ta
50+ whos=(set ship)
51+ nas=^state:naive
52+ own=owners
53+ logs=(list =event-log:rpc:ethereum)
54+ ==
55+```
56+
57+`whos` is the set of ships currently known by Azimuth. `nas` is the PKI state,
58+as defined in [`naive.hoon`](#naive). `own` is a `jug` of Ethereum addresses and
59+the set of ships owned by that address. `logs` is a list of all Azimuth-related
60+Ethereum event logs known by the ship.
61+
62+Scries can be inferred from the `+on-peek` arm:
63+
64+```hoon
65+++ on-peek
66+ |= =path
67+ ^- (unit (unit cage))
68+ ?+ path (on-peek:def path)
69+ [%x %logs ~] ``noun+!>(logs.state)
70+ [%x %nas ~] ``noun+!>(nas.state)
71+ [%x %dns ~] ``noun+!>(dns.nas.state)
72+ [%x %own ~] ``noun+!>(own.state)
73+ ==
74+```
75+
76+### `eth-watcher.hoon`
77+
78+`/app/eth-watcher.hoon` is responsible for listening to an Ethereum node and
79+collecting Azimuth related transactions. It sends collected transactions to
80+`+on-agent` in `azimuth.hoon`, which then obtains the resulting PKI transitions
81+from them using `naive.hoon`.
82+
83+### `naive.hoon` {#naive}
84+
85+`/lib/naive.hoon` is a gate whose sample is a `verifier`, `chain-id=@ud`,
86+`state`, and `input`, which outputs a cell of `[effects state]`. This is the
87+transition function which updates the state of the PKI stored in `azimuth.hoon`
88+which handles state transitions caused by both layer 1 and layer 2 transactions.
89+A high-level overview of how `naive.hoon` functions can be found
90+[here](/docs/azimuth/layer2#layer-2).
91+
92+A `verifier` is a gate of the form
93+
94+```hoon
95++$ verifier $-([dat=octs v=@ r=@ s=@] (unit address))
96+```
97+
98+It runs the keccak hash function on `dat` to verify that `dat` is data signed by
99+the ECDSA signature given by the `[v r s]` tuple, according to the format for
100+signed transactions outlined in the [bytestring
101+format](/docs/azimuth/bytestring) documentation.
102+
103+`chain-id` is the ID used by the Ethereum blockchain, which is `1337`. See [bytestring
104+format](/docs/azimuth/bytestring) for more information.
105+
106+`state` is the current state of the PKI:
107+
108+```hoon
109++$ state
110+ $: =points
111+ =operators
112+ dns=(list @t)
113+ ==
114++$ points (tree [ship point])
115+++ point
116+ $: :: domain
117+ ::
118+ =dominion
119+ ::
120+ :: ownership
121+ ::
122+ $= own
123+ $: owner=[=address =nonce]
124+ spawn-proxy=[=address =nonce]
125+ management-proxy=[=address =nonce]
126+ voting-proxy=[=address =nonce]
127+ transfer-proxy=[=address =nonce]
128+ ==
129+ ::
130+ :: networking
131+ ::
132+ $= net
133+ $: rift=@ud
134+ =keys
135+ sponsor=[has=? who=@p]
136+ escape=(unit @p)
137+ ==
138+ ==
139++$ dominion ?(%l1 %l2 %spawn)
140++$ operators (jug address address)
141+```
142+`points` should be self-explanatory if you are already familiar with the
143+structure of Urbit ID. The only new addition is `dominion`, which is a record of
144+whether a ship is on layer 1, layer 2, or layer 1 with a layer 2 spawn proxy.
145+See [Layer 2 actions](/docs/azimuth/l2-actions) for an overview of how
146+`dominion` determines the actions available to a ship.
147+
148+`operators` already existed on layer 1 and are defined as a part of the [ERC-721
149+standard](https://eips.ethereum.org/EIPS/eip-721).
150+
151+`dns` is a list of DNS entries associated to galaxy IP addresses. At present, this
152+is always `~['urbit.org' 'urbit.org' 'urbit.org']`.
153+
154+### `aggregator.hoon`
155+
156+`/app/aggregator.hoon` is a Gall agent responsible for collecting and submitting batches of
157+layer 2 transactions to the Ethereum blockchain. This app is also called the
158+roller. Among other things, it keeps track of a list of pending transactions to
159+be sent, transactions it has sent that are awaiting confirmation, history of
160+transactions sent organized by Ethereum address, and when the next batch of
161+transactions will be sent.
162+
163+![Aggregator](https://media.urbit.org/docs/layer2/l2-aggregator.svg)
164+
165+`aggregator.hoon` has a number of scries available, intended primarily to
166+display data to the end user in Bridge. They can be inferred from the `+on-peek`
167+arm:
168+
169+```hoon
170+ ++ on-peek
171+ |= =path
172+ ^- (unit (unit cage))
173+ |^
174+ ?+ path ~
175+ [%x %pending ~] ``noun+!>(pending)
176+ [%x %pending @ ~] (pending-by i.t.t.path)
177+ [%x %tx @ %status ~] (status i.t.t.path)
178+ [%x %history @ ~] (history i.t.t.path)
179+ [%x %nonce @ @ ~] (nonce i.t.t.path i.t.t.t.path)
180+ [%x %spawned @ ~] (spawned i.t.t.path)
181+ [%x %next-batch ~] ``atom+!>(next-batch)
182+ [%x %point @ ~] (point i.t.t.path)
183+ [%x %points @ ~] (points i.t.t.path)
184+ [%x %config ~] config
185+ [%x %chain-id ~] ``atom+!>(chain-id)
186+ ==
187+```
188+
189+This app is not responsible for communicating with Bridge via HTTP. Instead, that is
190+handled by `aggregator-rpc.hoon`. The scries are also communicated to Bridge via
191+`aggregator-rpc.hoon`.
192+
193+### `aggregator-rpc.hoon`
194+
195+`/app/aggregator-rpc.hoon` is a very simple Gall app responsible for receiving HTTP RPC-API
196+calls, typically sent from other Urbit ID users via Bridge. It then translates
197+these API calls from JSON to a format understood by `aggregator.hoon` and
198+forwards them. This app
199+does not keep any state - its only purpose is to act as an intermediary between
200+Bridge and `aggregator.hoon`. See [here](/docs/azimuth/layer2-api) for more
201+information on the JSON RPC-API.
202+
content/docs/azimuth/layer2-api.mdnew file+14
@@ -0,0 +1,14 @@
1++++
2+title = "Roller HTTP RPC API"
3+weight = 10
4+template = "doc.html"
5++++
6+
7+With the introduction of Layer 2 arrived a new set of Gall agents equipped with
8+an HTTP RPC API primarily intended for interacting with Bridge. We have
9+documented how to perform these API calls yourself if you are so inclined. These can be found [here](https://documenter.getpostman.com/view/16338962/Tzm3nx7x).
10+
11+The set of API calls available is summarized in the following diagram.
12+
13+![JSON RPC-API](https://media.urbit.org/docs/layer2/l2-json-rpc.svg)
14+
content/docs/azimuth/layer2.md+23−8
@@ -4,7 +4,7 @@ weight = 5
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−This document provides technical detail on Azimuth's "Layer 2" scaling solution
7+This document provides technical details on Azimuth's "Layer 2" scaling solution
8for 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
9"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
10as other proximal topis.
10as other proximal topis.
@@ -17,7 +17,8 @@ This is not intended for everyday users who only wish to know how
17to either transfer their ship to layer 2 or perform layer 2 actions. For that,
17to either transfer their ship to layer 2 or perform layer 2 actions. For that,
18see ((bridge documentation yet to be written)). For a casual overview of the
18see ((bridge documentation yet to be written)). For a casual overview of the
19rationale and functionality of layer 2, please see this [blog
19rationale and functionality of layer 2, please see this [blog
20−post](/blog/rollups).
20+post](/blog/rollups). For more information on how Azimuth works more generally,
21+including interactions with Bridge and Ethereum, see the page on [Azimuth data flow](/docs/azimuth/l2-flow).
21
22
22This page is also not where to find instruction on how to run your own "aggregator"/"roller".
23This page is also not where to find instruction on how to run your own "aggregator"/"roller".
23Documentation for this process is forthcoming. However, this page does contain
24Documentation for this process is forthcoming. However, this page does contain
@@ -50,7 +51,7 @@ By default, step four always succeeds. It has always been possible in theory for
50your urbit to dispute what it read on Ethereum, but there has never been any
51your urbit to dispute what it read on Ethereum, but there has never been any
51reason to do so.
52reason to do so.
52
53
53−### Layer 2
54+### Layer 2 {#layer-2}
54
55
55Layer 1 still functions identically today as it did before naive rollups. Naive
56Layer 1 still functions identically today as it did before naive rollups. Naive
56rollups work via the following process.
57rollups work via the following process.
@@ -104,9 +105,12 @@ They are:
104 duplicate information such as which smart contract the transactions are
105 duplicate information such as which smart contract the transactions are
105 intended for.
106 intended for.
106
107
107−Put together, these create a reduction in gas costs of at least 65x. This is
108+Put together, these create a reduction in gas costs of at least 65x when adding
108−true even for batches of L2 transactions that contain only a single transaction.
109+a transaction to a sufficiently large batch (approximately 30 or more
109−Thus there is reason to use one's own ship as an aggregator.
110+transactions). A single transaction submitted as a batch is approximately 5x
111+cheaper, while 10 transaction submitted as a batch is approximately 30x cheaper.
112+Thus using one's own ship to submit a single-transaction batch is still a
113+cost-saving measure.
110
114
111### One way trip
115### One way trip
112
116
@@ -139,7 +143,8 @@ in the sponsee having no sponsor on layer 1, and layer 2 as well if they were
139the sponsor on layer 2. This is necessary to simplify the logic, but it also
143the sponsor on layer 2. This is necessary to simplify the logic, but it also
140guarantees that there is no hard requirement to ever utilize layer 2. Without
144guarantees that there is no hard requirement to ever utilize layer 2. Without
141this exception, sponsors with sponsees that move to layer 2 would be forced to
145this exception, sponsors with sponsees that move to layer 2 would be forced to
142−detach them as a layer 2 action if they wanted to cease sponsorship.
146+detach them as a layer 2 action if they wanted to cease sponsorship. This would
147+also have an unacceptable impact on ships owned by [smart contracts](#smart-contracts).
143
148
144If both sponsor and sponsee are on layer 1 then sponsorship actions may occur on
149If both sponsor and sponsee are on layer 1 then sponsorship actions may occur on
145either layer. As long as all sponsorship actions betweeen the two parties occur
150either layer. As long as all sponsorship actions betweeen the two parties occur
@@ -153,6 +158,12 @@ transitions](#sponsorship-state-transitions) section below, we give a table that
153shows how the sponsor and escape status of a ship changes according to which
158shows how the sponsor and escape status of a ship changes according to which
154actions are taken.
159actions are taken.
155
160
161+### Smart contracts {#smart-contracts}
162+
163+Smart contracts are unable to own layer 2 ships, and thus cannot sign layer 2
164+transactions. This creates a hard requirement that layer 1 ships be allowed to
165+perform a layer 1 detach operation on a layer 2 ships.
166+
156## Azimuth state
167## Azimuth state
157
168
158The introduction of layer 2 presents additional complication in understanding
169The introduction of layer 2 presents additional complication in understanding
@@ -195,6 +206,9 @@ state held on your ship (Layer 2 Azimuth state) claims that the sponsor of
195sponsor of `~sampel-palnet` was `~marzod` before `~sampel-palnet` was deposited
206sponsor of `~sampel-palnet` was `~marzod` before `~sampel-palnet` was deposited
196to layer 2, and thus the Azimuth PKI on Ethereum will forever reflect this.
207to layer 2, and thus the Azimuth PKI on Ethereum will forever reflect this.
197
208
209+For more information on how Azimuth state is handled, including how this
210+integrates with Bridge and Ethereum, see [Azimuth data flow](/docs/azimuth/l2-flow).
211+
198### Sponsorship state transitions
212### Sponsorship state transitions
199
213
200When either a sponsor or sponsee is on layer 2, then all sponsorship actions
214When either a sponsor or sponsee is on layer 2, then all sponsorship actions
@@ -312,7 +326,8 @@ immediately creates problems, and the seller's reputation would be tarnished.
312Due to the expense or effort needed to acquire a star, this seems an unlikely
326Due to the expense or effort needed to acquire a star, this seems an unlikely
313scenario as the reward is much less than the cost. Nonetheless, buyers should
327scenario as the reward is much less than the cost. Nonetheless, buyers should
314always make an effort to purchase from a reputable star, as is the case with all
328always make an effort to purchase from a reputable star, as is the case with all
315−transactions in life.
329+transactions in life. If you want to be absolutely sure that you've received the
330+planet, just wait for the batch to be sent and confirmed.
316
331
317Multi-keyfiles were possible before layer 2, but as the cost of configuring keys
332Multi-keyfiles were possible before layer 2, but as the cost of configuring keys
318was comparable to the cost of buying a planet, they were not practical.
333was comparable to the cost of buying a planet, they were not practical.
content/using/id/_index.md+16
@@ -31,3 +31,19 @@ network.
31### [Guide to Breaches](/using/id/guide-to-breaches)
31### [Guide to Breaches](/using/id/guide-to-breaches)
32
32
33What to do when things go very wrong and you need to start over.
33What to do when things go very wrong and you need to start over.
34+
35+## Layer 2
36+
37+In 2021, [naive rollups](/blog/rollups) were introduced to reduce the cost of
38+working with Urbit ID and the friction associated with using Ethereum and
39+cryptocurrency. We have written a series of short guides intended to educate
40+users of how these changes affect them. For more comprehensive documentation
41+aimed at developers, see the [Azimuth documentation](/docs/azimuth).
42+
43+### Layer 2 Bridge Guide
44+
45+A guide to how to utilize Bridge to interact with Layer 2.
46+
47+### [Layer 2 Star Proxies](/using/id/l2-star)
48+
49+A summary of the different options available to stars and their proxies on layer 2.
content/using/id/l2-star.mdnew file+40
@@ -0,0 +1,40 @@
1++++
2+title = "Layer 2 Star Proxies"
3+weight = 60
4+template = "doc.html"
5++++
6+
7+This is a brief summary of proxy options for stars on layer 2.
8+
9+## One-way trip
10+
11+Stars have three options with respect to layer 2:
12+ - Layer 1
13+ - Layer 1 with Layer 2 spawn proxy
14+ - Layer 2
15+
16+A layer 1 star can move to layer 1 with layer 2 spawn proxy, or to layer 2. A
17+star on layer 1 with layer 2 spawn proxy can move to layer 2. None of these
18+actions are currently reversible.
19+
20+Moving between layers has no effect on sponsorship status of any of its
21+sponsees, nor its sponsorship status with its galaxy. It also has no effect on
22+planets spawned by the star prior to moving between layers.
23+
24+## Layer 1
25+
26+A star on layer 1 performs all Urbit ID-related actions on layer 1, except for
27+sponsorship actions, which can be performed on either layer.
28+
29+## Layer 1 with Layer 2 spawn proxy
30+
31+A star on layer 1 with layer 2 spawn proxy can spawn planets on layer 2 using
32+either their ownership proxy or spawn proxy. They will no longer be able to
33+spawn planets on layer 1. They may also perform sponsorship actions on either
34+layer, identical to layer 1 stars.
35+
36+## Layer 2
37+
38+A star on layer 2 must perform all Urbit ID related actions on layer 2. All
39+planets spawned by the star will be on layer 2.
40+