mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-08-16 17:20:35 +03:00
fix header levels so ToC is correct
This commit is contained in:
parent
f3bc2a2661
commit
d891ad1e3e
@ -3,8 +3,6 @@ title = "%ahoy Ship Monitoring"
|
||||
weight = 10
|
||||
+++
|
||||
|
||||
# `%ahoy` Ship Monitoring
|
||||
|
||||
The `%ahoy` desk by [~midden-fabler](https://urbit.org/ids/~midden-fabler) provides a number of agents to automatically monitor ship activity such as breaching and network uptime. This tutorial examines the `%ahoy` agent specifically with some slight simplifications to demonstrate how an Urbit-native app can be constructed. You will see how to render a front-end using Sail, employ the `++abet` nested core design pattern, construct CLI generators, and set wakeup timers using [Behn](https://developers.urbit.org/reference/glossary/behn).
|
||||
|
||||
`%ahoy` presents a web UI at `/ahoy` rendered using [Sail](https://developers.urbit.org/guides/additional/sail) and [~paldev](https://urbit.org/ids/~paldev)'s Rudder library alongside command-line generators to add, delete, and modify ship watches. Notifications are sent using `%hark-store` if a ship hasn't been contacted after a specified amount of time.
|
||||
|
@ -3,8 +3,6 @@ title = "%feature Page Hosting"
|
||||
weight = 160
|
||||
+++
|
||||
|
||||
# `%feature` Page Hosting
|
||||
|
||||
[`%feature`](https://github.com/hanfel-dovned/Feature) by [~hanfel-dovned](https://urbit.org/ids/~hanfel-dovned) hosts a simple HTML page from an Urbit ship at an associated URL. This tutorial examines how it uses the middleware [`%schooner`](https://github.com/dalten-collective/schooner/) library by Quartus to return a web page when contacted by a web browser. You will learn how a basic site hosting app can handle HTTP requests and render a page using an `%html` mark.
|
||||
|
||||
`%feature` presents a web page from `/app/feature-ui` at `/apps/feature/feature-ui`. These paths are both configurable by the developer.
|
||||
|
@ -3,8 +3,6 @@ title = "%flap JS Client"
|
||||
weight = 60
|
||||
+++
|
||||
|
||||
# `%flap` JS Client
|
||||
|
||||
## Introduction
|
||||
|
||||
In this tutorial, we will take an off-the-shelf JavaScript game which runs in the browser and connect it to an Urbit back-end. This page assumes that you have completed some version of Hoon School and App School, whether the [live courses](/courses) or the [written docs](/guides/core/hoon-school/A-intro). Our goal is to show you one way of directly serving client code from an Urbit ship as server.
|
||||
|
@ -4,7 +4,7 @@ description = "Learn to write tests with Aqua"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
# Concepts
|
||||
## Concepts
|
||||
|
||||
Aqua (short for "aquarium", alluding to the idea that you're running
|
||||
multiple ships in a safe, artificial environment and watching them
|
||||
@ -14,7 +14,7 @@ within a single host.
|
||||
pH is a library of functions designed to make it easy to write
|
||||
integration tests using Aqua.
|
||||
|
||||
# First test
|
||||
## First test
|
||||
|
||||
To run your first pH test, run the following commands:
|
||||
|
||||
@ -64,7 +64,7 @@ breaches, mock http clients or servers, or anything you can imagine.
|
||||
Check out `/lib/ph/io.hoon` for other available functions, and look at
|
||||
other tests in `/ted/ph/` for inspiration.
|
||||
|
||||
# Reference
|
||||
## Reference
|
||||
|
||||
Aqua has the following commands:
|
||||
|
||||
|
@ -3,11 +3,9 @@ title = "Competitive Programming"
|
||||
weight = 10
|
||||
+++
|
||||
|
||||
# Competitive Programming
|
||||
|
||||
Let's take a quick look at implementations for some common tasks in Hoon. I assume that you want to use library tools whenever possible, but you can delve into the source code itself if you want to know more.
|
||||
|
||||
### Sorting
|
||||
## Sorting
|
||||
|
||||
- Given a `list` of values, sort the values according to a given rule and produce a `list`.
|
||||
|
||||
@ -44,7 +42,7 @@ If something isn't a `list`, the easiest way to sort it is to convert it to a `l
|
||||
~[1 2 3 4 5 6 7 8 9 10]
|
||||
```
|
||||
|
||||
### Bitwise Operations
|
||||
## Bitwise Operations
|
||||
|
||||
Bitwise operations are necessary when you are closely packing data into binary formats or otherwise dealing with binary data. Basically there are three scenarios:
|
||||
|
||||
@ -52,7 +50,7 @@ Bitwise operations are necessary when you are closely packing data into binary f
|
||||
2. Working with MIME-type data. Urbit has standard library support for yielding and parsing these, but it's sometimes a bit confusing where they may be located.
|
||||
3. Directly processing particular kinds of data streams, like audio or video data. On Urbit, you'll be serving these or interfacing with an external service. (Remember, Urbit is more like a server than a GPU.)
|
||||
|
||||
#### Binary Operations
|
||||
### Binary Operations
|
||||
|
||||
If you are working with packed binary data, you'll typically print the atom data with a `@ux` unsigned hexadecimal aura.
|
||||
|
||||
@ -153,7 +151,7 @@ Standard bitwise logical operations are available:
|
||||
0b1111.1111.1111.0100
|
||||
```
|
||||
|
||||
#### MIME Data Operations
|
||||
### MIME Data Operations
|
||||
|
||||
[MIME data types](https://en.wikipedia.org/wiki/MIME) allow HTTP communications to include rich content. The `++html` core in the standard library provides quite a few operations for encoding and decoding MIME-typed values.
|
||||
|
||||
@ -187,7 +185,7 @@ There are operations for JSON, [Base58](https://en.wikipedia.org/wiki/Binary-to-
|
||||
|
||||
Urbit furthermore has a notion of _jammed noun_, which is essentially a serialization (marshaling, pickling) of a noun into an atom.
|
||||
|
||||
### Primes and Factors
|
||||
## Primes and Factors
|
||||
|
||||
To calculate a prime number, the tried-and-true method is the Sieve of Eratosthenes, which is an elimination algorithm. In other words, we need to be able to calculate factors of a given positive integer. We're actually going to do an even simpler (and less efficient) method here, and leave the Sieve as an exercise to the reader.
|
||||
|
||||
@ -234,7 +232,7 @@ Now that we can find factors, it should be straightforward to find primes. In t
|
||||
|
||||
- How would you change this algorithm to the more efficient Sieve of Eratosthenes?
|
||||
|
||||
### Pragmatic Input/Output
|
||||
## Pragmatic Input/Output
|
||||
|
||||
While Hoon has a sophisticated text parsing library, the primitives are rather low-level and we won't assume that you want to directly implement a parser using them in a rapid-fire competitive environment.
|
||||
|
||||
@ -245,11 +243,11 @@ Fortunately, there is a regular expression library you can incorporate into your
|
||||
|
||||
- https://github.com/lynko/re.hoon
|
||||
|
||||
### Functional Operators
|
||||
## Functional Operators
|
||||
|
||||
Hoon is a functional programming language, so naturally it supports the basic collective operations which functional programming languages expect.
|
||||
|
||||
#### Curry
|
||||
### Curry
|
||||
|
||||
[_Currying_](https://en.wikipedia.org/wiki/Currying) describes taking a function of multiple arguments and reducing it to a set of functions that each take only one argument. _Binding_, an allied process, is used to set the value of some of those arguments permanently. Hoon has a left-bind `++cury` and a right-bind `++curr`.
|
||||
|
||||
@ -265,7 +263,7 @@ Hoon is a functional programming language, so naturally it supports the basic co
|
||||
117
|
||||
```
|
||||
|
||||
#### Map
|
||||
### Map
|
||||
|
||||
The Map operation describes applying a function to each item of a set or iterable object, resulting in the same final number of items transformed. In Hoon terms, we would say slamming a gate on each member of a `list` or `set`. The standard library arms that accomplish this include [`++turn`](https://developers.urbit.org/reference/hoon/stdlib/2b#turn) for a `list`, [`++run:in`](https://developers.urbit.org/reference/hoon/stdlib/2h#repin) for a `set`, and [`++run:by`](https://developers.urbit.org/reference/hoon/stdlib/2i#runby) for a `map`.
|
||||
|
||||
@ -273,7 +271,7 @@ The Map operation describes applying a function to each item of a set or iterabl
|
||||
> (turn `(list @ud)`~[1 2 3 4 5] one)
|
||||
```
|
||||
|
||||
#### Reduce
|
||||
### Reduce
|
||||
|
||||
The Reduce operation applies a function as a sequence of pairwise operations to each item, resulting in one summary value. The standard library arms that accomplish this are [`++roll`](https://developers.urbit.org/reference/hoon/stdlib/2b#roll) and [`++reel`](https://developers.urbit.org/reference/hoon/stdlib/2b#reel) for a `list`, [`++rep:in`](https://developers.urbit.org/reference/hoon/stdlib/2h#repin) for a `set`, and [`++rep:by`](https://developers.urbit.org/reference/hoon/stdlib/2i#repby) for a `map`.
|
||||
|
||||
@ -284,7 +282,7 @@ The Reduce operation applies a function as a sequence of pairwise operations to
|
||||
b=120
|
||||
```
|
||||
|
||||
#### Filter
|
||||
### Filter
|
||||
|
||||
The Filter operation applies a true/false function to each member of a collection, resulting in some number of items equal to or fewer than the size of the original set. In Hoon, the library arms that carry this out include [`++skim`](https://developers.urbit.org/reference/hoon/stdlib/2b#skim), [`++skid`](https://developers.urbit.org/reference/hoon/stdlib/2b#skid), [`++murn`](https://developers.urbit.org/reference/hoon/stdlib/2b#murn) for a `list`, and [`++rib:by`](https://developers.urbit.org/reference/hoon/stdlib/2i#ribby) for a `map`.
|
||||
|
||||
@ -297,7 +295,7 @@ An interesting feature of Hoon is that it really prefers functions-that-produce-
|
||||
|
||||
- [Functional Programming](https://developers.urbit.org/guides/core/hoon-school/Q-func) - This module will discuss some gates-that-work-on-gates and other assorted operators that are commonly recognized as functional programming tools.
|
||||
|
||||
### Floating-Point Operations
|
||||
## Floating-Point Operations
|
||||
|
||||
`@ud` unsigned decimal operations are, of course, postive-integer-only. For floating-point maths, you will need to work with `@rs` for 32-bit single-precision IEEE 754 floating-point atoms. These are prefixed with a single `.` which is _not_ a decimal point.
|
||||
|
||||
@ -332,7 +330,7 @@ Equivalent mathematical operations for `@rs` values are available in the `++rs`
|
||||
|
||||
(I picked the above set of examples after perusing the excellent book [Antti Laaksonen (2017) _Guide to Competitive Programming: Learning and Improving Algorithms Through Contests_](https://link.springer.com/book/10.1007/978-3-319-72547-5).)
|
||||
|
||||
### Debugging and Troubleshooting
|
||||
## Debugging and Troubleshooting
|
||||
|
||||
Static typing with compile-time type checking turns out to be a secret strength of Hoon. Once you've satisfied the typechecker, your code is often surprisingly free of bugs (compared to e.g. Python).
|
||||
|
||||
|
@ -3,7 +3,7 @@ title = "Gleichniszahlenreihe"
|
||||
weight = 30
|
||||
+++
|
||||
|
||||
# Challenge: The Look-and-Say Sequence
|
||||
## Challenge: The Look-and-Say Sequence
|
||||
|
||||
_Gleichniszahlenreihe_, or the [look-and-say sequence](https://en.wikipedia.org/wiki/Look-and-say_sequence), is constructed from an aural description of a sequence of numbers.
|
||||
|
||||
@ -13,7 +13,7 @@ This is a fairly complicated program. You need a few parts: the ability to tak
|
||||
|
||||
- Compose a `%say` generator which carries out the look-and-say sequence calculation for a given input. The input should be a number which indicates which value in the sequence is desired (e.g. 1→1, 2→11, 3→21).
|
||||
|
||||
## Solutions
|
||||
## Solutions
|
||||
|
||||
_These solutions were submitted by the Urbit community as part of the Hoon School Live ~2022.2 cohort. They are made available under both the [MIT license](https://mit-license.org/) and the [CC0 license](https://creativecommons.org/share-your-work/public-domain/cc0). We ask you to acknowledge authorship should you utilize these elsewhere._
|
||||
|
||||
|
@ -3,7 +3,7 @@ title = "Rhonda Numbers"
|
||||
weight = 48
|
||||
+++
|
||||
|
||||
# Challenge: Rhonda Numbers
|
||||
## Challenge: Rhonda Numbers
|
||||
|
||||
A Rhonda number is a positive integer _n_ that satisfies the property that, for [a given base _b_](https://en.wikipedia.org/wiki/Radix), the product of the base-_b_ digits of _n_ is equal to _b_ times the sum of _n_'s prime factors. Only composite bases (non-prime bases) have Rhonda numbers.
|
||||
|
||||
|
@ -3,7 +3,7 @@ title = "Roman Numerals"
|
||||
weight = 50
|
||||
+++
|
||||
|
||||
# Challenge: Printing and Parsing Roman Numerals
|
||||
## Challenge: Printing and Parsing Roman Numerals
|
||||
|
||||
Roman numerals constitute a numeral system capable of expressing positive integers by additive values (rather than place-number notation). Additive series are produced by summing values in a series, as `iii` → 3, while subtractive values are produced by prepending certain smaller values ahead of a larger value, as `ix` → 9.
|
||||
|
||||
@ -36,7 +36,7 @@ Roman numerals constitute a numeral system capable of expressing positive intege
|
||||
|
||||
**Note**: This design pattern is not optimal since analysis over a union of some types can be difficult to carry out, and it would be better to either separate the generators or use a flag. In this case, the pattern works because we are distinguishing an atom from a cell.
|
||||
|
||||
## Unit Tests
|
||||
## Unit Tests
|
||||
|
||||
Following a principle of test-driven development, we compose a series of tests which allow us to rigorously check for expected behavior.
|
||||
|
||||
@ -866,7 +866,7 @@ Following a principle of test-driven development, we compose a series of tests w
|
||||
--
|
||||
```
|
||||
|
||||
## Solutions
|
||||
## Solutions
|
||||
|
||||
_These solutions were submitted by the Urbit community as part of a competition in ~2022.6. They are made available under both the [MIT license](https://mit-license.org/) and the [CC0 license](https://creativecommons.org/share-your-work/public-domain/cc0). We ask you to acknowledge authorship should you utilize these elsewhere._
|
||||
|
||||
|
@ -3,9 +3,7 @@ title = "Solitaire Cipher"
|
||||
weight = 60
|
||||
+++
|
||||
|
||||
# Solitaire Cipher
|
||||
|
||||
## Challenge: Solitaire Encryption Cipher
|
||||
## Challenge: Solitaire Encryption Cipher
|
||||
|
||||
The [Solitaire or Pontifex algorithm](https://en.wikipedia.org/wiki/Solitaire_%28cipher%29) is a cryptographic algorithm designed by cryptographer [Bruce Schneier](https://www.schneier.com/academic/solitaire/) based on coordinating two decks of cards so that they can be used to communicate between two field agents. Given a standard deck of 52 playing cards and two distinguishable jokers, a message may be encrypted as a keystream, or sequence of values combined with the message to encrypt or decrypt it. The algorithm features prominently in Neal Stephenson's novel _Cryptonomicon_.
|
||||
|
||||
@ -43,7 +41,7 @@ To generate one character:
|
||||
The foregoing hyperlinks showcase worked examples of Solitaire in action.
|
||||
|
||||
|
||||
## Solutions
|
||||
## Solutions
|
||||
|
||||
_This solution was produced by ~rabsef-bicrym. It is made available under the [GNU GPL](https://github.com/rabsef-bicrym/urbitasofia/blob/master/LICENSE). (Note that this is different from the other code snippets on this site, which are made available under the [MIT license](https://mit-license.org/)._
|
||||
|
||||
|
@ -14,7 +14,7 @@ The best place to start when building a new agent is its type definitions in its
|
||||
Let's look at each of these questions in turn, and put together our agent's
|
||||
`/sur` file, which we'll call `/sur/journal.hoon`.
|
||||
|
||||
### 1. Basic types
|
||||
## 1. Basic types
|
||||
|
||||
Our journal entries will just be plain text, so a simple `@t` will work fine to
|
||||
store their contents. Entries will be organized by date, so we'll also need to
|
||||
@ -34,7 +34,7 @@ The structure for a journal entry can therefore be:
|
||||
+$ entry [=id =txt]
|
||||
```
|
||||
|
||||
### 2. Actions
|
||||
## 2. Actions
|
||||
|
||||
Now that we know what a journal entry looks like, we can think about what kind
|
||||
of actions/commands our agent will handle in its `++on-poke` arm. For our
|
||||
@ -54,7 +54,7 @@ We can create a tagged union structure for these actions, like so:
|
||||
==
|
||||
```
|
||||
|
||||
### 3. Updates
|
||||
## 3. Updates
|
||||
|
||||
Updates are a little more complicated than our actions. Firstly, our front-end
|
||||
needs to be able to retrieve an initial list of journal entries to display. Once
|
||||
@ -113,7 +113,7 @@ milliseconds since the Unix Epoch:
|
||||
==
|
||||
```
|
||||
|
||||
### 4. State
|
||||
## 4. State
|
||||
|
||||
We need to store two things in our state: the journal entries and the update
|
||||
log. We could just use a couple of `map`s like so:
|
||||
|
@ -27,7 +27,7 @@ here](https://github.com/urbit/urbit/tree/master/pkg/npm/api).
|
||||
|
||||
Here is the reference material for each section of this walkthrough.
|
||||
|
||||
#### Types
|
||||
### Types
|
||||
|
||||
- [App School /sur section](/guides/core/app-school/7-sur-and-marks#sur) -
|
||||
This section of App School covers writing a `/sur` structure library for
|
||||
@ -38,7 +38,7 @@ Here is the reference material for each section of this walkthrough.
|
||||
This section of `zuse.hoon` contains all the functions for working with
|
||||
`mop`s, and is well commented.
|
||||
|
||||
#### Agent
|
||||
### Agent
|
||||
|
||||
- [App School I](/guides/core/app-school/intro) - App School I covers all
|
||||
aspects of writing Gall agents in detail.
|
||||
@ -52,7 +52,7 @@ Here is the reference material for each section of this walkthrough.
|
||||
The `agentio` library in the `%base` desk contains a large number of useful
|
||||
functions which making writing Gall agents easier.
|
||||
|
||||
#### JSON
|
||||
### JSON
|
||||
|
||||
- [The JSON Guide](/guides/additional/json-guide) - The stand-alone JSON guide
|
||||
covers JSON encoding/decoding in great detail.
|
||||
@ -69,7 +69,7 @@ Here is the reference material for each section of this walkthrough.
|
||||
- [Eyre Overview](/reference/arvo/eyre/eyre) - This section of the Eyre vane
|
||||
documentation goes over the basic features of the Eyre vane.
|
||||
|
||||
#### Marks
|
||||
### Marks
|
||||
|
||||
- [The Marks section of the Clay documentation](/reference/arvo/clay/marks/marks) -
|
||||
This section of the Clay vane documentation covers mark files comprehensively.
|
||||
@ -80,7 +80,7 @@ Here is the reference material for each section of this walkthrough.
|
||||
- [The JSON Guide](/guides/additional/json-guide) - This also covers writing mark
|
||||
files to convert to/from JSON.
|
||||
|
||||
#### Eyre
|
||||
### Eyre
|
||||
|
||||
- [The Eyre vane documentation](/reference/arvo/eyre/eyre) - This section of the vane
|
||||
docs covers all aspects of Eyre.
|
||||
@ -91,7 +91,7 @@ Here is the reference material for each section of this walkthrough.
|
||||
documentation walks through using Eyre's external API at a low level (using
|
||||
`curl`).
|
||||
|
||||
#### React App Setup and Logic
|
||||
### React App Setup and Logic
|
||||
|
||||
- [HTTP API Guide](/guides/additional/http-api-guide) - Reference documentation for
|
||||
`@urbit/http-api`.
|
||||
@ -104,7 +104,7 @@ Here is the reference material for each section of this walkthrough.
|
||||
code](https://github.com/urbit/urbit/tree/master/pkg/npm/http-api) - The
|
||||
source code for the `@urbit/http-api` NPM package.
|
||||
|
||||
#### Desk and Glob
|
||||
### Desk and Glob
|
||||
|
||||
- [App publishing/distribution docs](/guides/additional/software-distribution) -
|
||||
Documentation covering third party desk composition, publishing and
|
||||
|
@ -11,13 +11,13 @@ cryptography on Urbit. We first summarize the two categories of keys and how
|
||||
they are utilized by each ship type, then cover how different parts of Urbit are
|
||||
involved in cryptography.
|
||||
|
||||
### Types of keys
|
||||
## Types of keys
|
||||
|
||||
The two categories of keys are your Azimuth/Ethereum keys and your networking
|
||||
keys. In both cases, these are public/private key pairs utilized for public key
|
||||
cryptography.
|
||||
|
||||
#### Azimuth keys
|
||||
### Azimuth keys
|
||||
|
||||
Your Urbit ID exists as an ERC-721 non-fungible token on the Ethereum
|
||||
blockchain, and as such is contained in a wallet whose private key you possess.
|
||||
@ -44,7 +44,7 @@ private keys there is no way to retrieve them somehow from your ship.
|
||||
For more information on the usage of these keys and the associated proxies, see
|
||||
the [Azimuth documentation](/reference/azimuth/azimuth).
|
||||
|
||||
#### Networking keys
|
||||
### Networking keys
|
||||
|
||||
All communications in Urbit over the [Ames](/reference/glossary/ames) network
|
||||
are end-to-end encrypted, and thus your ship stores its own public/private pair
|
||||
@ -83,7 +83,7 @@ other method. This is merely a technical limitation imposed by the design of the
|
||||
system, not an intentional handicapping of comet abilities. A workaround to this
|
||||
limitation is slated to be implemented as of May 2021.
|
||||
|
||||
### System components
|
||||
## System components
|
||||
|
||||
[Ames](/reference/arvo/ames/ames) is Arvo's networking vane. All packets sent by
|
||||
Ames are encrypted utilizing a cryptosuite found in `zuse`. The only exception
|
||||
@ -113,7 +113,7 @@ infrastructure utilized by Urbit. `azimuth-tracker` obtains networking public
|
||||
keys for planets, stars, and galaxies from this store, which are then stored in
|
||||
Jael and utilized by Ames for end-to-end encrypted communication.
|
||||
|
||||
### Additional documentation
|
||||
## Additional documentation
|
||||
|
||||
The following pages contained more detailed information about the cryptography
|
||||
utilized by each of the system components.
|
||||
|
@ -43,7 +43,7 @@ DVCSes, and more.
|
||||
Clay has two other unique properties that we'll cover later on:
|
||||
it supports typed data and is referentially transparent.
|
||||
|
||||
### Revision Control
|
||||
## Revision Control
|
||||
|
||||
Every urbit has one or more desks, which are independently
|
||||
revision-controlled branches. Each desk contains its own `mark`
|
||||
@ -113,7 +113,7 @@ from revision 5 of the `%base` desk on `~sampel-sipnym`, we refer to
|
||||
`/~sampel-sipnym/base/5/try/readme/md`. Clay's namespace is thus
|
||||
global and referentially transparent.
|
||||
|
||||
### A Typed Filesystem
|
||||
## A Typed Filesystem
|
||||
|
||||
Since Clay is a general filesystem for storing data of arbitrary
|
||||
types, in order to revision control correctly it needs to be
|
||||
@ -169,7 +169,7 @@ As far as we are aware, Clay is the first generalized,
|
||||
type-aware revision control system. We'll go into the workings
|
||||
of this system in some detail.
|
||||
|
||||
### Marks
|
||||
## Marks
|
||||
|
||||
Central to a typed filesystem is the idea of file types. In Clay, we
|
||||
call these `mark`s. See the [Marks](/reference/arvo/clay/marks/marks)
|
||||
|
@ -20,14 +20,14 @@ zuse. Second is the write, query, and subscription logic. Finally, there
|
||||
is the logic for communicating requests to, and receiving requests from,
|
||||
foreign ships.
|
||||
|
||||
### User documentation
|
||||
## User documentation
|
||||
|
||||
[Filesystem](https://urbit.org/using/os/filesystem)
|
||||
|
||||
How to interact with the Clay filesystem via Dojo. This includes basics such as
|
||||
mounting to Unix, changing directory, merging, and listing files.
|
||||
|
||||
### Developer Documentation
|
||||
## Developer Documentation
|
||||
|
||||
[Architecture](/reference/arvo/clay/architecture)
|
||||
|
||||
|
@ -3,17 +3,17 @@ title = "Scries"
|
||||
weight = 40
|
||||
+++
|
||||
|
||||
### What is a scry?
|
||||
## What is a scry?
|
||||
|
||||
A scry is a read-only request to Arvo's global namespace.
|
||||
|
||||
Vanes and agents define _scry endpoints_ which allow one to request data from their respective states. The endpoints can process the data in any way before returning it, but they cannot alter the actual state - scries can _only_ read, not modify.
|
||||
|
||||
### Why scry?
|
||||
## Why scry?
|
||||
|
||||
The subject available in something like a Gall agent or thread contains a great many functions and structures from the standard library as well as `zuse` and `lull`, but it does not include any of the actual data stored elsewhere in the ship. All it has is its own state, a `bowl` and any `card`s it has been passed. Ordinarily, in order to access such data, one would need to `%poke` or `%watch` other agents, or `%pass` `task`s to vanes, then wait for a response. Arvo's scry system is the one exception to this; it allows direct retrieval of data from other vanes or agents in situ, from any context, without any of the normal messaging rigmarole.
|
||||
|
||||
### How do I scry?
|
||||
## How do I scry?
|
||||
|
||||
Scries are performed exclusively with the dotket rune: `.^`
|
||||
|
||||
@ -25,11 +25,11 @@ One further note on `care`s (which can sometimes be confusing): While `care`s ar
|
||||
|
||||
Most other vanes also make use of `care`s in their scry endpoints. While such vanes don't have corresponding submodules with strictly defined behaviour like Clay, the `care`s still confer the general nature of the endpoint. The most widely used `care` is `%x`, which implies reading data in a general sense. Gall has special handling of `%x` scries as described in the [Gall agents](#gall-agents) section below, but otherwise `care`s have no special behaviour for non-Clay vanes (though they must still be included if the endpoint specifies it).
|
||||
|
||||
### What can I scry?
|
||||
## What can I scry?
|
||||
|
||||
There are two places where scry endpoints are defined:
|
||||
|
||||
#### Vanes
|
||||
### Vanes
|
||||
|
||||
Each of Arvo's nine vanes (kernel modules) include a `+scry` arm which defines
|
||||
that vane's scry endpoints. The number of endpoints and extent of data available
|
||||
@ -43,13 +43,13 @@ endpoints you'd not typically use in your applications).
|
||||
|
||||
To explore what scry endpoints are available for vanes, you can refer to the Scry Reference section of each vane in the [Arvo](/reference/arvo/overview) section of the documents.
|
||||
|
||||
#### Gall agents
|
||||
### Gall agents
|
||||
|
||||
Gall has a single scry endpoint of its own to check for the existence of an agent, but otherwise all Gall scries are passed through to one of the agents it manages. The target agent to scry is specified in place of the `desk` as described in the diagram above. Each Gall agent includes a `+on-peek` arm that defines its own scry endpoints. For example, `%graph-store` has a number of scry endpoints to access the data it stores, such as chat messages and the like.
|
||||
|
||||
Gall agents can expose scry endpoints with any `care`, but most commonly they'll take a `%x` `care`. Gall handles `%x` scries specially - it expects an extra field at the end of the `path` that specifies a `mark`. Gall will attempt to perform a `mark` conversion from the `mark` returned by the scry endpoint to the `mark` specified. Note the trailing `mark` in the `path` will not be passed through to the agent itself.
|
||||
|
||||
### What is an endpoint?
|
||||
## What is an endpoint?
|
||||
|
||||
"Endpoint" refers to a specific scry path in a vane or agent. They will sometimes informally be noted in documentation or source comments like `/x/foo/bar/baz` or maybe just `/foo/bar/baz`. The first part of the former example is the `care`, then the rest is the `path` portion as noted in the diagram earlier.
|
||||
|
||||
@ -69,11 +69,11 @@ The case in the beginning says it takes a `%x` `care` and has a `path` of `/keys
|
||||
.^(json %gx /(scot %p our)/graph-store/(scot %da now)/keys/json)
|
||||
```
|
||||
|
||||
### Web scries
|
||||
## Web scries
|
||||
|
||||
The webserver vane Eyre has a system which allows clients like web browsers to perform scries over HTTP. For details, refer to the [Scry section of Eyre's External API Reference](/reference/arvo/eyre/external-api-ref#scry).
|
||||
|
||||
### Further reading
|
||||
## Further reading
|
||||
|
||||
[dotket](/reference/hoon/rune/dot#-dotket) - Documentation of the `.^` rune which performs scries.
|
||||
|
||||
|
@ -35,9 +35,9 @@ The Gall agents involved with Azimuth are summarized as follows:
|
||||
|
||||
The transaction processing library is [`/lib/naive.hoon`](#naive).
|
||||
|
||||
### Gall agents
|
||||
## Gall agents
|
||||
|
||||
#### `%azimuth` {% #azimuth %}
|
||||
### `%azimuth` {% #azimuth %}
|
||||
|
||||
`%azimuth`, located at `/app/azimuth.hoon`, is a Gall agent and thread handler
|
||||
responsible for finding Azimuth transactions gathered by `%eth-watcher`,
|
||||
@ -79,12 +79,12 @@ Scries can be inferred from the `+on-peek` arm:
|
||||
==
|
||||
```
|
||||
|
||||
#### `%azimuth-rpc` {% #azimuth-rpc %}
|
||||
### `%azimuth-rpc` {% #azimuth-rpc %}
|
||||
|
||||
`%azimuth-rpc`, located at `app/azimuth-rpc.hoon`, is a JSON RPC-API for getting
|
||||
`point` and `dns` data from the Azimuth PKI state kept by `%azimuth`.
|
||||
|
||||
#### `%eth-watcher` {% #eth-watcher %}
|
||||
### `%eth-watcher` {% #eth-watcher %}
|
||||
|
||||
`%eth-watcher`, located at `/app/eth-watcher.hoon`, is responsible for listening
|
||||
to an Ethereum node and collecting event logs from it. It is general-purpose and
|
||||
@ -94,7 +94,7 @@ not particular to Azimuth. It sends collected transactions to `+on-agent` in
|
||||
|
||||
[![Eth-watcher](https://media.urbit.org/docs/layer2/roller-agents.png)](https://media.urbit.org/docs/layer2/roller-agents.png)
|
||||
|
||||
#### `%roller` {% #roller %}
|
||||
### `%roller` {% #roller %}
|
||||
|
||||
`%roller`, stored at `/app/roller.hoon`, is a Gall agent responsible for
|
||||
collecting and submitting batches of layer 2 transactions to the Ethereum
|
||||
@ -142,7 +142,7 @@ This app is not responsible for communicating with Bridge via HTTP. Instead, tha
|
||||
handled by `%roller-rpc`. The scries are also communicated to Bridge via
|
||||
`%roller-rpc`.
|
||||
|
||||
#### `%roller-rpc`
|
||||
### `%roller-rpc`
|
||||
|
||||
`%roller-rpc`, stored at `/app/roller-rpc.hoon`, is a very simple Gall app responsible for receiving HTTP RPC-API
|
||||
calls, typically sent from other Urbit ID users via Bridge. It then translates
|
||||
@ -152,7 +152,7 @@ does not keep any state - its only purpose is to act as an intermediary between
|
||||
Bridge and `%roller`. See [here](/reference/azimuth/l2/layer2-api) for more
|
||||
information on the JSON RPC-API.
|
||||
|
||||
### `naive.hoon` {% #naive %}
|
||||
## `naive.hoon` {% #naive %}
|
||||
|
||||
`/lib/naive.hoon` consists of a gate whose sample is a `verifier`, `chain-id=@ud`,
|
||||
`state`, and `input`, which outputs a cell of `[effects state]`. This is the
|
||||
|
@ -23,7 +23,7 @@ HD wallet [below](#hardware-hd-wallet).
|
||||
Urbit HD wallets are composed of the following items, which are each assigned to
|
||||
their own individual Ethereum key-pairs.
|
||||
|
||||
### Master Ticket
|
||||
## Master Ticket
|
||||
|
||||
Think of your master ticket like a very high-value password. The master ticket
|
||||
is the secret code from which all of your other keys are derived. Technically,
|
||||
@ -31,14 +31,14 @@ your master ticket is a cryptographic seed. You should never share it with anyon
|
||||
store it very securely. This ticket can derive all of your other keys: your
|
||||
ownership key and all of the related proxies.
|
||||
|
||||
### Ownership Address
|
||||
## Ownership Address
|
||||
|
||||
An ownership address has all rights over the assets deeded to it. These rights
|
||||
are on-chain actions described and implemented in
|
||||
[Ecliptic](/reference/glossary/ecliptic), Azimuth's suite of governing
|
||||
smart-contracts.
|
||||
|
||||
### Proxies
|
||||
## Proxies
|
||||
|
||||
Each permanent Urbit ID can designate one or more
|
||||
[proxies](https://urbit.org/using/id/proxies), which are Ethereum addresses capable of a
|
||||
@ -46,7 +46,7 @@ limited subset of Urbit ID transactions, such as spawning planets or rotating
|
||||
keys. The HD wallet automatically generates additional addresses utilized as
|
||||
proxies according to what is appropriate for your Urbit ID.
|
||||
|
||||
### HD wallet generation
|
||||
## HD wallet generation
|
||||
|
||||
Your Urbit HD wallet is generated from a `@q` seed called `T`, which looks
|
||||
something like `~sampel-ticket-bucbel-sipnem`. This is the string known as your
|
||||
@ -68,7 +68,7 @@ which will be known as your ownership address. Bridge then automatically uses
|
||||
your ownership address to assign the other proxies to the other wallets
|
||||
generated.
|
||||
|
||||
### ERC-721
|
||||
## ERC-721
|
||||
|
||||
Most Ethereum tokens use the ERC-20 standard for smart contracts. Urbit
|
||||
identities are, however, essentially different from most Ethereum tokens, due to
|
||||
|
@ -17,14 +17,14 @@ while otherwise remaining on layer 1, but it is not possible to transfer only
|
||||
the management proxy to layer 2; it may only happen as a side-effect of
|
||||
transferring ownership to layer 2.
|
||||
|
||||
### Moving a pre-existing ship to L2
|
||||
## Moving a pre-existing ship to L2
|
||||
|
||||
In order to move your ship from layer 1 to layer 2, transfer ownership of your
|
||||
ship to the address `0x1111111111111111111111111111111111111111`. The easiest
|
||||
way to accomplish this is using [Bridge](/reference/glossary/bridge). The Azimuth
|
||||
smart contracts interpret any ship at this address as being on layer 2.
|
||||
|
||||
### Dominion
|
||||
## Dominion
|
||||
|
||||
Layer 2 Azimuth data for a given ship includes which layer that ship is on. We
|
||||
call this the ship's _dominion_. There are three dominions: `%l1`, `l2`, and
|
||||
@ -32,11 +32,11 @@ call this the ship's _dominion_. There are three dominions: `%l1`, `l2`, and
|
||||
of the three dominions, and galaxies may exist in dominion `%l1` or `%spawn`. We
|
||||
detail what this means in each case in the following.
|
||||
|
||||
### Planets
|
||||
## Planets
|
||||
|
||||
*Permitted dominions:* `%l1`, `%l2`.
|
||||
|
||||
#### `%l1` planets
|
||||
### `%l1` planets
|
||||
|
||||
*Permitted layer 2 actions:*
|
||||
- owner: `%escape`, `%cancel-escape`
|
||||
@ -54,7 +54,7 @@ sponsorship actions.
|
||||
Layer 1 planets may also move to dominion `%l2` by depositing their ownership to
|
||||
the layer 2 deposit address.
|
||||
|
||||
#### `%l2` planets
|
||||
### `%l2` planets
|
||||
|
||||
*Permitted layer 2 actions:*
|
||||
- owner: `%transfer-point`, `%configure-keys`,
|
||||
@ -71,11 +71,11 @@ will always be on layer 2.
|
||||
A layer 2 planet is no longer capable of performing any layer 1 actions, and
|
||||
cannot move to layer 1.
|
||||
|
||||
### Stars
|
||||
## Stars
|
||||
|
||||
*Permitted dominions:* `%l1`, `%spawn`, `%l2`.
|
||||
|
||||
#### `%l1` stars
|
||||
### `%l1` stars
|
||||
|
||||
*Permitted layer 2 actions:*
|
||||
- owner: `%escape`, `%cancel-escape`, `%adopt`,
|
||||
@ -94,7 +94,7 @@ A `%l1` dominion star may move to dominion `%spawn` by depositing its spawn prox
|
||||
layer 2 deposit address, or may move to dominion `%l2` by depositing its ownership
|
||||
to the layer 2 deposit address. Both actions are irreversible.
|
||||
|
||||
#### `%spawn` stars
|
||||
### `%spawn` stars
|
||||
|
||||
*Permitted layer 2 actions:*
|
||||
- owner: `%escape`, `%cancel-escape`, `%adopt`,
|
||||
@ -116,7 +116,7 @@ A star moving from `%l1` to `%spawn` has no effect on sponsorship status of any
|
||||
of its sponsored planets. Moving to `%spawn` from `%l1` is currently
|
||||
irreversible - the only further change to dominion permitted is moving to `%l2`.
|
||||
|
||||
#### `%l2` stars
|
||||
### `%l2` stars
|
||||
|
||||
*Permitted layer 2 actions:*
|
||||
- owner: `%transfer-point`, `%spawn`, `%configure-keys`, `%escape`,
|
||||
@ -134,11 +134,11 @@ spawned by a `%spawn` dominion galaxy.
|
||||
|
||||
A star in dominion `%l2` cannot perform any layer 1 actions.
|
||||
|
||||
### Galaxies
|
||||
## Galaxies
|
||||
|
||||
*Permitted dominions:* `%l1`, `%spawn`.
|
||||
|
||||
#### `%l1` galaxies
|
||||
### `%l1` galaxies
|
||||
|
||||
*Permitted layer 2 actions:*
|
||||
- owner: `%adopt`, `%reject`, `%detach`
|
||||
@ -162,7 +162,7 @@ Layer 2 has no interactions with this contract - all stars released in this
|
||||
manner are `%l1` dominion stars. Moving to the `%spawn` dominion has no effect
|
||||
on sponsorship status.
|
||||
|
||||
#### `%spawn` galaxies
|
||||
### `%spawn` galaxies
|
||||
|
||||
*Permitted layer 2 actions:*
|
||||
- owner: `%adopt`, `%reject`, `%detach`, `%spawn`,
|
||||
|
@ -32,7 +32,7 @@ There are three main steps involved with setting up a roller:
|
||||
- starting and configuring `%roller`,
|
||||
- aiming your front-end at the roller
|
||||
|
||||
### 1. Make sure `%azimuth` state is up to date
|
||||
## 1. Make sure `%azimuth` state is up to date
|
||||
|
||||
If you are using an ordinary live ship on the network as the roller, you should
|
||||
already have the latest `%azimuth` state and this step should not be necessary
|
||||
@ -52,7 +52,7 @@ found under the Setting page for the node on infura.io listed under `ENDPOINTS`.
|
||||
If you do not perform this step, you'll later see an error "roller not ready"
|
||||
when the first roller batch is about to be submitted.
|
||||
|
||||
### 2. Starting and configuring `%roller` {% #step2 %}
|
||||
## 2. Starting and configuring `%roller` {% #step2 %}
|
||||
|
||||
This step must be performed whether you're using a fakezod or a live ship.
|
||||
|
||||
@ -125,7 +125,7 @@ work with a front-end if you want to use it on livenet.
|
||||
|
||||
We cover the additional settings for `%roller` at the end.
|
||||
|
||||
### 3. Aiming Bridge at the roller
|
||||
## 3. Aiming Bridge at the roller
|
||||
|
||||
The last step is to set up the web interface by which users can submit
|
||||
transactions to be batched by the roller, which we refer to as the front-end. We
|
||||
@ -153,7 +153,7 @@ REACT_APP_ROLLER_HOST=https://myroller.sampel-pal.net/v1/roller npm run pilot-ma
|
||||
This will launch a server running Bridge that utilizes the mainnet roller you
|
||||
set up at `https://myroller.sampel-pal.net/v1/roller`.
|
||||
|
||||
### Additional `%roller` commmands
|
||||
## Additional `%roller` commmands
|
||||
|
||||
`%roller` has a few other settings and commands for managing things like the
|
||||
rate at which transactions are submitted and manually submitting batches. These
|
||||
|
@ -9,7 +9,7 @@ This is used for type checking as well as pretty printing.
|
||||
|
||||
You can learn more about auras in [Hoon school](/guides/core/hoon-school/B-syntax#nouns).
|
||||
|
||||
### Table of Auras
|
||||
## Table of Auras
|
||||
|
||||
```
|
||||
Aura Meaning Example Literal Syntax
|
||||
@ -48,7 +48,7 @@ Aura Meaning Example Literal Syntax
|
||||
@ux unsigned hexadecimal 0x5f5.e138
|
||||
```
|
||||
|
||||
### Bitwidth
|
||||
## Bitwidth
|
||||
|
||||
Capital letters at the end of auras indicate the bitwidth in binary powers of
|
||||
two, starting from A.
|
||||
@ -61,7 +61,7 @@ two, starting from A.
|
||||
@uvJ unsigned, 512-bit integer (frequently used for entropy)
|
||||
```
|
||||
|
||||
### Nesting
|
||||
## Nesting
|
||||
|
||||
A given aura nests under any aura whose name is a substring or extension of the
|
||||
given aura:
|
||||
@ -94,7 +94,7 @@ This is implicitly done by the irregular form of `^-`.
|
||||
7.303.014
|
||||
```
|
||||
|
||||
### Bunting
|
||||
## Bunting
|
||||
|
||||
The bunt value for all auras is 0 except for `@da`.
|
||||
|
||||
|
@ -4,13 +4,13 @@ weight = 1
|
||||
+++
|
||||
A limb is an attribute of subject.
|
||||
|
||||
### Produces
|
||||
## Produces
|
||||
|
||||
There are two kinds of limbs: arms and legs. An **arm** is a computation of some core. A **leg** is a piece of data in the subject.
|
||||
|
||||
If a limb expression resolves to a leg, the leg is produced. If a limb expression resolves to an arm -- in particular, by way of an arm name -- then the arm is computed with its parent core as the subject. The result of that computation is produced.
|
||||
|
||||
### Syntax
|
||||
## Syntax
|
||||
|
||||
Irregular: `+15` is slot `15`. The value at address `15` of the subject is produced.
|
||||
|
||||
@ -26,7 +26,7 @@ Irregular: `^^^abc` is the name `abc`, but which will skip the first three name
|
||||
|
||||
Irregular: `+<-` is "take the tail, then take the head of that, then the head of that." `+` and `>` mean "tail" while `-` and `<` mean "head." This limb syntax starts on `+` or `-` and alternates with `>` or `<` for readability.
|
||||
|
||||
### Traverse
|
||||
## Traverse
|
||||
|
||||
Name resolution happens by way of a search through the subject. The search traverse takes a name `q` and a **skip count** `p`.
|
||||
|
||||
@ -47,7 +47,7 @@ If the skip count `p` is nonzero, we pretend our first `p`
|
||||
matches are actually mismatches. This lets the programmer "look
|
||||
through" an overriding label.
|
||||
|
||||
### Examples
|
||||
## Examples
|
||||
|
||||
The Dojo prompt gives you a subject with a decent namespace.
|
||||
Try:
|
||||
|
@ -6,15 +6,15 @@ weight = 2
|
||||
|
||||
A wing is a limb search path into the subject.
|
||||
|
||||
### Produces
|
||||
## Produces
|
||||
|
||||
A wing is a list of limbs (including a trivial list of one limb). The limbs are resolved in succession. The result of the last limb resolution is the value produced by the wing expression.
|
||||
|
||||
### Syntax
|
||||
## Syntax
|
||||
|
||||
Irregular: `a.b.c`. Read this as '`a` in `b` in `c`'. Finds limb `a` within limb `b` within limb `c` of the subject.
|
||||
|
||||
### Discussion
|
||||
## Discussion
|
||||
|
||||
Intuitively, Hoon wings are written in the opposite order
|
||||
from attribute dot-paths in most languages. Hoon `a.b.c` is Java's
|
||||
@ -29,7 +29,7 @@ The mysterious idiom `..b` produces the leg `b` if `b`
|
||||
is a leg; the core exporting `b` if `b` is an arm. Since `.`
|
||||
is the same limb as `+`, `..b` is the same wing as `+1.foo`.
|
||||
|
||||
### Examples
|
||||
## Examples
|
||||
|
||||
```
|
||||
~zod:dojo> =a [fod=3 bat=[baz=1 moo=2]]
|
||||
|
@ -11,7 +11,7 @@ language that set it apart from others. If you're looking to learn Hoon, check
|
||||
out our tutorial series called [Hoon School](/guides/core/hoon-school/)
|
||||
below.
|
||||
|
||||
### What can Hoon do that other languages can't?
|
||||
## What can Hoon do that other languages can't?
|
||||
|
||||
The short answer is: implement a purely functional operating system.
|
||||
Try to do this in a principled way in Haskell, and the problems you'll
|
||||
@ -25,7 +25,7 @@ functional languages are:
|
||||
- Typesafe metaprogramming, and
|
||||
- Hot code reload and online data migration.
|
||||
|
||||
### What is Hoon good at?
|
||||
## What is Hoon good at?
|
||||
|
||||
Hoon is mostly good at compiling and running other Hoon code. Urbit
|
||||
consists of many layers of bootstrapping. Several of these layers lean
|
||||
@ -34,7 +34,7 @@ build system, the Dojo shell, and the Arvo kernel itself. Even Urbit's
|
||||
chat application lets you run Hoon expressions and share the results
|
||||
with your friends.
|
||||
|
||||
### Why did we write the OS in Hoon?
|
||||
## Why did we write the OS in Hoon?
|
||||
|
||||
The chain of reasoning goes something like this:
|
||||
|
||||
@ -78,13 +78,13 @@ Urbit's solution to these design constraints. Some Lisps come close to
|
||||
meeting these criteria — and Nock is very Lisp-like — but no practical
|
||||
Lisp dialects are nearly as pure or axiomatic as Nock.
|
||||
|
||||
### What is special about Hoon?
|
||||
## What is special about Hoon?
|
||||
|
||||
It's a purely functional systems language. Calling it a functional
|
||||
analog of C is not too far off in several ways. Almost all code
|
||||
throughout Urbit's kernelspace and userspace is written in Hoon.
|
||||
|
||||
### What properties does Hoon have? What type of language is it?
|
||||
## What properties does Hoon have? What type of language is it?
|
||||
|
||||
Hoon is a statically typed, purely functional, strictly evaluated
|
||||
programming language.
|
||||
@ -215,7 +215,7 @@ Hoon and Nock have several unusual properties:
|
||||
calmness of working with such inert building blocks is addictive, as
|
||||
many Hoon programmers will attest.
|
||||
|
||||
### Why is Hoon the way it is?
|
||||
## Why is Hoon the way it is?
|
||||
|
||||
Minimalism, mostly.
|
||||
|
||||
|
@ -5,7 +5,7 @@ weight = 4
|
||||
Let's run through the `u3` modules one by one. All public
|
||||
functions are commented, but the comments may be cryptic.
|
||||
|
||||
### u3m: main control
|
||||
## u3m: main control
|
||||
|
||||
To start `u3`, run
|
||||
|
||||
@ -77,7 +77,7 @@ and asserts if it finds any leaks or incorrect refcounts. This
|
||||
tool is for debugging and long-term maintenance only; refcounts
|
||||
should never err.
|
||||
|
||||
### u3j: jets
|
||||
## u3j: jets
|
||||
|
||||
The jet system, `u3j`, is what makes `u3` and `nock` in any sense
|
||||
a useful computing environment. Except perhaps `u3a` (there is
|
||||
@ -94,7 +94,7 @@ Indeed such a coupling would be wholly wrongtious and un-Urbit.
|
||||
But the jet system is not Hoon-specific. It is specific to nock
|
||||
runtime systems that use a design pattern we call a `core`.
|
||||
|
||||
#### u3j: core structure
|
||||
### u3j: core structure
|
||||
|
||||
A core is no more than a cell `[code data]`, in which a `code` is
|
||||
either a Nock formula or a cell of `code`s, and `data` is anything.
|
||||
@ -186,7 +186,7 @@ payload to be `[sample static-core]`, or even `[sample core]`.
|
||||
Any such constraint would not be rich enough to handle Hoon,
|
||||
let alone other languages.
|
||||
|
||||
#### u3j: jet state
|
||||
### u3j: jet state
|
||||
|
||||
There are two fundamental rules of computer science: (1) every
|
||||
system is best understood through its state; (2) less state is
|
||||
@ -303,7 +303,7 @@ the dying road. Reaping promotes anything we've learned about
|
||||
any battery that either (a) already existed in the outer road, or
|
||||
(b) is being saved to the outer road.
|
||||
|
||||
#### u3j: jet binding
|
||||
### u3j: jet binding
|
||||
|
||||
Jet binding starts with a `%fast` hint. (In Hoon, this is
|
||||
produced by the runes `~%`, for the general case, or `~/`
|
||||
@ -589,7 +589,7 @@ For historical reasons, all internal jet code in `j/[a-f]`
|
||||
do not do this in new `g` jets! The new standard protocol is to
|
||||
transfer both arguments and results.
|
||||
|
||||
### u3a: allocation functions
|
||||
## u3a: allocation functions
|
||||
|
||||
`u3a` allocates on the current road (u3R). Its internal
|
||||
structures are uninteresting and typical of a naive allocator.
|
||||
@ -677,7 +677,7 @@ threads within its own synchronization primitives - for this to
|
||||
work with `u3a_malloc()`, we'd have to introduce our own locks on
|
||||
the surface-level road (which might be a viable solution).
|
||||
|
||||
### u3n: nock execution
|
||||
## u3n: nock execution
|
||||
|
||||
The `u3n` routines execute Nock itself. On the inside, they have
|
||||
a surprising resemblance to the spec proper (the only interesting
|
||||
@ -823,7 +823,7 @@ caller's exception layer. (Maintaining this illusion is slightly
|
||||
nontrivial.) Finally, `u3n_nock_an()` is a sandbox with a null
|
||||
namespace.
|
||||
|
||||
### u3e: persistence
|
||||
## u3e: persistence
|
||||
|
||||
The only `u3e` function you should need to call is `u3e_save()`,
|
||||
which saves the loom. As it can be restored on any platform,
|
||||
@ -831,7 +831,7 @@ please make sure you don't have any state in the loom that is
|
||||
bound to your process or architecture - except for exceptions
|
||||
like the warm jet state, which is actively purged on reboot.
|
||||
|
||||
### u3r: reading nouns (weak)
|
||||
## u3r: reading nouns (weak)
|
||||
|
||||
As befits accessors they don't make anything, `u3r` noun reading
|
||||
functions always retain their arguments and their returns. They
|
||||
@ -869,14 +869,14 @@ It's important to remember that `u3r_mug()`, which produces a
|
||||
noun as a lazy cache. There are a number of variants of
|
||||
`u3r_mug()` that can get you out of building unneeded nouns.
|
||||
|
||||
### u3x: reading nouns (bail)
|
||||
## u3x: reading nouns (bail)
|
||||
|
||||
`u3x` functions are like `u3r` functions, but instead of
|
||||
returning `u3_none` when (for instance) we try to take the head
|
||||
of an atom, they bail with `%exit`. In other words, they do what
|
||||
the same operation would do in Nock.
|
||||
|
||||
### u3h: hash tables.
|
||||
## u3h: hash tables.
|
||||
|
||||
We can of course use the Hoon `map` structure as an associative
|
||||
array. This is a balanced treap and reasonably fast. However,
|
||||
@ -898,7 +898,7 @@ The only funky function is `u3h_gut()`, which unifies keys with
|
||||
`u3r_sung()`. As with all cases of `u3r_sung()`, this must be
|
||||
used with extreme caution.
|
||||
|
||||
### u3z: memoization
|
||||
## u3z: memoization
|
||||
|
||||
Connected to the `~+` rune in Hoon, via the Nock `%memo` hint,
|
||||
the memoization facility is a general-purpose cache.
|
||||
@ -947,11 +947,11 @@ road, and goes away when it goes away. (In future, we may wish
|
||||
to promote keys/values which outlive the road, as we do with jet
|
||||
state.) There is no cache reclamation at present, so be careful.
|
||||
|
||||
### u3t: tracing and profiling.
|
||||
## u3t: tracing and profiling.
|
||||
|
||||
TBD.
|
||||
|
||||
### u3v: the Arvo kernel
|
||||
## u3v: the Arvo kernel
|
||||
|
||||
An Arvo kernel - or at least, a core that compiles with the Arvo
|
||||
interface - is part of the global `u3` state. What is an Arvo
|
||||
|
@ -13,7 +13,7 @@ says nothing interesting.
|
||||
But some of our idiosyncrasies go beyond convention. Yes, we've
|
||||
done awful things to C. Here's what we did and why we did.
|
||||
|
||||
### c3: integer types
|
||||
## c3: integer types
|
||||
|
||||
First, it's generally acknowledged that underspecified integer
|
||||
types are C's worst disaster. C99 fixed this, but the `stdint`
|
||||
@ -64,7 +64,7 @@ An enormous number of motes are defined in `i/c/motes.h`. There
|
||||
is no reason to delete motes that aren't being used, or even to
|
||||
modularize the definitions. Keep them alphabetical, though.
|
||||
|
||||
### c3: variables and variable naming
|
||||
## c3: variables and variable naming
|
||||
|
||||
The C3 style uses Hoon style TLV variable names, with a quasi
|
||||
Hungarian syntax. This is weird, but works really well, as long
|
||||
@ -93,7 +93,7 @@ c3_w wor_w; // 32-bit word
|
||||
Unlike in standard Hungarian, there is no change for pointer
|
||||
variables. C structure variables take a `_u` suffix.
|
||||
|
||||
### c3: loobeans
|
||||
## c3: loobeans
|
||||
|
||||
The code (from `defs.h`) tells the story:
|
||||
|
||||
|
@ -16,7 +16,7 @@ moment, only libraries directly related to Ames are documented here, though we
|
||||
note that there are jets for other cryptographic functions such as the [SHA
|
||||
Hash Family](/reference/hoon/stdlib/3d) as well.
|
||||
|
||||
### Ed25519 {% #ed %}
|
||||
## Ed25519 {% #ed %}
|
||||
|
||||
Urbit implements [Ed25519](http://ed25519.cr.yp.to/) based on the SUPERCOP
|
||||
"ref10" implementation. Additionally there is key exchanging and scalar addition
|
||||
@ -27,7 +27,7 @@ All code is pure ANSI C without any dependencies, except for the random seed
|
||||
generation which uses standard OS cryptography APIs (CryptGenRandom on Windows,
|
||||
`/dev/urandom` on nix).
|
||||
|
||||
### AES-SIV {% #aes %}
|
||||
## AES-SIV {% #aes %}
|
||||
|
||||
The library we utilize for AES-SIV is an
|
||||
[RFC5297](https://tools.ietf.org/html/rfc5297)-compliant C implementation of
|
||||
|
@ -6,7 +6,7 @@ The division between `c3` and `u3` is that you could theoretically
|
||||
imagine using `c3` as just a generic C environment. Anything to do
|
||||
with nouns is in `u3`.
|
||||
|
||||
### u3: a map of the system
|
||||
## u3: a map of the system
|
||||
|
||||
These are the symbols you'll need to know about to program in `u3`.
|
||||
All files listed below are found in the
|
||||
@ -39,7 +39,7 @@ u3w[a-g] jets (retain, nock core) jets/w.h jets/[a-g]/*.c
|
||||
|
||||
Additionally, various noun type definition are found in `pkg/noun/types.h`.
|
||||
|
||||
### u3: noun internals
|
||||
## u3: noun internals
|
||||
|
||||
A noun is a `u3_noun` - currently defined as a 32-bit `c3_w`.
|
||||
(This is zero-indexed so bit `31` is the high bit.)
|
||||
@ -78,7 +78,7 @@ Also, the value `0xffffffff` is `u3_none`, which is never a valid
|
||||
noun. Use the type `u3_weak` to express that a noun variable may
|
||||
be `u3_none`.
|
||||
|
||||
### u3: reference counts
|
||||
## u3: reference counts
|
||||
|
||||
The only really essential thing you need to know about `u3` is
|
||||
how to handle reference counts. Everything else, you can skip
|
||||
@ -108,7 +108,7 @@ look over your code again.)
|
||||
|
||||
(You can gain or lose a direct atom. It does nothing.)
|
||||
|
||||
### u3: reference protocols
|
||||
## u3: reference protocols
|
||||
|
||||
**THIS IS THE MOST CRITICAL SECTION IN THE `u3` DOCUMENTATION.**
|
||||
|
||||
@ -178,7 +178,7 @@ In general, though, in most places it's not worth thinking about
|
||||
what your function does. There is a convention for it, which
|
||||
depends on where it is, not what it does. Follow the convention.
|
||||
|
||||
### u3: reference conventions
|
||||
## u3: reference conventions
|
||||
|
||||
The `u3` convention is that, unless otherwise specified, **all
|
||||
functions have transfer semantics** - with the exception of the
|
||||
@ -190,7 +190,7 @@ If functions outside this set have retain semantics, they need to
|
||||
be commented, both in the `.h` and `.c` file, with `RETAIN` in
|
||||
all caps. Yes, it's this important.
|
||||
|
||||
### u3: system architecture
|
||||
## u3: system architecture
|
||||
|
||||
If you just want to tinker with some existing code, it might be
|
||||
enough to understand the above. If not, it's probably worth
|
||||
@ -212,7 +212,7 @@ of a computer that never loses state and never fails, we:
|
||||
- can abort any event without damaging the permanent state.
|
||||
- snapshot the permanent state periodically, and/or prune logs.
|
||||
|
||||
### u3: the road model
|
||||
## u3: the road model
|
||||
|
||||
`u3` uses a memory design which I'm sure someone has invented
|
||||
somewhere before, because it's not very clever, but I've never
|
||||
@ -305,7 +305,7 @@ roads - see below - this will become a thread-local variable.)
|
||||
Relative to `u3R`, `+` memory is called `junior` memory; `-`
|
||||
memory is `normal` memory; `~` is `senior` memory.
|
||||
|
||||
### u3: explaining the road model
|
||||
## u3: explaining the road model
|
||||
|
||||
But... why?
|
||||
|
||||
@ -344,13 +344,13 @@ should be discarded in one step by copying the results. Then,
|
||||
within the procedure, we can switch the allocator into `sand`
|
||||
mode, and stop tracking references at all.
|
||||
|
||||
### u3: rules for C programming
|
||||
## u3: rules for C programming
|
||||
|
||||
There are two levels at which we program in C: (1) above the
|
||||
interpreter; (2) within the interpreter or jets. These have
|
||||
separate rules which need to be respected.
|
||||
|
||||
### u3: rules above the interpreter
|
||||
## u3: rules above the interpreter
|
||||
|
||||
In its relations with Unix, Urbit follows a strict rule of "call
|
||||
me, I won't call you." We do of course call Unix system calls,
|
||||
@ -368,7 +368,7 @@ You'd need to make the global road pointer, `u3R`, a thread-local
|
||||
variable instead. This seems perfectly practical, but we haven't
|
||||
done it because we haven't needed to.
|
||||
|
||||
### u3: rules within the interpreter
|
||||
## u3: rules within the interpreter
|
||||
|
||||
Within the interpreter, your code can run either in the surface
|
||||
road or in a deep road. You can test this by testing
|
||||
@ -404,7 +404,7 @@ In deep execution, `c3_assert()` will issue an exception that
|
||||
queues an error event, complete with trace stack, on the Arvo
|
||||
event queue. Let's see how this happens.
|
||||
|
||||
### u3: exceptions
|
||||
## u3: exceptions
|
||||
|
||||
You produce an exception with
|
||||
|
||||
@ -456,7 +456,7 @@ remote node, render the stacktrace as a consequence of the user's
|
||||
action - even if its its direct cause was (for instance) a Unix
|
||||
SIGINT or SIGALRM.
|
||||
|
||||
### u3: C structures on the loom
|
||||
## u3: C structures on the loom
|
||||
|
||||
Normally, all data on the loom is nouns. Sometimes we break this
|
||||
rule just a little, though - eg, in the `u3h` hashtables.
|
||||
|
Loading…
Reference in New Issue
Block a user