reticiulum-specification/test-vectors

Test vectors

Known-good byte sequences that any Reticulum-compatible implementation should be able to round-trip in both directions.

Status

Populated against RNS 1.2.4 / LXMF 0.9.7:

• ✅ identities.json — Alice + Bob identity vectors (regenerator: ../tools/regen_identities.py, verifier: ../tools/verify_destination_hash.py).
• ✅ announces.json — two announce vectors (no-ratchet + with-ratchet) signed by Alice (regenerator: ../tools/regen_announces.py, verifier: ../tools/verify_announce_roundtrip.py).
• ✅ lxmf.json — two opportunistic-LXMF vectors Alice → Bob (regenerator: ../tools/regen_lxmf.py, verifier: ../tools/verify_lxmf_opportunistic.py).
• ✅ links.json — full Link handshake vector (LINKREQUEST + LRPROOF + derived session key) Alice → Bob, plus an LRRTT packet (§6.4.2) emitted from the initiator with pinned IV and rtt_seconds = 0.05 (regenerator: ../tools/regen_links.py, verifiers: ../tools/verify_link_handshake.py, ../tools/verify_link_lrrtt.py).
• ✅ resources.json — deterministic multi-part Resource ciphertext, part packets, hashmap, advertisement, and proof body (regenerator: ../tools/regen_resources.py, verifier: ../tools/verify_resource.py).
• ✅ link-lxmf.json — DIRECT LXMF PACKET and Resource vectors at the exact 319/320 computed-content boundary (regenerator: ../tools/regen_link_lxmf.py, verifier: ../tools/verify_link_lxmf.py).
• ✅ request-response.json — Link REQUEST/RESPONSE packet and Resource forms with deterministic correlation IDs (regenerator: ../tools/regen_request_response.py, verifier: ../tools/verify_request_response.py).
• ✅ propagated-lxmf.json — PROPAGATED LXMF submission packet/Resource boundary, full transient IDs, and /get framing (regenerator: ../tools/regen_propagated_lxmf.py, verifier: ../tools/verify_propagated_lxmf.py).
• ✅ propagation-peer.json — propagation-node announce, directional peering key, /offer, and peer-sync Resource plaintext (regenerator: ../tools/regen_propagation_peer.py, verifier: ../tools/verify_propagation_peer.py).
• ✅ transport-link.json — one-relay LINKREQUEST, LRPROOF, established-Link DATA, and invalid HEADER_2 fixtures (regenerator: ../tools/regen_transport_link.py, verifier: ../tools/verify_transport_link.py).

All ten files are byte-deterministic across runs: regenerators pin every random source (ephemeral keys, IVs, random_hash values, timestamps) so the output is reproducible against a fixed upstream RNS / LXMF version.

See ../agent.md §3 and ../todo.md for the evidence model and remaining task list.

Format (proposed)

Each vector lives in a per-domain JSON file, e.g.:

• identities.json — Alice + Bob with encPriv, sigPriv, ratchetPriv (hex), plus the derived publicKey, identityHash, destinationHash for lxmf.delivery
• announces.json — full hex of a signed announce packet, plus the inputs that produced it (display_name, ratchetPub, etc.)
• lxmf.json — sender + recipient identity, plaintext, expected ciphertext bytes
• links.json — LINKREQUEST + LRPROOF + derived session keys
• resources.json — Resource plaintext, encrypted stream, parts, hashmap, advertisement, and proof
• link-lxmf.json — DIRECT LXMF Link DATA and Resource boundary forms
• request-response.json — Link REQUEST/RESPONSE packet and Resource forms
• propagated-lxmf.json — PROPAGATED submission and /get response forms
• propagation-peer.json — propagation-node announce and peer-sync forms
• transport-link.json — transport-relayed Link establishment and traffic forms

Each entry should include:

{
  "description": "Alice's lxmf.delivery announce with ratchet, display_name='AliceTest'",
  "inputs": { ... },
  "expected_bytes_hex": "...",
  "rns_version_at_generation": "1.2.0",
  "generator_script": "tools/regen_announces.py"
}

The generator_script is the file in ../tools/ that, when run against upstream RNS, regenerates expected_bytes_hex. Keeping the generator alongside the vector lets a future contributor verify the vector still matches a newer upstream RNS.

What needs to round-trip

For the spec to claim "an implementation that passes all test vectors interoperates with upstream", the vectors must cover:

1. Identity construction — given the same private-key inputs, derive the same public key, identity hash, destination hash.
2. Announce build + parse — build a signed announce; verify the same bytes come back through upstream's parser; verify upstream-built announces parse correctly.
3. Token encrypt + decrypt — bidirectional, with both ratchet and long-term keys.
4. Opportunistic LXMF — full plaintext → ciphertext → plaintext round-trip, signature valid both ways.
5. Link handshake — LINKREQUEST built by client A, LRPROOF computed by upstream as B, both arrive at the same link_id and session keys.
6. Link-delivered LXMF — body packed by client, decrypted + parsed by upstream. Covered by link-lxmf.json.
7. Resource transfer — encrypt once, split into parts, validate ADV/hashmap, assemble, and emit the expected proof.
8. REQUEST/RESPONSE — packet and Resource RPC forms, request-ID derivation, and response correlation.
9. Propagated LXMF — recipient-encrypted submission, full transient-ID derivation, packet/Resource selection, and /get framing.
10. Propagation peer sync — node announce, directional peering key, /offer selection, and stamped Resource transfer.
11. Transport-relayed Link — LINKREQUEST/LRPROOF relay state, bidirectional established-Link forwarding, and invalid-header failure behavior.

A separate vector set for FAILURE cases is also useful: malformed announces, expired ratchets, mismatched signatures. An implementation should reject those as a regression-prevention measure.