Blockchain Service

The hub provides access to the blockchain, which is easiest to see as a big database. The blockchain is a list of blocks and each block has a list of transactions. Because this database is too big for iteration you need to understand the way that Flowee the Hub wants you to access the data if you want to get the best speed.

Blocks are sequential, which means that you can request any block by its height, a natural number increasing continuously. If you request data that is very recent we suggest to use the blockhash instead to avoid reorgs causing hard to trace bugs.

Inside of blocks we list transactions serially as well, but beware that we don’t use an index on blocks. Instead services use “offset-in-block” as an ID. This is the amount of bytes into the block that the transaction is stored. Notice that the first transaction (the coinbase) is always at position 81.

Inside of the transaction we don’t have any sort of indexing, but pre-processing the transaction on the Hub will in many cases still be faster than sending the entire thing to clients. As such we allow a large range of options to fetch specific pieces of the transaction. See the GetBlock and GetTransaction messages for details.

This service has Service-Id: 1

Datatypes are raw

Transaction-ids, block-ids and addresses are always sent and expected as raw byte-arrays.

Hashes are often printed in hex form, which is easy to recognize because they become twice as long. In the API we want the fully decoded values. A sha256 block-hash is 32 bytes.

Addresses are often encoded using methods like cash-address or base58, this should be done as close as possible to the user and only fully decoded versions are accepted on the API. Addresses are 20 byte hashes.

Messages

GetBlockChainInfo

GetBlockChainInfoReply

GetBestBlockHash

GetBestBlockHashReply

GetBlock

This one method (and its sister method GetTransaction) hide a lot of power because there are a large number of settings to request exactly how to return a block. You can filter which transactions to be included based on several options.

Additionally the selected transactions can be sent in full but you can also elect to let the Hub parse the transaction and send an annotated list of items. For instance only the inputs, or only the amount sent for each output.

Below the message table we go into detail for these methods.

Address Filters

This concept allows filtering of transactions based on a match of an output-script to a specific script-hash. Script hashes are useful in this context because they are generic for all payment methods and address types.

AddFilterScriptHash

Adds a single script hash to the filter

SetFilterScriptHash

Same as AddFilterScriptHash, but clears the filters first

ReuseScriptHashFilter

allows a getblock to reuse the filter from a previous call to getblock. As long as it was using the same connection.

Filter on Script-Type

This concept allows filtering of transactions based on a match between demanded script-types and the script-types used in the transaction.

What is a scrypt-type? This is similar to a template, but specifically we highlight a number of typical script opcodes that can be used to select a transaction on. Should one of the below opcodes be used in any of the outputs, then the filter will match.

Multiple script-tags can be filtered on, just add the different values together and pass the result to the FilterOnScriptType message value.

Notice that Address-filters and Script-type filters work addative. The result will include transactions that match either Address filters OR script-type filters.

Report parsed results

This concept allows the selected transactions to be parsed by the Hub and the result will be tagged for easy consumption. For those that worry about bandwidth usage, this is an excellent way to limit the amount of data sent and processed client-side.

For all the include_* fields the rule is that if they are not included in the request, they are set to false.

The FullTransactionData default value is a bit more complex, it is true (send full transaction data) by default, unless the request enables one or more Include_* fields. If this is confusing, just include the FullTransactionData and set it explicity to true or false. Its just one byte in the request.

Include_Inputs

This enables the reply to have the Tx_IN_TxId the Tx_IN_OutIndex and the Tx_InputScript. fields.

Include_OutputAmounts

Returns the Tx_Out_Amount.

Include_OutputScripts

Returns the Tx_OutputScript.

Include_OutputAddresses

Returns the BitcoinP2PKHAddress, but only if it is a Public-Key-Hash!

Include_OutputScriptHash

Returns the script-hash of the output. This one works for all address-types.

Include_Outputs

This is a shortcut to enable both Include_OutputAmounts and Include_OutputScripts.

GetBlockReply

Due to filters the answer may not include all transactions in a block and for transactions included outputs may also be filtered. Outputs that are included will thus always be prefixed with a Tx_Out_Index field indicating which index the next data is about.

GetBlockVerbose

This is a mapping to the legacy JSON RPC API to return a header of the block plus a list of transaction-ids.

GetBlockVerboseReply

GetBlockHeader

You can either ask for a blockHash or a blockheight, only the first seen in the message will be handled.

GetBlockHeaderReply

GetBlockCount

GetBlockCountReply

GetTransaction

GetTransactionReply

Due to Include_* filters the answer may not include all outputs in a transaction. Outputs that are included will thus always be prefixed with a Tx_Out_Index field indicating which index the next data is about.