13 files changed, 2294 insertions, 50 deletions

diff --git a/scripts/bitflash-mining-calculator.py b/scripts/bitflash-mining-calculator.py
new file mode 100644
index 0000000..1fcc1a9
--- /dev/null
+++ b/scripts/bitflash-mining-calculator.py
@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Estimate Bitflash mining rewards and electricity cost.
+
+This is a local WhatToMine-style calculator for Bitflash. It does not fetch
+prices, does not talk to the node, and does not affect consensus.
+"""
+
+import argparse
+import json
+import math
+import sys
+
+
+HASHES_AT_DIFF_1 = 4096.0
+DEFAULT_BLOCK_TIME = 120.0
+DEFAULT_BLOCK_REWARD = 50.0
+
+
+UNITS = {
+    "h": 1.0,
+    "h/s": 1.0,
+    "hs": 1.0,
+    "kh": 1_000.0,
+    "kh/s": 1_000.0,
+    "khs": 1_000.0,
+    "mh": 1_000_000.0,
+    "mh/s": 1_000_000.0,
+    "mhs": 1_000_000.0,
+    "gh": 1_000_000_000.0,
+    "gh/s": 1_000_000_000.0,
+    "ghs": 1_000_000_000.0,
+}
+
+
+def parse_hashrate(value, unit):
+    try:
+        n = float(value)
+    except ValueError:
+        raise SystemExit("invalid hashrate: %s" % value)
+    mul = UNITS.get(unit.lower())
+    if mul is None:
+        raise SystemExit("unknown hashrate unit: %s" % unit)
+    if n < 0:
+        raise SystemExit("hashrate must not be negative")
+    return n * mul
+
+
+def fmt_hashrate(hps):
+    units = [("GH/s", 1_000_000_000.0), ("MH/s", 1_000_000.0), ("kH/s", 1_000.0), ("H/s", 1.0)]
+    for name, div in units:
+        if hps >= div:
+            return "%.4g %s" % (hps / div, name)
+    return "%.4g H/s" % hps
+
+
+def fmt_money(x):
+    return "%.8f" % x
+
+
+def estimate(args):
+    miner_hps = parse_hashrate(args.hashrate, args.hashrate_unit)
+    if args.network_hashrate is not None:
+        network_hps = parse_hashrate(args.network_hashrate, args.network_hashrate_unit)
+        difficulty = network_hps * args.block_time / HASHES_AT_DIFF_1
+        network_source = "network_hashrate"
+    else:
+        if args.difficulty is None:
+            raise SystemExit("provide either --network-hashrate or --difficulty")
+        difficulty = float(args.difficulty)
+        if difficulty <= 0:
+            raise SystemExit("difficulty must be positive")
+        network_hps = difficulty * HASHES_AT_DIFF_1 / args.block_time
+        network_source = "difficulty"
+
+    if network_hps <= 0:
+        raise SystemExit("network hashrate must be positive")
+
+    block_reward = float(args.block_reward)
+    block_time = float(args.block_time)
+    pool_fee_percent = float(args.pool_fee)
+    price = float(args.price)
+    watts = float(args.watts)
+    kwh_cost = float(args.kwh_cost)
+    if block_reward < 0 or block_time <= 0 or pool_fee_percent < 0 or price < 0 or watts < 0 or kwh_cost < 0:
+        raise SystemExit("numeric inputs must be non-negative; block time must be positive")
+
+    share = miner_hps / network_hps
+    blocks_per_day = 86400.0 / block_time
+    gross_btf_day = blocks_per_day * block_reward * share
+    net_btf_day = gross_btf_day * max(0.0, 1.0 - pool_fee_percent / 100.0)
+    revenue_day = net_btf_day * price
+    cost_day = watts / 1000.0 * 24.0 * kwh_cost
+    profit_day = revenue_day - cost_day
+    expected_seconds_per_block = math.inf if miner_hps <= 0 else difficulty * HASHES_AT_DIFF_1 / miner_hps
+
+    periods = {
+        "hour": 1.0 / 24.0,
+        "day": 1.0,
+        "week": 7.0,
+        "month_30d": 30.0,
+    }
+    rows = {}
+    for name, days in periods.items():
+        rows[name] = {
+            "btf": net_btf_day * days,
+            "revenue": revenue_day * days,
+            "electricity_cost": cost_day * days,
+            "profit": profit_day * days,
+        }
+
+    return {
+        "schema": "bitflash-mining-calculator-1",
+        "network_source": network_source,
+        "inputs": {
+            "miner_hashrate_hps": miner_hps,
+            "miner_hashrate": fmt_hashrate(miner_hps),
+            "network_hashrate_hps": network_hps,
+            "network_hashrate": fmt_hashrate(network_hps),
+            "difficulty": difficulty,
+            "block_time_seconds": block_time,
+            "block_reward_btf": block_reward,
+            "pool_fee_percent": pool_fee_percent,
+            "price_per_btf": price,
+            "power_watts": watts,
+            "electricity_per_kwh": kwh_cost,
+        },
+        "estimates": {
+            "miner_network_share": share,
+            "blocks_per_day": blocks_per_day,
+            "expected_time_to_solo_block_seconds": expected_seconds_per_block,
+            "expected_time_to_solo_block_hours": expected_seconds_per_block / 3600.0,
+            "gross_btf_per_day": gross_btf_day,
+            "net_btf_per_day": net_btf_day,
+            "periods": rows,
+        },
+    }
+
+
+def print_text(result):
+    i = result["inputs"]
+    e = result["estimates"]
+    print("Bitflash mining calculator")
+    print("schema: %s" % result["schema"])
+    print()
+    print("Network")
+    print("  source:      %s" % result["network_source"])
+    print("  hashrate:    %s" % i["network_hashrate"])
+    print("  difficulty:  %.8f" % i["difficulty"])
+    print("  block time:  %.0fs" % i["block_time_seconds"])
+    print("  reward:      %s BTF" % fmt_money(i["block_reward_btf"]))
+    print()
+    print("Miner")
+    print("  hashrate:    %s" % i["miner_hashrate"])
+    print("  share:       %.8f%%" % (e["miner_network_share"] * 100.0))
+    if math.isinf(e["expected_time_to_solo_block_seconds"]):
+        print("  solo block:  never")
+    else:
+        print("  solo block:  %.2f hours expected average" % e["expected_time_to_solo_block_hours"])
+    print()
+    print("Economics")
+    print("  price:       $%.8f / BTF" % i["price_per_btf"])
+    print("  power:       %.2f W" % i["power_watts"])
+    print("  kWh cost:    $%.4f" % i["electricity_per_kwh"])
+    print("  pool fee:    %.2f%%" % i["pool_fee_percent"])
+    print()
+    print("Estimated rewards")
+    print("  %-9s %16s %12s %12s %12s" % ("period", "BTF", "revenue", "power", "profit"))
+    for name in ["hour", "day", "week", "month_30d"]:
+        row = e["periods"][name]
+        print("  %-9s %16s $%11.4f $%11.4f $%11.4f" % (
+            name,
+            fmt_money(row["btf"]),
+            row["revenue"],
+            row["electricity_cost"],
+            row["profit"],
+        ))
+    print()
+    print("Note: this is an expectation, not a promise. Solo mining variance can be huge.")
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--hashrate", required=True, help="miner hashrate number")
+    ap.add_argument("--hashrate-unit", default="kh/s", choices=sorted(UNITS), help="miner hashrate unit")
+    ap.add_argument("--network-hashrate", help="network hashrate number")
+    ap.add_argument("--network-hashrate-unit", default="kh/s", choices=sorted(UNITS), help="network hashrate unit")
+    ap.add_argument("--difficulty", type=float, help="Bitflash difficulty; diff 1 expects 4096 hashes")
+    ap.add_argument("--block-time", type=float, default=DEFAULT_BLOCK_TIME, help="target block time in seconds")
+    ap.add_argument("--block-reward", type=float, default=DEFAULT_BLOCK_REWARD, help="block reward in BTF")
+    ap.add_argument("--pool-fee", type=float, default=0.0, help="pool fee percent")
+    ap.add_argument("--price", type=float, default=0.0, help="price per BTF in USD or your chosen fiat unit")
+    ap.add_argument("--watts", type=float, default=0.0, help="miner or whole-system power in watts")
+    ap.add_argument("--kwh-cost", type=float, default=0.0, help="electricity cost per kWh")
+    ap.add_argument("--json", action="store_true", help="print JSON")
+    args = ap.parse_args(argv)
+
+    result = estimate(args)
+    if args.json:
+        print(json.dumps(result, sort_keys=True, indent=2))
+    else:
+        print_text(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/bitflash_chain.py b/scripts/bitflash_chain.py
new file mode 100644
index 0000000..4a3231c
--- /dev/null
+++ b/scripts/bitflash_chain.py
@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+"""Shared Bitflash block/chain parser for deterministic audit tools."""
+
+import datetime as _dt
+import hashlib
+import json
+import mmap
+import os
+import struct
+from pathlib import Path
+
+
+MAGIC = bytes([0xBF, 0x20, 0x5C, 0xFD])
+MAX_BLOCK_PAYLOAD = 32 * 1024 * 1024
+UTXO_LEAF_DOMAIN = "BTFUTXO1"
+UTXO_NODE_DOMAIN_TAG = "BTFNODE1"
+UTXO_NODE_DOMAIN = (UTXO_NODE_DOMAIN_TAG + "|").encode("ascii")
+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:
+        f.seek(0, os.SEEK_END)
+        file_size = f.tell()
+        if file_size == 0:
+            return
+        f.seek(0)
+        mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
+        try:
+            pos = 0
+            while True:
+                offset = mm.find(MAGIC, pos)
+                if offset < 0 or offset + 8 > file_size:
+                    break
+                size = struct.unpack("<I", mm[offset + 4:offset + 8])[0]
+                payload_offset = offset + 8
+                end = payload_offset + size
+                if size == 0 or size > MAX_BLOCK_PAYLOAD or end > file_size:
+                    pos = offset + 1
+                    continue
+                payload = mm[payload_offset:end]
+                try:
+                    yield parse_block(payload, path.name, payload_offset)
+                except ParseError:
+                    pos = offset + 1
+                    continue
+                pos = end
+        finally:
+            mm.close()
+
+
+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([
+        UTXO_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 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(UTXO_NODE_DOMAIN + 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:
+                    if strict_duplicates:
+                        raise ParseError("duplicate output at height %d: %s" % (height, key))
+                    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 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
new file mode 100755
index 0000000..dbb8e17
--- /dev/null
+++ b/scripts/build-explorer.py
@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+"""Build a static Bitflash block explorer from local blk*.dat files."""
+
+import argparse
+import hashlib
+import json
+import shutil
+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 += chain.sha256d(v)[:4]
+    n = int.from_bytes(v, "big")
+    s = ""
+    while n > 0:
+        n, r = divmod(n, 58)
+        s = B58[r] + s
+    for byte in v:
+        if byte == 0:
+            s = "1" + s
+        else:
+            break
+    return s
+
+
+def hash160(b):
+    return hashlib.new("ripemd160", hashlib.sha256(b).digest()).digest()
+
+
+def spk_info(script_hex):
+    try:
+        spk = bytes.fromhex(script_hex)
+    except ValueError:
+        return {"type": "malformed", "hex": script_hex[:80]}
+    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])}
+    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))}
+        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": 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 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"])
+    (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")
+    (out / "style.css").write_text(STYLE_CSS, encoding="utf-8")
+    (out / "explorer.js").write_text(EXPLORER_JS, encoding="utf-8")
+    logo = Path(__file__).resolve().parents[1] / "docs" / "logo.png"
+    if logo.exists():
+        shutil.copyfile(logo, out / "logo.png")
+    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>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Bitflash Block Explorer</title>
+<meta name="description" content="Read-only Bitflash block explorer generated from local blk*.dat files.">
+<link rel="icon" href="logo.png" type="image/png">
+<link rel="stylesheet" href="style.css">
+<script src="explorer.js" defer></script>
+</head>
+<body>
+<header class="topbar">
+  <a class="brand" href="https://bitflash.network/"><img src="logo.png" width="22" height="22" alt="">Bitflash</a>
+  <nav aria-label="Bitflash sites">
+    <a href="https://bitflash.network/">home</a>
+    <a href="https://git.bitflash.network/bitflash/bitflash">code</a>
+    <a href="https://docs.bitflash.network/">docs</a>
+    <a href="https://releases.bitflash.network/">downloads</a>
+    <a href="https://explorer.bitflash.network/" aria-current="page">explorer</a>
+    <a href="https://status.bitflash.network/">status</a>
+  </nav>
+  <span class="meta" id="tip"></span>
+</header>
+<div class="wrap">
+  <h1>Block explorer <button class="link" id="home" hidden>back to blocks</button></h1>
+  <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>
+      <thead><tr><th>Height</th><th>Time (UTC)</th><th>Txs</th><th>Size</th><th>Coinbase</th><th>To</th></tr></thead>
+      <tbody id="rows"></tbody>
+    </table></div>
+    <p class="mut" id="more"></p>
+  </div>
+  <div id="detail" hidden></div>
+</div>
+</body>
+</html>
+"""
+
+
+STYLE_CSS = r""":root{
+  color-scheme: light dark;
+  --bg:#fff; --bg-2:#f6f6f6; --fg:#111; --dim:#6b6b6b; --line:#d7d7d7; --line-hard:#111;
+  --accent:#0b7a34; --accent-2:#12a047; --bar:3rem;
+  --mono: ui-monospace,"Cascadia Mono","Segoe UI Mono",Consolas,"DejaVu Sans Mono","Liberation Mono","Courier New",monospace;
+}
+@media (prefers-color-scheme: dark){:root{
+  --bg:#000; --bg-2:#0b0b0b; --fg:#dcdcdc; --dim:#8a8a8a; --line:#242424; --line-hard:#4a4a4a;
+  --accent:#2ee06a; --accent-2:#6bff9f;
+}}
+*{box-sizing:border-box;}
+html,body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.55 var(--mono);-webkit-text-size-adjust:100%;}
+a{color:var(--accent);}
+.topbar{display:flex;align-items:center;gap:1rem;flex-wrap:wrap;min-height:var(--bar);
+        padding:.5rem clamp(.9rem,2.5vw,3rem);border-bottom:1px solid var(--line);position:sticky;top:0;background:var(--bg);z-index:5;}
+.brand{display:flex;align-items:center;gap:.6rem;text-decoration:none;color:var(--fg);font-weight:bold;}
+.brand img{width:22px;height:22px;display:block;}
+.topbar nav{display:flex;flex-wrap:wrap;gap:.15rem 1.4rem;font-size:.86rem;}
+.topbar nav a{text-decoration:none;color:var(--dim);}
+.topbar nav a::before{content:"/";color:var(--line-hard);margin-right:.3rem;}
+.topbar nav a:hover{color:var(--fg);text-decoration:underline;}
+.topbar nav a[aria-current="page"]{color:var(--accent);font-weight:bold;}
+.topbar nav a[aria-current="page"]::before{color:var(--accent);}
+.topbar .meta{margin-left:auto;font-size:.76rem;color:var(--dim);letter-spacing:.06em;}
+.wrap{padding:1.4rem clamp(.9rem,2.5vw,3rem) 4rem;}
+h1{font-size:1rem;margin:0 0 .3rem;letter-spacing:.02em;}
+h2{font-size:.95rem;margin:1.2rem 0 .4rem;}
+.mut{color:var(--dim);}
+.note{color:var(--dim);font-size:.82rem;max-width:60rem;margin:.2rem 0 1rem;}
+input{width:100%;max-width:28rem;padding:.5rem .7rem;border:1px solid var(--line);background:var(--bg-2);color:var(--fg);font:inherit;font-size:.86rem;}
+input:focus{outline:none;border-color:var(--accent);}
+.scroll{overflow-x:auto;}
+table{width:100%;border-collapse:collapse;margin-top:.8rem;font-size:.86rem;}
+th,td{text-align:left;padding:.5rem .6rem;border-bottom:1px solid var(--line);font-variant-numeric:tabular-nums;}
+th{font-size:.72rem;text-transform:uppercase;letter-spacing:.1em;color:var(--dim);font-weight:normal;}
+tr.blk{cursor:pointer;}
+tr.blk:hover td{background:var(--bg-2);}
+code{font-size:.8rem;word-break:break-all;color:var(--fg);}
+.card{border:1px solid var(--line);background:var(--bg-2);padding:.9rem 1rem;margin-top:.8rem;}
+.kv{display:grid;grid-template-columns:11rem 1fr;gap:.25rem .8rem;font-size:.82rem;}
+.kv div:nth-child(odd){color:var(--dim);}
+.tx{border-top:1px solid var(--line);padding:.7rem 0;}
+.io{display:grid;grid-template-columns:1fr 1fr;gap:1rem;}
+@media (max-width:640px){.io{grid-template-columns:1fr;}.kv{grid-template-columns:7rem 1fr;}.topbar .meta{margin-left:0;width:100%;}}
+.pill{display:inline-block;font-size:.68rem;padding:.05rem .5rem;border:1px solid var(--line);color:var(--dim);text-transform:uppercase;letter-spacing:.05em;}
+button.link{background:none;border:none;color:var(--accent);cursor:pointer;font:inherit;padding:0;text-decoration:underline;}
+"""
+
+
+EXPLORER_JS = r"""
+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 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');
+  clear(rows);
+  var list = q ? SUM.filter(function(b){ return String(b.height)===q || b.hash.indexOf(q)===0; }) : SUM.slice(0,SHOWN);
+  if(!list.length){
+    var empty = E('tr');
+    var td = E('td', 'mut', 'no match');
+    td.colSpan = 6;
+    append(empty, td); append(rows, empty);
+  }
+  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") : "";
+}
+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 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').hidden = true;
+    detail.hidden = false;
+    document.getElementById('home').hidden = false;
+    window.scrollTo(0,0);
+  });
+}
+document.getElementById('home').onclick=function(){
+  document.getElementById('detail').hidden = true;
+  document.getElementById('listview').hidden = false;
+  this.hidden = true;
+};
+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';
+  renderList('');
+});
+"""
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/build-pool-index.py b/scripts/build-pool-index.py
new file mode 100644
index 0000000..d3eb386
--- /dev/null
+++ b/scripts/build-pool-index.py
@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+#
+# Build a static public pool directory from one or more Bitflash pool_status.json
+# files. Inputs may be local paths or http(s) URLs.
+
+import argparse
+import html
+import json
+import os
+import time
+import urllib.parse
+import urllib.request
+
+
+def load_json(source):
+    if source.startswith("http://") or source.startswith("https://"):
+        with urllib.request.urlopen(source, timeout=10) as r:
+            return json.loads(r.read().decode("utf-8"))
+    with open(source, "r", encoding="utf-8-sig") as f:
+        return json.load(f)
+
+
+def normalize_pool(source, obj, now):
+    operator = obj.get("operator", {})
+    pool = obj.get("pool", {})
+    node = obj.get("node", {})
+    rounds_file = operator.get("roundsFile") or "pool_rounds.json"
+    rounds_url = ""
+    if source.startswith("http://") or source.startswith("https://"):
+        rounds_url = urllib.parse.urljoin(source, rounds_file)
+    updated = int(obj.get("updatedAt") or 0)
+    age = max(0, now - updated) if updated else None
+    online = bool(node.get("poolRunning")) and age is not None and age <= 120
+    return {
+        "source": source,
+        "name": operator.get("name") or "Bitflash Pool",
+        "btfAddress": operator.get("btfAddress") or "",
+        "feePercent": float(operator.get("feePercent") or 0.0),
+        "dashboardUrl": operator.get("dashboardUrl") or "",
+        "height": int(node.get("height") or 0),
+        "online": online,
+        "ageSeconds": age,
+        "authorizedMiners": int(pool.get("authorizedMiners") or 0),
+        "blocksFoundSession": int(pool.get("blocksFoundSession") or 0),
+        "roundShares": int(pool.get("roundShares") or 0),
+        "hashRate": float(pool.get("hashRate") or 0.0),
+        "roundsUrl": rounds_url,
+        "recentRounds": obj.get("recentRounds", []),
+    }
+
+
+def rank_key(pool):
+    return (
+        1 if pool["online"] else 0,
+        pool["hashRate"],
+        pool["authorizedMiners"],
+        -pool["feePercent"],
+        pool["name"].lower(),
+    )
+
+
+def render_html(pools, generated_at):
+    rows = []
+    for p in pools:
+        dash = p["dashboardUrl"]
+        rounds = p.get("roundsUrl", "")
+        # Only linkify http(s). The dashboard URL comes from an operator's
+        # self-published status file, so a "javascript:" or "data:" scheme
+        # would become a clickable script-injection on this public page.
+        dash_lower = dash.lower()
+        if dash_lower.startswith("http://") or dash_lower.startswith("https://"):
+            dash_html = '<a href="{0}" rel="noopener noreferrer">dashboard</a>'.format(
+                html.escape(dash, quote=True))
+        else:
+            dash_html = "-"
+        rounds_lower = rounds.lower()
+        if rounds_lower.startswith("http://") or rounds_lower.startswith("https://"):
+            rounds_html = '<a href="{0}" rel="noopener noreferrer">proof</a>'.format(
+                html.escape(rounds, quote=True))
+        else:
+            rounds_html = "-"
+        rows.append(
+            "<tr>"
+            "<td>{status}</td>"
+            "<td><strong>{name}</strong><br><code>{addr}</code></td>"
+            "<td>{fee:.2f}%</td>"
+            "<td>{miners}</td>"
+            "<td>{hashrate:.2f}</td>"
+            "<td>{blocks}</td>"
+            "<td>{height}</td>"
+            "<td>{age}</td>"
+            "<td>{dash}</td>"
+            "<td>{rounds}</td>"
+            "</tr>".format(
+                status="online" if p["online"] else "stale",
+                name=html.escape(p["name"]),
+                addr=html.escape(p["btfAddress"]),
+                fee=p["feePercent"],
+                miners=p["authorizedMiners"],
+                hashrate=p["hashRate"],
+                blocks=p["blocksFoundSession"],
+                height=p["height"],
+                age="{}s".format(p["ageSeconds"]) if p["ageSeconds"] is not None else "-",
+                dash=dash_html,
+                rounds=rounds_html,
+            )
+        )
+
+    return """<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Bitflash Pools</title>
+  <style>
+    body {{ font: 15px/1.45 system-ui, sans-serif; margin: 32px; color: #111; }}
+    table {{ border-collapse: collapse; width: 100%; }}
+    th, td {{ border-bottom: 1px solid #ddd; padding: 10px; text-align: left; vertical-align: top; }}
+    th {{ font-size: 12px; text-transform: uppercase; letter-spacing: .08em; }}
+    code {{ font-size: 12px; word-break: break-all; }}
+    .note {{ color: #555; max-width: 780px; }}
+  </style>
+</head>
+<body>
+  <h1>Bitflash Pools</h1>
+  <p class="note">This directory is informational. Bitflash nodes discover pools through Nostr and .btf; this page only helps humans compare public operators.</p>
+  <table>
+    <thead>
+      <tr><th>Status</th><th>Pool</th><th>Fee</th><th>Miners</th><th>H/s</th><th>Blocks</th><th>Height</th><th>Age</th><th>Link</th><th>Proof</th></tr>
+    </thead>
+    <tbody>
+      {rows}
+    </tbody>
+  </table>
+  <p class="note">Generated at {generated_at}. JSON: <a href="pools.json">pools.json</a>.</p>
+</body>
+</html>
+""".format(rows="\n      ".join(rows), generated_at=generated_at)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out-dir", default="pool-site")
+    ap.add_argument("sources", nargs="+", help="pool_status.json paths or URLs")
+    args = ap.parse_args()
+
+    now = int(time.time())
+    pools = []
+    errors = []
+    for source in args.sources:
+        try:
+            pools.append(normalize_pool(source, load_json(source), now))
+        except Exception as e:
+            errors.append({"source": source, "error": str(e)})
+
+    pools.sort(key=rank_key, reverse=True)
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    generated_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now))
+    with open(os.path.join(args.out_dir, "pools.json"), "w", encoding="utf-8") as f:
+        json.dump({
+            "schema": "bitflash-pool-directory-1",
+            "generatedAt": generated_at,
+            "pools": pools,
+            "errors": errors,
+        }, f, indent=2, sort_keys=True)
+        f.write("\n")
+
+    with open(os.path.join(args.out_dir, "index.html"), "w", encoding="utf-8") as f:
+        f.write(render_html(pools, generated_at))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/check-money-log-lines.sh b/scripts/check-money-log-lines.sh
new file mode 100755
index 0000000..c9f348b
--- /dev/null
+++ b/scripts/check-money-log-lines.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Money-moving payout lines must print every time they fire: they are the
+# audit trail for obligations created, moved and destroyed, and LogPrint's
+# burst collapse can stand one line in for any number of events inside one
+# 3-second window (issue #3: 100 voids totalling 4,950 BTF read as one
+# 49.49 BTF line). Every line carrying one of the phrases below must use
+# LogPrintAlways, which keeps the category gate but skips the collapse.
+#
+# Adding a payout line that reports money moving? Use LogPrintAlways and
+# add its phrase here. A phrase found in a plain LogPrint call fails this
+# check; anything else passes, so a non-money line is never held up by it.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+phrases='was orphaned -- voiding|orphaned while queued|\[payout\] paid %s to %s|FAILED to pay|writing off|SKIPPED bad address'
+
+# Call sites span several lines; flatten each call to a single line first so
+# the phrase and the macro it belongs to are matched together. Only a line
+# whose first token is the macro starts a call, so comments mentioning
+# LogPrint are never mistaken for one.
+bad=$(awk '
+    /^[ \t]*LogPrint(Always)?[(]/ {
+        if (collecting) print buf
+        buf = $0; collecting = 1; next
+    }
+    collecting {
+        buf = buf $0
+        if (/;[ \t]*$/) { print buf; collecting = 0 }
+    }
+    END { if (collecting) print buf }
+' src/rpc.cpp | grep -E '^[[:space:]]*LogPrint[(]' | grep -E "$phrases" || true)
+
+if [ -n "$bad" ]; then
+    echo "error: money-moving payout line(s) on collapsing LogPrint:" >&2
+    echo "$bad" >&2
+    exit 1
+fi
+echo "ok: every money-moving payout line in src/rpc.cpp uses LogPrintAlways"
diff --git a/scripts/make-release-checksums.sh b/scripts/make-release-checksums.sh
index 5b29e2d..9c4f45a 100644..100755
--- a/scripts/make-release-checksums.sh
+++ b/scripts/make-release-checksums.sh
@@ -10,6 +10,7 @@ Usage: scripts/make-release-checksums.sh [--sign] [--local-user KEYID]
 
 Creates SHA256SUMS for release assets in the current directory:
   Bitflash-*-windows.zip
+  Bitflash-*-windows-with-tor.zip
   Bitflash-*-x86_64.AppImage
   bitflash-node-*-x86_64
 
@@ -44,6 +45,7 @@ fi
 assets=()
 for pattern in \
   "Bitflash-*-windows.zip" \
+  "Bitflash-*-windows-with-tor.zip" \
   "Bitflash-*-x86_64.AppImage" \
   "bitflash-node-*-x86_64"
 do
diff --git a/scripts/package-windows-tor.sh b/scripts/package-windows-tor.sh
new file mode 100755
index 0000000..c8cca3b
--- /dev/null
+++ b/scripts/package-windows-tor.sh
@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERSION="${VERSION:-$(sed -n 's/^VERSION[[:space:]]*:= *//p' "$ROOT/Makefile" | head -1)}"
+
+TOR_VERSION="${TOR_VERSION:-15.0.19}"
+TOR_ARCHIVE_NAME="tor-expert-bundle-windows-x86_64-${TOR_VERSION}.tar.gz"
+TOR_URL="${TOR_URL:-https://archive.torproject.org/tor-package-archive/torbrowser/${TOR_VERSION}/${TOR_ARCHIVE_NAME}}"
+TOR_SHA256="${TOR_SHA256:-6AC067402C7B4A3DC37887ED3754B3914B67FDC220C966190683E9CCF91ABF0F}"
+TOR_ASC_URL="${TOR_ASC_URL:-${TOR_URL}.asc}"
+TOR_SIGNING_KEY_FINGERPRINT="${TOR_SIGNING_KEY_FINGERPRINT:-EF6E286DDA85EA2A4BA7DE684E2C6E8793298290}"
+TOR_VERIFY_GPG="${TOR_VERIFY_GPG:-auto}"
+
+BUNDLE_DIR="${BUNDLE_DIR:-$ROOT/Bitflash-${VERSION}-windows}"
+OUT_ZIP="${OUT_ZIP:-$ROOT/Bitflash-${VERSION}-windows-with-tor.zip}"
+CACHE_DIR="${CACHE_DIR:-$ROOT/.cache}"
+ARCHIVE="${TOR_ARCHIVE:-$CACHE_DIR/$TOR_ARCHIVE_NAME}"
+ASC_FILE="${TOR_ASC:-$ARCHIVE.asc}"
+
+usage() {
+  cat <<EOF
+Usage: scripts/package-windows-tor.sh
+
+Creates Bitflash-${VERSION}-windows-with-tor.zip from an existing
+Bitflash-${VERSION}-windows/ release directory.
+
+Environment overrides:
+  VERSION       Bitflash release version, default read from Makefile
+  TOR_VERSION   Tor Expert Bundle version, default ${TOR_VERSION}
+  TOR_URL       Download URL, default official Tor archive URL
+  TOR_ASC_URL   Signature URL, default TOR_URL.asc
+  TOR_SHA256    Expected archive SHA256
+  TOR_ARCHIVE   Use an existing archive instead of downloading
+  TOR_ASC       Use an existing detached signature
+  TOR_VERIFY_GPG auto, required, or off; default auto
+  BUNDLE_DIR    Existing unpacked Windows release directory
+  OUT_ZIP       Output zip path
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "missing required command: $1" >&2
+    exit 1
+  }
+}
+
+need sha256sum
+need tar
+need zip
+
+download() {
+  local url="$1"
+  local out="$2"
+  if command -v curl >/dev/null 2>&1; then
+    curl -L --fail --output "$out" "$url"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -O "$out" "$url"
+  else
+    echo "missing required command: curl or wget" >&2
+    exit 1
+  fi
+}
+
+if [ ! -d "$BUNDLE_DIR" ]; then
+  echo "missing Windows release directory: $BUNDLE_DIR" >&2
+  echo "run 'make windows' first, or set BUNDLE_DIR" >&2
+  exit 1
+fi
+if [ ! -f "$BUNDLE_DIR/Bitflash.exe" ]; then
+  echo "missing Bitflash.exe in $BUNDLE_DIR" >&2
+  exit 1
+fi
+BUNDLE_PARENT="$(cd "$(dirname "$BUNDLE_DIR")" && pwd)"
+BUNDLE_NAME="$(basename "$BUNDLE_DIR")"
+OUT_PARENT="$(mkdir -p "$(dirname "$OUT_ZIP")" && cd "$(dirname "$OUT_ZIP")" && pwd)"
+OUT_NAME="$(basename "$OUT_ZIP")"
+OUT_ZIP_ABS="$OUT_PARENT/$OUT_NAME"
+
+mkdir -p "$CACHE_DIR"
+if [ ! -f "$ARCHIVE" ]; then
+  download "$TOR_URL" "$ARCHIVE"
+fi
+
+got="$(sha256sum "$ARCHIVE" | awk '{print tolower($1)}')"
+want="$(printf '%s' "$TOR_SHA256" | tr 'A-F' 'a-f')"
+if [ "$got" != "$want" ]; then
+  echo "Tor archive SHA256 mismatch" >&2
+  echo "  expected: $want" >&2
+  echo "       got: $got" >&2
+  exit 1
+fi
+
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/bitflash-tor-package.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT
+
+case "$TOR_VERIFY_GPG" in
+  auto|required|off) ;;
+  *) echo "TOR_VERIFY_GPG must be auto, required, or off" >&2; exit 2 ;;
+esac
+
+if [ "$TOR_VERIFY_GPG" != "off" ]; then
+  if command -v gpg >/dev/null 2>&1; then
+    if [ ! -f "$ASC_FILE" ]; then
+      download "$TOR_ASC_URL" "$ASC_FILE"
+    fi
+    gnupg_home="$tmp/gnupg"
+    mkdir -p "$gnupg_home"
+    chmod 0700 "$gnupg_home"
+    gpg --homedir "$gnupg_home" --batch --auto-key-locate nodefault,wkd,keyserver \
+      --locate-keys torbrowser@torproject.org >/dev/null 2>&1 || {
+        if [ "$TOR_VERIFY_GPG" = "required" ]; then
+          echo "could not import Tor Browser Developers signing key" >&2
+          exit 1
+        fi
+        echo "WARNING: skipped Tor GPG signature verification; signing key import failed" >&2
+      }
+    if gpg --homedir "$gnupg_home" --batch --with-colons --fingerprint "$TOR_SIGNING_KEY_FINGERPRINT" \
+        2>/dev/null | grep -q "^fpr:::::::::${TOR_SIGNING_KEY_FINGERPRINT}:"; then
+      gpg --homedir "$gnupg_home" --batch --verify "$ASC_FILE" "$ARCHIVE" >/dev/null 2>&1 || {
+        echo "Tor archive GPG signature verification failed" >&2
+        exit 1
+      }
+      echo "Tor archive GPG signature verified against ${TOR_SIGNING_KEY_FINGERPRINT}"
+    elif [ "$TOR_VERIFY_GPG" = "required" ]; then
+      echo "Tor signing key fingerprint mismatch" >&2
+      exit 1
+    else
+      echo "WARNING: skipped Tor GPG signature verification; signing key fingerprint was not available" >&2
+    fi
+  elif [ "$TOR_VERIFY_GPG" = "required" ]; then
+    echo "missing required command for TOR_VERIFY_GPG=required: gpg" >&2
+    exit 1
+  else
+    echo "WARNING: gpg not found; relying on pinned SHA256 only" >&2
+  fi
+fi
+
+mkdir -p "$tmp/extract"
+tar -xzf "$ARCHIVE" -C "$tmp/extract"
+
+if [ ! -f "$tmp/extract/tor/tor.exe" ]; then
+  echo "Tor archive did not contain tor/tor.exe" >&2
+  exit 1
+fi
+
+rm -rf "$BUNDLE_DIR/tor"
+mkdir -p "$BUNDLE_DIR/tor"
+cp -R "$tmp/extract/tor/." "$BUNDLE_DIR/tor/"
+if [ -d "$tmp/extract/docs" ]; then
+  mkdir -p "$BUNDLE_DIR/tor/docs"
+  cp -R "$tmp/extract/docs/." "$BUNDLE_DIR/tor/docs/"
+fi
+if [ -d "$tmp/extract/data" ]; then
+  mkdir -p "$BUNDLE_DIR/tor/data-defaults"
+  cp -R "$tmp/extract/data/." "$BUNDLE_DIR/tor/data-defaults/"
+fi
+
+cat > "$BUNDLE_DIR/TOR-EXPERT-BUNDLE.txt" <<EOF
+Bitflash managed Tor bundle
+
+This Windows package includes the Tor Expert Bundle so -managedtor can start
+Tor without requiring a separate Tor install.
+
+Tor Expert Bundle: ${TOR_VERSION}
+Archive URL: ${TOR_URL}
+Archive SHA256: ${TOR_SHA256}
+
+Bitflash uses tor/tor.exe from this package. Runtime state, hidden-service keys,
+and control authentication cookies are written under the user's Bitflash data
+directory, not inside this release directory.
+EOF
+
+rm -f "$OUT_ZIP_ABS"
+(
+  cd "$BUNDLE_PARENT"
+  zip -qr "$OUT_ZIP_ABS" "$BUNDLE_NAME"
+)
+
+echo "Bundled Tor Expert Bundle ${TOR_VERSION}"
+echo "Built: $OUT_ZIP_ABS"
diff --git a/scripts/prove-utxo.py b/scripts/prove-utxo.py
new file mode 100644
index 0000000..105e677
--- /dev/null
+++ b/scripts/prove-utxo.py
@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Create a Bitflash UTXO inclusion proof from local blk*.dat files.
+
+The proof is deliberately outside consensus. It proves that one txid:vout is
+included in the deterministic UTXO root produced by verify-utxo-set.py.
+"""
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+SCHEMA = "bitflash-utxo-inclusion-proof-1"
+
+
+def canonical_bytes(obj):
+    return (json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
+
+
+def split_outpoint(outpoint):
+    parts = outpoint.split(":")
+    if len(parts) != 2 or len(parts[0]) != 64:
+        raise SystemExit("outpoint must be txid:vout")
+    try:
+        vout = int(parts[1], 10)
+    except ValueError:
+        raise SystemExit("vout must be a decimal integer")
+    if vout < 0:
+        raise SystemExit("vout must not be negative")
+    return parts[0].lower(), vout
+
+
+def build_merkle_proof(keys, leaf_hashes, index):
+    current_index = index
+    layer = list(leaf_hashes)
+    proof = []
+    level = 0
+    while len(layer) > 1:
+        if current_index % 2 == 0:
+            sibling_index = current_index + 1
+            duplicated = sibling_index >= len(layer)
+            sibling = layer[current_index] if duplicated else layer[sibling_index]
+            side = "right"
+        else:
+            sibling_index = current_index - 1
+            duplicated = False
+            sibling = layer[sibling_index]
+            side = "left"
+        proof.append({
+            "level": level,
+            "side": side,
+            "hash": sibling.hex(),
+            "duplicated": duplicated,
+        })
+
+        next_layer = []
+        for i in range(0, len(layer), 2):
+            left = layer[i]
+            right = layer[i + 1] if i + 1 < len(layer) else left
+            next_layer.append(hashlib.sha256(chain.UTXO_NODE_DOMAIN + left + right).digest())
+        layer = next_layer
+        current_index //= 2
+        level += 1
+    return proof, layer[0].hex()
+
+
+def build_proof(args):
+    txid, vout = split_outpoint(args.outpoint)
+    outpoint = "%s:%d" % (txid, vout)
+
+    raw_blocks = chain.read_blocks(args.datadir, args.max_blocks)
+    if not raw_blocks:
+        raise SystemExit("no Bitflash blocks found in %s" % args.datadir)
+    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 = [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 = chain.utxo_root(utxos)
+    if root != direct_root:
+        raise SystemExit("internal proof root mismatch")
+
+    tip = blocks[-1]
+    utxo = utxos[outpoint]
+    report = {
+        "schema": SCHEMA,
+        "deterministic": True,
+        "chain": {
+            "name": "Bitflash",
+            "ticker": "BTF",
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
+        },
+        "commitment": {
+            "algorithm": "sorted-outpoint-merkle-sha256",
+            "leaf_domain": chain.UTXO_LEAF_DOMAIN,
+            "node_domain": chain.UTXO_NODE_DOMAIN_TAG,
+            "root": root,
+            "leaf_count": len(keys),
+        },
+        "target": {
+            "outpoint": outpoint,
+            "txid": txid,
+            "vout": vout,
+            "leaf_index": index,
+            "leaf_hash": leaf_hashes[index].hex(),
+            "utxo": utxo,
+        },
+        "proof": proof_path,
+        "scanned": {
+            "raw_block_count": len(raw_blocks),
+            "side_blocks_ignored": len(raw_blocks) - len(blocks),
+            "main_chain_block_count": len(blocks),
+            "first_height": 0,
+            "last_height": len(blocks) - 1,
+            "tip_hash": tip["hash"],
+            "tip_time": tip["time"],
+            "tip_time_utc": tip["time_utc"],
+        },
+        "warnings": {
+            "legacy_duplicate_output_overwrites": len(stats["duplicate_outputs"]),
+        },
+        "verdict": "UTXO_INCLUSION_PROOF_CREATED",
+    }
+    return report
+
+
+def print_text(proof):
+    data_hash = hashlib.sha256(canonical_bytes(proof)).hexdigest()
+    target = proof["target"]
+    utxo = target["utxo"]
+    print("Bitflash UTXO inclusion proof")
+    print("schema: %s" % proof["schema"])
+    print("canonical proof sha256: %s" % data_hash)
+    print()
+    print("Target")
+    print("  outpoint: %s" % target["outpoint"])
+    print("  value:    %s BTF" % utxo["value_btf"])
+    print("  height:   %d" % utxo["created_height"])
+    print("  index:    %d of %d" % (target["leaf_index"], proof["commitment"]["leaf_count"]))
+    print()
+    print("Commitment")
+    print("  root:     %s" % proof["commitment"]["root"])
+    print("  path:     %d sibling hashes" % len(proof["proof"]))
+    print("  tip:      %s" % proof["scanned"]["tip_hash"])
+    print()
+    print("Verdict: %s" % proof["verdict"])
+
+
+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=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)
+
+    proof = build_proof(args)
+    data = canonical_bytes(proof)
+    if args.out:
+        Path(args.out).write_bytes(data)
+    if args.json:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(proof)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/smoke-managed-tor-onion.ps1 b/scripts/smoke-managed-tor-onion.ps1
new file mode 100644
index 0000000..70658c7
--- /dev/null
+++ b/scripts/smoke-managed-tor-onion.ps1
@@ -0,0 +1,174 @@
+param(
+    [string]$Bitflash,
+    [string]$Tor,
+    [string]$WorkDir,
+    [int]$TimeoutSec = 600,
+    [int]$OnionWarmupSec = 120
+)
+
+$ErrorActionPreference = "Stop"
+
+function Resolve-RepoRoot {
+    $scriptDir = Split-Path -Parent $PSCommandPath
+    return (Resolve-Path (Join-Path $scriptDir "..")).Path
+}
+
+function Get-FreeTcpPort {
+    $listener = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback, 0)
+    $listener.Start()
+    try {
+        return ([Net.IPEndPoint]$listener.LocalEndpoint).Port
+    }
+    finally {
+        $listener.Stop()
+    }
+}
+
+function Wait-RegexInFile {
+    param(
+        [string]$Path,
+        [string]$Pattern,
+        [datetime]$Deadline,
+        [string]$Label
+    )
+
+    while ((Get-Date) -lt $Deadline) {
+        if (Test-Path $Path) {
+            $text = Get-Content -Raw -ErrorAction SilentlyContinue $Path
+            if ($null -ne $text) {
+                $m = [regex]::Match($text, $Pattern)
+                if ($m.Success) {
+                    return $m
+                }
+            }
+        }
+        Start-Sleep -Milliseconds 500
+    }
+    throw "timed out waiting for $Label"
+}
+
+function Stop-TestProcesses {
+    param(
+        [System.Diagnostics.Process[]]$Processes,
+        [string[]]$DataDirKeys
+    )
+
+    foreach ($p in $Processes) {
+        try {
+            $p.Refresh()
+            if (!$p.HasExited) {
+                Stop-Process -Id $p.Id -Force
+            }
+        }
+        catch {}
+    }
+
+    foreach ($key in $DataDirKeys) {
+        if ([string]::IsNullOrWhiteSpace($key)) {
+            continue
+        }
+        try {
+            Get-CimInstance Win32_Process -Filter "name = 'tor.exe'" |
+                Where-Object { $_.CommandLine -like "*$key*" } |
+                ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
+        }
+        catch {}
+    }
+}
+
+$repo = Resolve-RepoRoot
+if ([string]::IsNullOrWhiteSpace($Bitflash)) {
+    $Bitflash = Join-Path $repo "src\bitflash.exe"
+}
+if ([string]::IsNullOrWhiteSpace($Tor)) {
+    $candidates = @(
+        (Join-Path $repo "src\tor\tor.exe"),
+        (Join-Path $repo "Bitflash-$(Select-String -Path (Join-Path $repo 'Makefile') -Pattern '^VERSION[ ]*:=' | ForEach-Object { ($_.Line -split ':=')[1].Trim() })-windows\tor\tor.exe")
+    )
+    foreach ($candidate in $candidates) {
+        if (Test-Path $candidate) {
+            $Tor = $candidate
+            break
+        }
+    }
+}
+if ([string]::IsNullOrWhiteSpace($WorkDir)) {
+    $WorkDir = Join-Path $env:TEMP ("bitflash-managed-tor-two-node-" + (Get-Date -Format "yyyyMMddHHmmss"))
+}
+
+if (!(Test-Path $Bitflash)) {
+    throw "Bitflash binary not found: $Bitflash"
+}
+if (!(Test-Path $Tor)) {
+    throw "Tor binary not found. Pass -Tor or build the Windows-with-Tor package."
+}
+
+New-Item -ItemType Directory -Force -Path $WorkDir | Out-Null
+$dataA = Join-Path $WorkDir "node-a"
+$dataB = Join-Path $WorkDir "node-b"
+New-Item -ItemType Directory -Force -Path $dataA | Out-Null
+New-Item -ItemType Directory -Force -Path $dataB | Out-Null
+
+$portA = Get-FreeTcpPort
+$portB = Get-FreeTcpPort
+$deadline = (Get-Date).AddSeconds($TimeoutSec)
+$oldPath = $env:PATH
+$env:PATH = "C:\msys64\ucrt64\bin;C:\msys64\usr\bin;" + $env:PATH
+
+$procA = $null
+$procB = $null
+$dataKeys = @((Split-Path $WorkDir -Leaf))
+
+try {
+    $argsA = @(
+        "-datadir=$dataA",
+        "-port=$portA",
+        "-managedtor=$Tor",
+        "-nogui",
+        "-debug",
+        "-checkblocks=0"
+    )
+    $procA = Start-Process -FilePath $Bitflash -ArgumentList $argsA -WorkingDirectory (Split-Path $Bitflash -Parent) -PassThru -WindowStyle Hidden
+    $logA = Join-Path $dataA "debug.log"
+
+    $btfMatch = Wait-RegexInFile -Path $logA -Pattern "Nostr: node \.btf address = ([a-z2-7]+\.btf)" -Deadline $deadline -Label "node A .btf address"
+    $btfA = $btfMatch.Groups[1].Value
+
+    $onionMatch = Wait-RegexInFile -Path $logA -Pattern "Managed Tor hidden service ready: ([a-z2-7]{56}\.onion:\d+)" -Deadline $deadline -Label "node A managed onion"
+    $onionA = $onionMatch.Groups[1].Value
+
+    Wait-RegexInFile -Path $logA -Pattern "Nostr: \.btf self-resolve OK via .*" -Deadline $deadline -Label "node A descriptor self-resolve" | Out-Null
+    if ($OnionWarmupSec -gt 0) {
+        Write-Host "Waiting $OnionWarmupSec second(s) for Tor hidden-service descriptor propagation"
+        Start-Sleep -Seconds $OnionWarmupSec
+    }
+
+    $argsB = @(
+        "-datadir=$dataB",
+        "-port=$portB",
+        "-managedtor=$Tor",
+        "-oniononly",
+        "-connectbtf=$btfA",
+        "-nogui",
+        "-debug",
+        "-checkblocks=0"
+    )
+    $procB = Start-Process -FilePath $Bitflash -ArgumentList $argsB -WorkingDirectory (Split-Path $Bitflash -Parent) -PassThru -WindowStyle Hidden
+    $logB = Join-Path $dataB "debug.log"
+
+    Wait-RegexInFile -Path $logB -Pattern ("connected " + [regex]::Escape($btfA) + " via direct onion ") -Deadline $deadline -Label "node B direct onion connection to node A" | Out-Null
+
+    Write-Host "Managed Tor two-node onion smoke test passed"
+    Write-Host "  node A .btf:   $btfA"
+    Write-Host "  node A onion:  $onionA"
+    Write-Host "  node A port:   $portA"
+    Write-Host "  node B port:   $portB"
+    Write-Host "  work dir:      $WorkDir"
+}
+finally {
+    $env:PATH = $oldPath
+    $procs = @()
+    if ($null -ne $procA) { $procs += $procA }
+    if ($null -ne $procB) { $procs += $procB }
+    Stop-TestProcesses -Processes $procs -DataDirKeys $dataKeys
+}
diff --git a/scripts/verify-fair-launch.py b/scripts/verify-fair-launch.py
new file mode 100644
index 0000000..c33c8be
--- /dev/null
+++ b/scripts/verify-fair-launch.py
@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Produce a deterministic Bitflash fair-launch audit report."""
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+
+def build_report(blocks, source_mode):
+    genesis = blocks[0]
+    launch_outputs = genesis["transactions"][0]["vout"] if genesis["transactions"] else []
+    coinbase_outputs = []
+    total_mined = 0
+    non_coinbase_txs = 0
+
+    for height, block in enumerate(blocks):
+        if not block["transactions"]:
+            continue
+        cb = block["transactions"][0]
+        if chain.is_coinbase(cb):
+            amount = sum(out["value_satoshis"] for out in cb["vout"])
+            total_mined += amount
+            coinbase_outputs.append({
+                "height": height,
+                "block_hash": block["hash"],
+                "coinbase_txid": cb["txid"],
+                "value_satoshis": amount,
+                "value_btf": chain.format_money(amount),
+                "outputs": cb["vout"],
+            })
+        non_coinbase_txs += sum(1 for tx in block["transactions"] if not chain.is_coinbase(tx))
+
+    checks = {
+        "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 chain.is_coinbase(genesis["transactions"][0])),
+        "genesis_supply_is_50_btf": sum(out["value_satoshis"] for out in launch_outputs) == 50 * chain.COIN,
+    }
+
+    report = {
+        "schema": "bitflash-fair-launch-report-1",
+        "deterministic": True,
+        "source_mode": source_mode,
+        "chain": {
+            "name": "Bitflash",
+            "ticker": "BTF",
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
+        },
+        "source_constants": {
+            "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),
+            "first_height": 0,
+            "last_height": len(blocks) - 1,
+            "non_coinbase_transactions": non_coinbase_txs,
+            "total_coinbase_satoshis": total_mined,
+            "total_coinbase_btf": chain.format_money(total_mined),
+        },
+        "genesis": {
+            "hash": genesis["hash"],
+            "merkle_root": genesis["merkle_root"],
+            "computed_merkle_root": genesis["computed_merkle_root"],
+            "time": genesis["time"],
+            "time_utc": genesis["time_utc"],
+            "bits": genesis["bits"],
+            "nonce": genesis["nonce"],
+            "tx_count": genesis["tx_count"],
+            "coinbase_txid": genesis["transactions"][0]["txid"] if genesis["transactions"] else "",
+            "outputs": launch_outputs,
+        },
+        "coinbase_outputs": coinbase_outputs,
+        "checks": checks,
+        "verdict": "FAIR_LAUNCH_BASELINE_VERIFIED" if all(checks.values()) else "CHECKS_FAILED",
+        "external_timestamping": {
+            "status": "not_embedded",
+            "recommended": "OpenTimestamps",
+            "instructions": [
+                "Save the canonical JSON report.",
+                "Run: ots stamp bitflash-fair-launch-report.json",
+                "Later verify with: ots verify bitflash-fair-launch-report.json.ots",
+            ],
+        },
+    }
+    report["attestation_payload_sha256"] = hashlib.sha256(chain.canonical_bytes(report)).hexdigest()
+    return report
+
+
+def print_text(report):
+    checks = report["checks"]
+    print("Bitflash fair-launch verifier")
+    print("schema: %s" % report["schema"])
+    print("source: %s" % report["source_mode"])
+    print("attestation payload sha256: %s" % report["attestation_payload_sha256"])
+    print()
+    print("Genesis")
+    print("  hash:    %s" % report["genesis"]["hash"])
+    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" % chain.format_money(sum(o["value_satoshis"] for o in report["genesis"]["outputs"])))
+    print()
+    print("Scanned")
+    print("  blocks:  %d" % report["scanned"]["block_count"])
+    print("  height:  %d..%d" % (report["scanned"]["first_height"], report["scanned"]["last_height"]))
+    print("  minted:  %s BTF" % report["scanned"]["total_coinbase_btf"])
+    print("  normal transactions in range: %d" % report["scanned"]["non_coinbase_transactions"])
+    print()
+    print("Checks")
+    for key in sorted(checks):
+        print("  %s %s" % ("OK  " if checks[key] else "FAIL", key))
+    print()
+    print("Verdict: %s" % report["verdict"])
+    print()
+    print("OpenTimestamps")
+    print("  canonical JSON can be stamped later with: ots stamp <report.json>")
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    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")
+    ap.add_argument("--reconstruct-genesis", action="store_true",
+                    help="do not read disk; reconstruct only the genesis block from source constants")
+    args = ap.parse_args(argv)
+
+    if args.reconstruct_genesis:
+        blocks = [chain.reconstructed_genesis()]
+        source_mode = "reconstructed-genesis"
+    else:
+        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" % args.datadir)
+        source_mode = "local-block-files"
+
+    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)
+    if args.json:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(report)
+    return 0 if report["verdict"] == "FAIR_LAUNCH_BASELINE_VERIFIED" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/verify-release.sh b/scripts/verify-release.sh
index c651e78..4fd4558 100644..100755
--- a/scripts/verify-release.sh
+++ b/scripts/verify-release.sh
@@ -1,23 +1,50 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-repo="bitflash-coin/bitflash"
-tag="${1:-latest}"
+# Verifies a Bitflash release: the checksum file's signature against a pinned
+# key, then the assets against the checksums.
+#
+# The signing key is embedded below, not fetched. That is the whole point of a
+# pinned key: the trust anchor ships with this script (in git), so it does not
+# depend on the same server that serves the release. A server that is
+# compromised can swap the binaries and the checksums, but it cannot forge a
+# signature by this key.
+
+host="https://releases.bitflash.network"
 require_signature=0
 
+# The Bitflash release signing key. Verification requires this exact key --
+# gpg's own "good signature" is not enough, because a good signature by *some*
+# key proves nothing. See issue #138.
+RELEASE_KEY_FP="910A2B4CCA879E81FB4B2AEA1D4A53D3B78AA4B8"
+read -r -d '' RELEASE_KEY <<'KEY' || true
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEanSOmRYJKwYBBAHaRw8BAQdAXj24i2BYUcAmOpoXwjE4ZTynHsifCZ+niwQK
+HqO0nMa0UEJpdGZsYXNoIFJlbGVhc2VzIChiaXRmbGFzaC5uZXR3b3JrIHJlbGVh
+c2Ugc2lnbmluZykgPHJlbGVhc2VzQGJpdGZsYXNoLm5ldHdvcms+iJAEExYKADgW
+IQSRCitMyoeegftLKuodSlPTt4qkuAUCanSOmQIbAwULCQgHAgYVCgkICwIEFgID
+AQIeAQIXgAAKCRAdSlPTt4qkuIi9AP96X3OcstiCTTgKOr16Vhds3LyuZ19q3Apq
+4KAcNuOUMAD+NqgJ1CqkLGPXfZLCtYBCRHXNYWxMMEk+ViLcRtdLMg4=
+=mxic
+-----END PGP PUBLIC KEY BLOCK-----
+KEY
+
 usage() {
   cat <<'EOF'
 Usage: scripts/verify-release.sh [tag|latest] [--require-signature]
 
 Downloads the release checksum file and every asset named in it, then verifies:
-  1. SHA256SUMS.asc, if present, against SHA256SUMS with gpg.
+  1. SHA256SUMS.asc against SHA256SUMS, requiring the pinned Bitflash release
+     key (fingerprint 910A 2B4C CA87 9E81 FB4B 2AEA 1D4A 53D3 B78A A4B8).
   2. SHA256SUMS against the downloaded assets.
 
-Use --require-signature for release audits. Without it, older releases that
-ship only SHA256SUMS are checked for integrity and reported as unsigned.
+Releases from before signing was introduced ship only SHA256SUMS; without
+--require-signature those are checked for integrity and reported as unsigned.
 EOF
 }
 
+tag="${1:-latest}"
 for arg in "${@:2}"; do
   case "$arg" in
     --require-signature) require_signature=1 ;;
@@ -25,19 +52,9 @@ for arg in "${@:2}"; do
     *) echo "unknown option: $arg" >&2; usage >&2; exit 2 ;;
   esac
 done
+if [ "$tag" = "-h" ] || [ "$tag" = "--help" ]; then usage; exit 0; fi
 
-if [ "$tag" = "-h" ] || [ "$tag" = "--help" ]; then
-  usage
-  exit 0
-fi
-
-need() {
-  if ! command -v "$1" >/dev/null 2>&1; then
-    echo "missing required command: $1" >&2
-    exit 1
-  fi
-}
-
+need() { command -v "$1" >/dev/null 2>&1 || { echo "missing required command: $1" >&2; exit 1; }; }
 need sed
 need awk
 
@@ -46,39 +63,25 @@ if command -v sha256sum >/dev/null 2>&1; then
 elif command -v shasum >/dev/null 2>&1; then
   sha_check=(shasum -a 256 -c SHA256SUMS)
 else
-  echo "missing required command: sha256sum or shasum" >&2
-  exit 1
+  echo "missing required command: sha256sum or shasum" >&2; exit 1
 fi
 
 download() {
-  local url="$1"
-  local out="$2"
-  if command -v curl >/dev/null 2>&1; then
-    curl -fsSL "$url" -o "$out"
-  elif command -v wget >/dev/null 2>&1; then
-    wget -q "$url" -O "$out"
-  else
-    echo "missing required command: curl or wget" >&2
-    exit 1
-  fi
+  if command -v curl >/dev/null 2>&1; then curl -fsSL "$1" -o "$2"
+  elif command -v wget >/dev/null 2>&1; then wget -q "$1" -O "$2"
+  else echo "missing required command: curl or wget" >&2; exit 1; fi
 }
 
 if [ "$tag" = "latest" ]; then
-  tag="$(download "https://api.github.com/repos/$repo/releases/latest" - |
-    sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' |
-    head -1)"
-  if [ -z "$tag" ]; then
-    echo "could not resolve latest release tag" >&2
-    exit 1
-  fi
+  tag="$(download "$host/latest.txt" - 2>/dev/null | tr -d '[:space:]' || true)"
+  [ -n "$tag" ] || { echo "could not resolve the latest release tag from $host/latest.txt" >&2; exit 1; }
 fi
 
 workdir="$(mktemp -d "${TMPDIR:-/tmp}/bitflash-release-verify.XXXXXX")"
 cleanup() { rm -rf "$workdir"; }
 trap cleanup EXIT
 
-base_url="https://github.com/$repo/releases/download/$tag"
-
+base_url="$host/$tag"
 echo "Verifying Bitflash $tag"
 echo "Working directory: $workdir"
 cd "$workdir"
@@ -86,27 +89,32 @@ cd "$workdir"
 download "$base_url/SHA256SUMS" SHA256SUMS
 
 if download "$base_url/SHA256SUMS.asc" SHA256SUMS.asc 2>/dev/null; then
-  if ! command -v gpg >/dev/null 2>&1; then
-    echo "SHA256SUMS.asc exists, but gpg is not installed" >&2
+  need gpg
+  # Verify in a throwaway keyring holding ONLY the pinned key, and require that
+  # the signature validates against it with the pinned fingerprint. This is the
+  # difference between "signed" and "signed by Bitflash".
+  keyring="$workdir/keyring"
+  mkdir -p "$keyring"; chmod 700 "$keyring"
+  printf '%s\n' "$RELEASE_KEY" | GNUPGHOME="$keyring" gpg --batch --quiet --import 2>/dev/null
+  status="$(GNUPGHOME="$keyring" gpg --batch --status-fd=1 --verify SHA256SUMS.asc SHA256SUMS 2>/dev/null || true)"
+  if printf '%s' "$status" | grep -q "VALIDSIG.*$RELEASE_KEY_FP"; then
+    echo "Signature OK -- signed by the pinned Bitflash release key"
+  else
+    echo "SIGNATURE REJECTED: not a valid signature by the pinned release key" >&2
+    echo "  expected key: $RELEASE_KEY_FP" >&2
     exit 1
   fi
-  gpg --verify SHA256SUMS.asc SHA256SUMS
-  echo "Signature OK"
 else
   if [ "$require_signature" -eq 1 ]; then
-    echo "release does not publish SHA256SUMS.asc" >&2
-    exit 1
+    echo "release does not publish SHA256SUMS.asc" >&2; exit 1
   fi
-  echo "WARNING: no SHA256SUMS.asc found; checking hashes only"
+  echo "WARNING: no SHA256SUMS.asc found; checking hashes only (unsigned release)"
 fi
 
 awk '{print $2}' SHA256SUMS | while IFS= read -r file; do
-  file="${file#\*}"
-  file="${file#./}"
+  file="${file#\*}"; file="${file#./}"
   [ -z "$file" ] && continue
-  case "$file" in
-    */*|..*) echo "refusing unexpected checksum path: $file" >&2; exit 1 ;;
-  esac
+  case "$file" in */*|..*) echo "refusing unexpected checksum path: $file" >&2; exit 1 ;; esac
   echo "Downloading $file"
   download "$base_url/$file" "$file"
 done
diff --git a/scripts/verify-utxo-proof.py b/scripts/verify-utxo-proof.py
new file mode 100644
index 0000000..50d9356
--- /dev/null
+++ b/scripts/verify-utxo-proof.py
@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Verify a Bitflash UTXO inclusion proof against a UTXO root."""
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+SCHEMA = "bitflash-utxo-inclusion-proof-1"
+
+
+def canonical_bytes(obj):
+    return (json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
+
+
+def load_proof(path):
+    try:
+        return json.loads(Path(path).read_text(encoding="ascii"))
+    except Exception as e:
+        raise SystemExit("could not read proof: %s" % e)
+
+
+def verify(proof, expected_root=None):
+    failures = []
+    if proof.get("schema") != SCHEMA:
+        failures.append("unexpected schema")
+    commitment = proof.get("commitment", {})
+    if commitment.get("algorithm") != "sorted-outpoint-merkle-sha256":
+        failures.append("unexpected commitment algorithm")
+    if commitment.get("leaf_domain") != chain.UTXO_LEAF_DOMAIN:
+        failures.append("unexpected leaf domain")
+    if commitment.get("node_domain") != chain.UTXO_NODE_DOMAIN_TAG:
+        failures.append("unexpected node domain")
+
+    target = proof.get("target", {})
+    outpoint = target.get("outpoint", "")
+    utxo = target.get("utxo", {})
+    if outpoint != "%s:%s" % (target.get("txid"), target.get("vout")):
+        failures.append("target outpoint does not match txid:vout")
+
+    try:
+        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)
+        current = b"\x00" * 32
+        leaf_ok = False
+
+    if not leaf_ok:
+        failures.append("target leaf hash mismatch")
+
+    for i, step in enumerate(proof.get("proof", [])):
+        try:
+            sibling = bytes.fromhex(step["hash"])
+        except Exception:
+            failures.append("bad sibling hash at proof level %d" % i)
+            sibling = b"\x00" * 32
+        if len(sibling) != 32:
+            failures.append("bad sibling hash length at proof level %d" % i)
+        side = step.get("side")
+        if side == "right":
+            current = chain.sha256(chain.UTXO_NODE_DOMAIN + current + sibling)
+        elif side == "left":
+            current = chain.sha256(chain.UTXO_NODE_DOMAIN + sibling + current)
+        else:
+            failures.append("bad sibling side at proof level %d" % i)
+
+    computed_root = current.hex()
+    root = expected_root or commitment.get("root")
+    if computed_root != root:
+        failures.append("computed root does not match expected root")
+
+    return {
+        "schema": "bitflash-utxo-proof-verification-1",
+        "deterministic": True,
+        "target": {
+            "outpoint": outpoint,
+            "value_satoshis": utxo.get("value_satoshis"),
+            "value_btf": utxo.get("value_btf"),
+            "created_height": utxo.get("created_height"),
+        },
+        "commitment": {
+            "expected_root": root,
+            "computed_root": computed_root,
+            "leaf_hash": target.get("leaf_hash"),
+            "path_length": len(proof.get("proof", [])),
+        },
+        "checks": {
+            "schema_is_supported": proof.get("schema") == SCHEMA,
+            "leaf_hash_matches_target": leaf_ok,
+            "root_matches": computed_root == root,
+        },
+        "failures": failures,
+        "verdict": "UTXO_PROOF_VERIFIED" if not failures else "UTXO_PROOF_FAILED",
+    }
+
+
+def print_text(result):
+    data_hash = hashlib.sha256(canonical_bytes(result)).hexdigest()
+    print("Bitflash UTXO proof verifier")
+    print("schema: %s" % result["schema"])
+    print("canonical verification sha256: %s" % data_hash)
+    print()
+    print("Target")
+    print("  outpoint: %s" % result["target"]["outpoint"])
+    print("  value:    %s BTF" % result["target"]["value_btf"])
+    print("  height:   %s" % result["target"]["created_height"])
+    print()
+    print("Commitment")
+    print("  expected: %s" % result["commitment"]["expected_root"])
+    print("  computed: %s" % result["commitment"]["computed_root"])
+    print("  path:     %d sibling hashes" % result["commitment"]["path_length"])
+    print()
+    print("Checks")
+    for key in sorted(result["checks"]):
+        print("  %s %s" % ("OK  " if result["checks"][key] else "FAIL", key))
+    if result["failures"]:
+        print()
+        print("Failures")
+        for failure in result["failures"]:
+            print("  - %s" % failure)
+    print()
+    print("Verdict: %s" % result["verdict"])
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("proof", help="canonical JSON proof from prove-utxo.py")
+    ap.add_argument("--root", help="expected UTXO root; defaults to root embedded in proof")
+    ap.add_argument("--json", action="store_true", help="print canonical JSON")
+    args = ap.parse_args(argv)
+
+    result = verify(load_proof(args.proof), args.root)
+    data = canonical_bytes(result)
+    if args.json:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(result)
+    return 0 if result["verdict"] == "UTXO_PROOF_VERIFIED" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/verify-utxo-set.py b/scripts/verify-utxo-set.py
new file mode 100644
index 0000000..b5bf3d5
--- /dev/null
+++ b/scripts/verify-utxo-set.py
@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Build a deterministic Bitflash UTXO-set commitment from local blk*.dat."""
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+
+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 = chain.utxo_root(utxos)
+    checks = {
+        "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,
+    }
+    warnings = {
+        "legacy_duplicate_output_overwrites": len(stats["duplicate_outputs"]),
+    }
+    report = {
+        "schema": "bitflash-utxo-set-commitment-1",
+        "deterministic": True,
+        "chain": {
+            "name": "Bitflash",
+            "ticker": "BTF",
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
+        },
+        "commitment": {
+            "algorithm": "sorted-outpoint-merkle-sha256",
+            "leaf_domain": "BTFUTXO1",
+            "node_domain": "BTFNODE1",
+            "root": root,
+        },
+        "scanned": {
+            "raw_block_count": len(raw_blocks),
+            "side_blocks_ignored": len(raw_blocks) - len(blocks),
+            "main_chain_block_count": len(blocks),
+            "first_height": 0,
+            "last_height": len(blocks) - 1,
+            "tip_hash": tip["hash"],
+            "tip_time": tip["time"],
+            "tip_time_utc": tip["time_utc"],
+        },
+        "stats": stats,
+        "checks": checks,
+        "warnings": warnings,
+        "verdict": "UTXO_COMMITMENT_VERIFIED" if all(checks.values()) else "CHECKS_FAILED",
+    }
+    if include_utxos:
+        report["utxos"] = {k: utxos[k] for k in sorted(utxos)}
+    return report
+
+
+def print_text(report):
+    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)
+    print()
+    print("Commitment")
+    print("  root:   %s" % report["commitment"]["root"])
+    print("  algo:   %s" % report["commitment"]["algorithm"])
+    print()
+    print("Scanned")
+    print("  main chain blocks: %d" % report["scanned"]["main_chain_block_count"])
+    print("  raw disk blocks:   %d" % report["scanned"]["raw_block_count"])
+    print("  side ignored:      %d" % report["scanned"]["side_blocks_ignored"])
+    print("  height: %d..%d" % (report["scanned"]["first_height"], report["scanned"]["last_height"]))
+    print("  tip:    %s" % report["scanned"]["tip_hash"])
+    print()
+    print("Supply")
+    print("  utxos:  %d" % report["stats"]["utxo_count"])
+    print("  supply: %s BTF" % report["stats"]["total_unspent_btf"])
+    print("  mined:  %s BTF" % report["stats"]["total_coinbase_btf"])
+    print("  delta:  %s BTF" % report["stats"]["coinbase_minus_unspent_btf"])
+    print("  fees:   %s BTF" % report["stats"]["total_fees_btf"])
+    if report["warnings"]["legacy_duplicate_output_overwrites"]:
+        print("  legacy duplicate overwrites: %d" % report["warnings"]["legacy_duplicate_output_overwrites"])
+    print()
+    print("Checks")
+    for key in sorted(report["checks"]):
+        print("  %s %s" % ("OK  " if report["checks"][key] else "FAIL", key))
+    print()
+    print("Verdict: %s" % report["verdict"])
+    print()
+    print("OpenTimestamps")
+    print("  canonical JSON can be stamped later with: ots stamp <report.json>")
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    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 = chain.read_blocks(args.datadir, args.max_blocks)
+    if not blocks:
+        raise SystemExit("no Bitflash blocks found in %s" % args.datadir)
+    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:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(report)
+    return 0 if report["verdict"] == "UTXO_COMMITMENT_VERIFIED" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))