@@ -11,15 +11,17 @@ hidetitle = "true"
1111
1212Urbit reimagines the internet as a peer-to-peer network designed to stay that way. Previous attempts to "decentralize" the internet have only attempted to solve certain corners of the problem. Urbit proposes that only a new stack, built from the ground up as a tightly integrated system, can realize a great user experience for people using a peer-to-peer web.
1313
14−Combining a deterministic operating system (Urbit OS / Arvo) and a secure, global identity layer (Urbit ID / Azimuth), the Urbit project has created something that’s never existed before: an encrypted peer-to-peer network where you can be sure that messages are never tampered with or surveilled, and where strangers on that network can be trusted by default.
14+Combining a deterministic operating system ([Urbit OS](#what-is-arvo) / Arvo) and a secure, global identity layer ([Urbit ID](#what-is-urbit-id) / [Azimuth](#what-is-azimuth)), the Urbit project has created something that’s never existed before: an encrypted [Sybil resistant](https://en.wikipedia.org/wiki/Sybil_attack) peer-to-peer network where you can be sure that messages are never tampered with or surveilled.
1515
16−The connected world anticipated by Urbit is a much friendlier one, much like the early Internet, where collegial discussion and collaboration was the norm. Problems that are unsolvable without large-scale political centralization in our current internet – data breaches, spam, fake reviews, malware-spreading, harassment – become tractable when individuals control their computing again. You have one login for everything. You own and control all of your software and all of your data by default. Software is designed around the friendships, families, communities, and organizations you're already a part of – not the other way around.
16+The connected world anticipated by Urbit is a much friendlier one, much like the early Internet, where collegial discussion and collaboration was the norm. Problems that are unsolvable without large-scale political centralization in our current internet – data breaches, spam, fake reviews, malware-spreading, harassment – become tractable when individuals control their computing again. You have one login for everything. You own and control all of your software and all of your data by default. Software is designed around the friendships, families, communities, and organizations you're already a part of – not the other way around.
1717
1818### How secure is Urbit right now? {#how-secure-is-urbit}
1919
20−Urbit ID / Azimuth, Urbit's identity layer, is live on the Ethereum blockchain and has been audited by Open Zeppelin, Blockchain at Berkeley, and Bloctrax. [We run a bug bounty program](https://hackerone.com/tlon) on HackerOne.
20+[Urbit ID](#what-is-urbit-id) / [Azimuth](#what-is-azimuth), Urbit's identity layer, is live on the Ethereum blockchain and has been audited by Open Zeppelin, Blockchain at Berkeley, and Bloctrax.
2121
22−Urbit OS / Arvo is still an early beta. Arvo is safe to play with, but it’s not yet a place to store or share private information. Urbit's cryptographic protocols have not been professionally audited, and the OS itself doesn't provide protection from attackers on the network — although we haven't seen any yet.
22+In late 2020, Urbit's [Ames](@/docs/glossary/ames.md) networking protocol was audited by [Leviathan Security](https://www.leviathansecurity.com/). You can read about this milestone [here](@/blog/security-and-continuity.md).
23+
24+Looking to the future, Tlon has plans to begin working to make Urbit secure against attacks from quantum computers in 2021.
2325
2426### How can I contribute to Urbit? {#contribute}
2527
@@ -43,7 +45,7 @@ The community of people who build Urbit have widely varied ways of thinking and
4345
4446### Why aren't there more planets? {#more-planets}
4547
46−Urbit is designed to be as simple as possible. The sponsorship tree for Urbit ID simply expands by squaring the size of the last tier. That is, there are <span class="mono">2<sup>8</sup> (256)</span> galaxies, <span class="mono">(2<sup>8</sup>)<sup>2</sup> = 2<sup>16</sup> (~65K)</span> stars, <span class="mono">(2<sup>16</sup>)<sup>2</sup> = 2<sup>32</sup> (~4B)</span> planets. There are <span class="mono">2<sup>64</sup></span> moons — but moons are tethered to their planet, unlike stars and planets.
48+Urbit is designed to be as simple as possible. The sponsorship tree for Urbit ID simply expands by squaring the size of the last tier. That is, there are <span class="mono">2<sup>8</sup> (256)</span> [galaxies](@/docs/glossary/galaxy.md), <span class="mono">(2<sup>8</sup>)<sup>2</sup> = 2<sup>16</sup> (~65K)</span> [stars](@/docs/glossary/star.md), <span class="mono">(2<sup>16</sup>)<sup>2</sup> = 2<sup>32</sup> (~4B)</span> [planets](@/docs/glossary/planet.md). There are <span class="mono">2<sup>64</sup></span> [moons](@/docs/glossary/moon.md) — but moons are tethered to their planet, unlike stars and planets.
4749
4850This pattern exists because it’s a simple way to enforce the scarcity of addresses and build a friendly network. When a tier of the address space begins to be populated, we start populating the next tier down. When Urbit nears the limit of <span class="mono">2<sup>32</sup> (4B)</span> planets, we’ll figure out a way to populate the <span class="mono">2<sup>64</sup></span> moons. The galaxies that govern the Urbit ID contracts can always vote to upgrade them — and we expect that they will.
4951
@@ -55,51 +57,51 @@ It’s also worth noting that, while there are almost 8B people on Earth, there
5557
5658### Why do you use Ethereum? {#why-eth}
5759
58−As of 2019, Ethereum is the most widely deployed, most secure, and best documented general purpose blockchain. Using Ethereum is a practical engineering choice. It’s the best way to bootstrap real cryptographic ownership. We’re not specifically interested in Ethereum one way or the other.
60+In 2019 (when [Azimuth](#what-is-azimuth) was launched), Ethereum was the most widely deployed, most secure, and best documented general purpose blockchain, and it remains so today. Using Ethereum is a practical engineering choice. It’s the best way to bootstrap real cryptographic ownership. We’re not specifically interested in Ethereum one way or the other.
5961
60−One day we’d really like the Urbit ID registry to be hosted on Urbit OS itself. But the first challenge is getting Urbit OS to be completely secure.
62+One day we’d really like the Urbit ID registry to be hosted on [Urbit OS](#what-is-arvo) itself. But the first challenge is getting Urbit OS to be completely secure.
6163
6264### Why is Hoon so weird? {#why-hoon}
6365
64−There are things about Urbit that are weird by design, and some that are weird because we haven’t gotten around to cleaning them up. Hoon, for the most part, is weird by design, but there are a few things about it we’d like to clean up.
66+There are things about Urbit that are weird by design, and some that are weird because we haven’t gotten around to cleaning them up. [Hoon](@/docs/glossary/hoon.md), for the most part, is weird by design, but there are a few things about it we’d like to clean up.
6567
6668The runes are, once you get the hang of them, pretty nice. Your mileage may vary, of course, but many talented engineers have spent many, many hours writing Hoon. It’s a simple, practical language. But the learning curve can be a bit high.
6769
6870The standard library and naming is something we’ve discussed changing, and it could happen. It’s definitely up for debate whether or not the four-letter naming convention works well. The vanes (kernel modules) have largely moved away from this convention.
6971
70−The right way to think about Hoon is as the ‘C of Urbit’. It’s a bare bones language that gets you pretty close to Nock. Eventually, we’ll probably implement more expressive languages that compile to Urbit. But for now, satisfy your curiosity and [sign up for Hoon School](/hoonschool/).
71−
72−### What is the point of Nock? {#why-nock}
72+The right way to think about Hoon is as the ‘C of Urbit’. It’s a bare bones language that gets you pretty close to Nock. Eventually, we’ll probably implement more expressive languages that compile to Urbit. But for now, satisfy your curiosity and [sign up for Hooniversity](https://hooniversity.org/), a community led Hoon educational organization.
7373
74−The primary technical reason we can’t run our own computers already is that they don’t all compute the same way. Nock solves this problem. It provides a single computing foundation for the whole network. It’s also deterministic — which is an important feature for anything you’re going to put sensitive data into.
74+Another option is to treat [Urbit as an API](@/using/integrating-api.md), which allows one to use common languages such as Python and Javascript to build userspace programs. For now this option is not as powerful as Hoon, but there is still a lot that a developer without the time or inclination to learn Hoon can do.
7575
76−It’s true that Nock, without jets, is slow. With the ability to call out to a native function, it’s not so bad. We’ve been working on a new Nock interpreter for Grall Truffle that’s about 10x faster than the current one — so we’re not all that worried about performance for the time being.
76+### What is the point of Nock? {#why-nock}
7777
78−### Can I really host my Urbit with someone else? {#why-hosting}
78+The primary technical reason it is difficult for the individual to run a personal server is that modern computing architectures are not deterministic. What solves a problem for one person is not guaranteed to work on another person's computer, even if they are using identical hardware. [Nock](/docs/glossary/nock.md) solves this problem. It provides a single computing foundation for the whole network, so that difficult issues that arise when running a server need only to be solved once and the solution is guaranteed to work for everyone on the network.
7979
80−As a rule, anyone that has physical access to your computer owns you. They can steal your secrets and read its contents. There’s no way around that. We can’t prevent anyone hosting your Urbit from inspecting it — but we think it’s much nicer to host an Urbit than to run a web service for two reasons:
80+It’s true that Nock, without jets, is slow. With the ability to call out to a native function, it’s not so bad. This is done by our runtime, [Vere](@/docs/glossary/vere.md), a Nock interpreter written in C.
8181
82−One, you own your Urbit ID with a key that you never have to give your host. Your host only gets an operating key, and you can always revoke that key remotely. So, you might lose your data but it’s up to you to take good care of your identity.
82+### Can I host my Urbit with someone else? {#why-hosting}
8383
84−Two, your Urbit runs inside a VM. There’s a very clear line over which a host should never step: your event log. This is not unlike the way that cloud hosting works today. Netflix is hosted on AWS — one of their biggest competitors. Luckily, the AWS terms of service protects Netflix from a legal standpoint.
84+Yes, [Tlon](@/blog/hosting-the-future.md) and [a few others](@/blog/providers.md) began [accepting signups](https://tlon.io) for our hosting service in 2020. Under this arrangement, Tlon does all the work of setting up cloud infrastructure and getting your planet up and running, making getting started with Urbit as simple as signing up for an ordinary online service.
8585
86−At the end of the day, if you’re really worried about security, it’s quite easy to host Urbit yourself. This means that people who care a lot about privacy can still get the same usability as those who want the convenience of hosting.
86+Should you one day wish to run your Urbit yourself, any hosting provider ought to offer you the ability to download your [ship](@/docs/glossary/ship.md)'s [pier](@/docs/glossary/pier.md) to your own device and do so. This is a very low friction process thanks to Urbit's deterministic design.
8787
8888## Urbit ID
8989
9090### What is Urbit ID? {#what-is-urbit-id}
9191
92−Urbit ID is a general-purpose PKI ("public key infrastructure") that Urbit uses as an identity system. This system is implemented as a suite of smart contracts on the Ethereum blockchain, and it determines which Ethereum addresses own which Urbit planets, stars, or galaxies. In Urbit OS, a single identity is called a "ship", whereas in Urbit ID a single identity is just an "identity."
92+Urbit ID is the identity system utilized by Urbit, which associates to each [ship](@/docs/glossary/ship.md) a public and private key used to establish encrypted connections between one another and to guard private data. For [planets](@/docs/glossary/planet.md), [stars](@/docs/glossary/star.md), and [galaxies](@/docs/glossary/galaxy.md), this is achieved with a set of Ethereum smart contracts called [Azimuth](#what-is-azimuth). Keys for [moons](@/docs/glossary/moon.md) and [comets](@/docs/glossary/comet.md) are handled within Urbit.
9393
9494### What are stars, galaxies, and planets? {#stars-galaxies-planets}
9595
9696Urbit IDs come in three classes: galaxies, stars, and planets. The length of an identity’s name will tell you its class. Galaxies are 8-bit and have names like `~mul`. Galaxies issue 16-bit stars (`~dacmul`), which can themselves issue 32-bit planets (`~laptel-holfur`).
9797
98−Planets are intended for everyday use by individuals, and there are 4.3 billion of them (two to the 32nd power). Stars and galaxies, on the other hand, are meant to act as network infrastructure: on the Urbit OS network they provide routing and are responsible for distributing software updates.
98+Planets are intended for everyday use by individuals, and there are 4.3 billion of them (two to the 32nd power). Stars and galaxies, on the other hand, are meant to act as network infrastructure: on the [Urbit OS](#what-is-arvo) network they provide routing and are responsible for distributing software updates.
9999
100100### What is Azimuth? {#what-is-azimuth}
101101
102−Azimuth is what we call the set of Ethereum contracts that make up Urbit ID. It's also kind of a [cool astronomical concept](https://en.wikipedia.org/wiki/Azimuth).
102+[Azimuth](@/docs/glossary/azimuth.md) is what we call the set of Ethereum contracts that make up a general-purpose decentralized PKI ("public key infrastructure") utilized by Urbit ID. It keeps a record of which Ethereum addresses own which Urbit planets, stars, and galaxies, as well as the public keys associated with those ships.
103+
104+It's also kind of a [cool astronomical concept](https://en.wikipedia.org/wiki/Azimuth).
103105
104106### How many planets, stars, and galaxies are active? {#how-many-planets-stars-galaxies}
105107
@@ -109,29 +111,31 @@ You can also inspect and execute functions in the [azimuth.eth](https://ethersca
109111
110112### What are comets and moons? {#comets-moons}
111113
112−In addition to the three classes of identities mentioned above, there are two other kinds of Urbit ships that are _not_ registered in the Urbit ID / Azimuth contracts.
114+In addition to the three classes of identities mentioned above, there are two other kinds of Urbit [ship](@/docs/glossary/ship.md)s that are _not_ registered in the Urbit ID / Azimuth contracts.
113115
114−Moons are 64 bits, issued by planets, and have names like `~doznec-salfun-naptul-habrys`. Moons are meant for connected devices: phones, desktops, smart TVs, digital thermostats, and other IoT devices. Moons are subordinated to their parent planet.
116+[Moons](@/docs/glossary/moon.md) are 64 bits, issued by [planets](@/docs/glossary/planet.md), and have names like `~doznec-salfun-naptul-habrys`. Moons are meant for connected devices: phones, desktops, smart TVs, digital thermostats, and other IoT devices. Moons are subordinate to their parent planet. A strong analogy here is that ordinary social media sites are somewhat like planets, and your account on them is a moon. Urbit elevates everybody to the level of planet.
115117
116−Comets are 128 bits and have no parents. They can be launched by anyone. They are temporary, disposable identities. Being disposable and essentially unlimited, they will likely not be trusted by default by others on the Urbit OS network, though you shouldn't have any problem until the network grows much larger. They have long, hard-to-memorize names, like `~racmus-mollen-fallyt-linpex-watres-sibbur-modlux-rinmex`.
118+[Comets](@/docs/glossary/comet.md) are 128 bits and have no parents. They can be launched by anyone for free. Since their identity is not maintained on the blockchain, they will likely not be trusted by default by others on the [Urbit OS](#what-is-arvo) network, though you shouldn't have any problem until the network grows much larger. They have long, hard-to-memorize names, like `~racmus-mollen-fallyt-linpex-watres-sibbur-modlux-rinmex`.
117119
118120### What is a `@p`? Why is my username generated for me? {#what-is-patp}
119121
120−A `@p` (pronounced *pat-pee*) is a name like `~zod` or `~lodleb-ritrul` composed of pronounceable, three-letter phonemic elements like `zod`, `lod`, `leb`, `rit` and `rul`. Shorter names, such as `~zod` and `~marzod`, are assigned to ships with special duties on the Arvo network stars and galaxies, respectively. Longer names like `~palfun-foslup` are identities for typical users.
122+A `@p` ([pronounced](@/docs/tutorials/hoon/hoon-school/hoon-syntax.md#reading-hoon-aloud) *pat-pee*) is a name like `~zod` or `~lodleb-ritrul` composed of pronounceable, three-letter phonemic elements like `zod`, `lod`, `leb`, `rit` and `rul`. Shorter names, such as `~zod` and `~marzod`, are assigned to [ship](@/docs/glossary/ship.md)s with special duties on the [Arvo](#what-is-arvo) network galaxies and stars, respectively. Longer names like `~palfun-foslup` are identities for typical users.
121123
122124These names map directly to a corresponding number in the Urbit ID address space. Galaxies occupy the 8-bit address space, so any galaxy is actually a number between zero and 255. Stars occupy the 16-bit address space, and planets occupy the 32-bit address space.
123125
126+Your name is generated for you as a solution to [Zooko's triangle](https://en.wikipedia.org/wiki/Zooko%27s_triangle), which roughly states that names on a network protocol can only be two of (i) human-meaningful, (ii) secure, and (iii) decentralized. Urbit chooses (ii) and (iii), which something like DNS chooses (i) and (ii).
127+
128+Regardless, you can always choose to set your nickname in [Landscape](#what-is-landscape), so if you wish for a different name to be displayed then you have the freedom to do so.
129+
124130### Can I change my `@p`? {#change-my-patp}
125131
126132Nope. There is a 1:1 mapping between name and identity. Think of your `@p` sort of like a phone number. It's just a random synthetic name that doesn't leak any personal information about you.
127133
128134### How do I get an identity? {#get-an-identity}
129135
130−The easiest way is to find a friend who can give you one. They're out there — just ask around.
131−
132−Or, if you must, try an ERC-721 (NFT) exchange (Google or Twitter should help you with this). This will probably involve a purchase and a transfer to an Ethereum address that you own. We recommend using [Bridge](https://bridge.urbit.org) to access the address that the identity is transferred to.
136+The easiest way is to find a friend who can give you one. They're out there — just ask around. You'll have a good chance of meeting one if you join Urbit Community, the default group for new [ship](@/docs/glossary/ship.md)s at `~bitbet-bolbel/urbit-community`, as a [comet](@/docs/glossary/comet.md) and contribute pleasantly to the conversation.
133137
134−If you don't want to use Bridge, a tool like [Etherscan](https://etherscan.io) will allow you to execute functions in the [ecliptic.eth](https://etherscan.io/address/ecliptic.eth#code) contract.
138+Or, if you must, try an ERC-721 (NFT) exchange (Google or Twitter should help you with this). This will probably involve a purchase and a transfer to an Ethereum address that you own. We recommend using [Bridge](@/docs/glossary/bridge.md), available at [https://bridge.urbit.org](https://bridge.urbit.org), to access the address that the identity is transferred to.
135139
136140### How do I transfer an identity to someone else? {#transfer-identity}
137141
@@ -141,44 +145,44 @@ Access the Ethereum address that holds the identity you wish to transfer via [Br
141145
142146We recommended using [Bridge](https://bridge.urbit.org) for all Urbit ID-related operations. It’s great for managing your identities, as well as for viewing information about identities you don’t own.
143147
144−Be careful about using hosted versions of Bridge not hosted on urbit.org. Since Bridge touches your private keys, it can also steal them.
148+Be careful about using online versions of Bridge not hosted on urbit.org. Since Bridge touches your private keys, it can also steal them.
145149
146150## Urbit HD Wallet
147151
148152### What is the Urbit HD Wallet? {#urbit-hd-wallet}
149153
150−The Urbit Hierarchical Deterministic (HD) Wallet is a custom Ethereum wallet based on BIP39 and BIP44 – the same underlying technology used by wallet providers like Ledger, Trezor, Metamask, and MyEtherWallet. You can think of the Urbit HD wallet as a wallet of wallets, which lets you keep a single passphrase for all of your Urbit ID keys. Urbit ID uses multiple keys with different capabilities – a bit like permissions – so that you can keep the more valuable keys in cold storage while keeping less valuable keys, used in day-to-day operation, more easily accessible. If you're only operating a planet, you shouldn't have to worry about this: you can simply think of your "master ticket" as the password to your Urbit ID. If you're operating a star or galaxy, the Urbit HD Wallet allows you to implement a multi-tier key custody scheme.
154+The [Urbit Hierarchical Deterministic (HD) Wallet](@/docs/glossary/hdwallet.md) is a custom Ethereum wallet based on BIP39 and BIP44 – the same underlying technology used by wallet providers like Ledger, Trezor, Metamask, and MyEtherWallet. You can think of the Urbit HD wallet as a wallet of wallets, which lets you keep a single passphrase for all of your Urbit ID keys. Urbit ID uses multiple keys with different capabilities – a bit like permissions – so that you can keep the more valuable keys in cold storage while keeping less valuable keys, used in day-to-day operation, more easily accessible. If you're only operating a planet, you shouldn't have to worry about this: you can simply think of your "master ticket" as the password to your Urbit ID. If you're operating a star or galaxy, the Urbit HD Wallet allows you to implement a multi-tier key custody scheme.
151155
152156If you're interested, you can read the spec here: [Urbit HD Wallet Spec (UP 8)](https://github.com/urbit/proposals/blob/master/008-urbit-hd-wallet.md).
153157
154158### What is a master ticket? {#master-ticket}
155159
156−The "master ticket" is the entropy seed from which your other Urbit ID keys are derived. It should be treated like a master password: **you should never share it with anyone, and you must store it very securely (see our practices below).** This ticket is used to derive the Ethereum wallet that holds your ownership keys, your Urbit OS key – used to boot your Urbit – and the other keys associated with your identity. You’ll have a ticket if you used the Urbit Wallet Generator or claimed a ship on our hosted version of Bridge.
160+The "master ticket" is the entropy seed from which your other Urbit ID keys are derived. It should be treated like a master password: **you should never share it with anyone, and you must store it very securely (see our practices below).** This ticket is used to derive the Ethereum wallet that holds your ownership keys, your [Urbit OS](#what-is-arvo) key – used to boot your Urbit – and the other keys associated with your identity. You’ll have a master ticket if you used the Urbit Wallet Generator or claimed a [ship](@/docs/glossary/ship.md) on our hosted version of Bridge.
157161
158162If you're operating a planet, you can use your master ticket to authenticate with Bridge.
159163
160164### What is an ownership address? {#ownership-address}
161165
162−An ownership address is an Ethereum address that owns one or more of your Urbit IDs. The Urbit Wallet Generator creates one Urbit HD Wallet and associated addresses for each of your identities. Using the ownership key associated with your ownership address, you can transfer identities to other people, meaning that it’s very important to store securely.
166+An ownership address is an Ethereum address that owns one or more of your Urbit IDs. The Urbit Wallet Generator creates one [Urbit HD Wallet](@/docs/glossary/hdwallet.md) and associated addresses for each of your identities. Using the ownership key associated with your ownership address, you can transfer identities to other people, meaning that it’s very important to store securely.
163167
164168### What are proxies? {#proxies}
165169
166−Proxies are seeds derived from your master ticket used to generate sub-wallets, which in turn are used to generate keys that have the ability to execute different Urbit ID functions associated with your Urbit identity. Proxies generally have more restricted capabilities than your ownership seed. These capabilities include spawning child identities, voting, and setting networking keys.
170+[Proxies](@/docs/glossary/proxies.md) are seeds derived from your master ticket used to generate sub-wallets, which in turn are used to generate keys that have the ability to execute different Urbit ID functions associated with your Urbit identity. Proxies generally have more restricted capabilities than your ownership seed. These capabilities include spawning child identities, voting, and setting networking keys.
167171
168172- Transfer proxy: Can transfer your identity to another Ethereum address.
169−- Spawn Proxy: For stars and galaxies only. Can create new child identities.
173+- Spawn Proxy: For [stars](@/docs/glossary/star.md) and [galaxies](@/docs/glossary/galaxy.md) only. Can create new child identities.
170174- Management Proxy: Can configure or set networking keys and conduct sponsorship related operations.
171−- Voting Proxy: Galaxies only. Galaxies are the part of the galactic senate, which means they can cast votes on new proposals including changes to the "Ecliptic" contract, which defines the operations of Azimuth.
175+- Voting Proxy: [Galaxies](@/docs/glossary/galaxy.md) only. Galaxies are the part of the [galactic senate](@/docs/glossary/senate.md), which means they can cast votes on new proposals including changes to the "[Ecliptic](@/docs/glossary/ecliptic.md)" contract, which defines the operations of [Azimuth](@/docs/glossary/azimuth.md).
172176
173177### What are seeds? {#seeds}
174178
175−All Ethereum key-pairs in the Urbit wallet system, including proxies, are produced by 128-bit cryptographically random values called seeds. These seeds are the equivalent of the BIP39 mnemonic of an Ethereum wallet and are yours alone. An ownership key pair is derived from an ownership seed and, likewise, the various proxy key pairs are generated from their respective proxy seeds.
179+All Ethereum key-pairs in the Urbit wallet system, including [proxies](@/docs/glossary/proxies.md), are produced by 128-bit cryptographically random values called seeds. These seeds are the equivalent of the BIP39 mnemonic of an Ethereum wallet and are yours alone. An ownership key pair is derived from an ownership seed and, likewise, the various proxy key pairs are generated from their respective proxy seeds.
176180
177181For detailed information see the [Urbit HD Wallet Spec (UP 8)](https://github.com/urbit/proposals/blob/master/008-urbit-hd-wallet.md).
178182
179183### What does it mean to “set public keys”? {#set-public-keys}
180184
181−This means registering the public keys of your identity's encryption and authentication key pairs (together known as "networking keys") with Urbit ID / Azimuth, so that others can discover them. The corresponding private keys can then be used to, for example, run a ship on the Urbit OS network.
185+This means registering the public keys of your identity's encryption and authentication key pairs (together known as "networking keys") with Urbit ID / [Azimuth](@/docs/glossary/azimuth.md), so that others can discover them. The corresponding private keys can then be used to, for example, run a [ship](@/docs/glossary/ship.md) on the [Urbit OS](#what-is-arvo) network.
182186
183187You want to reset these keys if they are compromised, or if your ship has sunk. This is of little practical significance today, but resetting your networking keys resets your relationship with other ships on the network.
184188
@@ -235,25 +239,25 @@ There are two kinds of release schemes for locked up assets: linear and conditio
235239
236240In either scheme, you start out being able to take one star out of lockup, regardless of the terms set around the lockup as a whole. This way, you get to participate with a star right away. Go do something cool!
237241
238−If your lockup involved a galaxy, all of its stars will be locked up, but you will have immediate, lock-free control of the galaxy. You will likely need it to use that star.
242+If your lockup involved a [galaxy](@/docs/glossary/galaxy.md), all of its [stars](@/docs/glossary/star.md) will be locked up, but you will have immediate, lock-free control of the galaxy. You will likely need it to use that star.
239243
240244Note that the "releasing" of stars just means that they become available for you to claim. They don't automatically get transferred to you; you have to withdraw them from the appropriate lockup contract.
241245
242246Linear release is the simplest: your stars will be released linearly over a period of time. Most often this is a period of four years. If you have four stars in lockup, that means you will be able to withdraw one star per year. In many cases, there is also an initial windup period which has to pass before linear releasing begins, typically one year. Since Azimuth launched in January 2019, the linear release will begin in January 2020.
243247
244−Conditional release is a bit more complicated. If your stars are in conditional lockup, they're likely divided over three so-called tranches. Each of these unlocks only after a unique condition is met. Since it's difficult to verify things about the real world using smart contracts, the Galactic Senate verifies that they've been met. Once the Senate marks a condition for a tranche as cleared, it starts releasing linearly over the period of a year.
248+Conditional release is a bit more complicated. If your stars are in conditional lockup, they're likely divided over three so-called tranches. Each of these unlocks only after a unique condition is met. Since it's difficult to verify things about the real world using smart contracts, the [Galactic Senate](@/docs/glossary/senate.md) verifies that they've been met. Once the Senate marks a condition for a tranche as cleared, it starts releasing linearly over the period of a year.
245249
246250## Urbit OS
247251
248252### What is Urbit OS? {#what-is-arvo}
249253
250−Urbit OS, also called Arvo, is our functional and deterministic software stack. Arvo is written in Hoon, our purely functional programming language, which compiles to Nock, a compact bytecode language.
254+Urbit OS, also called [Arvo](@/docs/glossary/arvo.md), is our functional and deterministic software stack. Arvo is written in [Hoon](@/docs/glossary/hoon.md), our purely functional programming language, which compiles to [Nock](@/docs/glossary/nock.md), a compact bytecode language.
251255
252−Instances of Urbit OS / Arvo, called 'ships', communicate as peers on what we refer to as “the Urbit OS network.” Using Urbit ID, Urbit OS ships can prove their identities to one another.
256+Instances of Urbit OS, called '[ships](@/docs/glossary/ship.md)', communicate as peers on what we refer to as “the [Ames](@/docs/glossary/ames.md) network.” Using Urbit ID, Urbit OS ships can prove their identities to one another.
253257
254258### What is unique about Urbit OS / Arvo? {#what-is-unique-about-arvo}
255259
256−Arvo is different from other operating systems in many ways. One notable way is that it is completely deterministic. Processing in the system happens in a unique way: when an event happens, a transition function takes that event and the old state of Arvo, and produces an effect and a new state of Arvo. To visualize:
260+[Arvo](@/docs/glossary/arvo.md) is different from other operating systems in many ways. One notable way is that it is completely deterministic. Processing in the system happens in a unique way: when an event happens, a transition function takes that event and the old state of Arvo, and produces an effect and a new state of Arvo. To visualize:
257261
258262`[event, old state] -> [effects, new state]`
259263
@@ -261,13 +265,13 @@ All events are logged to disk, so you can always restore the system to a previou
261265
262266### How is Urbit OS / Arvo connected to Ethereum? {#arvo-ethereum}
263267
264−When an Arvo ship (instance) is started for the first time you must use a "keyfile" containing the private keys for your identity's networking keys. Urbit ID uses the Ethereum blockchain as its decentralized ledger.
268+When an [Arvo](@/docs/glossary/arvo.md) ship (instance) is started for the first time you must use a "[keyfile](@/docs/glossary/keyfile.md)" containing the private keys for your identity's networking keys. Urbit ID uses the Ethereum blockchain as its decentralized ledger.
265269
266−See our [Getting Started](@/using/install.md) guide to learn how to get your ship onto the Urbit OS / Arvo network.
270+See our [Getting Started](@/using/install.md) guide to learn how to get your ship onto the Urbit OS / [Ames](@/docs/glossary/ames.md) network.
267271
268272### Will the Urbit OS network survive if Ethereum dies? {#if-ethereum-dies}
269273
270−Yes. It would be annoying, but Urbit ID / Azimuth could be ported to another decentralized ledger, or hosted on Urbit OS / Arvo itself.
274+Yes. It would be annoying, but Urbit ID / [Azimuth](@/docs/glossary/azimuth.md) could be ported to another decentralized ledger, or hosted on Urbit OS / [Arvo](@/docs/glossary/arvo.md) itself.
271275
272276### How do I install Urbit OS? {#install-urbit-os}
273277
@@ -283,13 +287,13 @@ Your sponsor, a star or galaxy that your ship is connected to, may send you new
283287
284288### What is Landscape? {#what-is-landscape}
285289
286−Landscape is an experimental Urbit OS web interface that includes social functions such as chat and publishing. You can access Landscape by navigating to `http://localhost:PORT`, where PORT is typically 80, 8080, or 8081 (check your boot messages).
290+[Landscape](@/docs/glossary/landscape.md) is an experimental Urbit OS web interface that includes social functions such as chat and publishing. You can access Landscape by navigating to `http://localhost:PORT`, where PORT is typically 80, 8080, or 8081 (check your boot messages).
287291
288292### I have an Urbit ID, now what? {#now-what}
289293
290−Follow our guide on how to boot a ship [here](@/using/install.md).
294+Follow our guide on how to boot a ship [here](@/using/install.md).
291295
292−Get on the [mailing list](https://urbit.us11.list-manage.com/subscribe/post?u=972a03db9e0c6c25bb58de8c8&id=be143888d2). Learn [Hoon](@/docs/tutorials/hoon/hoon-school/_index.md). Sign up for [Hoon School](@/community/hoonschool.md). [Make stuff](https://grants.urbit.org).
296+Get on the [mailing list](https://urbit.us11.list-manage.com/subscribe/post?u=972a03db9e0c6c25bb58de8c8&id=be143888d2). Learn [Hoon](@/docs/tutorials/hoon/hoon-school/_index.md). Sign up for [Hooniversity](https://hooniversity.org/). [Make stuff](https://grants.urbit.org).
293297
294298
295299## Urbit Grants
@@ -375,7 +379,7 @@ Here are a few important points from the bounty and proposal contracts:
375379
376380- **No employment relationship:** You agree that being approved for the grant or bounty does not imply any employment relationship with Tlon.
377381
378−- **Termination:** Either party (you or Tlon) can terminate the agreement on seven days' written notice. If that happens, you may be compensated *pro rata* for the amount of work you've completed, but this compensation is at the sole discretion of Tlon.
382+- **Termination:** Either party (you or Tlon) can terminate the agreement on seven days' written notice. If that happens, you may be compensated *pro rata* for the amount of work you've completed, but this compensation is at the sole discretion of Tlon.
379383
380384- **Governing law:** The agreement is governed by the laws of the State of California.
381385