Skip to content
BTCRelay re-implementation in Solidity
Python JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

BTCRelay implementation in Solidity

Disclaimer: this project is still under development and not safe to use!


npm install openzeppelin-solidity truffle-assertions buffer-reverse truffle-hdwallet-provider big-number

Chain Relays

Chain relays are on-chain programs or smart contracts deployed on a blockchain A capable of reading and verifying the state of another blockchain B. The underlying technical design and functionality is comparable to that of SPV-Clients. That is, a chain relay stores and maintains block headers of chain B on chain A and allows to verify transaction inclusion proofs. Summarizing, the two main functionalities a chain relay must/should provide are: consensus verification and transaction inclusion verification.

Read more about chain relays in the XCLAIM paper (Section V.B descibes the basic concept of chain relays, while Appendix B provides a formal model of the required functionality for PoW chain relays.).


BTCRelay-Sol is an implementation of a chain relay for Bitcoin on Ethereum. The first implementation of BTCRelay was implemented in Serpent and can be found here. However, as Serpent is outdated (last commit: December 2017), this project aims to implement an updated version in Solidity.


The current implementation is based on the existing Serpent implementation, specifically with regards for fork handling. As such, BTCRelay must store all block headers to establish, whether a transaction is included in the Bitcoin main chain. However, improved proofing techniques, such as NiPoPoWs and FlyClient, allow to reduce the storage requirements. Furthermore, protocols based on off-chain verification games such as Truebit may allow optimistic improvements to performance and cost.

To this end, BTCRelay will be split into multiple components, allowing integration with the above mentioned verification techniques:

  • Block header storage ... sole functionality of this component is the efficient storage of block headers submitted to the telay
  • Block header verification ... performs verification of block headers before they are persisted, e.g. checks if the correct difficulty was set, verifies the hash pre-image, makes sure the pervious block header exists (or determines that a specific verification techniques is being used - see below), etc.
  • Main chain detection ... the verification of the Bitcoin main chain (i.e., if a block is in the main chain or part of a fork) can be handled by (i) traversing all block headers as in the case of classic SPV verification, (ii) NiPoPoWs and FlyClient, (iii) off-chain verification games such as Truebit.
  • Transaction inclusion verification and parsing ... calls one of the available methods of the main chain detection component and provides tools for parsing transaction inputs/outputs and performing validity checks.

We note that the block header data used for testing was first provided in the BTCRelay Serpent implementation (repo).

Other resources

We make note of the following libraries/implementations, which specifically may aid with Bitcoin transaction parsing:


Make sure ganache-cli and truffle are installed as global packages. Then, install the required packages with:

npm install


Start ganache:

Note - due to contract size, we need to pass additional options to Ganache!

ganache-cli --gasLimit 800000000 --allowUnlimitedContractSize

Migrate contracts:

truffle migrate

Run tests:

truffle test

This will also re-run migration scripts.

You can’t perform that action at this time.