@@ -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+
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+
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+
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+
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+