Client Server Interface

Libbitcoin messages conform to a uniform message structure implemented using ZeroMQ. The payload of each message is byte-aligned as described below. Unless otherwise specified a full payload may be returned in the response even if the result is nonzero (error). In the case of an error the remainder of the response should be ignored. All integer and hash values are encoded in little-endian byte order. Bitcoin objects are returned in canonical serialization.

Version 1/2/3

blockchain.fetch_block_header

This query returns a block header. The request may be made by height or by block hash. A height request is limited to blocks in the server's strong chain. A hash request may return a valid block in a weaker chain.

REQUEST (by height)

 0 1 2 3 
+-------+
|height |
+-------+

REQUEST (by hash)

 0                   1                   2                   3   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+---------------------------------------------------------------+
|                              hash                             |
+---------------------------------------------------------------+

RESPONSE

 0                   1                   2                   3                   4                   5                   6                   7                   8       
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
| code  |                                                                            header                                                                             |
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+

blockchain.fetch_block_height

This query returns the strong chain height of a block requested by its hash. If the block is in a weak chain the maximum value is returned as a sentinel.

REQUEST

 0                   1                   2                   3   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+---------------------------------------------------------------+
|                              hash                             |
+---------------------------------------------------------------+

RESPONSE

 0 1 2 3 4 5 6 7 
+-------+-------+
| code  |height |
+-------+-------+

blockchain.fetch_block_transaction_hashes

This query returns the ordered set of transaction hashes in a block. The request may be made by height or by block hash. A height request is limited to blocks in the server's strong chain. A hash request may return a valid block in a weaker chain.

REQUEST (by height)

 0 1 2 3 
+-------+
|height |
+-------+

REQUEST (by hash)

 0                   1                   2                   3   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+---------------------------------------------------------------+
|                              hash                             |
+---------------------------------------------------------------+

RESPONSE

 0                   1                   2                   3           
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 
+-------+---------------------------------------------------------------+
| code  |                            hashes...                          |
+-------+---------------------------------------------------------------+

blockchain.fetch_last_height

This query returns the height of the last block in the server's strong chain.

REQUEST

++
||
++

RESPONSE

 0 1 2 3 4 5 6 7 
+-------+-------+
| code  |height |
+-------+-------+

blockchain.fetch_transaction

This query returns a confirmed transaction by its hash.

REQUEST

 0                   1                   2                   3   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+---------------------------------------------------------------+
|                              hash                             |
+---------------------------------------------------------------+

RESPONSE

 0                   1    
 0 1 2 3 4 5 6 7 8 9 0 1 2
+-------+-----------------
|       |                 
| code  |  transaction... 
|       |                 
+-------+-----------------

blockchain.fetch_transaction_index

This query returns a confirmed transaction's height and block position by its hash.

REQUEST

 0                   1                   2                   3   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+---------------------------------------------------------------+
|                              hash                             |
+---------------------------------------------------------------+

RESPONSE

 0                   1    
 0 1 2 3 4 5 6 7 8 9 0 1 
+-------+---------------+
| code  |height | posit |
|       |       | ion   |
+-------+---------------+

blockchain.fetch_spend

This query returns the input that has spent an output, or error::not_found if the output is unspent.

REQUEST

 0                   1                   2                   3           
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 
+---------------------------------------------------------------+-------+
|                     output transaction hash                   | index |
+---------------------------------------------------------------+-------+

RESPONSE

 0                   1                   2                   3                   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 
+-------+---------------------------------------------------------------+-------+
| code  |                     input transaction hash                    | index |
+-------+---------------------------------------------------------------+-------+

transaction_pool.fetch_transaction

This query returns a confirmed or unconfirmed transaction by its hash. In previous versions this query returned a transaction if and only if it was unconfirmed.

REQUEST

 0                   1                   2                   3   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+---------------------------------------------------------------+
|                              hash                             |
+---------------------------------------------------------------+

RESPONSE

 0                   1    
 0 1 2 3 4 5 6 7 8 9 0 1 2
+-------+-----------------
| code  |  transaction... 
+-------+-----------------

protocol.total_connections

This query returns the current number of peers connected to the server node.

REQUEST

++
||
++

RESPONSE

 0 1 2 3 4 5 6 7 
+-------+-------+
| code  | count |
+-------+-------+

Version 3 (new)

address.subscribe2

This query subscribes to receive notifications of confirmed and unconfirmed transactions that pertain to a given prefix. The prefix is a bit field representing either a stealth payment (0 to 32 bits) or payment address (0 to 160 bits) as derived from a standard input or output script. A prefix of 32 bits or less may match both stealth payments and payment addresses. A single subscription may cause the same transaction to be sent multiple times, including upon acceptance as unconfirmed and as confirmed. The query performs subscription renewal when it encounters a subscription for a client and prefix that is already subscribed. Subscriptions otherwise expire, as configured at the server. If the notification code is nonzero (error) then the remainder of the message is not sent.

REQUEST

 0                   1                   2   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+-+-----------------------------------------|
|b|                                         |
|i|       address or stealth prefix         |
|t|   [0..20 bytes as computed from bits]   |
|s|                                         |
+-+-----------------------------------------|

RESPONSE

 0 1 2 3 
+-------+
| code  |
+-------+

NOTIFICATION

 0                   1                   2                   3                   4                   5
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0
+-------+---+-------+---------------------------------------------------------------+-----------------
|       |seq|block  |                                                               |                 
| code  |uen|height |                          block hash                           |  transaction... 
|       |ce |       |                                                               |                 
+-------+---+-------+---------------------------------------------------------------+-----------------

address.unsubscribe2

This query removes an existing subscription. This call is not required as the subscription will eventually be purged if not renewed. The response to this call is error::success even if the subscription did not exist. If a subscription existed this will cause a final notification to be sent with the error code error::service_stopped.

REQUEST

 0                   1                   2   
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
+-+-----------------------------------------|
|b|                                         |
|i|       address or stealth prefix         |
|t|   [0..20 bytes as computed from bits]   |
|s|                                         |
+-+-----------------------------------------|

RESPONSE

 0 1 2 3 
+-------+
| code  |
+-------+

blockchain.broadcast

This query validates and stores a block, announcing it to peers when it builds on the strong chain. A nonzero response code indicates either validation failure or insufficient work to build on the strong chain.

REQUEST

 0                   1                   2                   3  
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------
|                              block...                            
+---------------------------------------------------------------

RESPONSE

 0 1 2 3 
+-------+
| code  |
+-------+

blockchain.fetch_history2

This query obtains input and output (point) history data for a payment address hash. The server identifies relevant points by parsing standard input and output scripts for payment addresses hashes.

The version value is not currently used to restrict these identifications. The caller may set the start height of the request, in which case points that precede the height will be missing. The server may have a height-limited index of address history, in which case points that precede the limit will be missing. It is not possible to determine from the response whether points are missing.

The response is a set of zero or more points. Each point includes a kind value to indicate whether the point is an output (0) or a spend (1), and whether to interpret the value field as a spend identifier. The block height of the point is included for convenience. If the spend identifier does not correlate to a checksum of an output in the set, the spend is uncorrelated due to a missing output. If two outputs have the same history checksum value then the correlation is ambiguous. This is possible, though extremely unlikely.

REQUEST

 0                   1                   2           
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 
+-+-----------------------------------------+-------+
|v|                                         |       |
|e|                                         |       |
|r|                                         |       |
|s|              address hash               |height |
|i|                                         |       |
|o|                                         |       |
|n|                                         |       |
+-+-----------------------------------------+-------+

RESPONSE

 0                   1                   2                   3                   4                   5     
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 
+-------+-+---------------------------------------------------------------+-------+-------+---------------+
|       |k|                                                               |       |       |               |
| code  |i|                   point transaction hash                      | point | block | output value  |
|       |n|                                                               | index | height| or spend id   |
|       |d|                                                               |       |       |               |
+-------+-+---------------------------------------------------------------+-------+-------+---------------+
|       | |                                                               |       |       |               |
+-------+-+---------------------------------------------------------------+-------+-------+---------------+
|       | |                                                               |       |       |               |
+-------+-+---------------------------------------------------------------+-------+-------+---------------+
|       | |                             ...                               |       |       |               |

blockchain.fetch_stealth2

REQUEST

RESPONSE

blockchain.fetch_stealth_transaction

REQUEST

RESPONSE

blockchain.validate

This query validates a block. A nonzero response code indicates either validation failure or insufficient work to build on the strong chain.

REQUEST

 0                   1                   2                   3  
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------
|                              block...                            
+---------------------------------------------------------------

RESPONSE

 0 1 2 3 
+-------+
| code  |
+-------+

transaction_pool.broadcast

This query validates, stores and announces a transaction to peers, as applicable based on server policy and peer configuration. A nonzero response code indicates either validation failure or a policy barrier to acceptance.

REQUEST

 0                   1                   2                   3  
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------
|                           transaction...                            
+---------------------------------------------------------------

RESPONSE

 0 1 2 3 
+-------+
| code  |
+-------+

transaction_pool.validate2

This validates a transaction and evaluates its acceptability with respect to server policy. A nonzero response code indicates either validation failure or a policy barrier to acceptance.

REQUEST

 0                   1                   2                   3  
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------
|                           transaction...                            
+---------------------------------------------------------------

RESPONSE

 0 1 2 3 
+-------+
| code  |
+-------+

Obsolete

address.fetch_history

This query returns bitcoin payment address history for confirmed and unconfirmed transactions. The query is obsoleted in v3 due to the elimination of history indexing of unconfirmed transactions. In v3 address.subscribe2 should be used for information on unconfirmed transactions and blockchain.fetch_history2 should be used to query the blockchain for confirmed address history.

address.renew

This query renews a v2 address subscription. The query is obsoleted in v3 in favor of address.subscribe2. The primary obstacle to using address.renew is the race condition between subscription expiration and renewal.

address.subscribe

This query subscribes to receive notifications of confirmed and unconfirmed transactions that pertain to a given payment address hash. The query is obsoleted in v3 in favor of address.subscribe2. The primary obstacle to using address.subscribe is the race condition between subscription expiration and renewal.

blockchain.fetch_history

This query returns a set of payment address history data that correspond to a given payment address hash. The query is obsoleted in v3 due to its confusing reversal of the request payment address hash. In v3 blockchain.fetch_stealth2 may be used instead.

blockchain.fetch_stealth

This query returns a set of stealth payment metadata that correspond to a given prefix. The query is obsoleted in v3 due to its confusing reversal of the response payment address hash. In v3 blockchain.fetch_stealth2 may be used instead.

protocol.broadcast_transaction

This query returns a result code after attempting to broadcast a given transaction. The query is obsoleted in v3 because it does not validate the transaction (always returns success) and is poorly categorized (as protocol). In v3 transaction_pool.broadcast may be used instead (with full validation of the transaction).

transaction_pool.validate

This query returns validation status for a given transaction. The query is obsoleted in v3 because it sends a list of unconfirmed outputs and limited result codes. In v3 transaction_pool.validate2 may be used instead (with greatly expanded result code detail).