> ## 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. # Vault pq integration traceability # Vault / PQ Integration Traceability Traceability and safety record for the Stablecoin Vault + post-quantum (PQ) verifier-evidence integration in the **private app repo** (`sirmrdrgod/walletwall`), mapped against the **public reference repo** (`Wallet-Wall/walletwall-vault`). This document answers one question for a reviewer or auditor: *for every public vault/PQ capability we surface in the app, where is the local, read-only counterpart, what proves it stays safe, and what it explicitly does not do.* * **Audit date:** 2026-06-21 * **Audit branch:** `audit/vault-pq-integration-traceability` * **Scope:** read-only audit + additive traceability doc + additive cross-surface safety guard. No product behavior change. * **Last updated:** 2026-06-21 — extended to map `walletwall-vault@0.8.5` (SHA `6462c10`) proof artifact example (PR #65) → private app `ProofArtifactStatusCard` + `proof-artifact-status.js`. *** ## 1. Baseline under audit ### Private app repo — `sirmrdrgod/walletwall` (`main`) The Stablecoin Vault / PQ integration stack merged as four PRs, all confirmed present on `main` at audit time: | PR | Title | Primary artifacts | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [#1171](https://github.com/sirmrdrgod/walletwall/pull/1171) | `sec(api): centralize route registration in a shared manifest + regression test` | `api/_route-manifest.js`, `server.js`, `test/api-route-registration.test.mjs` | | [#1172](https://github.com/sirmrdrgod/walletwall/pull/1172) | `feat(vault): surface read-only PQ verifier evidence on the Stablecoin Vault page` | `src/components/PQVerifierEvidenceCard.jsx`, `src/lib/pqVerifierEvidence.js`, `src/components/StablecoinVaultPage.jsx`, `test/stablecoin-vault-pq-evidence.test.mjs` | | [#1174](https://github.com/sirmrdrgod/walletwall/pull/1174) | `feat(vault): deterministic Stablecoin Vault rehearsal status model` | `src/lib/stablecoin-vault-rehearsal-status.js`, `src/components/StablecoinRehearsalStatusPanel.jsx`, `test/stablecoin-vault-rehearsal-status.test.mjs` | | [#1175](https://github.com/sirmrdrgod/walletwall/pull/1175) | `chore(vault): harmonize Stablecoin Vault trust-boundary copy` | `src/components/StablecoinVaultPage.jsx`, `src/lib/stablecoin-vault-readiness.js`, `test/stablecoin-vault-disclosure-copy.test.mjs` | ### Public reference repo — `Wallet-Wall/walletwall-vault` * **Observed reference version: `walletwall-vault@0.8.5`** (main SHA `6462c10`). This supersedes the earlier `0.8.1` reference point. * Source public PRs whose shapes/boundaries the app mirrors: | Public PR | Subject | | --------- | ----------------------------------------------------------------------------------------- | | #58 | Sepolia rehearsal / operator docs + app-consumable status example | | #60 | PQ verifier boundary guards | | #61 | PQ evidence artifact / schema | | #62 | SP1 smoke lane | | #63 | ZK/PQ status matrix | | #64 | Expanded ACVP / ML-DSA-65 vector coverage | | #65 | Reproducible proof artifact example ← **primary reference for `ProofArtifactStatusCard`** | | #66 | Hosted verifier demo spike (disclosure only — not wired at runtime) | | #67 | On-chain verifier feasibility doc (disclosure only — not wired at runtime) | > Version note: the app's local fixtures mirror result/metadata **shapes** that > entered the public repo through the `#56`/`#58` era (`walletwall.pq-verifier.v1`, > the Sepolia app-status example) and remain shape-compatible with `0.8.5`. Public > PRs `#60`–`#63` are reflected in the app as **disclosure and boundary posture**. > Public PRs `#64`–`#67` (vector coverage, proof artifact example, hosted verifier > spike, on-chain feasibility) are reflected as an **app-local, read-only proof > artifact status surface** (`ProofArtifactStatusCard`, `proof-artifact-status.js`). > No code from `#64`–`#67` is imported at runtime. *** ## 2. Capability → app artifact mapping | Public reference capability | Source public PR(s) | Private app artifact(s) | Proof | | ---------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Route manifest / registration hardening | (app-side #1171; pairs with repo-trust posture) | `api/_route-manifest.js`, `server.js` | `test/api-route-registration.test.mjs`, `test/vault-pq-integration-safety.test.mjs` ("no write route") | | PQ evidence artifact / schema (`walletwall.pq-verifier.v1`, hash-only) | #61, #60 | `src/lib/pqVerifierEvidence.js`, `src/components/PQVerifierEvidenceCard.jsx` (types + read-only card) | `test/pq-verifier-evidence.test.mjs`, `test/stablecoin-vault-pq-evidence.test.mjs` | | Sepolia app-status example (testnet simulator metadata) | #58 | `src/lib/stablecoin-vault-rehearsal-status.js` (rehearsal status model + static demo fixture), `src/components/StablecoinRehearsalStatusPanel.jsx` | `test/stablecoin-vault-rehearsal-status.test.mjs` | | SP1 smoke lane | #62 | **Disclosure only** — surfaced as "Not a ZK proof" / "Not on-chain ML-DSA verification" disclosures; no SP1/prover code in the app | `PQ_VERIFIER_DISCLOSURES` in `src/lib/pqVerifierEvidence.js`; asserted in `test/pq-verifier-evidence.test.mjs` | | ZK/PQ status matrix | #63 | **Copy / disclosure boundaries** — Stablecoin Vault rehearsal + PQ section copy keeps the two gates separate and neither implies production protection | `test/stablecoin-vault-disclosure-copy.test.mjs`, `test/vault-pq-integration-safety.test.mjs` | | Operator docs (no-custody / no-write operating path) | #58 | **No-custody / no-write copy** — `REQUIRED_DISCLOSURES`, hero + section trust-boundary copy | `test/stablecoin-vault-disclosure-copy.test.mjs` | | Expanded ACVP / ML-DSA-65 vector coverage | #64 | **Context for proof artifact fixture** — `DEMO_PROOF_ARTIFACT.vectorSetId = 'ACVP-ML-DSA-65-v1.0'` in `proof-artifact-status.js` references the vector set; no ACVP code imported | `test/proof-artifact-status.test.mjs` (DEMO fixture reference version check) | | **Reproducible proof artifact example** | **#65** | **`src/lib/proof-artifact-status.js`** (proof artifact model + `DEMO_PROOF_ARTIFACT` static fixture), **`src/components/ProofArtifactStatusCard.jsx`** (read-only status card) | **`test/proof-artifact-status.test.mjs`** (41 tests), `test/vault-pq-integration-safety.test.mjs` (surface discovery) | | Hosted verifier demo spike | #66 | **Disclosure only** — "SP1 proving remains gated", "Not on-chain verification" disclosures; no hosted verifier call in the app | `PROOF_ARTIFACT_DISCLOSURES` in `src/lib/proof-artifact-status.js`; asserted in `test/proof-artifact-status.test.mjs` | | On-chain verifier feasibility doc | #67 | **Disclosure only** — "Not on-chain verification", "Not production quantum protection" disclosures; no on-chain verification in the app | `PROOF_ARTIFACT_DISCLOSURES` in `src/lib/proof-artifact-status.js`; asserted in `test/proof-artifact-status.test.mjs` | ### Three gates, never collapsed The integration keeps **three independent gates** and never merges them into a single "ready / protected / secured" claim: * **PQ evidence** answers: *"was read-only verifier evidence observed?"* (`PQ_EVIDENCE_STATE.observed | not_observed`). The flagship page shows only a **sample** result, so live PQ evidence is *not* observed there. * **Rehearsal metadata** answers: *"is a testnet simulator / operator path documented and metadata-safe?"* (`REHEARSAL_STATUS.*`, fail-closed). * **Proof artifact status** answers: *"is a proof artifact reference available, and what is its proof-block generation status?"* (`ARTIFACT_STATUS.*`, fail-closed; kept separate from both PQ evidence and rehearsal metadata). `buildVaultRehearsalModel(...)` composes the first two without producing a combined boolean. `buildProofArtifactModel(...)` is a separate, independent call. Tests: * `stablecoin-vault-rehearsal-status.test.mjs` pins "no combined ready/protected boolean at the model top level" and "PQ evidence gate is independent of rehearsal state." * `proof-artifact-status.test.mjs` pins "no combined ready/protected flag at model top level" for the proof artifact model and verifies the three gates are never merged. *** ## 3. Audit findings ### 3.1 No runtime dependency on the public vault repo — confirmed Across all **40+** discovered Vault / PQ / rehearsal / proof-artifact surface files (`src/components`, `src/components/vault`, `src/lib`): * **No code import** from `Wallet-Wall/walletwall-vault` or the embedded `research/walletwall-vault` copy. The only references are a comment in `src/lib/vaultContract.js` and a path-describing string in `src/lib/vaultDeploymentManifest.js` — neither is an import. * **No runtime fetch** of the public repo: no `raw.githubusercontent`, no absolute-URL `fetch(...)`. The only `fetch()` calls (in `src/lib/quantum-exposure-adapter.js`) target same-origin `/api/*` routes. * **No Dune `/execute`** path. `executeAndPoll` / `api.dune.com/.../execute` live only in the pre-existing, guarded `api/_dune.js` helper (covered by `npm run dune:guard` / `npm run dune:verify`); no vault/pq surface touches it. ### 3.2 Forbidden-term sweep — results | Term | Result | Disposition | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `Wallet-Wall/walletwall-vault`, `github.com/Wallet-Wall/walletwall-vault` | Present as `` doc links + `repoUrl`/`docsUrl`/`canonicalSource` string constants | **Allowed (safe).** Attribution / informational external links — not runtime fetches or imports. | | `raw.githubusercontent.com` | Absent in app code | — | | `.abi`, `hardhat`, `artifacts/`, `bytecode` | Absent in app vault/pq code | — | | `/execute` | Only in `api/_dune.js` (guarded) | **Allowed (safe).** Pre-existing centralized Dune helper; no vault/pq surface uses it. | | `quantum-proof`, `mainnet-ready`, `vaulted funds`, `deposit now` | Absent | — | | `protected`, `secured` | Absent as claims on vault/pq surfaces | — | | `yield` | Only in negations / qualified mock labels | **Allowed (safe).** "no real yield", "Real yield: none", "mock yield". | ### 3.3 Documented safe contexts (intentional, individually tested) * **`"Mock APY: demo-only rate"`** (`src/components/VaultPage.jsx`, mock pool economics panel). Qualified mock label shown alongside `Pool status: Simulated` and `Custody: none`. Pinned by `test/vault-mock-pool-economics-panel.test.mjs`. The cross-surface guard therefore forbids `live apy` / `live yield` / `earn|generate yield`, **not** a qualified mock label. * **`"Stabilizing secure workspace…"`** (`src/components/vault/VaultModeTransition.jsx`). Rehearsal-mode loading microcopy. `secure` (adjective for the local workspace) is **not** the forbidden `secured` funds-claim; pinned by `test/vault-seal-transition.test.mjs` and `test/motion-loading-reveal.test.mjs`. * **Repo reference links/strings** — see §3.2. No unsafe term required removal; nothing was changed to product behavior or copy in this PR. ### 3.4 Safety guard — extended for proof artifact `test/vault-pq-integration-safety.test.mjs` — a **directory-level**, additive guard that sweeps every current and future vault/pq/proof-artifact surface and pins: 1. The surface set is non-empty and includes key anchors (cannot silently no-op). * **New anchors added:** `src/components/ProofArtifactStatusCard.jsx`, `src/lib/proof-artifact-status.js` 2. No surface imports public-repo / research-copy code. 3. No surface performs a public-repo runtime fetch or absolute-URL fetch. 4. No surface introduces a Dune `/execute` path. 5. No surface contains unconditional overclaiming copy. 6. The public API route table registers no wallet/contract write route. The surface discovery regex was extended from `/(vault|pq-?verifier|rehearsal|verifier|stablecoin)/i` to also include `proof-?artifact`, so any future `proof-artifact-*.js` or `*ProofArtifact*.jsx` file is automatically swept. It does **not** replace or weaken the narrower per-surface tests (`stablecoin-vault-disclosure-copy`, `stablecoin-vault-rehearsal-status`, `pq-verifier-evidence`, `proof-artifact-status`, `api-route-registration`), which remain the source of truth for their stricter rules. *** ## 4. Explicit non-goals This integration, and this PR, do **not** add or claim any of: * custody of funds, * wallet transactions, * signing / private-key handling, * contract writes, * mainnet deposits or withdrawals, * yield / interest / APY, * production quantum protection (PQ evidence is read-only; SP1 smoke is research/disclosure status only; there is no on-chain ML-DSA verification). *** ## 5. Verification commands | Command | Expected outcome | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `node --test test/vault-pq-integration-safety.test.mjs` | 6/6 pass (surface set includes ProofArtifactStatusCard + proof-artifact-status anchors) | | `node --test test/proof-artifact-status.test.mjs` | 41/41 pass — model states, frozen, fail-closed, lib safety, component safety, page wiring | | `node --test test/api-route-registration.test.mjs` | route manifest hardening passes (no `_`-prefixed/route drift, no `/wallet-contract`) | | `node --test test/stablecoin-vault-rehearsal-status.test.mjs` | rehearsal model + lib runtime-independence pass; gates stay separate | | `node --test test/stablecoin-vault-pq-evidence.test.mjs test/pq-verifier-evidence.test.mjs` | PQ evidence fail-closed; hash-only; required disclosures present | | `node --test test/stablecoin-vault-disclosure-copy.test.mjs` | trust-boundary copy coherent; no overclaim vocabulary | | `node --test "test/**/*.test.mjs"` | full suite green (4590+ tests, 0 fail from this PR's scope) | | `node scripts/static-check.mjs` | lint passes | *** *Maintained as part of the Vault/PQ release-readiness lane. Reference version updated from `0.8.1` → `0.8.5` (SHA `6462c10`) on 2026-06-21 as part of the `feat/vault-proof-artifact-status` PR. Update again when the public `Wallet-Wall/walletwall-vault` reference advances past `0.8.5`.*