READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

10,879 bytes · SHA-256 cce200eb983a9ae7… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2018-present The Bitcoin Core developers
3# Distributed under the MIT software license, see the accompanying
4# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5"""Tests some generic aspects of the RPC interface."""
6
7import json
8import os
9from dataclasses import dataclass
10from test_framework.test_framework import BitcoinTestFramework
11from test_framework.util import JSONRPCException, assert_equal, assert_greater_than_or_equal
12from threading import Thread
13from typing import Optional
14
15
16RPC_INVALID_PARAMETER      = -8
17RPC_METHOD_NOT_FOUND       = -32601
18RPC_INVALID_REQUEST        = -32600
19RPC_PARSE_ERROR            = -32700
20
21
22@dataclass
23class BatchOptions:
24    version: Optional[int] = None
25    notification: bool = False
26    request_fields: Optional[dict] = None
27    response_fields: Optional[dict] = None
28
29
30def format_request(options, idx, fields):
31    request = {}
32    if options.version == 1:
33        request.update(version="1.1")
34    elif options.version == 2:
35        request.update(jsonrpc="2.0")
36    elif options.version is not None:
37        raise NotImplementedError(f"Unknown JSONRPC version {options.version}")
38    if not options.notification:
39        request.update(id=idx)
40    request.update(fields)
41    if options.request_fields:
42        request.update(options.request_fields)
43    return request
44
45
46def format_response(options, idx, fields):
47    if options.version == 2 and options.notification:
48        return None
49    response = {}
50    if not options.notification:
51        response.update(id=idx)
52    if options.version == 2:
53        response.update(jsonrpc="2.0")
54    else:
55        response.update(result=None, error=None)
56    response.update(fields)
57    if options.response_fields:
58        response.update(options.response_fields)
59    return response
60
61
62def send_raw_rpc(node, raw_body: bytes) -> tuple[object, int]:
63    return node._request("POST", "/", raw_body)
64
65
66def send_json_rpc(node, body: object) -> tuple[object, int]:
67    raw = json.dumps(body).encode("utf-8")
68    return send_raw_rpc(node, raw)
69
70
71def expect_http_rpc_status(expected_http_status, expected_rpc_error_code, node, method, params, version=1, notification=False):
72    req = format_request(BatchOptions(version, notification), 0, {"method": method, "params": params})
73    response, status = send_json_rpc(node, req)
74
75    if expected_rpc_error_code is not None:
76        assert_equal(response["error"]["code"], expected_rpc_error_code)
77
78    assert_equal(status, expected_http_status)
79
80
81def test_work_queue_getblock(node, got_exceeded_error):
82    while not got_exceeded_error:
83        try:
84            node.cli("waitfornewblock", "500").send_cli()
85        except JSONRPCException as e:
86            assert_equal(e.error["message"], "non-JSON HTTP response with '503 Service Unavailable' from server: Work queue depth exceeded")
87            got_exceeded_error.append(True)
88
89
90class RPCInterfaceTest(BitcoinTestFramework):
91    def set_test_params(self):
92        self.num_nodes = 1
93        self.setup_clean_chain = True
94        self.supports_cli = False
95
96    def test_getrpcinfo(self):
97        self.log.info("Testing getrpcinfo...")
98
99        info = self.nodes[0].getrpcinfo()
100        assert_equal(len(info['active_commands']), 1)
101
102        command = info['active_commands'][0]
103        assert_equal(command['method'], 'getrpcinfo')
104        assert_greater_than_or_equal(command['duration'], 0)
105        assert_equal(info['logpath'], os.path.join(self.nodes[0].chain_path, 'debug.log'))
106
107    def test_batch_request(self, call_options):
108        calls = [
109            # A basic request that will work fine.
110            {"method": "getblockcount"},
111            # Request that will fail.  The whole batch request should still
112            # work fine.
113            {"method": "invalidmethod"},
114            # Another call that should succeed.
115            {"method": "getblockhash", "params": [0]},
116            # Invalid request format
117            {"pizza": "sausage"}
118        ]
119        results = [
120            {"result": 0},
121            {"error": {"code": RPC_METHOD_NOT_FOUND, "message": "Method not found"}},
122            {"result": "0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206"},
123            {"error": {"code": RPC_INVALID_REQUEST, "message": "Missing method"}},
124        ]
125
126        request = []
127        response = []
128        for idx, (call, result) in enumerate(zip(calls, results), 1):
129            options = call_options(idx)
130            if options is None:
131                continue
132            request.append(format_request(options, idx, call))
133            r = format_response(options, idx, result)
134            if r is not None:
135                response.append(r)
136
137        rpc_response, http_status = send_json_rpc(self.nodes[0], request)
138        if len(response) == 0 and len(request) > 0:
139            assert_equal(http_status, 204)
140            assert_equal(rpc_response, None)
141        else:
142            assert_equal(http_status, 200)
143            assert_equal(rpc_response, response)
144
145    def test_batch_requests(self):
146        self.log.info("Testing empty batch request...")
147        self.test_batch_request(lambda idx: None)
148
149        self.log.info("Testing basic JSON-RPC 2.0 batch request...")
150        self.test_batch_request(lambda idx: BatchOptions(version=2))
151
152        self.log.info("Testing JSON-RPC 2.0 batch with notifications...")
153        self.test_batch_request(lambda idx: BatchOptions(version=2, notification=idx < 2))
154
155        self.log.info("Testing JSON-RPC 2.0 batch of ALL notifications...")
156        self.test_batch_request(lambda idx: BatchOptions(version=2, notification=True))
157
158        # JSONRPC 1.1 does not support batch requests, but test them for backwards compatibility.
159        self.log.info("Testing nonstandard JSON-RPC 1.1 batch request...")
160        self.test_batch_request(lambda idx: BatchOptions(version=1))
161
162        self.log.info("Testing nonstandard mixed JSON-RPC 1.1/2.0 batch request...")
163        self.test_batch_request(lambda idx: BatchOptions(version=2 if idx % 2 else 1))
164
165        self.log.info("Testing nonstandard batch request without version numbers...")
166        self.test_batch_request(lambda idx: BatchOptions())
167
168        self.log.info("Testing nonstandard batch request without version numbers or ids...")
169        self.test_batch_request(lambda idx: BatchOptions(notification=True))
170
171        self.log.info("Testing nonstandard jsonrpc 1.0 version number is accepted...")
172        self.test_batch_request(lambda idx: BatchOptions(request_fields={"jsonrpc": "1.0"}))
173
174        self.log.info("Testing unrecognized jsonrpc version number is rejected...")
175        self.test_batch_request(lambda idx: BatchOptions(
176            request_fields={"jsonrpc": "2.1"},
177            response_fields={"result": None, "error": {"code": RPC_INVALID_REQUEST, "message": "JSON-RPC version not supported"}}))
178
179    def test_http_status_codes(self):
180        self.log.info("Testing HTTP status codes for JSON-RPC 1.1 requests...")
181        # OK
182        expect_http_rpc_status(200, None,                  self.nodes[0], "getblockhash", [0])
183        # Errors
184        expect_http_rpc_status(404, RPC_METHOD_NOT_FOUND,  self.nodes[0], "invalidmethod", [])
185        expect_http_rpc_status(500, RPC_INVALID_PARAMETER, self.nodes[0], "getblockhash", [42])
186        # force-send empty request
187        response, status = send_raw_rpc(self.nodes[0], b"")
188        assert_equal(response, {"id": None, "result": None, "error": {"code": RPC_PARSE_ERROR, "message": "Parse error"}})
189        assert_equal(status, 500)
190        # force-send invalidly formatted request
191        response, status = send_raw_rpc(self.nodes[0], b"this is bad")
192        assert_equal(response, {"id": None, "result": None, "error": {"code": RPC_PARSE_ERROR, "message": "Parse error"}})
193        assert_equal(status, 500)
194
195        self.log.info("Testing HTTP status codes for JSON-RPC 2.0 requests...")
196        # OK
197        expect_http_rpc_status(200, None,                   self.nodes[0], "getblockhash", [0],  2, False)
198        # RPC errors but not HTTP errors
199        expect_http_rpc_status(200, RPC_METHOD_NOT_FOUND,   self.nodes[0], "invalidmethod", [],  2, False)
200        expect_http_rpc_status(200, RPC_INVALID_PARAMETER,  self.nodes[0], "getblockhash", [42], 2, False)
201        # force-send invalidly formatted requests
202        response, status = send_json_rpc(self.nodes[0], {"jsonrpc": 2, "method": "getblockcount"})
203        assert_equal(response, {"result": None, "error": {"code": RPC_INVALID_REQUEST, "message": "jsonrpc field must be a string"}})
204        assert_equal(status, 400)
205        response, status = send_json_rpc(self.nodes[0], {"jsonrpc": "3.0", "method": "getblockcount"})
206        assert_equal(response, {"result": None, "error": {"code": RPC_INVALID_REQUEST, "message": "JSON-RPC version not supported"}})
207        assert_equal(status, 400)
208
209        self.log.info("Testing HTTP status codes for JSON-RPC 2.0 notifications...")
210        # Not notification: id exists
211        response, status = send_json_rpc(self.nodes[0], {"jsonrpc": "2.0", "id": None, "method": "getblockcount"})
212        assert_equal(response["result"], 0)
213        assert_equal(status, 200)
214        # Not notification: JSON 1.1
215        expect_http_rpc_status(200, None,                   self.nodes[0], "getblockcount", [],  1)
216        # Not notification: has "id" field
217        expect_http_rpc_status(200, None,                   self.nodes[0], "getblockcount", [],  2, False)
218        block_count = self.nodes[0].getblockcount()
219        # Notification response status code: HTTP_NO_CONTENT
220        expect_http_rpc_status(204, None,                   self.nodes[0], "generatetoaddress", [1, "bcrt1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqdku202"],  2, True)
221        # The command worked even though there was no response
222        assert_equal(block_count + 1, self.nodes[0].getblockcount())
223        # No error response for notifications even if they are invalid
224        expect_http_rpc_status(204, None, self.nodes[0], "generatetoaddress", [1, "invalid_address"], 2, True)
225        # Sanity check: command was not executed
226        assert_equal(block_count + 1, self.nodes[0].getblockcount())
227
228    def test_work_queue_exceeded(self):
229        self.log.info("Testing work queue exceeded...")
230        self.restart_node(0, ['-rpcworkqueue=1', '-rpcthreads=1'])
231        got_exceeded_error = []
232        threads = []
233        for _ in range(3):
234            t = Thread(target=test_work_queue_getblock, args=(self.nodes[0], got_exceeded_error))
235            t.start()
236            threads.append(t)
237        for t in threads:
238            t.join()
239
240    def run_test(self):
241        self.test_getrpcinfo()
242        self.test_batch_requests()
243        self.test_http_status_codes()
244        self.test_work_queue_exceeded()
245
246
247if __name__ == '__main__':
248    RPCInterfaceTest(__file__).main()
249

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.