@@ -9,7 +9,7 @@
99
1010This guide is broken into five parts:
1111
12−+ [Acquiring an Urbit Identity](#acquire)
12++ [Urbit Identities](#acquire)
1313+ [Using Bridge](#bridge)
1414+ [Installing Arvo](#arvo)
1515+ [Booting Your Ship](#boot)
@@ -20,34 +20,30 @@ Urbit network, you can skip to [Installing Arvo](#arvo)._
2020
2121;=
2222 ;h2
23− ;div(id "acquire"): Acquiring an Urbit Identity
23+ ;div(id "acquire"): Urbit Identities
2424 ==
2525==
2626
27−Urbit's identity layer, called Azimuth, is a suite of contracts on the Ethereum
28−blockchain. An Azimuth address, called a *point*, functions as an identity and
27+Urbit's identity layer, called Azimuth, is a public-key infrastructure (PKI)
28+that uses the Ethereum blockchain. An Azimuth address, called a point,
29+functions as an identity and
2930a network address for Arvo, the Urbit OS. An instance of Arvo is called a
30−*ship*. A ship can't use the Arvo network until it's combined with a point.
31+*ship*. A ship can't use the Arvo network unless it's been booted with the keys
32+registered to a point.
3133
3234Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
3335interchangeably.
3436
3537Points are generally not freely available, so you will need to either
36−purchase one or get one from a friend. This guide assumes you have found a way
37−to acquire a point.
38−
39−If you went through the address registration process and used [Wallet Generator](https://github.com/urbit/urbit-wallet-generator),
40−then you should have have received a .zip file that contains an Ethereum address
41−and cryptographic secrets in the form of a PDF.
42−
43−Your ownership PDF contains two secrets that must be kept safe.
44−
45−- *Master Ticket*: This is a master key that allows you to manage every aspect of
46− your address.
47−
48−- *Ownership Seed BIP39 Mnemonic*: The master ticket encoded as a BIP39 mnemonic
49− for compatibility with most Ethereum wallet software, including our own *Bridge*
50− client.
38+purchase one or get one from a friend. To receive one, you will need an Ethereum
39+wallet that supports the BIP39 mnemonic seed functionality, which allows you to
40+access your wallet with a series of dictionary words.
41+Hardware wallets, such as Ledger and TREZOR devices, satisfy this requirement.
42+So do various web-based wallets.
43+
44+Once you have such a wallet, give your Ethereum address to the person who agreed
45+to give you a point. Have them transfer the point to your address, and continue to the
46+next section.
5147
5248;=
5349 ;h2
@@ -55,57 +51,27 @@ Your ownership PDF contains two secrets that must be kept safe.
5551 ==
5652==
5753
58−Bridge is a client that we built for accessing and managing your Urbit identities.
59−Like Wallet Generator, Bridge is a web application that can also be run in offline mode.
60−It can be run in Firefox on all platforms, and also in Chrome if you're using
61−a Mac.
62−
63−Importantly, Bridge also allows you to generate a keyfile that
64−
65−you will need to boot your ship on the Arvo network for the first time. Once you boot a ship
54+Bridge is a client for accessing and managing your Urbit identities.
55+Importantly, Bridge also allows you to generate a keyfile that you will need to
56+boot your ship so that it can use the Arvo network. Once you boot a ship
6657with a keyfile, you can restart it later without the keyfile.
6758
68−*Note* Bridge allows you to make _writes_ to the blockchain, but we ask you to confirm
59+*Note:* Bridge allows you to make _writes_ to the blockchain, but we ask you to confirm
6960anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
7061sure your Ethereum address has some pocket ETH.
7162
72−Download Bridge [here](https://github.com/urbit/bridge/releases) and follow
73−the instructions below.
74−
75−#### Step 1: Welcome
76−
77−Click `Unlock a Wallet`.
78−
79−#### Step 2: Select a Network
80−
81−On the dropdown menu, make sure that `Main Network` is selected. Then click
82−`Continue ->`.
63+Download Bridge [here](https://github.com/urbit/bridge/releases), and follow
64+the instructions to run that program. Get a little bit of ETH on your address,
65+enough for a couple of transactions.
8366
84−#### Step 3: Unlock a Wallet
67+Once the program is running in your browser, go through each step according to
68+what kind of wallet you have.
8569
86−On this dropdown menu, choose how you'd like to access your Ethereum wallet.
87−If you aren't using a hardware wallet (we support Ledger and Trezor), you'll
88−want to use your Ethereum wallet's BIP39 Mnemonic.
70+### Accept Your Transfer
8971
90−If you used Wallet Generator to generate an HD wallet, you have a few choices:
91−you can choose `Urbit Master Ticket,` which is high-value, but allows you unfettered
92−permissions to update your point. The mnemonic associated with your management
93−seed is also useful to perform everyday operations (such as boot your ship!).
94−
95−Select the appropriate option and click `Continue ->`.
96−
97−If you already have a point -- for example, if you are trying to boot a ship
98−from a pre-Ethereum-era network -- you should see a list of points associated with your
99−keys. If you are trying to boot a planet for the first time, click on the
100−`Details` link for that point. At the bottom on the Details page, there is
101−a section called `Urbit Networking`. If the fields in this section are filled out, proceed to step 6.
102−
103−If you do not yet have a point and are getting one sent to you, proceed to step 4.
104−
105−#### Step 4: Accept Your Transfer
106−
107−If you were sent a point by a friend, then you should see a graphic under
108−`Incoming Transfers`. Click the `Details ->` link under that graphic.
72+After you access your Ethereum address, if a point was sent to that address,
73+you'll come to a page that has an `Incoming Transfers` header, under which is
74+a graphic. Click the `Details ->` link under that graphic.
10975
11076Now you'll be on the management page of your point. The transfer isn't completed
11177yet, so click `Accept incoming transfer`. Then check both boxes and and click
@@ -114,25 +80,33 @@ their associated `Sign Transaction` and `Send Transaction` buttons.
11480If you already own a point, then click on the `Details ->` under your sigil in the
11581`Your Points` section.
11682
117−#### Step 5: Set Your Networking Keys
83+### Set Your Networking Keys
11884
11985If you just accepted a point, you'll be returned to your point screen. Notice that
12086that links and buttons are now clickable. You now own this point!
12187
122−Click the link that says `Set Urbit networking keys`. Bridge will let you either
123−download a keyfile derived from your networking keys are you can paste in your own
124−network seed and derive a new keyfile. See our
125−[HD Wallet Spec](https://github.com/urbit/proposals/blob/master/8.udon)
126−for more information.
88+Click the link that says `Set Urbit networking keys`. The field that is presented
89+in the resulting page expects a 32-byte hexademicmal string; you can generate
90+this data any way you please, but in the terminal on MacOS or Linux, you can write
12791
128−It should be noted that this is an event on the Ethereum network and will cost
129−a trivial, but non-zero, amount of [gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
92+```
93+hexdump -n 32 -e '4/4 "%08X"' /dev/random
94+```
95+
96+and use the result.
13097
131−#### Step 6: Generate Your Keyfile
98+It should be noted that setting your network keys is an event on the Ethereum network,
99+and will therefore cost a trivial, but non-zero, amount of
100+[gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
101+
102+### Generate Your Keyfile
132103
133104From the detail page associated with your point, click the `Generate Arvo Keyfile`
134−button and you'll be taken to a page with a field titled `Network seed`. If you went
135−through the address registration process, this should be filled in already.
105+link and you'll be taken to a page with a field titled `Network seed`. This
106+field should already be filled in, and should match the hexadecimal string that you
107+entered in the previous step. If its not filled in or does not match, fill it in
108+with the correct string.
109+
136110Click `Generate ->`, which will download a keyfile onto your machine.
137111
138112With that keyfile in hand, you can now exit Bridge.
@@ -279,7 +253,7 @@ sudo ninja -C ./build/ meson-install
279253urbit
280254```
281255
282−##### FreeBSD
256+#### FreeBSD
283257
284258```
285259# Bash or Sh
@@ -299,7 +273,7 @@ sudo ninja -C ./build/ meson-install
299273urbit
300274```
301275
302−##### Amazon Web Services
276+#### Amazon Web Services
303277
304278```
305279# Bash
@@ -373,18 +347,18 @@ Don’t spend a lot of time tweaking these settings; the simplest thing is fine.
373347Now the rubber meets the road. You'll be booting your ship with the keyfile
374348that you downloaded from Bridge.
375349
376−#### Step 1: Find Your Point's Name
350+### Step 1: Find Your Point's Name
377351
378352This will look something like `~lodleb-ritrul`. You can see the name of your
379353point(s) when you log into your wallet using the Bridge client.
380354
381355;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
382356
383−#### Step 2: Find the path to your keyfile
357+### Step 2: Find the path to your keyfile
384358
385359Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
386360
387−#### Step 3: Run the boot command
361+### Step 3: Run the boot command
388362
389363Type `cd` in your terminal to return to your home directory. If you want to
390364store your ship somewhere besides your home directory, change the terminal's
@@ -395,13 +369,13 @@ Urbit identity, and `path/to/my-planet.key` replaced with the path to your
395369keyfile:
396370
397371```
398−urbit -w sample-planet -k path/to/my-planet.key
372+urbit -w ~sample-planet -k path/to/my-planet.key
399373```
400374
401375Or, if you'd prefer to copy your key in, you can run:
402376
403377```
404−urbit -w sample-planet -G rAnDoMkEy
378+urbit -w ~sample-planet -G rAnDoMkEy
405379```
406380
407381Either command will create a directory called `sample-planet/` and begin
@@ -419,7 +393,7 @@ machine.
419393
420394Welcome to your urbit! There's a few things you should do to become oriented.
421395
422−#### Dojo
396+### Dojo
423397
424398Let's try out the Dojo, the Arvo command line and Hoon REPL:
425399
@@ -436,7 +410,7 @@ Should produce:
436410
437411Good.
438412
439−#### Mounting
413+### Mounting
440414
441415Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
442416prompt and run:
@@ -457,13 +431,13 @@ which indicates that the command was processed.
457431Unix (the "pier" is our shorthand for the directory whose name corresponds to your Azimuth point). Changes to these files are automatically synced into your ship.
458432
459433
460−#### Landscape
434+### Landscape
461435
462436Landscape is web app we built for chatting and making posts. We are using Landscape to run a few experimental "cities" -- private discussion communities -- as a closed beta of sorts. If you have an Azimuth point, you’ll need to [email us](mailto:support@urbit.org) a request to gain access to one of these cities.
463437
464438Once you're in a channel, you can also interact with it from the command line, if you so wish. Use `ctrl-x` in your ship's terminal window to toggle between the Dojo and the Talk prompts.
465439
466−#### Shutting Down and Restarting
440+### Shutting Down and Restarting
467441
468442You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
469443