meshticulumDeveloper documentation / Technical overview
Follow the bytes.
Keep the boundaries.
Meshticulum separates application acceptance from reliable delivery and radio completion. Each layer has its own evidence, and each transfer keeps its original limits.
The reusable stack
Two services.
A bounded transport.
Applications supply current admission and device ownership. Meshticulum supplies reusable contracts, cryptography, reliable flow, resources and carrier workers.
01 / Protocol
A request is more than a byte range.
The MR1 resource codec names a public pack and resource, then asks for a bounded range. A response carries a truncated hash of that exact request, a status, the total resource length and the returned offset. The reader checks all of them before assembling the bytes.
MR1 is an application codec. Peer authentication, encryption, deadlines and transport ownership must already be enforced by its exchange. A valid response header alone does not establish publisher trust.
02 / Cryptography
Bind the session. Authenticate every frame.
PeerID identifies the full chain and signing-key identity. SessionKey adds both peers, a session identifier and a separate generation. Service, route, profile, limits and expiry enter the session context; a compact reference on the air is not an identity or permission by itself.
Current radio and TCP codecs derive directional keys with HKDF from a provisioned pairwise secret. ChaCha20-Poly1305 authenticates DATA and ACK packets. Transmit counters are reserved durably before encryption, and receive replay decisions are committed before plaintext is exposed. A retransmission gets a fresh outer counter while retaining the flow's logical sequence number.
Private envelopes add a separate boundary: a sender signs the message and seals it to the intended recipient. The compact binary carrier removes outer Base64 framing while preserving the ciphertext and signature.
The current provisioned session codecs and long-term recipient envelopes do not establish it. An experimental forward-session primitive exists in source; native private lifecycle and erasure qualification remain open.
The default radio, TCP and private-envelope protocols use classical cryptography. Draft PR #5 combines X25519 + ML-KEM-768 and requires both Ed25519 and ML-DSA-65 signatures. Its 49 source checks pass, but it is unmerged and has no device integration yet.
The sample handshake is 9,352 bytes before radio headers, ACKs, retries and identity distribution. Independent cryptographic review and device measurements remain open. Read the PQ status and try the prototype.
03 / Reliable flow
Credit controls what can enter.
MT05 fragments a transfer and tracks receipt with a cumulative acknowledgement plus a 32-bit selective bitmap. Receiver credit counts available capacity, including held reorder frames and unconsumed delivered bytes. A stale ACK cannot create new credit.
The flow owner routes DATA, retries, probes and ACKs through scheduling and admission. Its accepted flow and port are frozen under reviewed source hashes. The authenticated radio composition currently uses packets up to 255 bytes, leaving 193 useful bytes in a DATA frame.
A driver reporting RF_DONE proves local completion of that attempt. An authenticated peer ACK proves another event. Durable public-resource verification comes later.
Accepted reliable flow · Authenticated composition · Transfer walkthrough
04 / Verified resources
The publisher's identity survives the path.
A public pack starts with an independently pinned publisher trust root, signed manifest and content-addressed chunks. Lamplighter verifies the manifest and complete chunks before caching them. Availability information helps select a source; it cannot authenticate that source's content.
Bounded MR1 blocks move raw resource bytes over the scarce carrier. Host code reconstructs any batch representation locally for the whole-chunk verifier. A partial transfer remains unverified, and resume reuses only verified work.
Pack schema and signatures · Publisher and cache verification
05 / Path selection
Use measurements, not interface names.
The resource scheduler works with explicitly supplied routes, verified request timings and shared bottlenecks. It can choose another admitted reader for the same content and retain verified chunks. It does not discover routes autonomously or move a live cipher session between carriers.
Finite native public campaigns have exercised mixed LoRa/IP delivery, injected loss, fresh LoRa resume and measured return to IP under one original resource expiry. Those results demonstrate specific service paths. Sustained network capacity is still a separate qualification.
06 / Device ownership
A library import cannot grant a radio.
The host application supplies the exclusive port or HAT owner, current peer and service admission, original clock bounds, and attempt journals. Radio workers reserve cost before device writes. An unknown outcome retains debt and fences further dispatch.
Lantern owns its protected SAGE adapters, native device policy, provisioning, product orchestration and deployment. Meshticulum remains usable by other applications without importing those components.