@@ -5,145 +5,63 @@ template = "doc.html"
55aliases = ["/docs/learn/azimuth"]
66+++
77
8−Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum blockchain, used as a platform for _Urbit identities_. You need such an identity to use the Arvo network.
8+Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum
9+blockchain, used as a platform for _Urbit identities_. You need such an identity
10+to use the Arvo network.
911
10−The primary way to interact with Azimuth is through our [Bridge](https://github.com/urbit/bridge) application and the node libraries that it depends on, [azimuth-js](https://github.com/urbit/azimuth-js) and [urbit-key-generation](https://github.com/urbit/urbit-key-generation). Take a look at the source and play around, or see [Getting Started](/getting-started/).
12+The primary way to interact with Azimuth is through
13+[Bridge](https://github.com/urbit/bridge) and the node libraries that it depends
14+on, [azimuth-js](https://github.com/urbit/azimuth-js) and
15+[urbit-key-generation](https://github.com/urbit/urbit-key-generation). Take a
16+look at the source and play around, or see [Getting Started](/getting-started/).
1117
1218## Arvo vs. Azimuth
1319
14−Urbit is a project, not a single computer system. It has multiple components: Arvo, the operating system; and Azimuth, the identity system. Let's compare them.
20+Urbit is a project, not a single computer system. It has multiple components:
21+Arvo, the operating system; and Azimuth, the identity system. Let's compare
22+them.
23+
24+**Arvo** is an operating system that provides the software for a personal
25+server. These personal servers together constitute the peer-to-peer Arvo
26+network. To make this network work on the social level, Arvo is built to work
27+with a system of scarce and immutable identities.
28+
29+**Azimuth** is the public-key infrastructure built to be a system of scarce and
30+immutable identities. It consists of a suite of [smart contracts on the Ethereum
31+blockchain](https://github.com/urbit/azimuth) as well as [several
32+apps](/docs/azimuth/l2-flow) run locally on your urbit. Togeter, they determine
33+which Ethereum addresses own which Urbit ID's as well as the public keys needed
34+to communicate with those ID's. All identity-related operations, such as
35+transfers, are governed by Azimuth. Azimuth isn't built strictly for Arvo -- the
36+smart contracts on Ethereum are sufficient to be used as a generalized identity
37+system for other projects.
38+
39+These otherwise-parallel systems meet when you want to connect to the Arvo
40+network. Your Arvo personal server, called your _ship_, needs to be able to
41+prove cryptographically that it is who it says it is. This proof comes in the
42+form of a keyfile, derived from your identity, that you use to start your ship.
43+
44+A metaphor might help illustrate the relationship between these two systems: the
45+Arvo network is the neighborhood that you live in; Azimuth is the bank vault
46+that stores the deed to your house.
47+
48+## Naive rollups
49+
50+In 2021, Tlon introduced a new system to Azimuth intended to reduce gas costs
51+for working with Urbit ID and friction associated with using cryptocurrency in
52+general called **naive rollups**, often referred to as **layer 2**. This system
53+allows batches of Azimuth transactions to be submitted together as a single
54+transaction using an urbit node known as a "roller". The PKI state transitions
55+resulting from these transactions are computed locally by your urbit rather than
56+by the [Ethereum Virtual Machine](https://ethereum.org/en/developers/docs/evm/).
57+
58+Due to the dramatically reduced cost, Tlon offers their own roller that is free
59+for ordinary public use. This enables new users to get started with a permanent
60+Azimuth identity without any prior knowledge of Ethereum, cryptocurrency, or
61+blockchains.
62+
63+A casual overview of the naive rollups system can be found on the
64+[blog](/blog/rollups) as well as the Pilot's Manual (insert link). Developers
65+are encouraged to read our Layer 2 documentation, starting with the [Layer 2
66+Overview](/docs/azimuth/layer2).
1567
16−**Arvo** is an operating system that provides the software for a personal server. These personal servers together constitute the peer-to-peer Arvo network. To make this network work on the social level, Arvo is built to work with a system of scarce and immutable identities.
17−
18−**Azimuth** is the public-key infrastructure built to be such a system. A suite of smart-contracts on the Ethereum blockchain, Azimuth determines which Ethereum addresses own which Azimuth identities, called _Urbit identities_, or just _identities_. All identity-related operations, such as transfers, are governed at this layer. But Azimuth isn't built strictly for Arvo -- it could be used as a generalized identity system for other projects.
19−
20−These otherwise-parallel systems meet when you want to connect to the Arvo network. Your Arvo personal server, called your _ship_, needs to be able to prove cryptographically that it is who it says it is. This proof comes in the form of a keyfile, derived from your identity, that you use to start your ship.
21−
22−A metaphor might help illustrate the relationship between these two systems: the Arvo network is the neighborhood that you live in; Azimuth is the bank vault that stores the deed to your house.
23−
24−## The Urbit HD Wallet
25−
26−Owners of Urbit identities need safeguards that allow for the use of Urbit without jeopardizing cryptographic ownership of their assets. Toward this end, we created the **Urbit Hierarchical Deterministic (HD) Wallet** for the storage of identities. The Urbit HD Wallet is not one key-pair, but a system of related key-pairs that each have distinct powers, from setting networking keys for communicating in the Arvo network to transferring ownership of identities.
27−
28−The Urbit HD Wallet's derivation paths have a hierarchical structure, so that
29−keys with different powers can be physically separated. A "master ticket" can
30−[re-derive the entire wallet](#hd-wallet-generation) in case of loss. The
31−encryption and authentication keys that identities ships use to sign messages
32−within the network are also derived from the wallet.
33−
34−Another HD wallet option you may wish to utilize to store your Urbit are hardware
35−wallets such as Trezor or Ledger. We compare this method to the Urbit HD wallet
36−[below](#hardware-hd-wallet).
37−
38−Urbit HD wallets are composed of the following items, which are each assigned to their own individual Ethereum key-pairs.
39−
40−### Master Ticket
41−
42−Think of your master ticket like a very high-value password. The master ticket is the secret code from which all of your other keys are derived. Technically, your master ticket is seed entropy. You should never share it with anyone, and store it very securely. This ticket can derive all of your other keys: your ownership key and all of the related proxies.
43−
44−### Ownership Address
45−
46−An ownership address has all rights over the assets deeded to it. These rights are on-chain actions described and implemented in [Ecliptic](/docs/glossary/ecliptic), Azimuth's suite of governing smart-contracts.
47−
48−### Proxies
49−
50−Proxy addresses allow you to execute non-ownership related actions like spawning child identities, voting, and setting networking keys without jeopardizing the keys you've designated with ownership rights. Setting proxy rights is optional, but it is recommended for on-chain actions you will execute more frequently.
51−
52−- **Management Proxy**
53−
54− Can configure or set Arvo networking keys and conduct sponsorship related
55− operations.
56−
57−- **Voting Proxy**
58−
59− Galaxies only. Galaxies are the part of the [Galactic Senate](/docs/glossary/senate), and this means
60− they can cast votes on new proposals including changes to Ecliptic.
61−
62−- **Spawn Proxy**
63−
64− For stars and galaxies only. Can create new child identities.
65−
66−### HD wallet generation
67−
68−Your Urbit HD wallet is generated from a `@q` seed called `T`, which looks
69−something like `~sampel-ticket-bucbel-sipnem`. This is the string known as your
70−"Master Ticket" that you input into Bridge to sign in. This is put through a
71−series of algorithms that ultimately generate your keys and the Ethereum addresses at which they are stored.
72−
73−
74−
75−First, your `@q` is converted into a numeric value `E` as an intermediary step
76−by adding [salt](<https://en.wikipedia.org/wiki/Salt_(cryptography)>). Then by
77−adding additional salts, `E` is converted into a set of BIP39 seed phrases -
78−these are 24 word mnemonic sequences used to generate Ethereum wallets. You end up
79−with one seed phrase for each proxy associated with your ship, and these seed
80−phrases are then used to generate Ethereum wallets.
81−
82−One of the wallets will store your Azimuth point, an [ERC-721](#erc-721) token,
83−which will be known as your ownership address. Bridge then automatically uses
84−your ownership address to assign the other proxies to the other wallets
85−generated.
86−
87−### ERC-721
88−
89−Most Ethereum tokens use the ERC-20 standard for smart contracts. Urbit identities
90−are, however, essentially different from most Ethereum tokens, due to identities not
91−being fungible. Since any two stars will handle social-networking realities in a
92−different way, they will carry a different reputation.
93−
94−The ERC-721 standard, having been made specifically to provide a smart-contract
95−interface for non-fungible assets, serves our needs well. This is the standard
96−that we use for deeding Urbit identities.
97−
98−Identities, and all of their blockchain operations, are governed by Ecliptic. Ecliptic is an Ethereum smart-contract that governs identity state and the
99−ownership, spawn, management, and voting rights affiliated with your identities.
100−
101−For the technical implementation details, take a look at Azimuth's
102−[Github repository](https://github.com/urbit/azimuth).
103−
104−## Hardware HD wallet
105−
106−You may also store your Urbit using a hardware HD wallet such as a Trezor or
107−Ledger. This option is used instead of a master ticket - it is a totally
108−separate process from that outlined above. How hardware wallets work are
109−outside of the scope of this document, but here we explain how you may utilize
110−your hardware wallet in a similar fashion to the Urbit HD wallet.
111−
112−A hardware HD wallet is generated from a seed phrase that should be thought of
113−as analogous to the `@q` `T` used to generate the Urbit HD wallet in the above
114−diagram. This seed phrase is a human readable sequence of words that may be used
115−to generate private keys to a near-limitless number of wallets created by adding
116−salt. Some hardware
117−wallets also allow an additional passphrase to go into the generation of these
118−wallets. The seed phrase and passphrase should be considered equal in
119−value to the master ticket `T`- never share these with anyone!
120−
121−In order to use your hardware wallet as your Urbit wallet, you first need to
122−generate a set of addresses on which you would like to store your Azimuth point
123−and proxies. Consult your wallet vendor on how to do this. Then login to Bridge
124−using your current method (likely a master ticket) and transfer ownership to the
125−wallet address you generated on your hardware wallet for ownership.
126−
127−Next, login to Bridge using your hardware wallet. While Bridge supports Trezor
128−and Ledger natively, this may require using Metamask as an intermediary anyways,
129−depending on which firmware you are running. Then [accept the
130−transfer](/using/id/using-bridge#accept-your-transfer). Your Azimuth
131−point is now stored on your hardware wallet.
132−
133−To finish the process, use Bridge to set your management, voting, and spawn
134−proxies to the other addresses you generated as applicable. You are now using
135−your hardware HD wallet in an analogous fashion to the Urbit HD wallet.
136−
137−## Heightened security practices
138−
139−A common security pattern is to have "hot" and "cold" wallets. For higher value
140−points such as stars and galaxies, you may consider having your ownership
141−address live on a "cold" wallet that never touches an
142−internet-connected computer, and the various proxies on a "hot" wallet that is
143−permitted to connect to internet-connected devices. This could be accomplished
144−with multiple hardware wallets, a combination of paper and hardware wallet, a
145−hardware cold wallet and Metamask hot wallet, etc.
146−
147−One tool useful for this setup is `claz`, located at `app/claz.hoon`. `claz` is
148−used for making and signing Bridge transactions from an offline computer. A
149−guide to using `claz` is forthcoming.