Merge pull request 'tools: harden chain audit scripts' (#25) from tooling-hardening into main

2 files changed, 21 insertions, 2 deletions

diff --git a/docs/fair-launch.md b/docs/fair-launch.md
index 79eca8e..9603910 100644
--- a/docs/fair-launch.md
+++ b/docs/fair-launch.md
@@ -8,7 +8,8 @@ python3 scripts/verify-fair-launch.py --max-blocks 1000 --out bitflash-fair-laun
 
 The verifier reads `blk*.dat` directly from the local Bitflash data directory.
 It does not use Berkeley DB, does not call the node binary, and does not need
-network access.
+network access. It uses the same shared Python chain parser as the UTXO
+commitment and proof tools, so block serialization fixes land in one place.
 
 The report proves the launch baseline that can be checked from the chain:
 
diff --git a/docs/utxo-commitment.md b/docs/utxo-commitment.md
index 991e5d9..ab43deb 100644
--- a/docs/utxo-commitment.md
+++ b/docs/utxo-commitment.md
@@ -21,7 +21,8 @@ python3 scripts/verify-utxo-set.py --out utxo-report.json --json
 
 The verifier:
 
-- parses Bitflash block files directly;
+- parses Bitflash block files directly with the shared Python chain parser;
+- streams `blk*.dat` records instead of loading full block files into memory;
 - reconstructs the best chain rooted at the Bitflash genesis block;
 - ignores side blocks that may also be present in `blk*.dat`;
 - verifies every scanned block merkle root;
@@ -98,6 +99,23 @@ last-write-wins semantics for the UTXO map, matching the legacy index model.
 Those warnings are part of the report so auditors can see the historical debt
 instead of relying on a polished summary.
 
+For synthetic chains or future clean consensus ranges, auditors can make
+duplicates a hard failure:
+
+```bash
+python3 scripts/verify-utxo-set.py --strict-duplicates
+```
+
+The default remains compatible with the current historical chain because it has
+known legacy duplicate-output overwrites.
+
+## Shared Parser
+
+The audit scripts share `scripts/bitflash_chain.py` for block parsing,
+main-chain selection, UTXO application, canonical JSON, and genesis
+reconstruction. That keeps `verify-utxo-set.py`, `verify-fair-launch.py`,
+`prove-utxo.py`, and the explorer on the same serialization rules.
+
 ## Future Consensus Path
 
 This tool is the low-risk first step toward consensus commitments. A future