git.iko.soy/urbit.org
on master help sign in
new folder structure, moving all files
commit7c49870a59d49677a4192e912f20a69530a49655 authordrbeefsupreme <drbeefsupreme@discordja.net> dateThu 18 Feb 2021, 13:59 (6 years ago) parenta7a26a4
157 files changed+342−625
compare with master
unifiedsplit
reference/vane-apis/ames.md → arvo/ames/ames-api.md tutorials/arvo/ames.md → arvo/ames/ames.md tutorials/arvo/arvo.md → arvo/arvo.md reference/vane-apis/behn.md → arvo/behn/behn-api.md tutorials/arvo/behn.md → arvo/behn/behn.md tutorials/arvo/clay.md → arvo/clay/clay.md reference/vane-apis/dill.md → arvo/dill/dill-api.md tutorials/arvo/dill.md → arvo/dill/dill.md tutorials/arvo/eyre.md → arvo/eyre/eyre.md reference/vane-apis/gall.md → arvo/gall/gall-api.md tutorials/arvo/gall.md → arvo/gall/gall.md reference/vane-apis/iris.md → arvo/iris/iris-api.md reference/vane-apis/jael.md → arvo/jael/jael-api.md tutorials/arvo/move-trace.md → arvo/move-trace.md tutorials/advanced-azimuth-tools.md → azimuth/advanced-azimuth-tools.md tutorials/concepts/azimuth.md → azimuth/azimuth.md reference/vane-apis/airlock.md → development/airlock.md development/develop.md+117 development/integrating-api.md+224 tutorials/hoon/hoon-school/aqua.md → hoon/guides/aqua.md tutorials/hoon/cli-tutorial.md → hoon/guides/cli-tutorial.md tutorials/hoon/parsing.md → hoon/guides/parsing.md tutorials/hoon/hoon-school/_index.md → hoon/hoon-school/_index.md tutorials/hoon/hoon-school/ackermann.md → hoon/hoon-school/ackermann.md tutorials/hoon/hoon-school/arms-and-cores.md → hoon/hoon-school/arms-and-cores.md tutorials/hoon/hoon-school/atoms-auras-and-simple-cell-types.md → hoon/hoon-school/atoms-auras-and-simple-cell-types.md tutorials/hoon/hoon-school/bank-account.md → hoon/hoon-school/bank-account.md tutorials/hoon/hoon-school/behn.md → hoon/hoon-school/behn.md tutorials/hoon/hoon-school/caesar.md → hoon/hoon-school/caesar.md tutorials/hoon/hoon-school/conditionals.md → hoon/hoon-school/conditionals.md tutorials/hoon/hoon-school/doors.md → hoon/hoon-school/doors.md tutorials/hoon/hoon-school/egg-timer.md → hoon/hoon-school/egg-timer.md tutorials/hoon/hoon-school/fibonacci.md → hoon/hoon-school/fibonacci.md tutorials/hoon/hoon-school/gall.md → hoon/hoon-school/gall.md tutorials/hoon/hoon-school/gates.md → hoon/hoon-school/gates.md tutorials/hoon/hoon-school/generators.md → hoon/hoon-school/generators.md tutorials/hoon/hoon-school/hoon-syntax.md → hoon/hoon-school/hoon-syntax.md tutorials/hoon/hoon-school/iron-polymorphism.md → hoon/hoon-school/iron-polymorphism.md tutorials/hoon/hoon-school/lead-polymorphism.md → hoon/hoon-school/lead-polymorphism.md tutorials/hoon/hoon-school/libraries.md → hoon/hoon-school/libraries.md tutorials/hoon/hoon-school/list-of-numbers.md → hoon/hoon-school/list-of-numbers.md tutorials/hoon/hoon-school/lists.md → hoon/hoon-school/lists.md tutorials/hoon/hoon-school/molds.md → hoon/hoon-school/molds.md tutorials/hoon/hoon-school/nouns.md → hoon/hoon-school/nouns.md tutorials/hoon/hoon-school/recursion.md → hoon/hoon-school/recursion.md tutorials/hoon/hoon-school/setup.md → hoon/hoon-school/setup.md tutorials/hoon/hoon-school/structures-and-complex-types.md → hoon/hoon-school/structures-and-complex-types.md tutorials/hoon/hoon-school/the-subject-and-its-legs.md → hoon/hoon-school/the-subject-and-its-legs.md tutorials/hoon/hoon-school/trees-sets-and-maps.md → hoon/hoon-school/trees-sets-and-maps.md tutorials/hoon/hoon-school/type-checking-and-type-inference.md → hoon/hoon-school/type-checking-and-type-inference.md tutorials/hoon/hoon-school/type-polymorphism.md → hoon/hoon-school/type-polymorphism.md tutorials/hoon/workbook/_index.md → hoon/hoon-school/workbook/_index.md tutorials/hoon/workbook/bomb.md → hoon/hoon-school/workbook/bomb.md tutorials/hoon/workbook/digits.md → hoon/hoon-school/workbook/digits.md tutorials/hoon/workbook/eightball.md → hoon/hoon-school/workbook/eightball.md tutorials/hoon/workbook/traffic-light.md → hoon/hoon-school/workbook/traffic-light.md reference/hoon-expressions/advanced.md → hoon/reference/advanced.md reference/hoon-expressions/basic.md → hoon/reference/basic.md reference/cheat-sheet.md → hoon/reference/cheat-sheet.md tutorials/hoon/hoon-errors.md → hoon/reference/hoon-errors.md reference/hoon-expressions/irregular.md → hoon/reference/irregular.md reference/hoon-expressions/limb/_index.md → hoon/reference/limbs/_index.md reference/hoon-expressions/limb/limb.md → hoon/reference/limbs/limb.md reference/hoon-expressions/limb/wing.md → hoon/reference/limbs/wing.md reference/hoon-expressions/rune/_index.md → hoon/reference/runes/_index.md reference/hoon-expressions/rune/bar.md → hoon/reference/runes/bar.md reference/hoon-expressions/rune/buc.md → hoon/reference/runes/buc.md reference/hoon-expressions/rune/cen.md → hoon/reference/runes/cen.md reference/hoon-expressions/rune/col.md → hoon/reference/runes/col.md reference/hoon-expressions/rune/constants.md → hoon/reference/runes/constants.md reference/hoon-expressions/rune/dot.md → hoon/reference/runes/dot.md reference/hoon-expressions/rune/ket.md → hoon/reference/runes/ket.md reference/hoon-expressions/rune/lus.md → hoon/reference/runes/lus.md reference/hoon-expressions/rune/mic.md → hoon/reference/runes/mic.md reference/hoon-expressions/rune/sig.md → hoon/reference/runes/sig.md reference/hoon-expressions/rune/terminators.md → hoon/reference/runes/terminators.md reference/hoon-expressions/rune/tis.md → hoon/reference/runes/tis.md reference/hoon-expressions/rune/wut.md → hoon/reference/runes/wut.md reference/hoon-expressions/rune/zap.md → hoon/reference/runes/zap.md reference/library/1a.md → hoon/reference/stdlib/1a.md reference/library/1b.md → hoon/reference/stdlib/1b.md reference/library/1c.md → hoon/reference/stdlib/1c.md reference/library/2a.md → hoon/reference/stdlib/2a.md reference/library/2b.md → hoon/reference/stdlib/2b.md reference/library/2c.md → hoon/reference/stdlib/2c.md reference/library/2d.md → hoon/reference/stdlib/2d.md reference/library/2e.md → hoon/reference/stdlib/2e.md reference/library/2f.md → hoon/reference/stdlib/2f.md reference/library/2g.md → hoon/reference/stdlib/2g.md reference/library/2h.md → hoon/reference/stdlib/2h.md reference/library/2i.md → hoon/reference/stdlib/2i.md reference/library/2j.md → hoon/reference/stdlib/2j.md reference/library/2k.md → hoon/reference/stdlib/2k.md reference/library/2l.md → hoon/reference/stdlib/2l.md reference/library/2m.md → hoon/reference/stdlib/2m.md reference/library/2n.md → hoon/reference/stdlib/2n.md reference/library/2o.md → hoon/reference/stdlib/2o.md reference/library/2p.md → hoon/reference/stdlib/2p.md reference/library/2q.md → hoon/reference/stdlib/2q.md reference/library/3a.md → hoon/reference/stdlib/3a.md reference/library/3b.md → hoon/reference/stdlib/3b.md reference/library/3c.md → hoon/reference/stdlib/3c.md reference/library/3d.md → hoon/reference/stdlib/3d.md reference/library/3e.md → hoon/reference/stdlib/3e.md reference/library/3f.md → hoon/reference/stdlib/3f.md reference/library/3g.md → hoon/reference/stdlib/3g.md reference/library/4a.md → hoon/reference/stdlib/4a.md reference/library/4b.md → hoon/reference/stdlib/4b.md reference/library/4c.md → hoon/reference/stdlib/4c.md reference/library/4d.md → hoon/reference/stdlib/4d.md reference/library/4e.md → hoon/reference/stdlib/4e.md reference/library/4f.md → hoon/reference/stdlib/4f.md reference/library/4g.md → hoon/reference/stdlib/4g.md reference/library/4h.md → hoon/reference/stdlib/4h.md reference/library/4i.md → hoon/reference/stdlib/4i.md reference/library/4j.md → hoon/reference/stdlib/4j.md reference/library/4k.md → hoon/reference/stdlib/4k.md reference/library/4l.md → hoon/reference/stdlib/4l.md reference/library/4m.md → hoon/reference/stdlib/4m.md reference/library/4n.md → hoon/reference/stdlib/4n.md reference/library/4o.md → hoon/reference/stdlib/4o.md reference/library/5a.md → hoon/reference/stdlib/5a.md reference/library/5b.md → hoon/reference/stdlib/5b.md reference/library/5c.md → hoon/reference/stdlib/5c.md reference/library/5d.md → hoon/reference/stdlib/5d.md reference/library/5e.md → hoon/reference/stdlib/5e.md reference/library/5f.md → hoon/reference/stdlib/5f.md reference/library/5g.md → hoon/reference/stdlib/5g.md reference/library/_index.md → hoon/reference/stdlib/_index.md reference/library/table-of-contents.md → hoon/reference/stdlib/table-of-contents.md tutorials/hoon/hoon-school/style.md → hoon/reference/style.md introduction.md+1 tutorials/hoon/graph.md → landscape/apiref/graph.md tutorials/concepts/arch.md → landscape/arch.md tutorials/nock/_index.md → nock/_index.md tutorials/nock/definition.md → nock/definition.md tutorials/nock/example.md → nock/example.md tutorials/nock/explanation.md → nock/explanation.md tutorials/nock/implementations.md → nock/implementations.md reference/_index.md → old/reference/_index.md reference/hoon-expressions/_index.md → old/reference/hoon-expressions/_index.md reference/vane-apis/_index.md → old/reference/vane-apis/_index.md tutorials/_index.md−27 tutorials/arvo/_index.md−49 tutorials/arvo/ford.md−9 tutorials/concepts/_index.md−11 tutorials/concepts/technical-overview.md−172 tutorials/creating-an-invite-pool.md−39 tutorials/guide-to-breaches.md−90 tutorials/hoon/_index.md−16 tutorials/ship-troubleshooting.md−212 tutorials/vere/_index.md → vere/_index.md tutorials/vere/api.md → vere/api.md tutorials/vere/c.md → vere/c.md tutorials/vere/jetting.md → vere/jetting.md tutorials/vere/nouns.md → vere/nouns.md tutorials/vere/runtime.md → vere/runtime.md
reference/vane-apis/ames.md → arvo/ames/ames-api.mdrenamed

The content is the same.

tutorials/arvo/ames.md → arvo/ames/ames.mdrenamed

The content is the same.

tutorials/arvo/arvo.md → arvo/arvo.mdrenamed

The content is the same.

reference/vane-apis/behn.md → arvo/behn/behn-api.mdrenamed

The content is the same.

tutorials/arvo/behn.md → arvo/behn/behn.mdrenamed

The content is the same.

tutorials/arvo/clay.md → arvo/clay/clay.mdrenamed

The content is the same.

reference/vane-apis/dill.md → arvo/dill/dill-api.mdrenamed

The content is the same.

tutorials/arvo/dill.md → arvo/dill/dill.mdrenamed

The content is the same.

tutorials/arvo/eyre.md → arvo/eyre/eyre.mdrenamed

The content is the same.

reference/vane-apis/gall.md → arvo/gall/gall-api.mdrenamed

The content is the same.

tutorials/arvo/gall.md → arvo/gall/gall.mdrenamed

The content is the same.

reference/vane-apis/iris.md → arvo/iris/iris-api.mdrenamed

The content is the same.

reference/vane-apis/jael.md → arvo/jael/jael-api.mdrenamed

The content is the same.

tutorials/arvo/move-trace.md → arvo/move-trace.mdrenamed

The content is the same.

tutorials/advanced-azimuth-tools.md → azimuth/advanced-azimuth-tools.mdrenamed

The content is the same.

tutorials/concepts/azimuth.md → azimuth/azimuth.mdrenamed

The content is the same.

reference/vane-apis/airlock.md → development/airlock.mdrenamed

The content is the same.

development/develop.mdnew file+117
@@ -0,0 +1,117 @@
1++++
2+title = "Developer's Guide"
3+description = "How to get started developing on Urbit."
4+weight = 3
5+template = "page_indiced.html"
6+aliases = ["/docs/using/creating-a-development-ship/", "/docs/getting-started/contributing"]
7++++
8+
9+You can develop on Urbit in three ways:
10+
11+- [Applications using Urbit](#api), which use Urbit as the back-end to store data and communicate with others
12+- [Urbit Applications](#application), which are written in [Hoon](/docs/glossary/hoon/), and run as part of Urbit
13+- [Urbit Core](#core), which involves contributing to Urbit's operating system ([Arvo](https://github.com/urbit/urbit/tree/master/pkg/arvo)) or runtime ([Vere](https://github.com/urbit/urbit/tree/master/pkg/urbit))
14+
15+This guide will start by getting you set up to run an Urbit ship, and then tell you everything you need to know to do either.
16+
17+### Setting up your environment
18+
19+We assume you’ve gotten a basic introduction to Urbit. If you haven’t, read the [Understanding Urbit](@/understanding-urbit/_index.md) series.
20+
21+Once you’re ready, you can get started on the network right away and take some first steps, without acquiring an identity, by [creating a comet](@/using/install.md#comet).
22+
23+When developing, however, we recommend [booting a development ship](#creating-a-development-ship) and working locally -- you may need to make changes that could, in the wrong hands, destroy the ship’s environment, and it’s best to do so in a safe, separate place.
24+
25+## Applications using Urbit {#api}
26+
27+Urbit ships with its own set of apps written in its own language, Hoon. However it is also meant to integrate with applications written in other languages via an API. The clearest example of an application using Urbit is Landscape, the default client. Although it does currently ship with Urbit, its front-end is a separate piece of software that uses Urbit's HTTP APIs to interact with an Urbit ship. You can create your own application that uses Urbit to store data and interact with other Urbit ships without writing any Hoon code thanks to Urbit's HTTP APIs. This could be a chat client, a writing app, a game, or anything else that can communicate over HTTP.
28+
29+To get started quickly with the language of your choice, see the following libraries that provide HTTP interfaces to Urbit:
30+
31+ - [Python](https://github.com/baudtack/urlock-py) (Stable)
32+ - [Swift](https://github.com/dclelland/UrsusAirlock) (Under development)
33+ - [Haskell](https://github.com/bsima/urbit-airlock) (Under active development)
34+ - [JavaScript](https://www.npmjs.com/package/urbit) (Under active development)
35+ - Go (Pending release)
36+
37+[View details about using the API or creating your own implementation here.](/using/integrating-api/)
38+
39+## Urbit Applications {#application}
40+
41+Urbit applications are still young, but can be fun to experiment with.
42+
43+When creating user applications on Urbit, you aren’t tied to any particular user interface. They can work without providing a response to the user, or by printing to the Dojo, or with an interface in Landscape, which uses [Eyre](@/docs/tutorials/arvo/eyre.md) (the Arvo vane that serves HTTP to serve a React-based interface to the application through a web browser).
44+
45+When writing applications, you will often make use of [Gall](@/docs/tutorials/hoon/hoon-school/gall.md), the Arvo vane that manages user applications.
46+
47+If you want to see examples of Urbit applications with common functionality requirements, you can see our [examples](https://github.com/urbit/examples) repository. If you want to get started building applications with a Landscape interface, check out our [create-landscape-app](https://github.com/urbit/create-landscape-app) repository.
48+
49+## Urbit Core {#core}
50+
51+Working on the core means improving the Urbit project itself, working with the existing community of Urbit developers. The kernel is much more stable, but generally more challenging from an engineering standpoint.
52+
53+Just arrived and unsure what to work on? An ideal way to get started is by experimenting with the system, talking to other developers, and reading (or [contributing to](https://github.com/urbit/docs)) the [documentation](/docs/).
54+
55+Prefer learning with an instructor? Our community runs an online course that covers the basics of Urbit development called [Hooniversity](https://hooniversity.org/). If course-based learning works well for you, we recommend you sign up.
56+
57+The Urbit developer community congregates around [the urbit-dev mailing list](https://groups.google.com/a/urbit.org/forum/#!forum/dev), the `~bitbet-bolbel/urbit-community` group on Landscape, and [Urbit’s GitHub repository](https://github.com/urbit/urbit). It’s a good idea to sign up, see what people are talking about, and introduce yourself.
58+
59+Once you’re comfortable working with Urbit, check out the [project’s issues on GitHub](https://github.com/urbit/urbit/issues) or some of our [contribution bounties](https://grants.urbit.org/).
60+
61+If you’re looking for some guidance, need help, or would prefer direct communication for your ideas, you can also always reach out to us directly at [support@urbit.org](mailto:support@urbit.org).
62+
63+## Creating a development ship {#creating-a-development-ship}
64+
65+To do work with Hoon and with the system, we recommended using a "fake" ship -- one not connected to the network.
66+
67+Because such a ship has no presence on the network, you don't need an Azimuth identity for its purposes. You just need to have [installed our software](/using/install).
68+
69+To create a fake ship named `~zod`, run the command below. You can replace `zod` with any valid Urbit ship-name.
70+
71+```
72+./urbit -F zod
73+```
74+
75+Now you should see a block of boot messages, starting with the Urbit version number. Welcome!
76+
77+## Community tutorials {#community-tutorials}
78+
79+Here are some tutorials written by members of the Urbit community.
80+
81+- [A Nock Interpreter](https://jtobin.io/nock) by `~nidsut-tomdun`
82+- [Basic Hoonery](https://jtobin.io/basic-hoonery) by `~nidsut-tomdun`
83+- [The Complete Guide to
84+ Gall](https://github.com/timlucmiptev/gall-guide/blob/master/overview.md) by
85+ `~timluc-miptev`
86+- [Nock for Everyday Coders](https://blog.timlucmiptev.space/part1.html) by `~timluc-miptev`
87+- [Rote - An Annotated Flashcard App](https://github.com/lukechampine/rote)
88+
89+If you want to add something to the list, [shoot us an email](mailto:support@urbit.org) or make a pull request in the [docs repository](https://github.com/urbit/docs).
90+
91+## How else can I contribute? {#how}
92+
93+The Urbit project is a global community of developers, users, and fans. If you’re interested in getting involved, there’s space for you; you don’t have to be a developer to be a part of the project.
94+
95+### Running stars and galaxies
96+
97+There are two ways to participate in the Arvo network: as a user running a planet and as an infrastructure provider running a galaxy or a star.
98+
99+For planets, Urbit is a peer-to-peer network where users can interact with each other via Landscape, or using custom applications that anyone can write.
100+
101+Running a planet helps build Urbit’s community, surfaces bugs, and helps core developers improve Urbit under realistic conditions.
102+
103+Stars and galaxies, however, have additional responsibilities and play a role in peer discovery as well as star and planet distribution. You can think of stars and galaxies as similar to the DNS system in the modern Internet. Most users don’t know it exists, but without it, the web wouldn’t work at all.
104+
105+Running a reliable galaxy or star, and spawning stars and planets from them, are excellent ways to help bootstrap the Urbit network.
106+
107+If you’re interested in running a galaxy or star, you’ll be reliably providing peer discovery for your children just by running your node – and we’re doing our best to make this both easy and profitable. If you’re interested in this, see [Star and Galaxy Operations](@/using/operations/stars-and-galaxies.md).
108+
109+If you’re interested in distributing planets, read on.
110+
111+### Distribute points
112+
113+Want to get your friends and family into Urbit? Distribute planets using Bridge with a feature called **delegated sending**.
114+
115+Here’s how it works: any star can grant a number of invites to any of its child planets. Those planets can then send one-time-use invite codes via email to anyone of their choosing.
116+
117+For instructions on how to grant and send invites, check out [Using Bridge](@/using/operations/using-bridge.md).
development/integrating-api.mdnew file+224
@@ -0,0 +1,224 @@
1++++
2+title = "Integrating with Urbit for Developers"
3+description = "How to use Urbit's API."
4+weight = 4
5+template = "page_indiced.html"
6++++
7+
8+This guide is aimed at developers who have a working knowledge of HTTP grammar (`PUT`, `GET`), and should not require any special knowledge of Urbit's internals. To learn more about a specific application within Urbit, please search for that with the docs once you have finished this guide.
9+
10+## Authentication
11+
12+The first step in creating an application *on* Urbit (to be distinguished from an Urbit application) is to authenticate with the desired ship. This can be a planet, comet, or any other Urbit ship. For the purposes of this example, we will be running a "fakezod" on port 8080. Run this code, substituting the appropriate path to your Urbit binary:
13+
14+```bash
15+/path/to/urbit -p 8080 -F zod
16+```
17+
18+(for the unfamiliar, this will create a folder named "zod" in your working directory, from which the ship will run. Use `/path/to/urbit -p 8080 zod` in the future)
19+
20+You can run `+code` in the dojo to get the key, but a fakezod's key is always `lidlut-tabwed-pillex-ridrup`. This is our password, our API token that we will use.
21+
22+Run this code in your bash terminal (requires cURL):
23+
24+```bash
25+curl -i localhost:8080/~/login -X POST -d "password=lidlut-tabwed-pillex-ridrup"
26+```
27+Let's explain what this does:
28+
29+ - `-i` displays the headers, so that you can see the cookie that gets sent
30+ - `localhost:8080/~/login` is the URL to which you are POSTing. You will note this is also the URL you visit when you log into Landscape.
31+ - `-X POST` specifies that you are POSTing data, not GETting.
32+ - `-d "password=lidlut-tabwed-pillex-ridrup"` specifies the key for your Urbit that we retrieved above. It is sent as form data, as if it were sent from an HTML form input field (which it is in Landscape)
33+
34+You should see the following:
35+
36+```bash
37+HTTP/1.1 200 ok
38+Date: Sun, 01 Jan 2020 00:00:00 GMT
39+Connection: keep-alive
40+Server: urbit/vere-0.10.8
41+set-cookie: urbauth-~zod=0v3.fvaqc.nnjda.vude1.vb5l6.kmjmg; Path=/; Max-Age=604800
42+transfer-encoding: chunked
43+```
44+
45+The `Date` and `set-cookie` will be slightly different of course.
46+
47+Take a look at the `set-cookie` line. This is now your session authentication, and will need to be sent with any future requests. It consists of three parts:
48+
49+ - `urbauth` is a prefix that Eyre uses to check for presence of authentication
50+ - `~zod` is the name of the ship you are logging in as
51+ - `0v3.fvaqc.nnjda.vude1.vb5l6.kmjmg` is the actual authentication token.
52+
53+At present there is no way to separate these parts — you must pass a cookie *as* a cookie. This string must be in the `Cookie` header. The `set-cookie` header is only used for this request upon response. It is what browsers expect when receiving a cookie.
54+
55+## Interacting with Urbit
56+
57+Once authenticated, you will perform all your operations on a channel. You may open as many channels as needed using the same authentication token, but this will increase complexity and memory usage on your Urbit ship.
58+
59+Interacting with Urbit comprises two parts:
60+
61+1. Sending information via PUT requests, which receive HTTP status code `204` (no content) upon success. We will not receive updated information (as in a POST request).
62+2. Receiving data on channels, which must first be subscribed to via an initial request. These come in the form of SSEs ([Server-Sent Events](https://www.w3.org/TR/eventsource/))
63+
64+These can be used independently, i.e. you may choose to only send information or only receive information from your Urbit, based on your application. Both can take place on the same channel.
65+
66+### Creating a Channel
67+
68+For this example, we will use the following channel:
69+
70+```
71+http://localhost:8080/~/channel/1601844290-ae45b
72+```
73+
74+Let's examine the parts. A channel is simply a URL in this pattern: `{url}/~/channel/{uid}` where `{uid}` is a string of your choosing. Most libraries default to the current unix time plus six hexadecimal characters. Your program should determine a channel for its current session and store that in its state.
75+
76+The channel does not yet exist in Urbit, however. To subscribe to events on this URL, you must first make a request (PUT) to Urbit on this URL. The simplest way to do this is to `hi` ourselves, as if we had entered `|hi our` in the dojo. A `hi` is analogous to a ping, and does not manipulate state. Let's learn how to make requests using this as an example.
77+
78+### Making Requests
79+
80+All requests will take the form of sending a message. Messages can take different forms, such as `subscribe`s, `ack`s, and `poke`s. These are called actions and there are more than these, but these will cover most basic use cases. You can think of them as a somewhat more sophisticated HTTP grammar. A message always requires an `id` and an `action`. Other fields depend on the specific action.
81+
82+Let's look at the structure of a message by examining the most basic `hi` we will send.
83+
84+```js
85+{
86+ 'id': 1, // Required. A sequential ID. Keep track of which messages you have sent.
87+ 'action': 'poke', // Required. The action to take. poke is the most basic way of sending data, like HTTP POST
88+ 'ship': 'zod', // Required by poke. The ship on which to perform the poke. You can only poke foreign ships with JSON, but this is the authenticated ship.
89+ 'app': 'hood', // Required by poke. The Urbit app to which to send the data.
90+ 'mark': 'helm-hi', // Required by poke. The "mark," or type, of data being sent.
91+ 'json': 'Opening airlock' // Required by poke. The actual data being sent.
92+}
93+```
94+
95+Let's open our channel by sending the following request using cURL (**remember to change the cookie**):
96+
97+```bash
98+curl --header "Content-Type: application/json" \
99+ --cookie "urbauth-~zod=0v3.fvaqc.nnjda.vude1.vb5l6.kmjmg" \
100+ --request PUT \
101+ --data '[{"id":1,"action":"poke","ship":"zod","app":"hood","mark":"helm-hi","json":"Opening airlock"}]' \
102+ http://localhost:8080/~/channel/1601844290-ae45b
103+```
104+
105+If you switch to your fakezod's dojo, you should see `< ~zod: Opening airlock`.
106+
107+Note that in the JSON that we sent via `--data`, the payload is wrapped in `[]`. This is because we can send multiple messages in a single payload, and Eyre expects a list of items, even if we are only sending one.
108+
109+You will always receive a `204` status code if the `PUT` request successfully reached Urbit, authentication succeeded, and the payload was valid. This is merely an HTTP status code, however. If the request failed within Urbit itself, however, you will receive a "nack" event that you will have to process separately.
110+
111+Let's look at how to receive events from Urbit.
112+
113+### Subscribing to Events
114+
115+Now that Urbit has opened an Eyre channel at our URL, we can watch for events on that URL by sending a `subscribe` message. Let's look at the anatomy of a `susbcribe`:
116+
117+```js
118+{
119+ 'id': 2, // Required. This is the next message we are sending, so we give it the next ID.
120+ 'action': 'subscribe', // Required.
121+ 'ship': 'zod', // Required by subscribe.
122+ 'app': 'chat-view', // Required by subscribe. In this case, we want to watch events that occur in the chat-view app, which is responsible for handling incoming chats.
123+ 'path': '/primary' // Required by subscribe. All apps have different path structures. In the case of chat-view, this is where we see all incoming chats.
124+}
125+```
126+
127+This is all we need to send Urbit to say "On this URL through which I am sending information, send me SSEs whenever something occurs on this app at this path."
128+
129+You should be able to send this information if you were able to send the above cURL example. However, we now need to be able to listen to the SSEs. The `EventSource` object is available for JavaScript in the browser context, as this is why SSEs were invented, but there should be a library for it in your chosen language. Take a look at a Browser JavaScript example:
130+
131+```js
132+const eventSource = new EventSource('http://localhost:8080/~/channel/1601844290-ae45b', {
133+ withCredentials: true // Required, sends your cookie
134+});
135+
136+eventSource.addEventListener('message', function (event) {
137+ ack(Number(event.lastEventId)); // See section below
138+ const payload = JSON.parse(event.data); // Data is sent in JSON format
139+ payload.id === event.lastEventId; // The SSE spec includes event IDs. This information is duplicated in the payload.
140+ const data = payload.json; // Beyond this, the actual data will vary between apps
141+});
142+
143+eventSource.addEventListener('error', function (event) {
144+ handleError(event);
145+});
146+
147+```
148+
149+### Handling Received Events
150+
151+Once you have received an event, it is expected that you will "ack" or "acknowledge" that you have received them. To do so, simply send a message in the following format:
152+
153+```js
154+{
155+ 'id': 3, // Required. Picking up where we left off
156+ 'action': 'ack', // Required.
157+ 'event-id': 15, // Required by ack. Whichever SSE of which you are acknowledging receipt
158+}
159+```
160+
161+### Unsubscribing from Events
162+
163+You may want to stop receiving events from a particular app path, but you don't want to close the channel altogether yet. Let's look at how to do that. Take a look at the example for subscribing. We sent that message with `id: 2`. We will use that ID to cancel the relevant subscription:
164+
165+```javascript
166+{
167+ 'id': 4, // Required. We always increment the ID as we send messages.
168+ 'action': 'unsubscribe', // Required.
169+ 'subscription': 2 // Required by unsubscribe. This corresponds to the id of a subscribe message sent earlier.
170+}
171+```
172+
173+### Deleting a Channel
174+
175+You should clean up your channel when able. To do so, simply send a `delete` message and Eyre will handle the rest so your program can safely exit.
176+
177+```javascript
178+{
179+ 'id': 5, // Required.
180+ 'action': 'delete' // Required.
181+}
182+```
183+
184+## Other Operations
185+
186+There are other operations which require authentication but do not require the use of a channel. Some operations are app-specific and will not be enumerated here, but there are two operations that exist across Urbit: `scry` and `spider`.
187+
188+### Scrying
189+
190+Scrying lets you see what an app has exposed at a particular path. It does not manipulate state.
191+
192+It takes the form `{url}/~/scry/{app}{path}.{mark}`
193+
194+ Let's get the base hash of our fakezod in the same way that Landscape does it.
195+
196+```bash
197+curl --header "Content-Type: application/json" \
198+ --cookie "urbauth-~zod=0v3.fvaqc.nnjda.vude1.vb5l6.kmjmg" \
199+ --request GET \
200+ http://localhost:8080/~/scry/file-server/clay/base/hash.json
201+```
202+
203+Note the use of a `GET` request.
204+
205+In this example we're scrying the `file-server` app at the path `/clay/base/hash` and using the `json` mark, which is most common. We receive `"0"` which is correct because we are at the top level of the hierarchy using a fake ship.
206+
207+Scry will fail with a 500 or return a 404 if no data is found.
208+
209+### Running Threads with Spider
210+
211+Running threads is an exception to the rule that we outlined in the section on channels. It uses a `POST` request and both manipulates state and receives information back. It also exposes the ability to send a sequence of commands, i.e. a "thread," hence the name.
212+
213+It takes the form `{url}/spider/{inputMark}/{threadname}/{outputmark}.json`
214+
215+This should be considered an advanced technique, but the basic structure of a request can be seen here:
216+
217+```bash
218+curl --header "Content-Type: application/json" \
219+ --cookie "urbauth-~zod=0v3.fvaqc.nnjda.vude1.vb5l6.kmjmg" \
220+ --request POST \
221+ --data '[{"foo": "bar"}]' \
222+ http://localhost:8080/spider/graph-view-action/graph-create/json.json
223+
224+```
tutorials/hoon/hoon-school/aqua.md → hoon/guides/aqua.mdrenamed

The content is the same.

tutorials/hoon/cli-tutorial.md → hoon/guides/cli-tutorial.mdrenamed

The content is the same.

tutorials/hoon/parsing.md → hoon/guides/parsing.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/_index.md → hoon/hoon-school/_index.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/ackermann.md → hoon/hoon-school/ackermann.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/arms-and-cores.md → hoon/hoon-school/arms-and-cores.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/atoms-auras-and-simple-cell-types.md → hoon/hoon-school/atoms-auras-and-simple-cell-types.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/bank-account.md → hoon/hoon-school/bank-account.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/behn.md → hoon/hoon-school/behn.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/caesar.md → hoon/hoon-school/caesar.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/conditionals.md → hoon/hoon-school/conditionals.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/doors.md → hoon/hoon-school/doors.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/egg-timer.md → hoon/hoon-school/egg-timer.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/fibonacci.md → hoon/hoon-school/fibonacci.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/gall.md → hoon/hoon-school/gall.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/gates.md → hoon/hoon-school/gates.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/generators.md → hoon/hoon-school/generators.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/hoon-syntax.md → hoon/hoon-school/hoon-syntax.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/iron-polymorphism.md → hoon/hoon-school/iron-polymorphism.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/lead-polymorphism.md → hoon/hoon-school/lead-polymorphism.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/libraries.md → hoon/hoon-school/libraries.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/list-of-numbers.md → hoon/hoon-school/list-of-numbers.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/lists.md → hoon/hoon-school/lists.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/molds.md → hoon/hoon-school/molds.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/nouns.md → hoon/hoon-school/nouns.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/recursion.md → hoon/hoon-school/recursion.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/setup.md → hoon/hoon-school/setup.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/structures-and-complex-types.md → hoon/hoon-school/structures-and-complex-types.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/the-subject-and-its-legs.md → hoon/hoon-school/the-subject-and-its-legs.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/trees-sets-and-maps.md → hoon/hoon-school/trees-sets-and-maps.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/type-checking-and-type-inference.md → hoon/hoon-school/type-checking-and-type-inference.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/type-polymorphism.md → hoon/hoon-school/type-polymorphism.mdrenamed

The content is the same.

tutorials/hoon/workbook/_index.md → hoon/hoon-school/workbook/_index.mdrenamed

The content is the same.

tutorials/hoon/workbook/bomb.md → hoon/hoon-school/workbook/bomb.mdrenamed

The content is the same.

tutorials/hoon/workbook/digits.md → hoon/hoon-school/workbook/digits.mdrenamed

The content is the same.

tutorials/hoon/workbook/eightball.md → hoon/hoon-school/workbook/eightball.mdrenamed

The content is the same.

tutorials/hoon/workbook/traffic-light.md → hoon/hoon-school/workbook/traffic-light.mdrenamed

The content is the same.

reference/hoon-expressions/advanced.md → hoon/reference/advanced.mdrenamed

The content is the same.

reference/hoon-expressions/basic.md → hoon/reference/basic.mdrenamed

The content is the same.

reference/cheat-sheet.md → hoon/reference/cheat-sheet.mdrenamed

The content is the same.

tutorials/hoon/hoon-errors.md → hoon/reference/hoon-errors.mdrenamed

The content is the same.

reference/hoon-expressions/irregular.md → hoon/reference/irregular.mdrenamed

The content is the same.

reference/hoon-expressions/limb/_index.md → hoon/reference/limbs/_index.mdrenamed

The content is the same.

reference/hoon-expressions/limb/limb.md → hoon/reference/limbs/limb.mdrenamed

The content is the same.

reference/hoon-expressions/limb/wing.md → hoon/reference/limbs/wing.mdrenamed

The content is the same.

reference/hoon-expressions/rune/_index.md → hoon/reference/runes/_index.mdrenamed

The content is the same.

reference/hoon-expressions/rune/bar.md → hoon/reference/runes/bar.mdrenamed

The content is the same.

reference/hoon-expressions/rune/buc.md → hoon/reference/runes/buc.mdrenamed

The content is the same.

reference/hoon-expressions/rune/cen.md → hoon/reference/runes/cen.mdrenamed

The content is the same.

reference/hoon-expressions/rune/col.md → hoon/reference/runes/col.mdrenamed

The content is the same.

reference/hoon-expressions/rune/constants.md → hoon/reference/runes/constants.mdrenamed

The content is the same.

reference/hoon-expressions/rune/dot.md → hoon/reference/runes/dot.mdrenamed

The content is the same.

reference/hoon-expressions/rune/ket.md → hoon/reference/runes/ket.mdrenamed

The content is the same.

reference/hoon-expressions/rune/lus.md → hoon/reference/runes/lus.mdrenamed

The content is the same.

reference/hoon-expressions/rune/mic.md → hoon/reference/runes/mic.mdrenamed

The content is the same.

reference/hoon-expressions/rune/sig.md → hoon/reference/runes/sig.mdrenamed

The content is the same.

reference/hoon-expressions/rune/terminators.md → hoon/reference/runes/terminators.mdrenamed

The content is the same.

reference/hoon-expressions/rune/tis.md → hoon/reference/runes/tis.mdrenamed

The content is the same.

reference/hoon-expressions/rune/wut.md → hoon/reference/runes/wut.mdrenamed

The content is the same.

reference/hoon-expressions/rune/zap.md → hoon/reference/runes/zap.mdrenamed

The content is the same.

reference/library/1a.md → hoon/reference/stdlib/1a.mdrenamed

The content is the same.

reference/library/1b.md → hoon/reference/stdlib/1b.mdrenamed

The content is the same.

reference/library/1c.md → hoon/reference/stdlib/1c.mdrenamed

The content is the same.

reference/library/2a.md → hoon/reference/stdlib/2a.mdrenamed

The content is the same.

reference/library/2b.md → hoon/reference/stdlib/2b.mdrenamed

The content is the same.

reference/library/2c.md → hoon/reference/stdlib/2c.mdrenamed

The content is the same.

reference/library/2d.md → hoon/reference/stdlib/2d.mdrenamed

The content is the same.

reference/library/2e.md → hoon/reference/stdlib/2e.mdrenamed

The content is the same.

reference/library/2f.md → hoon/reference/stdlib/2f.mdrenamed

The content is the same.

reference/library/2g.md → hoon/reference/stdlib/2g.mdrenamed

The content is the same.

reference/library/2h.md → hoon/reference/stdlib/2h.mdrenamed

The content is the same.

reference/library/2i.md → hoon/reference/stdlib/2i.mdrenamed

The content is the same.

reference/library/2j.md → hoon/reference/stdlib/2j.mdrenamed

The content is the same.

reference/library/2k.md → hoon/reference/stdlib/2k.mdrenamed

The content is the same.

reference/library/2l.md → hoon/reference/stdlib/2l.mdrenamed

The content is the same.

reference/library/2m.md → hoon/reference/stdlib/2m.mdrenamed

The content is the same.

reference/library/2n.md → hoon/reference/stdlib/2n.mdrenamed

The content is the same.

reference/library/2o.md → hoon/reference/stdlib/2o.mdrenamed

The content is the same.

reference/library/2p.md → hoon/reference/stdlib/2p.mdrenamed

The content is the same.

reference/library/2q.md → hoon/reference/stdlib/2q.mdrenamed

The content is the same.

reference/library/3a.md → hoon/reference/stdlib/3a.mdrenamed

The content is the same.

reference/library/3b.md → hoon/reference/stdlib/3b.mdrenamed

The content is the same.

reference/library/3c.md → hoon/reference/stdlib/3c.mdrenamed

The content is the same.

reference/library/3d.md → hoon/reference/stdlib/3d.mdrenamed

The content is the same.

reference/library/3e.md → hoon/reference/stdlib/3e.mdrenamed

The content is the same.

reference/library/3f.md → hoon/reference/stdlib/3f.mdrenamed

The content is the same.

reference/library/3g.md → hoon/reference/stdlib/3g.mdrenamed

The content is the same.

reference/library/4a.md → hoon/reference/stdlib/4a.mdrenamed

The content is the same.

reference/library/4b.md → hoon/reference/stdlib/4b.mdrenamed

The content is the same.

reference/library/4c.md → hoon/reference/stdlib/4c.mdrenamed

The content is the same.

reference/library/4d.md → hoon/reference/stdlib/4d.mdrenamed

The content is the same.

reference/library/4e.md → hoon/reference/stdlib/4e.mdrenamed

The content is the same.

reference/library/4f.md → hoon/reference/stdlib/4f.mdrenamed

The content is the same.

reference/library/4g.md → hoon/reference/stdlib/4g.mdrenamed

The content is the same.

reference/library/4h.md → hoon/reference/stdlib/4h.mdrenamed

The content is the same.

reference/library/4i.md → hoon/reference/stdlib/4i.mdrenamed

The content is the same.

reference/library/4j.md → hoon/reference/stdlib/4j.mdrenamed

The content is the same.

reference/library/4k.md → hoon/reference/stdlib/4k.mdrenamed

The content is the same.

reference/library/4l.md → hoon/reference/stdlib/4l.mdrenamed

The content is the same.

reference/library/4m.md → hoon/reference/stdlib/4m.mdrenamed

The content is the same.

reference/library/4n.md → hoon/reference/stdlib/4n.mdrenamed

The content is the same.

reference/library/4o.md → hoon/reference/stdlib/4o.mdrenamed

The content is the same.

reference/library/5a.md → hoon/reference/stdlib/5a.mdrenamed

The content is the same.

reference/library/5b.md → hoon/reference/stdlib/5b.mdrenamed

The content is the same.

reference/library/5c.md → hoon/reference/stdlib/5c.mdrenamed

The content is the same.

reference/library/5d.md → hoon/reference/stdlib/5d.mdrenamed

The content is the same.

reference/library/5e.md → hoon/reference/stdlib/5e.mdrenamed

The content is the same.

reference/library/5f.md → hoon/reference/stdlib/5f.mdrenamed

The content is the same.

reference/library/5g.md → hoon/reference/stdlib/5g.mdrenamed

The content is the same.

reference/library/_index.md → hoon/reference/stdlib/_index.mdrenamed

The content is the same.

reference/library/table-of-contents.md → hoon/reference/stdlib/table-of-contents.mdrenamed

The content is the same.

tutorials/hoon/hoon-school/style.md → hoon/reference/style.mdrenamed

The content is the same.

introduction.mdnew file+1
@@ -0,0 +1 @@
1+
tutorials/hoon/graph.md → landscape/apiref/graph.mdrenamed

The content is the same.

tutorials/concepts/arch.md → landscape/arch.mdrenamed

The content is the same.

tutorials/nock/_index.md → nock/_index.mdrenamed

The content is the same.

tutorials/nock/definition.md → nock/definition.mdrenamed

The content is the same.

tutorials/nock/example.md → nock/example.mdrenamed

The content is the same.

tutorials/nock/explanation.md → nock/explanation.mdrenamed

The content is the same.

tutorials/nock/implementations.md → nock/implementations.mdrenamed

The content is the same.

reference/_index.md → old/reference/_index.mdrenamed

The content is the same.

reference/hoon-expressions/_index.md → old/reference/hoon-expressions/_index.mdrenamed

The content is the same.

reference/vane-apis/_index.md → old/reference/vane-apis/_index.mdrenamed

The content is the same.

tutorials/_index.mddeleted−27
@@ -1,27 +0,0 @@
1−+++
2−title = "Tutorials"
3−weight = 2
4−sort_by = "weight"
5−template = "sections/docs/chapters.html"
6−aliases = ["docs/learn/"]
7−+++
8−
9−Tutorials and explanations for all the components of Urbit.
10−
11−## [Arvo](@/docs/tutorials/arvo/_index.md)
12−
13−Arvo is a clean-slate system software stack defined as a deterministic computer. An encrypted P2P network, %ames, runs on a functional operating system, Arvo, written in a strict, typed functional language, Hoon, which compiles itself to a combinator interpreter, Nock, whose spec gzips to 340 bytes.
14−
15−## [Hoon Tutorial](@/docs/tutorials/hoon/hoon-school/_index.md)
16−
17−Hoon is a high-level, statically typed, functional programming language, custom-designed for use with Urbit. For a functional language it has a surprisingly imperative style, and mastering it doesn't require knowing any advanced mathematics. The Hoon Tutorial is the best place to start if you want to learn Urbit.
18−
19−## [Nock](@/docs/tutorials/nock/_index.md)
20−
21−Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.
22−
23−## [Vere](@/docs/tutorials/vere/_index.md)
24−
25−The Nock runtime system, written in C.
26−
27−Keep reading if you're planning to work on the Urbit interpreter, you're a language implementation geek, or you don't really understand anything until you've seen the actual structs.
tutorials/arvo/_index.mddeleted−49
@@ -1,49 +0,0 @@
1−+++
2−title = "Arvo"
3−weight = 1
4−sort_by = "weight"
5−template = "sections/docs/chapters.html"
6−aliases = ["/docs/learn/arvo/"]
7−+++
8−
9−## [Arvo](@/docs/tutorials/arvo/arvo.md)
10−
11−Arvo is Urbit's functional operating system, written in [Hoon](@/docs/tutorials/hoon/hoon-school/_index.md). It's composed of modules called _vanes_:
12−
13−## Vanes
14−
15−### [Ames](@/docs/tutorials/arvo/ames.md)
16−
17−Ames is the name of our network and the vane that communicates over it. It's an encrypted P2P network composed of instances of the Arvo operating system.
18−
19−### [Behn](@/docs/tutorials/arvo/behn.md)
20−
21−Behn is our timer. It allows vanes and applications to set and timer events, which are managed in a simple priority queue.
22−
23−### [Clay](@/docs/tutorials/arvo/clay.md)
24−
25−Clay is our filesystem and revision-control system.
26−
27−### [Dill](@/docs/tutorials/arvo/dill.md)
28−
29−Dill is our terminal driver. Unix sends keyboard events to dill from the terminal, and dill produces terminal output.
30−
31−### [Eyre](@/docs/tutorials/arvo/eyre.md)
32−
33−Eyre is our HTTP server. Unix sends HTTP messages to `%eyre`, and `%eyre` produces HTTP messages in response.
34−
35−### [Ford](@/docs/tutorials/arvo/ford.md)
36−
37−Ford is our build system. It handles resources and publishing.
38−
39−### [Gall](@/docs/tutorials/arvo/gall.md)
40−
41−Gall is the vane for controlling userspace apps.
42−
43−### Iris
44−
45−Iris is our HTTP client.
46−
47−## [Move trace tutorial](@/docs/tutorials/arvo/move-trace.md)
48−
49−A walkthrough of what the Arvo kernel does to respond to a simple command.
tutorials/arvo/ford.mddeleted−9
@@ -1,9 +0,0 @@
1−+++
2−title = "Ford Fusion"
3−weight = 7
4−template = "doc.html"
5−aliases = ["/docs/learn/arvo/ford/"]
6−+++
7−
8−> This document is out of date as of 2020.07.20. In the meantime, see the [blog
9−> post](https://urbit.org/blog/ford-fusion/) about Ford Fusion.
tutorials/concepts/_index.mddeleted−11
@@ -1,11 +0,0 @@
1−+++
2−title = "Concepts"
3−weight = 1
4−sort_by = "weight"
5−template = "sections/docs/chapters.html"
6−+++
7−
8−The documents in this section are high-level introductions to the Urbit project and components thereof.
9−
10−* [Technical Overview](technical-overview): An in-the-weeds explanation of the components of the Urbit stack.
11−* [Azimuth](azimuth): An overview of Azimuth, the Urbit identity layer.
tutorials/concepts/technical-overview.mddeleted−172
@@ -1,172 +0,0 @@
1−+++
2−title = "Technical overview"
3−weight = 1
4−template = "doc.html"
5−aliases = ["/understanding-urbit/technical-overview"]
6−+++
7−
8−Urbit is a clean-slate software stack designed to implement an encrypted P2P
9−network of general-purpose personal servers. Each server on this network is a
10−deterministic computer called an 'urbit' that runs on a Unix-based virtual
11−machine.
12−
13−The current Urbit stack includes (among other things):
14−
15−- Arvo: the functional operating system of each urbit, written in Hoon.
16−- Azimuth: the Urbit identity layer, built on the Ethereum blockchain.
17−- Hoon: a strictly typed functional programming language whose standard library
18− includes a Hoon-to-Nock compiler.
19−- Nock: a low-level combinator language whose formal specification fits readably on a t-shirt.
20−- Vere: a Nock interpreter and Unix-based virtual machine that mediates between
21− each urbit and the Unix software layer.
22−
23−## Anatomy of a personal server
24−
25−Your urbit is a deterministic computer in the sense that its state is a pure
26−function of its event history. Every event in this history is a
27−[transaction](https://en.wikipedia.org/wiki/Transaction_processing); your
28−urbit's state is effectively an [ACID database](https://en.wikipedia.org/wiki/ACID).
29−
30−Because each urbit is deterministic we can describe its role appropriately in
31−purely functional terms: it maps an input event and the old urbit state to a
32−list of output actions and the subsequent state. This is the Urbit transition
33−function.
34−
35−```
36−<input event, old state> -> <output actions, new state>
37−```
38−
39−For example, one input event could be a keystroke from the terminal, say
40−`[enter]` after having already typed `(add 2 2)`; and an output action could be
41−to print in the terminal window the resulting value of a computation performed
42−when the user hit `[enter]`, in this case `4`. The input event is stored in the
43−urbit's event history.
44−
45−Events always start from outside of your urbit, whether they're local to the
46−computer running the urbit (e.g., a keystroke in the terminal) or they originate
47−elsewhere (e.g., a packet received from another urbit). When an event is
48−processed, various parts of the urbit state can be modified before the resulting
49−list of output actions is returned.
50−
51−Can output actions from your urbit cause side-effects in the outside world?
52−The answer had better be "yes," because a personal server without side effects
53−isn't useful for much. In another sense the answer had better be "no," or else
54−there is a risk of losing functional purity; your urbit cannot _guarantee_ that
55−the side effects in question actually occur. What's the solution?
56−
57−Each urbit is
58−[sandboxed](https://en.wikipedia.org/wiki/Sandbox_%28computer_security%29) in a
59−virtual machine, Vere, which runs on Unix. Code running in your urbit cannot
60−make Unix system calls or otherwise directly affect the underlying platform.
61−Strictly speaking, internal urbit code can only change internal urbit state; it
62−has no way of sending events outside of its runtime environment. Functional
63−purity is preserved.
64−
65−In practical terms, however, you don't want your urbit to be an impotent
66−[brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's why
67−Vere also serves as the intermediary between your urbit and Unix. Vere observes
68−the list of output events, and when external action is called for makes the
69−appropriate system calls itself. When external events relevant to your urbit
70−occur in the Unix layer, Vere encodes and delivers them as input events.
71−
72−### Arvo
73−
74−Arvo is a purely functional, [non-preemptive](https://en.wikipedia.org/wiki/Cooperative_multitasking)
75−OS, written in Hoon, that serves as the event manager of your urbit.
76−It can upgrade itself from over the network without downtime. The Arvo kernel
77−proper is quite simple -- it's only about 600 lines of code, excluding its
78−various modules.
79−
80−The Urbit transition function is implemented in Arvo. Upon being 'poked' by
81−Vere with the pair of `<input event, state>`, Arvo directs the event to the
82−appropriate OS module. The result of each Vere 'poke' is a pair of
83−`<output events, new state>`. Events are typed, and each has an explicit
84−call-stack structure indicating the event's source module in Arvo.
85−
86−Arvo modules are also called 'vanes'. Arvo's vanes are:
87−
88−- Ames: defines and implements Urbit's encrypted P2P network protocol, as well
89− as Urbit's identity protocol.
90−- Behn: manages timer events for other vanes.
91−- Clay: global, version-controlled, and referentially-transparent file system.
92−- Dill: terminal driver.
93−- Eyre: HTTP web client and server.
94−- Ford: typed functional build system.
95−- Gall: application sandbox and manager.
96− - Dojo (app): Shell and Hoon REPL.
97− - Talk (app): Chat client.
98−
99−### Hoon
100−
101−Hoon is a strictly typed functional programming language that compiles itself
102−to Nock and is designed to support higher-order functional programming without
103−requiring knowledge of category theory or other advanced mathematics. Haskell
104−is fun but it isn't for everybody.
105−
106−Hoon aspires to a concrete, imperative feel. To discourage the creation of
107−write-only code, Hoon forbids user-level macros and uses ASCII digraphs instead
108−of keywords. The type system infers only forward and does not use unification,
109−but is not much weaker than Haskell's. The compiler and inference engine is
110−about 3000 lines of Hoon.
111−
112−### Nock
113−
114−Nock is a low-level [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity)
115−combinator language. It's so simple that its [specification](@/docs/tutorials/nock/definition.md)
116−fits on a t-shirt. In some ways Nock resembles a nano-Lisp but its ambitions
117−are more narrow. Most Lisps are one-layer: a practical language is to be
118−created by extending a theoretically simple interpreter. The abstraction is
119−simple and the implementation is practical. Unfortunately it's far more difficult
120−to enforce both simplicity and practicality in an actual Lisp codebase. Hoon
121−and Nock are two layers: Hoon, the practical layer, compiles itself to Nock, the
122−simple layer. Your urbit runs in Vere, which includes a Nock interpreter, so it
123−can upgrade Hoon over the network without downtime.
124−
125−The Nock data model is quite simple. Every piece of data is a 'noun'. A [noun](/docs/glossary/noun/)
126−is an [atom](/docs/glossary/atom/) or a cell. An atom is any unsigned integer. A cell is an ordered
127−pair of nouns. Nouns are acyclic and expose no pointer equality test.
128−
129−### Vere
130−
131−Vere is the Nock runtime environment and Urbit VM. It's written in C, runs on
132−Unix, and is the intermediate layer between your urbit and Unix. As noted
133−earlier, Unix system calls are made by Vere, not Arvo; Vere must also encode
134−and deliver relevant external events to Arvo. Vere is also responsible for
135−implementing jets and maintaining the persistent state of each urbit.
136−
137−In principle, Vere keeps a comprehensive log of every event from the time you
138−initially booted your urbit. What happens if the physical machine loses power
139−and your urbit's state is 'lost' from memory? When your urbit restarts it will
140−replay its entire event history and totally recover its latest state from
141−scratch.
142−
143−In practice, event logs become large and unwieldy over time. Periodically a
144−snapshot of the permanent state is taken and the logs are pruned. You're still
145−able to rebuild your state in case of power outage, down to the last keystroke.
146−
147−Vere is not essential to the Urbit stack; one can imagine using Urbit on a
148−hypervisor, or even bare metal. One member of the community is even working on
149−an independent implementation of Urbit using Graal/Truffle on the JVM.
150−
151−The Urbit stack (compiler, standard library, kernel, modules, and applications,
152−but excluding Vere) is about 30,000 lines of Hoon. Urbit is patent-free and MIT
153−licensed.
154−
155−### Azimuth
156−
157−Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum
158−blockchain, used as a decentralized ledger for what are known as **Urbit
159−identities**, or simply **identities**. Having an identity is necessary to use
160−the Urbit network, which makes it important to have a neutral ledger to
161−determine who owns what.
162−
163−Azimuth is not, however, part of the Urbit stack. Azimuth is a parallel system
164−that can be used as a generalized identity system for other projects. Azimuth
165−"touches" the Urbit ecosystem when an Urbit identity is used to boot a virtual
166−computer on the Arvo network for the first time. When that happens, the identity
167−considered **linked** to Azimuth and the identity's full powers are available
168−for use. Once an identity is linked, it cannot be unlinked.
169−
170−A metaphor might make the relationship between these two systems to understand:
171−Azimuth is the bank vault that stores the deed to your house. The Urbit network
172−is the neighborhood that you live in.
tutorials/creating-an-invite-pool.mddeleted−39
@@ -1,39 +0,0 @@
1−+++
2−title = "Creating an Invite Pool"
3−weight = 9
4−template = "doc.html"
5−+++
6−
7−If you're a star owner, you have the ability to create **invite pools**. These invite pools let you give your friends a piece of the network in the form of planets. This document will give you an explanation of how to create an invite pool and how to share it with your friends using our tool [Bridge](https://bridge.urbit.org).
8−
9−For more general tips on using your star, check out the [Star and Galaxy Operations page](https://urbit.org/using/operations/stars-and-galaxies/).
10−
11−## Anatomy of an Invite Pool
12−
13−An invite pool is a set of planet invites that can be distributed via email; each invite is worth one planet when redeemed. An invite pool can be as big as you'd like, providing that you have enough planets left to spawn. All invite pools must be created by a star, but they must be given to a planet. If you're interested in how this works technically, take a look at the [DelegatedSending.sol contract](https://github.com/urbit/azimuth/blob/master/contracts/DelegatedSending.sol).
14−
15−Keep in mind that all planets will have access to the invite pool until the invite pool is exhausted.
16−
17−For example: As `~marzod`, I spawn `~wicdev-wisryt` and give it an invite pool of 100 planets. `~wicdev-wisryt` can now send an invite to a friend at galen@tlon.io. When Galen claims his planet (`~ravmel-ropdyl`), `~ravmel-ropdyl` can now invite his friend — or 99 of them.
18−
19−## How to Invite Friends
20−
21−Giving your friends a piece of Urbit only takes a few minutes: send an invite pool to a planet, and then that planet can email an invite to a friend (or friends)
22−
23−1. Log into Bridge using your ownership address for your star.
24−
25−2. Get the name (like `~poldec-tonteg`) of the planet to whom you'd like to give invites, it can be one you control or a friend's.
26−
27−3. Click "Manage Invite Pools" to assign an invite pool to the planet. You may receive a notification that you need to assign your spawn proxy to the address of the Delegated Sending contract. This is so that the contract can send invites on your behalf when the recipient claims them.
28−
29−![](https://media.urbit.org/docs/invite-pool/browser-point.png)
30−
31−4. Enter the planet name and the number of invites you'd like to assign them.
32−
33−![](https://media.urbit.org/docs/invite-pool/browser-create-pool.png)
34−
35−5. If you control the planet that you gave the invite pool to, it should be accessible from the Bridge homepage. Click the Planet, then "Invite" to create invites for your friends.
36−
37−![](https://media.urbit.org/docs/invite-pool/browser-invite.png)
38−
39−Your friend will get an email shortly with your gift of an identity for life!
tutorials/guide-to-breaches.mddeleted−90
@@ -1,90 +0,0 @@
1−+++
2−title = "Guide to Breaches"
3−weight = 10
4−template = "doc.html"
5−+++
6−
7−An important concept on the [Ames](@/docs/tutorials/arvo/ames.md) network is that of continuity. Continuity refers to how ships remember the order of their own network messages and the network messages of others -- these messages are numbered, starting from zero. A _breach_ is when ships on the network agree to forget about this sequence and treat one or more ships like they are brand new.
8−
9−There are two kinds of breaches: **personal breaches** and **network breaches**.
10−
11−## Personal Breaches
12−
13−Ships on the Ames network sometimes need to reset their continuity. A personal breach is when an individual ship announces to the network: "I forgot who I am, let's start over from scratch." That is, it clears its own event log and sends an announcement to the network, asking all ships that have communicated with it to reset its networking information in their state. This makes it as though the ship was just started for the first time again, since everyone on the network has forgotten about it.
14−
15−Personal breaches often fix connectivity issues, but should only be used as a
16−last resort. Before performing a personal breach, look at alternative fixes in
17−the [Ship Troubleshooting](../ship-troubleshooting) guide. Also reach out for
18−help in the Help channel in the Urbit Community group
19−`~bitbet-bolbel/urbit-community`, or, failing that, in the
20−`#ship-starting-support` channel in our [Discord
21−server](https://discord.gg/n9xhMdz) to see if there is another option.
22−
23−There are two types of personal breaches - one where your Ethereum ownership address
24−remains the same, and one where you are switching to a new Ethereum ownership
25−address. We make the emphasis about the Ethereum _ownership_ address as
26−changing your [proxies](@/docs/glossary/proxies.md) does not require a breach.
27−
28−If you will be keeping the same Ethereum ownership address and would like to perform a
29−personal breach, follow the steps below.
30−
31−- Go to [bridge.urbit.org](https://bridge.urbit.org) and log into your identity.
32−- Click on `OS: Urbit OS Settings` at the bottom, then click `Reset Networking Keys`.
33−- Check the `Breach Continuity` box. Click `Reset Networking Keys`, and then click `Send Transaction` and wait for the progress bar to appear.
34−- Download your new keyfile following these instructions: [Generate your
35− keyfile](@/using/operations/using-bridge.md#generate-your-keyfile).
36−- Delete or archive your old [pier](@/docs/glossary/pier.md).
37−- Proceed to [boot your ship](@/using/install.md#boot-your-planet) with the new keyfile.
38−- Delete your keyfile after successfully booting.
39−- Rejoin your favorite chat channels and subscriptions.
40−
41−If you are switching to a new Ethereum ownership address you will have the
42−choice as to whether or not you want to breach. This is to cover the case when
43−you are transferring to another address you own. The process here is slightly different.
44−
45−- Go to [bridge.urbit.org](https://bridge.urbit.org) and log into your identity.
46−- Click on `ID: Identity and security settings` at the bottom, then click
47− `Transfer this point`.
48−- Enter the new Ethereum address you would like to transfer ownership to. Click
49− `Generate & Sign Transaction`, then click `Send Transaction` and wait for the
50− progress bar to complete.
51−- Logout of your current session in Bridge by clicking `Logout` at the top, and
52− then login to your new ownership address.
53−- From here, following the directions on how to [Accept your
54− transfer](@/using/operations/using-bridge.md#accept-your-transfer), [Set your
55− networking keys](@/using/operations/using-bridge.md#set-your-networking-keys),
56− and [Generate your
57− keyfile](@/using/operations/using-bridge.md#generate-your-keyfile). The option
58− whether or not to breach is in the Accept your Transfer step.
59−- Delete or archive your old [pier](@/docs/glossary/pier.md).
60−- Proceed to [boot your ship](@/using/install.md#boot-your-planet) with the new keyfile.
61−- Delete your keyfile after successfully booting.
62−- Rejoin your favorite chat channels and subscriptions.
63−
64−Performing a personal breach on your ship increments an integer value called
65−your ship's _life_ by one, which refers to your ship's [Azimuth](@/docs/tutorials/concepts/azimuth.md) _key
66−revision number_. This value is utilized by
67−Ames and Jael to ensure that you are
68−communicating with a ship created using its most recent set of keys. Your
69−ship's life is written at the end of the name of its keyfile, e.g.
70−`sampel-palnet-4.key`. Changing the Etherum address that holds the Urbit ID,
71−called _reticketing_, increments a number called the ship's _rift_ by one in
72−addition to incrementing your ship's life.
73−Rift refers to your ship's Azimuth _continuity number_.
74−
75−You can check your current life and rift number by running the
76−`+keys our` generator in Dojo. You can inspect another ship's life and rift can be checked by
77−running `+keys ~sampel-palnet`.
78−
79−
80−## Network Breaches
81−
82−A network breach is an event where all ships on the network are required to update to a new continuity era. Network breaches happen when an Arvo update is released that is too large to release over the air. The current continuity era is given by a value in Ames, our networking vane, that is incremented when a network breaches; only ships with the same such value are able to communicate with one another.
83−
84−If a network breach is happening, follow the steps below.
85−
86−- Delete your old Urbit binary.
87−- Delete or archive your old pier.
88−- Download the new Urbit binary by following the instructions in the [Install page](@/using/install.md).
89−- Create a new pier by booting your ship with your key, according to the instructions on the install page. (Note: You do _not_ need to use a new key to boot into a new continuity era.)
90−- Rejoin your favorite chat channels and subscriptions.
tutorials/hoon/_index.mddeleted−16
@@ -1,16 +0,0 @@
1−
2−+++
3−title = "Hoon"
4−weight = 1
5−sort_by = "weight"
6−template = "sections/docs/hoon.html"
7−aliases = ["/docs/byte/0/", "/docs/byte", "/docs/learn/hoon/hoon-tutorial/"]
8−+++
9−
10−This section contains material for learning Hoon. For newbies, we recommend
11−going through the [Hoon School](@/docs/tutorials/hoon/hoon-school/_index.md)
12−series, and consider enrolling in Hooniversity, a regularly held community-run
13−course which follows along the Hoon School curriculum and may be found at [Hooniversity](https://hooniversity.org/).
14−
15−The other tutorials found in this section are also valuable material for
16−learning Hoon, but are not a part of the linearly organized Hoon school path.
tutorials/ship-troubleshooting.mddeleted−212
@@ -1,212 +0,0 @@
1−+++
2−title = "Ship Troubleshooting"
3−weight = 8
4−template = "doc.html"
5−aliases = ["docs/using/ship-troubleshooting/"]
6−+++
7−
8−Urbit is still in the development stage, so there's a chance that your ship won't start properly, or will stop working properly when you're running it. That's ok! This document is intended to help you in such an event.
9−
10−This page contains resolutions to many of the most commonly encountered issues.
11−If your issue is not covered here, please check out our [Troubleshooting Knowledgebase](https://github.com/urbit/support/wiki).
12−
13−## Table of Contents
14−
15−- [Best practices](#best-practices)
16−- [Operation issues](#operation-issues)
17−- [Connectivity issues](#connectivity-issues)
18−- [Booting issues](#booting-issues)
19−- [Crashing issues](#crashing-issues)
20−
21−## Best Practices {#best-practices}
22−
23−An ounce of prevention is worth a pound of cure, so let's first go over some best practices to keep your ship in working order.
24−
25−### Only boot with your keyfile once
26−
27−Once your ship is booted with your keyfile, you should never use that same keyfile again. If you do boot with the same keyfile twice, any other ship on the network that your ship has communicated with will not be able to talk to your ship.
28−
29−If you accidentally booted with the same keyfile twice, the only remedy is performing a [personal breach](#personal-breach), which is explained in the next section.
30−
31−### Do not delete your pier
32−
33−Urbit is stateful, meaning that it needs to hold onto all your data. If you delete your pier and start your ship again, you won't be able to talk to any ship you've talked to before. The only solution to this is performing a [personal breach](#personal-breach)
34−
35−### Keep track of the directory that you put your ship in
36−
37−When you first start your ship, you should make sure you put it a place where you can find it again and where it won't get accidentally deleted. Remember that you must perform `|mount %` in your ship's Dojo to make your ship visible as a directory in the Unix file system.
38−
39−### Keep up-to-date builds
40−
41−Check for latest Urbit version at https://github.com/urbit/urbit/releases. If you're behind, update using [this guide](@/using/install.md#updating).
42−
43−### `|hi` your star to see if you're connected
44−
45−Find out who your star is by running `(sein:title our now our)` in the Dojo. Then, run `|hi ~star`, where `~star` is the star's name, and if things are working properly, you should get the message `hi ~star successful`. It could also be helpful to use `|hi` to check connectivity with `~zod` or another planet that you're in a Chat channel with.
46−
47−### Turn your ship off and on again
48−
49−Use `ctrl-d` to gracefully exit your ship, and then start it again. This can solve many issues.
50−
51−### Use the `|knob` command to customize your error messages
52−
53−Error messages can be by overwhelming, so the `|knob` command is intended to remedy this. It's used to silence errors that aren't important.
54−
55−The command takes two arguments, and comes in the form of `|knob %error-tag %level`.
56−
57−`%error-tag` is the name of the error in question. It's usually printed at the top of the stack trace, such as in `crud: %hole event failed` -- `%hole` here is an example of an error tag.
58−
59−`%level` determines how much you will see of errors with your chosen `%error-tag`. There are three levels:
60−
61−- `%hush`: no output.
62−- `%soft`: one line of output, just containing the error tag.
63−- `%loud`: full output.
64−
65−So for example, to silence all Ames packet-related errors, try `|knob %hole %hush`.
66−
67−### Perform a personal breach. {#personal-breach}
68−
69−A personal breach is when a ship tells all the other ships that have communicated with it to treat it as though the ship was just started for the first time again, since everyone on the network has forgotten about it.
70−
71−Personal breaches often fix connectivity issues, but should only be used as a
72−last resort. To find out how to perform a personal breach, check out our [Guide
73−to Breaches](../guide-to-breaches). Before taking such a drastic measure, try
74−other methods in this guide. You can also ask for help on
75−in the Help channel in the Urbit Community group at `~bitbet-bolbel/urbit-community` or, failing that, in the `#ship-starting-support`
76−channel in our [Discord server](https://discord.gg/n9xhMdz).
77−
78−### Reset `+code`
79−
80−You login to Landscape using the camel-case phrase obtained from dojo by
81−entering `+code`. For security reasons you may wish to change this code
82−regularly. You may do so by entering `|code %reset` into dojo. Doing this
83−will prevent [Bridge](@/docs/glossary/bridge.md) from being to derive your code,
84−meaning you will only be able to check it from dojo in the future.
85−
86−## Operation Issues {#operation-issues}
87−
88−### My urbit is very slow
89−
90−Run `|wash-gall`. This clears caches in Gall, and may result in steep performance improvements.
91−
92−### My urbit is frozen
93−
94−Sometimes this happens if you're processing a very large event, or if you're in an infinite loop, or for a variety of other reasons.
95−
96−Before doing anything, try waiting for a minute: an event might finish processing. If it doesn't clear up, then use the Unix kill-command, `ctrl-z`, to end your ship's process. Then restart your ship.
97−
98−### When I try to type into the Dojo, it prints `dy-noprompt`
99−
100−This happens when your Dojo is waiting on a request, such as an HTTP request. You can fix it simply by typing `backspace` or (`delete` on Mac).
101−
102−### My ship doesn't recognize file changes that I make in my pier
103−
104−Since version `0.8.0`, changes no longer automatically sync between the Unix side (your pier) and your ship. To sync your file changes, you must run `|commit %desk` in your Dojo, where `%desk` is the desk you'd like to sync.
105−
106−## Connectivity Issues {#connectivity-issues}
107−
108−### I can't communicate with anyone
109−
110−You may have booted a ship with your keyfile twice in the same era. To fix this, you must perform a [personal breach](#personal-breach).
111−
112−### I don't have the latest OTA
113−
114−You can check what build your ship is on by entering `+trouble` into dojo and
115−reading the `%base` hash. If this does not match the latest hash published in
116−the `urbit-dev` mailing list, you are behind.
117−
118−Your sponsor may just be lagging behind, so sometimes this will resolve on its
119−own with patience. Otherwise, try the procedure outlined [here](https://github.com/urbit/support/wiki/Missing-OTA).
120−
121−### I keep getting an `ames` error stack-trace
122−
123−You may see a message like this one: `/~zod/home/~2019.7.22..18.55.46..83a3/sys/vane/ames:<[line column].[line column]>`. This is a clay path to a Hoon file, pointing to the line and column where an expression crashed. This kind of error might be accompanied by a `crud` message.
124−
125−This means that another ship is sending invalid packets to you. This could be because one of the ships has not updated the other ship's "life number", which is the number that starts at one and increments every time that ship performs a personal breach.
126−
127−This can happen if they have the wrong keys of yours, or if you have the wrong keys of theirs. You can figure out who has the wrong keys by running this scry command in your dojo: `.^(* %j /=life=/shipname)`, where shipname is the other ship's name. Save that information. Then, go to the [Azimuth contract on Etherscan](https://etherscan.io/address/0x223c067f8cf28ae173ee5cafea60ca44c335fecb#readContract), scroll down to `32. points`, and put in the hexadecimal representation of the other ship's `@p`. You can find the hexadecimal representation by running ...
128−
129−```
130−`@ux`~sampel-palnet
131−```
132−
133−... in the Dojo, where `~sampel-palnet` is the other ship's name. Then, compare it to the scry information that you saved. If that information matches up, it means that the other ship is the problem. If it **doesn't** match up, your ship has wrong information about the other ship. If you have such wrong information, you can fix this by running:
134−
135−```
136−:azimuth-tracker|listen ~ %app %azimuth-tracker
137−```
138−
139−The last line above syncs from an Ethereum node for _all_ ships on the network. If you only wanted to sync with certain ships, run:
140−
141−```
142−:azimuth-tracker|listen ~[~sampel-palnet ~zod ~marzod] %app %azimuth-tracker
143−```
144−
145−`~sampel-palnet ~zod ~marzod` are example ship-names; replace these with any number of desired ships-names.
146−
147−The above commands work if you have the wrong keys of other ships. If other ships have wrong keys of _yours_, you need to somehow ask them to to run such a command.
148−
149−### I can talk to some ships, but I can't talk to my sponsor and some other ships
150−
151−This is the result of deleting your pier and starting your ship again. To fix this, you must perform a [personal breach](#personal-breach).
152−
153−## Booting Issues {#booting-issues}
154−
155−### My ship booted for the first time, but it turned into a comet instead of my planet or star
156−
157−You may have used the wrong arguments when booting your ship for the first time. Delete this comet and try again.
158−
159−### My development ship ("fakezod") gets a `boot: malformed` failure
160−
161−This means that you gave your development ship an invalid `@p`. So, you will get this error if you write, for example, `urbit -F zodzod` instead of `urbit -F zod`.
162−
163−## Crashing Issues {#crashing-issues}
164−
165−### I got a `bail` error and my ship crashed
166−
167−Try bringing it back up; it will often start working just fine again.
168−
169−However, if you get a `bail` error again, you should perform a [personal breach](#personal-breach).
170−
171−#### Making a GitHub issue out of your `bail`
172−
173−You can get help with you problem by creating an issue at [github.com/urbit/urbit](https://github.com/urbit/urbit/issues). But to make a good issue, you need to include some information.
174−
175−When your urbit crashes with a `bail`, you'll probably get a core dump, which is a file that contains the program state of your urbit when it crashed. On Mac, core dumps can be found in `/cores`. On Linux, cores can often be found in `/var/crash`, or the home directory.
176−
177−Navigate to the folder containing your core dumps. Find the most recent core dump by looking at the dates after you run `ls -l`. Then `lldb -c <corename>`. Once that loads, you'll be at an `(lldb)` prompt; type `bt` at this prompt. This will create a stack trace that looks like this:
178−
179−```
180−(lldb) bt
181−* thread #1, stop reason = signal SIGSTOP
182− * frame #0: 0x000000010583d871 urbit`_box_free + 17
183− frame #1: 0x0000000105845ee6 urbit`u3j_boot + 182
184− frame #2: 0x000000010584d1f9 urbit`u3m_boot + 89
185− frame #3: 0x000000010583d15d urbit`main + 2765
186− frame #4: 0x00007fff75cb83d5 libdyld.dylib`start + 1
187−(lldb)
188−```
189−
190−Copy this stack trace and include it in your GitHub issue.
191−
192−### My ship crashed with a `bail: meme` error.
193−
194−This means that your ship ran out of memory.
195−
196−1. Make sure you are running the latest binary if you are not already on it.
197−
198−2. Restart your ship. If you don't crash again, everything may be fine.
199−
200−3. Try the procedure outlined [here](https://github.com/urbit/support/wiki/ship-exits-with-a-bail:-meme-error).
201−
202−4. If you **do** crash again, then you should perform a [personal breach](#personal-breach).
203−
204−### My ship crashed with a `bail: oops` error
205−
206−Restart your ship. These issues often just go away on their own. If this error repeats after restart two or more times, post the messages in an issue at [github.com/urbit/urbit](https://github.com/urbit/urbit/issues).
207−
208−This same error might also appear with a message like `Assertion '0'`.
209−
210−### My ship crashed with an `pier: work error` error
211−
212−This means that the Urbit worker process has shut down for one reason or another. Just restart your ship; this is not a notable or reportable error.
tutorials/vere/_index.md → vere/_index.mdrenamed

The content is the same.

tutorials/vere/api.md → vere/api.mdrenamed

The content is the same.

tutorials/vere/c.md → vere/c.mdrenamed

The content is the same.

tutorials/vere/jetting.md → vere/jetting.mdrenamed

The content is the same.

tutorials/vere/nouns.md → vere/nouns.mdrenamed

The content is the same.

tutorials/vere/runtime.md → vere/runtime.mdrenamed

The content is the same.