SPV Verification

​

Why SPV Works

• The hash of the previous block (linking the chain)
• A Merkle root - a single hash that commits to every transaction in the block
• A nonce and target - proof that miners did computational work to produce this block

1. The block header - to verify it has valid proof-of-work
2. A Merkle proof - a set of sibling hashes that, combined with your transaction’s hash, reproduce the Merkle root in the header
3. The raw transaction - to verify the transaction data matches the hash

​

The Writz Approach: an On-Chain Header Light Client

• One trusted anchor. The admin sets a checkpoint - a recent real Bitcoin block - exactly once. Every stored header must descend from it.
• Anyone can extend the chain. submit_headers accepts a run of contiguous headers, checks each one (proof-of-work, link to a stored parent, the exact difficulty Bitcoin requires at that height, sane timestamp) and keeps the chain with the most cumulative work. The Writz relayer does this routinely, but any party can.
• Proofs are cheap. verify_transaction names a stored block and checks a Merkle proof against its root. It no longer re-validates a header chain on every call.

​

What the Contract Verifies

pub fn verify_transaction(
    env: Env,
    block_hash: BytesN<32>,         // Hash of the (already stored) block holding the tx
    merkle_proof: Vec<BytesN<32>>,  // Sibling hashes from tx to block root
    tx_index: u32,                  // Transaction's index in the block
    raw_tx: Bytes,                  // The raw Bitcoin transaction (non-witness)
    min_confirmations: u32,         // Minimum depth required (default: 6)
) -> SpvVerificationResult

• Each header’s prev_block_hash must be a header the contract already stores (ultimately the checkpoint)
• SHA256d(header) must meet the target encoded in bits
• bits must equal what Bitcoin’s difficulty rules require at that height: unchanged inside a 2016-block period, the exact retarget at each boundary
• The timestamp may not be more than two hours ahead of ledger time
• The chain with the most cumulative work becomes the best chain; a heavier fork replaces it

• The block must be stored, after the checkpoint, and on the best chain
• Its depth below the best tip must be at least min_confirmations
• raw_tx must not be exactly 64 bytes (the size of a Merkle inner-node preimage)
• Compute txid = SHA256d(raw_tx), walk the Merkle proof (alternating left/right by tx_index), and the result must equal the stored block’s merkle_root
• Return SpvVerificationResult { txid, block_hash, confirmations }, where confirmations is the block’s real depth

​

SHA256d: Bitcoin’s Hash Function

SHA256d(x) = SHA256(SHA256(x))

​

The Relayer Service

1. Watches a Bitcoin Esplora API for transactions to monitored addresses
2. Fetches the raw transaction, the block header it was included in, and sufficient ancestor headers to meet min_confirmations
3. Computes the Merkle proof from the block’s transaction list
4. Packages everything into a sorobanArgs bundle ready to submit to the SPV contract

GET /spv-proof/{txid}

Response:
{
  "txid": "11932100...",
  "block_hash": "00000000...",
  "confirmations": 6,
  "sorobanArgs": {
    "headers": [...],
    "merkleProof": [...],
    "txIndex": 42,
    "rawTx": "0200000001..."
  }
}

​

Security Guarantees

• A user sending BTC to the wrong P2WSH address (user error)
• A deep reorg affecting more than 6 blocks (extraordinarily unlikely, but theoretically possible on a heavily attacked network)
• Bugs in the SPV contract itself (mitigated by audits and extensive testing)

​

Tested on Real Bitcoin Transactions

• Real Bitcoin mainnet transactions (correct txid and block_hash verified against Python-computed SHA256d)
• Multiple block depths (1, 3, 6, 12 confirmations)
• Multi-transaction blocks with varying Merkle proof sizes
• Edge cases: single-transaction blocks, maximum-size transactions