Name: btcrelay
Owner: ConsenSys
Description: Ethereum contract for Bitcoin SPV
Forked from: ethereum/btcrelay
Created: 2016-02-22 01:24:08.0
Updated: 2017-08-20 14:36:38.0
Pushed: 2016-05-31 20:00:11.0
Size: 60824
Language: Python
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
BTC Relay is an Ethereum contract for Bitcoin SPV. The main functionality it provides are:
The address and ABI is all that's needed to use BTC Relay, in addition to the API documentation below.
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.
rawTransaction - raw bytes of the transactiontransactionIndex - transaction's index within the block, as int256merkleSibling - array of the sibling hashes comprising the Merkle proof, as int256[]blockHash - hash of the block that contains the transaction, as int256Returns uint256
0 if rawTransaction is exactly 64 bytes in length or fails verificationNote: See examples/sampleCall.html including use of bitcoin-proof for constructing merkleSibling.
Verifies a Bitcoin transaction per verifyTx() and relays the verified transaction to the specified Ethereum contract.
rawTransaction - raw bytes of the transactiontransactionIndex - transaction's index within the block, as int256merkleSibling - array of the sibling hashes comprising the Merkle proof, as int256[]blockHash - hash of the block that contains the transaction, as int256contractAddress - address of the processor contract that will receive the verified Bitcoin transaction, as int256The 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
processTransaction functionNote: Callers cannot be 100% certain when an ERR_RELAY_VERIFY occurs because it 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.
Store a single block header if it is valid, such as a valid Proof-of-Work and the previous block it reference exists.
blockHeader - raw bytes of the block header (not the hex string, but the actual bytes).Returns int256
0 otherwiseStore multiple block headers if they are valid.
bytesOfHeaders - raw bytes of the block headers (not the hex string, but the actual bytes), with one following immediately the other.numberOfHeaders - int256 count of the number of headers being stored.Returns int256
0 if any of the block headers were not successfully storedNote: See deploy/relayTest/testBulkDeploy.yaml for an example of the data for storing multiple headers. Also, to avoid exceeding Ethereum's block gas limit, a guideline is to store only 5 headers at time.
Get the 80 byte block header for a given blockHash. A payment value of
getFeeAmount(blockHash) must be provided in the transaction.
blockHash - hash of the block as int256Returns bytes
0 (as a single byte) if insufficient payment is providedGet the block hash for a given blockHeight.
blockHeight - height of the block as int256. Minimum value is 1.Returns int256
0 if not foundReturns 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.
getBlockchainHead - returns the hash of the latest block, asint256
getLastBlockHeight - returns the block height of the latest block, as int256
See BitcoinRelayAbi.js for other APIs and testnetContractStatus.html for an example of calling some of them.
The following APIs are described in Incentives for Relayers below.
storeBlockWithFee(), changeFeeRecipient(), getFeeRecipient(), getFeeAmount(), getChangeRecipientFee()
Examples for how to use BTC Relay include:
testnetSampleCall.html for calling verifyTx including use of bitcoin-proof for constructing merkleSibling.
mainnet sampleCall.html for calling verifyTx
(very similar to above.)
testnetSampleRelayTx.html shows relayTx relaying a Bitcoin transaction from the frontend to an Ethereum contract.
testnetContractStatus.html for calling other basic functions.
The easiest way to use BTC Relay is via relayTx because the ABI can remain on the frontend.
testnetSampleRelayTx.html shows how a Bitcoin transaction from the frontend can be passed (relayed) to an Ethereum contract.
See other examples for other ways to use BTC Relay and the docs for FAQ.
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 call storeBlockWithFee. The Relayer will be the
getFeeRecipient() for the block they submit, and when any transactions are verified
in the block, or the header is retrieved via getBlockHeader, the Relayer will be
rewarded with getFeeAmount().
To avoid a relayer R1 from setting excessive fees, it is possible for a relayer R2
to changeFeeRecipient(). R2 must specify a fee lower than what R1 specified, and
pay getChangeRecipientFee() to R1, but now R2 will be the getFeeRecipient() for the block
and will earn all future getFeeAmount().
With this background, here are API details for incentives.
Store a single block header (like storeBlockHeader) and
set a fee that will be charged for verifications that use blockHeader.
blockHeader - raw bytes of the block header (not the hex string, but the actual bytes).fee - int256 amount in wei.Returns int256
0 otherwiseSet the fee and recipient for a given blockHash. The call must have msg.value
of at least getChangeRecipientFee(), and must also specify a fee lower than
the current getFeeAmount(blockHash).
blockHash - hash of the block as int256.fee - int256 amount in wei.recipient - int256 address of the recipient of fees.Returns int256
1 if the fee and recipient were successfully set0 otherwiseGet the address that receives the fees for a given blockHash.
blockHash - hash of the block as int256.Returns int256
Get the fee amount in wei for verifications using a given blockHash.
blockHash - hash of the block as int256.Returns int256
Get the amount of wei required that must be sent to BTC Relay when calling
changeFeeRecipient.
Returns int256
Requirements
Exclude slow tests:
est test/ -s -m "not slow"
Run slow tests without veryslow tests
est test/ -s -m "slow and not veryslow"
All tests:
est test/ -s
See full MIT License including:
SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
ESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
ORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
ILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
SOFTWARE.