maxmustermann/dogecoin
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge #14592: doc: Add external interface consistency guarantees

Browse source 
fa77aaa5ad doc: Add external interface consistency guarantees (MarcoFalke)

Pull request description:

  An attempt to clarify our consistency guarantees for developers and users

Tree-SHA512: 8bad6a2bcfd85f0aeeecf3b090332f64c778c69a838a519d11ea83f2cb51929b9f43a7e9b2469567f305a1277206cafe8e65041f1a002dadbe69259d6a0adc18
This commit is contained in:
Wladimir J. van der Laan 2018-11-01 16:17:12 +01:00
commit f69d92299d
No known key found for this signature in database
GPG key ID: 1E4AED62986CD25D
3 changed files with 45 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
doc/JSON-RPC-interface.md Normal file
View file

@ -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.

1
doc/README.md
View file

@ -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)

6
doc/REST-interface.md
View file

@ -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
-------------