@@ -24,7 +24,15 @@ A metaphor might help illustrate the relationship between these two systems: the
25Owners 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.
25Owners 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−The Urbit HD Wallet's derivation paths have a hierarchical structure, so that keys with different powers can be physically separated. A \"master ticket" can re-derive the entire wallet in case of loss. The encryption and authentication keys that identities ships use to sign messages within the network are also derived from the wallet.
27+The Urbit HD Wallet's derivation paths have a hierarchical structure, so that
28+keys with different powers can be physically separated. A "master ticket" can
29+[re-derive the entire wallet](#hd-wallet-generation) in case of loss. The
30+encryption and authentication keys that identities ships use to sign messages
31+within the network are also derived from the wallet.
33+Another HD wallet option you may wish to utilize to store your Urbit are hardware
34+wallets such as Trezor or Ledger. We compare this method to the Urbit HD wallet
35+[below](#hardware-hd-wallet).
29Urbit HD wallets are composed of the following items, which are each assigned to their own individual Ethereum key-pairs.
37Urbit HD wallets are composed of the following items, which are each assigned to their own individual Ethereum key-pairs.
@@ -54,8 +62,28 @@ Proxy addresses allow you to execute non-ownership related actions like spawning
55 For stars and galaxies only. Can create new child identities.
63 For stars and galaxies only. Can create new child identities.
65+### HD wallet generation
67+Your Urbit HD wallet is generated from a `@q` seed called `T`, which looks
68+something like `~sampel-ticket-bucbel-sipnem`. This is the string known as your
69+"Master Ticket" that you input into Bridge to sign in. This is put through a
70+series of algorithms that ultimately generate your keys and the Ethereum addresses at which they are stored.
57
72
74+First, your `@q` is converted into a numeric value `E` as an intermediary step
75+by adding [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)). Then by
76+adding additional salts, `E` is converted into a set of BIP39 seed phrases -
77+these are 24 word mnemonic sequences used to generate Ethereum wallets. You end up
78+with one seed phrase for each proxy associated with your ship, and these seed
79+phrases are then used to generate Ethereum wallets.
81+One of the wallets will store your Azimuth point, an [ERC-721](#erc-721) token,
82+which will be known as your ownership address. Bridge then automatically uses
83+your ownership address to assign the other proxies to the other wallets
60Most Ethereum tokens use the ERC-20 standard for smart contracts. Urbit identities
88Most Ethereum tokens use the ERC-20 standard for smart contracts. Urbit identities
61are, however, essentially different from most Ethereum tokens, due to identities not
89are, however, essentially different from most Ethereum tokens, due to identities not
@@ -67,9 +95,56 @@ The ERC-721 standard, having been made specifically to provide a smart-contract
67interface for non-fungible assets, serves our needs well. This is the standard
95interface for non-fungible assets, serves our needs well. This is the standard
68that we use for deeding Urbit identities.
96that we use for deeding Urbit identities.
70−identities, and all of their blockchain operations, are governed by the Ecliptic.
98+Identities, and all of their blockchain operations, are governed by the Ecliptic.
71The Ecliptic is an Ethereum smart-contract that governs identity state and the
99The Ecliptic is an Ethereum smart-contract that governs identity state and the
72ownership, spawn, management, and voting rights affiliated with your identities.
100ownership, spawn, management, and voting rights affiliated with your identities.
74For the technical implementation details, take a look at Azimuth's
102For the technical implementation details, take a look at Azimuth's
75[Github repository](https://github.com/urbit/azimuth).
103[Github repository](https://github.com/urbit/azimuth).
105+## Hardware HD wallet
107+You may also store your Urbit using a hardware HD wallet such as a Trezor or
108+Ledger. This option is used instead of a master ticket - it is a totally
109+separate process from that outlined above. How hardware wallets work are
110+outside of the scope of this document, but here we explain how you may utilize
111+your hardware wallet in a similar fashion to the Urbit HD wallet.
113+A hardware HD wallet is generated from a seed phrase that should be thought of
114+as analogous to the `@q` `T` used to generate the Urbit HD wallet in the above
115+diagram. This seed phrase is a human readable sequence of words that may be used
116+to generate private keys to a near-limitless number of wallets created by adding
118+wallets also allow an additional passphrase to go into the generation of these
119+wallets. The seed phrase and passphrase should be considered equal in
120+value to the master ticket `T`- never share these with anyone!
122+In order to use your hardware wallet as your Urbit wallet, you first need to
123+generate a set of addresses on which you would like to store your Azimuth point
124+and proxies. Consult your wallet vendor on how to do this. Then login to Bridge
125+using your current method (likely a master ticket) and transfer ownership to the
126+wallet address you generated on your hardware wallet for ownership.
128+Next, login to Bridge using your hardware wallet. While Bridge supports Trezor
129+and Ledger natively, this may require using Metamask as an intermediary anyways,
130+depending on which firmware you are running. Then [accept the
131+transfer](@/using/operations/using-bridge.md#accept-your-transfer). Your Azimuth
132+point is now stored on your hardware wallet.
134+To finish the process, use Bridge to set your management, voting, and spawn
135+proxies to the other addresses you generated as applicable. You are now using
136+your hardware HD wallet in an analogous fashion to the Urbit HD wallet.
138+## Heightened security practices
140+A common security pattern is to have "hot" and "cold" wallets. For higher value
141+points such as stars and galaxies, you may consider having your ownership
142+address live on a "cold" wallet that never touches an
143+internet-connected computer, and the various proxies on a "hot" wallet that is
144+permitted to connect to internet-connected devices. This could be accomplished
145+with multiple hardware wallets, a combination of paper and hardware wallet, a
146+hardware cold wallet and Metamask hot wallet, etc.
148+One tool useful for this setup is `claz`, located at `app/claz.hoon`. `claz` is
149+used for making and signing Bridge transactions from an offline computer. A
150+guide to using `claz` is forthcoming.