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