@@ -10,6 +10,18 @@ vote](/docs/glossary/upgrade). This determines things such as what the various
1010proxies are capable of, how keys are changed, or verifying that a request is
1111valid.
1212
13+Ecliptic uses external contracts such as
14+[Azimuth.eth](/docs/azimuth/azimuth-eth) and
15+[Polls](https://github.com/urbit/azimuth/blob/master/contracts/Polls.sol) for
16+data storage so that it can easily be replaced incase the logic needs to be
17+changed without affecting the data. These data contracts are owned by the
18+Ecliptic contract, and this ownership is passed to the new Ecliptic contract
19+whenever it is replaced. Thus it is advised for clients to not store Ecliptic's
20+contract address directly, but instead ask the Azimuth.eth contract for its
21+`owner` attribute to ensure that transactions are sent to the latest Ecliptic
22+contract. Alternatively, the ENS name `ecliptic.eth` will always resolve to the
23+latest Ecliptic.
24+
1325You can read about [Urbit's first
1426upgrade](https://github.com/urbit/azimuth/pull/35) to Ecliptic, which occurred
1527in the summer of 2021, [here](https://urbit.org/blog/first-contract). The
@@ -17,10 +29,16 @@ in the summer of 2021, [here](https://urbit.org/blog/first-contract). The
1729and consisted of several small modifications to ready the PKI for the
1830introduction of naive rollups.
1931
32+Ecliptic implements the [ERC-721](https://eips.ethereum.org/EIPS/eip-721)
33+interface for non-fungible tokens, as well as the
34+[ERC-165](https://eips.ethereum.org/EIPS/eip-165) standard for interface
35+detection.
36+
2037There are currently [28 functions](#write) which may be called to write to
2138the Ecliptic, and [17 functions](#read) to read data from the Ecliptic. Many of these
2239have a corresponding [layer 2 action](/docs/azimuth/l2-actions), and/or can be
23−performed using [Bridge](/using/id/using-bridge). We note these facts where applicable.
40+performed using [Bridge](/using/id/using-bridge). We note these facts where
41+applicable.
2442
2543## Write functions {#write}
2644
@@ -29,133 +47,384 @@ data to Ethereum. These can be called using
2947[Etherscan](https://etherscan.io/address/ecliptic.eth#writeContract), but
3048the most common functions may be called from within Bridge.
3149
32−### `startDocumentPoll`
50+We only document here the write functions specific to Ecliptic and not the
51+standard functions that are part of the ERC-721 or ERC-165 interfaces.
3352
34−#### Accepts
53+### `Point`s interface
3554
36−`uint8 _galaxy, bytes32 _proposal`
55+These functions are available to each owner of a
56+[`Point`](/docs/azimuth/azimuth-eth#points), and a subset of them are available
57+to its [proxies](#proxies). All of these actions may be performed from Bridge.
3758
38−#### Action
59+#### `configureKeys`
3960
40−Starts a [document poll](/docs/glossary/docvote). Galaxies only. `_galaxy` is
41−the calling galaxy, and `_proposal` is a keccak-256 hash of any arbitrary
42−document or string of text.
61+```
62+ function configureKeys(uint32 _point,
63+ bytes32 _encryptionKey,
64+ bytes32 _authenticationKey,
65+ uint32 _cryptoSuiteVersion,
66+ bool _discontinuous)
67+```
68+
69+Configure `_point` with network public keys `_encryptionKey`, `_authenticationKey`,
70+and corresponding `_cryptoSuiteVersion`, incrementing the `Point`'s continuity
71+number if needed.
72+
73+Corresponds to the layer 2 `%configure-keys` action.
74+
75+#### `spawn`
76+
77+```
78+ function spawn(uint32 _point, address _target)
79+```
80+
81+Spawn `_point`, then either give, or allow `_target` to take, ownership of `_point`.
82+
83+If `_target` is the `:msg.sender`, `_target` owns the `_point` right away.
84+otherwise, `_target` becomes the transfer proxy of `_point`.
85+
86+Requirements:
87+ - `_point` must not be active
88+ - `_point` must not be a planet with a galaxy prefix
89+ - `_point`'s prefix must be linked and under its spawn limit
90+ - `:msg.sender` must be either the owner of `_point`'s prefix, or an authorized spawn proxy for it
91+
92+Corresponds to the layer 2 `%spawn` action.
93+
94+#### `transferPoint`
95+
96+```
97+ function transferPoint(uint32 _point, address _target, bool _reset)
98+```
99+
100+Transfer `_point` to `_target`, clearing all permissions
101+data and keys if `_reset` is true
102+
103+Note: the `_reset` flag is useful when transferring the point to
104+a recipient who doesn't trust the previous owner.
105+
106+Requirements:
107+ - `:msg.sender` must be either `_point`'s current owner, authorized to transfer
108+ `_point`, or authorized to transfer the current owner's points (as in ERC721's operator)
109+ - `_target` must not be the zero address.
110+
111+Corresponds to the layer 2 `%transfer-point` action.
112+
113+#### `escape`
114+
115+```
116+ function escape(uint32 _point, uint32 _sponsor)
117+```
118+
119+Request escape as `_point` to `_sponsor`.
120+
121+If an escape request is already active, this overwrites the existing request.
122+
123+Requirements:
124+ - `:msg.sender` must be the owner or manager of `_point`,
125+ - `_point` must be able to escape to `_sponsor` as per to `canEscapeTo()`
126+
127+ Corresponds to the layer 2 `%escape` action.
128+
129+#### `cancelEscape`
130+
131+```
132+ function cancelEscape(uint32 _point)
133+```
134+
135+Cancel the currently set escape for `_point`.
136+
137+Corresponds to the layer 2 `%cancel-escape` action.
138+
139+#### `adopt`
140+
141+```
142+ function adopt(uint32 _point)
143+```
144+
145+As the relevant sponsor, accept the `_point`.
146+
147+Requirements:
148+ - `:msg.sender` must be the owner or management proxy
149+ of `_point`'s requested sponsor
150+
151+Corresponds to the layer 2 `%adopt` action.
152+
153+#### `reject`
154+
155+```
156+ function reject(uint32 _point)
157+```
158+
159+As the relevant sponsor, deny the `_point`'s `adopt` request.
160+
161+Requirements:
162+ - `:msg.sender` must be the owner or management proxy
163+ of `_point`'s requested sponsor
164+
165+Corresponds to the layer 2 `%reject` action.
166+
167+#### `detach`
168+
169+```
170+ function detach(uint32 _point)
171+```
43172
44−### `detach`
173+As the `_sponsor`, stop sponsoring the `_point`.
45174
46−A sponsor may call this on a sponsee to set `hasSponsor` for their `Point` to
47−`false`.
175+Requirements:
176+ - `:msg.sender` must be the owner or management proxy
177+ of `_point`'s current sponsor
178+
179+Corresponds to the layer 2 `%detach` action.
48180
181+Unlike all other layer 1 actions, layer 1 sponsors may use a layer 1 `detach` on
182+a layer 2 sponsee. See the [Layer 2](/docs/azimuth/layer2#sponsorship) section
183+for more detail.
49184
50−### `approve`
185+### Proxy management {#proxies}
186+
187+These functions are used to manage the various
188+[proxies](/docs/using/id/proxies). All of these actions may be performed from Bridge.
189+
190+#### `setManagementProxy`
191+
192+```
193+ function setManagementProxy(uint32 _point, address _manager)
194+```
195+
196+Configure the management proxy for `_point`.
197+
198+The management proxy may perform "reversible" operations on
199+behalf of the owner. This includes public key configuration and
200+operations relating to sponsorship.
201+
202+Requirements:
203+ - `:msg.sender` must be either `_point`'s current owner or the management proxy.
204+
205+Corresponds to the layer 2 `%set-management-proxy` action.
206+
207+#### `setSpawnProxy`
208+
209+```
210+ function setSpawnProxy(uint16 _prefix, address _spawnProxy)
211+```
212+
213+Give `_spawnProxy` the right to spawn points with the prefix `_prefix` using the
214+`spawn` function.
215+
216+Requirements:
217+ - `:msg.sender` must be either `_point`'s current owner or the spawn proxy.
218+
219+Corresponds to the layer 2 `%set-spawn-proxy` action.
220+
221+#### `setVotingProxy`
222+
223+```
224+ function setVotingProxy(uint8 _galaxy, address _voter)
225+```
226+
227+Configure the voting proxy for `_galaxy`.
228+
229+The voting proxy is allowed to start polls and cast votes on the point's behalf.
230+
231+Requirements:
232+ - `:msg.sender` must be either `_point`'s current owner or the voting proxy.
233+
234+There is no corresponding layer 2 action since voting must occur on layer 1.
235+
236+#### `setTransferProxy`
237+
238+```
239+ function setTransferProxy(uint32 _point, address _transferProxy)
240+```
241+
242+Give `_transferProxy` the right to transfer `_point`.
243+
244+Requirements:
245+ - `:msg.sender` must be either `_point`'s current owner, an operator for the
246+ current owner, or the transfer proxy.
247+
248+Corresponds to the layer 2 `%set-transfer-proxy` action.
249+
250+### Poll actions
251+
252+Most of these are functions only available to galaxies. They are related to
253+[voting](/docs/glossary/voting). As voting does not occur on layer 2, there are
254+no corresponding layer 2 actions for poll actions.
255+
256+Upgrade and document polls last for 30 days, or once a majority is achieved,
257+whichever comes first. If a majority (129) of yes or no votes is achieved, the
258+final vote cast in favor of the winning option also triggers `updateUpgradePoll`
259+or `updateDocumentPoll` as appropriate. Otherwise, if a quorum of 64 votes is
260+achieved, with a majority voting for yes, and the 30 day voting period has
261+expired, then _any_ Ethereum address may call `updateUpgradePoll` or
262+`updateDocumentPoll` as appropriate.
263+
264+#### `startUpgradePoll`
265+
266+```
267+ function startUpgradePoll(uint8 _galaxy, EclipticBase _proposal)
268+```
269+
270+As `_galaxy`, start a poll for the Ecliptic upgrade `_proposal`.
271+
272+Requirements:
273+ - `:msg.sender` must be the owner or voting proxy of `_galaxy`,
274+ - the `_proposal` must expect to be upgraded from this specific
275+ contract, as indicated by its `previousEcliptic` attribute.
276+
277+This action must be performed manually - it is not available in Bridge.
278+
279+#### `startDocumentPoll`
280+
281+```
282+ function startDocumentPoll(uint8 _galaxy, bytes32 _proposal)
283+```
284+
285+As `_galaxy`, start a poll for the `_proposal`. Document polls last for 30 days,
286+or once a majority is achieved, whichever comes first.
287+
288+The `_proposal` argument is the keccak-256 hash of any arbitrary
289+document or string of text.
51290
52−### `updateDocumentPoll`
291+This action must be performed manually - it is not available in Bridge.
53292
54−### `onUpgrade`
293+#### `castUpgradeVote`
55294
56−### `transferPoint`
295+```
296+ function castUpgradeVote(uint8 _galaxy,
297+ EclipticBase _proposal,
298+ bool _vote)
299+```
57300
58−### `transferFrom`
301+As `_galaxy`, cast a `_vote` on the Ecliptic upgrade `_proposal`.
59302
60−### `createGalaxy`
303+`_vote` is true when in favor of the proposal, false otherwise.
61304
62−### `setTransferProxy`
305+This action may be performed from Bridge.
63306
64−Sets the `transferProxy` for a `Point`. This action may only be performed by the
65−owner of the `Point` or their transfer proxy.
307+#### `castDocumentVote`
66308
67−This action is performed by Bridge when transferring a point from one address to
68−another. This makes transferring into a two-step process in order to reduce the
69−likelihood of accidental transfer.
309+```
310+ function castDocumentVote(uint8 _galaxy, bytes32 _proposal, bool _vote)
311+```
70312
71−Corresponds to `%set-transfer-proxy` on layer 2.
313+As `_galaxy`, cast a `_vote` on the `_proposal`.
72314
73−### `safeTransferFrom`
315+`_vote` is true when in favor of the proposal, false otherwise.
74316
75−### `configureKeys`
317+This action may be performed from Bridge.
76318
77−### `castUpgradeVote`
319+#### `updateUpgradePoll`
78320
79−### `updateUpgradePoll`
321+```
322+ function updateUpgradePoll(EclipticBase _proposal)
323+```
80324
81−### `castDocumentVote`
325+Check whether the `_proposal` has achieved majority, upgrading to it if it has.
326+Any Ethereum address may call this function.
82327
83−### `renounceOwnership`
328+This action eiher occurs as part of a vote that achieves a majority, or must be
329+performed manually. It is not available in Bridge.
84330
85−Renounces ownership of the Ecliptic contract. This leaves the contract with no
86−owner, and thus it would no longer possible to call functions with the
87−`onlyOwner` modifier. This action may only be performed by the owner of
88−Ecliptic.
331+#### `updateDocumentPoll`
89332
90−### `setManagementProxy`
333+```
334+ function updateDocumentPoll(bytes32 _proposal)
335+```
91336
92−Sets the `managementProxy` for a `Point`. This action may only be performed by the
93−owner of the `Point` or their management proxy.
337+Check whether the `_proposal` has achieved majority. Any Ethereum address may
338+call this function.
94339
95−This action may be performed using Bridge.
340+### Contract owner operations
96341
97−Corresponds to `%set-management-proxy` on layer 2.
342+The following functions may only be performed by the owner of the contract.
343+There are only two such functions, one of which is to spawn galaxies. As all
344+galaxies have already been spawned, it is no longer of any use. Thus only
345+`setDnsDomains` is relevant today.
98346
99−### `startUpgradePoll`
347+#### `createGalaxy`
100348
101−### `spawn`
349+```
350+ function createGalaxy(uint8 _galaxy, address _target)
351+```
102352
103−### `setApprovalForAll`
353+Grant `_target` ownership of the `_galaxy` and register it for voting. Galaxies
354+are given by a `uint8`, and since all 256 galaxies have already been spawned,
355+this function has no valid arguments.
104356
105−### `setVotingProxy`
357+#### `setDnsDomains`
106358
107−Sets the `votingProxy` for a `Point`. This action may only be performed by
108−galaxies, by either their owner or their voting proxy.
359+```
360+ function setDnsDomains(string _primary, string _secondary, string _tertiary)
361+```
109362
110−This action may be performed using Bridge.
363+Sets 3 DNS domains by which galaxy IP addresses may be looked up as part of the
364+bootstrap process to get on the network. Currently, all three domains are `urbit.org`.
111365
112−This action does exist on layer 2 as `%set-voting-proxy`, however since galaxies
113−cannot be deposited to layer 2 they cannot set a layer 2 voting proxy.
366+In the future, this function should probably be parameterized as a per-galaxy
367+setting, so that each galaxy may set its own domain.
114368
115−### `setSpawnProxy`
369+## Read functions {#read}
116370
117−Sets the `spawnProxy` for a `Point`. This action may only be performed by stars and
118−galaxies, by either their owner or their spawn proxy.
371+Here we briefly describe each function in the Ecliptic which allows one to read
372+data from the contract. These can be called using
373+[Etherscan](https://etherscan.io/address/ecliptic.eth#readContract).
119374
120−This action may be performed using Bridge.
375+We only document here the read functions specific to Ecliptic and not the
376+standard functions that are part of the ERC-721 or ERC-165 interfaces.
121377
122−Corresponds to `%set-spawn-proxy` on layer 2.
378+#### `depositAddress`
123379
124−### `safeTransferFrom`
380+This returns the deposit address for [layer 2](/docs/azimuth/layer2), which is
381+`0x1111111111111111111111111111111111111111`. Ships sent to this address are
382+controlled on layer 2 instead of via Ecliptic.
125383
126−### `setDnsDomains`
384+#### `canEscapeTo`
127385
128−Sets `dnsDomains`. This may only be done by the owner of the contract. This may
129−not be done using Bridge and has no corresponding action on layer 2.
386+```
387+ function canEscapeTo(uint32 _point, uint32 _sponsor)
388+```
130389
131−### `reject`
390+Returns a `bool` that is true if `_point` could try to escape to `_sponsor`.
132391
133−### `escape`
392+#### `azimuth`
134393
135−Sets `escapeRequested` to `true` and `escapeRequestedTo` to a given `uint32`
136−indexing a `Point`. This action may only be performed by planets and stars, by
137−either the owner of the `Point` or their management proxy.
394+Returns the address of the [Azimuth.eth](/docs/azimuth/azimuth-eth) contract: `0x223c067f8cf28ae173ee5cafea60ca44c335fecb`.
138395
139−This action may be performed in Bridge.
396+#### `claims`
140397
141−Corresponds to `%escape` on layer 2.
398+Returns the address of the
399+[Claims](https://etherscan.io/address/0xe7e7f69b34d7d9bd8d61fb22c33b22708947971a)
400+contract: `0x1df4ea30e0b1359c9692a161c5f30cd1a6b64ebf`.
142401
143−### `adopt`
402+#### `polls`
144403
145−Corresponds to `%adopt` on layer 2.
404+Returns the address of the
405+[Polls](https://etherscan.io/address/0x7fecab617c868bb5996d99d95200d2fa708218e4)
406+contract: `0x7fecab617c868bb5996d99d95200d2fa708218e4`.
146407
147−This action may be performed using Bridge.
408+#### `previousEcliptic`
148409
149−Allows a potential sponsor to accept a `setEscapeRequest` from a potential
150−sponsee. Planets may only be adopted by stars, and stars may only be adopted by
151−galaxies.
410+Returns the address of the previous Ecliptic address.
152411
153−### `cancelEscape`
412+#### `getSpawnLimit`
154413
155−### `transferOwnership`
414+```
415+ function getSpawnLimit(uint32 _point, uint256 _time)
416+```
156417
157−Transfers ownership of the Ecliptic contract to a new owner. This may only be
158−performed by the owner of the contract, and is not available in Bridge or layer 2.
418+Returns a `uint32` that is the total number of children the `_point` is allowed
419+to spawn at `_time`.
159420
421+There is no limit for galaxies. Instead, for most galaxies, all stars have
422+already been spawned and placed into one of the lockup contracts: [Linear Star
423+Release](https://etherscan.io/address/0x86cd9cd0992f04231751e3761de45cecea5d1801)
424+and [Conditional Star
425+Release](https://etherscan.io/address/0x8c241098c3d3498fe1261421633fd57986d74aea).
160426
427+Beginning in 2019, stars may spawn at most 1024 planets. This limit doubles for
428+every subsequent year. However, this limit is not currently implemented on
429+[Layer 2](/docs/azimuth/layer2).
161430