jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/test-vectors/README.md
Rob cafb2889ab Initial bootstrap: README, LICENSE, SPEC.md, agent.md, scaffolding 
Bootstrapped from the working notes of two reverse-engineering efforts:
- reticulum-lora-webclient (web/Capacitor)
- reticulum-mobile-app (Kotlin Multiplatform / Android)

SPEC.md consolidates byte-level wire format findings that aren't in the
upstream Reticulum manual. Each section grounded in upstream Python
source citations (file + line) where possible.

agent.md establishes the verification rules:
- Every claim is verified, unverified, or speculation; markers required
- Verification means a runnable script or a source citation
- PRs that quietly remove markers get rejected

tools/ and test-vectors/ are placeholder scaffolding with READMEs
describing the work needed.

Sections in SPEC.md flagged as currently UNVERIFIED:
- §2.3 Originator HEADER_1 -> HEADER_2 conversion
- §4.3 app_data 3-element variant with capabilities
- §7.1 path? always precedes LXMF (vs only on stale paths)
- §7.4 ratchet ring count default = 8

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 09:38:46 -04:00

2.3 KiB
Raw Blame History

Test vectors

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

Status

Empty placeholder. See ../agent.md §5 for the bootstrap 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

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.

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.