Bitcoin Core REST 接口全解：无认证 HTTP API、缓存策略与源码实现剖析

Bitcoin Core REST 接口全解无认证 HTTP API、缓存策略与源码实现剖析【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本文以 Bitcoin Core 官方的 REST 接口文档为主体系统讲解如何通过-rest选项启用无认证 HTTP 接口覆盖全部受支持的端点交易、区块、区块头、过滤器、UTXO 查询、内存池等、默认 HTTP 缓存策略及安全风险提示并结合src/rest.cpp的源码实现与功能测试用例说明每个端点背后的数据访问路径与参数约束帮助读者安全、高效地以编程方式查询节点数据。启用 REST 接口与默认端口REST API 通过命令行/配置选项-rest启用对应源码 src/init.cpp#L741 中注册的参数默认值为关闭bitcoind -rest1接口运行在与 JSON-RPC 接口相同的端口上默认端口因网络而异网络REST/RPC 默认端口mainnet8332testnet18332testnet448332signet38332regtest18443需要注意的是该接口是无认证unauthenticated的——文档标题即明确写出 Unauthenticated REST Interface。因此它必须只暴露在可信网络内例如仅监听127.0.0.1这一点在源码中也有体现REST 处理器通过RegisterHTTPHandler(prefix, /*allow_running*/false, handler)注册其中第二个参数false表示不要求rpcallowip/认证凭据见 src/rest.cpp#L1178-L1196 的uri_prefixes路由表。节点启动时由StartREST()批量注册所有/rest/*前缀路由src/init.cpp#L795停止时StopREST()再逐一注销。一致性保证REST 接口与 JSON-RPC 接口 享有相同的一致性保证对应文档中的 RPC consistency guarantees 章节见 doc/JSON-RPC-interface.md#L191通过 RPC含 REST查询到的链状态保证至少与调用执行之前的链状态一致但反映 mempool 的接口如/rest/tx、/rest/mempool/*返回的状态可能与调用时刻的实时 mempool 略有滞后。默认 HTTP 缓存策略官方文档明确定义了各端点响应头中默认的Cache-Control值。在源码中对应两个常量src/rest.cpp#L47-L51/** Response bytes never change. One-day TTL limits staleness across software upgrades. */ static constexpr const char* REST_CACHE_IMMUTABLE public, immutable, max-age86400; /** Mutable, node-local, or error response; must not be cached. */ static constexpr const char* REST_CACHE_NO_STORE no-store;端点格式Cache-Control/block、/block/notxdetailsbin / hexpublic, immutable, max-age86400/blockpartbin / hexpublic, immutable, max-age86400/blockfilter、/spenttxouts全部格式public, immutable, max-age86400/deploymentinfo/BLOCKHASH.jsonjsonpublic, immutable, max-age86400/block、/block/notxdetailsJSONno-store/tx、/headers、/blockfilterheaders、/blockhashbyheight全部格式no-store/chaininfo、/mempool、/getutxos、/deploymentinfo.json全部格式no-store所有错误响应—no-store见 src/rest.cpp#L77-L83 的RESTERR设计考量区块的 bin/hex 字节流一旦落盘即不可变因此可以安全地长缓存文档特别指出 TTL 刻意只给一天86400 秒是为了避免缓存在软件升级后长期持有旧版本的响应格式JSON 形式的/block、mempool 类、错误响应等可能随链或节点状态变化且当前不提供ETag/Last-Modified等缓存验证器因此一律no-store若你用 Caddy、nginx配 headers-more 模块等反向代理或 CDN 前置 bitcoind可以在代理层覆盖这些默认值——但文档提醒只对你确定可以更激进缓存的响应做覆盖。受支持的 API 端点以下按文档结构完整列出各端点并结合 src/rest.cpp 的实现补充行为细节。所有端点均支持bin二进制、hex十六进制编码的二进制、json三种后缀格式部分端点除外格式由 URI 最后一个.后缀解析ParseDataFormatsrc/rest.cpp#L136-L159查询字符串在解析前会被剥离不会干扰格式识别。交易TransactionsGET /rest/tx/TX-HASH.bin|hex|json给定交易哈希返回二进制、十六进制或 JSON 格式的交易交易不存在时返回404。默认只搜索内存池。要查询已确认交易必须开启交易索引txindex1命令行/配置项。源码印证src/rest.cpp#L866-L925rest_tx中若g_txindex存在会先BlockUntilSyncedToCurrentChain()等待索引同步然后调用node::GetTransaction依次查 mempool 与 txindexbin/hex 输出使用带 witness 的序列化格式TX_WITH_WITNESS。区块BlocksGET /rest/block/BLOCK-HASH.bin|hex|json GET /rest/block/notxdetails/BLOCK-HASH.bin|hex|json给定区块哈希返回整块区块不存在时返回404。HTTP 请求与响应完全在内存中处理in-memory即整块读入内存再整体返回不适合超大带宽场景/notxdetails/变体的 JSON 响应只包含每笔交易的哈希而非完整交易明细——该选项只影响 JSON 格式bin/hex 与完整区块完全相同。源码中二者共用rest_block()核心src/rest.cpp#L403-L496通过TxVerbosity参数区分rest_block_extended传SHOW_DETAILS_AND_PREVOUT含输入 prevout 详情rest_block_notxdetails传SHOW_TXID。另外若请求的是已被修剪pruned或尚未完整下载的区块rest_block会返回 404 并分别附带not available (pruned data)/not available (not fully downloaded)提示src/rest.cpp#L432-L437。区块分片Block partGET /rest/blockpart/BLOCK-HASH.bin|hex?offsetOFFSETsizeSIZE返回区块的指定字节范围分片仅支持 bin/hex 两种格式区块或字节范围不存在时返回404范围非法时返回 400。查询参数解析见rest_block_partsrc/rest.cpp#L498-L515底层通过ReadRawBlock(pos, block_part)只读取指定区间。该端点适合做流式/分块下载避免一次性把整块载入内存。区块头BlockheadersGET /rest/headers/BLOCK-HASH.bin|hex|json?countCOUNT5给定区块哈希沿向上方向向链尖方向返回COUNT个区块头默认 5 个。若区块不存在或不在活跃链上返回空响应而非 404。count的取值范围由常量MAX_REST_HEADERS_RESULTS 2000限制src/rest.cpp#L45越界或非数字返回 400实现上在cs_main锁内从LookupBlockIndex出发沿active_chain.Next()向上收集src/rest.cpp#L224-L242——这解释了为什么不在活跃链上的区块会得到空结果24.0 起旧路径GET /rest/headers/COUNT/BLOCK-HASH.bin|hex|json已废弃但未被移除仍兼容。区块过滤器头Blockfilter HeadersGET /rest/blockfilterheaders/FILTERTYPE/BLOCK-HASH.bin|hex|json?countCOUNT5给定区块哈希为指定过滤器类型FILTERTYPE沿向上方向返回COUNT个过滤器头默认 5区块不存在或不在活跃链上时返回空。前提对应的过滤器索引必须已启用例如basic类型需要blockfilterindexbasic否则返回 400Index is not enabled for filtertype ...src/rest.cpp#L558-L561若索引尚未追上当前链错误信息会明确提示 Block filters are still in the process of being indexed同样保留 24.0 前的废弃路径GET /rest/blockfilterheaders/FILTERTYPE/COUNT/BLOCK-HASH.bin|hex|json。区块过滤器BlockfiltersGET /rest/blockfilter/FILTERTYPE/BLOCK-HASH.bin|hex|json返回指定区块、指定类型的区块过滤器BIP157 风格区块不存在返回404。JSON 响应形如{filter: hex}src/rest.cpp#L722-L730。按高度查区块哈希Blockhash by heightGET /rest/blockhashbyheight/HEIGHT.bin|hex|json给定高度返回**主链best-block-chain**上该高度区块的哈希找不到高度超出链尖返回404Block height out of range。JSON 响应为{blockhash: ...}。注意重组织可能改变该高度对应的哈希因此该端点所有格式均为no-storesrc/rest.cpp#L1148-L1156 中的注释 Do not cache because reorgs can change the response。已花费的交易输出Spent transaction outputsGET /rest/spenttxouts/BLOCK-HASH.bin|hex|json给定区块哈希返回按区块内每笔交易分组的被花费输出列表——数据来源于该区块的 undo 数据。区块不存在或 undo 数据不可用如已被修剪时返回404src/rest.cpp#L351-L359。bin/hex 格式下按SerializeBlockUndo序列化先写出交易数第一笔为 coinbase 占位随后每笔交易写出其花费的 prevout 数量与各CTxOutsrc/rest.cpp#L290-L300JSON 格式下每个 prevout 含valueBTC 单位与scriptPubKey含 asm/hex/address 等见 src/rest.cpp#L305-L322该端点属于不可变数据三种格式均标记为immutable, max-age86400可放心交给代理缓存。链信息ChaininfosGET /rest/chaininfo.json返回关于区块链处理的各种状态信息仅支持 JSON。字段与getblockchaininfoRPC 完全一致——实现上直接调用 RPC 处理函数getblockchaininfo().HandleRequest(...)src/rest.cpp#L740-L763因此文档提示参考getblockchaininfoRPC 的帮助信息。共识部署信息Deployment infoGET /rest/deploymentinfo.json GET /rest/deploymentinfo/BLOCKHASH.json返回关于共识规则部署如 Taproot、Minimal Difficulty 等软分叉激活状态的对象字段参考getdeploymentinfoRPC 的帮助。不带块哈希时查询当前链尖no-store带BLOCKHASH时查询历史某块其响应字节不可变标记为immutable, max-age86400src/rest.cpp#L797。仅支持 JSON。UTXO 集查询Query UTXO setGET /rest/getutxos/TXID-N/TXID-N/.../TXID-N.bin|hex|json GET /rest/getutxos/checkmempool/TXID-N/TXID-N/.../TXID-N.bin|hex|jsongetutxos端点按一组 outpoint交易ID-输出序号以-分隔、/连接多个查询 UTXO 集加/checkmempool/前缀时还会考虑内存池中的交易即被 mempool 交易标记为花费的 outpoint 会被视为不存在。bin/hex输出格式的输入输出序列化遵循 BIP 0064 的定义。关键限制源码可见单次最多 15 个 outpoint常量MAX_GETUTXOS_OUTPOINTS 15src/rest.cpp#L44超限返回 400Error: max outpoints exceeded (max: 15, tried: N)响应中的bitmap字符串JSON 里的1/0序列逐位标记每个请求的 outpoint 是否命中除了 URI 方式传 outpointbin/hex还允许把输入直接放在 HTTP 请求体里hex 会先转成 bin 再处理但URI 输入与原始请求体不能混用否则 400src/rest.cpp#L988-L1004。文档给出的完整示例testnet 节点json_pp为美化输出$ curl localhost:18332/rest/getutxos/checkmempool/b2cdfd7b89def827ff8af7cd9bff7627ff72e5e8b0f71210f92ea7a4000c5d75-0.json 2/dev/null | json_pp { chainHeight : 325347, chaintipHash : 00000000fb01a7f3745a717f8caebee056c484e6e0bfe4a9591c235bb70506fb, bitmap: 1, utxos : [ { height : 2147483647, value : 8.8687, scriptPubKey : { asm : OP_DUP OP_HASH160 1c7cebb529b86a04c683dfa87be49de35bcf589e OP_EQUALVERIFY OP_CHECKSIG, desc : addr(mi7as51dvLJsizWnTMurtRmrP8hG2m1XvD)#gj9tznmy, hex : 76a9141c7cebb529b86a04c683dfa87be49de35bcf589e88ac, type : pubkeyhash, address : mi7as51dvLJsizWnTMurtRmrP8hG2m1XvD } } ] }注意height: 21474836470x7FFFFFFF是 coinbase 输出的特殊高度标记。内存池Memory poolGET /rest/mempool/info.json返回关于交易内存池的各种信息仅支持 JSON字段参考getmempoolinfoRPC 帮助。GET /rest/mempool/contents.json?verbosetrue|falsemempool_sequencefalse|true返回内存池中的交易仅支持 JSON字段参考getrawmempoolRPC 帮助。默认verbosetrue、mempool_sequencefalse这两个查询参数自 25.0 版本起可用更早版本只能拿到默认详情的交易列表。源码实现rest_mempoolsrc/rest.cpp#L809-L864中还能看到参数校验细节verbose与mempool_sequence必须为字符串true/false否则 400二者不能同时为 true报错信息直接提示Verbose results cannot contain mempool sequence values. (hint: set verbosefalse)底层分别复用MempoolToJSON与MempoolInfoToJSON与对应 RPC 共享同一套序列化逻辑。安全风险XSS 与无认证访问文档在 Risks 一节明确警告在与开启了 REST 的 bitcoind 相同的机器上运行浏览器是有风险的。访问构造了 XSS 的恶意网站后页面可以通过形如script srchttp://127.0.0.1:8332/rest/tx/1234567890.json的链接读取该节点的交易/区块数据从而破坏节点的隐私例如泄露你正在查询哪些交易/区块。结合无认证这一设计事实实际部署时的最小防护建议是让 RPC/REST 端口只绑定回环地址rpcbind127.0.0.1且不加公网监听REST 只供本机程序使用确需远程访问时放在反向代理之后并自行加上认证/限流同时按前述代理覆盖缓存的提醒谨慎设置缓存头不暴露给公网时不要在同一机器上用日常浏览器访问不受信任的网页。功能测试如何验证 REST 行为仓库内置的功能测试 test/functional/interface_rest.py 覆盖了上述端点的端到端验证可作为行为基准。测试类RESTTest继承BitcoinTestFramework中的核心辅助方法test_rest_request会以ReqTypeGET/POST与RetTypebin/hex/json枚举组合发起请求并对照getblock、getrawmempool、getblockchaininfo、getdeploymentinfo等 RPC 结果断言一致性还包括通过invalidateblock/reconsiderblock触发重组验证/rest/headers在链变化下的行为等待basic block filter index同步后再请求/rest/blockfilterheaders与/rest/blockfilter并与getblockfilterRPC 比对用真实blk*.dat文件校验/rest/blockpart分片与原始字节一致验证/rest/mempool/contents.json在verbose、mempool_sequence组合下与getrawmempool输出一致。如果你要确认某个端点的输出格式细节阅读该测试文件是最快的实证途径配合bitcoin-cli help 对应RPC名查看 JSON 字段含义。总结主题要点启用-rest1默认关闭与 JSON-RPC 同端口mainnet 8332 / regtest 18443 等认证无认证务必限制网络暴露面防 XSS/本机读取风险格式bin/hex/json后缀由 URI 最后一个.解析缓存不可变数据区块 bin/hex、blockpart、blockfilter、spenttxouts、历史 deploymentinfoimmutable, max-age86400可变数据与错误一律no-store关键限制headers/count ≤ 2000getutxos ≤ 15 个 outpointblockpart 不支持 JSONmempool 查询参数需 25.0依赖索引/rest/tx查已确认交易需txindex1/rest/blockfilter*需对应blockfilterindex实现位置路由表与处理器全部在 src/rest.cpp格式解析在 src/rest.h端到端验证test/functional/interface_rest.py以这篇文档和src/rest.cpp为参照你可以把 bitcoind 当作一个带缓存语义的数据源集成进自己的工具链用 bin/hex 拉取不可变的区块数据并交给 CDN 缓存用 JSON 端点做链状态监控同时牢记无认证接口只能在内网使用的安全边界。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考