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.

34,624 bytes · SHA-256 39ad7fc2895917c8… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2014-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"""Test the REST API."""
6
7from decimal import Decimal
8from enum import Enum
9from io import BytesIO
10import http.client
11import json
12import typing
13import urllib.parse
14
15
16from test_framework.messages import (
17    BLOCK_HEADER_SIZE,
18    COIN,
19    deser_block_spent_outputs,
20)
21from test_framework.test_framework import BitcoinTestFramework
22from test_framework.util import (
23    assert_equal,
24    assert_greater_than,
25    assert_greater_than_or_equal,
26    assert_not_equal,
27    sync_txindex,
28)
29from test_framework.wallet import (
30    MiniWallet,
31    getnewdestination,
32)
33
34
35INVALID_PARAM = "abc"
36UNKNOWN_PARAM = "0000000000000000000000000000000000000000000000000000000000000000"
37
38
39class ReqType(Enum):
40    JSON = 1
41    BIN = 2
42    HEX = 3
43
44class RetType(Enum):
45    OBJ = 1
46    BYTES = 2
47    JSON = 3
48
49def filter_output_indices_by_value(vouts, value):
50    for vout in vouts:
51        if vout['value'] == value:
52            yield vout['n']
53
54class RESTTest (BitcoinTestFramework):
55    def set_test_params(self):
56        self.num_nodes = 2
57        self.extra_args = [["-rest", "-blockfilterindex=1", "-txindex"], []]
58        # whitelist peers to speed up tx relay / mempool sync
59        self.noban_tx_relay = True
60
61    def test_rest_request(
62            self,
63            uri: str,
64            http_method: str = 'GET',
65            req_type: typing.Optional[ReqType] = ReqType.JSON,
66            body: str = '',
67            status: int = 200,
68            ret_type: RetType = RetType.JSON,
69            query_params: typing.Union[dict[str, typing.Any], str, None] = None,
70            ) -> typing.Union[http.client.HTTPResponse, bytes, str, None]:
71        rest_uri = '/rest' + uri
72        if isinstance(req_type, ReqType):
73            rest_uri += f'.{req_type.name.lower()}'
74        if query_params:
75            if isinstance(query_params, str):
76                rest_uri += f'?{query_params}'
77            else:
78                rest_uri += f'?{urllib.parse.urlencode(query_params)}'
79
80        conn = http.client.HTTPConnection(self.url.hostname, self.url.port)
81        self.log.debug(f'{http_method} {rest_uri} {body}')
82        if http_method == 'GET':
83            conn.request('GET', rest_uri)
84        elif http_method == 'POST':
85            conn.request('POST', rest_uri, body)
86        resp = conn.getresponse()
87
88        assert resp.status == status, f"Expected: {status}, Got: {resp.status} ({resp.reason}) - Response: {str(resp.read())}"
89
90        if ret_type == RetType.OBJ:
91            return resp
92        elif ret_type == RetType.BYTES:
93            return resp.read()
94        elif ret_type == RetType.JSON:
95            return json.loads(resp.read().decode('utf-8'), parse_float=Decimal)
96
97        return None
98
99    def run_test(self):
100        self.url = urllib.parse.urlparse(self.nodes[0].url)
101        self.wallet = MiniWallet(self.nodes[0])
102
103        self.log.info("Broadcast test transaction and sync nodes")
104        txid = self.wallet.send_to(from_node=self.nodes[0], scriptPubKey=getnewdestination()[1], amount=int(0.1 * COIN))["txid"]
105        self.sync_all()
106
107        self.log.info("Test the /tx URI")
108
109        json_obj = self.test_rest_request(f"/tx/{txid}")
110        assert_equal(json_obj['txid'], txid)
111
112        # Check hex format response
113        hex_response = self.test_rest_request(f"/tx/{txid}", req_type=ReqType.HEX, ret_type=RetType.OBJ)
114        assert_greater_than_or_equal(int(hex_response.getheader('content-length')),
115                                     json_obj['size']*2)
116
117        spent = (json_obj['vin'][0]['txid'], json_obj['vin'][0]['vout'])  # get the vin to later check for utxo (should be spent by then)
118        # get n of 0.1 outpoint
119        n, = filter_output_indices_by_value(json_obj['vout'], Decimal('0.1'))
120        spending = (txid, n)
121
122        # Test /tx with an invalid and an unknown txid
123        resp = self.test_rest_request(uri=f"/tx/{INVALID_PARAM}", ret_type=RetType.OBJ, status=400)
124        assert_equal(resp.read().decode('utf-8').rstrip(), f"Invalid hash: {INVALID_PARAM}")
125        resp = self.test_rest_request(uri=f"/tx/{UNKNOWN_PARAM}", ret_type=RetType.OBJ, status=404)
126        assert_equal(resp.read().decode('utf-8').rstrip(), f"{UNKNOWN_PARAM} not found")
127
128        self.log.info("Query an unspent TXO using the /getutxos URI")
129
130        self.generate(self.wallet, 1)
131        bb_hash = self.nodes[0].getbestblockhash()
132
133        # Check chainTip response
134        json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}")
135        assert_equal(json_obj['chaintipHash'], bb_hash)
136
137        # Make sure there is one utxo
138        assert_equal(len(json_obj['utxos']), 1)
139        assert_equal(json_obj['utxos'][0]['value'], Decimal('0.1'))
140
141        self.log.info("Query a spent TXO using the /getutxos URI")
142
143        json_obj = self.test_rest_request(f"/getutxos/{spent[0]}-{spent[1]}")
144
145        # Check chainTip response
146        assert_equal(json_obj['chaintipHash'], bb_hash)
147
148        # Make sure there is no utxo in the response because this outpoint has been spent
149        assert_equal(len(json_obj['utxos']), 0)
150
151        # Check bitmap
152        assert_equal(json_obj['bitmap'], "0")
153
154        self.log.info("Query two TXOs using the /getutxos URI")
155
156        json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}/{spent[0]}-{spent[1]}")
157
158        assert_equal(len(json_obj['utxos']), 1)
159        assert_equal(json_obj['bitmap'], "10")
160
161        self.log.info("Query the TXOs using the /getutxos URI with a binary response")
162
163        bin_request = b'\x01\x02'
164        for txid, n in [spending, spent]:
165            bin_request += bytes.fromhex(txid)
166            bin_request += n.to_bytes(4, 'little')
167
168        bin_response = self.test_rest_request("/getutxos", http_method='POST', req_type=ReqType.BIN, body=bin_request, ret_type=RetType.BYTES)
169        chain_height = int.from_bytes(bin_response[0:4], 'little')
170        response_hash = bin_response[4:36][::-1].hex()
171
172        assert_equal(bb_hash, response_hash)  # check if getutxo's chaintip during calculation was fine
173        assert_equal(chain_height, 201)  # chain height must be 201 (pre-mined chain [200] + generated block [1])
174
175        self.log.info("Test the /getutxos URI with and without /checkmempool")
176        # Create a transaction, check that it's found with /checkmempool, but
177        # not found without. Then confirm the transaction and check that it's
178        # found with or without /checkmempool.
179
180        # do a tx and don't sync
181        txid = self.wallet.send_to(from_node=self.nodes[0], scriptPubKey=getnewdestination()[1], amount=int(0.1 * COIN))["txid"]
182        json_obj = self.test_rest_request(f"/tx/{txid}")
183        # get the spent output to later check for utxo (should be spent by then)
184        spent = (json_obj['vin'][0]['txid'], json_obj['vin'][0]['vout'])
185        # get n of 0.1 outpoint
186        n, = filter_output_indices_by_value(json_obj['vout'], Decimal('0.1'))
187        spending = (txid, n)
188
189        json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}")
190        assert_equal(len(json_obj['utxos']), 0)
191
192        json_obj = self.test_rest_request(f"/getutxos/checkmempool/{spending[0]}-{spending[1]}")
193        assert_equal(len(json_obj['utxos']), 1)
194
195        json_obj = self.test_rest_request(f"/getutxos/{spent[0]}-{spent[1]}")
196        assert_equal(len(json_obj['utxos']), 1)
197
198        json_obj = self.test_rest_request(f"/getutxos/checkmempool/{spent[0]}-{spent[1]}")
199        assert_equal(len(json_obj['utxos']), 0)
200
201        self.generate(self.nodes[0], 1)
202
203        json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}")
204        assert_equal(len(json_obj['utxos']), 1)
205
206        json_obj = self.test_rest_request(f"/getutxos/checkmempool/{spending[0]}-{spending[1]}")
207        assert_equal(len(json_obj['utxos']), 1)
208
209        self.log.info("Check some invalid requests")
210        self.test_rest_request("/getutxos", http_method='POST', req_type=ReqType.JSON, body='{"checkmempool', status=400, ret_type=RetType.OBJ)
211        self.test_rest_request("/getutxos", http_method='POST', req_type=ReqType.BIN, body='{"checkmempool', status=400, ret_type=RetType.OBJ)
212        self.test_rest_request("/getutxos/checkmempool", http_method='POST', req_type=ReqType.JSON, status=400, ret_type=RetType.OBJ)
213        self.test_rest_request(f"/getutxos/{spending[0]}_+1", ret_type=RetType.OBJ, status=400)
214        self.test_rest_request(f"/getutxos/{spending[0]}-+1", ret_type=RetType.OBJ, status=400)
215        self.test_rest_request(f"/getutxos/{spending[0]}--1", ret_type=RetType.OBJ, status=400)
216        self.test_rest_request(f"/getutxos/{spending[0]}aa-1234", ret_type=RetType.OBJ, status=400)
217        self.test_rest_request("/getutxos/aa-1234", ret_type=RetType.OBJ, status=400)
218
219        # Test limits
220        long_uri = '/'.join([f"{txid}-{n_}" for n_ in range(20)])
221        self.test_rest_request(f"/getutxos/checkmempool/{long_uri}", http_method='POST', status=400, ret_type=RetType.OBJ)
222
223        long_uri = '/'.join([f'{txid}-{n_}' for n_ in range(15)])
224        self.test_rest_request(f"/getutxos/checkmempool/{long_uri}", http_method='POST', status=200)
225
226        self.generate(self.nodes[0], 1)  # generate block to not affect upcoming tests
227
228        self.log.info("Test the /block, /blockhashbyheight, /headers, and /blockfilterheaders URIs")
229        bb_hash = self.nodes[0].getbestblockhash()
230
231        # Check result if block does not exists
232        assert_equal(self.test_rest_request(f"/headers/{UNKNOWN_PARAM}", query_params={"count": 1}), [])
233        self.test_rest_request(f"/block/{UNKNOWN_PARAM}", status=404, ret_type=RetType.OBJ)
234
235        # Check result if block is not in the active chain
236        self.nodes[0].invalidateblock(bb_hash)
237        assert_equal(self.test_rest_request(f'/headers/{bb_hash}', query_params={'count': 1}), [])
238        self.test_rest_request(f'/block/{bb_hash}')
239        self.nodes[0].reconsiderblock(bb_hash)
240
241        # Check binary format
242        response = self.test_rest_request(f"/block/{bb_hash}", req_type=ReqType.BIN, ret_type=RetType.OBJ)
243        assert_greater_than(int(response.getheader('content-length')), BLOCK_HEADER_SIZE)
244        response_bytes = response.read()
245
246        # Compare with block header
247        response_header = self.test_rest_request(f"/headers/{bb_hash}", req_type=ReqType.BIN, ret_type=RetType.OBJ, query_params={"count": 1})
248        assert_equal(int(response_header.getheader('content-length')), BLOCK_HEADER_SIZE)
249        response_header_bytes = response_header.read()
250        assert_equal(response_bytes[:BLOCK_HEADER_SIZE], response_header_bytes)

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.