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

# Evidence endpoint preview rehearsal

# Evidence endpoint preview rehearsal

**Version:** 2026-07-04 · **Status:** Active · preview-only rehearsal, disabled in production

Companion docs:

* [Hosted Evidence Consumption — App-Side Plan](../product/hosted-evidence-consumption.md) — the seam's original design, boundaries, and rollout phases (this runbook implements "Phase 2 — Gated consumption behind the flag").
* [Custody & Legal Boundaries](../product/custody-legal-boundaries.md) — canonical boundary reference.

***

## 1. Purpose

This runbook documents how to turn on the **hosted vault-evidence consumption
rehearsal** in a Vercel **preview** deployment only, so the `Vault Candidate
Readiness Packet` section of `/stablecoin-vault` shows real, validated
evidence fetched from the public `Wallet-Wall/walletwall-vault` repo's
committed static artifact — instead of the local reference packet.

**Production stays disabled.** Nothing in this runbook changes a default: the
app's evidence-endpoint seam (`src/lib/vault-evidence-endpoint-client.js`)
defaults to `enabled: false`, and the production Vercel environment never
sets the two env vars below. `test/vault-evidence-endpoint-status.test.mjs` and
`test/vault-evidence-endpoint-page-state.test.mjs` both assert the
env-unset (disabled) path resolves to the same reference packet + disabled
status the app has always shown.

## 2. What this rehearsal is (and is not)

* It is a **read-only, one-shot `GET`** of a single static, versioned JSON
  file — no polling, no retries beyond the existing 2.5s timeout, no
  credentials, no request body, no wallet data.
* It is **not** a live proof, a production ZK claim, or a mainnet-readiness
  signal — the fetched artifact itself says `"mode": "spike-non-production"`
  and `"proof": { "status": "gated" }`.
* It never runs in production: only a preview deployment's environment
  variables are changed by this runbook.

## 3. Vercel preview environment variables

Set these two variables on the **Preview** environment only (Vercel project
settings → Environment Variables → scope: Preview) — never Production:

| Variable                               | Value                                                                                                                                                             |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VITE_VAULT_EVIDENCE_ENDPOINT_ENABLED` | `true`                                                                                                                                                            |
| `VITE_VAULT_EVIDENCE_ENDPOINT_URL`     | `https://raw.githubusercontent.com/Wallet-Wall/walletwall-vault/0eaa94e425da955c4e9fb8278259a534129d78e7/evidence/zk/hosted/v1/zk-adapter-evidence-response.json` |

The URL is pinned to a specific commit SHA (`0eaa94e425da955c4e9fb8278259a534129d78e7`),
**not** `main` — a moving branch ref would let the rehearsal silently start
serving different bytes than what was reviewed. To rehearse against a newer
published artifact, deliberately update the SHA in this table (and re-review),
rather than pointing at a branch.

After setting both variables, redeploy the preview (or push a new commit to
the PR) so Vite picks up the new `VITE_*` values at build time.

## 4. What renders when live

With both variables set on a preview deployment, on `/stablecoin-vault`
under "Vault Candidate Readiness Packet":

* The **`VaultEvidenceSourceStatus`** chip row shows source label
  **"Validated endpoint evidence"** (not "Reference packet") and endpoint tag
  **"Validated"**, with detail text: *"Packet enriched from a validated,
  fresh hosted evidence endpoint response."* This copy explicitly names the
  hosted endpoint as the data source — it is never rendered as if the data
  were locally derived (see `test/hosted-evidence-endpoint-provenance.test.mjs`).
* The packet's "Reference packet — example only" notice does **not** appear
  (it is gated on `packet.referencePacket`, which is `false` once enriched).
* **`ProofEvidenceChainPanel`** (the six-step evidence chain elsewhere on the
  page) is unaffected and continues to render its static, locally-registered
  steps from `src/lib/vaultEvidenceChain.js` — it does not consume the
  endpoint seam and is not expected to change with this rehearsal.

If the fetch fails for any reason (timeout, non-200, malformed JSON, schema
mismatch, or a stale `servedAt` older than 24h), the page falls back silently
to the same reference-packet framing production always shows, with the
status chip showing **"Fallback active"** and a calm, specific reason —
never a raw error or a blank/broken section.

## 5. Rollback

Unset both `VITE_VAULT_EVIDENCE_ENDPOINT_ENABLED` and
`VITE_VAULT_EVIDENCE_ENDPOINT_URL` on the Preview environment (or delete the
env-var rows entirely) and redeploy. The page immediately reverts to the
disabled state — the same reference packet and "Reference packet" /
"Endpoint disabled" chip that renders when the variables were never set.
No code change is required to roll back; this is a config-only rehearsal.

## 6. Safety boundaries

* Production environment variables are never set by this runbook — confirmed
  by `test/vault-evidence-endpoint-status.test.mjs` and
  `test/vault-evidence-endpoint-page-state.test.mjs`, which both assert the
  env-unset path stays disabled.
* `test/vault-pq-integration-safety.test.mjs` continues to guard the whole
  vault/pq surface set (no absolute-URL fetch literal, no Dune `/execute`, no
  overclaiming copy, no wallet-write route) — this rehearsal adds no
  exception to that guard.
* No wallet data, address, or user identifier is ever sent with the fetch —
  the request is parameterless (see `src/lib/vault-evidence-endpoint-runtime.js`).