From c4784b506558744749acf12d4cff1aca2dcc3f76 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Wed, 3 May 2017 15:57:56 -0400 Subject: [PATCH] Add a dev notes document describing the new wallet RPC blocking --- doc/developer-notes.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 33c6ab9cb3..0eeea3c7b0 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -644,3 +644,16 @@ A few guidelines for introducing and reviewing new RPC interfaces: - *Rationale*: If a RPC response is not a JSON object then it is harder to avoid API breakage if new data in the response is needed. + +- Wallet RPCs call BlockUntilSyncedToCurrentChain to maintain consistency with + `getblockchaininfo`'s state immediately prior to the call's execution. Wallet + RPCs whose behavior does *not* depend on the current chainstate may omit this + call. + + - *Rationale*: In previous versions of Bitcoin Core, the wallet was always + in-sync with the chainstate (by virtue of them all being updated in the + same cs_main lock). In order to maintain the behavior that wallet RPCs + return results as of at least the highest best-known block an RPC + client may be aware of prior to entering a wallet RPC call, we must block + until the wallet is caught up to the chainstate as of the RPC call's entry. + This also makes the API much easier for RPC clients to reason about.