Build your own

Unseenet is meant to be like the old internet standards: written down, so that anyone can build a node, a client or a gateway that works with everybody else's, in any language, without asking the project. This last chapter is a map for doing that: which UN-RFCs to read, in which order, for what you want to build.

How the specification works

The protocol is specified in the UN-RFC series, numbered documents in the tradition of the RFCs that once defined Usenet. They are the authority: an implementation that follows them can join the network, and where the project's own code and a UN-RFC disagree, the code has the bug.

Every UN-RFC is still a Draft while Unseenet is pre-alpha, so details can change, and there is no promise of compatibility before 1.0. A change is proposed the same way for everyone: an issue that describes the problem, then a pull request with a new draft, as UN-RFC 0000 describes. The specification is under CC BY 4.0 and the code under the Apache License 2.0.

Everyone starts here

1. 0000 Process - how the series works, and the full index.
2. 0001 Architecture - the parts and how they fit.
3. 0002 Article format - what an article is, how its Message-ID is computed, and the validation every node and client runs.
4. 0003 Identities and crypto - keys, fingerprints, signatures and encryption, by name.
5. 0004 Groups - Group IDs, manifests, the types, bans and withdrawing posts.

With those five you understand what everything else builds on.

A client that reads

The smallest useful client connects to a node over Tor, reads groups and checks everything itself. It needs:

• 0005 ONNTP - NNTP over an onion service: the commands a client uses.
• 0010 Known nodes - finding a node to start with.
• 0008 Chat and 0028 Chats and posts - views, data groups, and the two kinds of message.
• 0018 Hierarchies and 0019 Names - showing groups and people safely, with petnames.
• 0031 Markdown and emoji - rendering posts as a safe tree, never as HTML.

The one rule not to skip: check every signature, manifest and withdrawal yourself, as section 4 of 0004 says. A client that trusts its node can be fooled by it.

A client that writes

To post, a client also needs:

• 0006 Postage and 0025 Key ripening - the proof-of-work on every article, and the ripening that sets its price.
• 0007 Data at rest - the vault, and writing nothing to the host.
• 0009 Inboxes - private posts and contacting operators.
• 0029 Key-bound groups - the groups that belong to a key, and renewing them.
• Then, as you add features: 0022 Profiles, 0027 Attachments, 0030 Comments in channels, 0032 Mention notices, 0033 Pins, 0034 Feeds, 0035 Pages and sites, 0042 Editing posts, 0044 Your state in the network.

Or build on the core

You do not have to implement all of that. A program in Python can use the project's client core, Session, which already does keys, the vault, Tor, postage, ripening and every check; a front end in any other language can talk to the same core through the local client API on 127.0.0.1. Either way your client behaves like the others from the first day. See Write a client.

A node

A node needs the client's reading list from 0002 to 0006, the ripening check of 0025, and:

• 0016 Peer keys - how nodes prove who they are.
• 0017 Catch-up by pull - group state, and getting what was missed.
• 0012 Retention - how long posts travel and are kept.
• 0013 Removing groups - rmgroup, local drops and tombstones.
• 0011 Node information and 0021 Listed nodes must be connected - what a node tells others, and what it takes to be listed.
• 0040 and 0041 - key-bound groups and manifests at the scale of millions.
• 0027 and 0035, if it carries files and sites.

A gateway or an entrance

• A gateway follows 0023 Gateways, one network profile - 0024 Usenet, 0026 Nostr or 0037 Matrix, or a new one you write - and 0038 for working alongside other gateways. The project's gateway has a shared core and one adapter per network, and a new adapter is the easiest way in.
• A web entrance follows 0043 Web entrances.

Testing against the network

• The project's test nodes and the group unseenet.test are there to be posted in by new software. Test nodes may be reset.
• The project's own code is the reference: when your implementation and it disagree, check the UN-RFC - and if the UN-RFC is unclear, that is worth an issue.
• A classic newsreader such as tin can read a node's open groups over Tor, which is a quick way to see what a node serves.

When something you build works, say so in the group unseenet - every independent implementation makes the network stronger, and shows that the specification says what it means.