Assurance Roadmap

Risks documents what can go wrong. This page defines how the project earns confidence that the design and the implementation are sound — two workstreams, and the hard gates they impose before the protocol carries real value.

Two failure classes, two instruments

Two distinct failure classes threaten the protocol, and they need different instruments:

• Incentive failures. Every role behaves as specified only if behaving as specified is that actor's best strategy. Cryptographic proofs do not cover this: a protocol can be mathematically sound and still fail in production because rational operators act differently than the design assumes. Incentive failures surface only once the network is live and someone exploits them — and a live decentralized system cannot simply be patched. They must be found before launch, by analysis.
• Implementation failures. The specification can be right and the code wrong. zkCoins deliberately runs a single protocol implementation (the Rust node; the TypeScript SDK independently re-implements only the client-side primitives — derivation, hashing, and signing). There is no second full implementation to cross-check against, so the independent view a second client would provide must come from elsewhere: the executable conformance harness — the specification's pinned test vectors, their negative controls, and the A-to-Z suite of the Implementation Mandate. By explicit project decision v1 ships without an external audit; the harness and the specification's internal soundness argument (spec §2.4) carry that assurance weight.

Both workstreams follow the project's standing rule: whatever they change flows through this repository as a spec PR first (Implementation Mandate).

Paper-conformance remediation is an open release gate

The paper-deviation analysis documents how an earlier specification baseline (docs@6816fc3) changed load-bearing parts of the original zkCoins and Shielded CSV constructions, including nullifiers, batch availability, accumulator admission, reorg handling, fees, and mint anchoring. PR #97 returned the model to on-chain half-aggregated state nullifiers, Bitcoin first occurrence and conditional NAV (now normative); Paper-Conformance Remediation tracks the remaining executable-conformance and assurance gates that must close before the protocol carries real value.

Workstream 1 — Incentive analysis

Scope: every mechanism whose correctness or liveness depends on actor behaviour rather than cryptography. Risks is the maintained catalog; the analysis must use the current on-chain-nullifier model, in which publishing is contention-free and the public accumulator is rebuilt from Bitcoin alone, while private CoinProof availability remains a replicated off-chain liveness requirement (spec §3.4, §3.6, §4.6).

Method — for each mechanism:

1. Actor model. Who participates, what they can do, what it costs them, what they earn.
2. Adversary budget. What a rational attacker spends versus what the attack yields — including griefing, where the attacker pays to impose losses on others.
3. Equilibrium argument. Show in writing, with assumptions stated, that following the protocol is each actor's best strategy. Where a closed-form argument is not available, simulate.
4. Verdict. Each mechanism ends in exactly one of: holds, holds under stated assumptions, accepted v1 boundary (a residual accepted as final for v1 and registered in the Paper-Deviation Analysis), or broken → spec change.

Output: the closed verdict table at the top of Risks — one row per mechanism, no row open. For v1 this table is complete (project decision 2026-07-22); a future mechanism change reopens only its own row. No mechanism ships to mainnet with an open verdict.

Workstream 2 — Verification staircase

The path to "demonstrably secure", in order — each step builds on the previous one:

1. Security definitions. Precise statements of what secure means for zkCoins: no forgery, no double-spend, and privacy of amounts, assets, and participants expressed as indistinguishability properties — stated precisely enough to capture the linkability gaps Risks already documents (intra-transaction co-output visibility via the shared output_coins_root, and cross-transition publisher linkage via the fee-coin ash chain), so v1's actual unlinkability guarantee is neither over- nor under-stated. The definitions become part of the Specification.
2. Paper proofs. Reductions showing the protocol meets those definitions under standard assumptions (hash security, discrete log/Schnorr, the proof system's soundness and zero-knowledge). Written up, published, and reviewable. For v1, publication of these proofs is a quality goal, not a release gate (project decision: no human-gated mainnet step); the release-gating artefacts are the in-spec soundness argument and the executable harness.
3. Machine-checked verification. Machine-checked proofs or model checking for the protocol state machine where feasible. By explicit project decision there is no external audit for v1: the executable conformance harness — pinned vectors, negative controls, and the A-to-Z suite — stands in for the independent check a second implementation or an external audit would otherwise provide.

Proofs cover the model, not the code

A security proof establishes that the specified protocol is sound. That the running code implements the specified protocol is established separately — by the pinned conformance vectors and the end-to-end suite the Implementation Mandate requires. Only both halves together justify the claim "demonstrably secure".

Gates

Gate	What must hold
Public testnet	Paper-conformance remediation Gate A (specification completeness) is closed; zero <REGEN> placeholders outside the explicitly non-byte-pinned cells (the V.5/V.6 signature values, locked by verification, and the deployment-specific V.6 block_anchor); zero open rows in the Risks verdict table; conformance vectors generated and pinned; the A-to-Z suite passes across node, SDK, and app. Steps 1–7 of the implementation-mandate runbook are the executable form of this gate.
Real value (mainnet)	Paper-conformance remediation Gates A–C are closed (their definitions); the Risks verdict table has no open and no broken row (Workstream 1); the specification's soundness summary (spec §2.4) and security-properties summary (spec §6.7) are complete and internally consistent, and the Gate-B negative-control vectors pass; the reference instantiation is final for v1 (spec §1.7.8); a vulnerability disclosure process is published (SECURITY.md).

These gates are ordered stations, not aspirations: a release that has not passed its gate does not ship. Their executable form — ordered steps with hard pass predicates and no human-gated stop — is the Path to mainnet runbook.