@@ -96,12 +96,19 @@ sponsorship chain and galaxy public keys are left at their bunted values.
9696
9797Like `%dawn`, `%fake` is used to initialize the other vanes. In response to a
9898`%fake` `task`, Jael `%slip`s a `%init` `task` to each of Eyre, Dill, Gall,
99−Clay, and Ames, and `%give`s a `%init` `gift` to Arvo.
99+Clay, and Ames, and `%give`s a `%init` `gift` to Unix.
100100
101101
102102### `%listen`
103103
104−set ethereum source?
104+Sets the source that the public keys for a set of `ship`s should be obtained
105+from. This can either be a Gall app that communicates with an Ethereum node such
106+as `%azimuth-tracker`, as in the case for galaxies, stars,
107+and planets, or a ship, as in the case of a moon or comet.
108+
109+After setting the source, Jael will then subscribe to the source for updates on
110+public keys for the given ships.
111+
105112
106113#### Accepts
107114
@@ -109,73 +116,29 @@ set ethereum source?
109116[whos=(set ship) =source]
110117```
111118
112−A `$source` is `(each ship term)`.
119+`whos` is the set of ships whose key data source is to be altered. `source` is
120+`(each ship term)`, where `term` will ultimately be treated as a handle for a
121+Gall app.
113122
114−```
115−++ each
116− |$ [this that]
117− :: either {a} or {b}, defaulting to {a}.
118− ::
119− :: mold generator: produces a discriminated fork between two types,
120− :: defaulting to {a}.
121− ::
122− $% [%| p=that]
123− [%& p=this]
124− ==
125−```
126−`term=@tas`
123+A `%listen` `task` with empty `whos` will set the default source to `source`.
124+This is the source used for all ships unless otherwise specified.
127125
128−```hoon
129− %listen
130− ~& [%jael-listen whos source]:tac
131− %- curd =< abet
132− (sources:~(feel su hen our now pki etn) [whos source]:tac)
133−```
126+When the `source` is a `term`, Jael looks into its state to find what source has
127+been previously assigned to that `term` and will henceforth obtain public keys for
128+ships in `(set ship)` from there. In practice, this is always
129+`%azimuth-tracker`, but the ability to use other sources is present.
134130
135−```hoon
136−++ su
137− :: the ++su core handles all derived state,
138− :: subscriptions, and actions.
139− ::
140− :: ++feed:su registers subscriptions.
141− ::
142− :: ++feel:su checks if a ++change should notify
143− :: any subscribers.
144− ::
145−```
146−
147−```hoon
148− :: Change sources for ships
149− ::
150− ++ sources
151− |= [whos=(set ship) =source]
152− ^+ ..feel
153− =^ =source-id this-su (get-source-id source)
154− =. ..feed
155− ?~ whos
156− ..feed(default-source.etn source-id)
157− =/ whol=(list ship) ~(tap in `(set ship)`whos)
158− =. ship-sources.etn
159− |- ^- (map ship ^source-id)
160− ?~ whol
161− ship-sources.etn
162− (~(put by $(whol t.whol)) i.whol source-id)
163− =. ship-sources-reverse.etn
164− %- ~(gas ju ship-sources-reverse.etn)
165− (turn whol |=(=ship [source-id ship]))
166− ..feed
167− ::
168− ?: ?=(%& -.source)
169− =/ send-message
170− |= =message
171− [hen %pass /public-keys %a %plea p.source %j /public-keys message]
172− (emit (send-message %public-keys whos))
173− (peer p.source whos)
174− --
175−```
131+When the `source` is a ship, Jael will obtain public keys for ships in `(set ship)` from
132+the given ship. By default, the `source` for a moon will be the planet that
133+spawned that moon, and the `source` for a comet will be the comet itself.
176134
177135#### Returns
178136
137+If the `source` is a `term`, Jael will `%pass` a `%deal` `task` to Gall asking to
138+`%watch` the app given by `source` at path `/`.
139+
140+If the `source` is a `ship`, Jael will `%pass` a `%plea` `task` to Ames wrapping
141+a `%public-keys` `task` intended for Jael on the `ship` specified by `source`.
179142
180143### `%meet`
181144