@@ -24,7 +24,15 @@ A metaphor might help illustrate the relationship between these two systems: the
2424
2525Owners 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.
2626
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.
32+
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).
2836
2937Urbit HD wallets are composed of the following items, which are each assigned to their own individual Ethereum key-pairs.
3038
@@ -54,8 +62,28 @@ Proxy addresses allow you to execute non-ownership related actions like spawning
5462
5563 For stars and galaxies only. Can create new child identities.
5664
65+### HD wallet generation
66+
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.
71+
5772
5873
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.
80+
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
84+generated.
85+
86+### ERC-721
5987
6088Most Ethereum tokens use the ERC-20 standard for smart contracts. Urbit identities
6189are, 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
6795interface for non-fungible assets, serves our needs well. This is the standard
6896that we use for deeding Urbit identities.
6997
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.
7199The Ecliptic is an Ethereum smart-contract that governs identity state and the
72100ownership, spawn, management, and voting rights affiliated with your identities.
73101
74102For the technical implementation details, take a look at Azimuth's
75103[Github repository](https://github.com/urbit/azimuth).
104+
105+## Hardware HD wallet
106+
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.
112+
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
117+salt. Some hardware
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!
121+
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.
127+
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.
133+
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.
137+
138+## Heightened security practices
139+
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.
147+
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.