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

3 files changed, 45 insertions, 0 deletions

diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md
new file mode 100644
index 0000000000..59df541567
--- /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.
diff --git a/doc/README.md b/doc/README.md
index acee6d0c80..344b1be5c4 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -56,6 +56,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th
 - [Translation Process](translation_process.md)
 - [Translation Strings Policy](translation_strings_policy.md)
 - [Travis CI](travis-ci.md)
+- [JSON-RPC Interface](JSON-RPC-interface.md)
 - [Unauthenticated REST Interface](REST-interface.md)
 - [Shared Libraries](shared-libraries.md)
 - [BIPS](bips.md)
diff --git a/doc/REST-interface.md b/doc/REST-interface.md
index 7010edfcd3..44df698382 100644
--- a/doc/REST-interface.md
+++ b/doc/REST-interface.md
@@ -6,6 +6,12 @@ The REST API can be enabled with the `-rest` option.
 The interface runs on the same port as the JSON-RPC interface, by default port 8332 for mainnet, port 18332 for testnet,
 and port 18443 for regtest.
 
+REST Interface consistency guarantees
+-------------------------------------
+
+The [same guarantees as for the RPC Interface](/doc/JSON-RPC-interface.md#rpc-consistency-guarantees)
+apply.
+
 Supported API
 -------------