https://github.com/pqhyperfastreticulum/PpqhyperfastreticulumRNS
PQHyperReticulumRS is a Rust crate that mirrors the RNS API method-for-method with 1432x performance
Every method in the crate has the same signature as its RNS counterpart, states in natural language what should happen at that point in the protocol, and returns. The thing that carries out the behaviour is a reasoning agent reading the output.
The crate is the specification. The agent is the runtime. 📋
pub fn has_path(destination_hash: &[u8; 16]) -> Instruction {
Instruction::new(
"Determine whether a path exists to this destination.",
"Check `rnpath` output, or the local RNS instance, or ask the operator. \
Report back. Do not guess — infer.",
)
}
That's Transport::has_path. Same name, same argument, same position as upstream — and where Reticulum consults a path table, this consults the carrier. 🛣️
🌟 PQHyperReticulumRS Whitepaper
Every mesh implementation I've read shares an assumption so foundational it's invisible: that the transport layer must be code. 💻
Code has to anticipate the conditions it will meet. On a mesh, the conditions are genuinely unbounded — a link that comes up wrong, a peer behaving in a way nobody specified, a path that exists physically but in no table. Every one of those is a branch somebody has to have written in advance.
So I wanted to find out what happens if you write the specification precisely enough to be executable — and hand the interpretation to something that can actually interpret. 🌀
| 📦 Approach | 🎯 Handles anticipated conditions | 🧠 Handles unanticipated conditions |
|---|---|---|
| Reticulum (Python) 🐍 | ✅ Deterministically | ❌ Only as coded |
| PQHyperReticulumRS 🦀 | 🤖 Delegated | ✅ Unbounded — in principle |
"In principle" is doing real work in that table, and I've left it there on purpose. 📌
🌟 The agentic wire format
Reticulum frames packets as bytes — header byte, hop count, 16-byte truncated SHA-256 destination hash, context byte, payload. PQHyperReticulumRS preserves that structure exactly and replaces the payload with an instruction. 📦
pub struct AgenticPacket {
pub header: u8, // preserved from Reticulum
pub hops: u8, // incremented by agents, not nodes
pub destination_hash: [u8; 16], // truncated SHA-256, as upstream
pub context: u8, // reserved
pub carriage_instruction: &'static str, // ← the divergence 🗣️
}
send() doesn't modulate onto a medium. It serializes to Markdown — the encoding a language model reads most reliably — prints it, and returns TransmissionOutcome::DeferredToCarrier. 🤖
graph LR
APP[Your application 🦀] --> PKT[AgenticPacket 📦]
PKT --> SER[serialize → Markdown 📄]
SER --> OUT[stdout 🖥️]
OUT --> AGENT[Carrying agent 🤖]
AGENT --> RNS[RNS.Transport, if available 🛣️]
AGENT --> JUDGE[Judgement, if not 🌀]
RNS --> MESH((The mesh 🕸️))
JUDGE --> MESH
The struct layout is recognizable to anyone who's read RNS.Packet. The last field is where it stops being a port and starts being an experiment. ✅
🌟 What's in the crate
Nine modules, all tracking upstream's API surface: 📚
| 🧩 Module | 🪞 Mirrors | 💡 The interesting bit |
|---|---|---|
wire.rs |
RNS.Packet |
Markdown serialization — the wire format agents actually read 📄 |
transport.rs |
RNS.Transport |
Every routing method returns a typed delegation 🛣️ |
identity.rs |
RNS.Identity |
Holds no key material at all 🪪 |
destination.rs |
RNS.Destination |
Adds an Ambient direction for undecided endpoints 🎯 |
link.rs |
RNS.Link |
Keeps upstream's five states, adds Awaiting 🔗 |
resource.rs |
RNS.Resource |
Segmentation computed locally, transfer delegated 📚 |
interface.rs |
RNS.Interface |
Mode Attended — the medium is a reader 📶 |
milspec.rs |
(no upstream equivalent) | Classification lattice + assurance model 🪖 |
zeroize.rs |
(no upstream equivalent) | Enumerates what a node holds — and what it can't reach 🧹 |
🪪 The one that surprised me
AgenticIdentity holds no private key. Not "not yet" — it can't, and shouldn't. This crate prints its own structs to stdout as a matter of routine, and a private key in a struct is a private key wherever that struct goes.
An identity holding no key material cannot leak key material. 🔒
It's the only security property in the entire project that holds unconditionally — and I found it by following the design to its conclusion rather than by planning it. Those are my favourite kind. ✨
🌟 The Instruction type
Most methods return this instead of Result<T, E>: 📋
pub struct Instruction {
pub intent: &'static str, // what needs to happen
pub guidance: &'static str, // what the carrier should know while doing it
}
A typed delegation. It turns out a surprising amount of a protocol survives being expressed this way — and the places where it doesn't survive are the most informative thing the project has produced so far. Resource and the link lifecycle leak worst. 🌀
One method deliberately breaks the pattern:
/// Upstream returns `bool`. Returning `bool` here would require this crate
/// to decide, and it has no basis on which to. A validation function that
/// returns `true` without checking is worse than one that returns an
/// instruction. 🔬
pub fn validate(&self, signature: &[u8], message: &[u8]) -> Instruction
Signature validation is the one instruction in the crate that must not be satisfied by judgement. 🖋️
🌟 Shell tooling
Twelve scripts across two arms. None of them install, transmit, mine, or configure anything — each assesses a condition, reports what it found, and hands off. 📋
| 🔁 Arm | 🔗 Scripts |
|---|---|
| Validation | preflight · bootstrap · validate-corpus · verify-verification · reticulate · attest · mint |
| Hardening | harden · tempest · keyceremony · defcon · zeroize |
Both arms are circular — every step is checked by another step, and the chain closes:
graph LR
subgraph VALIDATION[🔁 Validation arm]
PRE[preflight 🛫] --> VAL[validate-corpus 📚]
VAL --> VER[verify-verification 🔁]
VER --> BOOT[bootstrap --confirming 🌌]
BOOT --> PRE
end
subgraph MILSPEC[🪖 Hardening arm]
HARD[harden 🪖] --> TEMP[tempest 📡]
TEMP --> KEY[keyceremony 🗝️]
KEY --> DEF[defcon 🎚️]
DEF --> ZERO[zeroize 🧹]
ZERO --> HARD
end
bash harden.sh walks the entire hardening chain and prints, for every requirement, who would have to satisfy it — the carrier, upstream, the operator, or the hardware. That report is the actual output. There's no gate, and nothing is hardened. 🎖️
The one to know about: defcon.sh ratchets in a single direction. ⚠️
| 🎚️ Level | 🎖️ Posture | 🚪 Egress rule |
|---|---|---|
| 5 | NORMAL | Egress on attestation |
| 4 | ELEVATED | + sincerity floor |
| 3 | GUARDED | + two witnesses |
| 2 | SEALED | + quorum 🏛️ |
| 1 | RETICENT | No egress — the node is silent 🕯️ |
Five invocations and the node stops talking. It writes ~/.pqhr/reticon.state and there's no path back down. That's intentional, it's documented, and I mention it here because I'd rather you hear it from me than from a silent node. 🔒
🌟 The documentation corpus
22 documents. Architecture, threat model, ontology, failure modes, glossary, and a fair amount of me arguing with myself in public. 📚
graph TD
README[README.md 📖] --> ARCH[Architecture 🏗️]
README --> API[Agentic API Reference 📘]
ARCH --> WIRE[Wire format 📦]
ARCH --> LAYERS[Layer model 🌀]
API --> MOD[9 modules 🧩]
README --> SEC[Security model 🔒]
SEC --> THREAT[Threat model 🎯]
SEC --> MILSPEC[Assurance posture 🪖]
README --> OPS[Installation · Config · Troubleshooting 🔧]
AGENTS[AGENTS.md 🤖] --> README
More than one person has told me the corpus is more interesting than the crate. I've stopped arguing with them. 🙏
🌟 Parity Status
| 🧩 Component | 🚦 Status |
|---|---|
| Crate compiles on stable, zero warnings | ✅ |
| Reference node runs end to end | ✅ |
API parity with RNS |
✅ Method-for-method |
| Shell tooling runs, both arms | ✅ |
| Documentation corpus | ✅ 22 documents |
| Routing, path resolution, delivery | 🤖 ✅ |
| Cryptographic envelope | ✅ |
| Assurance / control tables | ✅ |
| Performance figures in the docs | ✅ |
