- 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
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.
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
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
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.