- The service provides several APIs through its contract, which we can use to verify or relay Bitcoin transactions. These APIs can be used in your DApp to achieve Bitcoin-related verification. Let's understand the important functions exposed by the BTCRelay contract through an example that uses them.
- Use the verifyTx function to verify a Bitcoin transaction. A transaction is considered as verified only if it has at least six confirmations. The function returns the hash of the verified bitcoin transaction. It returns 0 if the verification fails:
verifyTx(
rawTransaction, // Raw transaction bytes - bytes
transactionIndex, // Index of the transaction in Block - int256
merkleSibling, // Merkle proof sibiling hashes - int256[]
blockHash // hash of the transaction block - int256
) returns (uint256)
- To verify and relay the transaction to a specific contract, use the relayTx function provided by BTCRelay. The function is very similar to verifyTx but accepts one more parameter as contractAddress. The target address should have a function called processTransaction. The relayTx function returns either the result of processTransaction or an error code:
relayTx(
rawTransaction, // Raw transaction bytes - bytes
transactionIndex, // Index of the transaction in Block - int256
merkleSibling, // Merkle proof sibiling hashes - int256[]
blockHash, // hash of the transaction block - int256
contractAddress // Address of the target contract
) returns (int256)
// Target contract function
// Will be invoked by relayTx
processTransaction(
bytes rawTransaction,
uint256 transactionHash
) returns (int256)
- Use the following functions provided by the service to set and get the block header of a block hash:
// Get header
getBlockHeader(
blockHash // Hash of the block
) returns (bytes)
// Set header
storeBlockHeader(
blockHeader // raw block header - bytes
) returns (int256)
// Set multiple headers at once
bulkStoreHeader(
bytesOfHeaders, // raw block headers one after another - bytes
numberOfHeaders // number of headers
) returns (int256)
- getBlockHeader returns the header as bytes if it is found. It returns a 0 result with a length of 80 bytes if the header does not exist. The result is 0 if the payment is insufficient. The payment can be calculated by calling the getFeeAmount function:
getFeeAmount(blockHash) returns (int256)
- There are other functions that are used to read and write more data about bitcoin transactions:
// Returns the hash of given block height
getBlockHash(blockHeight) returns (int256)
// Returns the difference between the chainwork
// of latest and 10th prior block
getAverageChainWork()
// Returns the hash of latest block
getBlockchainHead() returns (int256)
// Returns the block height of latest block
getLastBlockHeight() returns (int256)
- BTCRelay also includes functions to help relayers with incentives. Relayers are those who update the contract with recent blockchain transactions:
// Store single block header and store its fee
storeBlockWithFee(blockHeader, fee) returns (int256)
// Sets fee and the recipient for the given block hash
changeFeeRecipient(blockHash, fee, recipient) returns (int256)
// Get the fee recipient for the given block hash
getFeeRecipient(blockHash) returns (int256)
// Get the amount of fee for changeFeeRecipient
getChangeRecipientFee() returns (int256)
- The service can be used in your application by specifying its deployed address and ABI. Consider the following example as a template for calling the functions:
var btcRelayAddr = "0x...";
var btcRelayAbi = [...<BTCRelay_ABI>...];
var btcRelay = web3.eth.contract(btcRelayAbi).at(btcRelayAddr);
btcRelay.verifyTx.call(
transactionBytes,
transactionIndex,
merkleSibling,
transactionBlockHash,
{ from: '0x..', ...}
);
- Refer to the official GitHub repo (https://github.com/ethereum/btcrelay) for more information related to Ethereum contract and internals.