> ## 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. # Sp1 candidate decision # 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](proof-readiness-stack.md), and executes step 4 ("proof-system comparison") and authorizes step 5 ("SP1 dev scaffold") of its §11 implementation sequence. See also: * [Proof-Readiness Architecture](proof-readiness-stack.md) — the pipeline, the ML-DSA vs ZK/SP1 distinction, and the claim-contract template this decision builds on. * [Proof Claim Schema](proof-claim-schema.md) — the versioned, validated schema (`src/lib/proof-claim-schema.js`) that the first claim must map onto. * [Vault-first positioning](../product/vault-first-positioning.md) — canonical thesis and copy red-lines. * [Complementary feature alignment](../product/complementary-feature-alignment.md) — per-surface jobs and Phase 0–4 roadmap. * [ZK Proof-Artifact Roadmap](../vault/zk-proof-artifact-roadmap.mdx) — staged, non-production ZK/SP1 next steps. * [Dune query guardrails](../operations/dune-query-guardrails.md) — 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](proof-readiness-stack.md) (`src/lib/buildVaultReadinessPacket.js`) is the evidence/proof attachment container, and the [proof claim schema](proof-claim-schema.md) (`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 | Option | Summary | Outcome | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **A. SP1** | A RISC-V zkVM (succinct, well-documented Rust tooling) that proves correct execution of an ordinary Rust program. Map a readiness rule to a Rust program; the proof attests the program ran correctly over committed inputs. | **Selected** as the initial *candidate* for a dev-only scaffold. | | **B. RISC Zero** | Another mature RISC-V zkVM with comparable "prove a Rust program" ergonomics. A strong alternative occupying the same architectural slot. | Kept as a first-class alternative behind the prover-agnostic `zk_candidate` key. Re-compare before any production proof. | | **C. No prover yet / defer** | Stay schema-only; build no scaffold until a production need is funded and authorized. | Rejected for *now* only — a tiny, isolated dev scaffold de-risks the integration point cheaply without committing to production. The schema-only posture remains the production default. | | **D. Generic ZK proof-layer abstraction** | Define a prover-agnostic proof-layer abstraction first, implement no concrete prover. | Partially adopted: the schema already provides the prover-agnostic abstraction (`zk_candidate`, claim contract). A *separate* abstraction layer is unnecessary overhead at this stage. | 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. | Criterion | SP1 | RISC Zero | Defer | Generic abstraction | | -------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------- | -------------------------------- | ---------------------------------- | | **Rust / program ergonomics** | Good — prove a plain Rust program | Good — comparable Rust zkVM | n/a | n/a (no prover) | | **Proof claim schema compatibility** | Good — maps to `sp1_candidate` + proof reference fields | Good — maps to `zk_candidate` | Good — schema already exists | Good — schema *is* the abstraction | | **Browser / app integration complexity** | Low *for the scaffold* — kept entirely off the app/runtime path | Low — same | None | None | | **CI / runtime cost** | Controlled — no proving runs in default CI or app startup; scaffold is fixtures + docs | Controlled — same posture | None | None | | **Local dev feasibility** | Good — documented local toolchain; scaffold uses deterministic fixtures, not live proving | Good — comparable | n/a | n/a | | **Verifier story** | Explicit — clear separation of prove vs verify; production verification stays out of scope | Explicit — comparable | n/a | n/a | | **Auditability** | Good — committed inputs / outputs + model version make a claim independently interpretable | Good | n/a | Good | | **Avoiding production overclaims** | Strong — schema forbids `verified` for candidate systems | Strong — same | Strongest — nothing to overclaim | Strong | | **No-custody / no-write boundary preservation** | Preserved — no custody, signing, or on-chain write is introduced | Preserved | Preserved | Preserved | | **Model-versioning support** | Good — claim binds to a canonical model + ruleset version | Good | n/a | Good | | **Ability to prove deterministic readiness rules** | Good — readiness rules are deterministic functions of committed inputs | Good | n/a | n/a | 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: | Field | Value for `readiness_score_v1` | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Claim name / type** | `readiness_score_v1` | | **Model version** | the canonical readiness model version the score was computed under (illustrative label `stablecoin-vault-readiness-model.v1`; the model module is the source of truth) | | **Ruleset version** | the score-band ruleset version (illustrative label `vault-score-bands.v1`) | | **Public inputs** | chain, stablecoin symbol, model version, ruleset version, packet type/version, and the asserted score band (revealed in the clear) | | **Private inputs (if any)** | none required for this first claim; a future claim *may* commit-and-withhold sensitive raw signals, exposing only their hash commitment | | **Input commitment** | a `0x`+64-hex hash committing to the canonical input set the computation consumed | | **Output commitment** | a `0x`+64-hex hash committing to the asserted output | | **Expected output** | the readiness `score` (0–100), its `scoreBand` (`low`/`moderate`/`elevated`/`candidate`), and the mapped `recommendationState` (e.g. `vault_candidate`) | | **Packet reference** | the Readiness Packet (`packetType` `walletwall.stablecoin-vault-readiness-packet`, `packetVersion` `v1`) the claim describes | | **Proof reference** | proof system `sp1_candidate` + proof id / hash (absent until a real proof exists) | | **Verification environment** | none in production; a future scaffold could re-check a proof off-runtime, on testnet/dev only | | **Limitations** | binds a computation to committed inputs only; asserts nothing about source-data truth, custody, protection, or outcome (see §9) | 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.*