tiny.reticulum

Overview · API · Code relationships · Verification · Audit

Overview

Everything one program needs to reach a named party across a mesh network: the address that names the party, the key material behind that address, the bytes that go on the wire, the ciphers that seal a payload, and the state machine that drives one node of the mesh. That network is Reticulum, in which nodes find each other by broadcasting signed announcements and reach each other over any medium that moves bytes.

A party has to stay reachable under one name while the wire under it changes, so the name a sender uses cannot be an interface or a route. Whoever holds that name has to be the only one who can read what is sent to it and the only one who can sign for it, so the address itself carries the guarantee. The code has to run where memory is fixed before the program starts, so every store takes its size from the caller and every call works in a buffer the caller owns. A port of a protocol that speaks to programs written by other people has to be checkable against the original, byte for byte.

A name built from an interface, an address, or a route stops naming the party as soon as any of them changes, so the sender has no way to find it again. One long-lived key pair leaves every message ever sent to it readable once those bytes leak. A mesh floods, so the same packet reaches a node by more than one route and would be acted on once for each.

The package follows Reticulum 1.5.0, the reference implementation, pinned to one upstream commit by the package README and the generated conformance corpus. The code takes the wire layouts, the key derivations, the addressing rule, and the state machines from the reference, and each declaration names the reference file and line range it follows. The package generates a corpus of reference bytes and clocks from that release and replays it in differential tests, so each of those claims is checkable from this tree.

The 16-byte address a party is reached by (a destination) is a truncated hash over a dotted name and, for a party with a single owner, that owner's public key, so it names the party under whatever interface or route it sits behind. The key material behind one address (an identity) is two key pairs: an X25519 pair that receives encrypted payloads and an Ed25519 pair that signs. A party also publishes a short-lived X25519 key (a rotating key) in its signed announcements and keeps the older ones, so a sender that heard a recent announcement encrypts to a key the party will soon stop using. Reading and writing a packet work in slices the caller supplies, and every store is carved out of caller storage whose length has to equal a derived byte count exactly. The node performs no input or output and reads no clock, so each step takes the current second from its caller and returns records standing for actions the caller performs, such as sending a frame or arming a timer (each an effect). The package names its parts: the wire layouts, what a node does with a packet once it is read, destination addressing, identity key material, the symmetric ciphers, carrier frames, interface access codes, the node state machine, the shared hash widths, and the generated corpus.

• carrier: one network interface a node sends and receives frames over, named by a byte index.
• access code: the shared key and code length that authenticate every frame on one carrier, appended on the way out and stripped and checked on the way in.

Definitions

Namespaces

Public namespaces.

• wire: The byte layouts of one datagram on a mesh network, with a reader and a writer for each: the header and its flag bits, the byte that says what the payload is for, the digest that names the packet, the two shapes of the signed reply that says a packet arrived, and the payloads that open an encrypted session.
• conformance: Generated by lib/reticulum/build/generate with rns==1.5.0.
• crypto: The constructions a Reticulum payload is sealed with once both ends already share a key: AES in cipher block chaining mode, the padding that fills a plaintext out to whole blocks, HMAC-SHA256, the key derivation that turns one secret into as many bytes as a caller needs, and the sealed format that composes them.
• destination: How a party is named on a Reticulum mesh and everything that name carries: building the name, cutting it down to the address a header holds, the four kinds of party a name can stand for, the announcement that publishes a name, the ciphers each kind uses, and the list of names one node answers for.
• hash
• identity: The key material behind one Reticulum address and everything that material does: name itself, sign, check a signature, seal a payload for a peer, open what arrives, and roll a short-lived key forward.
• interface: The code every frame on one network interface carries to show it belongs there, and the two calls that add it on the way out and check it on the way in.
• node: A state machine for one node of a mesh network holds everything the node remembers and turns one input at a time into a list of things for the program around it to do.
• packet: Four jobs govern what a node does with a packet once its bytes have been read: decide whether to act on it, remember it so it is acted on once, answer it with a signed reply that says it arrived, and keep track of the packets it sent that are still waiting to be answered.
• carrier: The unit of bytes a node hands to one network interface, and an interface that keeps those bytes in memory.

Code relationships

Direct static dependencies extracted from parsed source by semantic graph analysis.

Uses: tiny.choir, tiny.hypothesis, tiny.sdfii, tiny.smg, tiny.sys, tiny.ui, tiny.wayland
Used by: tiny.pluck, tiny.quic

Verification

No verification records are cataloged for this module in this build.

Audit