@@ -8,28 +8,27 @@ This document summarizes the various components involved with Azimuth and
88how they communicate with each other. This also constitutes an explanation for
99how Urbit implements the data flow of naive rollups.
1010
11−The following diagram illustrates the high-level structure of Azimuth.
12−
13−[](https://media.urbit.org/docs/layer2/l2-high.png)
14−
1511## Bridge
1612
17−The primary way in which users interact with Azimuth is via Bridge. Bridge is
18−responsible for collecting transactions from users, signing them, and forwarding
19−them to a roller via an HTTP API.
13+The primary way in which users interact with Azimuth is via
14+[Bridge](https://bridge.urbit.org). Bridge is responsible for collecting
15+transactions from users, signing them, and forwarding them to a roller via an
16+HTTP API.
2017
2118## Azimuth
2219
2320Azimuth was originally defined as a set of smart contracts on Ethereum that
24−defines the state and business logic of the PKI for layer 1. With the advent of
21+defines the [state](/docs/azimuth/azimuth-eth) and [business
22+logic](/docs/azimuth/ecliptic) of the PKI for layer 1. With the introduction of
2523naive rollups, this has also come to include the set of components used for
2624dealing with the PKI within Urbit, as now the complete PKI state is stored
27−offchain. The following sections outline what each component is responsible for
28−and how it communicates with the others.
25+offchain (though this state is derived entirely from on-chain data). The
26+following sections outline what each component is responsible for and how it
27+communicates with the others.
2928
3029The Gall agents involved with Azimuth are summarized as follows:
3130 - [`%azimuth`](#azimuth) - obtains and holds PKI state.
32− - [`%azimuth-rpc`](#azimuth-rpc) - JSON RPC-API for `%azimuth`
31+ - [`%azimuth-rpc`](#azimuth-rpc) - JSON RPC-API for `%azimuth`.
3332 - [`%eth-watcher`](#eth-watcher) - Ethereum event log collector.
3433 - [`%roller`](#roller) - submits batches of L2 transactions to Ethereum.
3534 - [`%roller-rpc`](#roller-rpc) - JSON RPC-API for `%roller`.
@@ -90,7 +89,7 @@ Scries can be inferred from the `+on-peek` arm:
9089`%eth-watcher`, located at `/app/eth-watcher.hoon`, is responsible for listening
9190to an Ethereum node and collecting event logs from it. It is general-purpose and
9291not particular to Azimuth. It sends collected transactions to `+on-agent` in
93−`%azimuth`, which then obtains the resulting PKI transitions by passing them through
92+`%azimuth`, which then obtains the resulting PKI state transitions by passing them to
9493[`naive.hoon`](#naive).
9594
9695[](https://media.urbit.org/docs/layer2/roller-agents.png)
@@ -105,6 +104,11 @@ that are awaiting confirmation, history of transactions sent organized by
105104Ethereum address, and when the next batch of transactions will be sent. See also
106105[Rollers](/docs/azimuth/l2/roller) for more information on the roller.
107106
107+The following diagram illustrates how the roller interacts with Bridge and
108+Ethereum at a high level.
109+
110+[](https://media.urbit.org/docs/layer2/l2-high.png)
111+
108112The relationship between the roller and other agents is outlined in the
109113following diagram.
110114
@@ -135,29 +139,30 @@ arm:
135139```
136140
137141This app is not responsible for communicating with Bridge via HTTP. Instead, that is
138−handled by `roller-rpc.hoon`. The scries are also communicated to Bridge via
139−`roller-rpc.hoon`.
142+handled by `%roller-rpc`. The scries are also communicated to Bridge via
143+`%roller-rpc`.
140144
141145#### `%roller-rpc`
142146
143147`%roller-rpc`, stored at `/app/roller-rpc.hoon`, is a very simple Gall app responsible for receiving HTTP RPC-API
144148calls, typically sent from other Urbit ID users via Bridge. It then translates
145149these API calls from JSON to a format understood by `%roller` and
146−forwards them. This app
150+forwards them to `%roller`. This app
147151does not keep any state - its only purpose is to act as an intermediary between
148152Bridge and `%roller`. See [here](/docs/azimuth/l2/layer2-api) for more
149153information on the JSON RPC-API.
150154
151155### `naive.hoon` {#naive}
152156
153−`/lib/naive.hoon` is a gate whose sample is a `verifier`, `chain-id=@ud`,
157+`/lib/naive.hoon` consists of a gate whose sample is a `verifier`, `chain-id=@ud`,
154158`state`, and `input`, which outputs a cell of `[effects state]`. This is the
155−transition function which updates the state of the PKI stored in `azimuth.hoon`
159+transition function which updates the state of the PKI stored in `%azimuth`
156160which handles state transitions caused by both layer 1 and layer 2 transactions.
157161A high-level overview of how `naive.hoon` functions can be found
158162[here](/docs/azimuth/l2/layer2#layer-2).
159163
160−A `verifier` is any gate of the form
164+A `verifier` is a gate whose sample is of the form `[dat=octs v=@ r=@ s=@]` and
165+which returns `(unit address)`:
161166
162167```hoon
163168+$ verifier $-([dat=octs v=@ r=@ s=@] (unit address))
@@ -169,11 +174,13 @@ tuple, according to the format for signed transactions outlined in the
169174[bytestring format](/docs/azimuth/l2/bytestring) documentation.
170175
171176`chain-id` is the ID used by the Ethereum blockchain, which is `1337`. See [bytestring
172−format](/docs/azimuth/l2/bytestring) for more information.
177+format](/docs/azimuth/l2/bytestring) for more information. This is used so that
178+e.g. transactions on the Ropsten test network cannot be replayed on the mainnet.
173179
174180`state` is the current state of the PKI. This is structured similarly to the
175181state held in [Azimuth.eth](/docs/azimuth/azimuth-eth), but will differ in
176−general since `state` takes into account layer 2 transactions as well.
182+general since `state` takes into account layer 2 transactions as well. See the
183+[Layer 2 Overview](/docs/azimuth/l2/layer2#state) for more on how PKI state is handled.
177184
178185```hoon
179186+$ state
@@ -209,15 +216,17 @@ general since `state` takes into account layer 2 transactions as well.
209216+$ dominion ?(%l1 %l2 %spawn)
210217+$ operators (jug address address)
211218```
219+
212220`points` should be self-explanatory if you are already familiar with the
213−structure of [Azimuth.eth](/docs/azimuth/azimuth-eth). The only new addition is `dominion`, which is a record of
221+structure of [Azimuth.eth](/docs/azimuth/azimuth-eth). The only new addition is
222+`dominion`, whose value says
214223whether a ship is on layer 1, layer 2, or layer 1 with a layer 2 spawn proxy.
215224See [Layer 2 actions](/docs/azimuth/l2/l2-actions) for an overview of how
216−`dominion` determines the actions available to a ship.
225+`dominion` determines the PKI actions available to a ship.
217226
218227`operators` already existed on layer 1 and are defined as a part of the [ERC-721
219228standard](https://eips.ethereum.org/EIPS/eip-721).
220229
221−`dns` is a list of DNS entries associated to galaxy IP addresses. At present, this
222−is always `~['urbit.org' 'urbit.org' 'urbit.org']`.
230+`dns` is a list of DNS entries by which galaxy IP addresses may be looked up. At
231+present, this is always `~['urbit.org' 'urbit.org' 'urbit.org']`.
223232