​

Architecture Decision: SP1 as a Candidate Proving Stack

Scope. This document is an architecture decision record only. It evaluates SP1 as a candidate proving stack for WalletWall’s readiness-computation claims and records the decision to use it for a dev-only scaffold — nothing more. It adds no prover, verifier, circuit, program, or contract code, changes no runtime behavior, and changes no Dune behavior. WalletWall remains proof-ready, not SP1-dependent: every readiness surface works today with no prover in the loop.

Status: Accepted — candidate selection, dev-only. This decision selects an initial candidate and authorizes a research scaffold. It does not commit WalletWall to SP1 in production and does not authorize a production prover or verifier. Date: 2026-06-23 Supersedes / advances: Resolves open questions #1 (“which proof claim should be first?”) and #4 (“is SP1 the right prover vs alternatives?”) from the Proof-Readiness Architecture, and executes step 4 (“proof-system comparison”) and authorizes step 5 (“SP1 dev scaffold”) of its §11 implementation sequence. See also:

• Proof-Readiness Architecture — the pipeline, the ML-DSA vs ZK/SP1 distinction, and the claim-contract template this decision builds on.
• Proof Claim Schema — the versioned, validated schema (src/lib/proof-claim-schema.js) that the first claim must map onto.
• Vault-first positioning — canonical thesis and copy red-lines.
• Complementary feature alignment — per-surface jobs and Phase 0–4 roadmap.
• ZK Proof-Artifact Roadmap — staged, non-production ZK/SP1 next steps.
• Dune query guardrails — read-only / cache-only Dune posture (unchanged by this decision).

---

​

1. Context

WalletWall is organized as a two-tier product hierarchy with Stablecoin Vault (the vault-readiness workflow and evidence destination) and Quantum Intelligence (the cryptographic exposure and migration-risk engine) as the primary surfaces. The Readiness Packet (src/lib/buildVaultReadinessPacket.js) is the evidence/proof attachment container, and the proof claim schema (src/lib/proof-claim-schema.js) is the stable, versioned interface a future proof artifact must take. Today the proof layer is schema-only. The schema already names SP1 as a candidate proof system (sp1_candidate) alongside a prover-agnostic zk_candidate key, and it already enforces that a candidate system can never report verificationStatus = "verified". What the architecture has not yet recorded is a decision: which proving stack to evaluate first, and which readiness computation should be the first claim. This document makes that decision. It is the natural next step after the proof-readiness map and the proof claim schema, and a prerequisite for the dev-only scaffold that follows. The app is read-only throughout: no surface takes custody, holds keys, moves funds, or asks a user to connect or sign with a wallet.

---

​

2. Decision

1. SP1 is selected as the initial candidate proving implementation for selected computation-correctness proofs over WalletWall readiness computations. “Candidate” is deliberate: SP1 is one option inside the broader ZK proof family, not a committed dependency. SP1 is not implemented in this app.
2. WalletWall remains proof-ready, not SP1-dependent. A proof system is an optional, additive layer. Removing it leaves a fully functional read-only readiness pipeline. This decision changes nothing about what WalletWall is.
3. The first proof target is a dev-only readiness-computation claim, not production verification. The first claim is readiness_score_v1 (see §6).
4. The schema stays generic enough to support alternatives. The zk_candidate key and the prover-agnostic claim contract are preserved so RISC Zero or another zkVM can fill the same slot without a schema rewrite.
5. No production verification claim is exposed, and nothing is wired to the live user flow beyond the existing mock proof-artifact path on the Readiness Packet.

---

​

3. Options considered

SP1 and RISC Zero are close. SP1 is chosen as the first candidate to scaffold because its “prove a plain Rust program” model maps cleanly onto deterministic readiness rules, its tooling and local-dev story are well documented, and its verifier story is explicit. The decision is intentionally reversible: option B remains a first-class alternative, and the claim contract is prover-agnostic by design.

---

​

4. Evaluation against WalletWall criteria

Scored for the initial dev-only scaffold, not for production. “Good” means favorable for a small, isolated, off-runtime research scaffold. The two zkVMs are near-equivalent against these criteria. The deciding factors for choosing SP1 first are pragmatic: clean mapping of deterministic readiness rules to a Rust program, a well-documented local-dev path, and an explicit verifier story — all of which make a low-cost, isolated scaffold straightforward.

---

​

5. Recommendation

• Use SP1 as the initial candidate for a dev-only scaffold that exercises the proof claim schema and the Readiness Packet integration point with deterministic fixtures — no real proving.
• Keep the schema generic enough to support alternatives (RISC Zero via zk_candidate); do not hard-code SP1 assumptions into the claim contract.
• Do not expose any production verification claim. Candidate proof systems remain unsupported / pending and can never be marked verified (enforced by validateProofClaim).
• Do not wire SP1 into the live user flow beyond the existing mock proof-artifact path already supported on the Readiness Packet (proofExtension).
• Compare SP1 against alternatives again — against the stabilized claim contract — before any production proof verification is pursued.

---

​

6. First candidate proof claim: readiness_score_v1

The first claim to scaffold is readiness_score_v1 — a CLAIM_TYPE_KEYS value already defined in the schema. It is the simplest high-value claim: it asserts that a readiness score was computed correctly under the canonical model version, over committed inputs. (adapter_recommendation_v1 is the natural second claim and a viable alternative first claim; readiness_score_v1 is chosen for its directness.) The claim is specified against the §8 claim-contract template of the proof-readiness architecture and maps field-for-field onto createProofClaim in the schema: What a readiness_score_v1 proof would and would not mean:

• Would mean: “the published score is the honest result of running the approved scoring ruleset over the exact committed inputs, under the stated model version.”
• Would not mean: that the inputs themselves (Dune / on-chain reads) are globally true, that the score guarantees any outcome, or that anything about custody, protection, or a wallet changed. A proof makes a computation auditable; it does not turn a research heuristic into a guarantee.

---

​

7. Relationship to ML-DSA and ZK / SP1

This decision does not collapse the two proof-adjacent layers. They answer different questions and are complementary, not a replacement for each other:

• ML-DSA (mldsa_attestation) is the post-quantum attestation / signature layer. It answers who attested or signed this evidence? — authenticity / provenance. It says nothing about whether a computation was correct. It remains the attestation layer and is unaffected by this decision.
• ZK / SP1 is the computation-correctness layer. It answers was this computation performed correctly under the approved ruleset? It says nothing about who signed. ZK is the broader proof family; SP1 is one candidate zkVM proving implementation inside it.

A mature evidence packet can carry both an ML-DSA attestation and a ZK/SP1 proof; neither subsumes the other. The Readiness Packet is the single integration point where both attach. Its builder already reserves additive, optional space for proof metadata via the proofExtension block (present only when proof claims are passed; absent by default, so base packet behavior is unchanged). A future SP1 proof would surface here as a ProofClaim with proofSystem: sp1_candidate — never replacing the packet, only annotating it.

---

​

8. Consequences and next steps

• Immediate (this decision): records SP1 as the initial candidate and authorizes a dev-only scaffold. No code behavior changes.
• Next (the scaffold PR): add an isolated, dev-only proofs/sp1/ scaffold — README + a readiness_score_v1 claim fixture + deterministic input/output fixtures — that maps to the proof claim schema and documents how a future prover’s output would attach to the Readiness Packet proofExtension. The scaffold adds no SP1 dependency to the app bundle, runs no proving in CI or app startup, and is not imported by any app entrypoint.
• Later (gated, not authorized here): a proof-system re-comparison against the stabilized claim contract, then — only if and when independently reviewed and explicitly authorized — a real SP1 dev program, and (separately) any testnet/demo-only proof surfacing. Production on-chain verification remains out of scope.

This decision is reversible. If a re-comparison favors RISC Zero or another stack, the prover-agnostic claim contract and zk_candidate key absorb the change without a schema rewrite.

---

​

9. Non-goals

This decision and the scaffold it authorizes deliberately do not, and copy must never imply that they do:

• Implement an SP1 prover or verifier, a ZK circuit, a program, or a proving key.
• Provide production on-chain verification of any proof in a live environment.
• Copy contracts, ABIs, or implementation details from the public vault research repo.
• Add custody of funds, deposits, withdrawals, pooling, staking, yield, fund movement, wallet connection, signing, or on-chain writes in any environment.
• Mean WalletWall is quantum-proof or quantum-immune, or that funds are protected, secured, or insured.
• Replace the ML-DSA attestation layer, or present a computation proof as an authenticity signature (or vice-versa).
• Prove that Dune, on-chain, or any external source data is globally true. A proof binds a computation to committed inputs, not to ground truth.
• Guarantee readiness, safety, protection, or any specific outcome.

---

​

10. Trust boundaries

The decision relaxes no existing platform boundary:

• Read-only app. No custody. WalletWall never holds keys, funds, or stablecoin balances, and never moves funds.
• No yield. No yield, interest, or return, and no return projections.
• No on-chain writes. 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 guarantee. Readiness signals are research heuristics; a proof raises confidence in a computation, not in an outcome, and is never insured custody or production custody.
• Model-versioning required. Every claim binds to a canonical model version so it is interpretable against the exact rules it used.
• No Dune behavior change. No Dune queries are executed, scheduled, refreshed, or modified; existing read-only / cache-only Dune guardrails are preserved unchanged.

---

​

11. Open questions

Intentionally unresolved; to be settled before any prover work beyond the scaffold:

1. Private inputs. Which canonical inputs (if any) are sensitive enough to commit-and-withhold rather than reveal in a later claim version?
2. Public / committed minimal set. What is the smallest set of public inputs and commitments that makes readiness_score_v1 independently meaningful?
3. Re-comparison trigger. What concrete signal (funding, a partner, a demo) should trigger the SP1-vs-alternatives re-comparison against the stabilized claim contract?
4. Input freshness. How are freshness and provenance of the inputs represented so a proof is never mistaken for a truth claim about the source data?
5. UI surfacing. How is a read-only proof reference surfaced without implying custody, protection, or a guarantee?

---

This document is an architecture decision record only. It introduces no prover, verifier, circuit, program, or contract code, no runtime behavior change, and no Dune behavior change. SP1 is selected as a candidate implementation for a dev-only scaffold of selected readiness-computation proofs; WalletWall remains proof-ready, not SP1-dependent, and the Readiness Packet is the integration point where any future proof artifact attaches.