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.

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).

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

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: 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:

Readiness tier provenance — the readiness tier was computed from the canonical inputs under model version X.
Vault-candidate threshold — the vault_candidate threshold was evaluated using the approved rules in the canonical readiness model.
Quantum-risk derivation — the quantum-risk tier was derived from the approved exposed-signature / dormancy / balance inputs.
Packet integrity — the packet summary hash corresponds to the canonical readiness-packet fields.
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 and the Dune vault-readiness scope audit. 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.

Docs / proof architecture — this document (the map and vocabulary). ✅ here.
Proof claim schema — formalize the §8 claim contract as a versioned, validated schema (still no prover).
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.
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 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/ (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 — execute-mode only, not production verification.
Testnet / demo-only proof integration — surface a real proof as read-only evidence on testnet / demo only.
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:

Which proof claim should be first? The §6 candidates differ sharply in value and difficulty — which earns the first design pass?
What inputs should remain private? Which canonical inputs are sensitive enough to commit-and-withhold rather than reveal?
What should be public / committed? What is the minimal set of public inputs and commitments that makes a claim independently meaningful?
Is SP1 the right prover vs alternatives? SP1, RISC Zero, or another system — decided against the stabilized claim contract, not before it.
Where should proof artifacts live in the UI? How is a read-only proof reference surfaced without implying custody, protection, or a guarantee?
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.

​WalletWall Proof-Readiness Architecture

​1. Executive summary

​2. Current product hierarchy

​3. Proof-readiness pipeline

​4. Layer responsibilities

​5. ML-DSA vs ZK / SP1

​6. Candidate SP1 proof claims

​7. Non-goals and forbidden implications

​8. Claim contract template

​9. Readiness Packet integration

​10. Dune / source-data boundary

​11. Future implementation sequence

​12. Security and trust boundaries

​13. Open questions