From 0270b35528388241a6e6b843503cea342c640c30 Mon Sep 17 00:00:00 2001
From: Nsable-sh <nsable-sh@noreply.git.bitflash.network>
Date: Tue, 11 Aug 2026 15:11:40 -0300
Subject: tests: add deterministic chain tool fixtures

---
 tests/scripts/test_bitflash_tools.py | 178 ++++++++++++++++++++++++++++++++++-
 1 file changed, 177 insertions(+), 1 deletion(-)

(limited to 'tests/scripts/test_bitflash_tools.py')

diff --git a/tests/scripts/test_bitflash_tools.py b/tests/scripts/test_bitflash_tools.py
index ff569e1..4b18d1e 100644
--- a/tests/scripts/test_bitflash_tools.py
+++ b/tests/scripts/test_bitflash_tools.py
@@ -12,6 +12,7 @@ from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[2]
 SCRIPTS = ROOT / "scripts"
+FIXTURES = ROOT / "tests" / "fixtures" / "chain-tools"
 sys.path.insert(0, str(SCRIPTS))
 
 import bitflash_chain as chain  # noqa: E402
@@ -45,12 +46,130 @@ def write_block_file(path, blocks):
             f.write(payload)
 
 
+def p2pkh_script(byte):
+    return "76a914%s88ac" % (bytes([byte]) * 20).hex()
+
+
+def make_tx(vin, vout):
+    tx = {
+        "version": 1,
+        "vin": vin,
+        "vout": vout,
+        "lock_time": 0,
+    }
+    tx["txid"] = chain.hash_hex(chain.ser_tx(tx))
+    return tx
+
+
+def make_coinbase(label, script_byte, value=50 * chain.COIN):
+    return make_tx(
+        [{
+            "prevout_hash": "0" * 64,
+            "prevout_n": 0xFFFFFFFF,
+            "script_sig_hex": label.encode("ascii").hex(),
+            "sequence": 0xFFFFFFFF,
+        }],
+        [{
+            "value_satoshis": value,
+            "value_btf": chain.format_money(value),
+            "script_pub_key_hex": p2pkh_script(script_byte),
+        }],
+    )
+
+
+def make_spend(prev_txid, prev_n, outputs, label):
+    return make_tx(
+        [{
+            "prevout_hash": prev_txid,
+            "prevout_n": prev_n,
+            "script_sig_hex": label.encode("ascii").hex(),
+            "sequence": 0xFFFFFFFF,
+        }],
+        [{
+            "value_satoshis": value,
+            "value_btf": chain.format_money(value),
+            "script_pub_key_hex": p2pkh_script(script_byte),
+        } for value, script_byte in outputs],
+    )
+
+
+def make_block(prev_hash, txs, ntime, nonce):
+    merkle = chain.merkle_root([tx["txid"] for tx in txs])
+    header = (
+        struct.pack("<i", 1)
+        + bytes.fromhex(prev_hash)[::-1]
+        + bytes.fromhex(merkle)[::-1]
+        + struct.pack("<III", ntime, chain.GENESIS_BITS, nonce)
+    )
+    block = {
+        "hash": chain.hash_hex(header),
+        "version": 1,
+        "previous_hash": prev_hash,
+        "merkle_root": merkle,
+        "computed_merkle_root": merkle,
+        "time": ntime,
+        "time_utc": chain.utc(ntime),
+        "bits": "0x%08x" % chain.GENESIS_BITS,
+        "nonce": nonce,
+        "tx_count": len(txs),
+        "transactions": txs,
+        "source_file": "synthetic",
+        "source_offset": 0,
+        "size": 80 + len(chain.ser_compact_size(len(txs))) + sum(len(chain.ser_tx(tx)) for tx in txs),
+    }
+    return block
+
+
+def fixture_chain():
+    genesis = chain.reconstructed_genesis()
+    spend1 = make_spend(
+        chain.GENESIS_MERKLE,
+        0,
+        [(30 * chain.COIN, 0x22), (19 * chain.COIN, 0x33)],
+        "spend genesis with 1 BTF fee",
+    )
+    block1 = make_block(
+        genesis["hash"],
+        [make_coinbase("fixture coinbase 1", 0x11), spend1],
+        chain.GENESIS_TIME + 120,
+        4001,
+    )
+    spend2 = make_spend(
+        spend1["txid"],
+        0,
+        [(12 * chain.COIN, 0x44), (17 * chain.COIN + 50_000_000, 0x55)],
+        "split spend with 0.5 BTF fee",
+    )
+    block2 = make_block(
+        block1["hash"],
+        [make_coinbase("fixture coinbase 2", 0x66), spend2],
+        chain.GENESIS_TIME + 240,
+        4002,
+    )
+    return [genesis, block1, block2], {
+        "genesis_outpoint": "%s:0" % chain.GENESIS_MERKLE,
+        "first_spend_txid": spend1["txid"],
+        "proof_outpoint": "%s:1" % spend2["txid"],
+    }
+
+
+def compare_golden(name, actual, update):
+    path = FIXTURES / name
+    if update:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(actual)
+        return
+    expected = path.read_bytes()
+    if actual != expected:
+        raise AssertionError("golden mismatch: %s" % name)
+
+
 def assert_true(cond, msg):
     if not cond:
         raise AssertionError(msg)
 
 
-def main():
+def run_genesis_smoke():
     genesis = chain.reconstructed_genesis()
     outpoint = "%s:0" % chain.GENESIS_MERKLE
 
@@ -99,6 +218,63 @@ def main():
         else:
             raise AssertionError("strict duplicate output mode did not fail")
 
+
+def run_golden_fixture(update):
+    blocks, meta = fixture_chain()
+
+    with tempfile.TemporaryDirectory(prefix="bitflash-tool-golden-") as tmp:
+        tmp = Path(tmp)
+        datadir = tmp / "datadir"
+        datadir.mkdir()
+        blk1 = datadir / "blk0001.dat"
+        blk2 = datadir / "blk0002.dat"
+        write_block_file(blk1, blocks[:2])
+        write_block_file(blk2, blocks[2:])
+
+        fair = run([SCRIPTS / "verify-fair-launch.py", "--datadir", datadir,
+                    "--max-blocks", "3", "--json"]).stdout.encode("ascii")
+        compare_golden("fair-launch-report.json", fair, update)
+        fair_report = json.loads(fair)
+        assert_true(fair_report["scanned"]["non_coinbase_transactions"] == 2,
+                    "fair-launch fixture did not count normal transactions")
+
+        utxo = run([SCRIPTS / "verify-utxo-set.py", "--datadir", datadir,
+                    "--include-utxos", "--strict-duplicates", "--json"]).stdout.encode("ascii")
+        compare_golden("utxo-report.json", utxo, update)
+        utxo_report = json.loads(utxo)
+        assert_true(utxo_report["stats"]["normal_transactions"] == 2,
+                    "UTXO fixture did not apply normal transactions")
+        assert_true(utxo_report["stats"]["total_fees_btf"] == "1.50000000",
+                    "UTXO fixture fee total changed")
+        assert_true(meta["genesis_outpoint"] not in utxo_report["utxos"],
+                    "spent genesis output still appears in the UTXO map")
+
+        proof_path = tmp / "fixture-proof.json"
+        proof = run([SCRIPTS / "prove-utxo.py", meta["proof_outpoint"],
+                     "--datadir", datadir, "--strict-duplicates",
+                     "--out", proof_path, "--json"]).stdout.encode("ascii")
+        compare_golden("utxo-proof.json", proof, update)
+
+        proof_check = run([SCRIPTS / "verify-utxo-proof.py", proof_path,
+                           "--root", utxo_report["commitment"]["root"], "--json"]).stdout.encode("ascii")
+        compare_golden("utxo-proof-verification.json", proof_check, update)
+        proof_report = json.loads(proof_check)
+        assert_true(proof_report["verdict"] == "UTXO_PROOF_VERIFIED",
+                    "fixture UTXO proof did not verify")
+
+        explorer_dir = tmp / "explorer"
+        run([SCRIPTS / "build-explorer.py", blk1, blk2, explorer_dir])
+        compare_golden("explorer-blocks.json",
+                       (explorer_dir / "blocks.json").read_bytes(), update)
+        detail = json.loads((explorer_dir / "block" / "1.json").read_text(encoding="ascii"))
+        assert_true(len(detail["txs"]) == 2,
+                    "explorer fixture block did not include the normal transaction")
+
+
+def main():
+    update = "--update-goldens" in sys.argv[1:]
+    run_genesis_smoke()
+    run_golden_fixture(update)
     print("Bitflash script tool regressions passed")
     return 0
 
-- 
cgit v1.2.3