From 034bc9a9497a336239aadb2e52d620661e90e536 Mon Sep 17 00:00:00 2001
From: Nsable-sh <nsable-sh@noreply.git.bitflash.network>
Date: Tue, 11 Aug 2026 09:31:58 -0300
Subject: tools: add UTXO inclusion proofs

---
 docs/utxo-commitment.md | 14 ++++++++++++
 docs/utxo-proofs.md     | 61 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 docs/utxo-proofs.md

(limited to 'docs')

diff --git a/docs/utxo-commitment.md b/docs/utxo-commitment.md
index ddf5450..991e5d9 100644
--- a/docs/utxo-commitment.md
+++ b/docs/utxo-commitment.md
@@ -54,6 +54,20 @@ SHA256("BTFNODE1|" || left_hash || right_hash)
 
 The final hash is the UTXO-set root.
 
+## Inclusion Proofs
+
+After a root has been computed, `scripts/prove-utxo.py` can create a compact
+inclusion proof for one unspent output:
+
+```bash
+python3 scripts/prove-utxo.py TXID:VOUT --out utxo-proof.json --json
+python3 scripts/verify-utxo-proof.py utxo-proof.json
+```
+
+The verifier does not need local block files. It recomputes the target leaf,
+walks the sibling path, and compares the result with the expected root. See
+[UTXO inclusion proofs](utxo-proofs.md).
+
 ## Deterministic Output
 
 `--json` and `--out` write canonical JSON with sorted keys, fixed separators,
diff --git a/docs/utxo-proofs.md b/docs/utxo-proofs.md
new file mode 100644
index 0000000..4947c3c
--- /dev/null
+++ b/docs/utxo-proofs.md
@@ -0,0 +1,61 @@
+# Bitflash UTXO inclusion proofs
+
+`scripts/prove-utxo.py` creates a deterministic inclusion proof for one
+currently unspent output. `scripts/verify-utxo-proof.py` verifies that proof
+against the UTXO root produced by `scripts/verify-utxo-set.py`.
+
+This is intentionally outside consensus. It turns the audit root into something
+useful for a specific coin without changing what nodes accept.
+
+## Create A Proof
+
+Use an unspent output in `txid:vout` form:
+
+```bash
+python3 scripts/prove-utxo.py TXID:VOUT --out utxo-proof.json --json
+```
+
+The proof contains:
+
+- the target UTXO;
+- its sorted leaf index;
+- the leaf hash;
+- the Merkle sibling path;
+- the UTXO root and chain tip used to create it.
+
+It does not contain the full UTXO set.
+
+## Verify A Proof
+
+Verify against the root embedded in the proof:
+
+```bash
+python3 scripts/verify-utxo-proof.py utxo-proof.json
+```
+
+Or verify against a root copied from another machine, dashboard, block explorer,
+or future node export:
+
+```bash
+python3 scripts/verify-utxo-proof.py utxo-proof.json \
+  --root ROOT_FROM_REPORT_OR_EXPORT
+```
+
+The verifier does not need local `blk*.dat` files. It only needs the proof and
+the expected root.
+
+## Scope
+
+This first proof format supports inclusion only. Absence and range proofs are
+left for a later design because they require a more careful commitment scheme
+and are easier to get subtly wrong.
+
+The proof uses the exact same leaf and node domains as the UTXO commitment:
+
+```text
+BTFUTXO1
+BTFNODE1
+```
+
+That keeps the verifier language-neutral and gives future implementations a
+small, stable target.
-- 
cgit v1.2.3