@@ -0,0 +1,251 @@
1++++
2+title = "Smart Contracts"
3+weight = 4
4+template = "doc.html"
5+aliases = ["/docs/learn/azimuth"]
6++++
7+
8+This document summarizes the Ethereum smart contracts that
9+govern Azimuth, as well as presents some raw data about them.
10+
11+Azimuth consists of the following smart contracts:
12+
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
20+ ownership, etc.
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
24+ upgrades.
25+ - [Linear Star
26+ Release](https://etherscan.io/address/0x86cd9cd0992f04231751e3761de45cecea5d1801):
27+ facilitates the release of blocks of stars to their owners over a period of
28+ time.
29+ - [Conditional Star
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
36+ point.
37+ - [Censures](https://etherscan.io/address/0x325f68d32bdee6ed86e7235ff2480e2a433d6189):
38+ `0x325f68d32bdee6ed86e7235ff2480e2a433d6189` simple reputation management,
39+ allowing galaxies and stars to flag points for negative reputation.
40+ - [Delegated
41+ Sending](https://etherscan.io/address/0xf6b461fe1ad4bd2ce25b23fe0aff2ac19b3dfa76):
42+ enables network-effect like distributing of planets.
43+
44+ We give a more in-depth look at a few of them below.
45+
46+## [Azimuth.eth](https://etherscan.io/address/azimuth.eth)
47+
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.
54+
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
58+following `struct`:
59+
60+```
61+ struct Point
62+ {
63+ // encryptionKey: (curve25519) encryption public key, or 0 for none
64+ //
65+ bytes32 encryptionKey;
66+ //
67+ // authenticationKey: (ed25519) authentication public key, or 0 for none
68+ //
69+ bytes32 authenticationKey;
70+ //
71+ // spawned: for stars and galaxies, all :active children
72+ //
73+ uint32[] spawned;
74+ //
75+ // hasSponsor: true if the sponsor still supports the point
76+ //
77+ bool hasSponsor;
78+
79+ // active: whether point can be linked
80+ //
81+ // false: point belongs to prefix, cannot be configured or linked
82+ // true: point no longer belongs to prefix, can be configured and linked
83+ //
84+ bool active;
85+
86+ // escapeRequested: true if the point has requested to change sponsors
87+ //
88+ bool escapeRequested;
89+
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)
93+ //
94+ uint32 sponsor;
95+
96+ // escapeRequestedTo: if :escapeRequested is true, new sponsor requested
97+ //
98+ uint32 escapeRequestedTo;
99+
100+ // cryptoSuiteVersion: version of the crypto suite used for the pubkeys
101+ //
102+ uint32 cryptoSuiteVersion;
103+
104+ // keyRevisionNumber: incremented every time the public keys change
105+ //
106+ uint32 keyRevisionNumber;
107+
108+ // continuityNumber: incremented to indicate network-side state loss
109+ //
110+ uint32 continuityNumber;
111+ }
112+```
113+
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.
119+
120+The owner of an Urbit ID may also set several [proxies](/docs/using/id/proxies)
121+by modifying their `Deed`:
122+
123+```
124+struct Deed
125+ {
126+ // owner: address that owns this point
127+ //
128+ address owner;
129+
130+ // managementProxy: 0, or another address with the right to perform
131+ // low-impact, managerial operations on this point
132+ //
133+ address managementProxy;
134+
135+ // spawnProxy: 0, or another address with the right to spawn children
136+ // of this point
137+ //
138+ address spawnProxy;
139+
140+ // votingProxy: 0, or another address with the right to vote as this point
141+ //
142+ address votingProxy;
143+
144+ // transferProxy: 0, or another address with the right to transfer
145+ // ownership of this point
146+ //
147+ address transferProxy;
148+ }
149+```
150+
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).
154+
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
161+forever.
162+
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.
168+
169+## [Ecliptic.eth](https://etherscan.io/address/ecliptic.eth) {#ecliptic}
170+
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.
175+
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.
182+
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.
187+
188+### `doEscape`
189+
190+Corresponds to `%adopt` on layer 2.
191+
192+This action may be performed using Bridge.
193+
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
196+galaxies.
197+
198+### `setSpawnProxy`
199+
200+Sets the spawn proxy for a point.
201+
202+This action may be performed using Bridge.
203+
204+Corresponds to `%set-spawn-proxy` on layer 2.
205+
206+### `setTransferProxy`
207+
208+Sets the transfer proxy for a point.
209+
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.
213+
214+Corresponds to `%set-transfer-proxy` on layer 2.
215+
216+### `renounceOwnership`
217+
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
221+Ecliptic,
222+
223+### `activatePoint`
224+
225+### `setManagementProxy`
226+
227+### `setVotingProxy`
228+
229+### `setEscapeRequest`
230+
231+### `setDnsDomains`
232+
233+### `loseSponsor`
234+
235+### `setOperator`
236+
237+### `registerSpawned`
238+
239+### `cancelEscape`
240+
241+### `setOwner`
242+
243+### `transferOwnership`
244+
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.
247+
248+### `incrementContinuityNumber`
249+
250+### `setKeys`
251+