urbit / urbit.org

The source for urbit.org

The website for Urbit is maintained by the Urbit Foundation and the Urbit community. Issues and contributions are welcome.

Getting Started

1. Fork the Urbit site repository.

2. Create a local clone of your fork.

3. Navigate to the urbit.org directory and install Node 18 using nvm:

   cd urbit.org
   nvm install 18

   You can then run nvm use whenever in the repository (or automate it with a script - see here).

4. Install our dependencies:

   npm install

5. Run the development server:

   npm run dev
   # or
   yarn dev

   Open http://localhost:3000 with your browser to see the result.

To learn more about contributing, see GitHub's documentation.

Framework and Library Documentation

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

To learn more about Tailwind CSS, take a look at the docs:

• Tailwind CSS Docs - Docs

Deployment

We deploy using Vercel. All pull requests will show a deployment preview via the same.

Upgrades

The /src/scripts contains scripts used to programmatically upgrade site content data.

urbit.org's Issues

Explain difference between %hiss and %them

They are both "make an http request", but %hiss is a wrapper around %them that does mark translation and authentication.

Broken link in docs/hoon/syntax

"Here's the FizzBuzz demo code, in idiomatic rune syntax. Compare with the original." Original is a hyperlink that currently leads to a 404.

Library docs aren't searchable with ^f

A single-page rendering would be much desired. (courtesy of ~hobten-hinrym).

Clarification of What is a Ship and How one comes about

After spending sometime considering what it could possibly mean for the address namespace to be "pre-mined" a wording I realize to be absent from the docs, however still confusing.

If I'm correct, the urbit network requires each peer to retain 3 unique bytes of data. A public key, a private key, and a ship. The public key is a comet, effectively. It is used in combination with the private key to make signatures on urbits. Ownership of a ship by a comet is confirmed informally and then formally signed by a hardcoded entity, or appropriate child thereof. Once the comet's planet is publically established, any signatures corresponding to the elliptic-curve of the comet will be assumed to belong to it's parent. Sovereignty implies that a planet not only speaks for itself that it can not act on behalf of its parent even if it wanted to (it wouldn't be trusted). Essentially every ship, sovereign or otherwise requires a direct comet, in order to indicate a message directly from that step in the hierarchy, without it that ship is mute and can only speak through it's children.

Beyond this, a rogue comet unlike a rogue moon is sovereign in that it speaks for no one and has no parent. Due to a private key being the associated, not even an unsovereign comet can be transferred, because regardless of what ship it belongs to it has no prefix and can easily be mimic-ed by former owners. Essentially anyone who has a comet is sovereign, however no one has any reason to trust or recognized them so their influence is effectively moot and/or second-class, trustless. This also lends a point to having a moon, since a moon can be transferred. Otherwise, the difference in treatment between a moon and a comet would be fickle and volitile.

I may be entirely wrong here, but I guess based on what seems like the most scalable and useful course with the highest potential, so even if I am wrong it may be worth comparing with the reality.

I post this as an issue, because again it's just not a very clear aspect of Urbit and establishing some firm semantics here would be useful for documenting it.

Should document talk message activation

Is it documented somewhere already? It should go in docs/using/messaging, I think?

unable to install libsigsegv-devel on Amazon Linux

With regards to http://urbit.org/docs/using/install/,

I tried recently, and wasn't able to resolve the package, even with yum --enablerepo epel.

I was able to build urbit by manually installing libsigsegv from source -- I just thought the absence of the package should be noted here.

different forms of twig labels are confusing

for example, :cons vs $cons. There's clearly a difference: $cons prints a core (and I don't know how to call it); I can call :cons, but not print it. It seems like it'd be simpler if the twig reference used the :cons form in its descriptions. If the distinction is important in the docs, it would be helpful to call it out explicitly.

This pattern is present on most of the twig-family summary pages, but especially prevalent on these:

• http://urbit.org/docs/hoon/twig/tis-flow/
• http://urbit.org/docs/hoon/twig/wut-test/

the dao blog post is broken

http://urbit.org/blog/dao/

Failing examples for arvo/network

Under arvo/network, the three examples (echo, square, pong) all give different definitions of the door argument. Only the one in echo.hoon works; the others fail with -find.$ or similar. The definitions:

echo.hoon:

|_  {bowl state/$~}

square.hoon:

|_  {bowl state=~}

pong.hoon:

|_  {bowl state=$~}

Both square.hoon and pong.hoon work correctly if given echo.hoon's argument definition.

Tiny lil' misspelling in 'Layout' doc page

https://github.com/urbit/docs/blame/master/docs/using/layout.md#L94

'Default web requets' => 'Default web requests'

That's all ✔️

:moar should be more clearly documented

You can kind of figure out out based on usage, but it deserves its own entry, probably in the twig reference.

Glossary of terms

Because Urbit introduces so many novel terms and nomenclatures, it may be helpful to have a master glossary page added to the docs as a quick reference for everything. As of now, all of the definitions/explanations for these terms are split across multiple categories and subcategories and can be difficult at times to know where to find the one you're looking for.

Irregular form syntax docs were lost in transition

~wolser-lopwyl= i've noticed that there are many usage examples/etc in the hoon
~wolser-lopwyl= reference that use irregular syntax in the examples which the
~wolser-lopwyl= reader may not have been exposed to yet
~wolser-lopwyl= makes it very difficult to decipher the docs sometimes - are
~wolser-lopwyl= there plans for an effort of some kind to 'sanitize' the docs,
--------[5.025]
~wolser-lopwyl= ie: add "long form" exmaples, reduce irregular syntax usage,
~wolser-lopwyl= etc?
~wolser-lopwyl= example: i still haven't come across docs explaining the
~wolser-lopwyl= backtick syntax, so every time i see that in an example i'm
~wolser-lopwyl= unsure exactly what it's illustrating
--------[5.030]
          ~fyr= did the irregular syntax doc not make the cut?
~wolser-lopwyl= what irregular syntax doc?

Code in /arvo/network/ is different from urbit/examples code

Specifically in the section "Sending a message to another urbit" the docs describe a "target" as an "urbit and app" with the code

[ost %poke /sending [to-urbit-address %pong] %atom 'howdy']

However in the examples/pong.hoon code the line is

[ost %poke /sending [to dap] %atom 'howdy']

where %pong is replaced with dap.

Pandoc everything

We really should normalize our markdown formats. In the past we have used pandoc, which is great.

I guess this issue has two parts:

• Pandoc everything in the repo
• Create a contributing.md that explains the standard.

HTTP to HTTPS?

From /docs/using/admin

Since our HTTPS isn't audited / battle tested we just call it "secure" HTTPS. You can find that on 8443. Or 8444 (and so on) if you're already running something on 8443.

But our 'secure" HTTPS is probably still better than normal HTTP, yes? Because almost all our docs right now use http in Urbit links. and our instructions regarding localhost all say to use port 8080 instead of 8443.

Friends of FizzBuzz exercise two is unfair :)

This is the one where you have to figure out how to pass two parameters to a gate. I believe the answer is just

|=  {start/atom end/atom}

(Maybe there is a better way?) However it is not clearly documented in the hoon docs as far as I can see. I suppose it can be figured out by implication. Perhaps the syntax section should talk about the syntax for creating some basic things like numbers, strings, cells/tuples, and whatever you call the {} construct. I don't think the {} syntax is ever discussed.

[edit: ignore this part about comments as it is already there] This should probably be a separate issue: but it would be really nice if there was a comment section at the bottom of each page for a lower friction way of providing comments.

Ford horn rune documentation

From @chc4 on June 17, 2015 18:47

Although the %ford commentary file mentions all the different horns and what they do, it's not the most discoverable place for it. The guide/a-ford.md tutorial, for example, says to check the rune index for the horn runes, but they aren't actually there yet.

Either a rune subdirectory for fas or one for %vane-specific runes should probably be created (along with updating the ford tutorial to point to it).

Copied from original issue: urbit/urbit#299

:cast and :new expand to :bunt, which is not defined

^- (:cast) expands to :like(:bunt(p) q) (http://urbit.org/docs/hoon/twig/ket-cast/hep-cast/)

=| (:new) expands to :pin(:bunt(p) q) (http://urbit.org/docs/hoon/twig/tis-flow/bar-new/)

:bunt is not specifically defined in the docs. The closes is in http://urbit.org/docs/hoon/twig/buc-mold/:

Many macros bunt a mold, producing :burn(:per(mold $))

There's a $bunt mold (?), but no keyword sigil for it.

examples mix keyword stems and runic stems

Example:

A trivial gate:

~zod:dojo> =foo |=(a/@ +(a))
~zod:dojo> (foo 20)
21

A slightly less trivial gate:

~zod:dojo> =foo  :gate  {a/@ b/@}
                 (add a b)
~zod:dojo> (foo 20 400)
420

If I got some guidance on this I would regularise the examples found in docs/hoon/twig.

(It's cool to have quasi-sensible names for the twigs, like |_ 'door', but they should IMHO never be used in example code in :door form.)

Change ^x to ctrl-x, or use both?

As per: https://www.reddit.com/r/urbit/comments/4ny941/the_command_line_doesnt_work/ it seems like it might be confusing to say ^x when we mean ctrl-x. I think @asgardiator and I talked about this the other day.

Any reason not to just switch? I know ^X is a convention, but I'd rather not confuse anyone.

Peer-Peer Crypto Documentation

Bearing in mind that the crypto is likely the most sensitive part of the project and extensive documentation may speed exposing vulnerable points, understanding the full extent of peer-enforced powers versus protocol-enforced powers granted by the certificates/sibyls. Also, to what degree are private keys and re-signing are significant? A person concerned about security may want to initiate a physical barrier between key calculations and the network connected client (such as usb to carry messages or manual data-entry).

A person skeptical of the legitimate monopoly of force, might be curious of the "pre-mining" process, practicality of "side-chaining" the network, and/or cross-compatibility between networks (or conflicting ~zod). Suggesting that doubt is an option may cut into the legitimacy of Tlon, but, if the electorial system is effective and legitimacy popular, it should be a negligible assurance.

More specific questions might be: are stars able to invalidate planets? If so, is it still deterministic that they were infact once valid? What algorithms can be used to efficiently create these keys and how much arbitrary work goes into the creation of a new sibyl, since P vs NP is still something to factor into. It's reasonable the believe that the underlining key of ~zod is vulnerable since it can be reasonable that facebookcorewwwi.onion proved the feasibility of breaking sha-256 and that the most recent supposed forgery of a single Satoshi private key. This makes wondering what algorithm is being used definitely a relevant longevity concern.

UDP choice seems to be controversial, though for the uninitiated in the halls of cisco, it may require some more documentation on how the actual association engine of messages and listeners works and why it works the way it does to defend or criticize.

And, as mentioned elsewhere, there is no redundancy of work between Urbit and Juan Benet's IPFS, however there could be said to be a redundacy of work between Urbit's addressing system and Juan Benet's IPNS which provides similar level of functionality at the moment, however has vaporware roadmap promising more deeply elaborated ethical considerations about the matter. The ultimately interesting question is, could urbit implements an alternative IPNS scheme or perhaps even some twisted hybrid scheme? The ethical considerations of a hybrid potential, likely out-weigh either's merits through mere individual choice, unless we don't believe in the power of that any more.

With the entire Vulture repayment model hinging on the value of such a system, centralized control and disenfranchising such compatibility would be incentivized even when destructive, so ethically how does one justify not documenting this most contraversial aspect. And, to everyone not associated and just reading, how do you justify not asking? Legitimately this is likely a lapse in consideration, but a cynical mind could paint it as malicious and reasonably so. If we can't hold ourselves accountable, the question, these days, is: who will?

Disclaimer: primary computer has only <600 mbs of ram; unable to actually use urbit.

+- wet arm syntax undocumented

~hobten-hinrym/ https://urbit.org/docs/hoon/advanced
~hobten-hinrym+ the wet arms section doesn't mention +-
~hobten-hinrym+ neither does
~hobten-hinrym/ https://urbit.org/docs/hoon/twig/bar-core/cen-core

Proper word references

I'm wondering if it wouldn't help the reader to give the familiar "incorrect" word within parentheses and the correct Urbit term in code block, such as:

A mold is a constructor gate (function) [...]

As opposed to:

A mold is a constructor function (gate) [...]

I feel it may speed up absorption a little bit. If you agree I'd be willing to go through with it and send a pull request.

<list> should be used with [src] instead of [dataPath]

Blocked on urbit/tree#9, which implements such.

Hoon concepts page has broken links

mint, twig, span, and limb have broken links on the Hoon concepts page (http://urbit.org/docs/hoon/concepts/). It's not clear where those links should go.

! runes are incomplete

From @ohAitch on October 26, 2015 21:34

The page for !_ should mention how !: and !. work, not claim it's tall/wide form is ?!.
Other runes should be checked for similar issues.

Copied from original issue: urbit/urbit#459

Multiple links broken on root docs page when browsing back from other pages

To reproduce:

1. Load urbit.org/docs/. notice the link is in the top paragraphs are all correct.

2. Browse to a sub-page (for example visit http://urbit.org/docs/using/install/)

3. Click the urbit-tilde in the top left corner to return to the main page (don't use the back button)

4. Notice all the links in the top paragraphs are now missing /docs and thus route to pages
   that don't exist.

Usage instructions out-of-date

Various usage instructions and examples under using/filesystem are now apparently out of date. For instance: |merge %desk [~planet-name %desk] now gives nest-fail, and only functions with |merge %desk /~planet-name/desk=; |sync %desk ~planet-name fails, requiring instead |sync %desk ~planet-name %desk (docs state the remote desk is optional if the same as the local desk); |cp /path1 /path2 %init fails, requiring no merge strategy argument.

Objections typo

~nodpet-rinned/ http://urbit.org/posts/objections#log
~nodpet-rinned+ unfinished sentence: "the current implementation of urbit
~nodpet-rinned+ maintains..."

Had to use `{{arg/TYPE $~} $~}}` instead of `{{arg/TYPE ~} ~}}` in arvo/subject

Referring specifically to this line, I had to use {{arg/TYPE $~} $~}}, as {{arg/TYPE ~} ~}} would throw an error. Not sure the reason why though!

Arvo Internals Quickstart chapter is incomplete

http://urbit.org/docs/arvo/internals/

Urbyte 0 fake ~zod creation issue

The procedure for creating a fake ~zod in "Urbyte 0: setup and nouns" didn't work for me, urbit just sat waiting for the hood indefinitely.
There was an error about missing ./arvo directory though.
On a whim I cloned urbit/arvo repo and symlinked it into the current directory; this time the fake ~zod was up and running in a minute.

Security Driver quickstart chapters need serious attention

In the security drivers chapter, everything works up until the example code following this text: ‘Creating an app is easy and well-documented.‘

Then the rest of it is broken.

"Empty path" weird text color

This should be CSS'd white or something, right?

:talk # repl functionality

Doesn't appear to be documented, in what is now using/messaging.md in the cleanorg branch.

undocumented twigs

I've been reading hoon.hoon, and I've come across the following undocumented twigs:

:: | core missing:
{$gasp p/twig q/twig}                               ::  |:
{$cork p/twig q/(map term foot)}                    ::  |^
{$port p/twig q/twig}                               ::  |~
{$tray p/twig}                                      ::  |? 

:: % call missing:
{$bake p/wing q/twig r/(list (pair wing twig))}     ::  %*

:: ^ cast missing:
{$ward p/twig q/twig}                               ::  ^. 
{$zinc p/twig}                                      ::  ^&

:: = flow missing:
{$tow p/(list twig)}                                ::  =~  twig stack

:: ! wild missing:
{$twig p/twig q/twig}                               ::  !,
{$spit p/twig q/twig}                               ::  !;

mark conversions do not work in marks quickstart chapter

~fintud-macrep:dojo> &examples-cord &atom &examples-cord &atom 9 should give:

'57'

but instead:

ford: no link: [%examples-cord %atom]
ford: casting %examples-cord to %atom
ford: cast %atom

Similarly: ~fintud-macrep:dojo> &examples-cord 17 should give:

'17'

but instead:

ford: no noun: [%examples-cord p=~zod q=%home r=[%ud p=10]]
ford: check [%examples-cord [p=~zod q=%home r=[%ud p=10]] ~mirtyn-dabset]
ford: casting %noun to %examples-cord
ford: cast %examples-cord

API Connector quickstart chapter has broken example code

According to @juped , the API connectors example code is broken. Either @philipcmonk or @ohAitch should probably take a look at it to determine whether or not we should fix it or just omit this chapter for now.

Fix 164 syntax in about/runtime.md

From about/runtime.md:

|  ++  arvo
|    |%
|    ++  come  |=  [yen=@ ova=(list ovum) nyf=pone]  ::  11
|              ^-  [(list ovum) _+>]
|              !!
|    ++  keep  |=  [now=@da hap=path]                ::  4
|              ^-  (unit ,@da) 
|              !!
|    ++  load  |=  [yen=@ ova=(list ovum) nyf=pane]  ::  86
|              ^-  [(list ovum) _+>]
|              !!
|    ++  peek  |=  [now=@da path]                    ::  87
|              ^-  (unit)
|              !!

Should these sample molds be molds?

up.hoon app from HTTP request chapter does not work

I inserted the proper mark (++ cord) from the marks section and then successfully poked the app as per the instructions: :examples-up &cord 'http://www.google.com'

The output should be:

[%all-is-well 200]
[%all-is-well 200]

with printfs occurring every 10 seconds. But instead, nothing happens.

According to the tutorial, there should be printfs every 10 seconds or so verifying that the app is up.

undocumented tree addressing syntaxes

Lark syntax and whatever you call &n and |n are currently undocumented.

several twigs have truncated explanations

• http://urbit.org/docs/hoon/twig/bar-core/cen-core/

In this trivial example, g id ther ...

• http://urbit.org/docs/hoon/twig/cen-call/sig-open/

In :call the core is a gate and we ...

• http://urbit.org/docs/hoon/twig/sig-hint/cen-fast/

... must already be registered.

No anchor links or index for standard library

Finding the documentation for a given arm requires one to grep the source or else guess which section it's in. Also can't link to anything from other parts of the docs.

Markdown YAML order sorting incorrectly.

The reason the docs/arvo pages seem out of order (Security Drivers and API's coming before basic Hoon material) is because the YAML sorting is not functioning properly. Tree is sorting 11 and 12 before 2 and 3. I tried fixing this by changing pages 0-9 to 00-09. This didn't work, but changing the page range from 1-12 to 11-22 fixed this.

Going to PR this so it works, but not sure if there's a change that can be made to make 1-12 work (just to make to make it normal, as I imagine this is going to be pretty annoying for people in the future wanting to, say, host their own blogs or static pages through Tree).

docs html underline rendered too low in Firefox

Broken link on shell

From the url "http://urbit.org/docs/using/shell/" clicking on the link from "For a complete explanation on urbith paths, see the filesystem section)" to the filesystem section cannot be resolved because it goes to "http://urbit.org/docs/using/shell/filesystem.md". The next page in the doc is the filesytem doc. At the bottom of the page if you click "next: filesystem" it correctly takes you to "http://urbit.org/docs/using/filesystem/".

A catalog of syntax collisions with other languages

From @ohAitch on December 1, 2015 16:14

C, bash, js, perl; I'm sure there's a list of the top 50, or at least 10, somewhere, and it would be useful to be able to point people at a reference for what expressions mean completely different things in hoon vs. something else you might be used to. A sort of inverse Rosetta code, maybe; the list could also contains expressions that do mean the same thing in hoon as another language.

Simple cases that come to mind:

• a=1 is usually assignment, either mutable or as a local let
• a:1 is {"a":1} dictionary literal in coffeescript, probably others
• %1 %2 %3 refer to arguments by position(bash, clojure)
• [a - b], [a + b], [a / b], [a ** b]; [a | b], [a & b], [a ~ b], [a ~~ b] (first three used to effect in a maths library I remember writing. @cgyarvin can write a language hostlie to DSLs, but this just makes their mechanism of action harder to determine.)
• a.b.c ordering
• a(b c) as distinct from (a b c)
• the expression

[ 1 ; 2
]

while nonidiomatic hoon, could give someone a bit of a start.

• likewise [ :* a == b ]
• ++ as "define" and not increment; --

Copied from original issue: urbit/urbit#609

Document backspace in dojo

As discussed in urbit/urbit#336

truncated paragraphs in whitepaper

End of section 4.2, page 10: "for the relationship between the ... identity of the node"