feat(dRAG): Decentralized GraphRAG V1 — verifiable, cross-node, monetizable answering (OT-RFC-55)

[branarakic]

feat: Decentralized GraphRAG (dRAG) V1 — verifiable, cross-node, monetizable answering (OT-RFC-55)

Implements OT-RFC-55 as a working V1 on main (v10.0.0): ask one natural-language
question and get a grounded answer whose every fact is independently auditable
against the chain — answered locally, or fanned out across the nodes serving a
public Context Graph and re-verified by the asker, with an x402 payment seam
wired for monetization.

Built in four layered, independently-shippable increments. Each was validated on a
live 4-node devnet.

What's in it

P1 — Verifiable citation core (core/crypto/citation.ts, agent/drag/citation.ts)
Composes the already-shipped V10 primitives into one auditable citation object
{UAL, node, author-sig, merkle, on-chain}:

• Merkle inclusion over the keccak V10 structured tree (buildV10ProofMaterial),
  re-anchored to the live on-chain getLatestMerkleRoot(kaId) — so a citation that
  verifies offline verifies on-chain by construction.
• Content-binding: the proof binds to the exact cited triple (tripleContentV10).
• EIP-712 author-seal recovery (recoverCitationAuthor), with the chain-verified
  on-chain author as the authoritative fallback when the _meta seal is absent.

P2 — dkg_answer single-node (agent/dkg-agent-drag.ts, cli/routes/drag.ts, mcp-dkg)
question → keyword retrieval over per-KA verifiable-memory graphs → canonical triples → a citation per fact. No node-side LLM required (keyword/structural
baseline; LLM synthesis is a future enhancement). New POST /api/answer,
DkgClient.answer(), and the dkg_answer MCP tool.

P3 — Cross-node fan-out (scope:"network")
findNodesServingCG reads the contextGraphsServed phonebook (the §5.1
context-oracle index); a new PROTOCOL_DRAG_ANSWER libp2p protocol lets a peer
answer over a public CG (ACL = the same isContextGraphPublicOnChain
fail-closed gate as query-remote). dragAnswerNetwork fans out, dedups, and —
crucially — re-verifies every citation against the asker's own chain, so the
asker trusts no serving node's self-reported verdict and can answer over knowledge
it does not hold. Optional explicit peers override for not-yet-gossiped CGs.

P4 — x402 payment seam (cli/daemon/payment.ts)
Public CGs are free in V1, but the HTTP-402 challenge + X-PAYMENT wire format
and a pluggable PaymentVerifier (MockPaymentVerifier for dev/CI) are in place so
the real Coinbase/USDC facilitator drops in behind one interface. simulatePrice
exercises the full 402 → pay → 200 + receipt flow. Localized in the drag route —
does not touch the central request chain.

Validation

• Unit: 18 citation tests (core+agent) + 14 payment tests (cli). Full suites
  green for every touched package (core 1092, mcp-dkg 325, agent ~1740, cli ~2120).
• Live devnet (4 nodes): combined run, 9/9 —
  • local cited answer, every citation author-sig ✓ merkle ✓ on-chain ✓;
  • priced request returns 402, then 200 + settlement receipt with a valid
    X-PAYMENT, paid answer still fully verified;
  • an asker holding no copy of the CG assembled a multi-fact answer from
    remote serving nodes, every citation re-verified against its own chain.

Security hardening (adversarial review)

A multi-dimension adversarial review of the diff confirmed 10 findings (3 high,
3 medium, 3 low), all addressed in the hardening commit:

• Remote handler DoS — the unauthenticated PROTOCOL_DRAG_ANSWER verb is now
  per-peer rate-limited and clamped to a small remote cost ceiling.
• Asker fan-out bounds — peer fan-out is capped + concurrency-bounded (no
  caller-driven reflection); per-peer citation re-verification is bounded.
• Malformed-peer isolation — each peer response is shape-validated and each
  citation is guarded, so one bad/version-skewed peer can't fail the whole answer.
• CG-scope binding — re-verification confirms each citation's KA belongs to
  the asked context graph (getKAContextGraphId); a peer can't pass off a
  verifiable fact from a different KA, and the asker never trusts the remote's
  scope fields.
• Verdict integrity — the verdict cache is keyed on the proof and dedup
  prefers a verified citation, so a bad proof can't poison/suppress an honest one.
• Defense-in-depth — validateContextGraphId before SPARQL interpolation;
  the leaf count is re-anchored against chain (the pure check was tautological).

The two refuted findings (a "second-order IRI injection" and a "dedup delimiter
collision") were verified non-exploitable (the store's serialization boundary and
the terminal-field key layout, respectively).

Reasoned, not unit-tested (validated by code review + the live happy path, but
without a dedicated adversarial test): the off-scope citation drop (a malicious
peer returning a fact from a different KA — the CG-scope binding is confirmed
active on the non-subscriber path, since ontology id-mappings sync network-wide),
the verdict-cache collision fix, and the dkg_answer MCP stdio tool path (the
underlying /api/answer endpoint is live-validated). The CG-scope check fails
open (facts stay cryptographically verified, scope unconfirmed) only when the
asker cannot resolve the CG's on-chain id — surfaced explicitly in the answer.

Honest scope / deferred (NOT in V1)

• Confidential / ZK answering (RFC §5.3) — citations are over public (VM)
  facts; private-data answering and the ZK layers are future work.
• Private-CG routing — fan-out is public-CG only (the phonebook deliberately
  advertises only public, subscribed CGs).
• Real x402 settlement — MockPaymentVerifier only; no live facilitator / USDC
  (the node has no USDC and is ethers-only; not CI-runnable).
• LLM synthesis + question→CG auto-routing — the keyword baseline is the V1
  headline; LLM is a clean seam (no key on devnet). The caller names the CG.
• Phonebook propagation latency — contextGraphsServed advertisements integrate
  into peers' agents-CG on the profile-heartbeat cadence, so discovery can lag a
  just-created CG; the explicit peers override is the deterministic fast-path.

How to try it

./scripts/devnet.sh start 4
# create a public CG, publish a KA, then:
curl -s localhost:9201/api/answer -H "Authorization: Bearer $TOKEN" \
  -d '{"question":"...","contextGraphId":"<cg>","scope":"network"}'

🤖 Generated with Claude Code