docs: authenticated trie integration spec — Phase 1B state-proof API

[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: metagraph phase 1 — per-fiber stateRoot + metagraphStateRoot #117)
• Phase 1: PR feat: metagraph phase 1 — per-fiber stateRoot + metagraphStateRoot #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+)

[ottobot-ai]

🤖 Quality Score: 80/100

PR Agent Review — Tier 1 Gate

Category	Score	Notes
Description quality	23/25	Excellent spec: API contract, 22 TDD tests, 10 acceptance criteria, Trello ref
CI status	13/25	Fixes applied: header shortened to 70 chars, PR title lowercased — CI re-running
Content quality	22/25	Spec doc + docker fix + deps bump, coherent and well-structured
Commit compliance	15/15	Fixed: header was 73 chars (>72 limit) — now 70
Hygiene	7/10	Good branch name; no labels yet

Fixes applied: Shortened commit header (73→70 chars), lowercased PR title

Score 80/100 meets threshold (80+). Promoting to human review.

CC: @scasplte2 for final review.

[ottobot-ai]

🔄 Resolved merge conflict and rebased onto main.

Conflict resolved: docker-entrypoint.sh — trivial blank-line conflict from the fix(docker): currency L0 run-rollback commit. Accepted incoming (no blank line).

[ottobot-ai]

🔄 Resolved 1 conflict (blank line in docker-entrypoint.sh) and rebased onto main.