> ## Documentation Index > Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt > Use this file to discover all available pages before exploring further. # Proof readiness stack # WalletWall Proof-Readiness Architecture > **Scope.** This document is architecture only. It defines WalletWall's > *proof-readiness stack* and explains where eventual zero-knowledge (ZK) proofs — > with **SP1** as one candidate proving implementation — would attach. It adds **no** > prover, verifier, circuit, or contract code, changes **no** runtime behavior, and > changes **no** Dune behavior. It reconciles the existing ML-DSA / ZK research work > (in the public vault research repo) and the canonical readiness model (in this app) > into one map, without duplicating either. See also: * [Product Pillars](../product-pillars.md) — the Vault + Quantum two-tier hierarchy * [Vault-first positioning](../product/vault-first-positioning.md) — canonical thesis and red-lines * [Complementary feature alignment](../product/complementary-feature-alignment.md) — per-surface jobs + Phase 0–4 roadmap * [App-surface vault-readiness audit](../operations/app-surface-vault-readiness-audit.md) — whole-app relevance classification * [ZK Proof-Artifact Roadmap](../vault/zk-proof-artifact-roadmap.mdx) — staged, non-production ZK/SP1 next steps * [Vault/PQ integration traceability](../vault-pq-integration-traceability.md) — read-only evidence-shape boundary * [Dune query guardrails](../operations/dune-query-guardrails.md) — read-only / cache-only Dune posture * [Custody & Legal Boundaries](../product/custody-legal-boundaries.md) — custody / financial / language guardrails *** ## 1. Executive summary WalletWall is building a **proof-ready** readiness architecture. The platform maps wallet, stablecoin, and cryptographic exposure and turns that intelligence into vault-ready migration paths and read-only evidence packets. The platform is **proof-ready, not SP1-dependent**. Every readiness surface works today with no prover in the loop. A proof system is an *optional, additive* layer that can later attach verifiable evidence to a readiness result — it is never a prerequisite for the product to function, and it never changes what WalletWall *is*: * WalletWall is **read-only**. It takes **no custody**, holds no keys or balances. * WalletWall pays **no yield**, interest, or return, and makes no return projections. * WalletWall performs **no on-chain writes** and never asks a user to connect or sign with a wallet to use a readiness surface. * A proof does **not** turn a research heuristic into a guarantee. Readiness stays a research signal whether or not a proof is attached. In short: proofs make a *computation* auditable. They do not make WalletWall a custodian, an insurer, or a guarantor. SP1 is described here as a **candidate implementation for selected readiness-computation proofs** — one option inside the broader ZK proof family, not the architecture itself. *** ## 2. Current product hierarchy WalletWall is organized as a two-tier hierarchy (see [Product Pillars](../product-pillars.md)). | Tier | Surface | Job in the proof-readiness stack | | ----------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Primary** | **Stablecoin Vault** | The vault-readiness **workflow** and the evidence **destination**: where a user reviews readiness and rehearses migration safely (read-only, Sepolia testnet rehearsal only). | | **Primary** | **Quantum Intelligence** | The cryptographic **exposure and migration-risk engine**: what signature / custody / dormancy exposure affects migration readiness. | | **Complementary** | **Holder Wall** | Holder / wallet analytics — supplies candidate wallets and holder-set context. | | **Complementary** | **Whale Watcher** | Large-wallet movement signals feeding exposure context. | | **Complementary** | **Coinstellation** | Wallet-relationship graph context. | | **Complementary** | **Stable Seer** | Stablecoin / token market intelligence (peg, rails, flows). | | **Complementary** | **Watchlist** | User-selected wallets / assets that seed the readiness inputs. | | **Decision / evidence** | **Migration Readiness** | Normalizes exposure into a recommendation verdict inside the workflow. | | **Decision / evidence** | **Readiness Packet** | The **evidence/proof attachment container** — where proof and attestation references eventually live. | > *Market Radar* is **not** a present product. It was renamed **Stable Seer** (Epic > \#163) and survives only as a historical reference. Each surface answers a distinct question, and the proof layer keeps these questions separate rather than collapsing them: * **ML-DSA** answers: *who attested or signed this evidence?* (authenticity / provenance) * **ZK / SP1** answers: *was this readiness computation performed correctly under the approved ruleset?* (computation correctness) * **Readiness Packet** answers: *what evidence, recommendations, model version, and proof / attestation references are attached?* (the evidence container) * **Stablecoin Vault** answers: *how does a user review readiness and rehearse migration safely?* (the workflow) * **Quantum Intelligence** answers: *what cryptographic / signature / custody exposure affects migration readiness?* (the risk engine) *** ## 3. Proof-readiness pipeline ```text theme={null} Complementary signals (Holder Wall · Whale Watcher · Coinstellation · Stable Seer · Watchlist) │ ▼ Quantum Intelligence risk engine (signature / custody / dormancy exposure → migration-risk tier) │ ▼ Canonical readiness adapter + model (src/lib/buildStablecoinVaultReadiness.js → src/lib/stablecoin-vault-readiness-model.js) │ ▼ Readiness Packet evidence container (src/lib/buildVaultReadinessPacket.js) │ ▼ Optional attestation / proof references (ML-DSA attestation + ZK/SP1 computation proof) ← additive, not required │ ▼ Stablecoin Vault readiness workflow (src/components/StablecoinVaultPage.jsx → read-only review + Sepolia rehearsal) ``` The same flow as a diagram: ```mermaid theme={null} %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ffffff'}}}%% flowchart TD classDef input fill:#FAFAF0,stroke:#D8C7A4,color:#2b2520; classDef process fill:#BF4E32,stroke:#8F321F,color:#fff4e2; classDef output fill:#4F7D5A,stroke:#355C3F,color:#fff4e2; classDef datastore fill:#7A2F21,stroke:#4F1E15,color:#fff4e2; classDef optional fill:#DDAA33,stroke:#B8860B,color:#2b2520; Signals([Complementary signals\nHolder Wall · Whale Watcher · Coinstellation · Stable Seer · Watchlist]):::input Quantum[Quantum Intelligence\nrisk engine]:::risk Adapter[Readiness adapter + model\nbuildStablecoinVaultReadiness → readiness-model]:::process Packet[Readiness Packet\nbuildVaultReadinessPacket]:::datastore MLDSA[/ML-DSA attestation\nwho signed the evidence?/]:::optional ZK[/ZK / SP1 proof\nwas the computation correct?/]:::optional Vault[Stablecoin Vault workflow\nread-only review + Sepolia rehearsal]:::output Signals --> Quantum --> Adapter --> Packet Packet -.optional.-> MLDSA Packet -.optional.-> ZK MLDSA -.attached refs.-> Vault ZK -.attached refs.-> Vault Packet --> Vault classDef risk fill:#A33A2A,stroke:#6E241B,color:#fff4e2; ``` The dashed edges are deliberate: attestation and proof are **optional**. Removing them leaves a fully functional read-only readiness pipeline. *** ## 4. Layer responsibilities | Layer | Owns | Does **not** own | Canonical home | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | **Complementary signals** | Discovery + raw signals (holders, whales, graph, peg/flows, watchlist). | Verdicts, custody, proofs. | Complementary surfaces + their `/api/*` read paths | | **Quantum Intelligence** | Cryptographic / signature / custody / dormancy exposure → migration-risk tier. | Custody, fund movement, guarantees. | Quantum surfaces + `src/lib/stablecoin-vault-readiness.js` | | **Readiness adapter / model** | Normalizing scattered signals into one canonical `StablecoinVaultReadiness` (recommendation state, score band, risk drivers, boundaries). | I/O, clock reads, Dune execution, invented dollar values. | `src/lib/buildStablecoinVaultReadiness.js`, `src/lib/stablecoin-vault-readiness-model.js` | | **Readiness Packet** | Bounding the readiness result into a self-describing, timestamped evidence container with placeholders for proof / attestation refs. | Signing, proving, custody, on-chain writes. | `src/lib/buildVaultReadinessPacket.js` | | **ML-DSA attestation** | Post-quantum signature over packet evidence: *who attested this?* | Computation correctness, custody. | Public vault research repo (read-only evidence shapes only) | | **ZK / SP1 proof** | Proof that the readiness computation followed the approved ruleset over committed canonical inputs: *was it computed correctly?* | Authenticity of the signer, truth of source data, custody. | Public vault research repo (candidate; not implemented here) | | **Stablecoin Vault workflow** | Read-only review of readiness + safe Sepolia rehearsal of migration. | Custody, deposits, withdrawals, mainnet writes, yield. | `src/components/StablecoinVaultPage.jsx`, `/stablecoin-vault`, `/vault` (Sepolia Simulator) | *** ## 5. ML-DSA vs ZK / SP1 These are **two different layers** that answer **two different questions**. They are **complementary, not replacements**. | | **ML-DSA** | **ZK / SP1** | | -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- | | Question answered | *Who attested or signed this evidence?* | *Was this computation performed correctly under the approved ruleset?* | | Property | **Authenticity / provenance** | **Computation correctness** | | Family | Post-quantum **signature** (FIPS 204 ML-DSA-65) | **Zero-knowledge proof** family; **SP1** is one candidate zkVM proving implementation | | Failure it prevents | A forged or unattributable evidence packet | A readiness result that silently used the wrong inputs or rules | | In the packet | An attestation signature / hash reference | A proof id / hash + input / output commitments | | Status in WalletWall | Read-only research evidence shape (hash-only) | Candidate / feasibility only — **not implemented** in this app | * **ML-DSA** is the **post-quantum attestation / signature layer**. It says nothing about whether the computation was correct — only that a known party stood behind the evidence with a post-quantum signature. * **ZK / SP1** is the **computation-correctness layer**. It says nothing about who signed — only that the published output is the honest result of running the approved ruleset over the committed inputs. * A mature evidence packet can carry **both**: an ML-DSA attestation *and* a ZK/SP1 proof. Neither subsumes the other. **ZK** is the broader proof family. **SP1** is named throughout this document as a *candidate* proving implementation for selected readiness-computation claims, never as a committed dependency. RISC Zero or another proof system could fill the same slot. *** ## 6. Candidate SP1 proof claims These are **examples of safe future claims** a ZK proof (SP1 or otherwise) could make about a *readiness computation*. They are candidates for design discussion, not commitments, and none is implemented: 1. **Readiness tier provenance** — the readiness tier was computed from the canonical inputs under **model version X**. 2. **Vault-candidate threshold** — the `vault_candidate` threshold was evaluated using the **approved rules** in the canonical readiness model. 3. **Quantum-risk derivation** — the quantum-risk tier was derived from the approved exposed-signature / dormancy / balance inputs. 4. **Packet integrity** — the packet summary hash corresponds to the canonical readiness-packet fields. 5. **Recommendation provenance** — the recommendation state was produced by the canonical readiness adapter, not hand-edited. Every claim is about a **computation over committed inputs**. None asserts that the *source data* is globally true, that funds are safe, or that a migration will succeed. *** ## 7. Non-goals and forbidden implications A proof — including a future SP1 proof — has a deliberately narrow meaning. Shipping a proof would **not** mean any of the following, and copy must never imply them: * It would **not** mean WalletWall has custody of any keys, funds, or balances. * It would **not** mean WalletWall protects, secures, or insures funds. * It would **not** mean WalletWall is quantum-proof or quantum-immune. * It would **not** mean WalletWall proves all source / on-chain / Dune data is globally true. A proof binds a computation to *committed inputs*, not to ground truth. * It would **not** mean readiness is guaranteed or that any outcome is assured. * It would **not** mean WalletWall verifies production vault security. * It would **not** mean WalletWall runs on-chain writes. * It would **not** mean users must connect or sign with a wallet to use a readiness surface. A proof raises confidence that a *computation* was done honestly. It changes nothing about custody, protection, guarantees, or the truth of upstream data. *** ## 8. Claim contract template Before any proof is built, the claim it proves must be specified as a non-code **claim contract**. This template is documentation-only; it defines *what* a claim asserts and *what it deliberately does not*, so a prover can be scoped without ambiguity later. | Field | Meaning | | ----------------------------- | ------------------------------------------------------------------------------------ | | **Claim name** | Stable identifier for the claim (e.g. `readiness-tier-provenance`). | | **Model version** | The canonical readiness/model version the claim is bound to. | | **Public inputs** | Inputs revealed in the clear (e.g. chain, model version, tier). | | **Private inputs (if any)** | Inputs intentionally withheld; only their commitment is public. | | **Committed inputs / hashes** | Hash commitments binding the proof to exact inputs. | | **Ruleset** | The approved rules / thresholds the computation must follow. | | **Output** | The asserted result (e.g. recommendation state, score band, tier). | | **Packet reference** | The Readiness Packet the claim describes (type + version). | | **Attestation reference** | The ML-DSA attestation over the evidence, if present. | | **Proof reference** | The proof system + proof id / hash, if present. | | **Verification environment** | Where / how the proof can be re-verified (and its limits). | | **Limitations** | What the claim explicitly does **not** assert (source-data truth, custody, outcome). | The **Limitations** row is mandatory: every claim contract must state its own boundaries so a proof can never be read as more than it is. *** ## 9. Readiness Packet integration The **Readiness Packet** is the single integration point where future proof metadata attaches. The packet already exists and already reserves space for this: today `buildVaultReadinessPacket.js` emits an `evidence` block with **null** `reportHash` / `evidenceHash` placeholders, documented as *"optional placeholders for a future attestation path."* No proof is generated; the slots are simply reserved. A future proof-bearing packet could carry an evidence block shaped like this (documentation sketch, not a schema or code): | Field | Meaning | | -------------------------------- | ----------------------------------------------------------------------------------- | | **proof system** | Which proof family / prover produced the proof (e.g. SP1). | | **proof id / hash** | Identifier or hash of the proof artifact. | | **model version** | The canonical model version the proof is bound to. | | **input commitment** | Hash committing to the exact canonical inputs. | | **output commitment** | Hash committing to the asserted output. | | **verifier reference** | Where / how the proof can be independently verified. | | **attestation signature / hash** | The ML-DSA attestation over the evidence. | | **generatedAt** | Timestamp the packet was produced (never a runtime clock read in the pure builder). | | **limitations** | The claim's explicit boundaries. | Design constraints for this integration point: * The packet stays **pure data**: no signing, no proving, no I/O, no clock reads inside the builder. * Proof / attestation fields are **optional and additive**. A packet with all of them null is the canonical default and remains fully valid. * Hashes follow the repo's existing convention (`0x` + 64 hex), matching `proof-artifact-status.js`. * The app consumes only **local, read-only** evidence shapes. It never imports prover / verifier code, ABIs, or contracts from the public vault research repo, and never fetches them at runtime. *** ## 10. Dune / source-data boundary Dune, on-chain reads, and other source APIs are **evidence sources**. A future proof can prove a *computation over canonical inputs* — it cannot, and must not be sold as, proof that the underlying source data is globally true. * A proof binds the readiness computation to **committed inputs**. If those inputs were stale or wrong, the proof is still "correct" about the computation but says nothing about ground truth. This distinction must stay explicit in every claim contract (see §8 Limitations) and in any UI that surfaces a proof. Existing **Dune guardrails are preserved unchanged** by this architecture: * **No query execution during tests or agent runs.** Execution is fail-closed behind `assertDuneExecutionAllowed` and hard-blocks in CI / test. * **No write / refresh / mutation behavior.** Read-only access only; no surface calls the execute-and-poll path. * **Cached / reduced read paths are preferred** (`readOrCache` / `getOrCache`). See [Dune query guardrails](../operations/dune-query-guardrails.md) and the [Dune vault-readiness scope audit](../audits/dune-vault-readiness-scope.md). This document changes **no** Dune behavior. *** ## 11. Future implementation sequence A sober, gated order. Each step is independent; none implies the next is funded, scheduled, or safe to ship. This reconciles with the staged plan in the [ZK Proof-Artifact Roadmap](../vault/zk-proof-artifact-roadmap.mdx). 1. **Docs / proof architecture** — this document (the map and vocabulary). ✅ here. 2. **Proof claim schema** — formalize the §8 claim contract as a versioned, validated schema (still no prover). 3. **Mock proof artifact in the Readiness Packet** — populate the §9 fields with a *mock* artifact end-to-end, so the integration point is exercised with no real proof. 4. **Proof-system comparison** — evaluate SP1 vs RISC Zero vs alternatives against the stabilized claim contract, if and when a real proof is pursued. ✅ recorded in the [SP1 candidate decision](sp1-candidate-decision.md). 5. **SP1 dev scaffold** — only **after** the claim contract is stable; research scaffold only, gated, off the app runtime path. The dev-only scaffold lives in [`proofs/sp1/`](../../proofs/sp1/README.md) (fixtures + docs; no prover, not wired to the app). To build/run the candidate program locally in a controlled environment, see the [SP1 dev environment runbook](../operations/sp1-dev-environment-runbook.md) — execute-mode only, **not production verification**. 6. **Testnet / demo-only proof integration** — surface a real proof as read-only evidence on testnet / demo only. 7. **No production verifier or custody claims** — production on-chain verification, custody, and mainnet behavior remain out of scope until independently reviewed and explicitly authorized. *** ## 12. Security and trust boundaries The proof-readiness stack does not relax any existing platform boundary: * **Read-only app.** No surface takes custody, holds keys, or moves funds. * **No custody.** WalletWall never holds keys, funds, or stablecoin balances. * **No yield.** No yield, interest, or return, and no return projections. * **No wallet signing.** No readiness surface requires connecting or signing with a wallet; the vault surface is a read-only Sepolia rehearsal, never mainnet. * **No guarantees.** Readiness signals are research heuristics; a proof raises confidence in a computation, not in an outcome. * **Model-versioning required.** Every proof / packet binds to a canonical model version, so a claim is always interpretable against the exact rules it used. * **Provenance vs. attestation separation.** *Who signed* (ML-DSA) and *what was computed correctly* (ZK/SP1) stay distinct fields; one is never presented as the other. * **Proof verification limitations.** A verified proof attests to a computation over committed inputs only — never to source-data truth, custody, protection, or a guaranteed outcome. *** ## 13. Open questions These are intentionally unresolved and should be settled before any prover work: 1. **Which proof claim should be first?** The §6 candidates differ sharply in value and difficulty — which earns the first design pass? 2. **What inputs should remain private?** Which canonical inputs are sensitive enough to commit-and-withhold rather than reveal? 3. **What should be public / committed?** What is the minimal set of public inputs and commitments that makes a claim independently meaningful? 4. **Is SP1 the right prover vs alternatives?** SP1, RISC Zero, or another system — decided against the stabilized claim contract, not before it. 5. **Where should proof artifacts live in the UI?** How is a read-only proof reference surfaced without implying custody, protection, or a guarantee? 6. **How do we avoid proving stale or unaudited source data?** How do freshness and provenance of the *inputs* get represented so a proof is never mistaken for a truth claim about the source? *** *This document is architecture and documentation only. It introduces no prover, verifier, circuit, or contract code, no runtime behavior change, and no Dune behavior change. SP1 is a candidate implementation for selected readiness-computation proofs; the Readiness Packet is the integration point where future proof artifacts attach.*