@@ -0,0 +1,251 @@
2+title = "Smart Contracts"
5+aliases = ["/docs/learn/azimuth"]
8+This document summarizes the Ethereum smart contracts that
9+govern Azimuth, as well as presents some raw data about them.
11+Azimuth consists of the following smart contracts:
13+ - [Azimuth.eth](https://etherscan.io/address/azimuth.eth)
14+ `0x223c067f8cf28ae173ee5cafea60ca44c335fecb`: contains all on-chain state for
15+ Azimuth. Most notably, ownership and public keys. Can't be modified directly,
16+ you must use the Ecliptic.
17+ - [Ecliptic.eth](https://etherscan.io/address/ecliptic.eth):
18+ `0x9ef27de616154FF8B38893C59522b69c7Ba8A81c ` is used as an interface for
19+ interacting with your points on-chain. Allows you to configure keys, transfer
21+ - [Polls](https://etherscan.io/address/0x7fecab617c868bb5996d99d95200d2fa708218e4):
22+ `0x7fecab617c868bb5996d99d95200d2fa708218e4` registers votes by the Galactic
23+ Senate on proposals. These can be either static documents or Ecliptic
26+ Release](https://etherscan.io/address/0x86cd9cd0992f04231751e3761de45cecea5d1801):
27+ facilitates the release of blocks of stars to their owners over a period of
30+ Release](https://etherscan.io/address/0x8c241098c3d3498fe1261421633fd57986d74aea):
31+ `0x8c241098c3d3498fe1261421633fd57986d74aea` facilitates the release of
32+ blocks of stars to their owners based on milestones.
33+ - [Claims](https://etherscan.io/address/0xe7e7f69b34d7d9bd8d61fb22c33b22708947971a):
34+ `0xe7e7f69b34d7d9bd8d61fb22c33b22708947971a` allows point owners to make
35+ claims about (for example) their identity, and associate that with their
37+ - [Censures](https://etherscan.io/address/0x325f68d32bdee6ed86e7235ff2480e2a433d6189):
38+ `0x325f68d32bdee6ed86e7235ff2480e2a433d6189` simple reputation management,
39+ allowing galaxies and stars to flag points for negative reputation.
41+ Sending](https://etherscan.io/address/0xf6b461fe1ad4bd2ce25b23fe0aff2ac19b3dfa76):
42+ enables network-effect like distributing of planets.
44+ We give a more in-depth look at a few of them below.
46+## [Azimuth.eth](https://etherscan.io/address/azimuth.eth)
48+This contract is used for storing all data related to Azimuth points and their
49+ownership, and should be considered to be the ledger for Azimuth. This contract
50+is only a data store - it only contains the bare minimum of business logic. See
51+[the Ecliptic](#ecliptic) for the contract containing the business logic for
52+this ledger. `Azimuth.eth` cannot be modified directly by [galaxy
53+vote](/docs/glossary/upgrade) - they are only eligible to modify the Ecliptic.
55+Urbit ID's are formalized as [ERC-721 non-fungible
56+tokens](https://eips.ethereum.org/EIPS/eip-721). The
57+data associated to a given Urbit ID is known as a `point`. A `point` is the
63+ // encryptionKey: (curve25519) encryption public key, or 0 for none
65+ bytes32 encryptionKey;
67+ // authenticationKey: (ed25519) authentication public key, or 0 for none
69+ bytes32 authenticationKey;
71+ // spawned: for stars and galaxies, all :active children
75+ // hasSponsor: true if the sponsor still supports the point
79+ // active: whether point can be linked
81+ // false: point belongs to prefix, cannot be configured or linked
82+ // true: point no longer belongs to prefix, can be configured and linked
86+ // escapeRequested: true if the point has requested to change sponsors
88+ bool escapeRequested;
90+ // sponsor: the point that supports this one on the network, or,
91+ // if :hasSponsor is false, the last point that supported it.
92+ // (by default, the point's half-width prefix)
96+ // escapeRequestedTo: if :escapeRequested is true, new sponsor requested
98+ uint32 escapeRequestedTo;
100+ // cryptoSuiteVersion: version of the crypto suite used for the pubkeys
102+ uint32 cryptoSuiteVersion;
104+ // keyRevisionNumber: incremented every time the public keys change
106+ uint32 keyRevisionNumber;
108+ // continuityNumber: incremented to indicate network-side state loss
110+ uint32 continuityNumber;
114+We remark that `uint32` is a 32-bit integer, and that 32 bits is the size of the
115+Urbit address space. Thus each ID is ultimately a 32-bit number, which one can
116+check in dojo with `\`@\`~sampel-palnet` or `\`@ub\`~sampel-palnet` to see it
117+written in binary. Thus `spawned`, `sponsor`, and `escapeRequestedTo` are
118+`uint32`'s referring to a particular Urbit ID.
120+The owner of an Urbit ID may also set several [proxies](/docs/using/id/proxies)
121+by modifying their `Deed`:
126+ // owner: address that owns this point
130+ // managementProxy: 0, or another address with the right to perform
131+ // low-impact, managerial operations on this point
133+ address managementProxy;
135+ // spawnProxy: 0, or another address with the right to spawn children
140+ // votingProxy: 0, or another address with the right to vote as this point
142+ address votingProxy;
144+ // transferProxy: 0, or another address with the right to transfer
145+ // ownership of this point
147+ address transferProxy;
151+Finally, each owner of an Urbit ID may set for itself a number of `operators`,
152+as defined and required by the ERC-721 standard. These are for third party
153+brokers/wallets/auctioneers/etc such as [OpenSea](http://opensea.io).
155+The ledger also contains some other state—domain names by which the IP
156+address of a galaxy may be looked up, e.g. `zod.urbit.org` resolves to
157+`35.247.119.159`. This is used for bootstrapping the network from DNS. Three
158+domains may be listed here, but as of today they are all `urbit.org`. This may
159+only be updated by the owner of Ecliptic, but arguably each galaxy ought to be
160+able to set its own domain name and so we do not expect this to remain the case
163+All data in this ledger is stored and processed locally on your ship by the
164+[`%azimuth` Gall agent](/docs/azimuth/l2-flow#azimuth), including [layer
165+2](/docs/azimuth/layer2) data. Because state transitions resulting from layer 2
166+transactions are not included in this ledger, in general the local store will
167+differ from what is kept in Azimuth.eth.
169+## [Ecliptic.eth](https://etherscan.io/address/ecliptic.eth) {#ecliptic}
171+Ecliptic.eth holds the business logic for the ledger kept by Azimuth.eth. It may
172+be modified by [galaxy vote](/docs/glossary/upgrade). This determines things
173+such as what the various proxies are capable of, how keys are changed, or
174+verifying that a request is valid.
176+You can read about [Urbit's first
177+upgrade](https://github.com/urbit/azimuth/pull/35) to Ecliptic, which occurred
178+in the summer of 2021, [here](https://urbit.org/blog/first-contract). The
179+[second](https://github.com/urbit/azimuth/pull/43) occurred later in the year
180+and consisted of several small modifications to ready the PKI for the
181+introduction of naive rollups.
183+There are currently 17 events which may be called in Ecliptic, which we explain
184+in the following. Most of these have a corresponding [layer 2
185+action](/docs/azimuth/l2-actions), and most of them may be performed using
186+[Bridge](/using/id/using-bridge). We describe how this is so where applicable.
190+Corresponds to `%adopt` on layer 2.
192+This action may be performed using Bridge.
194+Allows a potential sponsor to accept a `setEscapeRequest` from a potential
195+sponsee. Planets may only be adopted by stars, and stars may only be adopted by
200+Sets the spawn proxy for a point.
202+This action may be performed using Bridge.
204+Corresponds to `%set-spawn-proxy` on layer 2.
206+### `setTransferProxy`
208+Sets the transfer proxy for a point.
210+This action is performed by Bridge when transferring a point from one address to
211+another. This makes transferring into a two-step process in order to reduce the
212+likelihood of accidental transfer.
214+Corresponds to `%set-transfer-proxy` on layer 2.
216+### `renounceOwnership`
218+Renounces ownership of the Ecliptic contract. This leaves the contract with no
219+owner, and thus it would no longer possible to call functions with the
220+`onlyOwner` modifier. This action may only be performed by the owner of
225+### `setManagementProxy`
229+### `setEscapeRequest`
237+### `registerSpawned`
243+### `transferOwnership`
245+Transfers ownership of the Ecliptic contract to a new owner. This may only be
246+performed by the owner of the contract, and is not available in Bridge or layer 2.
248+### `incrementContinuityNumber`