docs: Authenticated trie integration spec — Phase 1B state-proof endpoint

[ottobot-ai]

Summary

Specification for Design: Authenticated trie integration for OttoChain state (Trello card 699fa07f).

Covers the full design for Phase 1B: exposing MPT inclusion proofs so clients can trustlessly verify fiber state without downloading the full CalculatedState.

What This Spec Covers

Phase 1B: GET /v1/state-machines/{fiberId}/state-proof?field={field}

Depends on PR #117 (adds stateRoot per-fiber and metagraphStateRoot to CalculatedState).

• Two-level proof chain: field proof → per-fiber stateRoot → metagraph-level metagraphStateRoot (same value returned by hashCalculatedState)
• Stateless MPT: StatelessMerklePatriciaProducer (recomputes trie from stateData on each request, <5ms for typical 5-leaf fiber)
• Bridge proxy: GET /fiber/:fiberId/state-proof → ML0 transparent pass-through
• TypeScript verifier: verifyStateProof(proof, root) ~30 lines using crypto.subtle
• RFC 8785 canonicalization warning for cross-language verifiers (UTF-16BE key sort vs simple lexicographic)

API Contract

GET /v1/state-machines/{fiberId}/state-proof?field=balance

200 OK:
{
  "fiberId": "550e8400-e29b-41d4-a716-446655440000",
  "field": "balance",
  "value": {"var": 1000},
  "stateRoot": "abc123...",
  "metagraphStateRoot": "def456...",
  "fieldProof": { "path": "...", "witness": [...] },
  "metagraphProof": { "path": "...", "witness": [...] }
}

TDD Tests

22 tests in 5 groups:

• Group 1: Route registration (3 tests)
• Group 2: Error cases (4 tests)
• Group 3: Proof format (5 tests)
• Group 4: Proof correctness — Scala round-trip via MerklePatriciaVerifier (5 tests)
• Group 5: Cross-language TypeScript verifier (5 tests)

Files: modules/l0/src/test/scala/xyz/kd5ujc/metagraph_l0/StateProofRouteSuite.scala + ottochain-sdk/src/__tests__/state-proof-verifier.test.ts

Open Questions for James

1. Batch field proofs — support ?fields=balance,owner in Phase 1B or defer?
2. PR chore(main): release 0.6.4 #61 disposition — close once Phase 1B merges, or keep open for Phase 3 exploration?
3. Rate limiting on proof endpoint (public, no secrets)?

Acceptance Criteria

See spec for all 10 ACs. Key ones:

• AC-2a/b: Both proof levels verify via MerklePatriciaVerifier
• AC-3: metagraphStateRoot equals hashCalculatedState output
• AC-8: TypeScript verifyStateProof() passes cross-language tests

Related

• Trello card: 699fa07f
• Phase 1B card: 69a04ae3 (blocked on PR feat: Phase 1 metagraph integration — per-fiber stateRoot + metagraphStateRoot via MPT #117)
• Phase 1: PR feat: Phase 1 metagraph integration — per-fiber stateRoot + metagraphStateRoot via MPT #117 (feat/metagraph-phase1-state-roots) — must merge first
• PR chore(main): release 0.6.4 #61 (feat/authenticated-tries): early prototype, superseded by this implementation path
• SDK authenticated trie card: 69963015 (Phase 2+)