Architecture

bitcoin-core-rpc is a JSON-RPC client library that runs inside its caller’s process. This page is its high-level design: the modules, how they depend on one another, and the properties those dependencies keep. What a user can expect of it in terms of security is SECURITY, and why those expectations hold is the assurance case.

Four modules, one direction

A package of four modules under src/bitcoin_core_rpc/, __init__.py itself a facade re-exporting __all__ rather than defining any of it: errors.py the exception hierarchy every other module raises out of, chains.py the chain and network vocabulary, transport.py the urllib layer, client.py the two clients built on the three beneath it. A module may import any of the ones before it in that order and none of the ones after — errors < chains < transport < client — and none of the four takes a dependency outside the standard library. tests/census_test.py reads the imports of every source file with ast and holds both the order and the closure, rather than trusting what ran; CONTRIBUTING.md’s The one constraint is the rule a contributor is bound by.

The transport layer

transport.py is the only module here that opens a socket, and http_request maps everything below an HTTP status onto FetchError: what a status means is client.py’s question, never the transport’s. HttpTransport — a callable taking the built request and a timeout, answering with the status and the body — is the public seam a caller’s own transport implements, and urlopen_transport is the default. _read_bounded is what every transport built here reads a reply through: a deadline taken once, before the exchange starts, and a loop of bounded chunks rather than one blocking read, so a body larger than max_body_size or slower than timeout is refused instead of held in memory or waited out indefinitely. Beneath it, the connections both transports open — _DeadlineHTTPConnection and its TLS subclass — hold everything before the body to that deadline as well: the name lookup, each connect attempt, the handshake, every send, and every recv of the status line and the headers, each given what is left of it.

SessionTransport is the alternative transport, one connection kept per (scheme, host, port) and reused across calls rather than one socket per call: a probe before every reuse, and one reconnect where the write fails, are what let it do that without ever re-sending a request the node may already be executing — its own docstring is the argument in full.

Three things a caller cannot get from HttpTransport’s own two arguments, and what http_request and urlopen_transport each do about them: only http and https reach a Request (_SCHEMES), no proxy is taken from the environment (ProxyHandler({}) in the one _OPENER this module builds its I/O with), and no redirect is followed (_NoRedirect). The Authorization header is built for one host, so following a 30x elsewhere, or letting HTTP_PROXY redirect the exchange, would send that credential somewhere the caller never named.

Two JSON-RPC versions, one client

Core answers JSON-RPC 1.1 by default and 2.0 to a request carrying the "jsonrpc": "2.0" marker; a node older than v28 does not recognize the marker and answers 1.1 regardless. Under 1.1 an rpc error arrives as the body of an HTTP 500, so the error is read before the status is judged. client.py’s _discriminate picks the shape from the reply’s own jsonrpc member, and _legacy_result and _v2_result are two functions rather than one with a flag, each reading its own version’s rule for where an error can be found. BitcoinCoreRpcClient.call always sends the 2.0 marker; call_raw is the one place a caller controls it, for a harness testing a server’s own conformance.

Every reply is also read against the request that asked for it: _reply_object refuses a body that does not parse as a json object, and _id_error refuses one whose id does not match — a caching proxy, or another call’s own answer arriving out of turn, is not read as this call’s result.

Credentials

BitcoinCoreRpcClient takes either a cookie path or a user/password pair, never both and never neither — each names who is calling, so a client given both would have to rank them. auth_header builds the Basic credential at every call rather than once: a cookie path is re-read through chains.cookie_auth, since bitcoind rewrites the file at every restart, and a client built while the node was up still works an hour and a restart later. BitcoinCoreRpcClient defines no __repr__, because a generated one prints every field, and the credential would then appear in any traceback or log line that renders the client. BitcoinCoreRestClient, over Core’s -rest interface, takes no credential at all — -rest authenticates nobody who reaches it — and shares only the transport and the chain vocabulary with the JSON-RPC client.

chains.cookie_auth reads the cookie file ascii, one line, bounded to _MAX_COOKIE_SIZE: a path that is not a cookie file is the ordinary mistake, and every failure to read one as such is a FetchError naming the file rather than a raw exception carrying its contents.

The two clients and RpcChannel

BitcoinCoreRpcClient.call invokes one rpc method; call_batch sends several in one HTTP exchange and correlates each reply by id, a member’s own RpcError sitting at its position rather than discarding every other member’s answer; call_raw hands back the envelope unread, for a caller who wants what arrived rather than what call makes of it. for_wallet derives a client for a node’s /wallet/<name> endpoint, always from the client the wallet client set was built from, never composing a second wallet segment onto an existing one. BitcoinCoreRestClient is -rest’s two shapes, get_bin and get_json, over a path the caller builds from Core’s own documentation of the interface: there is no per-resource method, because -rest itself cannot always tell two answers apart — README.md’s Reading Core’s -rest interface has why. RpcChannel is attribute-style sugar over a client’s call, with a hand-written guard in front of every name starting with _ so that copy.deepcopy or an interactive shell probing for a dunder does not turn into an rpc call of that name.

What proves it, and what a live node adds

tests/__init__.py’s Recorded is the transport a test passes wherever a client’s call has to answer with something: it answers from bytes committed under tests/_data, written from Core’s source rather than captured from a node, and opens no socket. That is what keeps the suite hermetic and fast, and it is also a boundary: a fixture proves the client reads the shape Core’s source says it sends, not that a live node sends it.

.github/scripts/rpc_smoke.py is the other half. Its --protocol mode starts a real bitcoind on a regtest chain it generates itself and puts to it what a fixture cannot settle, the script’s own docstring listing what and why. Its --chain mode starts a node of any of Core’s five chains with no peer reachable at all and checks only that Core still accepts -chain=<name>, echoes it back, and passes assert_chain for it. Neither mode lets the node reach the network: -listen=0 throughout, and -connect=0 -dnsseed=0 besides for --chain, regtest alone shipping no seed to connect to or look up. .github/workflows/integration-bitcoind.yml runs it against as many Core majors as the trigger calls for; what it trusts in bitcoind is stated where that workflow downloads it: an immutable, versioned archive fetched over https and checked against a SHA256SUMS digest pinned in the workflow itself before anything in the archive is extracted or run, with a negative control proving the check would fail a tampered digest.

The public surface

__all__ is declared in every module, and it is the union __init__.py re-exports — a name is public because that list says so. There is no version constant anywhere in the package: the release tag is the version, which pyproject.toml’s own comment on the point states for the one place the number is written down.