SP1 dev environment runbook

Version: 2026-06-23 · Status: Active · dev-only research runbook Companion docs:

SP1 dev scaffold overview (fixtures, claims, programs) — in the private research scaffold
SP1 candidate decision — why SP1 is a candidate (not committed) proving stack
Proof-readiness architecture — how a proof would attach to the Readiness Packet
Proof claim schema — the ProofClaim shape and proofExtension integration point
ZK proof-artifact roadmap — staged, non-production ZK/SP1 next steps

The read-only Dune contract this runbook does not change is maintained as internal engineering documentation.

1. Purpose

This runbook documents how to stand up a controlled, reproducible developer environment to build and run the dev-only SP1 candidate program for readiness_score_v1, and how to compare its execute-mode output against the deterministic execute-output fixture already committed in the private research scaffold. SP1 is a candidate proof system in WalletWall. WalletWall is proof-ready, not SP1-dependent — every readiness surface works today with no prover in the loop. A previous local validation attempt (2026-06-23) could not run the host script because Rust, Cargo, and the SP1 toolchain were not installed in the agent environment (rustc/cargo/rustup returned command-not-found, exit 127). This runbook exists so a developer with a controlled Linux/WSL/macOS environment can install the toolchain, run the execute-mode host, and — only on success — update the fixture’s metadata honestly.

This runbook is documentation only. It adds no SP1 runtime code, no proof generation to CI, and changes no app, Dune, or runtime behavior.

Workflow at a glance

Execute mode never generates a proof. A canonical-value mismatch is investigated, not silently rewritten — see Compare against the fixture below.

2. Scope

In scope:

Installing Rust (via rustup) and the Succinct SP1 toolchain in a controlled dev environment.
Verifying the toolchain is on PATH.
Building the dev-only SP1 zkVM guest program in the private research scaffold.
Running the dev-only execute-mode host in the private research scaffold.
Comparing the execute-mode output against the committed deterministic fixture.
Updating only the metadata of the execute-output fixture after a successful local run.

3. Non-goals

This runbook does not:

Generate a ZK proof, proving key, or verifier key. Execute mode runs the guest in a RISC-V emulator and produces no proof. This is not production verification.
Add SP1 to CI, default npm test, npm run lint, or npm run build. Proof generation and Rust compilation never run in default CI.
Add an SP1 dependency to the root app package.json or any JS/Vite bundle.
Import Rust/SP1 code into the Vite/browser runtime or any app entrypoint.
Add custody, yield, wallet signing, deposits, withdrawals, pooling, staking, or any on-chain write behavior.
Execute, refresh, mutate, or add any Dune query, or change any Dune behavior.
Claim WalletWall is ZK-secured, quantum-proof, guaranteed, insured, or production custody.

4. Prerequisites

A POSIX-style shell (Linux, macOS, or WSL2). See §5.
git, curl, and a C toolchain (build-essential / Xcode CLT) for native builds.
Disk: the SP1 toolchain and a target/ build directory can consume several GB.
Network access to fetch the Rust and SP1 toolchains (one-time install).
No WalletWall secrets, .env, Dune API key, or wallet material is needed or used.

Rust and SP1 are not required for normal WalletWall development. The JS test suite, lint, build, and the existing SP1 fixtures/tests all run without any Rust toolchain. Install the toolchain only when you specifically intend to run the SP1 execute path.

Recommended environment

Prefer, in order:

WSL2 Ubuntu (recommended on Windows) — a real Linux userland; the SP1 installer and cargo prove work as documented upstream.
GitHub Codespaces / a Linux devcontainer — disposable, reproducible, and isolated from your host.
Linux or macOS local shell — native bash/zsh.

The SP1 guest targets riscv32im-succinct-zkvm-elf and the SP1 installer is written for Linux/macOS shells. A Linux-style environment avoids the most common toolchain friction.Windows guidanceNative Windows PowerShell without Rust/SP1 on PATH will fail — this is exactly what the previous local validation attempt documented (rustc/cargo/rustup → command-not-found, exit 127). The SP1 installer (curl -L https://sp1.succinct.xyz | bash) expects a POSIX shell.On Windows, use WSL2 Ubuntu:

# In Windows PowerShell (one-time), install WSL2 + Ubuntu, then reboot if prompted:
wsl --install -d Ubuntu
# Afterwards, open the "Ubuntu" shell and run all steps below inside WSL.

Clone or access the repo from inside the WSL filesystem (or work against your existing checkout under /mnt/c/..., accepting slower I/O). Run every command in this runbook from the Ubuntu/WSL shell, not PowerShell.WSL / Codespaces guidanceInside WSL2 Ubuntu or a Codespace/devcontainer, ensure the base build tools are present:

sudo apt-get update
sudo apt-get install -y build-essential curl git pkg-config libssl-dev

Then follow §6 onward. A Codespace is a clean, throwaway environment, so it is the lowest-risk place to install the toolchain.

Install Rust

Install Rust with rustup (the official installer), then load it into the current shell:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Accept the default install, then:
source "$HOME/.cargo/env"

See rustup.rs for the canonical, up-to-date instructions.

Install SP1 tooling

Use the current Succinct SP1 installation instructions. As of this writing the documented flow is:

curl -L https://sp1.succinct.xyz | bash
# Restart your shell or source your profile, then:
sp1up

sp1up installs the SP1 toolchain, including cargo prove. The exact installer URL and command names are owned by Succinct and may change between SP1 versions — always defer to the current Succinct SP1 docs rather than to a pinned copy here. The SP1 install is optional and is not part of normal WalletWall development.

Verify the toolchain

Confirm each tool resolves on PATH before building:

rustc --version      # e.g. rustc 1.x.x
cargo --version      # e.g. cargo 1.x.x
rustup --version     # e.g. rustup 1.x.x
cargo prove --version   # confirms the SP1 toolchain is installed

If any of these return command not found, stop and re-check §6 / §7. This is the failure mode the previous validation attempt hit.

Build / check the guest program

The SP1 zkVM guest uses #![no_main] and the sp1-zkvm runtime, so it must be built with cargo prove build (not plain cargo build):

cd <SP1 guest program dir>   # in the private research scaffold
cargo prove build
# → the compiled guest ELF under the crate's target/ build directory

If your installed SP1 version names the build step differently, run cargo prove --help and follow the installed CLI; update this runbook if the SP1 CLI surface has changed.

The native stand-in guest crate (no sp1-zkvm dependency) builds with ordinary cargo build / cargo test and is useful for checking the scoring logic without the SP1 toolchain. It is a sibling experiment, not a substitute for the SP1 guest.

Run the execute-mode host

The host script loads the compiled guest ELF, feeds it the canonical fixture signals, and runs the guest in execute mode — a fast RISC-V emulator that returns public output values without generating a proof:

cd <execute-mode host script dir>   # in the private research scaffold
cargo run

Command names may vary by SP1 version; if cargo run does not behave as documented, follow the installed SP1 CLI help and update this runbook accordingly. Execute mode is intentional: proof generation (client.prove()) is gated and out of scope for this runbook.

Check the expected canonical output

For the canonical fixture signals (sig=0.91, dorm=0.4, bal=0.72), the execute-mode host must print these values:

Field	Expected value
`score`	`65`
`scoreBand`	`elevated`
`recommendationState`	`migrate`
`cycles (execute)`	a non-zero cycle count (informational)

The reconstructed output JSON is {"recommendationState":"migrate","score":65,"scoreBand":"elevated"}.Commitments (must be unchanged from the canonical fixture):

outputCommitment: 0x39b6eef94782ccd26f33a41be397308adcdc8242fcf4fd0dfb884ca260545032
inputCommitment: 0x7044bbbeb4bb043f3917caf8f6641475b0a0c5599f33bff136f8582b72529bef

The outputCommitment is sha256(stableStringify({ recommendationState, score, scoreBand })) and the inputCommitment is sha256(stableStringify(committedInputs)) — sha256 hashes over the committed fixture content, not ZK commitments.

How to compare against the fixture

Compare the printed score / scoreBand / recommendationState against the committed execute-output fixture in the private research scaffold:

# From the repo root, after running the host script, inspect the committed
# execute-output fixture in the private research scaffold and confirm:
#   score == 65, scoreBand == "elevated", recommendationState == "migrate",
#   inputCommitment / outputCommitment unchanged.

The fixture’s structure and commitment integrity are already guarded by automated fixture-integrity tests that run without Rust or SP1 (node --test). Run them after any fixture edit:

node --test <fixture-integrity tests>   # in the private research scaffold

If the live output does not match (score/band/recommendation differ), do not edit the fixture’s canonical values to match your run. A mismatch means either the SP1 version, the guest logic, or the canonical scoring model has drifted — investigate that first. The commitments must change only when a real execute confirms a genuinely different canonical value, and any such change must be reviewed.

How to update fixture metadata after success

Only after a successful local execute run that matches the expected output, update the metadata of the committed execute-output fixture.Allowed metadata updates:

validationStatus → "locally_executed"
toolchainStatus.rust / .cargo / .sp1Toolchain → the observed version strings (e.g. "available 1.x.x")
localValidationAttempt → record the commands run, the environment, and the result
the cycle count, if produced
a timestamp of the validation

Must remain unchanged:

proofSystem: "sp1_candidate"
verificationStatus is not "verified" (execute mode produces no proof; SP1 is a candidate system only)
artifactType: "sp1_execute_output"
the dev-only / candidate-only limitations (no production verification, no custody, no yield, no guarantee, etc.)
the canonical score / scoreBand / recommendationState and the inputCommitment / outputCommitment (unless a reviewed real-execute change applies)

This is still not production verification. A locally_executed status means the execute-mode I/O was confirmed locally — it does not mean a proof exists, was verified, or that any production guarantee applies.

14. What not to commit

Never commit build artifacts, caches, or secrets produced by this workflow:

target/ (any Rust/Cargo build directory) — excluded by each crate’s .gitignore.
Cargo.lock — the SP1 crates are dev-only and not committed per their crate-local .gitignore; do not add a Cargo.lock for them.
Compiled guest ELF binaries (*.elf) and any proof blobs.
Generated dependency folders and build caches (.cargo registry caches, ~/.sp1, etc.).
Private keys, proving keys, or verifier keys.
Wallet data, seed phrases, or any key material.
.env files or any secret-bearing configuration.
Dune outputs from paid/credit-consuming execution — this workflow never touches Dune.
Any large binary artifact.

The execute-output fixture (a small JSON file) is the only artifact this workflow may add or update under version control.

15. Troubleshooting

rustc / cargo / rustup: command not found (exit 127)

Likely cause: Rust not installed / not on PATH.Fix: Run §6; source "$HOME/.cargo/env"; reopen the shell.

cargo prove: no such subcommand

Likely cause: SP1 toolchain not installed.Fix: Run §7 (sp1up); verify with cargo prove --version.

Installer script fails on Windows PowerShell

Likely cause: SP1 installer expects a POSIX shell.Fix: Use WSL2 Ubuntu (§5.1).

cargo prove build fails on the riscv32im-succinct-zkvm-elf target

Likely cause: SP1 toolchain incomplete or version mismatch.Fix: Re-run sp1up; ensure sp1-zkvm / sp1-sdk versions match the installed toolchain.

Linker / openssl build errors

Likely cause: Missing system build deps.Fix: Install build-essential pkg-config libssl-dev (§5.2).

Output score/band differs from fixture

Likely cause: Version or logic drift.Fix: Investigate; do not silently rewrite canonical fixture values (§12).

16. Rollback / cleanup

This workflow is fully reversible and leaves nothing behind in the app.

Remove local build artifacts

Safe — they are gitignored:

# Remove local build artifacts (safe — they are gitignored):
cd <SP1 guest program dir> && cargo clean          # in the private research scaffold
cd <execute-mode host script dir> && cargo clean

Optionally remove the toolchains entirely

# Optionally remove the toolchains entirely:
rustup self uninstall          # removes Rust + cargo
rm -rf "$HOME/.sp1"            # removes the SP1 toolchain (path may vary by version)

Discard fixture metadata edits (optional)

If you edited the fixture metadata and want to discard it, git checkout on the committed execute-output fixture restores the committed version. No app, CI, or Dune state is affected by any step in this runbook.

17. Safety boundaries

This runbook and the SP1 dev scaffold are dev-only research and add no product capability. They do not:

constitute or imply production verification — execute mode generates no proof, and SP1 is a candidate proof system only;
mark any claim verified — the proof claim schema forbids verified for candidate systems until an independently reviewed production verifier is explicitly authorized;
add no custody, deposits, withdrawals, pooling, staking, no yield, fund movement, no wallet signing, wallet connection, or on-chain writes in any environment;
run SP1 / Rust / proof generation in default CI, npm test, npm run lint, or npm run build;
add SP1 dependencies to the root app package.json or import the SP1 dev scaffold into the app runtime;
execute, refresh, mutate, or add any Dune query, or change any Dune behavior;
guarantee migration safety or the freshness/global truth of any source data;
claim WalletWall is ZK-secured, quantum-proof, guaranteed, or insured.

WalletWall remains read-only, non-custodial intelligence and vault-readiness prioritization — not asset protection, custody, or a production proof system.

Operations & Runbooks

Documentation

SP1 dev environment runbook

SP1 dev environment runbook

1. Purpose

Workflow at a glance

2. Scope

3. Non-goals

4. Prerequisites

14. What not to commit

15. Troubleshooting

16. Rollback / cleanup

17. Safety boundaries

​SP1 dev environment runbook

​1. Purpose

​Workflow at a glance

​2. Scope

​3. Non-goals

​4. Prerequisites

​14. What not to commit

​15. Troubleshooting

​16. Rollback / cleanup

​17. Safety boundaries

SP1 dev environment runbook

1. Purpose

Workflow at a glance

2. Scope

3. Non-goals

4. Prerequisites

14. What not to commit

15. Troubleshooting

16. Rollback / cleanup

17. Safety boundaries