tools: harden chain audit scripts

6 files changed, 758 insertions, 864 deletions

diff --git a/scripts/bitflash_chain.py b/scripts/bitflash_chain.py
new file mode 100644
index 0000000..f3688f1
--- /dev/null
+++ b/scripts/bitflash_chain.py
@@ -0,0 +1,453 @@
+#!/usr/bin/env python3
+"""Shared Bitflash block/chain parser for deterministic audit tools."""
+
+import datetime as _dt
+import hashlib
+import json
+import os
+import struct
+from pathlib import Path
+
+
+MAGIC = bytes([0xBF, 0x20, 0x5C, 0xFD])
+MAX_BLOCK_PAYLOAD = 32 * 1024 * 1024
+COIN = 100_000_000
+GENESIS_HASH = "5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169"
+GENESIS_MERKLE = "1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325"
+GENESIS_TIME = 1_753_315_200
+GENESIS_BITS = 0x1F0FFFFF
+GENESIS_NONCE = 3141
+GENESIS_TEXT = "Bitflash 24/Jul/2026 Fair launch: one CPU one vote, no premine"
+
+
+class ParseError(Exception):
+    pass
+
+
+class Reader:
+    def __init__(self, data):
+        self.data = data
+        self.pos = 0
+
+    def take(self, n):
+        if self.pos + n > len(self.data):
+            raise ParseError("unexpected end of data")
+        out = self.data[self.pos:self.pos + n]
+        self.pos += n
+        return out
+
+    def u8(self):
+        return self.take(1)[0]
+
+    def u32(self):
+        return struct.unpack("<I", self.take(4))[0]
+
+    def i32(self):
+        return struct.unpack("<i", self.take(4))[0]
+
+    def i64(self):
+        return struct.unpack("<q", self.take(8))[0]
+
+
+def sha256(data):
+    return hashlib.sha256(data).digest()
+
+
+def sha256d(data):
+    return hashlib.sha256(hashlib.sha256(data).digest()).digest()
+
+
+def hash_hex(serialized):
+    return sha256d(serialized)[::-1].hex()
+
+
+def compact_size(r):
+    first = r.u8()
+    if first < 253:
+        return first
+    if first == 253:
+        return struct.unpack("<H", r.take(2))[0]
+    if first == 254:
+        return r.u32()
+    return struct.unpack("<Q", r.take(8))[0]
+
+
+def read_varbytes(r):
+    return r.take(compact_size(r))
+
+
+def ser_compact_size(n):
+    if n < 253:
+        return bytes([n])
+    if n <= 0xFFFF:
+        return b"\xfd" + struct.pack("<H", n)
+    if n <= 0xFFFFFFFF:
+        return b"\xfe" + struct.pack("<I", n)
+    return b"\xff" + struct.pack("<Q", n)
+
+
+def ser_varbytes(b):
+    return ser_compact_size(len(b)) + b
+
+
+def ser_tx(tx):
+    out = bytearray()
+    out += struct.pack("<i", tx["version"])
+    out += ser_compact_size(len(tx["vin"]))
+    for txin in tx["vin"]:
+        out += bytes.fromhex(txin["prevout_hash"])[::-1]
+        out += struct.pack("<I", txin["prevout_n"])
+        out += ser_varbytes(bytes.fromhex(txin["script_sig_hex"]))
+        out += struct.pack("<I", txin["sequence"])
+    out += ser_compact_size(len(tx["vout"]))
+    for txout in tx["vout"]:
+        out += struct.pack("<q", txout["value_satoshis"])
+        out += ser_varbytes(bytes.fromhex(txout["script_pub_key_hex"]))
+    out += struct.pack("<I", tx["lock_time"])
+    return bytes(out)
+
+
+def parse_tx(r):
+    start = r.pos
+    tx = {"version": r.i32(), "vin": [], "vout": [], "lock_time": 0}
+    for _ in range(compact_size(r)):
+        tx["vin"].append({
+            "prevout_hash": r.take(32)[::-1].hex(),
+            "prevout_n": r.u32(),
+            "script_sig_hex": read_varbytes(r).hex(),
+            "sequence": r.u32(),
+        })
+    for _ in range(compact_size(r)):
+        value = r.i64()
+        tx["vout"].append({
+            "value_satoshis": value,
+            "value_btf": format_money(value),
+            "script_pub_key_hex": read_varbytes(r).hex(),
+        })
+    tx["lock_time"] = r.u32()
+    raw = r.data[start:r.pos]
+    tx["txid"] = hash_hex(raw)
+    return tx
+
+
+def merkle_root(txids):
+    if not txids:
+        return "0" * 64
+    layer = [bytes.fromhex(x)[::-1] for x in txids]
+    while len(layer) > 1:
+        nxt = []
+        for i in range(0, len(layer), 2):
+            left = layer[i]
+            right = layer[i + 1] if i + 1 < len(layer) else left
+            nxt.append(sha256d(left + right))
+        layer = nxt
+    return layer[0][::-1].hex()
+
+
+def parse_block(payload, file_name="", offset=0):
+    r = Reader(payload)
+    header = r.take(80)
+    version, = struct.unpack("<i", header[0:4])
+    prev = header[4:36][::-1].hex()
+    merkle = header[36:68][::-1].hex()
+    ntime, bits, nonce = struct.unpack("<III", header[68:80])
+    txs = [parse_tx(r) for _ in range(compact_size(r))]
+    if r.pos != len(payload):
+        raise ParseError("trailing bytes inside block")
+    txids = [tx["txid"] for tx in txs]
+    return {
+        "hash": hash_hex(header),
+        "version": version,
+        "previous_hash": prev,
+        "merkle_root": merkle,
+        "computed_merkle_root": merkle_root(txids),
+        "time": ntime,
+        "time_utc": utc(ntime),
+        "bits": "0x%08x" % bits,
+        "nonce": nonce,
+        "tx_count": len(txs),
+        "transactions": txs,
+        "source_file": file_name,
+        "source_offset": offset,
+        "size": len(payload),
+    }
+
+
+def iter_block_files(datadir):
+    for path in sorted(Path(datadir).glob("blk*.dat")):
+        yield path
+
+
+def iter_blocks_from_file(path):
+    path = Path(path)
+    with path.open("rb") as f:
+        window = f.read(4)
+        offset = 0
+        while len(window) == 4:
+            if window != MAGIC:
+                nxt = f.read(1)
+                if not nxt:
+                    break
+                window = window[1:] + nxt
+                offset += 1
+                continue
+
+            size_bytes = f.read(4)
+            if len(size_bytes) != 4:
+                break
+            size = struct.unpack("<I", size_bytes)[0]
+            if size == 0 or size > MAX_BLOCK_PAYLOAD:
+                offset += 1
+                f.seek(offset)
+                window = f.read(4)
+                continue
+            payload_offset = offset + 8
+            payload = f.read(size)
+            if len(payload) != size:
+                break
+            try:
+                yield parse_block(payload, path.name, payload_offset)
+            except ParseError:
+                offset += 1
+                f.seek(offset)
+                window = f.read(4)
+                continue
+
+            offset = f.tell()
+            window = f.read(4)
+
+
+def read_blocks_from_files(paths, max_blocks=0):
+    blocks = []
+    for path in paths:
+        for block in iter_blocks_from_file(path):
+            blocks.append(block)
+            if max_blocks and len(blocks) >= max_blocks:
+                return blocks
+    return blocks
+
+
+def read_blocks(datadir, max_blocks=0):
+    return read_blocks_from_files(iter_block_files(datadir), max_blocks)
+
+
+def select_main_chain(blocks):
+    by_hash = {}
+    for block in blocks:
+        by_hash.setdefault(block["hash"], block)
+    if GENESIS_HASH not in by_hash:
+        raise ParseError("genesis block not found in block files")
+
+    children = {}
+    for block in by_hash.values():
+        children.setdefault(block["previous_hash"], []).append(block)
+    for v in children.values():
+        v.sort(key=lambda b: (b["hash"], b["source_file"], b["source_offset"]))
+
+    best = []
+    stack = [(by_hash[GENESIS_HASH], [by_hash[GENESIS_HASH]])]
+    while stack:
+        block, path = stack.pop()
+        if len(path) > len(best) or (len(path) == len(best) and block["hash"] < best[-1]["hash"]):
+            best = path
+        for child in children.get(block["hash"], []):
+            stack.append((child, path + [child]))
+    return best
+
+
+def is_coinbase(tx):
+    return (
+        len(tx["vin"]) == 1
+        and tx["vin"][0]["prevout_hash"] == "0" * 64
+        and tx["vin"][0]["prevout_n"] == 0xFFFFFFFF
+    )
+
+
+def utxo_leaf_hash(outpoint, utxo):
+    payload = "|".join([
+        "BTFUTXO1",
+        outpoint,
+        str(utxo["value_satoshis"]),
+        utxo["script_pub_key_hex"],
+        str(utxo["created_height"]),
+        utxo["created_txid"],
+    ]).encode("ascii")
+    return sha256(payload)
+
+
+def utxo_root(utxos):
+    leaves = [utxo_leaf_hash(k, utxos[k]) for k in sorted(utxos)]
+    if not leaves:
+        return sha256(b"BTFUTXO1|empty").hex()
+    layer = leaves
+    while len(layer) > 1:
+        nxt = []
+        for i in range(0, len(layer), 2):
+            left = layer[i]
+            right = layer[i + 1] if i + 1 < len(layer) else left
+            nxt.append(sha256(b"BTFNODE1|" + left + right))
+        layer = nxt
+    return layer[0].hex()
+
+
+def apply_blocks(blocks, strict_duplicates=False):
+    utxos = {}
+    spent = 0
+    missing_spends = []
+    duplicate_outputs = []
+    total_coinbase = 0
+    total_fees = 0
+    normal_txs = 0
+
+    for height, block in enumerate(blocks):
+        if block["computed_merkle_root"] != block["merkle_root"]:
+            raise ParseError("bad merkle root at height %d" % height)
+        for tx in block["transactions"]:
+            coinbase = is_coinbase(tx)
+            input_value = 0
+            output_value = sum(out["value_satoshis"] for out in tx["vout"])
+            if coinbase:
+                total_coinbase += output_value
+            else:
+                normal_txs += 1
+                for txin in tx["vin"]:
+                    prev = "%s:%d" % (txin["prevout_hash"], txin["prevout_n"])
+                    prev_utxo = utxos.pop(prev, None)
+                    if prev_utxo is None:
+                        missing_spends.append({
+                            "height": height,
+                            "txid": tx["txid"],
+                            "missing_outpoint": prev,
+                        })
+                    else:
+                        spent += prev_utxo["value_satoshis"]
+                        input_value += prev_utxo["value_satoshis"]
+                if input_value >= output_value:
+                    total_fees += input_value - output_value
+            for n, out in enumerate(tx["vout"]):
+                key = "%s:%d" % (tx["txid"], n)
+                if key in utxos:
+                    duplicate_outputs.append({"height": height, "outpoint": key})
+                    if strict_duplicates:
+                        raise ParseError("duplicate output at height %d: %s" % (height, key))
+                utxos[key] = {
+                    "txid": tx["txid"],
+                    "vout": n,
+                    "value_satoshis": out["value_satoshis"],
+                    "value_btf": out["value_btf"],
+                    "script_pub_key_hex": out["script_pub_key_hex"],
+                    "created_height": height,
+                    "created_block_hash": block["hash"],
+                    "created_txid": tx["txid"],
+                    "coinbase": coinbase,
+                }
+
+    total_unspent = sum(u["value_satoshis"] for u in utxos.values())
+    return {
+        "utxos": utxos,
+        "stats": {
+            "utxo_count": len(utxos),
+            "spent_outputs": spent,
+            "total_unspent_satoshis": total_unspent,
+            "total_unspent_btf": format_money(total_unspent),
+            "total_coinbase_satoshis": total_coinbase,
+            "total_coinbase_btf": format_money(total_coinbase),
+            "coinbase_minus_unspent_satoshis": total_coinbase - total_unspent,
+            "coinbase_minus_unspent_btf": format_money(total_coinbase - total_unspent),
+            "total_fees_satoshis": total_fees,
+            "total_fees_btf": format_money(total_fees),
+            "normal_transactions": normal_txs,
+            "missing_spends": missing_spends,
+            "duplicate_outputs": duplicate_outputs,
+        },
+    }
+
+
+def genesis_transaction():
+    script_sig = (
+        bytes.fromhex("04ffff001d")
+        + b"\x01\x04"
+        + bytes([len(GENESIS_TEXT)])
+        + GENESIS_TEXT.encode("ascii")
+    )
+    pubkey_num = bytes.fromhex(
+        "5f1df16b2b704c8a578d0bbaf74d385cde12c11ee50455f3c438ef4c3fbcf649"
+        "b6de611feae06279a60939e028a8d65c10b73071a6f16719274855feb0fd8a6704"
+    )
+    script_pub_key = bytes([65]) + pubkey_num[::-1] + b"\xac"
+    tx = {
+        "version": 1,
+        "vin": [{
+            "prevout_hash": "0" * 64,
+            "prevout_n": 0xFFFFFFFF,
+            "script_sig_hex": script_sig.hex(),
+            "sequence": 0xFFFFFFFF,
+        }],
+        "vout": [{
+            "value_satoshis": 50 * COIN,
+            "value_btf": format_money(50 * COIN),
+            "script_pub_key_hex": script_pub_key.hex(),
+        }],
+        "lock_time": 0,
+    }
+    tx["txid"] = hash_hex(ser_tx(tx))
+    return tx
+
+
+def reconstructed_genesis():
+    tx = genesis_transaction()
+    header = (
+        struct.pack("<i", 1)
+        + bytes(32)
+        + bytes.fromhex(tx["txid"])[::-1]
+        + struct.pack("<III", GENESIS_TIME, GENESIS_BITS, GENESIS_NONCE)
+    )
+    return {
+        "hash": hash_hex(header),
+        "version": 1,
+        "previous_hash": "0" * 64,
+        "merkle_root": tx["txid"],
+        "computed_merkle_root": tx["txid"],
+        "time": GENESIS_TIME,
+        "time_utc": utc(GENESIS_TIME),
+        "bits": "0x%08x" % GENESIS_BITS,
+        "nonce": GENESIS_NONCE,
+        "tx_count": 1,
+        "transactions": [tx],
+        "source_file": "reconstructed-from-source-constants",
+        "source_offset": 0,
+        "size": 80 + len(ser_compact_size(1)) + len(ser_tx(tx)),
+    }
+
+
+def ser_block(block):
+    header = (
+        struct.pack("<i", block["version"])
+        + bytes.fromhex(block["previous_hash"])[::-1]
+        + bytes.fromhex(block["merkle_root"])[::-1]
+        + struct.pack("<III", block["time"], int(block["bits"], 16), block["nonce"])
+    )
+    txs = block["transactions"]
+    return header + ser_compact_size(len(txs)) + b"".join(ser_tx(tx) for tx in txs)
+
+
+def format_money(value):
+    sign = "-" if value < 0 else ""
+    value = abs(value)
+    return "%s%d.%08d" % (sign, value // COIN, value % COIN)
+
+
+def utc(ts):
+    return _dt.datetime.fromtimestamp(ts, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def default_datadir():
+    if os.name == "nt" and os.environ.get("APPDATA"):
+        return os.path.join(os.environ["APPDATA"], "Bitflash")
+    if os.environ.get("HOME"):
+        return os.path.join(os.environ["HOME"], ".bitflash")
+    return "."
+
+
+def canonical_bytes(report):
+    return (json.dumps(report, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
diff --git a/scripts/build-explorer.py b/scripts/build-explorer.py
index 7849e8a..0d86b3c 100755
--- a/scripts/build-explorer.py
+++ b/scripts/build-explorer.py
@@ -1,134 +1,161 @@
 #!/usr/bin/env python3
-#
-# Build a static Bitflash block explorer (v0) from a node's blk0001.dat.
-# Emits into <out-dir>:
-#   blocks.json            summary of every main-chain block (newest first)
-#   block/<height>.json    full detail per block (header + all txs)
-#   index.html             self-contained viewer (vanilla JS, same-origin fetch)
-#
-# Scope (v0, deliberately): block list, block detail, and coinbase. No mempool,
-# no per-address history. On this chain the coinbase payout key rotates every
-# block, so an address index would be nearly useless; block-level transparency is
-# what lets miners and users confirm the chain is honest.
-#
-# Usage: build-explorer.py <blk0001.dat> <out-dir>
-
-import sys, os, json, hashlib, struct
-
-MAGIC = bytes([0xbf, 0x20, 0x5c, 0xfd])
-ADDRESS_VERSION = 25  # Bitflash addresses start with "B"
-
-def sha256d(b): return hashlib.sha256(hashlib.sha256(b).digest()).digest()
+"""Build a static Bitflash block explorer from local blk*.dat files."""
 
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+
+ADDRESS_VERSION = 25
 B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
 def b58check(payload):
     v = bytes([ADDRESS_VERSION]) + payload
-    v += sha256d(v)[:4]
-    n = int.from_bytes(v, 'big')
+    v += chain.sha256d(v)[:4]
+    n = int.from_bytes(v, "big")
     s = ""
     while n > 0:
-        n, r = divmod(n, 58); s = B58[r] + s
+        n, r = divmod(n, 58)
+        s = B58[r] + s
     for byte in v:
-        if byte == 0: s = "1" + s
-        else: break
+        if byte == 0:
+            s = "1" + s
+        else:
+            break
     return s
 
+
 def hash160(b):
-    return hashlib.new('ripemd160', hashlib.sha256(b).digest()).digest()
-
-class R:
-    def __init__(s, b, o=0): s.b = b; s.o = o
-    def u(s, n): v = s.b[s.o:s.o+n]; s.o += n; return v
-    def i32(s): return struct.unpack('<i', s.u(4))[0]
-    def u32(s): return struct.unpack('<I', s.u(4))[0]
-    def i64(s): return struct.unpack('<q', s.u(8))[0]
-    def cs(s):
-        c = s.b[s.o]; s.o += 1
-        if c < 253: return c
-        if c == 253: return struct.unpack('<H', s.u(2))[0]
-        if c == 254: return struct.unpack('<I', s.u(4))[0]
-        return struct.unpack('<Q', s.u(8))[0]
-    def script(s): n = s.cs(); return s.u(n)
-
-def spk_info(spk):
-    # P2PKH: OP_DUP OP_HASH160 <20> OP_EQUALVERIFY OP_CHECKSIG
-    if len(spk) == 25 and spk[0] == 0x76 and spk[1] == 0xa9 and spk[2] == 0x14 and spk[23] == 0x88 and spk[24] == 0xac:
+    return hashlib.new("ripemd160", hashlib.sha256(b).digest()).digest()
+
+
+def spk_info(script_hex):
+    spk = bytes.fromhex(script_hex)
+    if (
+        len(spk) == 25 and spk[0] == 0x76 and spk[1] == 0xA9
+        and spk[2] == 0x14 and spk[23] == 0x88 and spk[24] == 0xAC
+    ):
         return {"type": "p2pkh", "address": b58check(spk[3:23])}
-    # P2PK: <pubkey> OP_CHECKSIG (65- or 33-byte key)
-    if len(spk) >= 35 and spk[-1] == 0xac:
+    if len(spk) >= 35 and spk[-1] == 0xAC:
         if spk[0] == 0x41 and len(spk) == 67:
-            pk = spk[1:66]; return {"type": "p2pk", "pubkey": pk.hex(), "address": b58check(hash160(pk))}
+            pk = spk[1:66]
+            return {"type": "p2pk", "pubkey": pk.hex(), "address": b58check(hash160(pk))}
         if spk[0] == 0x21 and len(spk) == 35:
-            pk = spk[1:34]; return {"type": "p2pk", "pubkey": pk.hex(), "address": b58check(hash160(pk))}
-    return {"type": "other", "hex": spk.hex()[:80]}
-
-def parse_tx(r):
-    start = r.o
-    r.i32()
-    nin = r.cs(); vin = []
-    for _ in range(nin):
-        ph = r.u(32); idx = r.u32(); r.script(); r.u32()
-        coinbase = (ph == b'\x00' * 32 and idx == 0xffffffff)
-        vin.append({"coinbase": coinbase, "prev": (None if coinbase else ph[::-1].hex()), "vout": (None if coinbase else idx)})
-    nout = r.cs(); vout = []
-    for _ in range(nout):
-        val = r.i64(); spk = r.script(); vout.append(dict({"value": val}, **spk_info(spk)))
-    r.u32()
-    raw = r.b[start:r.o]
-    return {"txid": sha256d(raw)[::-1].hex(), "vin": vin, "vout": vout, "size": len(raw)}
-
-def main():
-    if len(sys.argv) != 3:
-        print("usage: build-explorer.py <blk0001.dat> <out-dir>", file=sys.stderr); sys.exit(2)
-    blkpath, out = sys.argv[1], sys.argv[2]
-    data = open(blkpath, 'rb').read()
-    blocks = {}; o = 0; n = len(data)
-    while o + 8 <= n:
-        if data[o:o+4] != MAGIC: o += 1; continue
-        o += 4; size = struct.unpack('<I', data[o:o+4])[0]; o += 4
-        blk = data[o:o+size]; o += size
-        if len(blk) < 80: continue
-        h = sha256d(blk[:80])[::-1].hex()
-        r = R(blk, 0)
-        ver = r.i32(); prev = r.u(32)[::-1].hex(); merk = r.u(32)[::-1].hex()
-        t = r.u32(); bits = r.u32(); nonce = r.u32()
-        ntx = r.cs(); txs = []
-        try:
-            for _ in range(ntx): txs.append(parse_tx(r))
-        except Exception:
-            continue
-        blocks[h] = {"hash": h, "prev": prev, "merkleRoot": merk, "version": ver,
-                     "time": t, "bits": bits, "nonce": nonce, "size": size, "txs": txs}
-    if not blocks:
-        print("no blocks parsed", file=sys.stderr); sys.exit(1)
-
-    hc = {}
-    def height(h):
-        chain = []; cur = h
-        while cur in blocks and cur not in hc:
-            chain.append(cur); cur = blocks[cur]["prev"]
-        base = hc.get(cur, 0)
-        for hh in reversed(chain): base += 1; hc[hh] = base
-        return hc[h]
-    for h in blocks: height(h)
-    tip = max(blocks, key=lambda h: hc[h])
-    chain = []; cur = tip
-    while cur in blocks: chain.append(cur); cur = blocks[cur]["prev"]
-    chain.reverse()
-
-    os.makedirs(os.path.join(out, "block"), exist_ok=True)
+            pk = spk[1:34]
+            return {"type": "p2pk", "pubkey": pk.hex(), "address": b58check(hash160(pk))}
+    return {"type": "other", "hex": script_hex[:80]}
+
+
+def explorer_tx(tx):
+    vin = []
+    for txin in tx["vin"]:
+        coinbase = (
+            txin["prevout_hash"] == "0" * 64
+            and txin["prevout_n"] == 0xFFFFFFFF
+        )
+        vin.append({
+            "coinbase": coinbase,
+            "prev": None if coinbase else txin["prevout_hash"],
+            "vout": None if coinbase else txin["prevout_n"],
+        })
+    vout = []
+    for out in tx["vout"]:
+        vout.append(dict({"value": out["value_satoshis"]}, **spk_info(out["script_pub_key_hex"])))
+    return {"txid": tx["txid"], "vin": vin, "vout": vout, "size": len(chain.ser_tx(tx))}
+
+
+def parse_args(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--datadir", help="Bitflash data directory containing blk*.dat")
+    ap.add_argument("--max-blocks", type=int, default=0,
+                    help="number of blocks to scan; 0 means all block files")
+    ap.add_argument("paths", nargs="+",
+                    help="with --datadir: <out-dir>; otherwise: <blk*.dat>... <out-dir>")
+    args = ap.parse_args(argv)
+    if args.datadir:
+        if len(args.paths) != 1:
+            raise SystemExit("usage with --datadir: build-explorer.py --datadir DATADIR <out-dir>")
+        args.block_files = None
+        args.out_dir = args.paths[0]
+    else:
+        if len(args.paths) < 2:
+            raise SystemExit("usage: build-explorer.py <blk*.dat>... <out-dir>")
+        args.block_files = args.paths[:-1]
+        args.out_dir = args.paths[-1]
+    return args
+
+
+def load_blocks(args):
+    if args.datadir:
+        return chain.read_blocks(args.datadir, args.max_blocks)
+    return chain.read_blocks_from_files(args.block_files, args.max_blocks)
+
+
+def build_explorer(raw_blocks, out_dir):
+    try:
+        blocks = chain.select_main_chain(raw_blocks)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
+    out = Path(out_dir)
+    (out / "block").mkdir(parents=True, exist_ok=True)
+
     summaries = []
-    for h in chain:
-        b = blocks[h]; H = hc[h]
-        cb = b["txs"][0]["vout"][0] if b["txs"] and b["txs"][0]["vout"] else {}
-        summaries.append({"height": H, "hash": h, "time": b["time"], "nTx": len(b["txs"]),
-                          "size": b["size"], "cbValue": cb.get("value", 0), "cbAddr": cb.get("address", "")})
-        json.dump(dict({"height": H}, **b), open(os.path.join(out, "block", "%d.json" % H), "w"), separators=(',', ':'))
+    for height, block in enumerate(blocks):
+        txs = [explorer_tx(tx) for tx in block["transactions"]]
+        detail = {
+            "height": height,
+            "hash": block["hash"],
+            "prev": block["previous_hash"],
+            "merkleRoot": block["merkle_root"],
+            "version": block["version"],
+            "time": block["time"],
+            "bits": int(block["bits"], 16),
+            "nonce": block["nonce"],
+            "size": block["size"],
+            "txs": txs,
+        }
+        cb = txs[0]["vout"][0] if txs and txs[0]["vout"] else {}
+        summaries.append({
+            "height": height,
+            "hash": block["hash"],
+            "time": block["time"],
+            "nTx": len(txs),
+            "size": block["size"],
+            "cbValue": cb.get("value", 0),
+            "cbAddr": cb.get("address", ""),
+        })
+        (out / "block" / ("%d.json" % height)).write_text(
+            json.dumps(detail, sort_keys=True, separators=(",", ":")) + "\n",
+            encoding="ascii",
+        )
+
     summaries.sort(key=lambda x: -x["height"])
-    json.dump({"network": "bitflash", "tipHeight": hc[tip], "count": len(chain), "blocks": summaries},
-              open(os.path.join(out, "blocks.json"), "w"), separators=(',', ':'))
-    open(os.path.join(out, "index.html"), "w").write(INDEX_HTML)
-    print("explorer built: %d main-chain blocks, tip %d, into %s" % (len(chain), hc[tip], out))
+    (out / "blocks.json").write_text(
+        json.dumps({
+            "network": "bitflash",
+            "tipHeight": len(blocks) - 1,
+            "count": len(blocks),
+            "blocks": summaries,
+        }, sort_keys=True, separators=(",", ":")) + "\n",
+        encoding="ascii",
+    )
+    (out / "index.html").write_text(INDEX_HTML, encoding="utf-8")
+    return len(blocks), len(blocks) - 1
+
+
+def main(argv):
+    args = parse_args(argv)
+    raw_blocks = load_blocks(args)
+    if not raw_blocks:
+        raise SystemExit("no Bitflash blocks parsed")
+    count, tip = build_explorer(raw_blocks, args.out_dir)
+    print("explorer built: %d main-chain blocks, tip %d, into %s" % (count, tip, args.out_dir))
+    return 0
 
 
 INDEX_HTML = r"""<!doctype html>
@@ -144,6 +171,7 @@ INDEX_HTML = r"""<!doctype html>
   body { font: 15px/1.5 system-ui, sans-serif; margin:0; background:var(--bg); color:var(--fg); }
   header { padding:20px 24px; border-bottom:1px solid var(--line); display:flex; gap:16px; align-items:baseline; flex-wrap:wrap; }
   h1 { font-size:18px; margin:0; }
+  h2 { font-size:16px; }
   .mut { color:var(--mut); }
   .wrap { padding:16px 24px; max-width:1100px; margin:0 auto; }
   input { width:100%; max-width:420px; padding:9px 12px; border:1px solid var(--line); border-radius:8px; background:var(--card); color:var(--fg); font-size:14px; }
@@ -154,7 +182,6 @@ INDEX_HTML = r"""<!doctype html>
   tr.blk:hover td { background:var(--card); }
   code { font-size:12px; word-break:break-all; }
   .scroll { overflow-x:auto; }
-  a { color:var(--acc); text-decoration:none; }
   .card { border:1px solid var(--line); border-radius:10px; background:var(--card); padding:14px 16px; margin-top:12px; }
   .kv { display:grid; grid-template-columns:150px 1fr; gap:4px 12px; font-size:13px; }
   .kv div:nth-child(odd){ color:var(--mut); }
@@ -174,7 +201,7 @@ INDEX_HTML = r"""<!doctype html>
   <button class="link" id="home" style="display:none">back to blocks</button>
 </header>
 <div class="wrap">
-  <p class="note">Read-only view of the main chain: blocks, their transactions, and the coinbase payout. There is no mempool and no per-address history here. On Bitflash the coinbase payout key rotates every block, so an address index would say almost nothing; what matters is that every block and every coinbase is here to check.</p>
+  <p class="note">Read-only view of the main chain: blocks, their transactions, and the coinbase payout. There is no mempool and no per-address history here.</p>
   <div id="listview">
     <input id="q" placeholder="Search by height or block hash">
     <div class="scroll"><table>
@@ -186,52 +213,114 @@ INDEX_HTML = r"""<!doctype html>
   <div id="detail" style="display:none"></div>
 </div>
 <script>
-var SUM = [], BYH = {}, SHOWN = 200;
+var SUM = [], SHOWN = 200;
 function btf(sat){ return (sat/1e8).toFixed(8).replace(/0+$/,'').replace(/\.$/,'')+" BTF"; }
 function ts(t){ return new Date(t*1000).toISOString().replace('T',' ').replace('.000Z',' UTC'); }
-function esc(s){ return String(s).replace(/[&<>]/g,function(c){return {'&':'&amp;','<':'&lt;','>':'&gt;'}[c];}); }
-function short(h){ return h ? h.slice(0,10)+"…"+h.slice(-6) : "-"; }
-
+function short(h){ return h ? h.slice(0,10)+"..."+h.slice(-6) : "-"; }
+function E(tag, cls, text){
+  var e = document.createElement(tag);
+  if(cls) e.className = cls;
+  if(text !== undefined) e.textContent = text;
+  return e;
+}
+function code(text){ return E('code', '', text); }
+function clear(e){ while(e.firstChild) e.removeChild(e.firstChild); }
+function append(parent){
+  for(var i=1;i<arguments.length;i++) parent.appendChild(arguments[i]);
+  return parent;
+}
+function row(cells, cls){
+  var tr = E('tr', cls || '');
+  cells.forEach(function(c){ append(tr, E('td', '', c)); });
+  return tr;
+}
 function renderList(filter){
-  var q=(filter||"").trim().toLowerCase(), rows=document.getElementById('rows'), out="";
+  var q=(filter||"").trim().toLowerCase(), rows=document.getElementById('rows');
+  clear(rows);
   var list = q ? SUM.filter(function(b){ return String(b.height)===q || b.hash.indexOf(q)===0; }) : SUM.slice(0,SHOWN);
-  for(var i=0;i<list.length;i++){ var b=list[i];
-    out += '<tr class="blk" data-h="'+b.height+'"><td>'+b.height+'</td><td>'+ts(b.time)+'</td><td>'+b.nTx+'</td><td>'+b.size+' B</td><td>'+btf(b.cbValue)+'</td><td><code>'+(b.cbAddr?esc(b.cbAddr):'-')+'</code></td></tr>';
+  if(!list.length){
+    var empty = E('tr');
+    var td = E('td', 'mut', 'no match');
+    td.colSpan = 6;
+    append(empty, td); append(rows, empty);
   }
-  rows.innerHTML = out || '<tr><td colspan="6" class="mut">no match</td></tr>';
+  list.forEach(function(b){
+    var tr = row([String(b.height), ts(b.time), String(b.nTx), b.size+' B', btf(b.cbValue), ''], 'blk');
+    tr.dataset.h = b.height;
+    clear(tr.children[5]);
+    append(tr.children[5], code(b.cbAddr || '-'));
+    tr.onclick = function(){ openBlock(tr.dataset.h); };
+    append(rows, tr);
+  });
   document.getElementById('more').textContent = (!q && SUM.length>SHOWN) ? ("showing latest "+SHOWN+" of "+SUM.length+" blocks; search to find any") : "";
-  Array.prototype.forEach.call(rows.querySelectorAll('tr.blk'), function(tr){ tr.onclick=function(){ openBlock(tr.getAttribute('data-h')); }; });
 }
-function ioSide(title, items, html){
-  var s='<div><div class="mut">'+title+'</div>'; for(var i=0;i<items.length;i++){ s+=html(items[i]); } return s+'</div>';
+function kv(parent, key, value, isCode){
+  append(parent, E('div', '', key));
+  append(parent, isCode ? append(E('div'), code(value)) : E('div', '', value));
+}
+function ioSide(title, items, render){
+  var side = E('div');
+  append(side, E('div', 'mut', title));
+  items.forEach(function(item){ append(side, render(item)); });
+  return side;
 }
 function openBlock(h){
   fetch('block/'+h+'.json').then(function(r){return r.json();}).then(function(b){
-    var s='<div class="card"><div class="kv">'+
-      '<div>Height</div><div>'+b.height+'</div>'+
-      '<div>Hash</div><div><code>'+esc(b.hash)+'</code></div>'+
-      '<div>Previous</div><div><button class="link" onclick="openBlock('+(b.height-1)+')"><code>'+esc(short(b.prev))+'</code></button></div>'+
-      '<div>Merkle root</div><div><code>'+esc(b.merkleRoot)+'</code></div>'+
-      '<div>Time (UTC)</div><div>'+ts(b.time)+'</div>'+
-      '<div>Bits / Nonce</div><div>'+b.bits.toString(16)+' / '+b.nonce+'</div>'+
-      '<div>Size / Txs</div><div>'+b.size+' B / '+b.txs.length+'</div>'+
-      '</div></div>';
-    for(var i=0;i<b.txs.length;i++){ var t=b.txs[i];
-      s+='<div class="tx"><div><code>'+esc(t.txid)+'</code> '+(i===0?'<span class="pill">coinbase</span>':'')+'</div><div class="io">';
-      s+=ioSide('Inputs', t.vin, function(v){ return '<div>'+(v.coinbase?'<span class="pill">coinbase</span>':'<code>'+esc(short(v.prev))+':'+v.vout+'</code>')+'</div>'; });
-      s+=ioSide('Outputs', t.vout, function(o){ var to=o.address?esc(o.address):(o.pubkey?'pubkey '+esc(o.pubkey.slice(0,16))+'…':esc(o.type)); return '<div>'+btf(o.value)+' → <code>'+to+'</code></div>'; });
-      s+='</div></div>';
+    var detail = document.getElementById('detail');
+    clear(detail);
+    append(detail, E('h2', '', 'Block '+b.height));
+    var card = E('div', 'card'), grid = E('div', 'kv');
+    kv(grid, 'Height', String(b.height));
+    kv(grid, 'Hash', b.hash, true);
+    var prev = E('div');
+    if(b.height > 0){
+      var btn = E('button', 'link');
+      append(btn, code(short(b.prev)));
+      btn.onclick = function(){ openBlock(b.height - 1); };
+      append(prev, btn);
+    } else {
+      append(prev, code(short(b.prev)));
     }
+    append(grid, E('div', '', 'Previous'), prev);
+    kv(grid, 'Merkle root', b.merkleRoot, true);
+    kv(grid, 'Time (UTC)', ts(b.time));
+    kv(grid, 'Bits / Nonce', b.bits.toString(16)+' / '+b.nonce);
+    kv(grid, 'Size / Txs', b.size+' B / '+b.txs.length);
+    append(card, grid); append(detail, card);
+    b.txs.forEach(function(t, i){
+      var tx = E('div', 'tx');
+      var head = E('div');
+      append(head, code(t.txid));
+      if(i === 0) append(head, E('span', 'pill', 'coinbase'));
+      var io = E('div', 'io');
+      append(io, ioSide('Inputs', t.vin, function(v){
+        var d = E('div');
+        if(v.coinbase) append(d, E('span', 'pill', 'coinbase'));
+        else append(d, code(short(v.prev)+':'+v.vout));
+        return d;
+      }));
+      append(io, ioSide('Outputs', t.vout, function(o){
+        var d = E('div');
+        var to = o.address ? o.address : (o.pubkey ? 'pubkey '+o.pubkey.slice(0,16)+'...' : o.type);
+        append(d, document.createTextNode(btf(o.value)+' -> '), code(to));
+        return d;
+      }));
+      append(tx, head, io); append(detail, tx);
+    });
     document.getElementById('listview').style.display='none';
-    var d=document.getElementById('detail'); d.style.display='block'; d.innerHTML='<h2 style="font-size:16px">Block '+b.height+'</h2>'+s;
+    detail.style.display='block';
     document.getElementById('home').style.display='inline';
     window.scrollTo(0,0);
   });
 }
-document.getElementById('home').onclick=function(){ document.getElementById('detail').style.display='none'; document.getElementById('listview').style.display='block'; this.style.display='none'; };
+document.getElementById('home').onclick=function(){
+  document.getElementById('detail').style.display='none';
+  document.getElementById('listview').style.display='block';
+  this.style.display='none';
+};
 document.getElementById('q').oninput=function(){ renderList(this.value); };
 fetch('blocks.json').then(function(r){return r.json();}).then(function(d){
-  SUM=d.blocks; document.getElementById('tip').textContent='tip height '+d.tipHeight+' · '+d.count+' blocks';
+  SUM=d.blocks; document.getElementById('tip').textContent='tip height '+d.tipHeight+' - '+d.count+' blocks';
   renderList('');
 });
 </script>
@@ -239,5 +328,6 @@ fetch('blocks.json').then(function(r){return r.json();}).then(function(d){
 </html>
 """
 
+
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/prove-utxo.py b/scripts/prove-utxo.py
index 7a10d2a..9f2704b 100644
--- a/scripts/prove-utxo.py
+++ b/scripts/prove-utxo.py
@@ -7,27 +7,16 @@ included in the deterministic UTXO root produced by verify-utxo-set.py.
 
 import argparse
 import hashlib
-import importlib.util
 import json
-import os
 import sys
 from pathlib import Path
 
+import bitflash_chain as chain
 
 SCHEMA = "bitflash-utxo-inclusion-proof-1"
 NODE_DOMAIN = b"BTFNODE1|"
 
 
-def load_utxo_tool():
-    path = Path(__file__).with_name("verify-utxo-set.py")
-    spec = importlib.util.spec_from_file_location("bitflash_verify_utxo_set", path)
-    if spec is None or spec.loader is None:
-        raise SystemExit("could not load %s" % path)
-    mod = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(mod)
-    return mod
-
-
 def canonical_bytes(obj):
     return (json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
 
@@ -80,25 +69,27 @@ def build_merkle_proof(keys, leaf_hashes, index):
 
 
 def build_proof(args):
-    tool = load_utxo_tool()
     txid, vout = split_outpoint(args.outpoint)
     outpoint = "%s:%d" % (txid, vout)
 
-    raw_blocks = tool.read_blocks(args.datadir, args.max_blocks)
+    raw_blocks = chain.read_blocks(args.datadir, args.max_blocks)
     if not raw_blocks:
         raise SystemExit("no Bitflash blocks found in %s" % args.datadir)
-    blocks = tool.select_main_chain(raw_blocks)
-    state = tool.apply_blocks(blocks)
+    try:
+        blocks = chain.select_main_chain(raw_blocks)
+        state = chain.apply_blocks(blocks, strict_duplicates=args.strict_duplicates)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
     utxos = state["utxos"]
     stats = state["stats"]
     if outpoint not in utxos:
         raise SystemExit("outpoint is not unspent in the scanned chain: %s" % outpoint)
 
     keys = sorted(utxos)
-    leaf_hashes = [tool.utxo_leaf_hash(k, utxos[k]) for k in keys]
+    leaf_hashes = [chain.utxo_leaf_hash(k, utxos[k]) for k in keys]
     index = keys.index(outpoint)
     proof_path, root = build_merkle_proof(keys, leaf_hashes, index)
-    direct_root = tool.utxo_root(utxos)
+    direct_root = chain.utxo_root(utxos)
     if root != direct_root:
         raise SystemExit("internal proof root mismatch")
 
@@ -110,8 +101,8 @@ def build_proof(args):
         "chain": {
             "name": "Bitflash",
             "ticker": "BTF",
-            "message_start_hex": tool.MAGIC.hex(),
-            "coin": tool.COIN,
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
         },
         "commitment": {
             "algorithm": "sorted-outpoint-merkle-sha256",
@@ -169,20 +160,14 @@ def print_text(proof):
     print("Verdict: %s" % proof["verdict"])
 
 
-def default_datadir():
-    if os.name == "nt" and os.environ.get("APPDATA"):
-        return os.path.join(os.environ["APPDATA"], "Bitflash")
-    if os.environ.get("HOME"):
-        return os.path.join(os.environ["HOME"], ".bitflash")
-    return "."
-
-
 def main(argv):
     ap = argparse.ArgumentParser(description=__doc__)
     ap.add_argument("outpoint", help="unspent output to prove, as txid:vout")
-    ap.add_argument("--datadir", default=default_datadir(), help="Bitflash data directory")
+    ap.add_argument("--datadir", default=chain.default_datadir(), help="Bitflash data directory")
     ap.add_argument("--max-blocks", type=int, default=0,
                     help="number of blocks to scan; 0 means all block files")
+    ap.add_argument("--strict-duplicates", action="store_true",
+                    help="fail instead of using legacy last-write-wins duplicate output handling")
     ap.add_argument("--json", action="store_true", help="print canonical JSON")
     ap.add_argument("--out", help="write canonical JSON proof to this path")
     args = ap.parse_args(argv)
diff --git a/scripts/verify-fair-launch.py b/scripts/verify-fair-launch.py
index ce396fb..c33c8be 100644
--- a/scripts/verify-fair-launch.py
+++ b/scripts/verify-fair-launch.py
@@ -1,299 +1,12 @@
 #!/usr/bin/env python3
-"""Produce a deterministic Bitflash fair-launch audit report.
-
-This verifier is intentionally self-contained. It parses Bitflash block files
-directly, without Berkeley DB, without the node binary, and without network
-access. The canonical JSON output is stable for the same inputs and can be
-timestamped later with OpenTimestamps or any other external notary.
-"""
+"""Produce a deterministic Bitflash fair-launch audit report."""
 
 import argparse
-import datetime as _dt
 import hashlib
-import json
-import os
-import struct
 import sys
 from pathlib import Path
 
-
-MAGIC = bytes([0xBF, 0x20, 0x5C, 0xFD])
-COIN = 100_000_000
-GENESIS_HASH = "5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169"
-GENESIS_MERKLE = "1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325"
-GENESIS_TIME = 1_753_315_200
-GENESIS_BITS = 0x1F0FFFFF
-GENESIS_NONCE = 3141
-GENESIS_TEXT = "Bitflash 24/Jul/2026 Fair launch: one CPU one vote, no premine"
-
-
-class ParseError(Exception):
-    pass
-
-
-class Reader:
-    def __init__(self, data):
-        self.data = data
-        self.pos = 0
-
-    def take(self, n):
-        if self.pos + n > len(self.data):
-            raise ParseError("unexpected end of data")
-        out = self.data[self.pos:self.pos + n]
-        self.pos += n
-        return out
-
-    def u8(self):
-        return self.take(1)[0]
-
-    def u32(self):
-        return struct.unpack("<I", self.take(4))[0]
-
-    def i32(self):
-        return struct.unpack("<i", self.take(4))[0]
-
-    def i64(self):
-        return struct.unpack("<q", self.take(8))[0]
-
-
-def sha256d(data):
-    return hashlib.sha256(hashlib.sha256(data).digest()).digest()
-
-
-def hash_hex(serialized):
-    return sha256d(serialized)[::-1].hex()
-
-
-def compact_size(r):
-    first = r.u8()
-    if first < 253:
-        return first
-    if first == 253:
-        return struct.unpack("<H", r.take(2))[0]
-    if first == 254:
-        return r.u32()
-    return struct.unpack("<Q", r.take(8))[0]
-
-
-def read_varbytes(r):
-    return r.take(compact_size(r))
-
-
-def ser_compact_size(n):
-    if n < 253:
-        return bytes([n])
-    if n <= 0xFFFF:
-        return b"\xfd" + struct.pack("<H", n)
-    if n <= 0xFFFFFFFF:
-        return b"\xfe" + struct.pack("<I", n)
-    return b"\xff" + struct.pack("<Q", n)
-
-
-def ser_varbytes(b):
-    return ser_compact_size(len(b)) + b
-
-
-def ser_tx(tx):
-    out = bytearray()
-    out += struct.pack("<i", tx["version"])
-    out += ser_compact_size(len(tx["vin"]))
-    for txin in tx["vin"]:
-        out += bytes.fromhex(txin["prevout_hash"])[::-1]
-        out += struct.pack("<I", txin["prevout_n"])
-        out += ser_varbytes(bytes.fromhex(txin["script_sig_hex"]))
-        out += struct.pack("<I", txin["sequence"])
-    out += ser_compact_size(len(tx["vout"]))
-    for txout in tx["vout"]:
-        out += struct.pack("<q", txout["value_satoshis"])
-        out += ser_varbytes(bytes.fromhex(txout["script_pub_key_hex"]))
-    out += struct.pack("<I", tx["lock_time"])
-    return bytes(out)
-
-
-def parse_tx(r):
-    start = r.pos
-    tx = {"version": r.i32(), "vin": [], "vout": [], "lock_time": 0}
-    for _ in range(compact_size(r)):
-        prev_hash = r.take(32)[::-1].hex()
-        prev_n = r.u32()
-        script = read_varbytes(r).hex()
-        sequence = r.u32()
-        tx["vin"].append({
-            "prevout_hash": prev_hash,
-            "prevout_n": prev_n,
-            "script_sig_hex": script,
-            "sequence": sequence,
-        })
-    for _ in range(compact_size(r)):
-        value = r.i64()
-        script = read_varbytes(r).hex()
-        tx["vout"].append({
-            "value_satoshis": value,
-            "value_btf": format_money(value),
-            "script_pub_key_hex": script,
-        })
-    tx["lock_time"] = r.u32()
-    raw = r.data[start:r.pos]
-    tx["txid"] = hash_hex(raw)
-    return tx
-
-
-def merkle_root(txids):
-    if not txids:
-        return "0" * 64
-    layer = [bytes.fromhex(x)[::-1] for x in txids]
-    while len(layer) > 1:
-        nxt = []
-        for i in range(0, len(layer), 2):
-            left = layer[i]
-            right = layer[i + 1] if i + 1 < len(layer) else left
-            nxt.append(sha256d(left + right))
-        layer = nxt
-    return layer[0][::-1].hex()
-
-
-def parse_block(payload, file_name="", offset=0):
-    r = Reader(payload)
-    header = r.take(80)
-    version, = struct.unpack("<i", header[0:4])
-    prev = header[4:36][::-1].hex()
-    merkle = header[36:68][::-1].hex()
-    ntime, bits, nonce = struct.unpack("<III", header[68:80])
-    txs = [parse_tx(r) for _ in range(compact_size(r))]
-    if r.pos != len(payload):
-        raise ParseError("trailing bytes inside block")
-    txids = [tx["txid"] for tx in txs]
-    return {
-        "hash": hash_hex(header),
-        "version": version,
-        "previous_hash": prev,
-        "merkle_root": merkle,
-        "computed_merkle_root": merkle_root(txids),
-        "time": ntime,
-        "time_utc": utc(ntime),
-        "bits": "0x%08x" % bits,
-        "nonce": nonce,
-        "tx_count": len(txs),
-        "transactions": txs,
-        "source_file": file_name,
-        "source_offset": offset,
-    }
-
-
-def iter_block_files(datadir):
-    for path in sorted(Path(datadir).glob("blk*.dat")):
-        yield path
-
-
-def read_blocks(datadir, limit):
-    blocks = []
-    for path in iter_block_files(datadir):
-        data = path.read_bytes()
-        pos = 0
-        while True:
-            idx = data.find(MAGIC, pos)
-            if idx < 0:
-                break
-            if idx + 8 > len(data):
-                break
-            size = struct.unpack("<I", data[idx + 4:idx + 8])[0]
-            start = idx + 8
-            end = start + size
-            if end > len(data):
-                break
-            blocks.append(parse_block(data[start:end], path.name, start))
-            if limit and len(blocks) >= limit:
-                return blocks
-            pos = end
-    return blocks
-
-
-def genesis_transaction():
-    script_sig = (
-        bytes.fromhex("04ffff001d")
-        + b"\x01\x04"
-        + bytes([len(GENESIS_TEXT)])
-        + GENESIS_TEXT.encode("ascii")
-    )
-    pubkey_num = bytes.fromhex(
-        "5f1df16b2b704c8a578d0bbaf74d385cde12c11ee50455f3c438ef4c3fbcf649"
-        "b6de611feae06279a60939e028a8d65c10b73071a6f16719274855feb0fd8a6704"
-    )
-    # The genesis source uses CScript << CBigNum("0x..."), and CBigNum::getvch()
-    # returns the minimal little-endian script number representation.
-    script_pub_key = bytes([65]) + pubkey_num[::-1] + b"\xac"
-    tx = {
-        "version": 1,
-        "vin": [{
-            "prevout_hash": "0" * 64,
-            "prevout_n": 0xFFFFFFFF,
-            "script_sig_hex": script_sig.hex(),
-            "sequence": 0xFFFFFFFF,
-        }],
-        "vout": [{
-            "value_satoshis": 50 * COIN,
-            "value_btf": format_money(50 * COIN),
-            "script_pub_key_hex": script_pub_key.hex(),
-        }],
-        "lock_time": 0,
-    }
-    tx["txid"] = hash_hex(ser_tx(tx))
-    return tx
-
-
-def reconstructed_genesis():
-    tx = genesis_transaction()
-    header = (
-        struct.pack("<i", 1)
-        + bytes(32)
-        + bytes.fromhex(tx["txid"])[::-1]
-        + struct.pack("<III", GENESIS_TIME, GENESIS_BITS, GENESIS_NONCE)
-    )
-    return {
-        "hash": hash_hex(header),
-        "version": 1,
-        "previous_hash": "0" * 64,
-        "merkle_root": tx["txid"],
-        "computed_merkle_root": tx["txid"],
-        "time": GENESIS_TIME,
-        "time_utc": utc(GENESIS_TIME),
-        "bits": "0x%08x" % GENESIS_BITS,
-        "nonce": GENESIS_NONCE,
-        "tx_count": 1,
-        "transactions": [tx],
-        "source_file": "reconstructed-from-source-constants",
-        "source_offset": 0,
-    }
-
-
-def format_money(value):
-    sign = "-" if value < 0 else ""
-    value = abs(value)
-    return "%s%d.%08d" % (sign, value // COIN, value % COIN)
-
-
-def utc(ts):
-    return _dt.datetime.fromtimestamp(ts, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def default_datadir():
-    if os.name == "nt" and os.environ.get("APPDATA"):
-        return os.path.join(os.environ["APPDATA"], "Bitflash")
-    if os.environ.get("HOME"):
-        return os.path.join(os.environ["HOME"], ".bitflash")
-    return "."
-
-
-def is_coinbase(tx):
-    return (
-        len(tx["vin"]) == 1
-        and tx["vin"][0]["prevout_hash"] == "0" * 64
-        and tx["vin"][0]["prevout_n"] == 0xFFFFFFFF
-    )
-
-
-def canonical_bytes(report):
-    return (json.dumps(report, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
+import bitflash_chain as chain
 
 
 def build_report(blocks, source_mode):
@@ -307,7 +20,7 @@ def build_report(blocks, source_mode):
         if not block["transactions"]:
             continue
         cb = block["transactions"][0]
-        if is_coinbase(cb):
+        if chain.is_coinbase(cb):
             amount = sum(out["value_satoshis"] for out in cb["vout"])
             total_mined += amount
             coinbase_outputs.append({
@@ -315,18 +28,18 @@ def build_report(blocks, source_mode):
                 "block_hash": block["hash"],
                 "coinbase_txid": cb["txid"],
                 "value_satoshis": amount,
-                "value_btf": format_money(amount),
+                "value_btf": chain.format_money(amount),
                 "outputs": cb["vout"],
             })
-        non_coinbase_txs += sum(1 for tx in block["transactions"] if not is_coinbase(tx))
+        non_coinbase_txs += sum(1 for tx in block["transactions"] if not chain.is_coinbase(tx))
 
     checks = {
-        "genesis_hash_matches_source": genesis["hash"] == GENESIS_HASH,
-        "genesis_merkle_matches_source": genesis["merkle_root"] == GENESIS_MERKLE,
+        "genesis_hash_matches_source": genesis["hash"] == chain.GENESIS_HASH,
+        "genesis_merkle_matches_source": genesis["merkle_root"] == chain.GENESIS_MERKLE,
         "computed_merkle_matches_header": genesis["computed_merkle_root"] == genesis["merkle_root"],
         "genesis_has_single_transaction": genesis["tx_count"] == 1,
-        "genesis_transaction_is_coinbase": bool(genesis["transactions"] and is_coinbase(genesis["transactions"][0])),
-        "genesis_supply_is_50_btf": sum(out["value_satoshis"] for out in launch_outputs) == 50 * COIN,
+        "genesis_transaction_is_coinbase": bool(genesis["transactions"] and chain.is_coinbase(genesis["transactions"][0])),
+        "genesis_supply_is_50_btf": sum(out["value_satoshis"] for out in launch_outputs) == 50 * chain.COIN,
     }
 
     report = {
@@ -336,17 +49,17 @@ def build_report(blocks, source_mode):
         "chain": {
             "name": "Bitflash",
             "ticker": "BTF",
-            "message_start_hex": MAGIC.hex(),
-            "coin": COIN,
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
         },
         "source_constants": {
-            "genesis_hash": GENESIS_HASH,
-            "genesis_merkle_root": GENESIS_MERKLE,
-            "genesis_time": GENESIS_TIME,
-            "genesis_time_utc": utc(GENESIS_TIME),
-            "genesis_bits": "0x%08x" % GENESIS_BITS,
-            "genesis_nonce": GENESIS_NONCE,
-            "genesis_message": GENESIS_TEXT,
+            "genesis_hash": chain.GENESIS_HASH,
+            "genesis_merkle_root": chain.GENESIS_MERKLE,
+            "genesis_time": chain.GENESIS_TIME,
+            "genesis_time_utc": chain.utc(chain.GENESIS_TIME),
+            "genesis_bits": "0x%08x" % chain.GENESIS_BITS,
+            "genesis_nonce": chain.GENESIS_NONCE,
+            "genesis_message": chain.GENESIS_TEXT,
         },
         "scanned": {
             "block_count": len(blocks),
@@ -354,7 +67,7 @@ def build_report(blocks, source_mode):
             "last_height": len(blocks) - 1,
             "non_coinbase_transactions": non_coinbase_txs,
             "total_coinbase_satoshis": total_mined,
-            "total_coinbase_btf": format_money(total_mined),
+            "total_coinbase_btf": chain.format_money(total_mined),
         },
         "genesis": {
             "hash": genesis["hash"],
@@ -381,7 +94,7 @@ def build_report(blocks, source_mode):
             ],
         },
     }
-    report["attestation_payload_sha256"] = hashlib.sha256(canonical_bytes(report)).hexdigest()
+    report["attestation_payload_sha256"] = hashlib.sha256(chain.canonical_bytes(report)).hexdigest()
     return report
 
 
@@ -397,7 +110,7 @@ def print_text(report):
     print("  merkle:  %s" % report["genesis"]["merkle_root"])
     print("  time:    %s" % report["genesis"]["time_utc"])
     print("  txs:     %d" % report["genesis"]["tx_count"])
-    print("  supply:  %s BTF" % format_money(sum(o["value_satoshis"] for o in report["genesis"]["outputs"])))
+    print("  supply:  %s BTF" % chain.format_money(sum(o["value_satoshis"] for o in report["genesis"]["outputs"])))
     print()
     print("Scanned")
     print("  blocks:  %d" % report["scanned"]["block_count"])
@@ -417,7 +130,7 @@ def print_text(report):
 
 def main(argv):
     ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--datadir", default=default_datadir(), help="Bitflash data directory")
+    ap.add_argument("--datadir", default=chain.default_datadir(), help="Bitflash data directory")
     ap.add_argument("--max-blocks", type=int, default=100, help="number of blocks to scan from blk*.dat")
     ap.add_argument("--json", action="store_true", help="print canonical JSON")
     ap.add_argument("--out", help="write canonical JSON to this path")
@@ -426,18 +139,19 @@ def main(argv):
     args = ap.parse_args(argv)
 
     if args.reconstruct_genesis:
-        blocks = [reconstructed_genesis()]
+        blocks = [chain.reconstructed_genesis()]
         source_mode = "reconstructed-genesis"
-        datadir = ""
     else:
-        datadir = Path(args.datadir)
-        blocks = read_blocks(datadir, args.max_blocks)
+        blocks = chain.read_blocks(args.datadir, args.max_blocks)
         if not blocks:
-            raise SystemExit("no Bitflash blocks found in %s; use --reconstruct-genesis for a source-only check" % datadir)
+            raise SystemExit("no Bitflash blocks found in %s; use --reconstruct-genesis for a source-only check" % args.datadir)
         source_mode = "local-block-files"
 
-    report = build_report(blocks, source_mode)
-    data = canonical_bytes(report)
+    try:
+        report = build_report(blocks, source_mode)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
+    data = chain.canonical_bytes(report)
 
     if args.out:
         Path(args.out).write_bytes(data)
diff --git a/scripts/verify-utxo-proof.py b/scripts/verify-utxo-proof.py
index 31099f7..c29caa9 100644
--- a/scripts/verify-utxo-proof.py
+++ b/scripts/verify-utxo-proof.py
@@ -7,6 +7,7 @@ import json
 import sys
 from pathlib import Path
 
+import bitflash_chain as chain
 
 SCHEMA = "bitflash-utxo-inclusion-proof-1"
 LEAF_DOMAIN = "BTFUTXO1"
@@ -17,22 +18,6 @@ def canonical_bytes(obj):
     return (json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
 
 
-def sha256(data):
-    return hashlib.sha256(data).digest()
-
-
-def utxo_leaf_hash(outpoint, utxo):
-    payload = "|".join([
-        LEAF_DOMAIN,
-        outpoint,
-        str(utxo["value_satoshis"]),
-        utxo["script_pub_key_hex"],
-        str(utxo["created_height"]),
-        utxo["created_txid"],
-    ]).encode("ascii")
-    return sha256(payload)
-
-
 def load_proof(path):
     try:
         return json.loads(Path(path).read_text(encoding="ascii"))
@@ -59,7 +44,7 @@ def verify(proof, expected_root=None):
         failures.append("target outpoint does not match txid:vout")
 
     try:
-        current = utxo_leaf_hash(outpoint, utxo)
+        current = chain.utxo_leaf_hash(outpoint, utxo)
         leaf_ok = target.get("leaf_hash") == current.hex()
     except Exception as e:
         failures.append("could not hash target leaf: %s" % e)
@@ -79,9 +64,9 @@ def verify(proof, expected_root=None):
             failures.append("bad sibling hash length at proof level %d" % i)
         side = step.get("side")
         if side == "right":
-            current = sha256(NODE_DOMAIN + current + sibling)
+            current = chain.sha256(NODE_DOMAIN + current + sibling)
         elif side == "left":
-            current = sha256(NODE_DOMAIN + sibling + current)
+            current = chain.sha256(NODE_DOMAIN + sibling + current)
         else:
             failures.append("bad sibling side at proof level %d" % i)
 
diff --git a/scripts/verify-utxo-set.py b/scripts/verify-utxo-set.py
index 12b024f..b5bf3d5 100644
--- a/scripts/verify-utxo-set.py
+++ b/scripts/verify-utxo-set.py
@@ -1,363 +1,24 @@
 #!/usr/bin/env python3
-"""Build a deterministic Bitflash UTXO-set commitment from local blk*.dat.
-
-This is deliberately outside consensus. It lets auditors reconstruct the chain
-state from disk blocks and compare the same canonical UTXO root independently.
-"""
+"""Build a deterministic Bitflash UTXO-set commitment from local blk*.dat."""
 
 import argparse
-import datetime as _dt
 import hashlib
-import json
-import os
-import struct
 import sys
 from pathlib import Path
 
-
-MAGIC = bytes([0xBF, 0x20, 0x5C, 0xFD])
-COIN = 100_000_000
-GENESIS_HASH = "5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169"
-GENESIS_MERKLE = "1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325"
-
-
-class ParseError(Exception):
-    pass
-
-
-class Reader:
-    def __init__(self, data):
-        self.data = data
-        self.pos = 0
-
-    def take(self, n):
-        if self.pos + n > len(self.data):
-            raise ParseError("unexpected end of data")
-        out = self.data[self.pos:self.pos + n]
-        self.pos += n
-        return out
-
-    def u8(self):
-        return self.take(1)[0]
-
-    def u32(self):
-        return struct.unpack("<I", self.take(4))[0]
-
-    def i32(self):
-        return struct.unpack("<i", self.take(4))[0]
-
-    def i64(self):
-        return struct.unpack("<q", self.take(8))[0]
-
-
-def sha256(data):
-    return hashlib.sha256(data).digest()
-
-
-def sha256d(data):
-    return hashlib.sha256(hashlib.sha256(data).digest()).digest()
-
-
-def hash_hex(serialized):
-    return sha256d(serialized)[::-1].hex()
-
-
-def compact_size(r):
-    first = r.u8()
-    if first < 253:
-        return first
-    if first == 253:
-        return struct.unpack("<H", r.take(2))[0]
-    if first == 254:
-        return r.u32()
-    return struct.unpack("<Q", r.take(8))[0]
-
-
-def read_varbytes(r):
-    return r.take(compact_size(r))
-
-
-def ser_compact_size(n):
-    if n < 253:
-        return bytes([n])
-    if n <= 0xFFFF:
-        return b"\xfd" + struct.pack("<H", n)
-    if n <= 0xFFFFFFFF:
-        return b"\xfe" + struct.pack("<I", n)
-    return b"\xff" + struct.pack("<Q", n)
-
-
-def ser_varbytes(b):
-    return ser_compact_size(len(b)) + b
-
-
-def ser_tx(tx):
-    out = bytearray()
-    out += struct.pack("<i", tx["version"])
-    out += ser_compact_size(len(tx["vin"]))
-    for txin in tx["vin"]:
-        out += bytes.fromhex(txin["prevout_hash"])[::-1]
-        out += struct.pack("<I", txin["prevout_n"])
-        out += ser_varbytes(bytes.fromhex(txin["script_sig_hex"]))
-        out += struct.pack("<I", txin["sequence"])
-    out += ser_compact_size(len(tx["vout"]))
-    for txout in tx["vout"]:
-        out += struct.pack("<q", txout["value_satoshis"])
-        out += ser_varbytes(bytes.fromhex(txout["script_pub_key_hex"]))
-    out += struct.pack("<I", tx["lock_time"])
-    return bytes(out)
-
-
-def parse_tx(r):
-    tx = {"version": r.i32(), "vin": [], "vout": [], "lock_time": 0}
-    for _ in range(compact_size(r)):
-        tx["vin"].append({
-            "prevout_hash": r.take(32)[::-1].hex(),
-            "prevout_n": r.u32(),
-            "script_sig_hex": read_varbytes(r).hex(),
-            "sequence": r.u32(),
-        })
-    for _ in range(compact_size(r)):
-        value = r.i64()
-        tx["vout"].append({
-            "value_satoshis": value,
-            "value_btf": format_money(value),
-            "script_pub_key_hex": read_varbytes(r).hex(),
-        })
-    tx["lock_time"] = r.u32()
-    tx["txid"] = hash_hex(ser_tx(tx))
-    return tx
-
-
-def merkle_root(txids):
-    if not txids:
-        return "0" * 64
-    layer = [bytes.fromhex(x)[::-1] for x in txids]
-    while len(layer) > 1:
-        nxt = []
-        for i in range(0, len(layer), 2):
-            left = layer[i]
-            right = layer[i + 1] if i + 1 < len(layer) else left
-            nxt.append(sha256d(left + right))
-        layer = nxt
-    return layer[0][::-1].hex()
-
-
-def parse_block(payload, file_name="", offset=0):
-    r = Reader(payload)
-    header = r.take(80)
-    version, = struct.unpack("<i", header[0:4])
-    prev = header[4:36][::-1].hex()
-    merkle = header[36:68][::-1].hex()
-    ntime, bits, nonce = struct.unpack("<III", header[68:80])
-    txs = [parse_tx(r) for _ in range(compact_size(r))]
-    if r.pos != len(payload):
-        raise ParseError("trailing bytes inside block")
-    txids = [tx["txid"] for tx in txs]
-    return {
-        "hash": hash_hex(header),
-        "version": version,
-        "previous_hash": prev,
-        "merkle_root": merkle,
-        "computed_merkle_root": merkle_root(txids),
-        "time": ntime,
-        "time_utc": utc(ntime),
-        "bits": "0x%08x" % bits,
-        "nonce": nonce,
-        "tx_count": len(txs),
-        "transactions": txs,
-        "source_file": file_name,
-        "source_offset": offset,
-    }
-
-
-def read_blocks(datadir, max_blocks):
-    blocks = []
-    for path in sorted(Path(datadir).glob("blk*.dat")):
-        data = path.read_bytes()
-        pos = 0
-        while True:
-            idx = data.find(MAGIC, pos)
-            if idx < 0:
-                break
-            if idx + 8 > len(data):
-                break
-            size = struct.unpack("<I", data[idx + 4:idx + 8])[0]
-            start = idx + 8
-            end = start + size
-            if end > len(data):
-                break
-            blocks.append(parse_block(data[start:end], path.name, start))
-            if max_blocks and len(blocks) >= max_blocks:
-                return blocks
-            pos = end
-    return blocks
-
-
-def select_main_chain(blocks):
-    by_hash = {}
-    for block in blocks:
-        by_hash.setdefault(block["hash"], block)
-    if GENESIS_HASH not in by_hash:
-        raise ParseError("genesis block not found in block files")
-
-    children = {}
-    for block in by_hash.values():
-        children.setdefault(block["previous_hash"], []).append(block)
-    for v in children.values():
-        v.sort(key=lambda b: (b["hash"], b["source_file"], b["source_offset"]))
-
-    best = []
-    stack = [(by_hash[GENESIS_HASH], [by_hash[GENESIS_HASH]])]
-    while stack:
-        block, path = stack.pop()
-        if len(path) > len(best) or (len(path) == len(best) and block["hash"] < best[-1]["hash"]):
-            best = path
-        for child in children.get(block["hash"], []):
-            stack.append((child, path + [child]))
-    return best
-
-
-def is_coinbase(tx):
-    return (
-        len(tx["vin"]) == 1
-        and tx["vin"][0]["prevout_hash"] == "0" * 64
-        and tx["vin"][0]["prevout_n"] == 0xFFFFFFFF
-    )
-
-
-def utxo_leaf_hash(outpoint, utxo):
-    # Text fields are length-delimited by separators and all variable data is
-    # hex or decimal ASCII. That keeps the commitment language-neutral.
-    payload = "|".join([
-        "BTFUTXO1",
-        outpoint,
-        str(utxo["value_satoshis"]),
-        utxo["script_pub_key_hex"],
-        str(utxo["created_height"]),
-        utxo["created_txid"],
-    ]).encode("ascii")
-    return sha256(payload)
-
-
-def utxo_root(utxos):
-    leaves = [utxo_leaf_hash(k, utxos[k]) for k in sorted(utxos)]
-    if not leaves:
-        return sha256(b"BTFUTXO1|empty").hex()
-    layer = leaves
-    while len(layer) > 1:
-        nxt = []
-        for i in range(0, len(layer), 2):
-            left = layer[i]
-            right = layer[i + 1] if i + 1 < len(layer) else left
-            nxt.append(sha256(b"BTFNODE1|" + left + right))
-        layer = nxt
-    return layer[0].hex()
-
-
-def apply_blocks(blocks):
-    utxos = {}
-    spent = 0
-    missing_spends = []
-    duplicate_outputs = []
-    total_coinbase = 0
-    total_fees = 0
-    normal_txs = 0
-
-    for height, block in enumerate(blocks):
-        if block["computed_merkle_root"] != block["merkle_root"]:
-            raise ParseError("bad merkle root at height %d" % height)
-        for tx_index, tx in enumerate(block["transactions"]):
-            coinbase = is_coinbase(tx)
-            input_value = 0
-            output_value = sum(out["value_satoshis"] for out in tx["vout"])
-            if coinbase:
-                total_coinbase += output_value
-            else:
-                normal_txs += 1
-                for txin in tx["vin"]:
-                    prev = "%s:%d" % (txin["prevout_hash"], txin["prevout_n"])
-                    prev_utxo = utxos.pop(prev, None)
-                    if prev_utxo is None:
-                        missing_spends.append({
-                            "height": height,
-                            "txid": tx["txid"],
-                            "missing_outpoint": prev,
-                        })
-                    else:
-                        spent += prev_utxo["value_satoshis"]
-                        input_value += prev_utxo["value_satoshis"]
-                if input_value >= output_value:
-                    total_fees += input_value - output_value
-            for n, out in enumerate(tx["vout"]):
-                key = "%s:%d" % (tx["txid"], n)
-                if key in utxos:
-                    duplicate_outputs.append({"height": height, "outpoint": key})
-                utxos[key] = {
-                    "txid": tx["txid"],
-                    "vout": n,
-                    "value_satoshis": out["value_satoshis"],
-                    "value_btf": out["value_btf"],
-                    "script_pub_key_hex": out["script_pub_key_hex"],
-                    "created_height": height,
-                    "created_block_hash": block["hash"],
-                    "created_txid": tx["txid"],
-                    "coinbase": coinbase,
-                }
-
-    total_unspent = sum(u["value_satoshis"] for u in utxos.values())
-    return {
-        "utxos": utxos,
-        "stats": {
-            "utxo_count": len(utxos),
-            "spent_outputs": spent,
-            "total_unspent_satoshis": total_unspent,
-            "total_unspent_btf": format_money(total_unspent),
-            "total_coinbase_satoshis": total_coinbase,
-            "total_coinbase_btf": format_money(total_coinbase),
-            "coinbase_minus_unspent_satoshis": total_coinbase - total_unspent,
-            "coinbase_minus_unspent_btf": format_money(total_coinbase - total_unspent),
-            "total_fees_satoshis": total_fees,
-            "total_fees_btf": format_money(total_fees),
-            "normal_transactions": normal_txs,
-            "missing_spends": missing_spends,
-            "duplicate_outputs": duplicate_outputs,
-        },
-    }
-
-
-def format_money(value):
-    sign = "-" if value < 0 else ""
-    value = abs(value)
-    return "%s%d.%08d" % (sign, value // COIN, value % COIN)
-
-
-def utc(ts):
-    return _dt.datetime.fromtimestamp(ts, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def default_datadir():
-    if os.name == "nt" and os.environ.get("APPDATA"):
-        return os.path.join(os.environ["APPDATA"], "Bitflash")
-    if os.environ.get("HOME"):
-        return os.path.join(os.environ["HOME"], ".bitflash")
-    return "."
-
-
-def canonical_bytes(report):
-    return (json.dumps(report, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
+import bitflash_chain as chain
 
 
-def build_report(raw_blocks, include_utxos=False):
-    blocks = select_main_chain(raw_blocks)
-    state = apply_blocks(blocks)
+def build_report(raw_blocks, include_utxos=False, strict_duplicates=False):
+    blocks = chain.select_main_chain(raw_blocks)
+    state = chain.apply_blocks(blocks, strict_duplicates=strict_duplicates)
     utxos = state["utxos"]
     stats = state["stats"]
     tip = blocks[-1]
-    root = utxo_root(utxos)
+    root = chain.utxo_root(utxos)
     checks = {
-        "genesis_hash_matches_source": blocks[0]["hash"] == GENESIS_HASH,
-        "genesis_merkle_matches_source": blocks[0]["merkle_root"] == GENESIS_MERKLE,
+        "genesis_hash_matches_source": blocks[0]["hash"] == chain.GENESIS_HASH,
+        "genesis_merkle_matches_source": blocks[0]["merkle_root"] == chain.GENESIS_MERKLE,
         "all_scanned_merkle_roots_match": all(b["computed_merkle_root"] == b["merkle_root"] for b in blocks),
         "no_missing_spends": len(stats["missing_spends"]) == 0,
     }
@@ -370,8 +31,8 @@ def build_report(raw_blocks, include_utxos=False):
         "chain": {
             "name": "Bitflash",
             "ticker": "BTF",
-            "message_start_hex": MAGIC.hex(),
-            "coin": COIN,
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
         },
         "commitment": {
             "algorithm": "sorted-outpoint-merkle-sha256",
@@ -400,7 +61,7 @@ def build_report(raw_blocks, include_utxos=False):
 
 
 def print_text(report):
-    data_hash = hashlib.sha256(canonical_bytes(report)).hexdigest()
+    data_hash = hashlib.sha256(chain.canonical_bytes(report)).hexdigest()
     print("Bitflash UTXO-set commitment verifier")
     print("schema: %s" % report["schema"])
     print("canonical report sha256: %s" % data_hash)
@@ -437,20 +98,26 @@ def print_text(report):
 
 def main(argv):
     ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--datadir", default=default_datadir(), help="Bitflash data directory")
+    ap.add_argument("--datadir", default=chain.default_datadir(), help="Bitflash data directory")
     ap.add_argument("--max-blocks", type=int, default=0,
                     help="number of blocks to scan; 0 means all block files")
     ap.add_argument("--include-utxos", action="store_true",
                     help="include the full sorted UTXO map in JSON output")
+    ap.add_argument("--strict-duplicates", action="store_true",
+                    help="fail instead of using legacy last-write-wins duplicate output handling")
     ap.add_argument("--json", action="store_true", help="print canonical JSON")
     ap.add_argument("--out", help="write canonical JSON to this path")
     args = ap.parse_args(argv)
 
-    blocks = read_blocks(args.datadir, args.max_blocks)
+    blocks = chain.read_blocks(args.datadir, args.max_blocks)
     if not blocks:
         raise SystemExit("no Bitflash blocks found in %s" % args.datadir)
-    report = build_report(blocks, include_utxos=args.include_utxos)
-    data = canonical_bytes(report)
+    try:
+        report = build_report(blocks, include_utxos=args.include_utxos,
+                              strict_duplicates=args.strict_duplicates)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
+    data = chain.canonical_bytes(report)
     if args.out:
         Path(args.out).write_bytes(data)
     if args.json: