@@ -0,0 +1,395 @@
2+title = "Jael Public API"
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.
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.
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.
39+`%dawn` accepts a `dawn-event`:
44+ spon=(list [=ship point:azimuth-types])
45+ czar=(map ship [=rift =life =pass])
48+ node=(unit purl:eyre)
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.
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`.
61+`czar` is a map from each galaxy's `@p` to its `rift`, `life`, and public key (`pass`).
63+`turf` is a `list` of DNS suffixes used by the Ames network, which for now is
66+`bloq` is the number of the Ethereum block in which the ship registered its keys
67+with the Azimuth smart contract.
69+`node` is the URL of the Ethereum node used to register the ship's keys with Azimuth.
73+Jael `%give`s an `%init` `gift` to Unix. This occurs after the Dill `%slip`
78+Jael `%slip`s `%init` `task`s to each of Eyre, Dill, Gall, Clay, and Ames, in
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.
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.
98+`ship` is the `@p` of the fake ship being created.
102+Jael `%give`s a `%init` `gift` to Unix.
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.
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.
117+After setting the source, Jael will then subscribe to the source for updates on
118+public keys for the given ships.
124+[whos=(set ship) =source]
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
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.
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.
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.
145+This `task` returns no `gift`s.
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 `/`.
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`.
158+This `task` is deprecated and does not perform any actions.
168+This `task` returns no `gift`s.
173+This `task` sets the public keys of a moon.
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.
184+`udiff:point` contains the new public keys to be stored for the moon.
188+This `task` returns no `gift`s.
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
202+`whos` is the `set` of `ship`s from which subscriptions are to be canceled.
206+This `task` returns no `gift`s.
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`.
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.
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`.
231+Jael `%give`s a `%done` `gift` in response to a `%plea` `task`.
235+Jael `%pass`es itself the wrapped `task`.
240+This `task` creates a subscription to the private keys kept by Jael.
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.
255+[%private-keys =life vein=(map life ring)]
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
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.
274+`ships` is the `set` of `ship`s whos' public keys are being subscribed to.
279+[%public-keys =public-keys-result]
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`.
285+A `$public-keys-result` is the following.
287+ +$ public-keys-result
288+ $% [%full points=(map ship point)]
289+ [%diff who=ship =diff:point]
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.
302+This `task` updates the ship's private keys.
310+`life` is a `@ud` that is the new ship key revision number. `ring` is a `@` that is the new private key.
315+[%private-keys =life vein=(map life ring)]
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
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.
335+This argument is unused by Jael.
339+This task returns nothing.
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.
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.
366+`%vega` is called whenever the kernel is updated. Jael currently does not do
367+anything in response to this.
371+`%vega` takes no arguments.
375+This `task` returns no `gift`s.
381+This `task` is a request to Jael to produce a memory usage report.
385+This `task` has no arguments.
389+In response to this `task,` Jael `%give`s a `%mass` `gift` containing Ames'
390+current memory usage.