git.iko.soy/urbit.org
on master help sign in
Merge pull request #1104 from tinnus-napbus/fix-jael-docs
300c30etinnus-napbus
content/docs/arvo/jael/scry.md+15−15
compare with master
unifiedsplit
@@ -10,7 +10,7 @@ Jael's scry endpoints never take a `care`. The particular endpoints are specifie
10
10
11A `%step` scry gets the current web login code revision number. It takes your ship name as its `path` and the type returned is a `@ud`.
11A `%step` scry gets the current web login code revision number. It takes your ship name as its `path` and the type returned is a `@ud`.
12
12
13−### Example
13+#### Example
14
14
15```
15```
16> .^(@ud %j /=step=/(scot %p our))
16> .^(@ud %j /=step=/(scot %p our))
@@ -21,7 +21,7 @@ A `%step` scry gets the current web login code revision number. It takes your sh
21
21
22A `%code` scry gets the current web login code. It takes your ship name as its `path` and the type returned is a `@p`.
22A `%code` scry gets the current web login code. It takes your ship name as its `path` and the type returned is a `@p`.
23
23
24−### Example
24+#### Example
25
25
26```
26```
27> .^(@p %j /=code=/(scot %p our))
27> .^(@p %j /=code=/(scot %p our))
@@ -32,7 +32,7 @@ A `%code` scry gets the current web login code. It takes your ship name as its `
32
32
33A `%life` scry gets the current `life` (key revision number) of a ship if known, otherwise it crashes. It takes a ship as its `path` and the type returned is a `@ud`.
33A `%life` scry gets the current `life` (key revision number) of a ship if known, otherwise it crashes. It takes a ship as its `path` and the type returned is a `@ud`.
34
34
35−### Example
35+#### Example
36
36
37```
37```
38> .^(@ud %j /=life=/(scot %p our))
38> .^(@ud %j /=life=/(scot %p our))
@@ -43,7 +43,7 @@ A `%life` scry gets the current `life` (key revision number) of a ship if known,
43
43
44A `%lyfe` scry gets the current unitized `life` (key revision number) of a ship if known, otherwise returns `~`. It takes a ship as its `path` and the type returned is a `(unit @ud)`.
44A `%lyfe` scry gets the current unitized `life` (key revision number) of a ship if known, otherwise returns `~`. It takes a ship as its `path` and the type returned is a `(unit @ud)`.
45
45
46−### Example
46+#### Example
47
47
48```
48```
49> .^((unit @ud) %j /=lyfe=/(scot %p our))
49> .^((unit @ud) %j /=lyfe=/(scot %p our))
@@ -54,7 +54,7 @@ A `%lyfe` scry gets the current unitized `life` (key revision number) of a ship
54
54
55A `%rift` scry gets the current `rift` (continuity number) of a ship if known, otherwise it crashes. It takes a ship as its `path` and the type returned is a `@ud`.
55A `%rift` scry gets the current `rift` (continuity number) of a ship if known, otherwise it crashes. It takes a ship as its `path` and the type returned is a `@ud`.
56
56
57−### Example
57+#### Example
58
58
59```
59```
60.^(@ud %j /=rift=/(scot %p our))
60.^(@ud %j /=rift=/(scot %p our))
@@ -65,7 +65,7 @@ A `%rift` scry gets the current `rift` (continuity number) of a ship if known, o
65
65
66A `%ryft` scry gets the current unitized `rift` (continuity number) of a ship if known, otherwise it returns `~`. It takes a ship as its `path` and the type returned is a `(unit @ud)`.
66A `%ryft` scry gets the current unitized `rift` (continuity number) of a ship if known, otherwise it returns `~`. It takes a ship as its `path` and the type returned is a `(unit @ud)`.
67
67
68−### Example
68+#### Example
69
69
70```
70```
71> .^((unit @ud) %j /=ryft=/(scot %p our))
71> .^((unit @ud) %j /=ryft=/(scot %p our))
@@ -76,7 +76,7 @@ A `%ryft` scry gets the current unitized `rift` (continuity number) of a ship if
76
76
77A `%vein` scry gets your ship's private key for the specified `life`. It takes a `life` `@ud` as its `path` and the type returned is a `ring`.
77A `%vein` scry gets your ship's private key for the specified `life`. It takes a `life` `@ud` as its `path` and the type returned is a `ring`.
78
78
79−### Example
79+#### Example
80
80
81```
81```
82> .^(@uw %j /=vein=/1)
82> .^(@uw %j /=vein=/1)
@@ -87,7 +87,7 @@ A `%vein` scry gets your ship's private key for the specified `life`. It takes a
87
87
88A `%vile` scry gets your `jam`mmed private boot parameters at your ship's current `life`. It takes no additional arguments in its `path`. The type returned is a `@` which is a `jam`med [$seed](/docs/arvo/jael/data-types#seed).
88A `%vile` scry gets your `jam`mmed private boot parameters at your ship's current `life`. It takes no additional arguments in its `path`. The type returned is a `@` which is a `jam`med [$seed](/docs/arvo/jael/data-types#seed).
89
89
90−### Examples
90+#### Examples
91
91
92```
92```
93> .^(@ %j /=vile=)
93> .^(@ %j /=vile=)
@@ -108,7 +108,7 @@ A `%vile` scry gets your `jam`mmed private boot parameters at your ship's curren
108
108
109A `%deed` scry gets the `life`, pubkey and maybe a signature if the ship in question is a comet. It takes the target ship and life as its `path` like `/~sampel-palnet/1` and the type returned is a `[life pass (unit @ux)]`.
109A `%deed` scry gets the `life`, pubkey and maybe a signature if the ship in question is a comet. It takes the target ship and life as its `path` like `/~sampel-palnet/1` and the type returned is a `[life pass (unit @ux)]`.
110
110
111−### Example
111+#### Example
112
112
113```
113```
114> .^([life pass (unit @ux)] %j /=deed=/(scot %p our)/1)
114> .^([life pass (unit @ux)] %j /=deed=/(scot %p our)/1)
@@ -122,7 +122,7 @@ A `%deed` scry gets the `life`, pubkey and maybe a signature if the ship in ques
122
122
123A `%earl` scry deterministically derives a private key for a moon. Note this is a holdover from an old version of moon infrastructure, the current `|moon` generator doesn't use this and instead generates moon private keys non-deterministically. It takes the moon name and your ship's current `life` (not the moon's `life`) as its `path` like `/~doznec-dozzod-dozzod-dozzod/1`. The type returned is a [$seed](/docs/arvo/jael/data-types#seed), the `life` of the moon in the `lyf` field of the `seed` will always be `1`.
123A `%earl` scry deterministically derives a private key for a moon. Note this is a holdover from an old version of moon infrastructure, the current `|moon` generator doesn't use this and instead generates moon private keys non-deterministically. It takes the moon name and your ship's current `life` (not the moon's `life`) as its `path` like `/~doznec-dozzod-dozzod-dozzod/1`. The type returned is a [$seed](/docs/arvo/jael/data-types#seed), the `life` of the moon in the `lyf` field of the `seed` will always be `1`.
124
124
125−### Example
125+#### Example
126
126
127```
127```
128> .^(seed:jael %j /=earl=/~doznec-dozzod-dozzod-dozzod/1)
128> .^(seed:jael %j /=earl=/~doznec-dozzod-dozzod-dozzod/1)
@@ -138,7 +138,7 @@ A `%earl` scry deterministically derives a private key for a moon. Note this is
138
138
139A `%sein` scry gets the sponsor for the specified ship. This scry is used implicitly by `sein:title`. It takes the target ship as its `path` and the type returned is a `@p`.
139A `%sein` scry gets the sponsor for the specified ship. This scry is used implicitly by `sein:title`. It takes the target ship as its `path` and the type returned is a `@p`.
140
140
141−### Example
141+#### Example
142
142
143```
143```
144> .^(@p %j /=sein=/~sampel-palnet)
144> .^(@p %j /=sein=/~sampel-palnet)
@@ -149,7 +149,7 @@ A `%sein` scry gets the sponsor for the specified ship. This scry is used implic
149
149
150A `%saxo` scry gets the sponsorship chain for the target ship (including the target ship itself). For example, a `%saxo` scry for a planet will return the planet, its star and the star's galaxy. This scry is used implicitly by `saxo:title`. It takes the target ship as its `path` and the type returned is a `(list @p)`.
150A `%saxo` scry gets the sponsorship chain for the target ship (including the target ship itself). For example, a `%saxo` scry for a planet will return the planet, its star and the star's galaxy. This scry is used implicitly by `saxo:title`. It takes the target ship as its `path` and the type returned is a `(list @p)`.
151
151
152−### Example
152+#### Example
153
153
154```
154```
155> .^((list @p) %j /=saxo=/~sampel-palnet)
155> .^((list @p) %j /=saxo=/~sampel-palnet)
@@ -168,7 +168,7 @@ nel=(set duct) :: trackers of all
168
168
169The `yen` `jug` maps subscribed `duct`s to the `ship`s they're tracking, and `ney` is just the inverse, mapping tracked `ship`s to subscribed `duct`s. The `nel` set contains `duct`s track all public key updates.
169The `yen` `jug` maps subscribed `duct`s to the `ship`s they're tracking, and `ney` is just the inverse, mapping tracked `ship`s to subscribed `duct`s. The `nel` set contains `duct`s track all public key updates.
170
170
171−### Example
171+#### Example
172
172
173```
173```
174.^([yen=(jug duct ship) ney=(jug ship duct) nel=(set duct)] %j /=subscriptions=/1)
174.^([yen=(jug duct ship) ney=(jug ship duct) nel=(set duct)] %j /=subscriptions=/1)
@@ -179,7 +179,7 @@ The `yen` `jug` maps subscribed `duct`s to the `ship`s they're tracking, and `ne
179
179
180A `%sources` scry gets the current state of Jael's sources for PKI updates. It takes no additional arguments in its `path` and returns a [$state-eth-node](/docs/arvo/jael/data-types#state-eth-node).
180A `%sources` scry gets the current state of Jael's sources for PKI updates. It takes no additional arguments in its `path` and returns a [$state-eth-node](/docs/arvo/jael/data-types#state-eth-node).
181
181
182−### Example
182+#### Example
183
183
184```
184```
185> .^(state-eth-node:jael %j /=sources=)
185> .^(state-eth-node:jael %j /=sources=)
@@ -196,7 +196,7 @@ A `%sources` scry gets the current state of Jael's sources for PKI updates. It t
196
196
197A `%turf` scry gets the list of domain prefixes for galaxies. It takes no additional arguments in its `path`. It returns a `(list turf)`, where a `turf` is a TLD-first `(list @t)`, so `urbit.org` as a `turf` is `~['org' 'urbit']`.
197A `%turf` scry gets the list of domain prefixes for galaxies. It takes no additional arguments in its `path`. It returns a `(list turf)`, where a `turf` is a TLD-first `(list @t)`, so `urbit.org` as a `turf` is `~['org' 'urbit']`.
198
198
199−### Example
199+#### Example
200
200
201```
201```
202> .^((list turf) %j /=turf=)
202> .^((list turf) %j /=turf=)
content/docs/arvo/jael/tasks.md+15−15
@@ -34,7 +34,7 @@ This `task` takes a [$dawn-event](/docs/arvo/jael/data-types#dawn-event) as its
34
34
35You would not use this `task` manually.
35You would not use this `task` manually.
36
36
37−### Returns
37+#### Returns
38
38
39Jael `%give`s an `%init` `gift` to Unix. This occurs after the Dill `%slip` init.
39Jael `%give`s an `%init` `gift` to Unix. This occurs after the Dill `%slip` init.
40
40
@@ -54,7 +54,7 @@ The `ship` field specifies the `@p` of the fake ship being created.
54
54
55You would not use this `task` manually.
55You would not use this `task` manually.
56
56
57−### Returns
57+#### Returns
58
58
59Jael `%give`s a `%init` `gift` to Unix.
59Jael `%give`s a `%init` `gift` to Unix.
60
60
@@ -72,7 +72,7 @@ Sets the source that the public keys for a set of `ship`s should be obtained fro
72
72
73You are unlikely to use this `task` manually.
73You are unlikely to use this `task` manually.
74
74
75−### Returns
75+#### Returns
76
76
77Jael will not return any `gift`s in response to a `%listen` `task`.
77Jael will not return any `gift`s in response to a `%listen` `task`.
78
78
@@ -94,7 +94,7 @@ Register moon keys or otherwise administer a moon.
94
94
95This is what is sent to Jael by `%hood` behind the scenes when you run `|moon`, `|moon-breach` or `|moon-cycle-keys`. The `ship` field is the moon's `@p`. The [$udiff:point](/docs/arvo/jael/data-types#udiffpoint) will contain the bunt of an [$id:block](/docs/arvo/jael/data-types#idblock) (since moons aren't registered in Azimuth) and one of the `udiff` actions depending on what you want to do.
95This is what is sent to Jael by `%hood` behind the scenes when you run `|moon`, `|moon-breach` or `|moon-cycle-keys`. The `ship` field is the moon's `@p`. The [$udiff:point](/docs/arvo/jael/data-types#udiffpoint) will contain the bunt of an [$id:block](/docs/arvo/jael/data-types#idblock) (since moons aren't registered in Azimuth) and one of the `udiff` actions depending on what you want to do.
96
96
97−### Returns
97+#### Returns
98
98
99Jael does not return any `gift`s in response to a `%moon` `task`.
99Jael does not return any `gift`s in response to a `%moon` `task`.
100
100
@@ -110,11 +110,11 @@ If you've subscribed to public or private key updates from Jael with a [%private
110
110
111To cancel a subscription to the ship's private keys you must leave `whos` empty like `[%nuke ~]`.
111To cancel a subscription to the ship's private keys you must leave `whos` empty like `[%nuke ~]`.
112
112
113−### Returns
113+#### Returns
114
114
115Jael does not return a `gift` in response to a `%nuke` `task`.
115Jael does not return a `gift` in response to a `%nuke` `task`.
116
116
117−### Examples
117+#### Examples
118
118
119See the [%public-keys and %nuke](/docs/arvo/jael/examples#public-keys-and-nuke) section of the Examples document for an example of using `%nuke` to cancel a `%public-keys` subscription. See the thread in the [%private-keys](/docs/arvo/jael/examples#private-keys) example for cancelling a `%private-keys` subscription.
119See the [%public-keys and %nuke](/docs/arvo/jael/examples#public-keys-and-nuke) section of the Examples document for an example of using `%nuke` to cancel a `%public-keys` subscription. See the thread in the [%private-keys](/docs/arvo/jael/examples#private-keys) example for cancelling a `%private-keys` subscription.
120
120
@@ -128,7 +128,7 @@ Subscribe to private key updates.
128
128
129Subscribe to be notified of private key updates for the local ship. The subscription will continue until Jael receives a [%nuke](#nuke) `task` to cancel it.
129Subscribe to be notified of private key updates for the local ship. The subscription will continue until Jael receives a [%nuke](#nuke) `task` to cancel it.
130
130
131−### Returns
131+#### Returns
132
132
133Jael responds to a `%private-keys` `task` with a `%private-keys` `gift` which looks like:
133Jael responds to a `%private-keys` `task` with a `%private-keys` `gift` which looks like:
134
134
@@ -138,7 +138,7 @@ Jael responds to a `%private-keys` `task` with a `%private-keys` `gift` which lo
138
138
139The `life` is the current life of the ship and the `vein` `map` contains the private key for each life up to (and including) the current one. Upon first subscribing, Jael will immediately respond with a `%private-keys` `gift`. Then, whenever the ship's private keys are changed, it'll send a new and updated `%private-keys` `gift`.
139The `life` is the current life of the ship and the `vein` `map` contains the private key for each life up to (and including) the current one. Upon first subscribing, Jael will immediately respond with a `%private-keys` `gift`. Then, whenever the ship's private keys are changed, it'll send a new and updated `%private-keys` `gift`.
140
140
141−### Example
141+#### Example
142
142
143See the [%private-keys](/docs/arvo/jael/examples#private-keys) section of the Examples document for a practical example.
143See the [%private-keys](/docs/arvo/jael/examples#private-keys) section of the Examples document for a practical example.
144
144
@@ -152,7 +152,7 @@ Subscribe to public key (and related) updates from Jael.
152
152
153An agent or thread can subscribe to be notified of public key updates, sponsorship changes and continuity breaches for the `set` of `ship`s specified in the `ships` field. The subscription will continue until Jael receives a [%nuke](#nuke) `task` to cancel it.
153An agent or thread can subscribe to be notified of public key updates, sponsorship changes and continuity breaches for the `set` of `ship`s specified in the `ships` field. The subscription will continue until Jael receives a [%nuke](#nuke) `task` to cancel it.
154
154
155−### Returns
155+#### Returns
156
156
157Jael responds to a `%public-keys` `task` with `%public-keys` `gift`s which look like:
157Jael responds to a `%public-keys` `task` with `%public-keys` `gift`s which look like:
158
158
@@ -164,7 +164,7 @@ The [$public-keys-result](/docs/arvo/jael/data-types#public-keys-result) contain
164
164
165Upon subscription, Jael will immeditely respond with a `%public-keys` `gift` containing a `%full` `public-keys-result` with the public key for each `life` up until the current one for each `ship` specified in the original `task`. After than, Jael will send a `%public-keys` `gift` with either a `%diff` or `%breach` `public-keys-result` each time a change occurs for any of the `ship`s to which you're subscribed.
165Upon subscription, Jael will immeditely respond with a `%public-keys` `gift` containing a `%full` `public-keys-result` with the public key for each `life` up until the current one for each `ship` specified in the original `task`. After than, Jael will send a `%public-keys` `gift` with either a `%diff` or `%breach` `public-keys-result` each time a change occurs for any of the `ship`s to which you're subscribed.
166
166
167−### Example
167+#### Example
168
168
169See the [%public-keys and %nuke](/docs/arvo/jael/examples#public-keys-and-nuke) section of the Examples document for a practical example.
169See the [%public-keys and %nuke](/docs/arvo/jael/examples#public-keys-and-nuke) section of the Examples document for a practical example.
170
170
@@ -178,7 +178,7 @@ Update private keys.
178
178
179This is what is sent to Jael by `%hood` when you run `|rekey`, as you must after setting new Azimuth keys or running `|cycle-moon-keys` on a moon's parent. It will update your `life` (key revision number) and private keys. The `life` field is the new `life` (typically an increment of the current `life`) and the `ring` is a private key `@`.
179This is what is sent to Jael by `%hood` when you run `|rekey`, as you must after setting new Azimuth keys or running `|cycle-moon-keys` on a moon's parent. It will update your `life` (key revision number) and private keys. The `life` field is the new `life` (typically an increment of the current `life`) and the `ring` is a private key `@`.
180
180
181−### Returns
181+#### Returns
182
182
183Jael does not return any `gift` in response to a `%rekey` `task`.
183Jael does not return any `gift` in response to a `%rekey` `task`.
184
184
@@ -192,7 +192,7 @@ View domains.
192
192
193The domains returned by a `%turf` `task` are used as the base for individual galaxy domain names (e.g. from `urbit.org` you get `zod.urbit.org`, `bus.urbit.org`, etc). Jael gets these from Azimuth, then Ames gets them from Jael and passes them to the runtime, which will perform the DNS lookups and give Ames back the galaxy IP addresses. A `%turf` task takes no additional arguments. You're unlikely to use this manually - if you want the current `turf`s you'd likely want to do a [turf scry](/docs/arvo/jael/scry#turf) instead.
193The domains returned by a `%turf` `task` are used as the base for individual galaxy domain names (e.g. from `urbit.org` you get `zod.urbit.org`, `bus.urbit.org`, etc). Jael gets these from Azimuth, then Ames gets them from Jael and passes them to the runtime, which will perform the DNS lookups and give Ames back the galaxy IP addresses. A `%turf` task takes no additional arguments. You're unlikely to use this manually - if you want the current `turf`s you'd likely want to do a [turf scry](/docs/arvo/jael/scry#turf) instead.
194
194
195−### Returns
195+#### Returns
196
196
197Jael will respond to a `%turf` `task` with a `%turf` `gift`, which looks like:
197Jael will respond to a `%turf` `task` with a `%turf` `gift`, which looks like:
198
198
@@ -202,7 +202,7 @@ Jael will respond to a `%turf` `task` with a `%turf` `gift`, which looks like:
202
202
203The `turf` in the `(list turf)` is a domain as a `(list @t)`, TLD-first. The current default is `[['org' 'urbit' ~] ~]`.
203The `turf` in the `(list turf)` is a domain as a `(list @t)`, TLD-first. The current default is `[['org' 'urbit' ~] ~]`.
204
204
205−### Example
205+#### Example
206
206
207See the [%turf section of the Examples document](/docs/arvo/jael/examples#turf) for a practical example.
207See the [%turf section of the Examples document](/docs/arvo/jael/examples#turf) for a practical example.
208
208
@@ -216,10 +216,10 @@ Reset web login code.
216
216
217Jael maintains a `step` value that represents the web login code revision number, and uses it to derive the code itself. It begins at `0` and is incremented each time the code is changed. When Jael updates the web login code, it sends Eyre a `%code-changed` `task:eyre` so that Eyre can throw away all of its current cookies and sessions. A `%step` task takes no additional argument.
217Jael maintains a `step` value that represents the web login code revision number, and uses it to derive the code itself. It begins at `0` and is incremented each time the code is changed. When Jael updates the web login code, it sends Eyre a `%code-changed` `task:eyre` so that Eyre can throw away all of its current cookies and sessions. A `%step` task takes no additional argument.
218
218
219−### Returns
219+#### Returns
220
220
221Jael does not return a `gift` in response to a `%step` `task`.
221Jael does not return a `gift` in response to a `%step` `task`.
222
222
223−### Example
223+#### Example
224
224
225See the [%step](/docs/arvo/jael/examples#step) section of the Examples document for a practical example.
225See the [%step](/docs/arvo/jael/examples#step) section of the Examples document for a practical example.