> ## 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 claim schema

# WalletWall Proof Claim Schema

> **Scope.** This document defines the `proof-claim-schema.js` — the
> application-level typed schema for future proof artifacts. It introduces no
> prover, verifier, circuit, or contract code, changes no runtime behavior, and
> changes no Dune behavior. It is the natural next step after the proof-readiness
> architecture map (`proof-readiness-stack.md`).

See also:

* [Proof-Readiness Architecture](proof-readiness-stack.md) — the pipeline,
  ML-DSA vs ZK/SP1 distinction, and the claim-contract template this schema
  implements.
* [Vault-first positioning](../product/vault-first-positioning.md) — canonical
  thesis and copy red-lines.
* [Complementary feature alignment](../product/complementary-feature-alignment.md) — 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 schema).

***

## 1. Purpose

The proof claim schema is the **stable, versioned interface** between the
readiness pipeline and any future proof or attestation system. It answers the
question:

> *If a future ZK or attestation layer were to produce a claim about a readiness
> computation, what shape should that claim take — and what must it explicitly
> disclaim?*

It is defined now, before any prover is built, so the app has a typed
integration point and the proof system design can be scoped against a stable
target rather than invented ad hoc.

***

## 2. Schema file

```text theme={null}
src/lib/proof-claim-schema.js
```

Pure data + pure helpers only. No I/O, no Dune execution, no clock reads, no
prover or verifier code.

***

## 3. Claim types

Each claim type describes a specific **readiness computation** that a future
proof could assert was performed correctly. The claim type does not imply the
proof exists; it is the target specification.

| Claim type key                 | Layer                | What it asserts                                                                                  |
| ------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------ |
| `readiness_score_v1`           | Readiness adapter    | The readiness score was computed under the canonical model version.                              |
| `vault_candidate_threshold_v1` | Readiness model      | The `vault_candidate` threshold was evaluated using the approved rules.                          |
| `quantum_risk_tier_v1`         | Quantum Intelligence | The quantum-risk tier was derived from approved exposed-signature / dormancy / balance inputs.   |
| `packet_integrity_v1`          | Readiness Packet     | The packet summary hash corresponds to the canonical Readiness Packet fields at generation time. |
| `adapter_recommendation_v1`    | Readiness adapter    | The recommendation state was produced by the canonical adapter, not modified post-generation.    |

Every claim type asserts something about a **computation over committed inputs**.
None asserts that the source data is globally true, that funds are safe, or that
readiness is guaranteed.

***

## 4. Proof systems

The schema defines six proof-system keys. The `_candidate` suffix signals a
future design option, not a committed or implemented dependency.

| Proof system key       | Type             | Question answered                                        |
| ---------------------- | ---------------- | -------------------------------------------------------- |
| `none`                 | —                | No proof attached; schema only.                          |
| `mock`                 | Dev/test fixture | Deterministic mock for tests; not a real proof.          |
| `sp1_candidate`        | ZK (candidate)   | Was this computation correct under the approved ruleset? |
| `zk_candidate`         | ZK (candidate)   | Was this computation correct under the approved ruleset? |
| `mldsa_attestation`    | Attestation      | Who attested or signed this evidence?                    |
| `external_attestation` | Attestation      | Who attested or signed this evidence?                    |

***

## 5. ML-DSA vs ZK/SP1

These two systems answer **different questions** and are **complementary, not a replacement for each other**. See the [proof-readiness architecture](proof-readiness-stack.md) for the full treatment.

|                      | **ML-DSA** (`mldsa_attestation`)                        | **ZK / SP1** (`sp1_candidate`, `zk_candidate`)                         |
| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
| Question             | *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             |
| Status in WalletWall | Read-only evidence shape (hash-only, public vault repo) | Candidate / feasibility — **not implemented** in this app              |
| `isAttestation` flag | `true`                                                  | `false`                                                                |
| `isCandidate` flag   | `false`                                                 | `true`                                                                 |

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 here as a *candidate*
proving implementation for selected readiness-computation claims — one option,
not the architecture itself.

***

## 6. Verification status

The verification status is **fail-closed**: the default is `not_applicable`
rather than `verified`.

| Status key       | Meaning                                                                 |
| ---------------- | ----------------------------------------------------------------------- |
| `not_applicable` | No proof system attached; verification does not apply.                  |
| `pending`        | A proof system is intended but proof generation has not completed.      |
| `attached`       | A proof is attached but not yet independently verified.                 |
| `verified`       | A proof was independently verified under the stated system.             |
| `failed`         | Verification was attempted and failed.                                  |
| `unsupported`    | The proof system is a candidate only; verification is not yet possible. |

Candidate proof systems (`sp1_candidate`, `zk_candidate`) are always
`unsupported` by default and **cannot** be marked `verified` until a production
verifier is implemented and explicitly authorized.

***

## 7. How it attaches to the Readiness Packet

The **Readiness Packet** (`buildVaultReadinessPacket.js`) is the single
integration point where proof metadata attaches. The architecture is additive:

```text theme={null}
Readiness Packet
  └── proofExtension (optional — present only when proofClaims passed)
        ├── proofClaims: ProofClaim[]
        ├── proofLimitations: string[]   ← mandatory limitations from schema
        └── proofReadinessVersion: string
```

By default, `proofExtension` is **absent** from the packet — the base packet
behavior is unchanged. It is only present when the caller explicitly passes
`options.proofClaims` to `buildVaultReadinessPacket`.

Helper:

```js theme={null}
// Build the optional extension block from proof claims:
import { buildProofClaimsPacketExtension } from './src/lib/proof-claim-schema.js';
const extension = buildProofClaimsPacketExtension([myClaim]);

// Attach to a packet:
import { buildVaultReadinessPacket } from './src/lib/buildVaultReadinessPacket.js';
const packet = buildVaultReadinessPacket(readiness, { proofClaims: [myClaim] });
// packet.proofExtension is now present
```

***

## 8. Safe limitations

Every proof claim carries a mandatory set of limitations, defined in
`PROOF_CLAIM_DEFAULT_LIMITATIONS`. These are **never relaxed by callers** — the
`createProofClaim` factory always merges them in.

Key limitations:

* A proof claim is **not custody**. WalletWall holds no keys, funds, or balances.
* A proof claim produces **no yield**, interest, or return.
* A proof claim is **not fund protection**. Readiness signals are research
  heuristics and do not insure or protect holdings.
* A proof claim does **not prove source-data truth**. It binds a computation
  to committed inputs only.
* A proof claim does **not guarantee readiness, protection, safety, or any outcome**.
* A proof claim does **not imply quantum resistance or quantum immunity**; post-quantum
  verifier work is read-only research on testnet only.
* **Candidate proof systems** (`sp1_candidate`, `zk_candidate`) are not
  implemented in production and carry no production verifier guarantee.
* An ML-DSA attestation answers **"who signed?"** (authenticity) only; it is
  not a computation-correctness proof.
* A ZK/SP1 candidate proof would answer **"was this computation correct?"** only;
  it says nothing about the truth of upstream source data or the identity of the signer.
* No proof claim requires or implies that a user must **connect a wallet, sign a
  transaction, or write to any chain**.

***

## 9. Why SP1 is future / candidate only

SP1 is described throughout this schema and the architecture doc as a *candidate
proving implementation* for selected readiness-computation claims. This framing
is intentional:

1. **The claim must be stable before the prover is built.** A stable claim
   schema is a prerequisite for scoping a prover — the claim defines *what* the
   proof must assert and *what it explicitly does not*.
2. **SP1 is one option, not the only option.** RISC Zero or another zkVM could
   fill the same slot. The `zk_candidate` key exists for a prover-agnostic
   design option.
3. **No SP1 implementation is in this app.** The app imports no prover, verifier,
   circuit, or program from the public vault research repo at runtime.
4. **Production verification is always out of scope** until independently reviewed
   and explicitly authorized. No `ProofClaim` from this schema may set
   `verificationStatus = "verified"` for a candidate proof system.

***

## 10. Mock claim builder

`buildMockReadinessProofClaim(readinessPacket, options)` produces a
**deterministic mock claim** for tests and future UI wiring.

* Uses `proofSystem: 'mock'` by default.
* Can produce a `sp1_candidate` or `zk_candidate` fixture if `options.proofSystem`
  is set explicitly.
* Performs no I/O, no clock reads, and no proving.
* Derives a stable `claimId` from `claimType`, subject address/symbol, and chain.
* Always includes the mandatory limitations plus a mock-specific disclosure.
* `verificationStatus` is `not_applicable` for `mock`, `unsupported` for candidates.

***

## 11. Non-goals

The proof claim schema explicitly does not:

* Implement SP1 prover or verifier code.
* Implement ZK circuits or programs.
* Import contracts, ABIs, or implementation details from the public vault
  research repo.
* Add custody, yield, fund movement, or wallet-signing behavior.
* Require mainnet writes or wallet connections.
* Prove that Dune, on-chain, or any external source data is globally true.
* Guarantee readiness, safety, protection, or any specific outcome.
* Provide production on-chain verification of any proof.

***

## 12. Dune / source-data boundary

This schema changes **no Dune behavior**:

* No Dune queries are executed, scheduled, refreshed, or modified.
* Proof claims reference committed inputs; they do not assert that the inputs
  from Dune or on-chain sources are globally true.
* Existing Dune guardrails (`assertDuneExecutionAllowed`, `readOrCache`,
  `getOrCache`) are preserved unchanged.

***

*This document is architecture and schema 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.*