tools: static block explorer generator (v0)

1 files changed, 243 insertions, 0 deletions

diff --git a/scripts/build-explorer.py b/scripts/build-explorer.py
new file mode 100755
index 0000000..7849e8a
--- /dev/null
+++ b/scripts/build-explorer.py
@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+#
+# Build a static Bitflash block explorer (v0) from a node's blk0001.dat.
+# Emits into <out-dir>:
+#   blocks.json            summary of every main-chain block (newest first)
+#   block/<height>.json    full detail per block (header + all txs)
+#   index.html             self-contained viewer (vanilla JS, same-origin fetch)
+#
+# Scope (v0, deliberately): block list, block detail, and coinbase. No mempool,
+# no per-address history. On this chain the coinbase payout key rotates every
+# block, so an address index would be nearly useless; block-level transparency is
+# what lets miners and users confirm the chain is honest.
+#
+# Usage: build-explorer.py <blk0001.dat> <out-dir>
+
+import sys, os, json, hashlib, struct
+
+MAGIC = bytes([0xbf, 0x20, 0x5c, 0xfd])
+ADDRESS_VERSION = 25  # Bitflash addresses start with "B"
+
+def sha256d(b): return hashlib.sha256(hashlib.sha256(b).digest()).digest()
+
+B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+def b58check(payload):
+    v = bytes([ADDRESS_VERSION]) + payload
+    v += 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()
+
+class R:
+    def __init__(s, b, o=0): s.b = b; s.o = o
+    def u(s, n): v = s.b[s.o:s.o+n]; s.o += n; return v
+    def i32(s): return struct.unpack('<i', s.u(4))[0]
+    def u32(s): return struct.unpack('<I', s.u(4))[0]
+    def i64(s): return struct.unpack('<q', s.u(8))[0]
+    def cs(s):
+        c = s.b[s.o]; s.o += 1
+        if c < 253: return c
+        if c == 253: return struct.unpack('<H', s.u(2))[0]
+        if c == 254: return struct.unpack('<I', s.u(4))[0]
+        return struct.unpack('<Q', s.u(8))[0]
+    def script(s): n = s.cs(); return s.u(n)
+
+def spk_info(spk):
+    # P2PKH: OP_DUP OP_HASH160 <20> OP_EQUALVERIFY OP_CHECKSIG
+    if len(spk) == 25 and spk[0] == 0x76 and spk[1] == 0xa9 and spk[2] == 0x14 and spk[23] == 0x88 and spk[24] == 0xac:
+        return {"type": "p2pkh", "address": b58check(spk[3:23])}
+    # P2PK: <pubkey> OP_CHECKSIG (65- or 33-byte key)
+    if len(spk) >= 35 and spk[-1] == 0xac:
+        if 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": spk.hex()[:80]}
+
+def parse_tx(r):
+    start = r.o
+    r.i32()
+    nin = r.cs(); vin = []
+    for _ in range(nin):
+        ph = r.u(32); idx = r.u32(); r.script(); r.u32()
+        coinbase = (ph == b'\x00' * 32 and idx == 0xffffffff)
+        vin.append({"coinbase": coinbase, "prev": (None if coinbase else ph[::-1].hex()), "vout": (None if coinbase else idx)})
+    nout = r.cs(); vout = []
+    for _ in range(nout):
+        val = r.i64(); spk = r.script(); vout.append(dict({"value": val}, **spk_info(spk)))
+    r.u32()
+    raw = r.b[start:r.o]
+    return {"txid": sha256d(raw)[::-1].hex(), "vin": vin, "vout": vout, "size": len(raw)}
+
+def main():
+    if len(sys.argv) != 3:
+        print("usage: build-explorer.py <blk0001.dat> <out-dir>", file=sys.stderr); sys.exit(2)
+    blkpath, out = sys.argv[1], sys.argv[2]
+    data = open(blkpath, 'rb').read()
+    blocks = {}; o = 0; n = len(data)
+    while o + 8 <= n:
+        if data[o:o+4] != MAGIC: o += 1; continue
+        o += 4; size = struct.unpack('<I', data[o:o+4])[0]; o += 4
+        blk = data[o:o+size]; o += size
+        if len(blk) < 80: continue
+        h = sha256d(blk[:80])[::-1].hex()
+        r = R(blk, 0)
+        ver = r.i32(); prev = r.u(32)[::-1].hex(); merk = r.u(32)[::-1].hex()
+        t = r.u32(); bits = r.u32(); nonce = r.u32()
+        ntx = r.cs(); txs = []
+        try:
+            for _ in range(ntx): txs.append(parse_tx(r))
+        except Exception:
+            continue
+        blocks[h] = {"hash": h, "prev": prev, "merkleRoot": merk, "version": ver,
+                     "time": t, "bits": bits, "nonce": nonce, "size": size, "txs": txs}
+    if not blocks:
+        print("no blocks parsed", file=sys.stderr); sys.exit(1)
+
+    hc = {}
+    def height(h):
+        chain = []; cur = h
+        while cur in blocks and cur not in hc:
+            chain.append(cur); cur = blocks[cur]["prev"]
+        base = hc.get(cur, 0)
+        for hh in reversed(chain): base += 1; hc[hh] = base
+        return hc[h]
+    for h in blocks: height(h)
+    tip = max(blocks, key=lambda h: hc[h])
+    chain = []; cur = tip
+    while cur in blocks: chain.append(cur); cur = blocks[cur]["prev"]
+    chain.reverse()
+
+    os.makedirs(os.path.join(out, "block"), exist_ok=True)
+    summaries = []
+    for h in chain:
+        b = blocks[h]; H = hc[h]
+        cb = b["txs"][0]["vout"][0] if b["txs"] and b["txs"][0]["vout"] else {}
+        summaries.append({"height": H, "hash": h, "time": b["time"], "nTx": len(b["txs"]),
+                          "size": b["size"], "cbValue": cb.get("value", 0), "cbAddr": cb.get("address", "")})
+        json.dump(dict({"height": H}, **b), open(os.path.join(out, "block", "%d.json" % H), "w"), separators=(',', ':'))
+    summaries.sort(key=lambda x: -x["height"])
+    json.dump({"network": "bitflash", "tipHeight": hc[tip], "count": len(chain), "blocks": summaries},
+              open(os.path.join(out, "blocks.json"), "w"), separators=(',', ':'))
+    open(os.path.join(out, "index.html"), "w").write(INDEX_HTML)
+    print("explorer built: %d main-chain blocks, tip %d, into %s" % (len(chain), hc[tip], out))
+
+
+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>
+<style>
+  :root { color-scheme: light dark; --bg:#fff; --fg:#111; --mut:#666; --line:#e2e2e2; --card:#fafafa; --acc:#2b6cb0; }
+  @media (prefers-color-scheme: dark){ :root{ --bg:#0e0f11; --fg:#e6e6e6; --mut:#9aa0a6; --line:#26282c; --card:#16181b; --acc:#63b3ed; } }
+  * { box-sizing: border-box; }
+  body { font: 15px/1.5 system-ui, sans-serif; margin:0; background:var(--bg); color:var(--fg); }
+  header { padding:20px 24px; border-bottom:1px solid var(--line); display:flex; gap:16px; align-items:baseline; flex-wrap:wrap; }
+  h1 { font-size:18px; margin:0; }
+  .mut { color:var(--mut); }
+  .wrap { padding:16px 24px; max-width:1100px; margin:0 auto; }
+  input { width:100%; max-width:420px; padding:9px 12px; border:1px solid var(--line); border-radius:8px; background:var(--card); color:var(--fg); font-size:14px; }
+  table { width:100%; border-collapse:collapse; margin-top:12px; }
+  th,td { text-align:left; padding:9px 10px; border-bottom:1px solid var(--line); font-variant-numeric:tabular-nums; }
+  th { font-size:12px; text-transform:uppercase; letter-spacing:.05em; color:var(--mut); }
+  tr.blk { cursor:pointer; }
+  tr.blk:hover td { background:var(--card); }
+  code { font-size:12px; word-break:break-all; }
+  .scroll { overflow-x:auto; }
+  a { color:var(--acc); text-decoration:none; }
+  .card { border:1px solid var(--line); border-radius:10px; background:var(--card); padding:14px 16px; margin-top:12px; }
+  .kv { display:grid; grid-template-columns:150px 1fr; gap:4px 12px; font-size:13px; }
+  .kv div:nth-child(odd){ color:var(--mut); }
+  .tx { border-top:1px solid var(--line); padding:10px 0; }
+  .io { display:grid; grid-template-columns:1fr 1fr; gap:16px; }
+  @media (max-width:640px){ .io{ grid-template-columns:1fr; } .kv{ grid-template-columns:110px 1fr; } }
+  .pill { display:inline-block; font-size:11px; padding:1px 7px; border-radius:99px; border:1px solid var(--line); color:var(--mut); }
+  button.link { background:none; border:none; color:var(--acc); cursor:pointer; font:inherit; padding:0; }
+  .note { color:var(--mut); font-size:13px; max-width:820px; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Bitflash Block Explorer</h1>
+  <span class="mut" id="tip"></span>
+  <span style="flex:1"></span>
+  <button class="link" id="home" style="display:none">back to blocks</button>
+</header>
+<div class="wrap">
+  <p class="note">Read-only view of the main chain: blocks, their transactions, and the coinbase payout. There is no mempool and no per-address history here. On Bitflash the coinbase payout key rotates every block, so an address index would say almost nothing; what matters is that every block and every coinbase is here to check.</p>
+  <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" style="display:none"></div>
+</div>
+<script>
+var SUM = [], BYH = {}, SHOWN = 200;
+function btf(sat){ return (sat/1e8).toFixed(8).replace(/0+$/,'').replace(/\.$/,'')+" BTF"; }
+function ts(t){ return new Date(t*1000).toISOString().replace('T',' ').replace('.000Z',' UTC'); }
+function esc(s){ return String(s).replace(/[&<>]/g,function(c){return {'&':'&amp;','<':'&lt;','>':'&gt;'}[c];}); }
+function short(h){ return h ? h.slice(0,10)+"…"+h.slice(-6) : "-"; }
+
+function renderList(filter){
+  var q=(filter||"").trim().toLowerCase(), rows=document.getElementById('rows'), out="";
+  var list = q ? SUM.filter(function(b){ return String(b.height)===q || b.hash.indexOf(q)===0; }) : SUM.slice(0,SHOWN);
+  for(var i=0;i<list.length;i++){ var b=list[i];
+    out += '<tr class="blk" data-h="'+b.height+'"><td>'+b.height+'</td><td>'+ts(b.time)+'</td><td>'+b.nTx+'</td><td>'+b.size+' B</td><td>'+btf(b.cbValue)+'</td><td><code>'+(b.cbAddr?esc(b.cbAddr):'-')+'</code></td></tr>';
+  }
+  rows.innerHTML = out || '<tr><td colspan="6" class="mut">no match</td></tr>';
+  document.getElementById('more').textContent = (!q && SUM.length>SHOWN) ? ("showing latest "+SHOWN+" of "+SUM.length+" blocks; search to find any") : "";
+  Array.prototype.forEach.call(rows.querySelectorAll('tr.blk'), function(tr){ tr.onclick=function(){ openBlock(tr.getAttribute('data-h')); }; });
+}
+function ioSide(title, items, html){
+  var s='<div><div class="mut">'+title+'</div>'; for(var i=0;i<items.length;i++){ s+=html(items[i]); } return s+'</div>';
+}
+function openBlock(h){
+  fetch('block/'+h+'.json').then(function(r){return r.json();}).then(function(b){
+    var s='<div class="card"><div class="kv">'+
+      '<div>Height</div><div>'+b.height+'</div>'+
+      '<div>Hash</div><div><code>'+esc(b.hash)+'</code></div>'+
+      '<div>Previous</div><div><button class="link" onclick="openBlock('+(b.height-1)+')"><code>'+esc(short(b.prev))+'</code></button></div>'+
+      '<div>Merkle root</div><div><code>'+esc(b.merkleRoot)+'</code></div>'+
+      '<div>Time (UTC)</div><div>'+ts(b.time)+'</div>'+
+      '<div>Bits / Nonce</div><div>'+b.bits.toString(16)+' / '+b.nonce+'</div>'+
+      '<div>Size / Txs</div><div>'+b.size+' B / '+b.txs.length+'</div>'+
+      '</div></div>';
+    for(var i=0;i<b.txs.length;i++){ var t=b.txs[i];
+      s+='<div class="tx"><div><code>'+esc(t.txid)+'</code> '+(i===0?'<span class="pill">coinbase</span>':'')+'</div><div class="io">';
+      s+=ioSide('Inputs', t.vin, function(v){ return '<div>'+(v.coinbase?'<span class="pill">coinbase</span>':'<code>'+esc(short(v.prev))+':'+v.vout+'</code>')+'</div>'; });
+      s+=ioSide('Outputs', t.vout, function(o){ var to=o.address?esc(o.address):(o.pubkey?'pubkey '+esc(o.pubkey.slice(0,16))+'…':esc(o.type)); return '<div>'+btf(o.value)+' → <code>'+to+'</code></div>'; });
+      s+='</div></div>';
+    }
+    document.getElementById('listview').style.display='none';
+    var d=document.getElementById('detail'); d.style.display='block'; d.innerHTML='<h2 style="font-size:16px">Block '+b.height+'</h2>'+s;
+    document.getElementById('home').style.display='inline';
+    window.scrollTo(0,0);
+  });
+}
+document.getElementById('home').onclick=function(){ document.getElementById('detail').style.display='none'; document.getElementById('listview').style.display='block'; this.style.display='none'; };
+document.getElementById('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('');
+});
+</script>
+</body>
+</html>
+"""
+
+if __name__ == "__main__":
+    main()