@@ -8,8 +8,7 @@ This document summarizes the various components involved with Azimuth and
8how they communicate with each other. This also constitutes an explanation for
8how they communicate with each other. This also constitutes an explanation for
9how Urbit implements the data flow of naive rollups.
9how Urbit implements the data flow of naive rollups.
11−The following diagram illustrates the high-level structure of Azimuth as seen
11+The following diagram illustrates the high-level structure of Azimuth.
12−from the perspective of Urbit.
14
13
@@ -21,27 +20,37 @@ them to a roller via an HTTP API.
24−Azimuth is a set of smart contracts that exists on Ethereum that defines the
23+Azimuth was originally defined as a set of smart contracts on Ethereum that
25−state and logic of the PKI. With the advent of naive rollups, this has also come
24+defines the state and business logic of the PKI for layer 1. With the advent of
26−to include the set of components used for dealing with the PKI within Urbit. The
25+naive rollups, this has also come to include the set of components used for
26+dealing with the PKI within Urbit, as now the complete PKI state is stored
27−following sections outline what each component is responsible for and how it
27+offchain. The following sections outline what each component is responsible for
28−communicates with the others.
28+and how it communicates with the others.
30
30
32−As seen in the above diagram, there are three Gall agents responsible for
32+The Gall agents involved with Azimuth are summarized as follows:
33−managing the PKI state: `azimuth.hoon`, `aggregator.hoon`, and `aggregator-rpc.hoon`.
33+ - [`%azimuth`](#azimuth) - obtains and holds PKI state.
34+ - [`%azimuth-rpc`](#azimuth-rpc) - JSON RPC-API for `%azimuth`
35+ - [`%eth-watcher`](#eth-watcher) - Ethereum event log collector.
36+ - [`%aggregator`](#aggregator) - submits batches of L2 transactions to Ethereum.
37+ - [`%aggregator-rpc`](#aggregator-rpc) - JSON RPC-API for `%aggregator`.
39+The transaction processing library is [`/lib/naive.hoon`](#naive).
35−### `azimuth.hoon`
43+#### `%azimuth` {#azimuth}
37−`/app/azimuth.hoon` is a Gall agent and thread handler responsible for keeping
45+`%azimuth`, located at `/app/azimuth.hoon`, is a Gall agent and thread handler
46+responsible for finding Azimuth transactions gathered by `%eth-watcher`,
38−track of the PKI state, and exposing that data via scries.
47+keeping track of the PKI state, and exposing that data via scries.
40−The following diagram illustrates `azimuth.hoon`'s role in the system.
49+The following diagram illustrates `%azimuth`'s role in the system.
42
51
44−The state held in `azimuth.hoon` is the following.
53+The state held by `%azimuth` is the following.
47++ app-state
56++ app-state
@@ -73,12 +82,67 @@ Scries can be inferred from the `+on-peek` arm:
76−### `eth-watcher.hoon`
85+#### `%azimuth-rpc` {#azimuth-rpc}
87+`%azimuth-rpc`, located at `app/azimuth-rpc.hoon`, is a JSON RPC-API for getting
88+`point` and `dns` data from the Azimuth PKI state kept by `%azimuth`.
90+#### `%eth-watcher` {#eth-watcher}
78−`/app/eth-watcher.hoon` is responsible for listening to an Ethereum node and
92+`%eth-watcher`, located at `/app/eth-watcher.hoon`, is responsible for listening
93+to an Ethereum node and collecting event logs from it. It is general-purpose and
79−collecting Azimuth related transactions. It sends collected transactions to
94+not particular to Azimuth. It sends collected transactions to `+on-agent` in
80−`+on-agent` in `azimuth.hoon`, which then obtains the resulting PKI transitions
95+`%azimuth`, which then obtains the resulting PKI transitions by passing them through
81−from them using `naive.hoon`.
96+[`naive.hoon`](#naive).
98+#### `%aggregator` {#aggregator}
100+`%aggregator`, stored at `/app/aggregator.hoon`, is a Gall agent responsible for
101+collecting and submitting batches of layer 2 transactions to the Ethereum
102+blockchain. This app is also called the roller. Among other things, it keeps
103+track of a list of pending transactions to be sent, transactions it has sent
104+that are awaiting confirmation, history of transactions sent organized by
105+Ethereum address, and when the next batch of transactions will be sent.
107+
109+`%aggregator` has a number of scries available, intended primarily to
110+display data to the end user in Bridge. They can be inferred from the `+on-peek`
116+ ^- (unit (unit cage))
119+ [%x %pending ~] ``noun+!>(pending)
120+ [%x %pending @ ~] (pending-by i.t.t.path)
121+ [%x %tx @ %status ~] (status i.t.t.path)
122+ [%x %history @ ~] (history i.t.t.path)
123+ [%x %nonce @ @ ~] (nonce i.t.t.path i.t.t.t.path)
124+ [%x %spawned @ ~] (spawned i.t.t.path)
125+ [%x %next-batch ~] ``atom+!>(next-batch)
126+ [%x %point @ ~] (point i.t.t.path)
127+ [%x %points @ ~] (points i.t.t.path)
128+ [%x %config ~] config
129+ [%x %chain-id ~] ``atom+!>(chain-id)
133+This app is not responsible for communicating with Bridge via HTTP. Instead, that is
134+handled by `aggregator-rpc.hoon`. The scries are also communicated to Bridge via
135+`aggregator-rpc.hoon`.
137+#### `%aggregator-rpc`
139+`%aggregator-rpc`, stored at `/app/aggregator-rpc.hoon`, is a very simple Gall app responsible for receiving HTTP RPC-API
140+calls, typically sent from other Urbit ID users via Bridge. It then translates
141+these API calls from JSON to a format understood by `%aggregator` and
142+forwards them. This app
143+does not keep any state - its only purpose is to act as an intermediary between
144+Bridge and `%aggregator`. See [here](/docs/azimuth/layer2-api) for more
145+information on the JSON RPC-API.
83### `naive.hoon` {#naive}
147### `naive.hoon` {#naive}
@@ -89,16 +153,16 @@ which handles state transitions caused by both layer 1 and layer 2 transactions.
89A high-level overview of how `naive.hoon` functions can be found
153A high-level overview of how `naive.hoon` functions can be found
90[here](/docs/azimuth/layer2#layer-2).
154[here](/docs/azimuth/layer2#layer-2).
92−A `verifier` is a gate of the form
156+A `verifier` is any gate of the form
95+$ verifier $-([dat=octs v=@ r=@ s=@] (unit address))
159+$ verifier $-([dat=octs v=@ r=@ s=@] (unit address))
98−It runs the keccak hash function on `dat` to verify that `dat` is data signed by
162+The `verifier` in use by `naive.hoon` runs the keccak hash function on `dat` to
99−the ECDSA signature given by the `[v r s]` tuple, according to the format for
163+verify that `dat` is data signed by the ECDSA signature given by the `[v r s]`
100−signed transactions outlined in the [bytestring
164+tuple, according to the format for signed transactions outlined in the
101−format](/docs/azimuth/bytestring) documentation.
165+[bytestring format](/docs/azimuth/bytestring) documentation.
103`chain-id` is the ID used by the Ethereum blockchain, which is `1337`. See [bytestring
167`chain-id` is the ID used by the Ethereum blockchain, which is `1337`. See [bytestring
104format](/docs/azimuth/bytestring) for more information.
168format](/docs/azimuth/bytestring) for more information.
@@ -151,52 +215,3 @@ standard](https://eips.ethereum.org/EIPS/eip-721).
151`dns` is a list of DNS entries associated to galaxy IP addresses. At present, this
215`dns` is a list of DNS entries associated to galaxy IP addresses. At present, this
152is always `~['urbit.org' 'urbit.org' 'urbit.org']`.
216is always `~['urbit.org' 'urbit.org' 'urbit.org']`.
154−### `aggregator.hoon`
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.
163−
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`
172− ^- (unit (unit cage))
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)
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`.
193−### `aggregator-rpc.hoon`
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.