on master help sign in
Add glossary to docs (#757)
55da472matildepark
_index.md+10−18
@@ -2,30 +2,22 @@
2title = "Docs"
2title = "Docs"
3template = "sections/docs.html"
3template = "sections/docs.html"
4+++
4+++
5−Welcome to the documentation for the Urbit project, including the Azimuth identity layer, the Arvo operating system, and the Hoon programming language. This documentation is maintained by [Tlon](https://tlon.io) in a public [Github repository](https://github.com/urbit/docs). Issues and contributions are welcome.
6
5
7−## Getting Started
6+Welcome to the documentation for the Urbit project. This documentation is maintained by [Tlon](https://tlon.io) in a public [Github repository](https://github.com/urbit/docs). Issues and contributions are welcome.
8
7
9−The following three guides will help get you started on Urbit.
8+### [Glossary](@/docs/glossary/_index.md)
10
9
11−### [Install Urbit](@/using/install.md)
10+We recommend getting started with the Glossary, which explains Urbit concepts in an accessible, wiki-like format. Glossary pages will point you in the direction of more substantial documentation in other sections like Tutorials and Reference, so browsing it will help you discover the rest of the docs. Also note the search box, which is a handy way to look a term up.
12
11
13−Urbit isn't ready for serious use yet, but it's available to try out. If you have an Urbit identity, you can follow this step-by-step guide to get your point's _keyfile_, which you need to boot your ship. Then you can install Urbit and join the community.
12+| Featured Glossary Terms |
13+|:--:|
14+| [Arvo](@/docs/glossary/arvo.md) - [Azimuth](@/docs/glossary/azimuth.md) - [Hoon](@/docs/glossary/hoon.md) - [Landscape](@/docs/glossary/landscape.md) - [Planet](@/docs/glossary/planet.md) - [Ship](@/docs/glossary/ship.md)|
14
15
15−### [Operator's Manual](@/using/operations/_index.md)
16
16
17−The Operator's Manual will show you how to perform everyday functions on your Urbit.
17+### [Tutorials](@/docs/tutorials/_index.md)
18
18
19−### [Developer's Guide](@/using/develop.md)
19+Tutorials contains learning materials about the system, enough where you can develop on Urbit.
20
20
21−This guide will teach you how set up an Urbit development environment.
21+### [Reference](@/docs/reference/_index.md)
22
22
23−## Documentation
24−
25−The documentation proper is contained on the sidebar of this page. It's meant for those interested in development on Urbit, and it's sorted by section:
26−
27−- [Concepts](concepts) gives an in-depth, high-level explanations of Urbit concepts.
28−
29−- [Tutorials](tutorials) contains tutorials all the details about the system, enough where you can develop on Urbit. There are sections on Arvo, the Urbit OS; Hoon, Urbit's functional programming language; Nock, the the low-level language Hoon compiles to; and Vere, the Nock interpreter that acts as the layer between Urbit and whatever system (MacOS, Linux, BSD) is running it.
30−
31−- [Reference](reference) contains technical reference documentation for Hoon and other components of the system. Keep reading if you need to look up a Hoon expression or a standard-library function.
23+Reference contains technical reference documentation for Hoon and other components of the system. Keep reading if you need to look up a Hoon expression or a standard-library function.
glossary/_index.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Glossary"
3+sort_by = "none"
4+template = "sections/docs/glossary.html"
5+[extra]
6+nav = "link"
7++++
8+
9+Short articles about key concepts in the Urbit project. Each definition connects you with more specific information within the documentation and on [urbit.org](https://urbit.org), so you can learn more about the project at your own pace.
glossary/ames.mdnew file+16
@@ -0,0 +1,16 @@
1++++
2+title = "Ames"
3+template = "doc.html"
4+[extra]
5+category = "arvo"
6++++
7+
8+**Ames** is the name of the Urbit network and the [vane](../vane) that communicates over it. It's an encrypted peer-to-peer network composed of instances of the [Arvo](../arvo) operating system. Each [galaxy](../galaxy), [star](../star), [planet](../planet), [moon](../moon), and [comet](../comet) communicates over the network utilizing the Ames protocol.
9+
10+Your ship upgrades itself with [OTA updates](../ota-updates) via communication over Ames. The web interface, [Landscape](../landscape), of ships can be accessed by typing `sampel-palnet.arvo.network` into a browser, where `sampel-palnet` is the name of your shape.
11+
12+### Further Reading
13+
14+- [The Ames tutorial](@/docs/tutorials/arvo/ames.md): An in-depth technical guide to the Ames protocol.
15+- [A Guide to Breaches](@/docs/tutorials/guide-to-breaches.md): Instructions on handling continuity breaches (resets) on the Ames network.
16+- [Ship Troubleshooting](@/docs/tutorials/ship-troubleshooting.md): General instructions on getting your ship to work, which includes network connectivity issues.
glossary/aqua.mdnew file+16
@@ -0,0 +1,16 @@
1++++
2+title = "Aqua"
3+template = "doc.html"
4+[extra]
5+category = "arvo"
6++++
7+
8+**Aqua** is something like Docker but for Urbit; it is a virtualization tool whose primary purpose is testing and development.
9+
10+Aqua is a [Gall](../gall) app that runs an [Arvo](../arvo) instance or instances in userspace. It pretends to be [Vere](../vere), and as such it loads [Pills](../pill) to boot up a virtual ship or fleet of ships and then manages them from within the parent Arvo instance. Running tests for a virtual fleet of Aqua ships is done using [pH](../ph).
11+
12+Aqua is jetted with the usual [Nock](../nock) interpreter and thus virtual ships do not run any slower than the parent ship.
13+
14+### Further Reading
15+
16+- [The Gall tutorial](@/docs/tutorials/arvo/gall.md): An technical guide to the Gall vane.
glossary/arvo.mdnew file+31
@@ -0,0 +1,31 @@
1++++
2+title = "Arvo"
3+template = "doc.html"
4++++
5+
6+**Arvo** is the Urbit operating system and kernel. Arvo's state is a pure function of its [event log](../eventlog), and it serves as the Urbit event manager. It contains [vanes](../vane), which are kernel modules that perform essential system operations. Arvo itself can only deal with one file at a time. For more, it relies on [Ford](../ford), the build-system vane.
7+
8+Arvo being purely functional means that the state of the operating system at a given moment is completely determined by the sequence of events in the event log. In other words, the state of an Arvo instance is given by a lifecycle function
9+```
10+L: History ➜ State
11+```
12+where `History` consists of the set of all possible sequences of events in an Arvo event log.
13+
14+Arvo coordinates and reloads vanes. It can be thought of as a traffic-director. Any vane needs to go through Arvo before reaching another vane. Events and their effects happen like so:
15+```
16+Unix event -> Vere -> Arvo -> vane -> Arvo
17+```
18+Here, [Vere](../vere) is the virtual machine running Urbit.
19+
20+Arvo is located in `/home/sys/arvo.hoon` within your urbit.
21+
22+Arvo vanes include [Ames](../ames) for networking, [Behn](../behn) for timing, [Clay](../clay) for filesystem and typed revision control, [Dill](../dill) for terminal driving, [Eyre](../eyre) for web services, [Ford](../ford) for building, and [Gall](../gall) for application management.
23+
24+Vanes and other programs for Arvo are written in [Hoon](../hoon).
25+
26+A ship creates its own copy of Arvo via a bootstrap sequence known as a [Pill](../pill).
27+
28+### Further Reading
29+
30+- [The Arvo tutorial](@/docs/tutorials/arvo/_index.md): An in-depth technical guide to Arvo and its vanes.
31+- [The Technical Overview](@/docs/tutorials/concepts/technical-overview.md): An overview of all of Urbit.
glossary/atom.mdnew file+18
@@ -0,0 +1,18 @@
1++++
2+title = "Atom"
3+template = "doc.html"
4+[extra]
5+category = "hoon-nock"
6++++
7+
8+An **atom** is any non-negative integer of any size. The atom is the most basic data type in [Nock](../nock) and [Hoon](../hoon).
9+
10+A Hoon atom type consists of a Nock atom with two additional pieces of metadata: an [aura](../aura) and an optional constant. A Hoon atom type is _warm_ or _cold_ based on whether or not the constant exists:
11+* An Hoon atom type is **warm** if the constant is `~` (null), any atom is in the type.
12+* An Hoon atom type is **cold** if the constant is `[~ atom]`, its only legal value is atom.
13+
14+### Further Reading
15+
16+- [The Hoon Tutorial](@/docs/tutorials/hoon/_index.md): Our guide to learning the Hoon programming language.
17+ - [Lesson 1.2: Nouns](@/docs/tutorials/hoon/nouns.md): An Hoon Tutoral lesson that explains how atoms work.
18+- [The Nock explanation](@/docs/tutorials/nock/explanation.md): Includes an explanation of atoms.
glossary/azimuth.mdnew file+18
@@ -0,0 +1,18 @@
1++++
2+title = "Azimuth"
3+template = "doc.html"
4++++
5+
6+**Azimuth** is Urbit's identity layer, built as a suite of smart contracts on the Ethereum blockchain. It is Urbit's method of securing digital identities that are required to use the [Arvo](../arvo) peer-to-peer network, without the need for a central authority. Azimuth identities exist as non-fungible tokens, which are owned by Ethereum addresses and can be transferred between such addresses. Identities can use the [claims](../claims) contract to make assertions – real-world or otherwise – about their owner.
7+
8+The primary way to interact with Azimuth and to manage your identities is through our [Bridge](bridge.urbit.org) application. Bridge is a front-end for [Ecliptic](../ecliptic), the Azimuth contract that's used to perform actions on the blockchain.
9+
10+There are a limited number of Azimuth identities which results in identities having value. This allows for identities to function as reputation primitives, since such scarcity creates an economic incentive for identities to remain static and to keep the network friendly. Undesirable behavior – spamming, scamming, and malware-spreading - will generally result in a [censure](../censure) from [galaxies](../galaxy) and [stars](../star), marking the bad actor.
11+
12+It should be noted that Azimuth isn't built just for Arvo. It can be used as an identity system for other projects.
13+
14+### Further Reading
15+
16+- [The Azimuth concepts page](@/docs/tutorials/concepts/azimuth.md): A more in-depth explanation of Azimuth, including information the storage of Urbit identities.
17+- [Install instructions](@/using/install.md): Guide to installing Urbit, which includes instructions on booting with your Urbit identity.
18+- [Understanding Urbit ID](@/understanding-urbit/urbit-id.md)
glossary/behn.mdnew file+14
@@ -0,0 +1,14 @@
1++++
2+title = "Behn"
3+template = "doc.html"
4+[extra]
5+category = "arvo"
6++++
7+
8+**Behn** is the timing [vane](../filesystem). It allows for applications to schedule events, which are managed in a simple priority queue. For example, [Clay](../clay), the Urbit filesystem, uses Behn to keep track of time-specific file requests. [Eyre](../eyre), the Urbit web vane, uses Behn for timing-out HTTP sessions.
9+
10+Behn is located in `/home/sys/vane/behn.hoon` within [Arvo](../arvo).
11+
12+### Further Reading
13+
14+- [The Behn tutorial](@/docs/tutorials/arvo/behn.md): An technical guide to the Behn vane.
glossary/bridge.mdnew file+32
@@ -0,0 +1,32 @@
1++++
2+title = "Bridge"
3+template = "doc.html"
4+[extra]
5+category = "azimuth"
6++++
7+
8+**Bridge** is a client made for interacting with [Azimuth](../azimuth). It's the recommended way to receive, send, and manage your Urbit identity, and it's by far the easiest way to generate the [keyfile](../keyfile) required to get your [ship](../ship) onto the [Arvo](../arvo) network. Most Bridge functions are accessed by "logging in" to an identity's ownership address or one of its [proxy addresses](../proxies). It's accessed at [bridge.urbit.org](https://bridge.urbit.org/).
9+
10+Below are some important functions of Bridge.
11+
12+#### View a Point
13+
14+This function allows you to view the public information of any Urbit identity, such as its ownership and proxy public keys. If you are viewing an identity that's controlled by the Ethereum address that you've accessed with Bridge, then at least some of the actions below will be available to you depending on the type of identity and what address you accessed it with.
15+
16+#### Actions
17+
18+- **Issue child:** Spawn a child from a [galaxy](../galaxy) or a [star](../star).
19+- **Transfer:** Send the Urbit identity to another Ethereum address.
20+- **Accept incoming transfer:** If someone is trying to send you an Urbit identity, you must use this action to receive it.
21+- **Cancel outgoing transfer:** Cancel a transfer that you initiated before the recipient has accepted it.
22+- **Generate Arvo keyfile:** Generate the keyfile to boot a ship with your Urbit identity.
23+- **Change spawn proxy:** Assign your spawn proxy to a new Ethereum address.
24+- **Change management proxy:** Assign your transfer proxy to a new Ethereum address.
25+- **Set network keys:** Set new authentication and encryption keys used on your Arvo ship. Will change your Arvo keyfile.
26+- **Generate Arvo keyfile:** Gets the file you need to get your ship on the Arvo network with your Urbit identity.
27+
28+### Further Reading
29+
30+- [bridge.urbit.org](https://bridge.urbit.org/): The Bridge website.
31+- [Using Bridge](@/using/operations/using-bridge.md): A guide to starting out with Bridge.
32+- [The Azimuth concepts page](@/docs/tutorials/concepts/azimuth.md): A more in-depth explanation of our identity layer.
glossary/censure.mdnew file+14
@@ -0,0 +1,14 @@
1++++
2+title = "Censures"
3+template = "doc.html"
4+[extra]
5+category = "azimuth"
6++++
7+
8+The **Censures** [Azimuth](../azimuth) contract allows [stars](../star) and [galaxies](../galaxy) to assign negative reputation information to other points of equal or lower rank. This information is publicly visible and is intended to create an economic deterrent to bad behavior.
9+
10+Positive reputation information cannot be similarly assigned to Urbit identities but it may be inferred from a lack of censures.
11+
12+### Further Reading
13+
14+- [The Censures contract](https://github.com/urbit/azimuth/blob/master/contracts/Censures.sol): The code on GitHub.
glossary/ceremony.mdnew file+8
@@ -0,0 +1,8 @@
1++++
2+title = "Ceremony"
3+template = "doc.html"
4+[extra]
5+category = "azimuth"
6++++
7+
8+The **ceremony** or **launch ceremony** was the event that transferred custody of [Azimuth](../Azimuth) identities from a centralized ledger to the Ethereum blockchain. Before the ceremony, the Tlon Corporation kept track of ownership in a spreadsheet. The ceremony created Ethereum tokens for those entries and transferred them to the appropriate [HD Wallets](../hdwallet).
glossary/chat.mdnew file+24
@@ -0,0 +1,24 @@
1++++
2+title = "chat-cli"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Chat**, also referred to as `:chat-cli`, is an application that handles communication between ships.
10+
11+There are four types of chats (lowercase) Each is a named collection of messages created by and hosted on a ship's [Hall](../hall), usually represented as `~ship-name/circle-name`. Most of Chat revolves around doing things with these chats.
12+
13+Circles are subscribed to by some number of ships which are permitted to post and retrieve messages from the circle.
14+
15+There are several default types of chats.
16+
17+ * A channel is a chat that is publicly readable and writable, with a blacklist for blocking.
18+ * A village is an invite-only chat.
19+ * A journal is publicly readable and privately writable, with a whitelist for authors.
20+ * A mailbox is readable by its owner and publicly writable, with a blacklist for blocking.
21+
22+### Further Reading
23+
24+- [Messaging guide](@/using/operations/using-your-ship.md#messaging): A guide to using Chat.
glossary/claims.mdnew file+21
@@ -0,0 +1,21 @@
1++++
2+title = "Claims"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+The **Claims** [Azimuth](../azimuth) contract allows Urbit identities to make publicly visible assertions about their owner. Such assertions are most commonly about the owner's identity, real-world or otherwise. A claim has three fields: the claim itself, the _protocol_, and the _dossier_.
10+
11+The claim itself is what you're attempting to assert the identity of, as in `@JohnDoe` for a Twitter account, or `1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa`
12+
13+The _dossier_ is the proof of a claim. It could be something like a link to a tweet from a known Twitter account saying, "Hi! I'm ~lodleb-ritrul on Azimuth," or, in the case of cryptocurrency, claim itself signed with the relevant private key.
14+
15+The _protocol_ indicates what kind of thing of the claim is. `Twitter` for a Twitter account, and `Bitcoin` for a Bitcoin address.
16+
17+Points are limited to a maximum of 16 claims. It's good practice to remove any claims associated with a ship when it is about to be transferred to a new owner.
18+
19+### Further Reading
20+
21+- [The Claims contract](https://github.com/urbit/azimuth/blob/master/contracts/Claims.sol): The code on GitHub.
glossary/clay.mdnew file+18
@@ -0,0 +1,18 @@
1++++
2+title = "Clay"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Clay** is the filesystem and typed revision-control [vane](../filesystem). It can be thought of as a continuously synced git. Clay handles file-change events and maps them from [Arvo](../arvo) to Unix and vice versa.
10+
11+A common way to use Clay is to create a pier, a directory that exists in and is visible in Unix. Changes are automatically recorded from Urbit to the Unix directory and vice versa. Just set it and forget it!
12+
13+Clay is located at `/home/sys/vane/clay.hoon` within Arvo.
14+
15+### Further Reading
16+
17+- [Using Your Ship](@/using/operations/using-your-ship.md#filesystem): A user guide that includes instructions on using Clay.
18+- [The Clay tutorial](@/docs/tutorials/arvo/clay.md): An technical guide to the Clay vane.
glossary/comet.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Comet"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **comet** is a kind of [ship](../ship) on the [Arvo](../arvo) network. They are disposable identities that will not be initially trusted by others on the network. One use might be to run bots as comets.
10+
11+Comets have no presence on [Azimuth](../azimuth) and thus have no associated Urbit identities.
12+
13+### Further reading
14+
15+- [Creating a Comet](@/using/operations/creating-a-comet.md): A guide to spinning up a comet of your own.
glossary/delegated-sending.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Delegated Sending"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+The **Delegated Sending** [Azimuth](../azimuth) contract is a way that a [star](../star ) distributes [planets](../planet). After a star configures the Delegated Sending contract as its [spawn proxy](../proxy) it can give invites to planets, and those invitees can subsequently send additional planets from that star to their friends, and pass on this invite power indefinitely. This contract keeps track of those operations in the form of the [Invite Tree](../invite-tree), so the relationship between inviters and invitees is publicly known.
glossary/desk.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Desk"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **desk** is an independently revision-controlled branch of a [ship](../ship) that uses the [Clay](../clay) filesystem. Each desk contains its own apps, [mark](../mark) definitions, files, and so forth.
10+
11+Traditionally a ship has at least a base desk and a home desk. The base desk has all the system software from the distribution, and the home desk is a fork of base with all the items specific to the user of the ship. A desk is a series of numbered commits, the most recent of which represents the current state of the desk. A commit is composed of `1` an absolute time when it was created, `2` a list of zero or more parents, and `3` a map from paths to data.
12+
13+### Further Reading
14+
15+- [Using Your Ship](@/using/operations/using-your-ship.md#filesystem): A user guide that includes instructions for using desks.
glossary/dill.mdnew file+22
@@ -0,0 +1,22 @@
1++++
2+title = "Dill"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Dill** is the terminal-driver [vane](../filesystem). You run your urbit in your Unix terminal, and Unix sends every event –⁠
10+such as a keystroke or a change in the dimensions of the terminal window –⁠ to be handled by Dill. Dill acts as an intermediary for anything that uses keyboard events, which results in a slight input lag in Urbit’s command-line interface.
11+
12+A keyboard event's journey from Unix to Dojo, the Urbit shell, can be imagined as diagrammed below:
13+
14+```
15+Keystroke in Unix -> Vere (virtual machine) -> Arvo -> Dill -> the Dojo
16+```
17+
18+Dill is located at `/home/sys/vane/dill.hoon` within [Arvo](../arvo).
19+
20+### Further Reading
21+
22+- [The Dill tutorial](@/docs/tutorials/arvo/dill.md): An technical guide to the Dill vane.
glossary/docvote.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Document Vote"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+A **document vote** is a type of [vote](../voting) action taken by the [Galactic Senate](../senate) over [Azimuth](../azimuth). By passing a document vote, [Galaxies](../galaxy) in the Senate agree legitimize a document with arbitrary content. Such a document might make claims about the state of the world; an example document that would be subject to this type of vote might be a file that says, "@urbit_senate is the official Twitter account of the senate, and is to be managed by John Doe until further notice."
glossary/ecliptic.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Ecliptic"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+The **Ecliptic** contract sets the rules for what is and is not possible on Azimuth. It's the point of entry for interacting with the [Azimuth](../azimuth) ledger data; the Azimuth contract itself is just data, and the Ecliptic contract is the logic for controlling that data. Examples of such logic include verifying permissions of the person asking to access their data, and ensuring a requested change is actually valid.
10+
11+The Senate (the voting body of [galaxies](../galaxy)) has the power to replace Ecliptic.
12+
13+### Further Reading
14+
15+- [The Dill tutorial](@/docs/tutorials/arvo/behn.md): An technical guide to the Dill van.
glossary/eventlog.mdnew file+19
@@ -0,0 +1,19 @@
1++++
2+title = "Event Log"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+The **event log** of a [ship](../ship) is a totally ordered list of every single [Arvo](../arvo) event that ship has undergone. The state of a ship is a pure function of the event log.
10+
11+The event log is maintained by [Vere](../vere).
12+
13+If the physical machine loses power and your urbit's state is 'lost' from memory, when your urbit restarts it will replay its entire event log and recover its last valid state from scratch.
14+
15+In practice event logs become large and unwieldy over time. Periodically a snapshot of the permanent state is taken and the logs are pruned. You're still able to rebuild your state in case of power outage down to the last keystroke. This is due to the practice of persistence.
16+
17+Persistence, in the context of storing data in a computer system, means that data is stored in a non-volatile manner and that input must be recorded before the output result is performed. Thus, every event must be written to disk - or must be _persisted_ - before the event effects actually take place.
18+
19+The initial entries of the event log are created during the bootstrap sequence contained in a [Pill](../pill).
glossary/eyre.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "Eyre"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Eyre** is the web-server [vane](../vane) that handles everything HTTP-related. Unix sends HTTP messages though to Eyre and Eyre produces HTTP messages in response.
10+
11+In general, apps and vanes do not call Eyre; rather, Eyre calls apps and vanes. Eyre uses [Ford](../ford) and [Gall](../gall) to functionally publish pages and facilitate communication with apps.
12+
13+Eyre is located at `/home/sys/vane/eyre.hoon` within [Arvo](../arvo).
14+
15+### Further Reading
16+
17+- [The Eyre tutorial](@/docs/tutorials/arvo/eyre.md): An technical guide to the Eyre vane.
glossary/ford.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "Ford"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Ford** is the build-system [vane](../vane). Ford is capable of sequencing generic asynchronous computations. Its uses include linking source files into programs, assembling live-updating websites, and performing file-type conversions.
10+
11+Ford neither accepts Unix events nor produces Unix effects. It exists entirely for the benefit of [Arvo](../arvo) applications and other vanes, specifically [Clay](../clay) and [Gall](../gall).
12+
13+Ford is located at `/home/sys/vane/ford.hoon` within [Arvo](../arvo).
14+
15+### Further Reading
16+
17+- [The Ford tutorial](@/docs/tutorials/arvo/ford.md): An technical guide to the Ford vane.
glossary/galaxy.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Galaxy"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **galaxy** is can be one of two related things:
10+
11+- A kind of [Azimuth](../azimuth) Urbit identity that sits at the top of the identity hierarchy. Stars, in this sense, have the power to issue [stars](../moon), meaning that all other kinds of identities ultimate derive from stars. Galaxies also form a [Senate](../senate), the governing body of Azimuth. The Senate has the power to update the logic of Azimuth by [majority vote](../voting).
12+
13+- A [ship](../ship) on the Arvo network whose identity is a planet in the former definition. In this sense, galaxies act as infrastructure for the [Arvo](../arvo) network, providing [Ames](../ames)-related services, such as peer-to-peer routing and distributing [over-the-air software updates](../ota-updates). Stars rely on galaxies for these services in the way that planets rely on stars.
14+
15+Galaxies are 8-bit, representable by numbers 0 to 255. This means that there are 256 possible galaxies; each of these galaxies is able to issue 256 [stars](../star). Galaxies have one-syllable names like `~mul` or `~lux`.
glossary/gall.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "Gall"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Gall** is the application-management [vane](../vane). Userspace apps –⁠ daemons, really –⁠ are started, stopped, and sandboxed by Gall. Gall provides developers with a consistent interface for connecting their app to [Arvo](../arvo). It allows applications and other vanes to send messages to applications and subscribe to data streams. Messages coming into Gall are routed to the intended application, and the response comes back along the same route. If the intended target is on another [ship](../ship), Gall will route it behind the scenes through [Ames](../ames) to the other ship.
10+
11+Gall is located at `/home/sys/vane/gall.hoon` within Arvo.
12+
13+### Further Reading
14+
15+- [The Hoon Tutorial](@/docs/tutorials/hoon/_index.md): Our guide to learning the Hoon programming language that will give you the foundation necessary for app development.
16+ - [Lesson 2.7: Gall](@/docs/tutorials/hoon/gall.md): An Hoon Tutorial lesson that explains how to write simple Gall app.
17+- [The Gall tutorial](@/docs/tutorials/arvo/gall.md): An technical guide to the Gall vane.
glossary/hall.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Hall"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Hall** is the former backend of [Talk](../talk), which originally combined the messaging protocol with a simple user experience. It is no longer used.
glossary/hdwallet.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "HD Wallet"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+The **Urbit HD Wallet** (_Hierarchical Deterministic_ Wallet) is a system of related Ethereum addresses that's used to store and manage an Urbit identity. Each of these Ethereum addresses have different powers over the same identity, from setting networking keys for communicating in the [Arvo](../arvo) network to transferring ownership of identities. HD Wallets are created with the [Wallet Generator](../wallet-generator) software.
10+
11+The Ethereum address that has full powers over a given Urbit identity, including the ability to transfer ownership of the identity, is called the ownership address. Ethereum addresses with fewer powers – the ability to transfer ownership being notably absent – are known as [proxies](../proxy). This scheme of compartmentalized powers allows wallet holders to only handle less valuable keys when they want to perform operations on an Urbit identity without risking their entire asset.
12+
13+If a proxy or ownership address is compromised or has its keys lost, it can always be rederived using the master ticket, which is the piece of entropy that was initially used to derive the HD wallet.
14+
15+### Further Reading
16+
17+- [The Azimuth concepts page](@/docs/tutorials/concepts/azimuth.md): A more in-depth explanation of Azimuth, including information the HD wallet.
glossary/hoon.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Hoon"
3+
4+template = "doc.html"
5++++
6+
7+Hoon is a strict, higher-order typed functional programming language that compiles itself to [Nock](../nock). As a result Hoon code is effectively implemented by the interpreter [Vere](../vere). Programs for the Urbit operating system and kernel, [Arvo](../arvo), are written in Hoon.
8+
9+The Hoon source file is located in `/home/sys/hoon.hoon` within your Urbit.
10+
11+### Further Reading
12+
13+- [The Hoon Tutorial](@/docs/tutorials/hoon/_index.md): Our guide to learning the Hoon programming language.
14+ - [Lesson 1.1: Setup](@/docs/tutorials/hoon/nouns.md): How to set up an environment for programming in Hoon.
15+- [Why Hoon?](@/blog/why-hoon.md): A blog post that explains why Urbit uses its own programming language.
glossary/invite-tree.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Invite Tree"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+The **Invite Tree** is the state stored by the [Delegated Sending](../delegated-sending) contract on [Azimuth](../azimuth), and is a record of who gave a [planet](../planet) to whom. This allows for community applications, such as a chat channel for all distantly related planets.
glossary/jacque.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Jacque"
3+
4+template = "doc.html"
5+[extra]
6+category = "hoon-nock"
7++++
8+
9+**Jacque** is a new [Nock](../nock) interpreter under development that is intended to replace the current worker process for [Vere](../vere).
10+
11+The current worker utilized by Vere is written in C, while Jacque is written using Java. The primary benefits of switching to Java are the ecosystem benefits and the fact that Java is more memory safe than C.
12+
13+### Further Reading
14+
15+- [The Vere tutorial](@/docs/tutorials/vere/_index.md): Learning information for Vere.
glossary/keyfile.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Keyfile"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+A **keyfile** is a piece of information used to associate a [ship](../ship) with an Urbit identity so that the ship can use the [Arvo](../arvo) network. A keyfile is dependent upon the [networking keys](../bridge) that have been set for the identity; we recommend using [Bridge](../bridge) to set the networking keys and to generate the corresponding keyfile.
10+
11+The keyfile is used as an argument in the command line when booting a ship. During the boot process, [Vere](../vere) passes the keyfile into the Arvo state.
12+
13+### Further Reading
14+
15+- [Installation Guide](@/using/install.md): Instructions on using a keyfile to boot a ship.
glossary/landscape.mdnew file+13
@@ -0,0 +1,13 @@
1++++
2+title = "Landscape"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Landscape** is basic social networking software for Urbit. Landscape is a user-facing messaging app built using [Gall](../gall). Similar to [Talk](../talk), Landscape has a web interface that can be accessed with a browser via [ship.arvo.network](../shiparvonetwork), ```localhost:80```, or with an iOS app.
10+
11+Landscape allows you to participate in IRC-like chats such as ```~dopzod/urbit-help```, subscribe to forum-like pages of other ships called Notebooks, and message other ships directly.
12+
13+Landscape is at frontend for the messaging protocol [Chat](../chat).
glossary/mark.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "Mark"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **mark** is a file-type in the [Clay](../clay) filesystem. A mark is a file that defines filesystem information such as type, merge routines, diff routines, and patch algorithms.
10+
11+The [Ford](../ford) [vane](../vane) converts data between marks and validates data into marks.
12+
13+
14+### Further Reading
15+
16+- [The Clay tutorial](@/docs/tutorials/arvo/clay.md): An technical guide to the Clay vane.
17+- [The Ford tutorial](@/docs/tutorials/arvo/ford.md): An technical guide to the Ford vane.
glossary/modulo.mdnew file+14
@@ -0,0 +1,14 @@
1++++
2+title = "Modulo"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Modulo** is the home screen interface for [Arvo](../arvo), and is the primary method for ordinary users to interact with Arvo and their ship without using the command line. Modulo facilitates user interaction with [Gall](../gall) apps such as [Landscape](../landscape) via a GUI written using React.js.
10+
11+### Further Reading
12+
13+- [Lesson 2.7: Gall](@/docs/tutorials/hoon/gall.md): An Hoon Tutorial lesson that explains how to write simple tile.
14+- [The Gall tutorial](@/docs/tutorials/arvo/gall.md): An technical guide to the Gall van.
glossary/moon.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Moon"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **moon** is a kind of [ship](../ship) on the [Arvo](../arvo) network. Moons are issued by planets, and are meant to be used for the issuing planet's connected devices, such as phones, desktops, smart TVs, and digital thermostats. A moon is not independent; it is always subordinated to the planet that issued it.
10+
11+Unlike planets, moons have no presence on [Azimuth](../azimuth) and have no associated identities. Moons are representable with 64 bits and have long names like `~doznec-salfun-naptul-habrys`, the latter half of which is inherited from their parent planet.
12+
13+### Further Reading
14+
15+- [Using Your Ship](@/using/operations/using-your-ship.md#moons): The "Moons" section contains instructions for creating and managing moons.
glossary/nock.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "Nock"
3+
4+template = "doc.html"
5++++
6+
7+**Nock** is a purely functional typeless programming language and acts as Urbit's lowest-level language. To be more precise, it is a Turing complete combinator interpreter not based on the lambda calculus. It could be thought of as the assembly-level language of Urbit, and is implemented by the runtime system [Vere](../vere).
8+
9+[comment]: # ("combinator interpreter" is from the old glossary, but I don't know what is meant by this and there only seems to be a few uses of it online according to google, so maybe there is a better term we can use here, or give more of an explanation of what is meant by this? but maybe that is not appropriate for a glossary)
10+
11+The only basic data type in Nock is the [atom](../atom), which is a non-negative integer. Computation in Nock occurs through the use of [nouns](../noun) (e.g. binary trees whose leaves are atoms) utilized in three different manners: formulas, subjects, and products. A _formula_ is a noun utilized as a function that takes in a noun, its _subject_, and returns a noun, its _product_.
12+
13+Code written in [Hoon](../hoon) is compiled to Nock, though it is unnecessary to learn Nock to write code in Hoon.
14+
15+### Further Reading
16+
17+- [The Nock Tutorial](@/docs/tutorials/nock/_index.md): An-in depth technical guide.
glossary/noun.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Noun"
3+
4+template = "doc.html"
5+[extra]
6+category = "hoon-nock"
7++++
8+
9+A **noun** is an [atom](../atom) or a cell, which is an ordered pair of nouns. This definition is recursive and ultimately means that a noun is a finite size binary tree whose leaves are atoms. A noun is the basic data structure in [Nock](../nock).
10+
11+### Further Reading
12+
13+- [The Hoon Tutorial](@/docs/tutorials/hoon/_index.md): Our guide to learning the Hoon programming language.
14+ - [Lesson 1.2: Nouns](@/docs/tutorials/hoon/nouns.md): A Hoon Tutoral lesson that explains how nouns work.
15+- [The Nock explanation](@/docs/tutorials/nock/_index.md): Includes a low-level explanation of nouns.
glossary/ota-updates.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "OTA Updates"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+[Ships](../ship) have the ability to upgrade themselves **over the air**. They receive updates from a sponsor [star](../star) or [galaxy](../galaxy).
10+
11+### Further Reading
12+
13+- [The Hoon Tutorial](@/docs/tutorials/hoon/_index.md): Our guide to learning the Hoon programming language.
14+ - [Lesson 1.2: Nouns](@/docs/tutorials/hoon/nouns.md): A Hoon Tutoral lesson that explains how nouns work.
15+- [The Nock explanation](@/docs/tutorials/nock/_index.md): Includes a low-level explanation of nouns.
glossary/ph.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "pH"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**pH** is a [Gall](../gall) app that is a framework for fleet testing using [Aqua](../aqua). pH comes with a number of default tests, as well as tools for building and executing custom tests.
glossary/pill.mdnew file+16
@@ -0,0 +1,16 @@
1++++
2+title = "Pill"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **Pill** is a bootstrap sequence to launch an Urbit ship for the first time. The [event log](../eventlog) begins with the bootstrap sequence of a Pill.
10+
11+A Pill consists of three ordered lists:
12+ * A list of events which are interpreted by Nock to create an [Arvo](../arvo) kernel.
13+ * A list of Arvo events to run once the Arvo kernel is created.
14+ * A list of userspace events to run once the Arvo events have been run. Currently, this consists of setting up the file system [Clay](../clay).
15+
16+
glossary/planet.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Planet"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **planet** is can be one of two related things:
10+
11+- A kind of [Azimuth](../azimuth) Urbit identity that sits at the bottom of the identity hierarchy. Planets act as independent identities for use by individual humans as peers on the [Arvo](../arvo) network. Planets are issued by [stars](../star), and receive services such as peer-to-peer routing and [over-the-air software updates](../ota-updates) from the star that sponsors them.
12+
13+- A [ship](../ship) on the Arvo network whose identity is a planet in the former definition. Planets, in the second sense, have the power to issue [moons](../moon). Moons are Arvo ships that are meant for use with devices, are completely subordinated from their parent planet, and have no Azimuth presence.
14+
15+Planets have addresses that are representable by 32 bits. This means that there are nearly 4.3 billion possible planets. Planets have four-syllable names like `~morzod-ballet` or `~rovnys-ricfer`.
glossary/proxies.mdnew file+29
@@ -0,0 +1,29 @@
1++++
2+title = "Proxies"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+**Proxies** are Ethereum addresses in the [Urbit HD Wallet](../hdwallet) system that have limited powers. They are lower-powered "siblings" of the ownership key, which has the sole power to transfer the assigned Urbit identity. Using [Bridge](../bridge), you can change the Ethereum addresses used for your proxies.
10+
11+There are three types of proxy.
12+
13+- **Management Proxy**
14+
15+The management proxy can configure or set Arvo networking keys and conduct sponsorship-related operations.
16+
17+- **Voting Proxy**
18+
19+The voting proxy can cast votes on behalf of its assigned point on new proposals, including changes to [Ecliptic](../ecliptic). The voting proxy is unique to [galaxies](../galaxy), since only power galaxies have seats in the Senate.
20+
21+- **Spawn Proxy**
22+
23+Creates new child points given Ethereum address. For [stars](../stars) and [galaxies](../galaxy) only.
24+
25+
26+### Further Reading
27+
28+- [Azimuth glossary page](../azimuth): The glossary entry for Azimuth.
29+- [The Azimuth concepts page](@/docs/tutorials/concepts/azimuth.md): A more in-depth explanation of Azimuth, including information the storage of Urbit identities.
glossary/replay.mdnew file+13
@@ -0,0 +1,13 @@
1++++
2+title = "Replay"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Replay** is how [Vere](../vere) computes the state of a ship's [Arvo](../arvo) instance from the [event log](../eventlog) after a ship reboots. In order to avoid replaying the entire event log, Replay takes a snapshot of the current state of the ship approximately once every ten minutes. Then when a ship reboots, Replay loads the most recent snapshot and replays events from the event log up to the most recent event.
10+
11+### Further Reading
12+
13+- [The Vere tutorial](@/docs/tutorials/vere/_index.md): An in-depth technical guide to Vere.
glossary/sailudon.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "Sail/Udon"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Sail** and **Udon** are domain specific languages for Hoon.
10+
11+Sail is used to express XML data structures, which are used for rendering webpages, such as when browsing [collections](../collection) in [Landscape](../landscape).
12+
13+Udon is similar to Markdown, a simple language for writing documents. Udon is stored in [Clay](../clay) and rendered using [Ford](../ford).
14+
15+### Further Reading
16+
17+- [The Sail and Udon guide](@/docs/tutorials/sail-and-udon.md): An in-depth guide to writing Sail and Udon.
glossary/senate.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Senate"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+The **Galactic Senate** is the body of all [galaxies](../galaxy) that governs [Azimuth](../azimuth) by [majority vote](../voting). There are two types of votes: a [constitution vote](../constitution), which is a motion to update the logic of Azimuth; and a [documentation vote](../docvote), which is a motion to legitimize or approve the content of an arbitrary document.
glossary/ship.mdnew file+25
@@ -0,0 +1,25 @@
1++++
2+title = "Ship"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **ship** is an instance of an Urbit computer that is a peer on the [Arvo](../arvo) network.
10+
11+A ship can be one of five classes:
12+
13+- [comets](../comet), disposable identities.
14+- [moons](../moon), connected devices subordinated to a ship.
15+- [planets](../planet), individual users.
16+- [stars](../star), network infrastructure nodes.
17+- [galaxy](../galaxy), also network infrastructure nodes.
18+
19+To be able to use the Arvo network, planets, stars, and galaxies must be combined with an [Azimuth](../azimuth)-based Urbit identity in the form of a [keyfile](../keyfile).
20+
21+### Further Reading
22+
23+- [Using Bridge](@/using/install.md): A guide to installing Urbit and booting a ship.
24+- [Ship Troubleshooting](@/docs/tutorials/ship-troubleshooting.md): General instructions on getting your ship to work, which includes network connectivity issues.
25+- [Understanding Urbit ID](@/understanding-urbit/urbit-id.md)
glossary/shiparvonetwork.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "ship.arvo.network"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**ship.arvo.network** is a way to connect to ships, primarily [galaxies](../galaxy), via HTTP utilizing DNS lookup. For example, the address for `~zod` would be `zod.arvo.network`.
glossary/star.mdnew file+17
@@ -0,0 +1,17 @@
1++++
2+title = "Star"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **star** is the kind of Urbit identity that sits between the [galaxy](../galaxy) and [planets](../planet) in the identity hierarchy. Stars act as infrastructure for the [Arvo](../arvo) network, providing planets with [Ames](../ames)-related services, such as peer-to-peer routing and distributing [over-the-air software updates](../ota-updates). Stars rely on galaxies for these services in the way that planets rely on stars.
10+
11+A **star** is can be to one of two related things:
12+
13+- A kind of [Azimuth](../azimuth) Urbit identity that sits between the [galaxy](../galaxy) and [planets](../planet) in the identity hierarchy. Stars, in this sense, have the power to issue [planets](../moon), and are themselves are issued by galaxies.
14+
15+- A [ship](../ship) on the Arvo network whose identity is a planet in the former definition. In this sense, stars act as infrastructure for the [Arvo](../arvo) network, providing planets with [Ames](../ames)-related services, such as peer-to-peer routing and distributing [over-the-air software updates](../ota-updates). Stars rely on galaxies for these services in the way that planets rely on stars.
16+
17+Stars have addresses that are representable by 16 bits. This means that there are 65,535 possible stars, and each of these stars is able to issue 65,535 planets. Stars have two-syllable names like `~taglux` or `~hallet`.
glossary/sync.mdnew file+16
@@ -0,0 +1,16 @@
1++++
2+title = "|sync"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**|sync** sets up a sychronization between two [Clay](../clay) [desks](../desk). It is mostly used to distribute kernel updates.
10+
11+By default, in the [galaxy](../galaxy)/[star](../star)/[planet](../planet)/[moon](../moon) hierachy, the kids desk of the parent is synchronized with the base desk of the child.
12+
13+
14+### Further Reading
15+
16+- [Using Your Ship](@/using/operations/using-your-ship.md#filesystem): A user guide that includes instructions on using Clay commands, including `|sync`.
glossary/talk.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Talk"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+**Talk** was Urbit's first big user-facing application. Talk utilized the [Hall](../hall) backend to ferry messages between ships, and acted as the frontend for the users to chat. This included reading from and writing to circles, as well as managing them. Talk is no longer used, and has been superseded by [Chat](../chat).
glossary/vane.mdnew file+22
@@ -0,0 +1,22 @@
1++++
2+title = "Vane"
3+
4+template = "doc.html"
5+[extra]
6+category = "arvo"
7++++
8+
9+A **vane** is an [Arvo](../arvo) kernel module that performs essential system operations. The vanes are:
10+
11+
12+- [Ames](../ames), the peer-to-peer networking vane.
13+- [Behn](../behn), the timer vane.
14+- [Clay](../clay), the filesystem and revision-control vane.
15+- [Dill](../dill), the terminal-driver vane.
16+- [Eyre](../dill), the HTTP vane.
17+- [Ford](../ford), the build-system vane.
18+- [Gall](../gall), the application vane.
19+
20+### Further Reading
21+
22+- [The Arvo tutorial](@/docs/tutorials/arvo/_index.md): An in-depth technical guide to Arvo and its vanes.
glossary/vere.mdnew file+18
@@ -0,0 +1,18 @@
1++++
2+title = "Vere"
3+
4+template = "doc.html"
5+[extra]
6+category = "hoon-nock"
7++++
8+
9+**Vere**, pronounced "Vair", is the [Nock](../nock) runtime environment and Urbit virtual machine. Vere is written in C, runs on Unix, and is the intermediate layer between your urbit and Unix. Unix system calls are made by Vere, not Arvo; Vere must also encode and deliver relevant external events to [Arvo](../arvo). Vere is also responsible for implementing jets and maintaining the persistent state of each urbit (computed as a pure function of its [event log](../eventlog) with [Replay](../replay)). It also contains the I/O drivers for Urbit’s vanes, which are responsible for generating events from Unix and applying effects to Unix.
10+
11+When you boot your [ship](../ship), Vere passes your [Azimuth](../azimuth) [keyfile](../keyfile) into the Arvo state, allowing a connection to the [Ames](../ames) network.
12+
13+Vere consists of two processes that communicate via a socket: a daemon process in charge of managing I/O channels, and a worker process that acts as a Nock interpreter that is instructed by the daemon process. Currently the worker is written in C, but a new worker written in Java, called [Jacque](../jacque), is under development.
14+
15+### Further Reading
16+
17+- [The Technical Overview](@/docs/tutorials/concepts/technical-overview.md)
18+- [The Vere tutorial](@/docs/tutorials/vere/_index.md): An in-depth technical guide to Vere.
glossary/voting.mdnew file+9
@@ -0,0 +1,9 @@
1++++
2+title = "Voting"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+**Voting** is a power available to [galaxies](../galaxy), in their capacities as members of the [Galactic Senate](../senate), through an [Azimuth](../azimuth) smart contract. Galaxies collectively make decisions about the governance of Azimuth and the [Arvo](../arvo) network by voting. There are two types of votes: a [constitution vote](../constitutionvote) and a [document vote](../docvote).
glossary/wallet-generator.mdnew file+11
@@ -0,0 +1,11 @@
1++++
2+title = "Wallet-Generator"
3+
4+template = "doc.html"
5+[extra]
6+category = "azimuth"
7++++
8+
9+The **Wallet Generator** is a planned open-source app developed for generating an [Urbit HD Wallet](../hdwallet) to secure your [Azimuth](../Azimuth) identities. Wallet Generator will be part of the [Bridge](../bridge) software, and it's a graphical user interface that handles the entire process of creating a new [Urbit HD Wallet](../hdwallet), starting with the entropy-creation step.
10+
11+The Wallet Generator must be used offline for security reasons. If an internet connection is detected at any time, the program will end, forcing the user to start from the beginning. As a final step, Wallet Generator will produce PDF files containing all of the aforementioned seeds, as well as a PDF that contains ownership Ethereum public addresses for receiving ships.
reference/_index.md−9
@@ -6,15 +6,6 @@ template = "sections/docs/chapters.html"
6+++
6+++
7Various reference documents are stored here, particularly for Hoon, but also for other parts of the system.
7Various reference documents are stored here, particularly for Hoon, but also for other parts of the system.
8
8
9−## [The Arvo Glossary](@/docs/reference/arvo-glossary.md)
10−
11−Urbit is known for introducing a great deal of new terminology. The glossary will
12−help demystify our jargon.
13−
14−## [The Azimuth Glossary](@/docs/reference/azimuth-glossary.md)
15−
16−Azimuth, the Urbit identity layer, has its own vocabulary.
17−
18## [The Cheat Sheet](@/docs/reference/cheat-sheet.md)
9## [The Cheat Sheet](@/docs/reference/cheat-sheet.md)
19
10
20The cheat sheet is a compact document for looking up Hoon runes.
11The cheat sheet is a compact document for looking up Hoon runes.
reference/arvo-glossary.mddeleted−849
@@ -1,849 +0,0 @@
1−+++
2−title = "Glossary"
3−weight = 3
4−template = "doc.html"
5−aliases = ["docs/reference/arvo-glossary/"]
6−+++
7−
8−Urbit is renowned for its exotic terminology. Here's a simple overview
9−from the strange words within.
10−
11−As Dijkstra put it: "The purpose of abstraction is not to be vague, but
12−to create a new semantic level in which one can be absolutely precise."
13−
14−This glossary only covers terms of the Arvo side of the project. You can find the
15−Azimuth glossary [here](../azimuth/glossary)
16−
17−### application
18−
19−Also known as an “app,” an _application_ is a Hoon program that can hold state.
20−
21−### arm
22−
23−An _arm_ is a named, functionally-computed attribute of a [core](#core).
24−
25−The [hoon](#a-hoon) of each arm is compiled to a Nock formula, with the
26−enclosing [core](#core) itself as the subject.
27−
28−There are two kinds of arms: _dry_ and _wet_. Most arms are
29−dry.
30−
31−#### dry
32−
33− normal, `++`, polymorphic by means of _variance_
34−
35− For a dry arm, we ask: is the new payload compatible with the old
36− payload (against which the core was compiled)?
37−
38−#### wet
39−
40− unusual, `+-`, polymorphic by means of _genericity_
41−
42− A wet arm uses the hoon as a macro. We create a new type analysis
43− path, which works as if we expanded the callee with the caller's
44− context.
45−
46−_See [advanced types](/docs/reference/hoon-expressions/advanced/)_.
47−
48−
49−
50−### Arvo
51−
52−The Urbit operating system and kernel. Arvo's state is a pure function of its
53−event log, and it serves as the Urbit event manager. It contains vanes, which are
54−kernel modules that perform essential system operations. Arvo itself can only
55−deal with one file at a time. For more, it relies on Ford, the build-system
56−vane.
57−
58−Arvo being purely functional means that the it is a function that is:
59−
60−`(state, event) → (state, effects)`
61−
62−Arvo coordinates and reloads vanes. It can be thought of as a traffic-director.
63−Any vane needs to go through Arvo before reaching another vane. Events and
64−their effects happen like so:
65−
66−`Unix event → vere (the virtual machine that runs Urbit) → Arvo → vane → Arvo`
67−
68−Arvo is located in `/home/sys/arvo.hoon` within your urbit.
69−
70−More in-depth information on Arvo can be found
71−[`here`](@/docs/tutorials/arvo/_index.md).
72−
73−Below are Arvo modules, which are called "vanes".
74−
75−#### Ames
76−
77− The networking vane. Ames handles all things UDP. Here live the protocols for
78− discovering and interacting with other urbits. It’s also the name for the Urbit
79− network itself. All communication is signed and encrypted.
80−
81− Ames is located in `/home/sys/vane/ames.hoon` within your urbit.
82−
83− More in-depth information on Ames can be found
84− [`here`](@/docs/tutorials/arvo/ames.md).
85−
86−#### Behn
87−
88− The timing vane. Behn allows for applications to schedule events, which are
89− managed in a simple priority queue. For example, Clay, the Urbit filesystem,
90− uses Behn to keep track of time-specific file requests. Eyre, the Urbit web
91− vane, uses Behn for timing-out HTTP sessions.
92−
93− Behn is located in `/home/sys/vane/behn.hoon` within your urbit.
94−
95−#### Clay
96−
97− The filesystem and typed revision-control vane. Think of Clay as a
98− continuously synced git. It handles file-change events and maps them from Urbit
99− to Unix and vice versa.
100−
101− A common way to use it is to create a pier, a directory that exists in and is
102− visible in Unix.
103−
104− Clay is located at `/home/sys/vane/clay.hoon` within your urbit.
105−
106− Basic information on using Clay can be found
107− [`here`](@/using/operations/using-your-ship.md). An in-depth explanation
108− of the architecture can be found
109− [`here`](@/docs/tutorials/arvo/clay.md).
110−
111−#### Dill
112−
113− The terminal-driver vane. You run your urbit in your Unix terminal, and
114− Unix sends every event -- such as a keystroke or a change in the dimensions of
115− the terminal window -- to be handled by Dill. Dill acts as an intermediary for
116− anything that uses keyboard events. This is why there’s some input lag in
117− Urbit’s command-line interface. (Optimization will come later!)
118−
119− A keyboard event's journey from Unix to Dojo, the Urbit shell, can be imagined
120− as diagrammed below:
121− ```
122− Keystroke in Unix -> Vere (virtual machine) -> Arvo -> Dill -> the Dojo
123− ```
124−
125− Dill is located at `/home/sys/vane/dill.hoon` within your urbit.
126−
127− More in-depth information on Dill can be found
128− [`here`](@/docs/tutorials/arvo/dill.md).
129−
130−#### Eyre
131−
132− The web-server vane. Anything HTTP-related lives here. Unix sends HTTP messages
133− though to Eyre, and Eyre produces HTTP messages in response.
134−
135− In general, apps and vanes do not call Eyre; rather, Eyre calls apps and vanes.
136− Eyre uses Ford and Gall to functionally publish pages and facilitate
137− communication with apps.
138−
139− Eyre is located at `/home/sys/vane/eyre.hoon` within your urbit.
140−
141− More in-depth information on Eyre can be found
142− [`here`](@/docs/tutorials/arvo/eyre.md).
143−
144−#### Ford
145−
146− The build-system vane. Ford is capable of sequencing generic asynchronous
147− computations. Its uses include linking source files into programs, assembling
148− live-updating websites, and performing file-type conversions.
149−
150− Ford neither accepts Unix events nor produces Unix effects. It exists
151− entirely for the benefit of Urbit applications and other vanes, in particular
152− Gall.
153−
154− Ford is located at `/home/sys/vane/ford.hoon` within your urbit.
155−
156− More in-depth information on Ford can be found
157− [`here`](@/docs/tutorials/arvo/ford.md).
158−
159−#### Gall
160−
161− The application-management vane. Userspace apps -- daemons, really -- are
162− started, stopped, and sandboxed by Gall. Gall provides developers with a
163− consistent interface for hooking their app up to the operating system. It allows
164− applications and other vanes to send messages to applications and subscribe to
165− data streams. Messages coming into Gall are routed to the intended application,
166− and the response comes back along the same route. If the intended target is on
167− another ship, Gall will route it, behind the scenes, through Ames to the other
168− ship.
169−
170− Gall is located at `/home/sys/vane/gall.hoon` within your urbit.
171−
172− More in-depth information on Gall can be found
173− [`here`](@/docs/tutorials/arvo/gall.md).
174−
175−### atom
176−
177−An atom is any natural number, including zero. The atom is the most basic data
178−type in [Nock](#nock) and [Hoon](#hoon). A Hoon atom type describes a Nock
179−atom with two additional pieces of metadata: an [_aura_](#aura), and an
180−optional constant.
181−
182−An atom type is _warm_ or _cold_ based on whether the constant exists.
183−
184−
185−#### warm
186−
187− If the constant is `~` (null), any atom is in the type.
188−
189−#### cold
190−
191− If the constant is `[~ atom]`, its only legal value is `atom`.
192−
193−_See [basic types](@/docs/reference/hoon-expressions/basic.md)_
194−
195−### aura
196−
197−An aura is a soft atom type. They appear as strings beginning with `@`. Auras
198−represent the structure of an atom, print format, or other semantics. Its
199−constraints on the value of an atom aren't enforced in any way.
200−
201−You can cast something to an aura, like a decimal, and get back its hexademical.
202−For example:
203−
204−```
205− > =a `@`29
206− > ^- @ux a
207− 0x1d
208−```
209−
210−Auras are an advisory type system. You can go up or down, but not sideways in
211−the hierarchy. `@t` and `@` can each be cast to the other, but @t can’t be cast
212−to `@u`, for example, without first being cast to the empty aura `@`.
213−
214−For example
215−
216−```
217− > ^- @ 'c' :: 'c' is of the aura @t
218− 99
219−
220− > ^- @u 'c'
221− ! exit
222−```
223−
224−Here is a non-exhaustive list of auras:
225−
226−```
227−Aura Meaning Example Literal Syntax
228−-------------------------------------------------------------------------
229−@d date
230− @da absolute date ~2018.5.14..22.31.46..1435
231−@n nil ~
232−@p phonemic string (ship name) ~sorreg-namtyv
233−@r IEEE floating-point
234− @rd double precision (64 bits) .~6.02214085774e23
235− @rh half precision (16 bits) .~~3.14
236−@s signed integer, sign-bit low
237− @sb signed binary --0b11.1000
238− @sd signed decimal --1.000.056
239− @sx signed hexadecimal -0x5f5.e138
240−@t UTF-8 text (cord) 'howdy'
241− @ta ASCII text (knot) ~.howdy
242− @tas ASCII text symbol (term) %howdy
243−@u unsigned integer
244− @ub unsigned binary 0b11.1000
245− @ud unsigned decimal 1.000.056
246− @ux unsigned hexadecimal 0x5f5.e138
247−```
248−
249−You can find the list of all auras [here](@/docs/reference/hoon-expressions/rune/constants.md).
250−
251−### blocksize
252−
253−Blocksize is the power-of-two bitwidth of an atom. So, an atom with a blocksize
254−of `3` has a bitwidth of `2^3`, which is 8. A bitwidth of 8, in turn, can
255−represent `2^8` values, or 256.
256−
257−### cast
258−
259−To cast is to put a Hoon expression through the compiler’s type-checker to test
260−whether the expression is guaranteed to evaluate to a product that falls within
261−the desired type. If the expression is not guaranteed to behave in this way,
262−then the compiler will halt with a nest-fail crash. Proper Hoon code will
263−include a cast for the product type of each gate.
264−
265−The cast rune is `^-` (pronounced "ket-hep"). So, to cast to a list of atoms,
266−we write `^- (list @)`. The irregular form of that expression is ``(list @)``.
267−
268−### cell
269−
270−In Nock and Hoon, a _cell_ is an ordered pair of [nouns](#noun).
271−
272−Syntax: `[a b]`.
273−
274−Cells orient to the right; for example, the noun [2 6 14 15] is short for
275−[2 [6 [14 15]]].
276−
277−
278−### clam
279−
280−A clam is the use of a structure as a gate. Usually used to verify marks from
281−other urbits.
282−
283−```
284− > ((list @t) [97 98 ~])
285− <|a b|>
286−```
287−
288−### cord
289−
290−In Hoon, `cord` is an aura for representing atoms as strings. UTF-8,
291−least-significant bit first. Represented as the aura `@t`.
292−
293−```
294− > `@t`478.560.413.032
295− 'hello'
296−```
297−
298−### core
299−
300−A _core_ is a [cell](#nock-cell) of `[code data]`, where we call the
301−code head the _battery_ and the data tail the _payload_. All code-data
302−structures in normal languages (functions, objects, modules, etc.)
303−translate to cores in Hoon.
304−
305−#### battery
306−
307− The code-containing head of a core.
308−
309−#### payload
310−
311− The data-containing tail of a core.
312−
313−_See [basic types](@/docs/reference/hoon-expressions/basic.md)._
314−
315−### Dojo
316−
317−The Dojo is the Urbit shell; the command line where you run programs,
318−expressions, and system commands. It’s a CLI that is encountered right when
319−an urbit is started for the first time. It is somewhat analogous to Bash, the
320−Unix terminal, and more analogous to a Hoon REPL.
321−
322−You’ll notice that many things can’t be written here; this is normal. The Dojo
323−enforces syntactical correctness right at the command line. Strings that can’t
324−be continued into a valid expression are automatically trimmed back to something
325−that can be. Some syntactically invalid expressions can be completed, but the
326−Dojo will prevent them from being entered as a command. You can play around
327−with this functionality learn what syntax is kosher.
328−
329−### desk
330−
331−A desk is an independently revision-controlled branch of urbit filesystem.
332−
333−_See [filesystem](@/using/operations/using-your-ship.md) and [Clay](@/docs/tutorials/arvo/clay.md)._
334−
335−
336−### duct
337−
338−A duct is an Arvo-level call stack. At the beginning of every duct is a Unix
339−event, such as a keystroke, network packet, timer event, or file change.
340−
341−A duct is a `list` of `wire`s. A wire is itself a `list` of `knot`s. A `knot`
342−is, in turn, a knot.
343−
344−### face
345−
346−A _face_ is the Hoon analog to what is a variable name in most other
347−programming languages. Faces are metadata labels for legs, allowing us to
348−address parts. Because there is no metadata in Nock, faces cannot exist in Nock.
349−
350−```
351− > a=2
352− a=2
353−```
354−
355−In the above example, `a` is the face and `2` is the value.
356−
357−Hoon has no scope or symbol-table; there is only the subject. To "declare" a
358−"variable" is to construct a new subject: `[name=value old-subject]`.
359−
360−_See [advanced types](@/docs/reference/hoon-expressions/advanced.md)_.
361−
362−
363−### flag
364−
365−A `flag` is Hoon's version of a boolean. `0` (`%.y`) is _yes_, `1` (`%.n`) is
366−_no_.
367−
368−### gate
369−
370−A _gate_ is a [core](#core) with one [arm](#arm) -- Hoon's closest
371−analog to a function. To call a gate on an argument, replace the sample
372−(at [tree address](@/docs/reference/hoon-expressions/limb/limb.md) `+6`
373−in the core) with the argument, and then compute the arm.
374−
375−The payload of a gate has a shape of `[sample context]`.
376−
377−#### sample
378−
379− The argument tuple.
380−
381−#### context
382−
383− The subject in which the gate was defined.
384−
385−_See [basic types](@/docs/reference/hoon-expressions/basic.md),
386−[`%-` ("cenhep")](@/docs/reference/hoon-expressions/rune/cen.md#cenhep) (the
387−[rune](#rune) for calling a `gate`)._
388−
389−### generator
390−
391−A _generator_ is like a limited Hoon script: it’s a shell command that produces
392−a value before disappearing. Generators take an input [noun](#noun) (a value)
393−and produce an output `noun` by performing calculations on its arguments,
394−prompting for input, or making HTTP requests.
395−
396−You need a `bar` rune like `|=` in your generator, because a generator is
397−essentially a function that you’re calling.
398−
399−Generators, unlike [apps](#application), hold no state. They are pure,
400−stateless functions, and they cannot send [moves](#move). Because of this,
401−generators are have a more narrow use than apps. Among the non-trivial uses of
402−a a generator is moving data into apps -- they’re the backbone of Urbit’s
403−information pipeline.
404−
405−Generators are run from the `/gen` directory of your current desk. For example,
406−to run a generator named `whatever.hoon`, you would type `> +whatever` in the
407−[Dojo](@/using/operations/using-your-ship.md#using-the-shell).
408−
409−### glyph
410−
411−A _glyph_ is a single, non-alphanumeric ASCII character. Each glyph has its own
412−monosyllabic name, which allows the efficient communication of Hoon-related
413−information in speech. [`Runes`](#rune) are composed of two glyphs.
414−Below is a complete list of glyphs with their associated pronunciations.
415−
416−```
417−ace [1 space] gal < pal (
418−bar | gap [>1 space, nl] par )
419−bas \ gar > sel [
420−buc $ hax # mic ;
421−cab _ hep - ser ]
422−cen % kel { sig ~
423−col : ker } soq '
424−com , ket ^ tar *
425−doq " lus + tic `
426−dot . pam & tis =
427−fas / pat @ wut ?
428−zap !
429−```
430−
431−### Hall
432−
433−_Hall_ is the Urbit communication back-end. It’s a messaging bus that can work
434−with clients of all sorts. [`:talk`](#talk), the built-in chat client, is one
435−such app that uses Hall.
436−
437−#### circle
438−
439− A circle is the “audience” of your messages -- who can receive them. It can be
440− thought of as a chat channel, but this is a little too narrow. More
441− specifically, it’s a named collection of messages created by and hosted on a
442− ship’s Hall, usually represented as `~ship-name/circle-name`. On Talk,
443− Urbit’s built-in chat front-end, the first circle that you will likely
444− encounter is `~dopzod/urbit-help`.
445−
446−### Hood
447−
448−_Hood_ orchestrates many of the Urbit initialization systems necessary
449−for boot.
450−
451−### Hoon
452−
453−Hoon is a strict, higher-order typed functional language that compiles itself
454−to Nock.
455−
456−The Hoon source file is located in `/home/sys/hoon.hoon` within your urbit.
457−
458−_More information can be found in the [hoon](@/docs/tutorials/hoon/_index.md) section._
459−
460−#### Mint
461−
462− _Mint_ is the Hoon compiler function. Mint takes the subject type and the
463− expression source (a [hoon](#a-hoon), for example) and produces the product
464− type and nock formula. So [type hoon] is mapped to [type nock].
465−
466−### hoon
467−
468−A _hoon_ (lowercase) is the result of parsing a Hoon source expression into an
469−AST node. These AST nodes are nouns, like all other Hoon data. Because every
470−Hoon program is, in its entirety, a single expression of Hoon, the result of
471−parsing the whole thing into an AST is a single `hoon`.
472−
473−A hoon is a tagged union of the form `[%tag data]`, where the tag
474−is a constant such as `%brts` (from the source [rune](#rune) `|=`,
475−i.e. "bartis"), and is matched up with the appropriate type of data
476−(often more `hoon`s, from source subexpressions). For example, the
477−expression `:-(2 17)`, once parsed into an AST, becomes the following:
478−
479−```
480−[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
481−```
482−
483−The `%clhp` is produced from the rune `:-` (i.e. "colhep"). The 2 and
484−17 have each been parsed as `%sand`-tagged hoons, which represent
485−atoms (in this case each with an aura of `%ud`, i.e. unsigned
486−decimal).
487−
488−To parse Hoon source into a hoon AST, use `ream` on a `cord`
489−containing Hoon source. Try the following in [Dojo](@/using/operations/using-your-ship.md#using-the-shell):
490−
491−```
492−(ream ':+(12 7 %a)')
493−```
494−
495−The result should be:
496−
497−```
498−[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
499−```
500−
501−See [expression reference](@/docs/reference/hoon-expressions/rune/_index.md) for the full list of hoons.
502−
503−### irregular form
504−
505−Irregular forms are alternative ways of writing Hoon expressions, alternatives
506−to the digraphic runes such as `:~`. Irregular forms are usually more compact
507−than regular forms.=
508−
509−_See [irregular forms](@/docs/reference/hoon-expressions/irregular.md)._
510−
511−### jet
512−
513−A _jet_ is a piece of C code that have equivalent products to a piece of Hoon or
514−Nock code. They are used for performance reasons; jets are meant to be faster
515−than the code that they are substituting for.
516−
517−Jets are necessary for mathematics, performance-wise, because Nock handles it
518−so inefficiently. Nock, for example, can’t decrement (reduce a number by one)
519−except by starting building a loop that starts from zero and increments to a
520−number just below.
521−
522−_See [API overview](@/docs/tutorials/vere/api.md)._
523−
524−### lark
525−
526−A lark is an expression that returns a [limb](#limb) at the specified
527−address in a cell. Using `-` by itself returns the head of the subject, and
528−using `+` by itself returns the tail:
529−
530−```
531−> -:[[4 5] [6 [14 15]]]
532−[4 5]
533−
534−> +:[[4 5] [6 [14 15]]]
535−[6 14 15]
536−```
537−
538−You can combine `+` or `-` with either of `>` or `<` to get a more specific limb
539−of the subject. `-<` returns the head of the head; `->` returns the tail of the
540−head; `+<` returns the head of the tail; and `+>` returns the tail of the tail.
541−By alternating the `+`/`-` symbols with `<`/`>` symbols, you can go as deep as
542−you desire.
543−
544−```
545−> +>-:[[4 5] [6 [14 15]]]
546−14
547−
548−> +>+:[[4 5] [6 [14 15]]]
549−15
550−```
551−
552−### limb
553−
554−A _limb_ is an attribute or variable reference. A limb is an [arm](#arm) or a
555−[leg](#leg).
556−
557−To resolve a _limb_ named "foo", the subject is searched depth-first,
558−head-first for either a face named "foo" or a core with an arm of
559−"foo". If a face is found, the result is a leg, if a core is
560−found, the result is the product of the arm.
561−
562−#### leg
563−
564− a subexpression, or subtree of the
565− [subject](#nock-subject).
566−
567−#### wing
568−
569− a search path into the subject, composed of
570− limbs. Search occurs from right to left (`a.b` means `b` within `a`).
571−
572−_See [Limbs and wings](@/docs/reference/hoon-expressions/limb/_index.md)_
573−
574−### move
575−
576−A move is the [Arvo](#arvo) equivalent of a syscall.
577−
578−### noun
579−
580−In [Nock](#nock) and [Hoon](#hoon), a _noun_ is an atom or a cell.
581−
582−### Nock
583−
584−Nock is a Turing-complete, non-lambda combinator interpreter. It's
585−Urbit's low-level programming language. Nock is functional and typeless.
586−
587−#### noun
588−
589− an _atom_ or a _cell_.
590−
591−#### atom
592−
593− any natural number, including zero.
594−
595−#### cell
596−
597− any ordered pair of nouns.
598−
599−
600−#### subject
601−
602− a noun - the data against which a _formula_ is evaluated.
603−
604−#### formula
605−
606− a noun - a function at the nock level.
607−
608−#### product
609−
610− a noun - the result of evaluating a formula against a subject.
611−
612−_See the [Nock definition](@/docs/tutorials/nock/definition.md)._
613−
614−### mark
615−
616−A _mark_ is Urbit's version of a MIME type, if a MIME type was an
617−executable specification. The mark is just a label that's used as a path
618−to a local source file in the Arvo filesystem. This source file defines
619−a core that can mold untrusted data, diff and patch, convert to other
620−marks, etc.
621−
622−If this sounds like magic, it isn't quite magic. There's no way
623−for different urbits to make sure they mean the same thing by the
624−same mark. However, when incompatibility happens, marks ensure
625−that we at least handle the situation in a predictable way.
626−
627−#### metal
628−
629−Every core has a _metal_ which defines its variance model (ie, the
630−properties of the type of a compatible core). The default is `gold`
631−(invariant).
632−
633−- `gold`: _invariant_
634−- `lead`: _bivariant_
635−- `zinc`: _covariant_
636−- `iron`: _contravariant_
637−
638−_See [advanced types](@/docs/reference/hoon-expressions/advanced.md)_.
639−
640−### ship
641−
642−An Urbit _ship_ is: a cryptographic title on a _will_ signed by private key; a
643−human-memorable name; and a packet-routing address. Ships are classed by the
644−number of bits in their address:
645−
646−```
647− Size Name Parent Object Example
648− ----- ------ ------ ------ -------
649− 2^8 galaxy ~ supernode ~zod
650− 2^16 star galaxy supernode ~dozbud
651− 2^32 planet star user ~tasfyn-partyv
652− 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
653− 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
654−```
655−
656−Any ship can be called an _urbit_. The lowercase "u" distinguishes it from Urbit
657−the software stack and Urbit the network.
658−
659−_You can find a longer-form summary [here.](https://urbit.org/posts/essays/the-urbit-address-space/)._
660−
661−An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
662−but it's easy to remember and say out loud. `~firbyr-napbes` is actually
663−just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,
664−that we turn into a human-memorable string. The full name of this string
665−can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful
666−when running a ship with a longer name, such as a _moon_ or a _comet_.
667−
668−Technically, an urbit is a secure digital identity that you own and
669−control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
670−the supply of urbits is mathematically limited. This keeps the network
671−friendly, by making spam and abuse expensive.
672−
673−An urbit name is just a number; smaller numbers make shorter names.
674−Shorter names are easier to remember, so they're more valuable. So
675−urbits are classified by the number of bits in their name. (A ship name
676−is just a scrambled base-256 representation of the number.)
677−
678−A 32-bit urbit (like `~firbyr-napbes`) is called a _planet._ A 16-bit
679−urbit (like `~pollev)` is a _star._ An 8-bit ship (like `~mun`) is a
680−_galaxy._ A planet is an identity for an independent, adult human. Stars
681−and galaxies are network infrastructure.
682−
683−Each planet or star is launched by its _parent,_ the star or galaxy
684−whose number is its bottom half. So the planet `~firbyr-napbes`,
685−`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef` or
686−`48.879`, whose parent is `~mun`, `0xef`, `239`. The galaxy at the address of
687−`0` is `~zod`.
688−
689−#### pier
690−
691− A ship's _pier_ is its Unix directory. For planets, the name of the pier is
692− usually the planet name.
693−
694−### structure
695−
696−A _structure_ is an idempotent [gate](#gate) (function) that constructs and
697−validates types in Hoon.
698−
699−An example: Arvo [marks](#mark) use Hoon's type system via structures to
700−validate untrusted network data.
701−
702−Here's some common structure terminology:
703−
704−#### bunt
705−
706− A bunt is the default value of a [structure](#structure). It's also a verb;
707− to _bunt_ a structure is to produce the bunt of that structure. For example,
708− bunting `@` results in `0`, and bunting `@t` results in `''`. Bunting is
709− performed with `*` followed by the structure in question:
710−
711− ```
712− > *@
713− 0
714− > *@t
715− ''
716− ```
717−
718−#### icon: The type of the mold's range
719−
720−_See [mold hoons](/docs/reference/hoon-expressions/rune/buc/)._
721−
722−### rune
723−
724−A Hoon _rune_ is a pair of ASCII symbols used to begin a
725−[Hoon expression](#a-hoon).
726−
727−For example, the rune [`?:`](@/docs/reference/hoon-expressions/rune/wut.md#wutcol) is
728−Hoon's most common conditional, a branch on a boolean test. The first
729−symbol in a rune represents a family of related runes. For example, the
730−[`?` family](@/docs/reference/hoon-expressions/rune/wut.md) are all conditionals.
731−
732−The result of parsing a Hoon source expression&mdash;the rune, followed
733−by its respective children&mdash;into an AST node is simply called
734−a [`hoon`](#a-hoon).
735−
736−Runes have two syntactic forms, _tall_ and _flat_:
737−
738−#### tall
739−
740− multiple lines, no parentheses, two or more spaces between tokens
741−
742− Example:
743−
744− ```
745− > %+ add 2 2
746− 4
747− ```
748−
749−#### flat
750−
751− one line, parentheses, one space between tokens
752−
753− Example:
754− ```
755− > %+(add 2 2) :: regular flat form
756− 4
757−
758− > (add 2 2) :: irregular flat form
759− 4
760− ```
761−
762−Tall hoons can contain flat hoons, but not vice versa. All irregular
763−forms are flat.
764−
765−_See [hoon concept](#a-hoon),
766−[expressions](@/docs/reference/hoon-expressions/rune/_index.md).
767−
768−### Sail
769−
770−_Sail_ is the Hoon markup language for XML.
771−
772−### scry
773−
774−To _scry_ means to request data from the Arvo namespace and bring it
775−to userspace.
776−
777−_See [.^ (dot-ket)](@/docs/reference/hoon-expressions/rune/dot.md#dotket)._
778−
779−### slot
780−
781−`slot` is the name for Hoon's tree-addressing scheme.
782−
783−Every cell has a head and a tail, each of which may be either an atom or
784−a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to
785−the whole cell (technically this would work against an atom as well).
786−The head of `+n` is `+2n`, the tail is `+(2n+1)`.
787−
788−`+7` is a special address for gates, because the position is defined
789−(by convention) as the context of a gate and of all cores.
790−
791−### talk
792−
793−_Talk_ is Urbit's built-in chat app. It’s one example of an app that can be
794−built on top of Hall, the Urbit back-end messaging system.
795−
796−_See [Messaging](@/using/operations/using-your-ship.md#messaging). for more information._
797−
798−### type
799−
800−A Hoon _type_ defines a set (finite or infinite) of nouns and ascribes
801−some semantics to it. There is no direct syntax for defining
802−types; they are always defined by inference (i.e., by
803−[`mint`](#mint)), usually using a constructor ([structure](#structure)).
804−
805−All types are assembled out of base types defined in `++type`.
806−(Look up `++ type` in hoon.hoon for examples.) When the compiler
807−does type-inference on a program, it assembles complex types out
808−of the simpler built-in types.
809−
810−#### nest
811−
812− `nest` is an internal Hoon function on two types which performs a type
813− compatibility test. `nest` produces yes if the
814− set of nouns in the second type is provably a subset of the first.
815− If `nest` produces no, the Hoon programmer will receive a `nest-fail`
816− error. This is one of the most commons errors in Hoon programming.
817−
818− _See [advanced types](@/docs/reference/hoon-expressions/advanced.md)_ and [troubleshooting](@/docs/tutorials/ship-troubleshooting.md).
819−
820−
821−### Unit
822−
823−Hoon's equivalent of a nullable pointer or a Haskell Maybe. If `q` is `~`,
824−null, the type is _warm_; any atom is in the type. If `q` is `[~ x]`, where
825−`x` is any atom, the type is _cold_; its only legal value is the constant `x`.
826−
827−### Vane
828−
829−A _vane_ is an [Arvo](#arvo) module. Each Vane is a single file because Arvo
830−cannot, on its own, deal with programs that are split between multiple files.
831−Some vanes can do this, however.
832−
833−### Vere (pronounced “vair”)
834−
835−The runtime system, written in C, that implements [Nock](#nock). All
836−It’s written in C. Vere-level errors are prepended with as `bail:`.
837−
838−Vere is a virtual machine: it pretends to be hardware, and is the single point
839−of contact between your Urbit and the rest of your system. But more than that,
840−Vere handles the Urbit event log and handles jets. It’s also contains the i/o
841−drivers for Urbit’s vanes, responsible for generating events from Unix and
842−applying effects to Unix.
843−
844−### Zuse
845−
846−_Zuse_ is a defined interface for vanes. It contains the part of the Hoon
847−standard library that is specific to Arvo functionality.
848−
849−Arvo is located in `/home/sys/zuse.hoon` within your urbit.
reference/azimuth-glossary.mddeleted−118
@@ -1,118 +0,0 @@
1−+++
2−title = "Azimuth Glossary"
3−weight = 4
4−template = "doc.html"
5−aliases = ["/docs/reference/azimuth-glossary/"]
6−+++
7−
8−
9−Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum blockchain, used as a platform for Urbit identities. You need an Azimuth identity to use the Arvo network. All identity-related operations are governed at this layer For more information, see the [Azimuth documentation](azimuth).
10−
11−This glossary is intended to familiarize you with Azimuth-related terminology. To brush up on terminology related to Arvo, check out the [Arvo glossary](../arvo/glossary).
12−
13−### Azimuth identity
14−
15−An Azimuth identity, previously known as a _point_, is a non-fungible Ethereum token ([ERC-721](https://medium.com/@brenn.a.hill/noobs-guide-to-understanding-erc-20-vs-erc-721-tokens-d7f5657a4ee7)) that represents a digital identity. The ERC-721 standard, having been made specifically to provide a smart-contract interface for non-fungible assets, allows Azimuth identity ownership to be take advantage of existing third-party tools and systems.
16−
17−#### Planet
18−
19−An Azimuth identity to be used as a personal identity. Issued by stars.
20−
21−#### Star
22−
23−An Azimuth identity meant to be used as network infrastructure. Issued by galaxies, issues planets.
24−
25−#### Galaxy
26−
27−An Azimuth identity meant to be used as top-level network infrastructure, with governance powers. Issues stars.
28−
29−### Bridge
30−
31−A tool that's the primary way to interact with Azimuth and manage your identities. It can be accessed at bridge.azimuth.network.
32−
33−### Master Ticket
34−
35−Think of your master ticket as a very high-value password. The master ticket is the secret code from which all of your other secrets are derived. Technically, your master ticket is seed entropy. You should never share it with anyone, and store it very securely. This ticket can derive all of your other keys: your ownership key and all of the related proxies.
36−
37−### Multipass
38−
39−Multipass is a planned feature of an Azimuth point that can be used as a universal, real-world identity. It will be able to hold money and have packets routed to it. See this [blog post](https://urbit.org/posts/azimuth-as-multipass/) for more information.
40−
41−#### Network Explorer
42−
43−A Bridge-based interface for browsing Azimuth identities. You can do things such as see which ships are on which invite pools, and much more.
44−
45−### Ownership Address
46−
47−The Ethereum address that owns a point. As the owner, it can perform all possible operations for that point.
48−
49−### Invite Pool
50−
51−Also called an _invite tree_. A host starts a pool and all individuals invited to it have the ability to share remaining, unclaimed invites with others; when an invite is sent to someone, they become a full member of the invite pool and themselves have the ability to invite. So membership of the invite pool grows like a tree.
52−
53−#### Pool Host
54−
55−The ship that generates the invite pool. It's most often a star.
56−
57−#### Guest List
58−
59−The names of planets invited to the same invite pool, as viewed by the pool host.
60−
61−#### Invite Cohort
62−
63−The names of planets invited to the same invite pool, as viewed by the pool's member's.
64−
65−#### Sending Invites
66−
67−The action of giving someone a planet using Bridge.
68−
69−#### Code
70−
71−Activation code from an email that allows you to claim an invite
72−
73−#### Birth Time
74−
75−When a ship is claimed from an invite
76−
77−### Passport
78−
79−The Passport is a folder of files one downloads that contains the secrets of your point and should be stored securely. As long as you own the passport, you own the point. The master ticket is stored in the Passport.
80−
81−### Proxy Address
82−
83−An Ethereum address that's allowed to perform a specific subset of the operations the owner of the point can perform. Useful for allowing some control over a point while keeping its ownership address in cold storage. Below, the specific kinds of proxy addresses are listed.
84−
85−#### Management Proxy Address
86−
87−An Ethereum address used for managing a point. This means it can only configure public (aka networking) keys, and perform sponsorship-related operations (requesting sponsor changes & approving/rejecting those).
88−Use cases:
89−- Keeping this handy so you can put the ownership/master ticket in a super safe place
90−- Allowing someone to manage your ship (by setting/deriving networking keys, managing sponsorship)
91−- Allowing a smart contract to manage sponsorship ops (ie star service smart contract)
92−
93−#### Network Keys
94−
95−Your public key contains Authentication and Encryption addresses, and also have Revision, Continuity Era, and Crypto Suite versions. Resetting Network Keys increases the revision number on the key. A main use case would be if your Network Keys were compromised, so you can use your Management Address to re-derive your Network Keys to another revision.
96−
97−#### Spawn Proxy Address
98−
99−An Ethereum address used for spawning children of a point. It can only perform the spawn operation (creating child points) and can do nothing else.
100−
101−Use cases:
102−- Keeping this handy so you can put the ownership/master ticket in a super safe place
103−- Allowing a smart contract to spawn on your behalf (delegated sending/invites, planet sale)
104−
105−#### Voting Proxy Address
106−An Ethereum address used for voting as a point.
107−
108−Use cases:
109−- Keeping this handy so you can put the ownership/master ticket in a super safe place
110−- Delegating your voting rights to someone else
111−
112−#### Transfer Proxy Address
113−
114−An Ethereum address that's allowed to transfer ownership of a point. Generally not used outside of transfers-in-progress. Using a transfer proxy allows one to give the recipient the power to take ownership of a point, rather than being given it. This "control check" is a strong safety mechanism commonly used in many (Ethereum-based) cryptographic assets.
115−
116−### Sponsorship
117−
118−Azimuth registers hierarchical dependence of identities on other identities; planets depend on stars, and stars depend on galaxies. Applications that use Azimuth can use this to set up things like network topology. In Arvo's case, the sponsor promises to provide software updates and peer discovery.
concepts/_index.md → tutorials/concepts/_index.mdrenamed

The content is the same.

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

The content is the same.

concepts/technical-overview.md → tutorials/concepts/technical-overview.mdrenamed+1
@@ -3,6 +3,7 @@ title = "Technical overview"
3weight = 1
3weight = 1
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6+
6Urbit is a clean-slate software stack designed to implement an encrypted P2P
7Urbit is a clean-slate software stack designed to implement an encrypted P2P
7network of general-purpose personal servers. Each server on this network is a
8network of general-purpose personal servers. Each server on this network is a
8deterministic computer called an 'urbit' that runs on a Unix-based virtual
9deterministic computer called an 'urbit' that runs on a Unix-based virtual
tutorials/hoon/landscape-tile.md+1−1
@@ -14,7 +14,7 @@ Tiles are one way to build apps in Landscape, the Urbit web interface. This docu
14
14
15It's recommended to always use this process in this section when creating a tile, even when your knowledge becomes more advanced. It makes development much easier.
15It's recommended to always use this process in this section when creating a tile, even when your knowledge becomes more advanced. It makes development much easier.
16
16
17−First and foremost, you'll need to have a [mounted fakezod](/docs/using/creating-development-ship) of Urbit version 0.8.0 or higher.
17+First and foremost, you'll need to have a [mounted fakezod](@/using/develop.md#creating-a-development-ship) of Urbit version 0.8.0 or higher.
18
18
19Then you'll need to get the pre-built tools that were mentioned. Navigate to [urbit/create-landscape-app](https://github.com/urbit/create-landscape-app) and click the green `Use this template` button on to copy the repo to your own account. After that, you will need to clone that new repository locally, using either the `git clone <repo-url>` terminal command, or by clicking the `Clone or download` button on the GitHub.
19Then you'll need to get the pre-built tools that were mentioned. Navigate to [urbit/create-landscape-app](https://github.com/urbit/create-landscape-app) and click the green `Use this template` button on to copy the repo to your own account. After that, you will need to clone that new repository locally, using either the `git clone <repo-url>` terminal command, or by clicking the `Clone or download` button on the GitHub.
20Once you've cloned the repo, `cd` into the newly downloaded folder and run `npm install` to install dependencies. After that, run `npm start` to start the setup wizard.
20Once you've cloned the repo, `cd` into the newly downloaded folder and run `npm install` to install dependencies. After that, run `npm start` to start the setup wizard.