Bitcoin Core 28.0 发布说明全解读：Testnet4、JSON-RPC 2.0、TRUC 与 P2A 内存池新政

本篇技术指南以仓库内 release-notes-28.0.md 为骨架，系统梳理 Bitcoin Core 28.0 引入的共识与网络层变更（Testnet4/BIP94、TRUC/BIP431、P2A、包中继）、JSON-RPC 2.0 支持、钱包与 RPC 能力升级，并结合当前仓库源码逐一佐证。读完你将对 28.0 版本的升级路径、关键配置参数（-testnet4、-mempoolfullrbf、bind=…=onion、-blocksxor 等）以及它们背后的源码实现形成完整把握。需说明：本文所述的 28.0 为历史发布版本（当前仓库 master 分支版本标识已为 31.99.0，见 CMakeLists.txt），但绝大多数特性在现行代码中仍可找到对应实现，文中将同步标注源码路径。

版本概览与升级指引

Bitcoin Core 28.0 是一次包含新特性、各类缺陷修复与性能提升的功能性发布，同时更新了多语言翻译。按文档口径，发布二进制可从 bitcoincore.org 官方发布目录获取；遇到缺陷应在官方 issue 跟踪器反馈；安全与更新通知可通过官方公告订阅。

升级步骤与数据目录兼容

若你正运行更早版本，标准升级流程如下：

1. 先彻底关闭旧版本节点进程；
2. 等待其完全退出（部分场景可能需要数分钟，例如回写未落盘的数据库状态）；
3. Windows 上直接运行安装程序；macOS 上整体覆盖 /Applications/Bitcoin-Qt；Linux 上覆盖 bitcoind / bitcoin-qt 可执行文件。

文档特别说明：

• 从已到达 EOL（生命周期结束）的旧版本直接升级是可行的，但当数据目录需要迁移时可能耗时较长；
• 早期版本的钱包（wallet）一般仍被支持，升级不会强制要求立即迁移钱包格式。

macOS 运行前的自签名处理

在 macOS 上运行从官方渠道下载的 Bitcoin Core 二进制前，需要移除隔离属性（quarantine）并执行本地 ad-hoc 自签名，否则系统会拦截未公证的应用。文档给出如下命令（在解包后的 bin 目录内执行）：

cd /path/to/bitcoin-28.0/bin
xattr -d com.apple.quarantine bitcoin-cli bitcoin-qt bitcoin-tx bitcoin-util bitcoin-wallet bitcoind test_bitcoin
codesign -s - bitcoin-cli bitcoin-qt bitcoin-tx bitcoin-util bitcoin-wallet bitcoind test_bitcoin

第一行针对每个可执行文件清除「来自互联网」的隔离扩展属性；第二行以空签名身份（-s -）对全部二进制执行本地签名，使其在本地得以运行。文件清单覆盖了该版本发布的所有 CLI/GUI/工具与单元测试二进制。

操作系统兼容性边界

• 官方支持并经过充分测试的系统：Linux Kernel 3.17+、macOS 11.0+、Windows 7 及以上；
• 其他类 UNIX 系统大概率可用，但测试频率较低；
• 不建议在不支持的系统上运行 Bitcoin Core。

Testnet4 与 BIP94 支持

28.0 最大的网络层新增是按 BIP94 规范实现 Testnet4，这是继被长期使用的 Testnet3 之后新一代公开测试网络。核心变化包括：

• 新增 -testnet4 启动选项用于选择该网络，其配置节（section header）命名为 [testnet4]；
• Testnet4 内建了 BIP94 的 timewarp 攻击缓解规则（限制时间偏移的难度调整逻辑）；
• Testnet3 在本版本中仍可用，但官方意图是在后续版本中逐步淘汰 Testnet3。

源码佐证

• 网络类型到配置节/默认端口的映射定义在 chainparamsbase.cpp：-testnet（等义 -chain=test，对应 RPC 默认端口 18332）的说明已直接标注“deprecated and will be removed in an upcoming release”，并提示改用 -testnet4；-testnet4（等义 -chain=testnet4）对应默认 RPC 端口 48332；
• Testnet4 的完整链参数（创世、DNS 种子、消息头、共识参数等）以 CTestNet4Params 形式定义于 kernel/chainparams.cpp，并通过 CChainParams::TestNet4() 工厂构造（同文件 L684）；
• 对应的矿工/时间戳测试见 src/test/testnet4_miner_tests.cpp（PR #30681 进一步把 BIP94 缓解在 regtest 上启用）。

实践提示：需要隔离的公开测试环境时应优先迁移到 -testnet4，RPC 端口规划、区块浏览器与工具链请以 48332 及 Testnet4 主网上首个激活区块为准。

JSON-RPC 2.0 支持

28.0 起，JSON-RPC 服务器能够识别 JSON-RPC 2.0 请求，并严格按照 2.0 规范应答（#27101）。原先默认采用的 JSON-RPC 1.1 行为仍是兼容基础，两种风格的差异与字段规则在仓库内文档 JSON-RPC-interface.md 中设有专门小节“JSON-RPC 1.1 vs 2.0”，是迁移客户端时的必读参照。

对客户端的影响与注意事项：

• JSON-RPC 客户端可能需要更新才能与服务器兼容——2.0 对 id、jsonrpc 字段、错误对象（code/message/data）以及通知（无 id 的请求）的语义更严格；
• 若在使用中遇到兼容性问题，官方建议通过 issue 反馈，以便在后续版本中修复。

从实现角度看，RPC 服务器代码位于 src/httprpc.cpp 与 src/rpc/request.cpp，28.0 的改动集中在请求解析与响应序列化层，这也是为什么它属于“服务器行为”变更而非某个具体业务 RPC 的变更。

Windows 默认数据目录迁移

在 Windows 上，默认数据目录由旧的 C:\Users\<用户名>\AppData\Roaming\Bitcoin 迁移到 C:\Users\<用户名>\AppData\Local\Bitcoin（#27064）。这一改动使 Bitcoin Core 遵循 Windows 上“应用数据文件应放 Local”的惯例，并规避 Roaming 目录在域漫游/同步时带来的性能与隐私问题。

兼容策略非常关键：节点启动时会先检查旧目录是否存在；若旧目录存在，则继续使用旧目录以保证向后兼容。因此：

• 全新安装的节点将直接使用新的 Local 目录；
• 已有旧目录的用户升级后行为不变，不会出现“找不到数据”的情况；
• 迁移数据目录时可手动移动旧目录内容，并删除空旧目录以启用新位置。

libbitcoinconsensus 移除

libbitcoin-consensus 动态库曾在 27.0 中标记弃用，28.0 起被彻底移除（#29648）。这意味着：

• 依赖该库做“链上验证”（把 Bitcoin Core 的共识逻辑链入第三方程序）的外部软件需要寻找替代方案——例如改用位权验证独立实现、或调用节点的 verifychain / 通过 RPC 间接完成验证；
• 构建产物中不再包含该目标，相关头文件安装项一并去除。

P2P 与网络层变更

bind 行为修正：不再隐式监听 Tor 端口

此前只要节点以默认设置或 bind=addr:port 形式监听 P2P 连接，就总会额外绑定 127.0.0.1:8334 用于接收 Tor（onion）连接，即使节点根本不用 Tor 也无法关闭。28.0 改变该行为（#22729）：

• 现在 bind=addr:port 只绑定所指定的地址；
• 默认行为（无任何 bind 时绑定 0.0.0.0:8333 与 127.0.0.1:8334）保持不变；
• 若你使用了 bind=... 但未写 bind=...=onion，又依赖旧行为在 8334 接收入站 Tor 连接，则必须显式声明：

bind=<你的外部地址>:<端口> bind=127.0.0.1:8334=onion

即用 =<network> 后缀把 8334 明确标记为 onion 专用监听口。

任一 P2P bind 失败即启动失败

同一 PR 还强化了启动健壮性：此前只有当全部 P2P bind 都失败时才中止启动；现在只要任一 P2P bind 失败，Bitcoin Core 就会拒绝启动。这避免了“部分网卡/端口不可用但进程带病运行”的隐蔽状态，也意味着配置监听端口前应确认端口未被占用、地址可用。

代理与 ZMQ 支持 UNIX domain socket

• 代理连接：-onion 与 -proxy 现在接受以 unix: 为前缀的本地 socket 路径，例如：

-onion=unix:/home/me/torsocket

• ZMQ 发布通道同样接受 UNIX socket 路径，例如：

-zmqpubrawtx=unix:/path/to/file

-zmqpubrawblock 与 -zmqpubrawtx 均可如此配置（#27375、#27679）。这让节点可以与同机上的 Tor 守护进程、ZMQ 订阅者走文件系统 socket，绕开 TCP 环回口的占用与 ACL 管理成本。相关地址解析逻辑可参考 src/zmq/zmqpublishnotifier.cpp 与 src/netbase.cpp 中的 unix: 前缀处理。

whitelist 新增 in/out 标记

-whitelist 此前会把权限应用于所有入站连接。28.0 新增 in 与 out 两个修饰标记（#27114），用于控制权限只对入站连接（inbound）或只对手动发起的连接（manual outbound）生效，默认仍为仅入站。例如把某个网段仅作为出站白名单时可按需写成 -whitelist=out=1.2.3.0/24（具体语法以 bitcoind -help 中该选项说明为准）。网络权限解析见 src/net_permissions.cpp。

1 父 1 子的机会型包提交（package relay 前奏）

费率过低、低于内存池最低费率（minimum feerate）的交易会被“机会主义”地与它的子交易配对成一个包提交，从而让节点借由现有交易中继协议下载 1-parent-1-child（1p1c）包（#28970）。结合其他内存池策略，这实现了受限的包中继能力——父交易可以低于内存池最低费率被接受；若父交易是 TRUC（拓扑受限至确认）交易，还允许低于最低中继费率（即支付 0 手续费）。

• 节点直接提交包请用 submitpackage RPC；
• 警告：该 P2P 特性是受限的——不同于 submitpackage 接口，一个子交易带有多个未确认父交易的包不支持；且在对抗性条件下尚不可靠。

Mempool 策略变更

标准交易层面开放 TRUC（v3 交易 / BIP431）

版本号设为 3 的交易现已在所有网络上被认定为标准交易（#29496），并适用可选的 Topologically Restricted Until Confirmation（TRUC） 交易策略（对应 BIP 431）。策略细节包括：

• 限制花费未确认输出（#28948）——TRUC 交易的未确认祖先/后代集合都被限制在 2 个以内（1 父 1 子）；
• 若提交了激励相容性更高的后代，将逐出之前的后代（#29306）；
• 最大交易体积限制为 10,000 vB（#29873）；
• 这些限制简化了“接受或替换 TRUC 交易是否激励相容”的评估，保证任何替换都对节点更有利，并使 fee-bumping（加价）更可靠。

源码佐证：完整策略实现在 src/policy/truc_policy.h 与 src/policy/truc_policy.cpp。头文件顶部即定义：

• TRUC_VERSION{3}：v3 即 TRUC 的判定依据；
• TRUC_ANCESTOR_LIMIT{2} / TRUC_DESCENDANT_LIMIT{2}：未确认祖先/后代集合各不超过 2；
• TRUC_MAX_VSIZE{10'000}（换算成 weight 即文档所述 10,000 vB 上限）与 TRUC_CHILD_MAX_VSIZE{1000}（花费未确认 TRUC 输出的子交易体积限制）。

其规则注释明确列出 6 项检查（TRUC 只能有 TRUC 祖先、非 TRUC 只能有非 TRUC 祖先、祖先/后代集合规模、子交易体积与总体积上限等），是本变更的权威说明。

Pay To Anchor（P2A）新标准输出模板

P2A 是新的标准见证输出类型，用于无密钥的 anchor 输出（#30352）：相对等价的 sh(OP_TRUE) 输出，它的花费条件更紧凑、效率更高，同时保留花费交易 txid 的稳定性——非常适合 CPFP fee-bumping 场景（先在锚点输出放一笔小额可花费输出，再让其子交易为双方加价）。

注意事项：P2A 输出花费在网络上传播范围有限，直到足够多的节点升级采用该模板。相关判定函数 IsPayToAnchor 被 mempool 与标准策略引用，见 src/policy/policy.cpp 中关于 anchor 输出（IsPayToAnchor）的检查点。

有限 Package RBF

28.0 启用了受限的包 RBF（#28984）：仅当“提议冲突的包”在内存池中会构成大小为 2 的连通分量（cluster，即父子对）时才允许；所有被冲突的 cluster 规模也须为 2 或更小。这是向 cluster mempool 演进前对 RBF 语义的一次收敛。

-mempoolfullrbf 默认开启

-mempoolfullrbf 的默认值由 0 改为 1（即 mempoolfullrbf=1，#30493）。这意味着默认情况下，内存池接受未设置 BIP125 可替换标志（replaceability signaling）的交易的 RBF 替换——俗称 full-RBF。需要旧行为（仅接受显式 signal 的替换）的用户可显式配置 -mempoolfullrbf=0。（该参数在 28.0 之后的版本已进一步演化为默认行为并可能被废弃，详见仓库中后续 release notes 的说明。）

更新的 RPC

dumptxoutset / loadtxoutset：UTXO 集转储新格式

• dumptxoutset 现在输出新的、改进的 UTXO 集转储格式；loadtxoutset 只接受该新格式（#29612）；
• 旧格式转储文件不再受支持，需要以新格式重新生成后才能加载；
• 新格式与当前源码中的序列化实现对应（dump 逻辑见 src/rpc/blockchain.cpp 中 dumptxoutset 注册段及 src/kernel/chainparams.cpp 提供的可用快照高度列表）。

AssumeUTXO 主网参数：高度 840,000

为主网新增了高度 840,000 的 AssumeUTXO 参数（#28553）。这使得 loadtxoutset 可以在主网配合该高度的匹配 UTXO 集使用——即实现极速同步（先加载官方认可的历史 UTXO 快照，再在后台验证与补齐区块）。对 28.0 用户而言，主网全节点同步不再必须从创世块逐块验证 UTXO。

getblockchaininfo/getmininginfo/getnetworkinfo：warnings 变为数组

这三个 RPC 的 warnings 字段现在返回所有活跃节点告警组成的字符串数组，而非单一告警（#29845）。若需临时恢复旧行为，可用配置项：

-deprecatedrpc=warnings

sendrawtransaction 错误消息精确化

当通过 sendrawtransaction 提交一笔输出已存在于 UTXO 集的交易时，旧错误码 -27 的消息从 “Transaction already in block chain” 改为 “Transaction outputs already in utxo set”（#30212），更准确地描述了问题来源（交易本身未上链，只是其输出已被花费/上链）。错误码不变。

estimatesmartfee 默认改为 economical

estimatesmartfee 的默认估算模式从 conservative 更新为 economical（#30275）。预期效果：

• 对多数用户减少手续费高估，尤其当 Replace-by-Fee（RBF）可用时；
• 需要高置信度（宁可高估）的场景仍可显式传 conservative 模式参数。

scantxoutset 新增 blockhash 与 confirmations 字段

scantxoutset 返回的 unspents JSON 数组中，每个元素现在新增两个字段：blockhash 与 confirmations（#30515），便于离线审计与构建花费状态判断。

submitpackage 新增 maxfeerate 与 maxburnamount

submitpackage 新增两个可选参数（#28950）：maxfeerate（限制整个包的最高费率）与 maxburnamount（限制可接受的销毁金额上限）。完整说明与示例见该 RPC help（源码注册于 src/rpc/mempool.cpp 的 submitpackage 段，示例同时给出父-子包构造）。钱包相关 RPC 变更见下文 Wallet 节。

更新的 REST API：/rest/getutxos 参数校验

对 /rest/getutxos 的参数校验做了强化（#30482、#30444）：

• 被截断或过长的 txid 以及畸形格式的 outpoint 索引，现在会返回 HTTP_BAD_REQUEST（“Parse error”）；
• 此前这类请求会被静默处理（要么忽略要么产生歧义结果）。

这提升了 REST 接口对畸形输入的确定性。REST 路由代码见 src/rest.cpp。

构建系统与编译要求

28.0 抬高了编译工具链与运行时基线：

• 编译器：GCC 11.1 或更高；或 Clang 16.0 或更高（#29091、#30263）；
• 运行时 glibc：最低 2.31（#29987）。由此 RHEL 8 与 Ubuntu 18.04（Bionic）不再受支持；
• 构建选项 --enable-lcov-branch-coverage 被移除——原因是 lcov 1.x 与 2.x 之间存在不兼容；相关选项请改用 LCOV_OPTS 传递（#30192）。

对应地，仓库根级 CMakeLists.txt 与 cmake/ 为当前构建系统的真实入口，当前 master 的版本声明也在 CMakeLists.txt 中（已演进至 31.99.0）。若要在本仓库源码上复现编译，请以仓库根 INSTALL.md、[doc/build-unix.md] 风格的构建文档及 CMakePresets.json 为准。

设置变更：-alertnotify 触发范围扩大

运行 -alertnotify 时，警报现在可以多次触发，而不再只触发一次（#30058）。此前它仅在未知新共识规则被激活时触发；现在范围扩大为所有内核（kernel）告警，具体包括：

• 检测到包含大量工作量（work）的无效链（如潜在的拒绝服务/分叉场景）时会发出警报；
• 未来可能继续追加其他告警类别。

-alertnotify 的取值是收到警报时应执行的外部命令/脚本，多触发语义意味着运维侧需保证处理脚本幂等。

钱包（Wallet）相关变更

钱包交易与内存池冲突检测（mempoolconflicts）

钱包现在能够检测钱包交易与内存池之间的冲突（#27307）：

• 冲突交易可通过 gettransaction 返回的 "mempoolconflicts" 字段查看；
• 当父交易从内存池被剔除时，mempool-conflicted 交易的输入无需手动 abandon 即可重新花费——此前这种残留会让钱包余额看起来偏高。相关实现见 src/wallet/wallet.cpp。

fundrawtransaction / walletcreatefundedpsbt / send 新增 max_tx_weight

这三个 RPC 新增 max_tx_weight 选项（#29523），指定最大交易权重；若资金组装（funding）过程中超出该限制，交易将不会被构建。默认值为 4,000,000 WU。示例用法（伪代码示意）：

send 金额 --max_tx_weight=4000000

在源码中，该参数被解析进 CoinControl 的 m_max_tx_weight（见 src/wallet/rpc/spend.cpp 中参数声明与上限处理，未提供值或超过 TRUC 上限时会回退到对应默认值），并参与 Send 交易的组装约束。

新 RPC：createwalletdescriptor

createwalletdescriptor 允许向钱包添加新的自动生成描述符（descriptor）（#29130），典型场景是把老版本创建的钱包升级到新标准描述符类型（例如 taproot）。源码注册见 src/wallet/rpc/wallet.cpp 中同名方法。

新 RPC：gethdkeys

gethdkeys 列出钱包内所有描述符正在使用的全部 BIP32 HD 密钥（#29130）。配合 createwalletdescriptor 可针对钱包已知的特定密钥创建并添加单密钥描述符，是“老钱包补足 taproot 等新描述符”流程的两件套。同样定义于 src/wallet/rpc/wallet.cpp（其 help 示例包含 active_only、private 等参数）。

sendall 可花费未确认找零并自动补齐加价

sendall 现在可以花费未确认的找零（change），并在必要时追加手续费，使生成交易把未确认交易的费率提升（bump）到指定费率（#28979）。这让“扫空钱包”场景在存在未确认找零时仍可一步完成。

bumpfee 不再强制 5 sat/vB 增量步长

bumpfee 指定 fee_rate 时，费率不再被限制为必须遵循钱包默认的增量费率 5 sat/vB（#27969）；但仍需至少等于原交易费率加上内存池增量费率（incremental feerate），以符合 RBF 规则。这为手动精确控制替换费率提供了空间。

GUI 变更

28.0 的图形界面（Bitcoin-Qt）有两项可见改进：

• “Migrate Wallet”菜单：允许迁移钱包目录中的任意 legacy（旧版非描述符）钱包，无论该钱包当前是否已加载（gui#824）；
• “Information”窗口：在显示 mempool 使用量的同时，新增显示最大内存池大小（gui#825）。

GUI 源码位于 src/qt/，迁移相关逻辑与钱包工具联动（见 src/qt/walletcontroller.cpp 等）。

底层（Low-level）变更

测试

• BIP94 timewarp 缓解已作用于 regtest（#30681）：本地回归测试网络也启用时间扭曲防护，使 regtest 上的共识行为更贴近 Testnet4；相关用例见 src/test/testnet4_miner_tests.cpp；
• test_bitcoin 新增 -testdatadir 选项，可指定单元测试数据目录的位置（#26564），便于并行测试与 CI 清理。

区块存储：默认 XOR 混淆

• 区块文件（block files）现在默认以存储于 blocksdir 的密钥做 XOR 混淆（#28052）；
• 之前的 Bitcoin Core 版本或第三方软件无法读取带非零 XOR-key 的 blocksdir；
• 详情参考 -blocksxor 选项帮助（bitcoind -help 中该参数说明）。这一机制属于数据完整性与磁盘隐私增强，迁移/降级时需注意版本兼容。

Chainstate：修剪期 flush 不再清空数据库缓存

• 区块被修剪（prune）时触发的 chainstate 数据库 flush 不再清空内存中的数据库缓存（#28280）；
• 缓存能保留更久，从而显著缩短初始区块下载（IBD）总耗时。这是 28.0 在同步性能上的关键低层优化。

依赖替换：Boost.Process → cpp-subprocess

• 对 Boost.Process 的依赖被替换为内置于源码中的 cpp-subprocess（#28981）；
• 构建外部签名者（external signer）支持时，构建者不再需要安装 Boost.Process。这也是外部签名功能（HWI 风格）构建依赖收敛的一步。

贡献者致谢

28.0 汇集了社区大量直接贡献，release notes 中逐一列出了署名贡献者名单（含 0xb10c、Anthony Towns、Ava Chow、glozow、Greg Sanders、Pieter Wuille、Ryan Ofsky、stickies-v、TheCharlatan 等众多开发者），同时向所有在 Transifex 平台上参与翻译的贡献者致谢。完整名单以 release-notes-28.0.md 末尾 Credits 一节为准。

小结：从 28.0 看 Bitcoin Core 的技术演进方向

综合全部变更可以提炼出 28.0 的几条主线：

1. 网络迭代：Testnet4/BIP94 落地、Testnet3 进入淘汰倒计时，反映测试网基础设施的现代化；
2. 协议与 mempool 精细化：TRUC（v3/BIP431）、P2A 与受限包 RBF、默认 full-RBF 协同作用，使费用替换与 CPFP 更可预测，为后续 cluster mempool 铺路；
3. 接口现代化：JSON-RPC 2.0 严格化、REST 参数校验、warnings 结构化；
4. 运营与性能：XOR 混淆区块文件、修剪期缓存保留、AssumeUTXO 主网 840,000 快照、更严格的 bind 启动检查。

若需按原始条目逐项回溯设计动机，可直接阅读 release-notes-28.0.md；想验证上述任一实现细节，可按正文给出的 src/ 源码路径继续深入当前仓库。