ERC-8002 Bitcoin SPV verification gateway (Simplified Payment Verification Gateway)
Draft · Vaults & DeFi · created 2025-08-07
A trust-minimized SPV gateway contract that stacks Bitcoin block headers on Ethereum so anyone can verify them, maintaining a mainchain and using Merkle proofs to confirm the existence of specific Bitcoin transactions.
Why it is needed
Bitcoin's programmability is extremely limited, so there is little it can do beyond trustless holding and transfer. Using Bitcoin as collateral on Ethereum or as proof of payment has therefore required trusting centralized bridges or wrapped token issuers. Such intermediaries can freeze assets or report incorrect state, so the very process of connecting Bitcoin to Ethereum DeFi has run counter to Ethereum's trustless design goals. Without this standard, there is no way to use native BTC as collateral for stablecoin loans or for an onchain contract to directly confirm that a Bitcoin payment actually occurred.
What to implement
event BlockHeaderAdded(uint64 indexed blockHeight, bytes32 indexed blockHash);: Emitted with the block height and block hash whenever a new block header is added to the contract's state.function addBlockHeader(bytes calldata blockHeaderRaw) external;: Receives a single raw 80-byte block header, verifies it, and appends it to the chain.function addBlockHeaderBatch(bytes[] calldata blockHeaderRawArray) external;: An OPTIONAL function that receives multiple block headers as an array and verifies and appends each in order.function getMainchainHead() external view returns (bytes32);: Returns the top block hash of the chain with the greatest cumulative work (the mainchain).function getMainchainHeight() external view returns (uint64);: Returns the height of the top block of the mainchain.function getBlockHeader(bytes32 blockHash) external view returns (BlockHeaderData memory);: Returns the block header data for a given block hash.function getBlockStatus(bytes32 blockHash) external view returns (bool, uint64);: Returns whether a given block belongs to the mainchain and its number of confirmations.function getBlockMerkleRoot(bytes32 blockHash) external view returns (bytes32);: Returns the Merkle root of a given block hash.function getBlockHeight(bytes32 blockHash) external view returns (uint64);: Returns the height within the chain of a given block hash.function getBlockHash(uint64 blockHeight) external view returns (bytes32);: Returns the mainchain block hash corresponding to a given height.function blockExists(bytes32 blockHash) external view returns (bool);: Returns whether a given block hash is stored in the contract.
In depth
Block header structure and big-endian conversion
A Bitcoin block header is a fixed 80 bytes consisting of, in order, Version (4 bytes, little-endian), Previous Block (32 bytes), Merkle Root (32 bytes), Time (4 bytes, little-endian), Bits (4 bytes, little-endian), and Nonce (4 bytes, little-endian). addBlockHeader receives and validates this raw 80-byte header, but for EVM efficiency, every field of the BlockHeaderData struct is converted to big-endian when stored in the contract's internal representation.
Difficulty adjustment and the target
Bitcoin is a PoW chain with probabilistic finality, so its difficulty target is adjusted dynamically. The initial target is 0x00000000ffff..., which is also the minimum difficulty. The target is recalculated every 2016 blocks (about two weeks, or 1,209,600 seconds) by multiplying the current target by the ratio of the actual time taken to mine the previous 2016 blocks to the expected time. To prevent sudden swings, the adjustment factor is capped at a maximum of 4x and a minimum of 1/4x. In the Bits field, the first byte encodes the shift amount and the remaining three bytes encode the actual target value.
Block header validation rules
For addBlockHeader to accept a block header, it must satisfy all three rules. Chain continuity: the Previous Block hash must point to an already-stored valid block. Timestamp: Time must be greater than the Median Time Past of the previous 11 blocks (the future 2-hour limit is omitted onchain). PoW constraint: the double SHA256 hash of the block header must be less than or equal to the current target. Only after passing all three conditions does the BlockHeaderAdded event fire and the block get added to the chain.
Verifying transaction inclusion via Merkle proofs
The transaction Merkle tree is built by taking the double SHA256 of the raw transaction bytes as leaves, then pairing sibling nodes with double SHA256 going up the tree (pairing a node with itself when it has no sibling). checkTxInclusion first confirms that blockHash belongs to the mainchain and has at least minConfirmationsCount confirmations, then recomputes the Merkle root from the merkleProof, txId, and txIndex and compares it against the stored Merkle Root field. It returns true if they match and false otherwise.
Defining the mainchain and cumulative work
The mainchain is defined as the chain with the greatest cumulative proof of work (cumulative PoW), not the greatest number of blocks. The work of a single block is calculated as (2**256 - 1) / (target + 1), with the target derived from the Bits field. addBlockHeader computes the cumulative work of the new header, compares it against the existing chains, reorganizes the mainchain if needed, and then emits the MainchainHeadUpdated event.
Initialization approach and trust assumptions
SPVGateway must provide a permissionless initialization mechanism, adopting an approach where anyone can bootstrap it by submitting a block header, height, and cumulative work at an arbitrary block height. Syncing the entire chain from the genesis block (estimated at roughly 100 ETH at 1 gwei gas) or proving historical correctness with a ZKP were also considered, but the current design trusts the submitted initial values, relying on off-chain means such as community checkpoint verification as a backstop.
Gas optimization in addBlockHeaderBatch
addBlockHeaderBatch is an OPTIONAL function that sequentially validates and appends multiple block headers to save gas. For batches larger than 11, the historical timestamps needed for the MTP calculation can be read from calldata instead of storage, substantially reducing storage reads and transaction cost.
Draft status
This proposal is currently in Draft status: the Deployment Method and Test Cases are still TBD and empty, and the contract address has not been finalized (0xTODO). Details may change or discussion may stall going forward.
Things to watch out for
- 51% attack risk: SPVGateway's security depends entirely on the security of Bitcoin's PoW consensus. A successful 51% attack on the Bitcoin network could let an attacker submit forged block headers that the contract would accept.
- Omission of the future timestamp check: The block header validation rules originally include a condition that Time must not be more than 2 hours ahead of network-adjusted time, but implementing this in a smart contract is impossible, so this check is omitted.
- Probabilistic finality and reorgs: Because Bitcoin has probabilistic rather than deterministic finality, the contract must be designed to handle chain reorganizations of arbitrary depth, though it cannot prevent them. Every dApp or protocol using this contract must determine for itself how many confirmations are sufficient to consider a transaction final.
- Trust in the initial state: addBlockHeader itself is permissionlessly and cryptographically verified, but the contract's initial state, namely the starting block header, height, and cumulative work, depends on trust. The correctness of these initial values must be verified by the community and by any dApp using a particular deployment.