@@ -9,7 +9,7 @@
10This guide is broken into five parts:
10This guide is broken into five parts:
12−+ [Acquiring an Urbit Identity](#acquire)
12++ [Urbit Identities](#acquire)
13+ [Using Bridge](#bridge)
13+ [Using Bridge](#bridge)
14+ [Installing Arvo](#arvo)
14+ [Installing Arvo](#arvo)
15+ [Booting Your Ship](#boot)
15+ [Booting Your Ship](#boot)
@@ -20,34 +20,30 @@ Urbit network, you can skip to [Installing Arvo](#arvo)._
23− ;div(id "acquire"): Acquiring an Urbit Identity
23+ ;div(id "acquire"): Urbit Identities
27−Urbit's identity layer, called Azimuth, is a suite of contracts on the Ethereum
27+Urbit's identity layer, called Azimuth, is a public-key infrastructure (PKI)
28−blockchain. An Azimuth address, called a *point*, functions as an identity and
28+that uses the Ethereum blockchain. An Azimuth address, called a point,
29+functions as an identity and
29a network address for Arvo, the Urbit OS. An instance of Arvo is called a
30a 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.
32Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
34Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
33interchangeably.
35interchangeably.
35Points are generally not freely available, so you will need to either
37Points 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
38+purchase one or get one from a friend. To receive one, you will need an Ethereum
37−to acquire a point.
39+wallet that supports the BIP39 mnemonic seed functionality, which allows you to
38−
40+access your wallet with a series of dictionary words.
39−If you went through the address registration process and used [Wallet Generator](https://github.com/urbit/urbit-wallet-generator),
41+Hardware wallets, such as Ledger and TREZOR devices, satisfy this requirement.
40−then you should have have received a .zip file that contains an Ethereum address
42+So do various web-based wallets.
41−and cryptographic secrets in the form of a PDF.
43+
42−
44+Once you have such a wallet, give your Ethereum address to the person who agreed
43−Your ownership PDF contains two secrets that must be kept safe.
45+to give you a point. Have them transfer the point to your address, and continue to the
45−- *Master Ticket*: This is a master key that allows you to manage every aspect of
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*
@@ -55,57 +51,27 @@ Your ownership PDF contains two secrets that must be kept safe.
58−Bridge is a client that we built for accessing and managing your Urbit identities.
54+Bridge is a client 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
63−Importantly, Bridge also allows you to generate a keyfile that
55+Importantly, Bridge also allows you to generate a keyfile that you will need to
65−you will need to boot your ship on the Arvo network for the first time. Once you boot a ship
56+boot your ship so that it can use the Arvo network. Once you boot a ship
66with a keyfile, you can restart it later without the keyfile.
57with a keyfile, you can restart it later without the keyfile.
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
69anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
60anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
70sure your Ethereum address has some pocket ETH.
61sure your Ethereum address has some pocket ETH.
72−Download Bridge [here](https://github.com/urbit/bridge/releases) and follow
63+Download Bridge [here](https://github.com/urbit/bridge/releases), and follow
73−the instructions below.
64+the instructions to run that program. Get a little bit of ETH on your address,
74−
65+enough for a couple of transactions.
77−Click `Unlock a Wallet`.
79−#### Step 2: Select a Network
81−On the dropdown menu, make sure that `Main Network` is selected. Then click
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.
86−On this dropdown menu, choose how you'd like to access your Ethereum wallet.
70+### Accept Your Transfer
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.
90−If you used Wallet Generator to generate an HD wallet, you have a few choices:
72+After you access your Ethereum address, if a point was sent to that address,
91−you can choose `Urbit Master Ticket,` which is high-value, but allows you unfettered
73+you'll come to a page that has an `Incoming Transfers` header, under which is
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!).
95−Select the appropriate option and click `Continue ->`.
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.
103−If you do not yet have a point and are getting one sent to you, proceed to step 4.
105−#### Step 4: Accept Your Transfer
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.
74+a graphic. Click the `Details ->` link under that graphic.
110Now you'll be on the management page of your point. The transfer isn't completed
76Now you'll be on the management page of your point. The transfer isn't completed
111yet, so click `Accept incoming transfer`. Then check both boxes and and click
77yet, so click `Accept incoming transfer`. Then check both boxes and and click
@@ -114,25 +80,33 @@ their associated `Sign Transaction` and `Send Transaction` buttons.
114If you already own a point, then click on the `Details ->` under your sigil in the
80If you already own a point, then click on the `Details ->` under your sigil in the
115`Your Points` section.
81`Your Points` section.
117−#### Step 5: Set Your Networking Keys
83+### Set Your Networking Keys
119If you just accepted a point, you'll be returned to your point screen. Notice that
85If you just accepted a point, you'll be returned to your point screen. Notice that
120that links and buttons are now clickable. You now own this point!
86that links and buttons are now clickable. You now own this point!
122−Click the link that says `Set Urbit networking keys`. Bridge will let you either
88+Click the link that says `Set Urbit networking keys`. The field that is presented
123−download a keyfile derived from your networking keys are you can paste in your own
89+in the resulting page expects a 32-byte hexademicmal string; you can generate
124−network seed and derive a new keyfile. See our
90+this data any way you please, but in the terminal on MacOS or Linux, you can write
125−[HD Wallet Spec](https://github.com/urbit/proposals/blob/master/8.udon)
126−for more information.
128−It should be noted that this is an event on the Ethereum network and will cost
92+```
129−a trivial, but non-zero, amount of [gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
93+hexdump -n 32 -e '4/4 "%08X"' /dev/random
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.
131−#### Step 6: Generate Your Keyfile
102+### Generate Your Keyfile
133From the detail page associated with your point, click the `Generate Arvo Keyfile`
104From 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
105+link and you'll be taken to a page with a field titled `Network seed`. This
135−through the address registration process, this should be filled in already.
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.
136Click `Generate ->`, which will download a keyfile onto your machine.
110Click `Generate ->`, which will download a keyfile onto your machine.
138With that keyfile in hand, you can now exit Bridge.
112With that keyfile in hand, you can now exit Bridge.
@@ -279,7 +253,7 @@ sudo ninja -C ./build/ meson-install
282−##### FreeBSD
256+#### FreeBSD
285# Bash or Sh
259# Bash or Sh
@@ -299,7 +273,7 @@ sudo ninja -C ./build/ meson-install
302−##### Amazon Web Services
276+#### Amazon Web Services
@@ -373,18 +347,18 @@ Don’t spend a lot of time tweaking these settings; the simplest thing is fine.
373Now the rubber meets the road. You'll be booting your ship with the keyfile
347Now the rubber meets the road. You'll be booting your ship with the keyfile
374that you downloaded from Bridge.
348that you downloaded from Bridge.
376−#### Step 1: Find Your Point's Name
350+### Step 1: Find Your Point's Name
378This will look something like `~lodleb-ritrul`. You can see the name of your
352This will look something like `~lodleb-ritrul`. You can see the name of your
379point(s) when you log into your wallet using the Bridge client.
353point(s) when you log into your wallet using the Bridge client.
381;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
355;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
383−#### Step 2: Find the path to your keyfile
357+### Step 2: Find the path to your keyfile
385Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
359Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
387−#### Step 3: Run the boot command
361+### Step 3: Run the boot command
389Type `cd` in your terminal to return to your home directory. If you want to
363Type `cd` in your terminal to return to your home directory. If you want to
390store your ship somewhere besides your home directory, change the terminal's
364store 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
398−urbit -w sample-planet -k path/to/my-planet.key
372+urbit -w ~sample-planet -k path/to/my-planet.key
401Or, if you'd prefer to copy your key in, you can run:
375Or, if you'd prefer to copy your key in, you can run:
404−urbit -w sample-planet -G rAnDoMkEy
378+urbit -w ~sample-planet -G rAnDoMkEy
407Either command will create a directory called `sample-planet/` and begin
381Either command will create a directory called `sample-planet/` and begin
@@ -419,7 +393,7 @@ machine.
420Welcome to your urbit! There's a few things you should do to become oriented.
394Welcome to your urbit! There's a few things you should do to become oriented.
422−#### Dojo
396+### Dojo
424Let's try out the Dojo, the Arvo command line and Hoon REPL:
398Let's try out the Dojo, the Arvo command line and Hoon REPL:
@@ -436,7 +410,7 @@ Should produce:
439−#### Mounting
413+### Mounting
441Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
415Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
442prompt and run:
416prompt and run:
@@ -457,13 +431,13 @@ which indicates that the command was processed.
457Unix (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.
431Unix (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.
460−#### Landscape
434+### Landscape
462Landscape 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.
436Landscape 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.
464Once 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.
438Once 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.
466−#### Shutting Down and Restarting
440+### Shutting Down and Restarting
468You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
442You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.