​

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: Stateless SPV

• No relayer dependency for core security: The SPV contract can be called by anyone with the right data. Writz runs a relayer service as a convenience, but it is not a critical path component.
• No growing on-chain state: A stateful header chain would grow indefinitely; a per-call header submission never accumulates that way.
• Simpler audit surface: The verification logic is a pure function of its inputs plus one small anchor value - given inputs, it returns a result. No header-chain state transitions to reason about.

​

What the Contract Verifies

pub fn verify_transaction(
    env: Env,
    headers: Vec<BitcoinBlockHeader>,  // The block headers (starting from anchor)
    merkle_proof: Vec<Bytes32>,        // Sibling hashes from tx to block root
    tx_index: u32,                     // Transaction's index in the block
    raw_tx: Bytes,                     // The raw Bitcoin transaction
    min_confirmations: u32,            // Minimum depth required (default: 6)
) -> SpvVerificationResult

• Parse the 80-byte header into its fields (version, prev_block, merkle_root, time, bits, nonce)
• Compute SHA256d(header) - Bitcoin’s double-SHA256 block hash
• Verify the hash meets the difficulty target encoded in bits
• Verify the chain is continuous: headers[i].prev_block == SHA256d(headers[i-1])
• Verify no header’s target is more than 64× easier than the stored checkpoint’s difficulty - this is what rules out a chain mined at a historically low (e.g. 2009-era) difficulty even though it would otherwise pass its own PoW check

• Compute txid = SHA256d(raw_tx) (one double-SHA256, not a fourth-power hash)
• Walk the Merkle proof: repeatedly hash txid with each sibling in the proof, alternating left/right based on tx_index
• The final hash must equal headers[0].merkle_root

• len(headers) >= min_confirmations (checked up front, before Step 1’s chain validation)
• Return SpvVerificationResult { txid, block_hash, confirmations }

​

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