mudRPC, gRPC for unstable networks

mudRPC — Specification

RPC over unstable networks, from any language.

Each layer described once, as it is. Rules are in CLAUDE.md; this file is what we build and why. Tests listed here are the floor for the work that builds the layer; each feature designs its own on top.

What we build

  1. Core (Rust, #![no_std], no allocation, no crates). A pure state machine: bytes and ticks in, bytes and events out. It owns no transport, no clock, no socket. Four modules, auditable in a day; the signed and AES sealers sit beside it in auth/ and gcm/, behind its one seam.
  2. Adapters. The transport contract, and two adapters we own: sim and lan. Real transports are written by the people who know them, against the contract, the mock of their transport in sim, and a conformance suite.
  3. Developer product. One C ABI with every language wrapper sitting on it as a single vendored file; mud gen, which parses .proto and emits thin stubs; a skill per wrapper and adapter; the simulator.

The layer picture and how the host pumps bytes between them are in README.md.

Delivery semantics

The three questions a drone team asks first. The answers are the whole contract.

What happens to a message that cannot be delivered now? It waits, up to its ttl. Where it waits is the transport’s business: at the sender when there is no path (Reticulum), in custody at the last peer that had it (DTN), or in core’s outbox until the host drains it. When a path appears, it goes. Core retries nothing, because nothing was lost; it was waiting.

How old can a delivered message be? At most ttl_secs. The sender says how long the message is worth acting on; the mesh drops it after that; the receiver never sees anything older. The receiver cannot measure age itself, since no clock is on the wire, so the promise rests on the transport honouring lifetime, which is a conformance test. Freshness inside the window is the product’s: a method that needs a timestamp puts one in its payload.

Queue or real time? One knob: ttl. Real time is a short ttl: a steering command with ttl 2 expires fast and the product falls back. A queue is a long ttl: a mission upload with ttl 3600 arrives whenever the link heals. Telemetry is a short ttl on a topic: fifty stale positions die in the mesh instead of arriving after heal. There is no second mechanism.

What the caller sees. call returns at once with an id. Later comes a Reply, or Expired at ttl. Never a hang, never a network error: off-mesh is the normal state. A reply is given the call’s ttl, measured from the reply, so a reply to a caller that went off-mesh waits in the mesh like any other message; a reply that arrives after the caller gave up is NoPending.

What the mesh may do. Deliver late, deliver twice, deliver out of order, deliver to several listeners, or never deliver. Core hides exactly two of these: twice (the per-sender window and the seen table) and never (Expired). Order and fan-out are facts of life the stubs make visible with seq and end.

Open: supersession, where a newer event from the same sender makes older ones worthless. ttl covers most of it; a supersedes flag is asked only if a real product shows the one knob is not enough.

Tests:

The messaging protocol

mudRPC is gRPC’s service model carried as self-contained message packets. Every gRPC concept lands on a message or is cut on purpose.

gRPC mudRPC
service a topic, named by the fully qualified service name
method method in a call message
unary call one call, one reply
server streaming one call; replies share its id, each with seq, last with end
client streaming cut: no API produced a client-stream item; a call with seq other than 0 is Dropped::Seq
bidirectional both; each direction independent
deadline ttl_secs, in the message and handed to the transport
status every reply carries gRPC’s status number and optional detail; OK costs zero bytes
metadata cut
cancellation ttl expiry; no cancel message
wire format protobuf, unchanged; interoperates with protoc output

Streams are packets. A stream is a sequence of self-contained messages sharing an id, each with seq, arriving out of order, with gaps, hours apart. The receiver sees the gaps. No byte pipe, no retransmit, no ordering. A .proto with stream maps onto it unchanged.

Events. A method with the topic option is a publish: one message, no reply, to a topic. One topic carries one message type.

Video. Live video needs a byte pipe and bandwidth the mesh does not have, and nobody re-invents their camera adapter. The camera’s own link (RTSP, WebRTC, MAVLink camera protocol) keeps carrying live video. mudRPC carries camera control as calls, “stream available at X” as events, and the degraded fallback as a stream of self-contained keyframes or stills when the live link drops. Each item is a complete picture, so a gap loses a frame, not the feed. A stream is leased by the call that opened it and ends with that call’s ttl: when nobody renews, the server stops, and no bytes flow to a receiver that is gone.

gRPC’s production failures, and where they went. Each is a live-connection assumption; mudRPC has none.

gRPC in production mudRPC
HTTP/2 pins a client to one backend; hot spots; needs an L7 proxy No connections. A topic is the address, any listener may answer, first reply wins.
Zombie connections: a silent black hole stalls clients for minutes; needs keepalive tuning No socket state to trust. Off-mesh is normal; the only failure signal is Expired at the caller’s ttl.
Shared .proto couples teams; proto3 dropped required Unknown fields skipped, so releases evolve independently. Field presence is the product’s check, as in gRPC.
Browsers cannot speak HTTP/2 frames; gRPC-web needs a proxy The wasm build exports the same ABI. No HTTP anywhere.
Stream limits per connection; hidden client queues; channel pools Limits are explicit: PENDING, SEEN, OUT are capacities and Full is a return code.

The firewall property. The only path from the mesh into product code is: unseal, decode the envelope, decode the payload against the .proto. Anything that fails any step is dropped before product code runs. No heap, fixed buffers, no std: the attack surface is one fuzzed decoder.

Human problems

We solve human problems. If a feature doesn’t move one of these lines, it’s cut.

Who Problem today What changes
Drone crews and field teams Links drop, apps freeze, state is lost; decisions go over chat apps Apps keep working off-mesh and catch up when the link heals
Operations Every vendor is a separate integration; the picture is only as good as the worst link One contract for all feeds; degraded links degrade gracefully, not to zero
Developers Integrating with Reticulum or DTN directly is intensive and buggy; no stubs, no docs, no test harness .proto in, native stubs out; unit-test against a simulated mesh with no radio
Hardware makers 500 new models a year, each wired in by hand Ship one adapter, work with every backend
Reticulum / DTN maintainers Every integrator asks the same questions; bugs blamed on the stack One adapter per stack, maintained once; their internals stay theirs

What the field says (2026, sources in Prior art). ROS 2 over DDS was built for wired, static networks: on Wi-Fi its multicast discovery storms, its reliability timers retransmit into the contention, and large payloads fragment and stall; the community chose Zenoh to replace it, a few bytes of per-message overhead against DDS’s 56. MAVLink’s plain messages carry no acknowledgement, its command protocol retries blindly, its mission protocol re-requests what was lost, and the friction is over who owns the timeout. MIT’s LCM chose brokerless UDP multicast with a schema compiled into every language and no RPC, and is maintained for that simplicity. Payload integration is where the money leaks: a closed payload SDK ties a camera to one airframe, and the 2026 answer is open contracts and the Pixhawk Payload Bus; integration with a large operator’s system is a standards exercise by insiders, the bridge-adapter model. Each is an argument the design makes: no discovery protocol, no live session, no retry storm, one knob for lifetime, a schema in every language, an open contract any vendor can pass.

The layers

0 · The mesh as it is

Fact What it removes
Delivery may take hours or never happen Anything that blocks. Anything with a socket lifetime.
Reticulum delivers with no source address “Reply to sender.” The caller names its inbox.
Clocks are not synchronised Absolute time on the wire. now is the caller’s uptime.
A topic may have many listeners “Exactly one reply.”
The smallest peer has no heap Dynamic tables. Strings. Everything is fixed-capacity or caller-owned.
The transport is someone else’s code Any requirement that the transport call into us. The host pumps.

1 · The wire

nonce     = sender(4) ‖ epoch(4) ‖ counter(4)                                  both ends compute it the same way
header    = nonce XOR mask    Key: ChaCha20_block(key, counter 2³²−1, sample)[0..12], sample = the 12 bytes after the header
                              Gcm: AES-ECB(header key, sample)[0..12], sample = the 16 bytes after the header
wire      = version(1) ‖ header(12) ‖ AEAD(key, nonce, ad = version ‖ topic, Envelope ‖ trailer) ‖ tag(16)
signature = Ed25519(seed_of_sender, nonce ‖ version ‖ len(topic) ‖ topic ‖ envelope)      the trailer under Signed, 64 bytes
id        = the nonce of the call (absent on a unary call: it is the header)
version   = 1 Key (ChaCha20-Poly1305) · 2 Signed<Key> · 3 Gcm (AES-256-GCM) · 4 Signed<Gcm>
message Envelope {                 // a comment in envelope.rs, not a shipped .proto
  bytes  id       = 1;             // the call's 12-byte nonce, absent on a unary call
  uint32 ttl_secs = 2;             // lifetime handed to the transport; dedupe window
  uint32 seq      = 3;             // streams; absent means 0
  bool   end      = 4;             // last item of a stream
  oneof body { Call call = 5; Reply reply = 6; Event event = 7; }
}
message Call  { string method = 1; string reply_to = 2; bytes payload = 3; }
message Reply { uint32 status = 1; string detail   = 2; bytes payload = 3; }
message Event { bytes payload = 1; }

The envelope and the sealed wire, in core/envelope.rs, core/codec.rs and core/rpc.rs:

The cipher, in core/seal.rs and gcm/aes.rs, gcm/ghash.rs, gcm/lib.rs:

The nonce. A sender has a name and a number. The name is its inbox topic, and a topic is UTF-8 of 1 to MAX_TOPIC (64) bytes, never empty, since a peer named nothing would listen on nothing: new, listen, call, publish and reply refuse an empty one as Empty (MUD_EINVAL at the ABI), a wire on one is Dropped::Topic before the tag, as one over 64 is, and a call whose reply_to is either is Dropped::Topic after it, in judge before verify, since nobody could answer it. The number makes every nonce unique without randomness, gives a receiver a per-sender replay floor and a cost bound, and is what a signature attaches to. It lives in core/rpc.rs.

The header mask, in core/seal.rs and gcm/lib.rs:

The per-sender window and floor, rate, the counters, in core/rpc.rs:

The sealer seam, in core/seal.rs and core/rpc.rs:

flowchart TD
  W(["a wire from the transport"]) --> V{"version byte the sealer's, topic within MAX_TOPIC?"}
  V -- no --> V0["Version(n) · Topic"]
  V -- yes --> T{"open: the tag, under current, previous, next"}
  T -- "no slot opens it" --> T0["Open(Tag): junk, a wrong key, a moved topic"]
  T -- opened --> D{"judge, on copies: decode"}
  D -- malformed --> D0["Decode"]
  D --> U{"dedupe: a reply against its call's bitmap, a call or event against the seen table"}
  U -- "seen, a stray, or a call nobody could answer" --> U0["Topic · NoPending · Seq · Id · Duplicate"]
  U --> F{"floor: below the highest the sender had sent MAX_TTL ago?"}
  F -- below --> F0["Rollback · Replay"]
  F --> N{"window: the sender's last 64 counters, in its newest epoch and the one before"}
  N -- "two epochs back, the older past its ttl, 64 behind, or seen" --> N0["Rollback · Replay · Duplicate"]
  N --> R{"sender already reported flooded this second?"}
  R -- yes --> R0["Rate"]
  R -- "no: the one verification is spent here" --> S{"verify: roster line, budget, signature (Key passes every wire)"}
  S -- refused --> S0["Open(Roster) · Open(Budget) · Open(Sig)"]
  S --> M{"mark: the global cap on calls and events, the per-sender cap, the strangers' share and a spent second's share, then the one write"}
  M -- "over a cap" --> M0["Rate · Flood, once a second"]
  M -- "window bit, seen entry, pending bit, rate counts" --> I(["Incoming::Call, Reply or Event to product code"])
sequenceDiagram
  participant A as unit A
  participant B as unit B
  participant C as unit C
  Note over A,C: three slots each: K1 current, previous and next empty
  Note over A,C: stage(K2) on each: K2 fills next and is live for receiving from this moment
  Note over A: 06:00 rotate(): seals under K2, K1 is previous
  A->>B: a wire under K2 opens from B's next
  B->>A: a wire under K1 opens from A's previous
  Note over B: 09:00 rotate()
  B->>C: a wire under K2 opens from C's next
  C->>A: a wire under K1 opens from A's previous
  Note over C: 14:00 rotate(): all three seal under K2
  Note over A,C: 06:00 to 14:00 the current keys differ, open tries current, previous, next, and every wire lands
  Note over A,C: retire() on each once every unit has rotated and K1's wires are past their ttl
  C-->>A: a wire under K1 held past that dies at the tag: Open(Tag), nothing marked

Authentication. Under one fleet key every holder is every peer. Signed gives each sender number a signature only its device can make, so a receiver knows who spoke, a compromised device can forge only as itself, and every Call, Reply, Event and Flood names a real unit. Rollback names the number written, not who wrote it: under Signed it is a clone or a key holder writing old epochs under that number, both incidents, and the one counter a key holder can raise by name; the verdict is reached before the signature, at one tag check, and stays there because verifying first would let the same party spend the budget to raise it, and the budget is what keeps honest wires landing. Signed is a Sealer that wraps another, outside core so core stays four modules: auth/signed.rs over auth/ed25519.rs (RFC 8032) and auth/sha512.rs (FIPS 180-4).

The threats as stated, and what is made exhausting, in core/rpc.rs and auth/signed.rs:

Tests that define this layer:

2 · The peer

The API is core/rpc.rs; its doc comments are the reference and the tests in core/tests/peer.rs are the behaviour. In one breath: new(name, sealer, sender, epoch), resume(epoch), renew(epoch), call, publish, listen, reply(now, &Call, seq, status, detail, bytes, end), deliver(now, topic, wire, buf) -> Incoming, tick(now), outgoing(now) (a peek that lends the queued item) and sent(), pressure(), counts(), pending(), queued(). Incoming is Call, Reply, Event, Expired, Flood, Rollback or Dropped(why). The host’s side, the twelve rules every binding shares, is the list at the top of bindings/c/mudrpc.h, and every skill points there.

Tests:

3 · Transport contract

Lives in adapters/, not core. What sim, lan and every third-party adapter implement; the Rust pump(peer, transport) helper is twenty lines, and a transport error ends its drain, not its round: the item stays queued, the inbound and the clock still reach the peer, and the error is returned.

pub enum Rx<'a> { Message { topic: &'a str, wire: &'a [u8] }, OnMesh, OffMesh }

pub trait Transport {
    type Error;
    fn send(&mut self, topic: &str, wire: &[u8], ttl_secs: u32) -> Result<(), Self::Error>; // returns at once
    fn listen(&mut self, topic: &str) -> Result<(), Self::Error>;                            // announce + subscribe
    fn poll(&mut self) -> Option<Rx<'_>>;                                                    // never blocks
    fn silent(&mut self, on: bool);                                                          // behave as if no path exists; keep receiving
}

The topic is the address: Reticulum, a destination hash of the name; DTN, dtn://<name>; lan, a topic byte-string in each datagram, filtered at the receiver, sent to a configured table of radios. Store-and-forward, routing and link encryption are the transport’s. The transport never sees plaintext. Size: a transport carries a wire of at most MUD_MSG, 512 bytes with its version byte, beside a topic of at most 64 and its own frame (lan’s 2 bytes, MAX_DATAGRAM 578), a unary call being 49 bytes, 113 signed, and a payload’s ceiling about 460, 396 signed (layer 1); core never splits a wire, so a transport whose packet is smaller carries it whole or in segments of its own, which its adapter’s author states against that transport’s documentation, Reticulum’s and DTN’s packet sizes included, since none is measured here. The conformance set below is CONFORMANCE.md, which an adapter’s author copies with its tests.

Tests:

4 · Protobuf and stubs

Protobuf’s rules are implemented once per language that has an emitter, and no developer installs anything to use them.

syntax = "proto3";
package mud;
import "google/protobuf/descriptor.proto";
extend google.protobuf.MethodOptions {
  uint32 ttl_secs = 51001;
  string topic    = 51003;   // publish, no reply
}

Tests:

5 · Bindings and the ABI

One real binding: the C ABI. Every other language is one hand-written, idiomatic file over it, vendored into the product, with no dependency beyond the language runtime. The no-std, no-crate rule stops at the ABI.

Binding Over Where State
Rust core directly embedded and Linux edge built
C / C++ the ABI; mud.hpp over it for C++ flight controllers, radios, legacy sensors, gRPC C++ services built
Python ctypes Reticulum’s language; prototyping built
C# / .NET P/Invoke Windows ground control built
Java / Kotlin Panama FFM; JNI on Android, bindings/android Android ground stations and apps built
JavaScript / TypeScript wasm export of the ABI dashboards, Node, Electron built
Go cgo relays and infrastructure, grpc-go services built
PHP FFI web back ends, gRPC PHP clients built
Swift C module map iOS field apps, macOS and Linux built on macOS and Linux; the iOS library built in the gate, its simulator run waiting on Xcode
Dart dart:ffi Flutter field apps to do
WASI the ABI on wasm32-wasip1 sandboxes to do

Any language with a C FFI works from the header in the C skill. Wasm is a distribution target, not the edge runtime.

Distribution is the repo. cargo build --release produces the library and mud. mud provision <dir> [n] makes the out-of-band half of a fleet from the operating system’s random source: fleet.key once, a device-<sender> file per device with its number, epoch 1 and seed, owner-only, and the roster of public keys, one name value a line in lowercase hex, numbering after the roster’s highest and never overwriting a file; mud provision <dir> --key writes a rotation’s next key, fleet.key.next, beside the fleet’s own. The ABI’s peer entries are no_std, and the simulator, the generator and wasm’s allocator are its std feature, default on, so the shipped libmudrpc is unchanged and a firmware links the ABI built with --no-default-features, whose panic handler calls C’s abort and which the tripwire links. A product copies one wrapper file and reads one skill. Package managers wait for 3.0 at the earliest. Wrappers supply uptime by default and persist the epoch beside the key; core reads neither a clock nor an RNG.

ABI rules, each a test. Caller-owned memory (mud_size then mud_new); no allocation; no caller pointer retained past the call; every string and buffer as (ptr, len), a block too: every entry that takes mem takes its len after it, and a length under 4 bytes or under the shape its tag names is MUD_EMEM, the tag the one thing read; mud_save takes its copy’s length as well and refuses a copy that overlaps its source by any byte as MUD_EINVAL, as every entry refuses a buffer or struct it is passed sharing a byte with the block, one of no bytes sharing none wherever it points, and a struct pointer misaligned for its type; every function returns a code; no callbacks; deliver and outgoing write into the caller’s buffer so nothing points into peer memory; mud_save is the one way to copy a block out, and the copy is disarmed until mud_resume. One thread drives a peer, and the block says so when two do: every entry that takes a block and returns a code holds a busy byte in it (a byte that was padding and zero, so a block saved before it reads as not busy and MAGIC stays) while it runs, and one that finds it held, any value but 0, is MUD_EBUSY with nothing done; mud_resume alone takes a held block, and clears it when it succeeds, since an entry a crash or a panic ended leaves it set, so such a block cannot be saved or dropped before a higher epoch resumes it; mud_new builds over whatever mem holds, and a save’s copy is not held. A detector of the host’s fault, not a lock: two threads that pass the check together are not caught, and the four reads (mud_count, mud_pressure, mud_pending, mud_queued) write nothing and read on. The Rust Peer needs none, since &mut self rules a second caller out. The codes are MUD_OK and MUD_EINVAL to MUD_ERATE, −1 to −9, MUD_EBUSY −10 and MUD_EPANIC −99, the same numbers in every wrapper. No constant secrets: mud_new and mud_stage refuse a key or seed whose 32 bytes are all equal, which is a zeroed config and the constant examples once shipped, and every skill’s example draws its key from the host’s random source and says so on that line; the harnesses derive their fixed keys as counting bytes, the same way in six languages, so the logs stay identical. A tripwire, not a test of randomness: it catches the two accidents that happen.

Six block shapes, by role and cipher. The tag, the block’s first word, names the shape at every entry, and every shape holds 16 pending calls and 16 queued wires:

Tag Shape Cipher Wire Bytes Roster lines Windows Seen entries mud_config
0 leaf ChaCha20-Poly1305 1 mud_size(), 13 936 none 16 64 cipher 0, no seed, hub 0
1 signed leaf ChaCha20-Poly1305 2 mud_size(), 13 936 16 16 64 cipher 0, seed and budget, hub 0
2 hub ChaCha20-Poly1305 2 mud_hub_size(), 65 776 256 256 1024 cipher 0, seed and budget, hub 1
3 leaf AES-256-GCM 3 mud_size(), 13 936 none 16 64 cipher 1, no seed, hub 0
4 signed leaf AES-256-GCM 4 mud_size(), 13 936 16 16 64 cipher 1, seed and budget, hub 0
5 hub AES-256-GCM 4 mud_hub_size(), 65 776 256 256 1024 cipher 1, seed and budget, hub 1

A leaf’s tables are what a drone’s MCU affords; a hub’s are for the host that believes a fleet and has the RAM: 256, the 200-peer run’s fleet rounded up to a power of two, four seen entries a window as a leaf’s (hub-telemetry measures it). An unsigned peer has no roster to size, so a hub without a seed is MUD_EINVAL and an unsigned ground station keeps a leaf’s tables, full in hub-telemetry’s unsigned log. hub or cipher above 1 is MUD_EINVAL, and a hub’s tag in a leaf’s length MUD_EMEM, so a hub block never reads as a leaf’s (Gcm is Key’s 136 bytes, hence two sizes). A line past the roster is MUD_EFULL in the ABI, an exception in every wrapper, never a trap; the standard harness boots gcs as the hub and each drone as a leaf believing the hub and the drones that fit, as fleet-of-40 runs signed in six languages. Every wrapper takes hub and the cipher at construction, sizes its save by the role and restores by length, and defaults to MUD_CIPHER_DEFAULT under its own name: AES, the NIST algorithm (Decisions, “One cipher or two”); in C a zeroed config is ChaCha, 0 being ChaCha’s before AES and an older block keeping its tag, so the C skill’s example names the constant. A block resumes under the cipher whose key checks it holds, so retagged to the other it is MUD_ECORRUPT; a peer drops the other cipher’s wires as Version, so a fleet runs one. Each AES shape is another monomorph: the three added 33 964 bytes to the release library’s __text on aarch64-apple-darwin and 52 162 to its wasm; later the __text was 431 928 bytes, the wasm 390 196; the tripwire, then linking core, auth and gcm without the ABI, did not move.

What a shape costs on a board. RAM is the block, one scratch and the stack below the deepest entry, in bytes; flash is the library’s.

Tag Shape Block Scratch Stack, M4 / RISC-V
0 leaf, ChaCha20-Poly1305 13 936 576 2 360 / 2 376
1 signed leaf, ChaCha20-Poly1305 13 936 576 3 940 / 4 500
2 hub, ChaCha20-Poly1305 65 776 576 as tag 1
3 leaf, AES-256-GCM 13 936 576 3 464 / 3 380
4 signed leaf, AES-256-GCM 13 936 576 3 932 / 4 500
5 hub, AES-256-GCM 65 776 576 as tag 4

The scratch is one buffer of MUD_MAX_TOPIC + MUD_MSG bytes, which mud_outgoing needs and mud_deliver’s MUD_MSG fits in, lent to one at a time; the transport’s receive buffer is the host’s. The stack is the peer’s deepest entry, call, which signs and seals, measured under QEMU in the tripwire profile on both boards by a stack painted below it (a signed wire’s deliver 3 564 / 3 652, outgoing 100 / 148, the ABI’s own frame not included); a hub runs the signed leaf’s code with its larger tables in the block, and the boards hold none. Flash is the library’s, not a shape’s, since every ABI entry dispatches on the tag to all six: the tripwire’s text, core, auth, gcm and the ABI without std as CI’s size step measures it, is 162 794 bytes on thumbv7em, 159 058 on thumbv6m, 163 510 on thumbv8m and 204 982 on riscv32imc (rustc 1.91.1; 10 000 to 23 000 more since the tripwire began to exercise the Signed<Gcm> peer as the other three, code the library already held), and a Rust firmware over core directly links its one shape, not measured apart.

The ABI is bindings/c/mudrpc.h, one screen, and the one copy of it.

The skill is the front door. Each skill is enough on its own for a developer, or an LLM they point at it, to integrate a product: the smallest complete example against sim, the exact commands that prove it, the automatic .proto hook.

Tests:

6 · Simulator and hardware

sim is a Transport whose instances share a World: peers, a reachability matrix, a queue of in-flight messages with delivery ticks, a seeded xorshift RNG. A scenario mutates the matrix or queue at ticks. Same seed, same run. A step applies its events and sends what is due, then moves only the wires alive at its end, when the peers read them, so nothing that dies inside a warp lands after it, and a flood sends none of its junk, which lives 10 s, in a step longer than that; a wire’s expire line is written at the first step its ttl has passed.

Where the mocks honestly differ: what happens with no path. Reticulum: a destination is known to a radio only once its announce has crossed a live path to that radio, so a listener behind a partition becomes reachable a second after the heal, not at it; with no path a message waits at the sender. DTN: the bundle leaves at once and is held by whichever peer last had it; it survives the sender’s death. Each mock opens with a “what we think you do” comment for its maintainers.

Scenario files, read with a whitespace split:

seed 7
peers 3
profile reticulum
0      partition 0 1
30000  heal      0 1
45000  replay    2

Kinds the world applies: partition a b, heal a b, jam a, heal a, malformed a topic, replay a, flood a topic rate (to 20 000 a second; past 1000 a step’s junk lands at once, one line a receiver, wearing the version byte its radio last heard), bandwidth a bytes_per_sec, peer_down a, peer_up a, noise a rate (bits flipped in the peer’s copy), hold a ms (from then radio a keeps each wire it hears, once, as a store-and-forward box forwards a bundle once, and sends it again, byte for byte as it was on the air, its noise on its peer’s copy alone, ms after it arrived, through a reboot; 0 stops the keeping). Kinds the harness performs as host events: clone, spam, stage, rotate, retire, warp, hostile, stale_reboot, torn_save, revoke, telemetry. A clone’s radio is empty until its first clone row, in the order every harness performs host events (by time, then file order), and has no boot image of its own, so a host event its peer performs before then (spam, rotate, hostile, revoke as the one revoking, stale_reboot, torn_save; a clone from it boots its source’s roster line, as every harness does) and a storage fault on it at any time are refused by the parser at their line, once for the six harnesses; the world’s kinds act on the radio, which exists; gcs calls every 150 rounds, not when the clock is a multiple of 15 s, so a warp off the 100 ms grid keeps the cadence, and the round a warp lands on runs again at the new clock, its calls made a week on, and the run ends 50 s after the later of the last event and the clock a warp left; while a flood is on, the harness says every ten rounds how many events each peer that took one took. Bandwidth is airtime at the sender: a message takes len / bps to leave. The standard set, each with its checked-in logs: partition-heal, jamming-window, hostile-peer, bandwidth-collapse, hostile-method, insider-flood, rollback, rotation, stranger, fleet-of-40, hub-telemetry, junk-at-bandwidth, relay-holds-past-ttl, noisy-radio, stale-epoch, torn-save. The campaign’s, held the same way: fleet-of-256 and reflash-within-the-week on a push, fleet-of-1024, all-at-once and churn-of-1024 before a release; the second reader’s on a push: noisy-relay-ring, warp-off-the-round, full-at-both-ends, starved-command, down-caller; the third’s: warp-on-the-call, many-calls-one-round, unsorted-host-events, expired-across-the-warp; the last’s: warps-in-one-round and warp-past-the-end.

The log is evidence, so it never lies by omission. One line a world action (send, deliver, expire, listen, radio, event) and one a peer verdict, each led by its millisecond in a column nine wide, the digits MAX_MS needs; a reader takes the time up to the first space, so a clock past it overflows the column, never the parse. A peer’s identical lines in one round are one line with ×n. A call, publish or reply the peer refuses is a line in the drops’ form, peer2 refused reply Full. An event names its sender, peer0 event "gcs" "pos" from sender 5, as a flood and a rollback do, so a receiver’s log says whose reports it ran and a reused nonce run twice can be read from it; a drop names none, since a refused wire’s number is unauthenticated, so Open(Roster) ×768 counts strangers and does not name them. Past MAX_LOG, 100 000 world lines, the world counts the rest by kind and the last line says so, world lines past 100000 counted, not written: send 24859, event 20, deliver 30690, expire 5121 for a 1 024-fleet reporting every second for a minute, whose world lines end at 41 s; every peer line is written, the pressure lines that close the log among them. Every checked-in log is whole but the two largest, fleet-of-1024’s and churn-of-1024’s under both sealers, which are their peer lines, every peer…, gcs and host: line, with the world’s held by one last line counting them by kind in the cap’s form, world lines counted, not written: listen 2947, send 18109, event 1986, deliver 25967, radio 1474, expire 6135 for churn-of-1024’s 56 618: whole, the four were 7.8 MB of a published repository and their world lines four fifths of it, as peer lines 1.6 MB, and the long test holds a fresh run, filtered the same way (sim::peer_lines, the scenario example’s --peer-lines), to them byte for byte. In flight the world holds at most MAX_INFLIGHT, 1 048 576 wires: a wire in flight costs 120 bytes, its topic and wire and one bit a radio twice, 424 bytes for a 52-byte report at 1 024 radios, so about 500 MB at the ceiling; that is a 1 024-fleet reporting every second for 1 024 s, where the harness’s reports keep 600, or ten a second for 102 s. Past it a send is not queued and is a full line; a run that reaches it has passed MAX_LOG on the way, so the tail counts it, full 2. churn-of-1024 peaks at 13 098. A holding relay remembers each wire it held, so its memory is the distinct wires it heard while holding. No harness has a ceiling below the simulator’s 1 024 or the peer’s: a round answers every call a receiver takes, up to its RX_PER_SEC, and host events at one millisecond keep file order, in all six; C ran every campaign scenario under the four sealers byte for byte (churn-of-1024 in 32 to 36 s a mode, the simulator’s time, as Rust), and Python, .NET, Java and JavaScript ran fleet-of-1024 in 10 to 18 s and all-at-once’s 1.8 million junk wires in 2 to 19 s; on a push C, .NET, Java and JavaScript run the campaign’s push pair beside the standard set and the readers’ nine, and Python the standard set and the nine, the pair costing it 9 s.

Rungs, one behaviour. In-process: a World in a test. Loopback: several radios on one machine over lan on real UDP sockets (one process in the tests, several in the field), the same fault-injection module deciding what to drop, the sender alone deciding whether a link is up; it carries the link kinds and the host events, and Lan::new refuses at its line a scenario with a kind only the World applies (malformed, replay, flood, noise, hold, bandwidth), since over loopback it would be a clean run. LAN: the same over real devices, when someone has them. Relay: the same binary on a box on your own LAN. CI climbs to loopback, and runs core on the target’s instruction set under QEMU (the bar); LAN and relay wait for the bench rig. lan refuses non-private addresses. Nothing listens on the internet.

Hardware. A board is where core runs; a radio is what a transport talks to. Hardware enters as cross-builds and QEMU; a rig with real radios is the integrator’s, the sim skill’s reference rig a starting point. CI cross-builds core for thumbv7em-none-eabihf (STM32H7: Pixhawk 6X, Cube Orange+), thumbv6m/thumbv8m.main (RP2040/RP2350), riscv32imc (ESP32-C3/C6), aarch64-linux (Pi, Jetson), wasm32-wasip1 and wasm32-unknown-unknown (the JavaScript wrapper), and for the four embedded targets asserts the size of the tripwire binary’s code (llvm-size’s text: core, auth, gcm and the ABI without std as a product’s release build links them) against a ceiling. IP mesh radios (Doodle Labs, Silvus, Rajant, Microhard, Persistent) present as Ethernet, so lan is already their adapter. LoRa goes through Reticulum on RNode hardware (LilyGO T-Beam, Heltec, RAK4631). The bench rig in the sim skill: three Raspberry Pis on Wi-Fi, a T-Beam each for the Reticulum rung, one Pixhawk with a CM4 companion for fit-for-purpose. What is “popular” is a trade-press claim until the first two real products say what they fly.

Tests:

Repository

mudrpc/
  CLAUDE.md  SPEC.md  SECURITY.md  LICENSE  README.md
  BACKLOG.md              To do, the gates that need the owner, Later
  core/                   lib.rs  codec.rs  envelope.rs  seal.rs  rpc.rs
  auth/                   sha512.rs  ed25519.rs  signed.rs             the signed sealer
  gcm/                    aes.rs  ghash.rs  lib.rs                     the AES-256-GCM sealer
  adapters/               transport.rs  sim.rs  lan.rs  harness.rs  SKILL.md  CONFORMANCE.md  examples/scenario.rs
  scenarios/              `<name>.scenario` + `<name>.log`, and `.signed.log` or `.gcm.log` where a sealer changes the log
  proto/                  mud_options.proto
  bindings/               c/ffi.rs + mudrpc.h   python/mud.py   dotnet/Mud.cs   java/Mud.java   js/mud.js, each + SKILL.md
  gen/                    parse.rs  rust.rs  python.rs  c.rs  main.rs (the `mud` binary)
  tripwire/  qemu/        the no-panic link and the target in CI
  demos/                  drones/ and sensors/: one .proto each and one program per language, every one printing the same lines
  docs/                   the longer pages, one phrase each, and their map; every folder a README.md front door; _config.yml renders the tree as the site
  packages/               build.sh and one manifest per package manager: npm, NuGet, PyPI, Maven, Conan, vcpkg; crates.io from the manifests, Go from bindings/go/go.mod

Core is four modules and lib.rs. If it grows, ask why.

Skill template, one per adapter and wrapper:

---
name: <name>
description: How to integrate, verify and test the <name> <adapter|binding> for mudRPC.
---
## Integrate        — the smallest complete example, copy-pasteable, runs against sim; the automatic .proto hook
## Verify           — the exact commands that prove the contract is honoured, not just compiled
## Test at each rung — in-process / bench (lan) / relay (self-hosted)
## Known edges      — when one appears, widen the principle in core; do not patch here

What we do not build

The bar

Set 2026-10-16. This is a low-level library beside systems whose failure costs lives: search and rescue, medical delivery, the inspection of things that fall down; good enough is not enough. The bar is not a feeling, it is a list of gates, each one a test, a document or a signature from outside, and 3.0 does not ship with one open. The ceiling is stated too: an open MIT library claims no certification; what it can be is CNSA-compliant algorithms, open assurance evidence and an independent audit, which is where regulated procurement starts.

Cryptography:

Assurance:

Robustness:

Process:

Decisions

Settled:

Open:

Prior art (read before writing anything)