Welcome to BTC Relay’s documentation!

API docs are on Github for now.

Contents

Frequently Asked Questions

What’s the simplest explanation of BTC Relay?

It allows users to pay with Bitcoin to use Ethereum.

How to use BTC Relay?

If you’re a user, you should not need to use BTC Relay directly since it works behind the scenes.

If you’re a developer, did you see How to use BTC Relay?

Who is BTC Relay for?

Developers who want a secure, fully decentralized and trustless method of verifying Bitcoin transactions for their Ethereum and smart contract applications.

BTC Relay is a building block for developers that want interoperability between Ethereum and Bitcoin. For example, developers who want to allow their users to pay with Bitcoin to use their Ethereum application.

How to be a Relayer and receive incentives?

Relayers are those who submit block headers to BTC Relay. To incentivize the community to be relayers, and thus allow BTC Relay to be autonomous and up-to-date with the Bitcoin blockchain, Relayers can submit block headers to BTC Relay. When any transaction is verified in the block, or the header is retrieved, Relayers will be rewarded a fee (see details at https://github.com/ethereum/btcrelay/tree/master#incentives-for-relayers).

Warning: as specified above, incentives are only sent when transactions are verified in the block or the header is retrieved, not when the block is submitted.

Why isn’t verifyTx / relayTx working?

  • Does your transaction have at least 6 Bitcoin confirmations?
  • Did you pass the correct parameters to construct the Merkle proof correctly? Viewing the page source of some examples might help.
  • Did you send at least the fee as indicated by getFeeAmount()?

What prevents fees from being too high?

If a fee for any block header is too high, anyone may changeFeeRecipient() to themselves.

They can compare the current fee against getChangeRecipientFee() to see if the fee is excessive. Callers of changeFeeRecipient() must make sure to satisfy all requirements for successful completion.

How does BTC Relay work?

BTC Relay is an Ethereum contract that stores Bitcoin block headers. BTC Relay uses these headers to build a mini-version of the Bitcoin blockchain: a method used by Bitcoin SPV light wallets.

Relayers who submit headers can earn Ether. When an application processes a Bitcoin payment, it uses a header to verify that the payment is legitimate. The relayer of the particular header earns a fee, usually specified when the relayer submitted the header.

The cycle of relayers submitting headers, then applications processing Bitcoin payments and rewarding a relayer with a micro-fee, can allow the system to be autonomous and self-sustaining.

http://btcrelay.org/images/howitworks.png

BTC Relay Status

What is shown on the Status page?

In addition to the address and ABI, the Status shows the latest Bitcoin block number and blockhash that BTC Relay knows about. It also shows the very first Bitcoin block header that is stored by BTC Relay. BTC Relay can only verify (and relay) transactions that occur between these blocks. The Status also shows the fee for making use of the block header.

What is the ETH fee?

The amount that needs to be paid to the Relayer when a Bitcoin transaction belongs in the block.

What is the Relayer?

The address that will receive the fee. It is usually the address of the origin account that was first to successfully submit the block header to BTC Relay.

What is the fee for previous blocks?

Use getFeeAmount().

What can I do if the fee is too high?

An option is to changeFeeRecipient() to yourself. Make sure you satisfy all requirements for successful completion.

Why is the latest block behind?

The missing Bitcoin block header has not been mined into an Ethereum block yet. Or if BTC Relay does not have enough Relayers, it could fall behind many blocks. You may want to consider being a Relayer.