diff options
| author | Wladimir J. van der Laan <[email protected]> | 2018-11-01 16:17:12 +0100 |
|---|---|---|
| committer | Wladimir J. van der Laan <[email protected]> | 2018-11-01 16:17:24 +0100 |
| commit | f69d92299dea352696b7ee342ae61099c0a5f333 (patch) | |
| tree | 628cbddeaa415003a29829104327d413f178096f /doc/JSON-RPC-interface.md | |
| parent | Merge #14197: [psbt] Convert non-witness UTXOs to witness if witness sig created (diff) | |
| parent | doc: Add external interface consistency guarantees (diff) | |
| download | discoin-f69d92299dea352696b7ee342ae61099c0a5f333.tar.xz discoin-f69d92299dea352696b7ee342ae61099c0a5f333.zip | |
Merge #14592: doc: Add external interface consistency guarantees
fa77aaa5ad21563dd18ce3e407d391d37ac8c201 doc: Add external interface consistency guarantees (MarcoFalke)
Pull request description:
An attempt to clarify our consistency guarantees for developers and users
Tree-SHA512: 8bad6a2bcfd85f0aeeecf3b090332f64c778c69a838a519d11ea83f2cb51929b9f43a7e9b2469567f305a1277206cafe8e65041f1a002dadbe69259d6a0adc18
Diffstat (limited to 'doc/JSON-RPC-interface.md')
| -rw-r--r-- | doc/JSON-RPC-interface.md | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md new file mode 100644 index 000000000..59df54156 --- /dev/null +++ b/doc/JSON-RPC-interface.md @@ -0,0 +1,38 @@ +# JSON-RPC Interface + +The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI +`bitcoin-qt` has it disabled by default. This can be changed with the `-server` +option. In the GUI it is possible to execute RPC methods in the Debug Console +Dialog. + +## RPC consistency guarantees + +State that can be queried via RPCs is guaranteed to be at least up-to-date with +the chain state immediately prior to the call's execution. However, the state +returned by RPCs that reflect the mempool may not be up-to-date with the +current mempool state. + +### Transaction Pool + +The mempool state returned via an RPC is consistent with itself and with the +chain state at the time of the call. Thus, the mempool state only encompasses +transactions that are considered mine-able by the node at the time of the RPC. + +The mempool state returned via an RPC reflects all effects of mempool and chain +state related RPCs that returned prior to this call. + +### Wallet + +The wallet state returned via an RPC is consistent with itself and with the +chain state at the time of the call. + +Wallet RPCs will return the latest chain state consistent with prior non-wallet +RPCs. The effects of all blocks (and transactions in blocks) at the time of the +call is reflected in the state of all wallet transactions. For example, if a +block contains transactions that conflicted with mempool transactions, the +wallet would reflect the removal of these mempool transactions in the state. + +However, the wallet may not be up-to-date with the current state of the mempool +or the state of the mempool by an RPC that returned before this RPC. For +example, a wallet transaction that was BIP-125-replaced in the mempool prior to +this RPC may not yet be reflected as such in this RPC response. |