@@ -10,6 +10,18 @@ vote](/docs/glossary/upgrade). This determines things such as what the various
10proxies are capable of, how keys are changed, or verifying that a request is
10proxies are capable of, how keys are changed, or verifying that a request is
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
13You can read about [Urbit's first
25You can read about [Urbit's first
14upgrade](https://github.com/urbit/azimuth/pull/35) to Ecliptic, which occurred
26upgrade](https://github.com/urbit/azimuth/pull/35) to Ecliptic, which occurred
15in the summer of 2021, [here](https://urbit.org/blog/first-contract). The
27in 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
17and consisted of several small modifications to ready the PKI for the
29and consisted of several small modifications to ready the PKI for the
18introduction of naive rollups.
30introduction of naive rollups.
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
20There are currently [28 functions](#write) which may be called to write to
37There are currently [28 functions](#write) which may be called to write to
21the Ecliptic, and [17 functions](#read) to read data from the Ecliptic. Many of these
38the Ecliptic, and [17 functions](#read) to read data from the Ecliptic. Many of these
22have a corresponding [layer 2 action](/docs/azimuth/l2-actions), and/or can be
39have 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
25## Write functions {#write}
43## Write functions {#write}
@@ -29,133 +47,384 @@ data to Ethereum. These can be called using
29[Etherscan](https://etherscan.io/address/ecliptic.eth#writeContract), but
47[Etherscan](https://etherscan.io/address/ecliptic.eth#writeContract), but
30the most common functions may be called from within Bridge.
48the most common functions may be called from within Bridge.
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.
34−#### Accepts
53+### `Point`s interface
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.
38−#### Action
59+#### `configureKeys`
40−Starts a [document poll](/docs/glossary/docvote). Galaxies only. `_galaxy` is
61+```
41−the calling galaxy, and `_proposal` is a keccak-256 hash of any arbitrary
62+ function configureKeys(uint32 _point,
42−document or string of text.
63+ bytes32 _encryptionKey,
64+ bytes32 _authenticationKey,
65+ uint32 _cryptoSuiteVersion,
69+Configure `_point` with network public keys `_encryptionKey`, `_authenticationKey`,
70+and corresponding `_cryptoSuiteVersion`, incrementing the `Point`'s continuity
73+Corresponds to the layer 2 `%configure-keys` action.
78+ function spawn(uint32 _point, address _target)
81+Spawn `_point`, then either give, or allow `_target` to take, ownership of `_point`.
83+If `_target` is the `:msg.sender`, `_target` owns the `_point` right away.
84+otherwise, `_target` becomes the transfer proxy of `_point`.
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
92+Corresponds to the layer 2 `%spawn` action.
97+ function transferPoint(uint32 _point, address _target, bool _reset)
100+Transfer `_point` to `_target`, clearing all permissions
101+data and keys if `_reset` is true
103+Note: the `_reset` flag is useful when transferring the point to
104+a recipient who doesn't trust the previous owner.
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.
111+Corresponds to the layer 2 `%transfer-point` action.
116+ function escape(uint32 _point, uint32 _sponsor)
119+Request escape as `_point` to `_sponsor`.
121+If an escape request is already active, this overwrites the existing request.
124+ - `:msg.sender` must be the owner or manager of `_point`,
125+ - `_point` must be able to escape to `_sponsor` as per to `canEscapeTo()`
127+ Corresponds to the layer 2 `%escape` action.
132+ function cancelEscape(uint32 _point)
135+Cancel the currently set escape for `_point`.
137+Corresponds to the layer 2 `%cancel-escape` action.
142+ function adopt(uint32 _point)
145+As the relevant sponsor, accept the `_point`.
148+ - `:msg.sender` must be the owner or management proxy
149+ of `_point`'s requested sponsor
151+Corresponds to the layer 2 `%adopt` action.
156+ function reject(uint32 _point)
159+As the relevant sponsor, deny the `_point`'s `adopt` request.
162+ - `:msg.sender` must be the owner or management proxy
163+ of `_point`'s requested sponsor
165+Corresponds to the layer 2 `%reject` action.
170+ function detach(uint32 _point)
44−### `detach`
173+As the `_sponsor`, stop sponsoring the `_point`.
46−A sponsor may call this on a sponsee to set `hasSponsor` for their `Point` to
175+Requirements:
47−`false`.
176+ - `:msg.sender` must be the owner or management proxy
177+ of `_point`'s current sponsor
179+Corresponds to the layer 2 `%detach` action.
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
50−### `approve`
185+### Proxy management {#proxies}
187+These functions are used to manage the various
188+[proxies](/docs/using/id/proxies). All of these actions may be performed from Bridge.
190+#### `setManagementProxy`
193+ function setManagementProxy(uint32 _point, address _manager)
196+Configure the management proxy for `_point`.
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.
203+ - `:msg.sender` must be either `_point`'s current owner or the management proxy.
205+Corresponds to the layer 2 `%set-management-proxy` action.
210+ function setSpawnProxy(uint16 _prefix, address _spawnProxy)
213+Give `_spawnProxy` the right to spawn points with the prefix `_prefix` using the
217+ - `:msg.sender` must be either `_point`'s current owner or the spawn proxy.
219+Corresponds to the layer 2 `%set-spawn-proxy` action.
221+#### `setVotingProxy`
224+ function setVotingProxy(uint8 _galaxy, address _voter)
227+Configure the voting proxy for `_galaxy`.
229+The voting proxy is allowed to start polls and cast votes on the point's behalf.
232+ - `:msg.sender` must be either `_point`'s current owner or the voting proxy.
234+There is no corresponding layer 2 action since voting must occur on layer 1.
236+#### `setTransferProxy`
239+ function setTransferProxy(uint32 _point, address _transferProxy)
242+Give `_transferProxy` the right to transfer `_point`.
245+ - `:msg.sender` must be either `_point`'s current owner, an operator for the
246+ current owner, or the transfer proxy.
248+Corresponds to the layer 2 `%set-transfer-proxy` action.
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.
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.
264+#### `startUpgradePoll`
267+ function startUpgradePoll(uint8 _galaxy, EclipticBase _proposal)
270+As `_galaxy`, start a poll for the Ecliptic upgrade `_proposal`.
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.
277+This action must be performed manually - it is not available in Bridge.
279+#### `startDocumentPoll`
282+ function startDocumentPoll(uint8 _galaxy, bytes32 _proposal)
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.
288+The `_proposal` argument is the keccak-256 hash of any arbitrary
289+document or string of text.
52−### `updateDocumentPoll`
291+This action must be performed manually - it is not available in Bridge.
54−### `onUpgrade`
293+#### `castUpgradeVote`
56−### `transferPoint`
295+```
296+ function castUpgradeVote(uint8 _galaxy,
297+ EclipticBase _proposal,
58−### `transferFrom`
301+As `_galaxy`, cast a `_vote` on the Ecliptic upgrade `_proposal`.
60−### `createGalaxy`
303+`_vote` is true when in favor of the proposal, false otherwise.
62−### `setTransferProxy`
305+This action may be performed from Bridge.
64−Sets the `transferProxy` for a `Point`. This action may only be performed by the
307+#### `castDocumentVote`
65−owner of the `Point` or their transfer proxy.
67−This action is performed by Bridge when transferring a point from one address to
309+```
68−another. This makes transferring into a two-step process in order to reduce the
310+ function castDocumentVote(uint8 _galaxy, bytes32 _proposal, bool _vote)
69−likelihood of accidental transfer.
311+```
71−Corresponds to `%set-transfer-proxy` on layer 2.
313+As `_galaxy`, cast a `_vote` on the `_proposal`.
73−### `safeTransferFrom`
315+`_vote` is true when in favor of the proposal, false otherwise.
75−### `configureKeys`
317+This action may be performed from Bridge.
77−### `castUpgradeVote`
319+#### `updateUpgradePoll`
79−### `updateUpgradePoll`
322+ function updateUpgradePoll(EclipticBase _proposal)
81−### `castDocumentVote`
325+Check whether the `_proposal` has achieved majority, upgrading to it if it has.
326+Any Ethereum address may call this function.
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.
85−Renounces ownership of the Ecliptic contract. This leaves the contract with no
331+#### `updateDocumentPoll`
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
90−### `setManagementProxy`
333+```
334+ function updateDocumentPoll(bytes32 _proposal)
92−Sets the `managementProxy` for a `Point`. This action may only be performed by the
337+Check whether the `_proposal` has achieved majority. Any Ethereum address may
93−owner of the `Point` or their management proxy.
338+call this function.
95−This action may be performed using Bridge.
340+### Contract owner operations
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.
99−### `startUpgradePoll`
347+#### `createGalaxy`
350+ function createGalaxy(uint8 _galaxy, address _target)
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.
105−### `setVotingProxy`
357+#### `setDnsDomains`
107−Sets the `votingProxy` for a `Point`. This action may only be performed by
359+```
108−galaxies, by either their owner or their voting proxy.
360+ function setDnsDomains(string _primary, string _secondary, string _tertiary)
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`.
112−This action does exist on layer 2 as `%set-voting-proxy`, however since galaxies
366+In the future, this function should probably be parameterized as a per-galaxy
113−cannot be deposited to layer 2 they cannot set a layer 2 voting proxy.
367+setting, so that each galaxy may set its own domain.
115−### `setSpawnProxy`
369+## Read functions {#read}
117−Sets the `spawnProxy` for a `Point`. This action may only be performed by stars and
371+Here we briefly describe each function in the Ecliptic which allows one to read
118−galaxies, by either their owner or their spawn proxy.
372+data from the contract. These can be called using
373+[Etherscan](https://etherscan.io/address/ecliptic.eth#readContract).
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.
122−Corresponds to `%set-spawn-proxy` on layer 2.
378+#### `depositAddress`
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.
126−### `setDnsDomains`
384+#### `canEscapeTo`
128−Sets `dnsDomains`. This may only be done by the owner of the contract. This may
386+```
129−not be done using Bridge and has no corresponding action on layer 2.
387+ function canEscapeTo(uint32 _point, uint32 _sponsor)
131−### `reject`
390+Returns a `bool` that is true if `_point` could try to escape to `_sponsor`.
133−### `escape`
392+#### `azimuth`
135−Sets `escapeRequested` to `true` and `escapeRequestedTo` to a given `uint32`
394+Returns the address of the [Azimuth.eth](/docs/azimuth/azimuth-eth) contract: `0x223c067f8cf28ae173ee5cafea60ca44c335fecb`.
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.
139−This action may be performed in Bridge.
396+#### `claims`
141−Corresponds to `%escape` on layer 2.
398+Returns the address of the
399+[Claims](https://etherscan.io/address/0xe7e7f69b34d7d9bd8d61fb22c33b22708947971a)
400+contract: `0x1df4ea30e0b1359c9692a161c5f30cd1a6b64ebf`.
143−### `adopt`
402+#### `polls`
145−Corresponds to `%adopt` on layer 2.
404+Returns the address of the
405+[Polls](https://etherscan.io/address/0x7fecab617c868bb5996d99d95200d2fa708218e4)
406+contract: `0x7fecab617c868bb5996d99d95200d2fa708218e4`.
147−This action may be performed using Bridge.
408+#### `previousEcliptic`
149−Allows a potential sponsor to accept a `setEscapeRequest` from a potential
410+Returns the address of the previous Ecliptic address.
150−sponsee. Planets may only be adopted by stars, and stars may only be adopted by
153−### `cancelEscape`
412+#### `getSpawnLimit`
155−### `transferOwnership`
414+```
415+ function getSpawnLimit(uint32 _point, uint256 _time)
157−Transfers ownership of the Ecliptic contract to a new owner. This may only be
418+Returns a `uint32` that is the total number of children the `_point` is allowed
158−performed by the owner of the contract, and is not available in Bridge or layer 2.
419+to spawn at `_time`.
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).
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).