Protocol Changes

This document lists changes made by protocol version.

Version 1.0

Deprecated methods

• blockchain.utxo.get_address()

• blockchain.numblocks.subscribe()

Version 1.1

Changes

• improved semantics of server.version() to aid protocol negotiation, and a changed return value.

• blockchain.transaction.get() no longer takes the height argument that was ignored anyway.

• blockchain.transaction.broadcast() returns errors like any other JSON RPC call. A transaction hash result is only returned on success.

New methods

• blockchain.scripthash.get_balance()

• blockchain.scripthash.get_history()

• blockchain.scripthash.get_mempool()

• blockchain.scripthash.listunspent()

• blockchain.scripthash.subscribe()

• server.features()

• server.add_peer()

Removed methods

• blockchain.utxo.get_address()

• blockchain.numblocks.subscribe()

Version 1.2

Changes

• blockchain.transaction.get() now has an optional parameter verbose.

• blockchain.headers.subscribe() now has an optional parameter raw.

• server.version() should not be used for “ping” functionality; use the new server.ping() method instead.

New methods

• blockchain.block.headers()

• mempool.get_fee_histogram()

• server.ping()

Deprecated methods

• blockchain.block.get_chunk(). Switch to blockchain.block.headers()

• blockchain.address.get_balance(). Switch to blockchain.scripthash.get_balance().

• blockchain.address.get_history(). Switch to blockchain.scripthash.get_history().

• blockchain.address.get_mempool(). Switch to blockchain.scripthash.get_mempool().

• blockchain.address.listunspent(). Switch to blockchain.scripthash.listunspent().

• blockchain.address.subscribe(). Switch to blockchain.scripthash.subscribe().

• blockchain.headers.subscribe() with raw other than True.

Version 1.3

Changes

• blockchain.headers.subscribe() argument raw switches default to True

New methods

• blockchain.block.header()

Removed methods

• blockchain.address.get_balance()

• blockchain.address.get_history()

• blockchain.address.get_mempool()

• blockchain.address.listunspent()

• blockchain.address.subscribe()

Deprecated methods

• blockchain.block.get_header(). Switch to blockchain.block.header().

Version 1.4

This version removes all support for deserialized headers.

Changes

• Deserialized headers are no longer available, so removed argument raw from blockchain.headers.subscribe().

• Only the first server.version() message is accepted.

• Optional cp_height argument added to blockchain.block.header() and blockchain.block.headers() to return merkle proofs of the header to a given checkpoint.

New methods

• blockchain.transaction.id_from_pos() to return a transaction hash, and optionally a merkle proof, given a block height and position in the block.

Removed methods

• blockchain.block.get_header()

• blockchain.block.get_chunk()

Version 1.4.1

Changes

• blockchain.block.header() and blockchain.block.headers() now truncate AuxPoW data (if using an AuxPoW chain) when cp_height is nonzero. AuxPoW data is still present when cp_height is zero. Non-AuxPoW chains are unaffected.

Version 1.4.2

New methods

• blockchain.scripthash.unsubscribe() to unsubscribe from a script hash.

Version 1.4.3

New methods

• blockchain.name.get_value_proof() to resolve a name (with proof). Name index coins (e.g. Namecoin) only.

Version 1.5

(this version number was skipped, no corresponding protocol is defined)

Version 1.6

Changes

• Breaking change for the version negotiation: we now mandate that the server.version() message must be the first message sent. That is, version negotiation must happen before any other messages.

• Also for server.version(), the server must tolerate and ignore extraneous arguments, to allow for extensions in future protocol versions.

• The status of a scripthash has its definition tightened in a backwards-compatible way: mempool txs now have a canonical ordering defined for the calculation (previously their order was undefined).

• blockchain.scripthash.get_mempool() previously did not define an order for mempool transactions. We now mandate a specific ordering.

• Optional mode argument added to blockchain.estimatefee().

• blockchain.block.headers() now returns headers as a list, instead of a single concatenated hex string.

New methods

• blockchain.transaction.broadcast_package() to broadcast a package of transactions (submitpackage).

• mempool.get_info() to get more detailed and general relayfee info.

Removed methods

• blockchain.relayfee() is removed. The minrelaytxfee field of the new mempool.get_info() RPC is a direct replacement.

Version 1.7

Changes

• server.ping() can now also be sent as an unrequested notification, by both the client and the server. The request/response signature also changed.

• The blockchain.scripthash.* methods are all replaced with blockchain.scriptpubkey.* methods. Note: sha256(scriptPubKey) == scripthash. Besides taking a scriptPubKey instead of a scripthash as input param, the new methods also have some minor functional changes.

  • the notifications for blockchain.scriptpubkey.subscribe() still contain the scripthash

  • the protocol now guarantees that a notification is sent even if the status of the scriptPubKey did not change but there was a reorg affecting a relevant tx

  • many RPCs now return a dict instead of an array

• The hash_function field is removed from the server.features() response.

• Standardize “history too large” error code for blockchain.scriptpubkey.* methods.

New methods

• blockchain.scriptpubkey.get_balance()

• blockchain.scriptpubkey.get_history()

• blockchain.scriptpubkey.get_mempool()

• blockchain.scriptpubkey.listunspent()

• blockchain.scriptpubkey.subscribe()

• blockchain.scriptpubkey.unsubscribe()

• blockchain.outpoint.subscribe() to subscribe to a transaction outpoint, and get a notification when it gets spent.

• blockchain.outpoint.unsubscribe() to unsubscribe from a TXO.

• blockchain.outpoint.get_status() to get current status of a TXO, without subscribing to changes.

• blockchain.transaction.testmempoolaccept()

• mempool.recent() to list a few of the latest txs just added to the mempool.

Removed methods

• blockchain.scripthash.get_balance()

• blockchain.scripthash.get_history()

• blockchain.scripthash.get_mempool()

• blockchain.scripthash.listunspent()

• blockchain.scripthash.subscribe()

• blockchain.scripthash.unsubscribe()