-
Notifications
You must be signed in to change notification settings - Fork 65
Client Server Interface
Libbitcoin messages conform to a uniform message structure implemented using ZeroMQ. The command and 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.
The libbitcoin-server secure and public query endpoints are implemented as ZMQ_ROUTER sockets. Clients may connect as ZMQ_REQ or ZMQ_DEALER sockets. There are ZeroMQ bindings for a large number of languages.
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
+---------------------------------------------------------------+
| block 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 |
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
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
+---------------------------------------------------------------+
| block hash |
+---------------------------------------------------------------+
RESPONSE
0 1 2 3 4 5 6 7
+-------+-------+
| code |height |
+-------+-------+
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
+---------------------------------------------------------------+
| block 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 | block hash |
+-------+---------------------------------------------------------------+
| |
+---------------------------------------------------------------+
| ... |
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 |
+-------+-------+
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
+---------------------------------------------------------------+
| transaction hash |
+---------------------------------------------------------------+
RESPONSE
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2
+-------+-----------------
| |
| code | transaction...
| |
+-------+-----------------
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
+---------------------------------------------------------------+
| transaction hash |
+---------------------------------------------------------------+
RESPONSE
0 1
0 1 2 3 4 5 6 7 8 9 0 1
+-------+---------------+
| code |height | posit |
| | | ion |
+-------+---------------+
This query returns the input that has spent an output, or error::not_found if the output is unspent. The server may have a height-limited index of spend history, in which case a spend that precedes the limit will be missing. It is not possible to determine from a response whether a spend is missing.
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 |
+-------+---------------------------------------------------------------+-------+
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
+---------------------------------------------------------------+
| transaction hash |
+---------------------------------------------------------------+
RESPONSE
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2
+-------+-----------------
| code | transaction...
+-------+-----------------
This query subscribes to receive notifications of confirmed and unconfirmed transactions that pertain to a given payment address hash as derived from a standard input or output script. 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 may not be 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
+-----------------------------------------|
| address hash |
+-----------------------------------------|
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 | | |
+-------+---+-------+---------------------------------------------------------------+-----------------
TODO:
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
+-----------------------------------------|
| address hash |
+-----------------------------------------|
RESPONSE
0 1 2 3
+-------+
| code |
+-------+
TODO:
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 |
+-------+
This query returns 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 a fully-correlated response whether points are missing.
The response includes 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, and may be necessary to handle as an error condition depending on the scenario.
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
+-----------------------------------------+-------+
| address hash |height |
+-----------------------------------------+-------+
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| | | | |
+-------+-+---------------------------------------------------------------+-------+-------+---------------+
| | | | | |
+-+---------------------------------------------------------------+-------+-------+---------------+
| | ... | | | |
This query returns stealth payment metadata for use in discovering payments made to a stealth address and advertised via a stealth prefix saved to a transaction in the blockchain. The server identifies relevant transactions by parsing standard stealth outputs for potential stealth payment metadata. The stealth prefix is limited to [1..4] bytes, as computed from the bits value (the maximum size is show below). The caller may set the start height of the request, in which case records that precede the height will be missing. The server may have a height-limited index of stealth metadata, in which case records that precede the limit will be missing. It is not possible to determine from a response whether records are missing.
The response includes a set of stealth metadata that correspond to the prefix.
This query is unsafe if not all transactions corresponding to the response are subsequently requested from the server, as filter bits can be eliminated for every transaction not requested. As such it is recommended to use
blockchain.fetch_stealth_transaction_hashes.
REQUEST
0 1 2 3 4 5 6 7 8
+-+-------+-------+
|b|stealth| |
|i|prefix |height |
|t|[1..4 | |
|s| bytes]| |
+-+-------+-------+
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 4 5 6 7
+-------+---------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------+
| code | ephemeral public key hash | public key hash | transaction hash |
+-------+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------+
| | | |
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------+
| ... | ... | ... |
This query returns hashes of potential stealth transactions that correspond to a stealth prefix. The server identifies relevant transactions by parsing standard stealth outputs for potential stealth payment metadata. The stealth prefix is limited to [1..4] bytes, as computed from the bits value (the maximum size is show below). The caller may set the start height of the request, in which case transactions that precede the height will be missing. The server may have a height-limited index of stealth metadata, in which case transactions that precede the limit will be missing. It is not possible to determine from a response whether transactions are missing.
The response includes a set of hashes of transactions that that contain metadata that correspond to the prefix. The caller may fetch the transactions and then parse them using libbitcoin stealth utilities.
REQUEST
0 1 2 3 4 5 6 7 8
+-+-------+-------+
|b|stealth| |
|i|prefix |height |
|t|[1..4 | |
|s| bytes]| |
+-+-------+-------+
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 | transaction hash |
+-------+---------------------------------------------------------------+
| |
+---------------------------------------------------------------+
| ... |
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 |
+-------+
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 |
+-------+
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 |
+-------+
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.
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.
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.
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_history2 may be used instead.
This query returns a set of payment address history data that correspond to a given payment address hash. The query is obsoleted in v3.1 in favor of blockchain.fetch_history3 due to its incorporation of an unused version byte parameter.
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.
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).
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).
This query returns the number of peer-to-peer network connections at the server's node The query is obsoleted in v3.1 because it leaks administrative information about the server.
Users | Developers | License | Copyright © 2011-2024 libbitcoin developers
- Home
- Build Server
- Download Server
- Frequently Asked Questions
- General Information
- Client Server Interface
- Configuration Settings
- Tutorials