- Flowee the Hub/
- Service API overview
- Service/Blockchain
- Service/Live Transactions
- Service/Mining
- Service/Util
- Service/RegTest
- Service/Hub Control
- Service/Indexer
- Service/AddressMonitor
- Service/TransactionMonitor
- Service/BlockNotification
- Service/Double Spend
- Service/System
- Protocol Spec
- Example Message
Flowee the Hub — API documentation
Service/Blockchain
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
Hub / API. sId=1 mId=0 |
---|
GetBlockChainInfoReply
Hub / API. sId=1 mId=1 | ||
---|---|---|
Difficulty: 64 | floating-point | Difficulty of chain |
MedianTime: 65 | natural-number | time in seconds |
ChainWork: 66 | sha256 | Total amount of work in chain |
Chain: 67 | string | Chain ID like "main" |
Blocks: 68 | natural-number | amount of blocks processed |
Headers: 69 | natural-number | Number of headers we validated |
BestBlockHash: 70 | sha256 | Chain-tips block-hash |
VerificationProgress: 71 | floating-point | Number between 0 and 1 |
GetBestBlockHash
Hub / API. sId=1 mId=2 |
---|
GetBestBlockHashReply
Hub / API. sId=1 mId=3 | ||
---|---|---|
GenericByteArray: 1 | bytearray | 32-byte hash |
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.
Hub / API. sId=1 mId=4 | ||
---|---|---|
BlockHash: 5 | bytearray | 32-byte blockhash. Alternative to BlockHeight |
BlockHeight: 7 | number | Height of the block in the chain. |
FilterOnScriptType: 39 | bitfield (number) | Script-types (see table below). |
ReuseScriptHashFilter: 40 | bool | Reuse an address filter (ScriptHash based) created on a previous GetBlock call. |
SetFilterScriptHash: 41 | bytearray | Clears and add a filter address |
AddFilterScriptHash: 42 | bytearray | Add a 20 byte bitcoin address. |
Select how transactions should be reported in the reply. | ||
Include_TxId: 43 | bool | Return a txid field for selected transactions. |
Include_OffsetInBlock: 44 | bool | Return offset in block field for selected transactions. |
FullTransactionData: 45 | bool | Return full transaction data. Default true, unless one of the "Include" fields is true. |
Include_Inputs: 46 | bool | Return all inputs for selected transactions |
Include_OutputAmounts: 47 | bool | Return amounts (in Satoshi) for selected transactions |
Include_OutputScripts: 48 | bool | Return out-scripts for selected transactions. |
Include_Outputs: 49 | bool | Return all outputs for selected transactions. |
Include_OutputAddresses:
50 | bool | Return output-addresses selected transactions, if they are p2pkh or p2pk. |
Include_OutputScriptHash: 51 | bool | Return output-script hashed. Supports all payment types. |
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.
ScriptTag | Flag-value |
---|---|
OpReturn | 1 |
OpChecksig / OpCheckSigVerify | 2 |
OpCheckmultisig / OpCheckmultisigVerify | 4 |
OpCheckLockTimeverify | 8, |
OpCheckDataSig / OpCheckDataSigVerify | 0x10 |
Is a P2SH based output | 0x20 |
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
theTx_IN_OutIndex
and theTx_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
andInclude_OutputScripts
.
GetBlockReply
Hub / API. sId=1 mId=5 | ||
---|---|---|
Full raw transaction: 1 | bytearray | A full transaction|
TxId: 4 | bytearray | 32-byte transaction hash |
BlockHash: 5 | bytearray | 32-byte blockhash. |
BlockHeight: 7 | natural-number | Height of the block in the chain. |
Tx_OffsetInBlock: 8 | natural-number | Key useful for GetTransaction |
Tx_IN_TxId 20 | bytearray | 32-byte hash (sha256) of the spending txid that this input spends. |
Tx_IN_OutIndex 21 | natural-number | index input in transaction identified Tx_IN_TxID that this input is spending. |
Tx_InputScript 22 | bytearray | Full input script. Typically pubkeys and signatures. |
Tx_Out_Index 24 | natural-number | the index of the output in the current transaction. |
Tx_Out_Amount 6 | positive-number | The amount of satoshis this output holds. |
Tx_OutputScript 23 | bytearray | Full outputscript |
BitcoinP2PKHAddress: 2 | bytearray | 20-byte address |
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.
Hub / API. sId=1 mId=6 | ||
---|---|---|
BlockHash: 5 | bytearray | 32-byte blockhash. Alternative to BlockHeight |
BlockHeight: 7 | number | Height of the block in the chain. |
Verbose: 60 | bool | If false, return the raw block data (default: true) |
GetBlockVerboseReply
Hub / API. sId=1 mId=7 | ||
---|---|---|
Time: 63 | natural-number | time in seconds |
Difficulty: 64 | floating-point | Difficulty of chain |
MedianTime: 65 | natural-number | time in seconds |
ChainWork: 66 | sha256 | Total amount of work in chain |
Nonce: 74 | natural-number | miner defined random number |
Target: 75 | bytearray | The target (spec) |
PrevBlockHash: 76 | sha256 | previous block hash (aka blockid) |
NextBlockHash: 77 | sha256 | next block hash (aka blockid) |
GetBlockHeader
Hub / API. sId=1 mId=8 | ||
---|---|---|
BlockHash: 5 | bytearray | 32-byte blockhash. |
BlockHeight: 7 | natural number | Block index in the chain. |
You can either ask for a blockHash or a blockheight, only the first seen in the message will be handled.
GetBlockHeaderReply
Hub / API. sId=1 mId=9 | ||
---|---|---|
BlockHash: 5 | bytearray | 32-byte blockhash. |
Confirmations: 72 | natural-number | Amount of blocks build on top |
BlockHeight: 7 | natural number | Block index in the chain. |
Version: 62 | natural-number | block-version |
MerkleRoot: 73 | bytearray | 32 byte sha256, merkleroot |
Time: 63 | natural-number | time in seconds |
Difficulty: 64 | floating-point | Difficulty of chain |
MedianTime: 65 | natural-number | time in seconds |
Nonce: 74 | natural-number | miner defined random number |
Target: 75 | bytearray | The target (spec) |
PrevBlockHash: 76 | sha256 | previous block hash (aka blockid) |
NextBlockHash: 77 | sha256 | next block hash (aka blockid) |
GetBlockCount
Hub / API. sId=1 mId=10 |
---|
GetBlockCountReply
Hub / API. sId=1 mId=11 | ||
---|---|---|
BlockHeight: 7 | natural number | number of validated blocks in chain. |
GetTransaction
Hub / API. sId=1 mId=12 | ||
---|---|---|
BlockHash: 5 | bytearray | 32-byte blockhash. Alternative to BlockHeight |
BlockHeight: 7 | number | Height of the block in the chain. |
Tx_OffsetInBlock: 8 | natural-number | Byte-offset in block |
Include_TxId: 43 | bool | Return a txid field for selected transactions. |
Include_OffsetInBlock: 44 | bool | Return offset in block field for selected transactions. |
FullTransactionData: 45 | bool | Return full transaction data. Default true, unless one of the "Include" fields is true. |
Include_Inputs: 46 | bool | Return all inputs for selected transactions |
Include_OutputAmounts: 47 | bool | Return amounts (in Satoshi) for selected transactions |
Include_OutputScripts: 48 | bool | Return out-scripts for selected transactions. |
Include_Outputs: 49 | bool | Return all outputs for selected transactions. |
Include_OutputAddresses: 50 | bool | Return output-addresses selected transactions, if they are p2pkh or p2pk. |
Include_OutputScriptHash: 51 | bool | Return output-script hashed. Supports all payment types. |
Include_TxFee: 53 | bool | Return the fee for each matched transaction. |
FilterOutputIndex: 52 | number | Only include 'output' items for this specific output-index. Can be passed multiple times. |
GetTransactionReply
Hub / API. sId=1 mId=13 | ||
---|---|---|
Full raw transaction: 1 | bytearray | A full transaction |
BitcoinP2PKHAddress: 2 | bytearray | 20-byte address |
TxId: 4 | bytearray | 32-byte transaction hash |
Amount: 6 | number | The number of Satoshis |
BlockHeight: 7 | natural-number | Height of the block in the chain. |
Tx_OffsetInBlock: 8 | natural-number | Offset in block |
Tx_IN_TxId 20 | bytearray | 32-byte hash (sha256) of the spending txid that this input spends. |
Tx_IN_OutIndex 21 | natural-number | index input in transaction identified Tx_IN_TxID that this input is spending. |
Tx_InputScript 22 | bytearray | Full input script. Typically pubkeys and signatures. |
Tx_OutputScript 23 | bytearray | Full outputscript |
Tx_Out_Index 24 | natural-number | the index of the output in the current transaction. |
TxFees: 25 | number | Number of satoshis that the inputs amounts are higher than the output amounts. |
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.