quantum-audit-scope.md (9802B)
1 # Quantum migration audit scope 2 3 ## Purpose and decision boundary 4 5 This document defines the review package for Iuna's post-quantum migration. The current code 6 reserves versioned addresses and transaction encodings, verifies hybrid Ed25519 + ML-DSA-44 7 authorizations, and activated transaction v2 at height 3000. Live consensus and blocks accept v2 8 transactions, and nodes relay canonical v2 mempool envelopes only across sessions that negotiated 9 the transaction-v2-mempool capability. The management wallet exposes 10 migration telemetry, reviewed block-bounded migration submission, and hybrid transfers. 11 12 An audit of this scope must review the active consensus code and the enabled wallet migration 13 flow. It must cover the final integration commit and the 14 post-height-3000 migration rehearsal described in quantum-migration.md. 15 16 ## Security claims 17 18 The candidate design intends to provide the following properties after a separately reviewed 19 activation: 20 21 1. Spending an address-v1 output requires valid Ed25519 and ML-DSA-44 signatures over exactly the 22 same canonical payload. 23 2. An address-v1 output commits to the scheme identifier, component lengths, and exact public-key 24 encodings without publishing those keys before the output is spent. 25 3. A transaction-v2 signature cannot be replayed across chain IDs, genesis blocks, transaction 26 kinds, inputs, outputs, amounts, fees, or authorization order. 27 4. Unknown versions and signature schemes fail closed. 28 5. Transaction identity is a fixed-size domain-separated hash of the complete canonical 29 transaction, not a signature value. 30 6. Malformed lengths, counts, and encodings are rejected before attacker-controlled allocation or 31 cryptographic work becomes unbounded. 32 7. Version-0 historical data and transactions remain valid under their existing rules. 33 8. An explicit transaction-v2 migration may reference a tagged 32-byte legacy hash or 64-byte 34 legacy signature ID and spend its version-0 output with the existing Ed25519 key. Ordinary v2 35 transactions use 32-byte hash IDs, and the resulting version-1 output cannot be spent without 36 both signature components. 37 38 The repository does not currently claim that wallet transactions, consensus identities, the VDF, 39 P2P identity, TLS, or software updates are post-quantum secure. 40 41 ## Threat model 42 43 The review should consider: 44 45 - a remote unauthenticated peer supplying arbitrary transaction-v2 bytes; 46 - a malicious spender choosing related Ed25519 and ML-DSA keys, signatures, and encodings; 47 - replay across networks, genesis blocks, transaction kinds, inputs, and activation boundaries; 48 - parser differentials between mempool, block, snapshot, JSON, and compact encodings; 49 - denial of service through large counts, lengths, signature verification, or repeated invalid 50 signatures; 51 - compromise of either the classical or post-quantum algorithm, but not both simultaneously; 52 - implementation or supply-chain defects in the pinned ML-DSA backend; 53 - a future cryptographically relevant quantum computer attacking public keys already visible on 54 chain; 55 - rollback, partial deployment, and partitions involving nodes that do not understand the new 56 protocol. 57 58 Compromise of both signature components, endpoint compromise while signing, malicious release 59 binaries, and recovery of value whose owner has lost all signing material remain out of scope for 60 the transaction-v2 cryptographic claim. 61 62 ## Review targets 63 64 The minimum code-review scope is: 65 66 - src/domain/signature.rs: scheme identifiers, exact lengths, backend decoding, and verification; 67 - src/domain/address.rs: version retention, Bech32m parsing, and key commitments; 68 - src/domain/transaction_v2.rs: canonical encoding, parsing, domain separation, transaction IDs, 69 authorization binding, resource limits, and the fixed activation gate; 70 - src/domain.rs: public boundaries and fuzz-only exposure; 71 - tests/vectors/: pinned NIST and Wycheproof provenance and expected verdicts; 72 - fuzz/fuzz_targets/transaction_v2.rs: decoder and verifier coverage; 73 - deployment.sh: the release fuzzing gate and retained evidence; 74 - all future call sites that connect transaction v2 to wallets, mempool, gossip, blocks, compact 75 storage, fees, or fork validation. 76 77 The exact review commit and all three Cargo lockfile hashes must be recorded when an engagement 78 starts. Any subsequent change to the files above invalidates approval until the auditor assesses 79 the delta. From a clean review checkout, `scripts/quantum-audit-manifest.sh --output 80 quantum-audit-manifest.json` records these identifiers, tool versions, and upstream vector 81 provenance in one machine-readable file. 82 83 ## Required invariants and negative tests 84 85 An auditor should independently confirm at least these cases: 86 87 - accepting either signature alone is impossible; 88 - a version-0 input accepts only its matching Ed25519 authorization, while a version-1 input 89 accepts only its matching hybrid authorization; 90 - swapping either public-key or signature component fails; 91 - signatures over different chain IDs or genesis hashes fail; 92 - reordering inputs, outputs, or authorizations fails or produces the uniquely specified payload; 93 - duplicate inputs and authorization-count mismatches are rejected by the eventual consensus call 94 site; 95 - non-canonical and trailing encodings fail rather than normalize; 96 - address commitments cannot be ambiguous across schemes or component boundaries; 97 - transaction IDs change when any authorization byte changes; 98 - maximum counts and lengths cannot overflow size accounting or cause excessive allocation; 99 - transaction v2 remains rejected through height 2999 and becomes eligible at height 3000; 100 - 0.4.30-shaped handshakes remain compatible before the activation boundary; new handshakes are 101 rejected once either peer is preparing height 3000 and omits transaction-v2-blocks. Auditors 102 must still verify the release/reconnect procedure for sessions opened before that boundary. 103 104 ## Techniques adopted and rejected 105 106 Iuna adopts the key-hiding and versioned-output pattern proposed by Bitcoin P2QRH, but does not 107 depend on that proposal's deployment or exact script design. It adopts hybrid signatures for the 108 migration interval and a staged read-before-activation rollout. 109 110 XMSS, used by QRL and standardized for restricted use by NIST SP 800-208, is not selected for 111 ordinary wallets because safe signing depends on durable one-time-signature state across backups 112 and devices. Stateless SLH-DSA remains a possible emergency recovery scheme, but would receive a 113 new scheme identifier and a separate size, fee, and implementation review. 114 115 Algorand-style post-quantum state proofs motivate a later checkpoint phase, but Iuna must first 116 specify who owns post-quantum checkpoint keys and how signer authority follows consensus. A 117 maintainer-signed snapshot is useful release evidence, but is not a decentralized finality proof 118 and must never be presented as one. 119 120 ## Reproduction 121 122 From the repository root, reviewers should run: 123 124 ```sh 125 cargo test --all-targets --all-features --locked 126 cargo clippy --all-targets --all-features -- -D warnings 127 cargo build --locked --manifest-path fuzz/Cargo.toml --bins 128 cargo test ml_dsa44_matches_pinned_nist_and_wycheproof_vectors --lib 129 cargo +nightly fuzz run transaction_v2 -- -max_total_time=300 -timeout=10 130 ``` 131 132 The curated vector set is a regression suite, not a substitute for running complete upstream 133 corpora or reviewing the cryptographic backend. Reviewers should verify the upstream file hashes 134 recorded in tests/vectors/ml_dsa44_audit.json and retain tool versions, corpus, coverage data, and 135 crash artifacts with their report. 136 137 ## Activation blockers 138 139 The active transaction-v2 and wallet-migration rules must not be described as production-ready 140 until all of the following are resolved: 141 142 - the cryptographic backend and Iuna integration are independently reviewed; 143 - the final consensus call sites and byte-based fee accounting receive independent review; 144 - wallet backup compatibility, migration batching, hybrid spending, recovery, and no-address-reuse 145 behavior are reviewed; deterministic external/change rotation and spend-triggered reward 146 rotation now exist, but their recovery and no-reuse behavior still require independent review; 147 - migration progress is observable without exposing wallet secrets; 148 - advertised transaction-v2-blocks behavior (including already-open sessions), restored 149 snapshot-v7 behavior, and activation-boundary recovery are rehearsed on the mainnet-candidate 150 network; 151 - post-quantum plans exist for peer identity and update signing; 152 - checkpoint signer authority is specified before any PQ checkpoint format is trusted; 153 - the VDF has a separate quantum threat analysis; 154 - an activation abort procedure exists before a release can reach activation height 3000. 155 156 ## Expected audit deliverables 157 158 The engagement should produce a public report containing the reviewed commit, scope exclusions, 159 toolchain and dependency versions, findings with severity and exploit prerequisites, test evidence, 160 and an explicit verdict for dormant shipping versus mainnet activation. Fixes must be reviewed as a 161 documented delta rather than assumed resolved by the project team. 162 163 ## Primary references 164 165 - NIST FIPS 204, Module-Lattice-Based Digital Signature Standard: 166 <https://csrc.nist.gov/pubs/fips/204/final> 167 - NIST FIPS 205, Stateless Hash-Based Digital Signature Standard: 168 <https://csrc.nist.gov/pubs/fips/205/final> 169 - NIST SP 800-208, stateful hash-based signature recommendations: 170 <https://csrc.nist.gov/pubs/sp/800/208/final> 171 - RFC 8391, XMSS: <https://www.rfc-editor.org/rfc/rfc8391> 172 - Bitcoin BIP 360, Pay to Quantum Resistant Hash: <https://bips.dev/360/> 173 - Algorand State Proofs: <https://developer.algorand.org/docs/get-details/stateproofs/>