interface_rest.py
1 #!/usr/bin/env python3 2 # Copyright (c) 2014-2022 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 7 from decimal import Decimal 8 from enum import Enum 9 import http.client 10 import json 11 import typing 12 import urllib.parse 13 14 15 from test_framework.messages import ( 16 BLOCK_HEADER_SIZE, 17 COIN, 18 ) 19 from test_framework.test_framework import BitcoinTestFramework 20 from test_framework.util import ( 21 assert_equal, 22 assert_greater_than, 23 assert_greater_than_or_equal, 24 ) 25 from test_framework.wallet import ( 26 MiniWallet, 27 getnewdestination, 28 ) 29 from typing import Optional 30 31 32 INVALID_PARAM = "abc" 33 UNKNOWN_PARAM = "0000000000000000000000000000000000000000000000000000000000000000" 34 35 36 class ReqType(Enum): 37 JSON = 1 38 BIN = 2 39 HEX = 3 40 41 class RetType(Enum): 42 OBJ = 1 43 BYTES = 2 44 JSON = 3 45 46 def filter_output_indices_by_value(vouts, value): 47 for vout in vouts: 48 if vout['value'] == value: 49 yield vout['n'] 50 51 class RESTTest (BitcoinTestFramework): 52 def set_test_params(self): 53 self.num_nodes = 2 54 self.extra_args = [["-rest", "-blockfilterindex=1"], []] 55 # whitelist peers to speed up tx relay / mempool sync 56 self.noban_tx_relay = True 57 self.supports_cli = False 58 59 def test_rest_request( 60 self, 61 uri: str, 62 http_method: str = 'GET', 63 req_type: ReqType = ReqType.JSON, 64 body: str = '', 65 status: int = 200, 66 ret_type: RetType = RetType.JSON, 67 query_params: Optional[dict[str, typing.Any]] = None, 68 ) -> typing.Union[http.client.HTTPResponse, bytes, str, None]: 69 rest_uri = '/rest' + uri 70 if req_type in ReqType: 71 rest_uri += f'.{req_type.name.lower()}' 72 if query_params: 73 rest_uri += f'?{urllib.parse.urlencode(query_params)}' 74 75 conn = http.client.HTTPConnection(self.url.hostname, self.url.port) 76 self.log.debug(f'{http_method} {rest_uri} {body}') 77 if http_method == 'GET': 78 conn.request('GET', rest_uri) 79 elif http_method == 'POST': 80 conn.request('POST', rest_uri, body) 81 resp = conn.getresponse() 82 83 assert_equal(resp.status, status) 84 85 if ret_type == RetType.OBJ: 86 return resp 87 elif ret_type == RetType.BYTES: 88 return resp.read() 89 elif ret_type == RetType.JSON: 90 return json.loads(resp.read().decode('utf-8'), parse_float=Decimal) 91 92 return None 93 94 def run_test(self): 95 self.url = urllib.parse.urlparse(self.nodes[0].url) 96 self.wallet = MiniWallet(self.nodes[0]) 97 98 self.log.info("Broadcast test transaction and sync nodes") 99 txid = self.wallet.send_to(from_node=self.nodes[0], scriptPubKey=getnewdestination()[1], amount=int(0.1 * COIN))["txid"] 100 self.sync_all() 101 102 self.log.info("Test the /tx URI") 103 104 json_obj = self.test_rest_request(f"/tx/{txid}") 105 assert_equal(json_obj['txid'], txid) 106 107 # Check hex format response 108 hex_response = self.test_rest_request(f"/tx/{txid}", req_type=ReqType.HEX, ret_type=RetType.OBJ) 109 assert_greater_than_or_equal(int(hex_response.getheader('content-length')), 110 json_obj['size']*2) 111 112 spent = (json_obj['vin'][0]['txid'], json_obj['vin'][0]['vout']) # get the vin to later check for utxo (should be spent by then) 113 # get n of 0.1 outpoint 114 n, = filter_output_indices_by_value(json_obj['vout'], Decimal('0.1')) 115 spending = (txid, n) 116 117 # Test /tx with an invalid and an unknown txid 118 resp = self.test_rest_request(uri=f"/tx/{INVALID_PARAM}", ret_type=RetType.OBJ, status=400) 119 assert_equal(resp.read().decode('utf-8').rstrip(), f"Invalid hash: {INVALID_PARAM}") 120 resp = self.test_rest_request(uri=f"/tx/{UNKNOWN_PARAM}", ret_type=RetType.OBJ, status=404) 121 assert_equal(resp.read().decode('utf-8').rstrip(), f"{UNKNOWN_PARAM} not found") 122 123 self.log.info("Query an unspent TXO using the /getutxos URI") 124 125 self.generate(self.wallet, 1) 126 bb_hash = self.nodes[0].getbestblockhash() 127 128 # Check chainTip response 129 json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}") 130 assert_equal(json_obj['chaintipHash'], bb_hash) 131 132 # Make sure there is one utxo 133 assert_equal(len(json_obj['utxos']), 1) 134 assert_equal(json_obj['utxos'][0]['value'], Decimal('0.1')) 135 136 self.log.info("Query a spent TXO using the /getutxos URI") 137 138 json_obj = self.test_rest_request(f"/getutxos/{spent[0]}-{spent[1]}") 139 140 # Check chainTip response 141 assert_equal(json_obj['chaintipHash'], bb_hash) 142 143 # Make sure there is no utxo in the response because this outpoint has been spent 144 assert_equal(len(json_obj['utxos']), 0) 145 146 # Check bitmap 147 assert_equal(json_obj['bitmap'], "0") 148 149 self.log.info("Query two TXOs using the /getutxos URI") 150 151 json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}/{spent[0]}-{spent[1]}") 152 153 assert_equal(len(json_obj['utxos']), 1) 154 assert_equal(json_obj['bitmap'], "10") 155 156 self.log.info("Query the TXOs using the /getutxos URI with a binary response") 157 158 bin_request = b'\x01\x02' 159 for txid, n in [spending, spent]: 160 bin_request += bytes.fromhex(txid) 161 bin_request += n.to_bytes(4, 'little') 162 163 bin_response = self.test_rest_request("/getutxos", http_method='POST', req_type=ReqType.BIN, body=bin_request, ret_type=RetType.BYTES) 164 chain_height = int.from_bytes(bin_response[0:4], 'little') 165 response_hash = bin_response[4:36][::-1].hex() 166 167 assert_equal(bb_hash, response_hash) # check if getutxo's chaintip during calculation was fine 168 assert_equal(chain_height, 201) # chain height must be 201 (pre-mined chain [200] + generated block [1]) 169 170 self.log.info("Test the /getutxos URI with and without /checkmempool") 171 # Create a transaction, check that it's found with /checkmempool, but 172 # not found without. Then confirm the transaction and check that it's 173 # found with or without /checkmempool. 174 175 # do a tx and don't sync 176 txid = self.wallet.send_to(from_node=self.nodes[0], scriptPubKey=getnewdestination()[1], amount=int(0.1 * COIN))["txid"] 177 json_obj = self.test_rest_request(f"/tx/{txid}") 178 # get the spent output to later check for utxo (should be spent by then) 179 spent = (json_obj['vin'][0]['txid'], json_obj['vin'][0]['vout']) 180 # get n of 0.1 outpoint 181 n, = filter_output_indices_by_value(json_obj['vout'], Decimal('0.1')) 182 spending = (txid, n) 183 184 json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}") 185 assert_equal(len(json_obj['utxos']), 0) 186 187 json_obj = self.test_rest_request(f"/getutxos/checkmempool/{spending[0]}-{spending[1]}") 188 assert_equal(len(json_obj['utxos']), 1) 189 190 json_obj = self.test_rest_request(f"/getutxos/{spent[0]}-{spent[1]}") 191 assert_equal(len(json_obj['utxos']), 1) 192 193 json_obj = self.test_rest_request(f"/getutxos/checkmempool/{spent[0]}-{spent[1]}") 194 assert_equal(len(json_obj['utxos']), 0) 195 196 self.generate(self.nodes[0], 1) 197 198 json_obj = self.test_rest_request(f"/getutxos/{spending[0]}-{spending[1]}") 199 assert_equal(len(json_obj['utxos']), 1) 200 201 json_obj = self.test_rest_request(f"/getutxos/checkmempool/{spending[0]}-{spending[1]}") 202 assert_equal(len(json_obj['utxos']), 1) 203 204 # Do some invalid requests 205 self.test_rest_request("/getutxos", http_method='POST', req_type=ReqType.JSON, body='{"checkmempool', status=400, ret_type=RetType.OBJ) 206 self.test_rest_request("/getutxos", http_method='POST', req_type=ReqType.BIN, body='{"checkmempool', status=400, ret_type=RetType.OBJ) 207 self.test_rest_request("/getutxos/checkmempool", http_method='POST', req_type=ReqType.JSON, status=400, ret_type=RetType.OBJ) 208 209 # Test limits 210 long_uri = '/'.join([f"{txid}-{n_}" for n_ in range(20)]) 211 self.test_rest_request(f"/getutxos/checkmempool/{long_uri}", http_method='POST', status=400, ret_type=RetType.OBJ) 212 213 long_uri = '/'.join([f'{txid}-{n_}' for n_ in range(15)]) 214 self.test_rest_request(f"/getutxos/checkmempool/{long_uri}", http_method='POST', status=200) 215 216 self.generate(self.nodes[0], 1) # generate block to not affect upcoming tests 217 218 self.log.info("Test the /block, /blockhashbyheight, /headers, and /blockfilterheaders URIs") 219 bb_hash = self.nodes[0].getbestblockhash() 220 221 # Check result if block does not exists 222 assert_equal(self.test_rest_request(f"/headers/{UNKNOWN_PARAM}", query_params={"count": 1}), []) 223 self.test_rest_request(f"/block/{UNKNOWN_PARAM}", status=404, ret_type=RetType.OBJ) 224 225 # Check result if block is not in the active chain 226 self.nodes[0].invalidateblock(bb_hash) 227 assert_equal(self.test_rest_request(f'/headers/{bb_hash}', query_params={'count': 1}), []) 228 self.test_rest_request(f'/block/{bb_hash}') 229 self.nodes[0].reconsiderblock(bb_hash) 230 231 # Check binary format 232 response = self.test_rest_request(f"/block/{bb_hash}", req_type=ReqType.BIN, ret_type=RetType.OBJ) 233 assert_greater_than(int(response.getheader('content-length')), BLOCK_HEADER_SIZE) 234 response_bytes = response.read() 235 236 # Compare with block header 237 response_header = self.test_rest_request(f"/headers/{bb_hash}", req_type=ReqType.BIN, ret_type=RetType.OBJ, query_params={"count": 1}) 238 assert_equal(int(response_header.getheader('content-length')), BLOCK_HEADER_SIZE) 239 response_header_bytes = response_header.read() 240 assert_equal(response_bytes[:BLOCK_HEADER_SIZE], response_header_bytes) 241 242 # Check block hex format 243 response_hex = self.test_rest_request(f"/block/{bb_hash}", req_type=ReqType.HEX, ret_type=RetType.OBJ) 244 assert_greater_than(int(response_hex.getheader('content-length')), BLOCK_HEADER_SIZE*2) 245 response_hex_bytes = response_hex.read().strip(b'\n') 246 assert_equal(response_bytes.hex().encode(), response_hex_bytes) 247 248 # Compare with hex block header 249 response_header_hex = self.test_rest_request(f"/headers/{bb_hash}", req_type=ReqType.HEX, ret_type=RetType.OBJ, query_params={"count": 1}) 250 assert_greater_than(int(response_header_hex.getheader('content-length')), BLOCK_HEADER_SIZE*2) 251 response_header_hex_bytes = response_header_hex.read(BLOCK_HEADER_SIZE*2) 252 assert_equal(response_bytes[:BLOCK_HEADER_SIZE].hex().encode(), response_header_hex_bytes) 253 254 # Check json format 255 block_json_obj = self.test_rest_request(f"/block/{bb_hash}") 256 assert_equal(block_json_obj['hash'], bb_hash) 257 assert_equal(self.test_rest_request(f"/blockhashbyheight/{block_json_obj['height']}")['blockhash'], bb_hash) 258 259 # Check hex/bin format 260 resp_hex = self.test_rest_request(f"/blockhashbyheight/{block_json_obj['height']}", req_type=ReqType.HEX, ret_type=RetType.OBJ) 261 assert_equal(resp_hex.read().decode('utf-8').rstrip(), bb_hash) 262 resp_bytes = self.test_rest_request(f"/blockhashbyheight/{block_json_obj['height']}", req_type=ReqType.BIN, ret_type=RetType.BYTES) 263 blockhash = resp_bytes[::-1].hex() 264 assert_equal(blockhash, bb_hash) 265 266 # Check invalid blockhashbyheight requests 267 resp = self.test_rest_request(f"/blockhashbyheight/{INVALID_PARAM}", ret_type=RetType.OBJ, status=400) 268 assert_equal(resp.read().decode('utf-8').rstrip(), f"Invalid height: {INVALID_PARAM}") 269 resp = self.test_rest_request("/blockhashbyheight/1000000", ret_type=RetType.OBJ, status=404) 270 assert_equal(resp.read().decode('utf-8').rstrip(), "Block height out of range") 271 resp = self.test_rest_request("/blockhashbyheight/-1", ret_type=RetType.OBJ, status=400) 272 assert_equal(resp.read().decode('utf-8').rstrip(), "Invalid height: -1") 273 self.test_rest_request("/blockhashbyheight/", ret_type=RetType.OBJ, status=400) 274 275 # Compare with json block header 276 json_obj = self.test_rest_request(f"/headers/{bb_hash}", query_params={"count": 1}) 277 assert_equal(len(json_obj), 1) # ensure that there is one header in the json response 278 assert_equal(json_obj[0]['hash'], bb_hash) # request/response hash should be the same 279 280 # Check invalid uri (% symbol at the end of the request) 281 for invalid_uri in [f"/headers/{bb_hash}%", f"/blockfilterheaders/basic/{bb_hash}%", "/mempool/contents.json?%"]: 282 resp = self.test_rest_request(invalid_uri, ret_type=RetType.OBJ, status=400) 283 assert_equal(resp.read().decode('utf-8').rstrip(), "URI parsing failed, it likely contained RFC 3986 invalid characters") 284 285 # Compare with normal RPC block response 286 rpc_block_json = self.nodes[0].getblock(bb_hash) 287 for key in ['hash', 'confirmations', 'height', 'version', 'merkleroot', 'time', 'nonce', 'bits', 'difficulty', 'chainwork', 'previousblockhash']: 288 assert_equal(json_obj[0][key], rpc_block_json[key]) 289 290 # See if we can get 5 headers in one response 291 self.generate(self.nodes[1], 5) 292 expected_filter = { 293 'basic block filter index': {'synced': True, 'best_block_height': 208}, 294 } 295 self.wait_until(lambda: self.nodes[0].getindexinfo() == expected_filter) 296 json_obj = self.test_rest_request(f"/headers/{bb_hash}", query_params={"count": 5}) 297 assert_equal(len(json_obj), 5) # now we should have 5 header objects 298 json_obj = self.test_rest_request(f"/blockfilterheaders/basic/{bb_hash}", query_params={"count": 5}) 299 first_filter_header = json_obj[0] 300 assert_equal(len(json_obj), 5) # now we should have 5 filter header objects 301 json_obj = self.test_rest_request(f"/blockfilter/basic/{bb_hash}") 302 303 # Compare with normal RPC blockfilter response 304 rpc_blockfilter = self.nodes[0].getblockfilter(bb_hash) 305 assert_equal(first_filter_header, rpc_blockfilter['header']) 306 assert_equal(json_obj['filter'], rpc_blockfilter['filter']) 307 308 # Test blockfilterheaders with an invalid hash and filtertype 309 resp = self.test_rest_request(f"/blockfilterheaders/{INVALID_PARAM}/{bb_hash}", ret_type=RetType.OBJ, status=400) 310 assert_equal(resp.read().decode('utf-8').rstrip(), f"Unknown filtertype {INVALID_PARAM}") 311 resp = self.test_rest_request(f"/blockfilterheaders/basic/{INVALID_PARAM}", ret_type=RetType.OBJ, status=400) 312 assert_equal(resp.read().decode('utf-8').rstrip(), f"Invalid hash: {INVALID_PARAM}") 313 314 # Test number parsing 315 for num in ['5a', '-5', '0', '2001', '99999999999999999999999999999999999']: 316 assert_equal( 317 bytes(f'Header count is invalid or out of acceptable range (1-2000): {num}\r\n', 'ascii'), 318 self.test_rest_request(f"/headers/{bb_hash}", ret_type=RetType.BYTES, status=400, query_params={"count": num}), 319 ) 320 321 self.log.info("Test tx inclusion in the /mempool and /block URIs") 322 323 # Make 3 chained txs and mine them on node 1 324 txs = [] 325 input_txid = txid 326 for _ in range(3): 327 utxo_to_spend = self.wallet.get_utxo(txid=input_txid) 328 txs.append(self.wallet.send_self_transfer(from_node=self.nodes[0], utxo_to_spend=utxo_to_spend)['txid']) 329 input_txid = txs[-1] 330 self.sync_all() 331 332 # Check that there are exactly 3 transactions in the TX memory pool before generating the block 333 json_obj = self.test_rest_request("/mempool/info") 334 assert_equal(json_obj['size'], 3) 335 # the size of the memory pool should be greater than 3x ~100 bytes 336 assert_greater_than(json_obj['bytes'], 300) 337 338 mempool_info = self.nodes[0].getmempoolinfo() 339 # pop unstable unbroadcastcount before check 340 for obj in [json_obj, mempool_info]: 341 obj.pop("unbroadcastcount") 342 assert_equal(json_obj, mempool_info) 343 344 # Check that there are our submitted transactions in the TX memory pool 345 json_obj = self.test_rest_request("/mempool/contents") 346 raw_mempool_verbose = self.nodes[0].getrawmempool(verbose=True) 347 348 assert_equal(json_obj, raw_mempool_verbose) 349 350 for i, tx in enumerate(txs): 351 assert tx in json_obj 352 assert_equal(json_obj[tx]['spentby'], txs[i + 1:i + 2]) 353 assert_equal(json_obj[tx]['depends'], txs[i - 1:i]) 354 355 # Check the mempool response for explicit parameters 356 json_obj = self.test_rest_request("/mempool/contents", query_params={"verbose": "true", "mempool_sequence": "false"}) 357 assert_equal(json_obj, raw_mempool_verbose) 358 359 # Check the mempool response for not verbose 360 json_obj = self.test_rest_request("/mempool/contents", query_params={"verbose": "false"}) 361 raw_mempool = self.nodes[0].getrawmempool(verbose=False) 362 363 assert_equal(json_obj, raw_mempool) 364 365 # Check the mempool response for sequence 366 json_obj = self.test_rest_request("/mempool/contents", query_params={"verbose": "false", "mempool_sequence": "true"}) 367 raw_mempool = self.nodes[0].getrawmempool(verbose=False, mempool_sequence=True) 368 369 assert_equal(json_obj, raw_mempool) 370 371 # Check for error response if verbose=true and mempool_sequence=true 372 resp = self.test_rest_request("/mempool/contents", ret_type=RetType.OBJ, status=400, query_params={"verbose": "true", "mempool_sequence": "true"}) 373 assert_equal(resp.read().decode('utf-8').strip(), 'Verbose results cannot contain mempool sequence values. (hint: set "verbose=false")') 374 375 # Check for error response if verbose is not "true" or "false" 376 resp = self.test_rest_request("/mempool/contents", ret_type=RetType.OBJ, status=400, query_params={"verbose": "TRUE"}) 377 assert_equal(resp.read().decode('utf-8').strip(), 'The "verbose" query parameter must be either "true" or "false".') 378 379 # Check for error response if mempool_sequence is not "true" or "false" 380 resp = self.test_rest_request("/mempool/contents", ret_type=RetType.OBJ, status=400, query_params={"verbose": "false", "mempool_sequence": "TRUE"}) 381 assert_equal(resp.read().decode('utf-8').strip(), 'The "mempool_sequence" query parameter must be either "true" or "false".') 382 383 # Now mine the transactions 384 newblockhash = self.generate(self.nodes[1], 1) 385 386 # Check if the 3 tx show up in the new block 387 json_obj = self.test_rest_request(f"/block/{newblockhash[0]}") 388 non_coinbase_txs = {tx['txid'] for tx in json_obj['tx'] 389 if 'coinbase' not in tx['vin'][0]} 390 assert_equal(non_coinbase_txs, set(txs)) 391 392 # Verify that the non-coinbase tx has "prevout" key set 393 for tx_obj in json_obj["tx"]: 394 for vin in tx_obj["vin"]: 395 if "coinbase" not in vin: 396 assert "prevout" in vin 397 assert_equal(vin["prevout"]["generated"], False) 398 else: 399 assert "prevout" not in vin 400 401 # Check the same but without tx details 402 json_obj = self.test_rest_request(f"/block/notxdetails/{newblockhash[0]}") 403 for tx in txs: 404 assert tx in json_obj['tx'] 405 406 self.log.info("Test the /chaininfo URI") 407 408 bb_hash = self.nodes[0].getbestblockhash() 409 410 json_obj = self.test_rest_request("/chaininfo") 411 assert_equal(json_obj['bestblockhash'], bb_hash) 412 413 # Compare with normal RPC getblockchaininfo response 414 blockchain_info = self.nodes[0].getblockchaininfo() 415 assert_equal(blockchain_info, json_obj) 416 417 # Test compatibility of deprecated and newer endpoints 418 self.log.info("Test compatibility of deprecated and newer endpoints") 419 assert_equal(self.test_rest_request(f"/headers/{bb_hash}", query_params={"count": 1}), self.test_rest_request(f"/headers/1/{bb_hash}")) 420 assert_equal(self.test_rest_request(f"/blockfilterheaders/basic/{bb_hash}", query_params={"count": 1}), self.test_rest_request(f"/blockfilterheaders/basic/5/{bb_hash}")) 421 422 self.log.info("Test the /deploymentinfo URI") 423 424 deployment_info = self.nodes[0].getdeploymentinfo() 425 assert_equal(deployment_info, self.test_rest_request('/deploymentinfo')) 426 427 previous_bb_hash = self.nodes[0].getblockhash(self.nodes[0].getblockcount() - 1) 428 deployment_info = self.nodes[0].getdeploymentinfo(previous_bb_hash) 429 assert_equal(deployment_info, self.test_rest_request(f"/deploymentinfo/{previous_bb_hash}")) 430 431 non_existing_blockhash = '42759cde25462784395a337460bde75f58e73d3f08bd31fdc3507cbac856a2c4' 432 resp = self.test_rest_request(f'/deploymentinfo/{non_existing_blockhash}', ret_type=RetType.OBJ, status=400) 433 assert_equal(resp.read().decode('utf-8').rstrip(), "Block not found") 434 435 resp = self.test_rest_request(f"/deploymentinfo/{INVALID_PARAM}", ret_type=RetType.OBJ, status=400) 436 assert_equal(resp.read().decode('utf-8').rstrip(), f"Invalid hash: {INVALID_PARAM}") 437 438 if __name__ == '__main__': 439 RESTTest().main()