contracts and README

Author: ethers

README.md

@@ -0,0 +1,158 @@
+# [BTC Relay](http://btcrelay.org)
+
+[![Join the chat at https://gitter.im/ethereum/btcrelay](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ethereum/btcrelay)
+
+[BTC Relay](http://btcrelay.org) is an Ethereum contract for Bitcoin SPV.  The main functionality it provides are:
+
+1. verification of a Bitcoin transaction
+1. optionally relay the Bitcoin transaction to any Ethereum contract
+1. storage of Bitcoin block headers
+1. inspection of the latest Bitcoin block header that is stored
+
+BTC Relay is [live](http://rawgit.com/ethereum/btcrelay/master/examples/relayContractStatus.html) on the testnet.
+
+
+## API
+
+
+##### verifyTx(transactionHash, 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.
+
+* `transactionHash` - hash of the transaction, as `int256`
+* `transactionIndex` - transaction's index within the block, as `int256`
+* `merkleSibling` - array of the hashes of sibling transactions comprising the Merkle proof, as `int256[]`
+* `blockHash` - hash of the block that contains the transaction, as `int256`
+
+Returns `int256`
+* `1` if transaction is verified to be on the Bitcoin blockchain
+* `0` otherwise
+
+*Note:* See [examples/sampleCall.html](examples/sampleCall.html) including use of [bitcoin-proof](https://www.npmjs.com/package/bitcoin-proof) for constructing `merkleSibling`.
+
+---
+
+##### relayTx(rawTransaction, transactionHash, transactionIndex, merkleSibling, blockHash, contractAddress)
+
+Verifies a Bitcoin transaction per `verifyTx()` and relays the verified transaction to the specified Ethereum contract.
+
+* `rawTransaction` - hex string of the raw transaction, as `bytes`
+* `transactionHash` - hash of the transaction, as `int256`
+* `transactionIndex` - transaction's index within the block, as `int256`
+* `merkleSibling` - array of the hashes of sibling transactions comprising the Merkle proof, as `int256[]`
+* `blockHash` - hash of the block that contains the transaction, as `int256`
+* `contractAddress` - address of the Ethereum contract that will receive the verified Bitcoin transaction, as `int256`
+
+The Ethereum contract should have a function of signature `processTransaction(rawTransaction, transactionHash)` and is what will be invoked by `relayTx` if the transaction passes verification.  For an example, see [example-btc-eth](example-btc-eth)
+
+Returns `int256`
+* value returned by the Ethereum contract's `processTransaction` function
+* `0` otherwise
+
+----
+
+##### storeBlockHeader(blockHeader)
+
+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`
+* block height of the header if it was successfully stored
+* `0` otherwise
+
+----
+
+##### bulkStoreHeader(bytesOfHeaders, numberOfHeaders)
+
+Store 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`
+* block height of the last header if all block headers were successfully stored
+* `0` if any of the block headers were not successfully stored
+
+*Note:* See [deploy/relayTest/testBulkDeploy.yaml](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.
+
+----
+
+##### getBlockHeader(blockHash)
+
+Get the 80 byte block header for a given `blockHash`.
+
+* `blockHash` - hash of the block as `int256`
+
+Returns `bytes`
+* block header, always as 80 bytes (all zeros if header does not exist)
+
+----
+
+##### getBlockHash(blockHeight)
+
+Get the block hash for a given `blockHeight`.
+
+* `blockHeight` - height of the block as `int256`.  Minimum value is `1`.
+
+Returns `int256`
+* block hash
+* `0` if not found
+
+----
+
+##### getAverageBlockDifficulty()
+
+Returns the difference between the cumulative difficulty of the latest block and the 10th block prior.
+
+This is provided in case an Ethereum contract wants to use the Bitcoin network difficulty as a data feed for some purpose.
+
+----
+
+##### getBlockchainHead(), getLastBlockHeight(), others
+
+`getBlockchainHead` - returns the hash of the latest block, as`int256`
+
+`getLastBlockHeight` - returns the block height of the latest block, as `int256`
+
+See [BitcoinRelayAbi.js](examples/BitcoinRelayABI.js) for other APIs and [relayContractStatus.html](examples/relayContractStatus.html) for an example of calling some of them.
+
+----
+
+## Examples
+
+* [sampleCall.html](examples/sampleCall.html) for calling `verifyTx` including use of [bitcoin-proof](https://www.npmjs.com/package/bitcoin-proof) for constructing `merkleSibling`.
+
+* [example-btc-eth](example-btc-eth) for relaying a Bitcoin transaction to an Ethereum contract using `relayTx`.
+
+* [relayContractStatus.html](examples/relayContractStatus.html) for calling other basic functions.
+
+
+## Development
+
+Requirements
+* [Serpent](https://github.com/ethereum/serpent)
+* [pyethereum](https://github.com/ethereum/pyethereum) (for tests)
+* [pyepm](https://github.com/etherex/pyepm) (for deployment)
+
+#### Running tests
+
+Exclude slow tests:
+```
+py.test test/ -s -m "not slow"
+```
+
+Run slow tests without veryslow tests
+```
+py.test test/ -s -m "slow and not veryslow"
+```
+
+All tests:
+```
+py.test test/ -s
+```
+
+
+## License
+
+[MIT](LICENSE)

btcBulkStoreHeaders.se

@@ -0,0 +1,21 @@
+inset('btcrelay.se')
+
+# store 'count' number of Bitcoin blockheaders represented as one
+# continuous 'headersBytes' (which should have length 80*count
+# since a single Bitcoin block header is 80 bytes)
+def bulkStoreHeader(headersBytes:str, count):
+    HEADER_SIZE = 80
+
+    offset = 0
+    endIndex = HEADER_SIZE
+
+    i = 0
+    while i < count:
+        currHeader = slice(headersBytes, chars=offset, chars=endIndex)
+        res = self.storeBlockHeader(currHeader)
+
+        offset += HEADER_SIZE
+        endIndex += HEADER_SIZE
+        i += 1
+
+    return(res)

btcChain.se

@@ -0,0 +1,152 @@
+inset('constants.se')
+
+# btcChain is required by btcrelay and is a separate file to improve
+# clarity: it has ancestor management and its
+# main method is inMainChain() which is tested by test_btcChain
+
+macro NUM_ANCESTOR_DEPTHS: 8
+
+# list for internal usage only that allows a 32 byte blockHash to be looked up
+# with a 32bit int
+# This is not designed to be used for anything else, eg it contains all block
+# hashes and nothing can be assumed about which blocks are on the main chain
+data internalBlock[2^50]
+
+# counter for next available slot in internalBlock
+# 0 means no blocks stored yet and is used for the special of storing 1st block
+# which cannot compute Bitcoin difficulty since it doesn't have the 2016th parent
+data ibIndex
+
+
+# save the ancestors for a block, as well as updating the height
+# ntoe: this is internal/private so make it into a macro
+macro m_saveAncestors($blockHashArg, $hashPrevBlockArg):
+    with $blockHash = $blockHashArg:
+        with $hashPrevBlock = $blockHashArg:
+            self.internalBlock[self.ibIndex] = blockHash
+            m_setIbIndex(blockHash, self.ibIndex)
+            self.ibIndex += 1
+
+            m_setHeight(blockHash, m_getHeight(hashPrevBlock) + 1)
+
+            # 8 indexes into internalBlock can be stored inside one ancestor (32 byte) word
+            ancWord = 0
+
+            # the first ancestor is the index to hashPrevBlock, and write it to ancWord
+            prevIbIndex = m_getIbIndex(hashPrevBlock)
+            m_mwrite32(ref(ancWord), prevIbIndex)
+
+            # update ancWord with the remaining indexes
+            i = 1
+            while i < NUM_ANCESTOR_DEPTHS:
+                depth = m_getAncDepth(i)
+
+                if m_getHeight(blockHash) % depth == 1:
+                    m_mwrite32(ref(ancWord) + 4*i, prevIbIndex)
+                else:
+                    m_mwrite32(ref(ancWord) + 4*i, m_getAncestor(hashPrevBlock, i))
+                i += 1
+
+            # write the ancestor word to storage
+            self.block[blockHash]._ancestor = ancWord
+
+
+# returns 1 if 'txBlockHash' is in the main chain, ie not a fork
+# otherwise returns 0
+def inMainChain(txBlockHash):
+    txBlockHeight = m_getHeight(txBlockHash)
+
+    # By assuming that a block with height 0 does not exist, we can do
+    # this optimization and immediate say that txBlockHash is not in the main chain.
+    # However, the consequence is that
+    # the genesis block must be at height 1 instead of 0 [see setInitialParent()]
+    if !txBlockHeight:
+        return(0)
+
+    return(self.fastGetBlockHash(txBlockHeight) == txBlockHash)
+
+
+# returns the blockHash at the given blockHeight
+# blockHeight must be greater than 0 (otherwise infinite loop since minimum height is 1)
+def getBlockHash(blockHeight):
+    if blockHeight < 1 || blockHeight > m_getHeight(self.heaviestBlock):
+        return(0)
+    return(self.fastGetBlockHash(blockHeight))
+
+
+# for internal use only since callers must ensure 2 things:
+# * blockHeight is greater than 0 (otherwise infinite loop since
+# minimum height is 1)
+# * blockHeight is less than the height of heaviestBlock, otherwise the
+# heaviestBlock is returned
+def fastGetBlockHash(blockHeight):
+    blockHash = self.heaviestBlock
+    anc_index = NUM_ANCESTOR_DEPTHS - 1
+
+    while m_getHeight(blockHash) > blockHeight:
+        while m_getHeight(blockHash) - blockHeight < m_getAncDepth(anc_index) && anc_index > 0:
+            anc_index -= 1
+        blockHash = self.internalBlock[m_getAncestor(blockHash, anc_index)]
+
+    return(blockHash)
+
+
+#
+# macros
+#
+
+
+# a block's _ancestor storage slot contains 8 indexes into internalBlock, so
+# this macro returns the index that can be used to lookup the desired ancestor
+# eg. for combined usage, self.internalBlock[m_getAncestor(someBlock, 2)] will
+# return the block hash of someBlock's 3rd ancestor
+macro m_getAncestor($blockHash, $whichAncestor):
+    div(sload(ref(self.block[$blockHash]._ancestor)) * 2**(32*$whichAncestor), BYTES_28)
+
+
+# index should be 0 to 7, so this returns 1, 5, 25 ... 78125
+macro m_getAncDepth($index):
+    5**$index
+
+
+# write $int32 to memory at $addrLoc
+# This is useful for writing 32bit ints inside one 32 byte word
+macro m_mwrite32($addrLoc, $int32):
+    with $addr = $addrLoc:
+        with $fourBytes = $int32:
+            mstore8($addr, byte(28, $fourBytes))
+            mstore8($addr + 1, byte(29, $fourBytes))
+            mstore8($addr + 2, byte(30, $fourBytes))
+            mstore8($addr + 3, byte(31, $fourBytes))
+
+
+# write $int24 to memory at $addrLoc
+# This is useful for writing 24bit ints inside one 32 byte word
+macro m_mwrite24($addrLoc, $int24):
+    with $addr = $addrLoc:
+        with $threeBytes = $int24:
+            mstore8($addr, byte(29, $threeBytes))
+            mstore8($addr + 1, byte(30, $threeBytes))
+            mstore8($addr + 2, byte(31, $threeBytes))
+
+
+# write $int16 to memory at $addrLoc
+# This is useful for writing 16bit ints inside one 32 byte word
+macro m_mwrite16($addrLoc, $int16):
+    with $addr = $addrLoc:
+        with $twoBytes = $int16:
+            mstore8($addr, byte(30, $twoBytes))
+            mstore8($addr + 1, byte(31, $twoBytes))
+
+
+# log ancestors
+# def logAnc(blockHash):
+#     log(11111)
+#     log(blockHash)
+#     i = 0
+#     while i < NUM_ANCESTOR_DEPTHS:
+#         anc = m_getAncestor(blockHash, i)
+#         # anc = self.block[blockHash]._ancestor[i]
+#         log(anc)
+#         i += 1
+#     log(22222)