Awesome

BTCRelay-Solidity Tools

Tools for interacting with the BTC Relay in Solidity

This contract provides an interface with BTC Relay which accepts and returns intuitive Solidity types, and provides additional functionality like fetching block headers by block height and caching results in a manner that is fair to the original relayers.

Contract Address:

ABI:

API

Transaction Verification

Functions for validating transactions. Insert example here

verifyTx(rawTransaction, transactionIndex, merkleSibling, blockHash)

Verifies the presence of a transaction on the Bitcoin blockchain, primarily that the transaction is on Bitcoin's main chain and has at least 6 confirmations.

Arguments:

rawTransaction: bytes - raw bytes of the transaction
transactionIndex: uint256 - transaction's index within the block
merkleSibling: bytes32[] - array of the sibling hashes comprising the Merkle proof
blockHash: bytes32 - hash of the block that contains the transaction

Returns: uint256

hash of the verified Bitcoin transaction
0 if rawTransaction is exactly 64 bytes in length or fails verification

relayTx(rawTransaction, transactionIndex, merkleSibling, blockHash, contractAddress)

Verifies a Bitcoin transaction per verifyTx() and relays the verified transaction to the specified Ethereum contract.

Arguments:

rawTransaction: bytes - raw bytes of the transaction
transactionIndex: uint256 - transaction's index within the block
merkleSibling: bytes32[] - array of the sibling hashes comprising the Merkle proof
blockHash: bytes32 - hash of the block that contains the transaction
contractAddress: address - address of the processor contract that will receive the verified Bitcoin transaction

The processor contract at contractAddress should have a function of signature processTransaction(bytes rawTransaction, uint256 transactionHash) returns (int256) and is what will be invoked by relayTx if the transaction passes verification. For examples, see BitcoinProcessor.sol and testnetSampleRelayTx.html.

Returns: int256

value returned by the processor contract's processTransaction function or -1 on failure

Note: Callers cannot be 100% certain when an relay error occurs because -1 may also have been returned by processTransaction(). Callers should be aware of the contract that they are relaying transactions to, and understand what the processor contract's processTransaction method returns.

Block Lookup

Functions for finding particular blocks

getBlockHash(blockHeight)

Get the block hash for a given blockHeight.

Arguments:

blockHeight: uint256 - height of the block. Minimum value is 1.

Returns: (bytes32, uint256)

(block hash, total fee paid)
(0, total fee paid) if not found or insufficient fee

NOTE: Due to the mechanics of BTC Relay, in order to fetch a block hash we must iterate over all of the successive blocks in the chain, paying the required fee for each. This is only true the first time a given block header is fetched, so before calling this function make sure to call getFeeAmount() and check if you are willing to pay the current price.

getBlockHeight(blockHash)

Get the block height of a block by its hash

Arguments:

blockHash: bytes32 - block hash of a Bitcoin block

Returns: uint

Height of the block
0 if not found

Block Header Fields

You must pay a small fee for these, i.e.

uint fee = relay.getFeeAmount(blockHash);
bytes32 merkleRoot = relay.getMerkleRoot.value(fee)(blockHash);

getBlockVersion(blockHash)

Get the Bitcoin block version bytes

Arguments:

blockHash: bytes32 - BTC block hash

Returns: bytes4

4-byte BTC block version indicator
0 if not found

getParentHash(blockHash)

Get the hash of the block immediately previous

Arguments:

blockHash: bytes32 - BTC block hash

Returns: bytes32

Blockhash of the parent block
0 if not found

getMerkleRoot(blockHash)

Get the Merkle root for the block

Arguments:

blockHash: bytes32 - BTC block hash

Returns: bytes32

Merkle root of the block
0 if not found

getTimestamp(blockHash)

Get the timestamp of the block, as a bytes4

Arguments:

blockHash: bytes32 - BTC block hash

Returns: bytes4

Timestamp of the block
0 if not found

getBits(blockHash)

Get the abbreviated difficulty

Actual difficulty is calculated as bits * 2**(8*(0x1b - 3))

Arguments:

blockHash: bytes32 - BTC block hash

Returns: bytes4

Bits field of the block
0 if not found

getNonce(blockHash)

Get the nonce of the block

Arguments:

blockHash: bytes32 - BTC block hash

Returns: bytes4

Nonce field of the block
0 if not found

Chain Info

These functions are free and provide general information about the state of the blockchain

getLastBlockHeight()

Returns: uint256

Block height of most recently relayed block

getBlockchainHead()

Returns: bytes32

Block hash of the latest block

getAverageChainWork()

Returns: uint

The difference between the chainWork of the latest block and the 10th block prior.

This is provided in case an Ethereum contract wants to use the chainWork or Bitcoin network difficulty (which can be derived) as a data feed.

Fee Estimators

These estimates are guaranteed to be enough for execution, although your contract may receive a refund to a function called _relay_refund(), or your fallback function if that does not exist.

getFeeAmount(blockHash|blockHeight)

uint is interpreted as a block height, bytes32 is interpreted as a block hash. For less ambiguity, you may use the more verbose functions

Arguments:

blockhash: bytes32 - BTC block hash of the block whose fee you need or
blockHeight: uint256 - Height of block

Returns: uint

Fee to be paid for accessing block header

getFeeAmountByBlockHash(blockHeight)

blockhash: bytes32 - BTC block hash of the block whose fee you need

Returns: uint

Fee to be paid for accessing block header

getMaxFeeAmountByBlockHeight(blockHeight)

blockHeight: uint256 - Height of block

Returns: uint

Fee to be paid for accessing block header