@@ -0,0 +1,395 @@
1++++
2+title = "Jael Public API"
3+weight = 5
4+template = "doc.html"
5++++
6+
7+# Jael
8+
9+In this document we describe the public interface for Jael. Namely, we describe
10+each `task` that Jael can be `%pass`ed, and which `gift`(s) Jael can `%give` in return.
11+
12+
13+## Tasks
14+
15+### `%dawn`
16+
17+This `task` is called once per ship during the vane initialization
18+phase immediately following the beginning of the [adult
19+stage](@/docs/tutorials/arvo/arvo.md#structural-interface-core). This `task` is `%pass`ed to Jael by Dill, as Dill is the first vane to be loaded for
20+technical reasons, though we consider Jael to be the true "first" vane. This
21+`task` is only used for ships that will join the Ames network - fake ships (i.e.
22+made with `./urbit -F zod`) use the `%fake` `task` instead.
23+
24+`%dawn` is used to perform a sequence of initialization tasks related to saving
25+information about Azimuth and the Ames network and booting other vanes for the first time. Upon
26+receipt of a `%dawn` `task`, Jael will:
27+ - record the Ethereum block the public key is registered to,
28+ - record the URL of the Ethereum node used,
29+ - save the signature of the parent planet (if the ship is a moon),
30+ - load the initial public and private keys for the ship,
31+ - set the DNS suffix(es) used by the network (currently just `arvo.network`),
32+ - save the public keys of all galaxies,
33+ - set Jael to subscribe to `%azimuth-tracker`,
34+ - `%slip` a `%init` `task` to Ames, Clay, Gall, Dill, and Eyre, and `%give` an `%init`
35+`gift` to Arvo, which then informs Unix that the initialization process has concluded.
36+
37+#### Accepts
38+
39+`%dawn` accepts a `dawn-event`:
40+
41+```hoon
42+ +$ dawn-event
43+ $: =seed
44+ spon=(list [=ship point:azimuth-types])
45+ czar=(map ship [=rift =life =pass])
46+ turf=(list turf)
47+ bloq=@ud
48+ node=(unit purl:eyre)
49+ ==
50+```
51+
52+The `seed` is `[who=ship lyf=life key=ring sig=(unit oath:pki)]`. `who` is the
53+`@p` of the ship running the `task`, `lyf` is the current ship key revision,
54+`key` is the ship's private key, and `sig` is the signature of the ship's parent
55+planet if the ship is moon and `[~]` otherwise.
56+
57+`spon` is a `list` of ships and their `point`s in the ship's sponsorship chain,
58+all the way to the galaxy level. `point:azimuth-types` contains all Azimuth
59+related data and can be found in `zuse.hoon`.
60+
61+`czar` is a map from each galaxy's `@p` to its `rift`, `life`, and public key (`pass`).
62+
63+`turf` is a `list` of DNS suffixes used by the Ames network, which for now is
64+just `arvo.network`.
65+
66+`bloq` is the number of the Ethereum block in which the ship registered its keys
67+with the Azimuth smart contract.
68+
69+`node` is the URL of the Ethereum node used to register the ship's keys with Azimuth.
70+
71+#### Returns
72+
73+Jael `%give`s an `%init` `gift` to Unix. This occurs after the Dill `%slip`
74+init.
75+
76+#### Slips
77+
78+Jael `%slip`s `%init` `task`s to each of Eyre, Dill, Gall, Clay, and Ames, in
79+that order.
80+
81+
82+### `%fake`
83+
84+This `task` is used instead of `%dawn` when creating a fake ship via the `-F`
85+flag when calling the Urbit binary. It performs a subset of the actions that
86+`%dawn` performs, modified to accommodate the fake ship.
87+
88+`%fake` endows the ship with a private key and a public key deterministically derived from the
89+ship's `@p`. It sets `fak.own.pki` to `%.y`, which is the bit that determines
90+whether or not a ship is fake. Other parts of the Jael state, such as the
91+sponsorship chain and galaxy public keys are left at their bunted values.
92+
93+#### Accepts
94+
95+```hoon
96+[=ship]
97+```
98+`ship` is the `@p` of the fake ship being created.
99+
100+#### Returns
101+
102+Jael `%give`s a `%init` `gift` to Unix.
103+
104+#### Slips
105+
106+In response to a `%fake` `task`, Jael `%slip`s a `%init` `task` to each of Eyre, Dill, Gall,
107+Clay, and Ames, in that order.
108+
109+
110+### `%listen`
111+
112+Sets the source that the public keys for a set of `ship`s should be obtained
113+from. This can either be a Gall app that communicates with an Ethereum node such
114+as `%azimuth-tracker`, as in the case for galaxies, stars,
115+and planets, or a ship, as in the case of a moon or comet.
116+
117+After setting the source, Jael will then subscribe to the source for updates on
118+public keys for the given ships.
119+
120+
121+#### Accepts
122+
123+```hoon
124+[whos=(set ship) =source]
125+```
126+
127+`whos` is the set of ships whose key data source is to be altered. `source` is
128+`(each ship term)`, where `term` will ultimately be treated as a handle for a
129+Gall app.
130+
131+A `%listen` `task` with empty `whos` will set the default source to `source`.
132+This is the source used for all ships unless otherwise specified.
133+
134+When the `source` is a `term`, Jael looks into its state to find what source has
135+been previously assigned to that `term` and will henceforth obtain public keys for
136+ships in `(set ship)` from there. In practice, this is always
137+`%azimuth-tracker`, but the ability to use other sources is present.
138+
139+When the `source` is a ship, Jael will obtain public keys for ships in `(set ship)` from
140+the given ship. By default, the `source` for a moon will be the planet that
141+spawned that moon, and the `source` for a comet will be the comet itself.
142+
143+#### Returns
144+
145+This `task` returns no `gift`s.
146+
147+#### Passes
148+
149+If the `source` is a `term`, Jael will `%pass` a `%deal` `task` to Gall asking to
150+`%watch` the app given by `source` at path `/`.
151+
152+If the `source` is a `ship`, Jael will `%pass` a `%plea` `task` to Ames wrapping
153+a `%public-keys` `task` intended for Jael on the `ship` specified by `source`.
154+
155+
156+### `%meet`
157+
158+This `task` is deprecated and does not perform any actions.
159+
160+#### Accepts
161+
162+```hoon
163+[=ship =life =pass]
164+```
165+
166+#### Returns
167+
168+This `task` returns no `gift`s.
169+
170+
171+### `%moon`
172+
173+This `task` sets the public keys of a moon.
174+
175+#### Accepts
176+
177+```hoon
178+[=ship =udiff:point]
179+```
180+
181+The `ship` is the `@p` of the moon. The `task` will be a no-op if the `@p` is not that
182+of a moon, or if the moon does not belong to the ship.
183+
184+`udiff:point` contains the new public keys to be stored for the moon.
185+
186+#### Returns
187+
188+This `task` returns no `gift`s.
189+
190+
191+### `%nuke`
192+
193+This `task` cancels subscriptions to Jael's state from a given set of `ship`s.
194+This `task` works differently depending on whether the `task` originated locally
195+or remotely.
196+
197+#### Accepts
198+
199+```hoon
200+[whos=(set ship)]
201+```
202+`whos` is the `set` of `ship`s from which subscriptions are to be canceled.
203+
204+#### Returns
205+
206+This `task` returns no `gift`s.
207+
208+
209+### `%plea`
210+
211+This `task` is `%pass`ed to Jael from Ames. `%plea`s are wrappers for `task`s
212+that originate from a remote source, as the `%plea` pattern
213+is used to extend the `%pass`/`%give` semantics over the Ames network. Jael
214+attempts to perform the `task` wrapped in the `%plea`.
215+
216+Jael accepts two kinds of `%plea`s: [`%nuke`](#nuke) and
217+[`%public-keys`](#public-keys) and will crash if passed anything else. See the
218+relevant entries to learn how Jael responds to these.
219+
220+#### Accepts
221+
222+```hoon
223+[=ship =plea:ames]
224+```
225+`ship` is the origin of the plea, and `plea:ames` is `[vane=@tas =path
226+payload=*]`. Here, `vane=%j`, `path` is the internal route on the receiving ship, and `payload` is either a `%nuke` or
227+a `%public-keys` `task`.
228+
229+#### Returns
230+
231+Jael `%give`s a `%done` `gift` in response to a `%plea` `task`.
232+
233+#### Passes
234+
235+Jael `%pass`es itself the wrapped `task`.
236+
237+
238+### `%private-keys`
239+
240+This `task` creates a subscription to the private keys kept by Jael.
241+
242+We note that there are two `+private-keys` arms in Jael - one located in the
243+`+feed` core and the other located in the `+feel` core. This `task` calls the
244+arm in the `+feed` core.
245+
246+#### Accepts
247+
248+```hoon
249+[~]
250+```
251+
252+#### Returns
253+
254+```hoon
255+[%private-keys =life vein=(map life ring)]
256+```
257+
258+In response to a `%private-keys` `task`, Jael `%give`s a `%private-keys` `gift`.
259+`life=@ud` is the current `life` of the ship, and `vein` is a `map` from
260+`life`s to `ring`s that keeps track of all `life`-`ring` pairs throughout the
261+history of the ship.
262+
263+
264+### `%public-keys`
265+
266+This `task` creates a subscription for the callee to a selection of the public
267+keys kept by Jael. This `task` can originate locally or remotely.
268+
269+#### Accepts
270+
271+```hoon
272+[ships=(set ship)]
273+```
274+`ships` is the `set` of `ship`s whos' public keys are being subscribed to.
275+
276+#### Returns
277+
278+```hoon
279+[%public-keys =public-keys-result]
280+```
281+If the `task` originated locally, Jael `%give`s a `%public-keys` `gift` in
282+response. If it originated remotely, Jael `%give`s a `%boon` `gift` to back
283+to Ames wrapping a `%public-keys` `gift`.
284+
285+A `$public-keys-result` is the following.
286+```hoon
287+ +$ public-keys-result
288+ $% [%full points=(map ship point)]
289+ [%diff who=ship =diff:point]
290+ [%breach who=ship]
291+```
292+The first time Jael receives a `%public-keys` `task` from a ship it will return
293+a `[%public-keys-result %full]` `gift`, which contains all information about ships and
294+their associated points that Jael knows. Subsequent updates will typically be
295+`[%public-keys-result %diff]`, which tells the caller what has changed
296+since last time they sent a `%public-keys` `task`, and `[%public-keys-result
297+%breach]`, which informs the caller of ship breaches.
298+
299+
300+### `%rekey`
301+
302+This `task` updates the ship's private keys.
303+
304+#### Accepts
305+
306+```hoon
307+[=life =ring]
308+```
309+
310+`life` is a `@ud` that is the new ship key revision number. `ring` is a `@` that is the new private key.
311+
312+#### Returns
313+
314+```hoon
315+[%private-keys =life vein=(map life ring)]
316+```
317+
318+In response to a `%rekey` `task`, Jael `%give`s a `%private-keys` `gift`. `life`
319+is the new `life` given in the original `task`, and `vein` is a `map` from
320+`life`s to `ring`s that keeps track of all `life`-`ring` pairs throughout the
321+history of the ship.
322+
323+
324+### `%trim`
325+
326+This `task` is sent by the interpreter in order to free up memory.
327+ This `task` is empty for Jael, since it is not a good idea to forget your
328+ private keys and other cryptographic data.
329+
330+#### Accepts
331+
332+```hoon
333+[p=@ud]
334+```
335+This argument is unused by Jael.
336+
337+#### Returns
338+
339+This task returns nothing.
340+
341+
342+
343+### `%turf`
344+
345+This `task` is a request for Jael to provide its list of `turf`s, e.g. DNS
346+suffixes for the Ames network. Currently `arvo.network` is the only `turf` in use.
347+
348+#### Accepts
349+
350+```hoon
351+[~]
352+```
353+
354+#### Returns
355+
356+```hoon
357+[%turn tuf.own.pki]
358+```
359+
360+Jael `%give`s a `%turf` `gift` in response to a `%turf` `task`. `tuf.own.pki` is
361+a `(list turf)`, which is Jael's list of `turf`s.
362+
363+
364+### `%vega`
365+
366+`%vega` is called whenever the kernel is updated. Jael currently does not do
367+anything in response to this.
368+
369+#### Accepts
370+
371+`%vega` takes no arguments.
372+
373+#### Returns
374+
375+This `task` returns no `gift`s.
376+
377+
378+
379+### `%wegh`
380+
381+This `task` is a request to Jael to produce a memory usage report.
382+
383+#### Accepts
384+
385+This `task` has no arguments.
386+
387+#### Returns
388+
389+In response to this `task,` Jael `%give`s a `%mass` `gift` containing Ames'
390+current memory usage.
391+
392+
393+
394+
395+