@@ -1,393 +0,0 @@
2−title = "API Reference"
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.
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.
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.
37−`%dawn` accepts a `dawn-event`:
42− spon=(list [=ship point:azimuth-types])
43− czar=(map ship [=rift =life =pass])
46− node=(unit purl:eyre)
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.
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`.
59−`czar` is a map from each galaxy's `@p` to its `rift`, `life`, and public key (`pass`).
61−`turf` is a `list` of DNS suffixes used by the Ames network, which for now is
64−`bloq` is the number of the Ethereum block in which the ship registered its keys
65−with the Azimuth smart contract.
67−`node` is the URL of the Ethereum node used to register the ship's keys with Azimuth.
71−Jael `%give`s an `%init` `gift` to Unix. This occurs after the Dill `%slip`
76−Jael `%slip`s `%init` `task`s to each of Eyre, Dill, Gall, Clay, and Ames, in
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.
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.
96−`ship` is the `@p` of the fake ship being created.
100−Jael `%give`s a `%init` `gift` to Unix.
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.
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.
115−After setting the source, Jael will then subscribe to the source for updates on
116−public keys for the given ships.
122−[whos=(set ship) =source]
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
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.
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.
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.
143−This `task` returns no `gift`s.
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 `/`.
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`.
156−This `task` is deprecated and does not perform any actions.
166−This `task` returns no `gift`s.
171−This `task` sets the public keys of a moon.
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.
182−`udiff:point` contains the new public keys to be stored for the moon.
186−This `task` returns no `gift`s.
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
200−`whos` is the `set` of `ship`s from which subscriptions are to be canceled.
204−This `task` returns no `gift`s.
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`.
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.
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`.
229−Jael `%give`s a `%done` `gift` in response to a `%plea` `task`.
233−Jael `%pass`es itself the wrapped `task`.
238−This `task` creates a subscription to the private keys kept by Jael.
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.
253−[%private-keys =life vein=(map life ring)]
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
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.
272−`ships` is the `set` of `ship`s whos' public keys are being subscribed to.
277−[%public-keys =public-keys-result]
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`.
283−A `$public-keys-result` is the following.
285− +$ public-keys-result
286− $% [%full points=(map ship point)]
287− [%diff who=ship =diff:point]
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.
300−This `task` updates the ship's private keys.
308−`life` is a `@ud` that is the new ship key revision number. `ring` is a `@` that is the new private key.
313−[%private-keys =life vein=(map life ring)]
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
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.
333−This argument is unused by Jael.
337−This task returns nothing.
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.
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.
364−`%vega` is called whenever the kernel is updated. Jael currently does not do
365−anything in response to this.
369−`%vega` takes no arguments.
373−This `task` returns no `gift`s.
379−This `task` is a request to Jael to produce a memory usage report.
383−This `task` has no arguments.
387−In response to this `task,` Jael `%give`s a `%mass` `gift` containing Ames'
388−current memory usage.