Bitcoin Core 22.0 版本特性全解析：I2P、Tor v2 移除与 RPC/钱包体系更新

Bitcoin Core 22.0 是一个以“网络层与隐私通道演进”为核心的里程碑版本：它首次原生支持 I2P 网络、全面移除 Tor v2 隐秘服务（仅保留 v3）、新增 NAT-PMP 端口映射，并同步重构了 banlist 存储、RPC 字段与钱包外部签名者支持。本文基于 release-notes-22.0.md 对该版本的所有 Notable changes 与 Low-level changes 进行逐项深入解读，并结合当前仓库源码验证各改动在 bitcoind/bitcoin-cli/bitcoin-qt 中的真实落点，帮助运行 22.0 或计划从旧版本升级的节点维护者、钱包开发者与协议研究者准确理解行为变化与升级注意事项。

升级方式与兼容性基线

如何从旧版本升级

如果你正在运行一个较旧版本的 Bitcoin Core，正确的升级步骤是：先关闭节点进程，等待其完全退出（某些情况下可能需要数分钟），再执行安装或覆盖操作：

• Windows：运行新版安装程序；
• macOS：覆盖 /Applications/Bitcoin-Qt；
• Linux：覆盖 bitcoind / bitcoin-qt 可执行文件。

官方明确说明：直接从已达生命周期终点（EOL）的旧版本跨级升级是可行的，但若数据目录需要迁移，升级耗时可能较长；旧版本的钱包文件通常仍被支持。

支持的平台与 macOS 基线抬升

22.0 在 Linux kernel 系列系统、macOS 10.14+、Windows 7 及更新版本上受官方支持并经过广泛测试；其他类 Unix 系统“应当可以工作”但测试频率较低，官方不建议在未支持的系统上运行。自 22.0 起，早于 macOS 10.14 的版本不再受支持（源码层面对应 PR bitcoin/bitcoin#20419 “Set minimum supported macOS to 10.14”），在依赖库方面还同步要求 C++17 编译器（bitcoin/bitcoin#20413、#21274），这些是构建 22.0 时的硬性前提。

P2P 与网络层三大变化

原生 I2P 支持：以服务节点身份运行与连接

22.0 最受关注的网络层新特性，是引入了通过 I2P SAM 协议桥接入 I2P（隐身互联网项目） 的能力（PR #20685），即节点既可以作为 I2P 服务（被其他节点主动连接），也可以主动连接 I2P 上的对等节点。这一能力的具体配置说明收录在仓库 doc/i2p.md 中：

• 需要一个开启了 SAM 应用桥接 的 I2P 路由器，官方推荐两个实现：Java 官方路由器 i2prouter（SAM 桥默认关闭，需在路由器控制台 http://127.0.0.1:7657/configclients 或 clients.config 中手动/自动开启）与 C++ 轻量实现 i2pd（默认启用 SAM 桥）。SAM 代理通常监听 127.0.0.1:7656。
• 在 22.0 中的最小配置只需一行：

bitcoind -i2psam=127.0.0.1:7656

其中 -i2psam=<ip:port> 用于指定 SAM 代理地址，-i2pacceptincoming 控制是否接受入站 I2P 连接（默认 1；该选项在未设置 -i2psam 时被忽略）。注意 I2P 的入站监听是通过 SAM 代理完成的，并非直接绑定本地地址与端口。仓库中 I2P 相关变更还包括：强制端口 0（bitcoin/bitcoin#22112）、限制入站消息大小（bitcoin/bitcoin#21407）、为 I2P 地址使用更强的 AddLocal()（bitcoin/bitcoin#21914）、I2P 硬编码种子（bitcoin/bitcoin#21825、#22589），并同步在 contrib/seeds 体系里维护种子节点列表。

针对运维细节，可用 -debug=i2p 在日志中观察 I2P 连接状态；-onlynet=i2p 会让自动出站连接只走 I2P（入站与手动连接不受影响，可多次指定如 onlynet=onion, onlynet=i2p）。需要提醒：22.0 刚引入 I2P 时该网络上的对等节点数量少于 Tor 或普通 IP，单一使用 I2P 可能更容易遭受 Sybil 攻击；同时仅靠 I2P 完成初始区块下载（IBD）可能很慢，可并行使用 onlynet=onion 加速。

彻底移除 Tor v2，只保留 v3

随着 Tor 网络在 Tor 0.4.6 发布时下线 v2 协议支持，22.0 同步移除了对 Tor v2 隐秘服务的全部支持（PR #22050 及后续 #22179）。从此以后节点会忽略 Tor v2 地址，既不会在网络上向其他对等节点传播（rumor），也不会将其保存在内存或 peers.dat 中。这要求此前依赖 v2 洋葱地址的节点运营者提前将服务迁移到 v3。仓库的 doc/tor.md 与相关 -onlynet 帮助文本同步做了修订。另外新增了一批 Tor v3 硬编码种子（bitcoin/bitcoin#21560），并更新了 testnet 的 v3 种子、剔除 v2 种子（bitcoin/bitcoin#22060）。为配合“只支持 Tor v3”的升级场景，CLI 也新增了 -addrinfo 命令（见下文“工具链”一节）以帮助节点判断是否已掌握足够的某网络地址。

NAT-PMP 端口映射支持

22.0 引入基于 libnatpmp 的 NAT-PMP 端口映射能力（PR #18077），使节点在支持 NAT-PMP 的家庭路由器上自动为监听端口做端口映射，与既有的 UPnP（-upnp）形成互补：当 UPnP 与 NAT-PMP 同时启用时，UPnP 的成功分配优先于 NAT-PMP。当前仓库把 NAT-PMP/PCP 相关协议逻辑沉淀在 src/common/pcp.cpp 中（如 NATPMP 服务端口 5351、RFC 6886 的版本字节、NATPMP_OP_MAP_TCP 端口映射操作码等），并跟随 depends 依赖管理引入 libnatpmp 源码。注意当前主干在 PCP 与 NAT-PMP 的架构上相比 22.0 又做了进一步演进，行为细节请以你实际构建的版本帮助文本为准。

RPC 接口：地址编码、字段增删与语义修正

BIP 350 落地：v1+ 见证地址改用 Bech32m

由于 22.0 实现了 BIP 350（#20861），所有接受地址的 RPC 在传入原生见证版本 1（或更高）地址时，行为发生变化：此类地址必须使用 Bech32m 编码而非旧的 Bech32，RPC 输出中这类地址也改用 Bech32m。当时主网上尚未有任何共识规则赋予 v1 地址语义（要等 BIP 341 Taproot 激活），因此该改动不影响主网生产系统，但会在 signet 等已赋予此类地址含义的网络上被观察到。仓库 doc/bips.md 中记录了各 BIP 的实现状态，供查询 Bech32m/BIP 341 的落地进度。

getpeerinfo：新增高带宽模式字段，移除三个旧字段

getpeerinfo 新增两个布尔字段（#19776），反映 BIP 152 紧凑区块（compact blocks）高带宽模式的协商结果：

• bip152_hb_to：我们是否选择了该对等节点作为高带宽模式对等节点；
• bip152_hb_from：该对等节点是否选择了我们作为高带宽对等节点。

高带宽对等节点通过 cmpctblock 消息推送新区块公告，而非通常的 inv/headers 公告。该字段的实现在 src/rpc/net.cpp 的 RPC 结果声明中可查，取值直接取自对等节点的 m_bip152_highbandwidth_to/from 状态（第 275–276 行）。

同时（#20755）getpeerinfo 不再返回此前在 0.21 中就已弃用的三个字段：addnode、banscore、whitelisted。迁移语义为：用 connection_type 取值 manual 替代 addnode；用 permissions 字段指示该对等节点是否拥有特权替代 whitelisted；banscore 则被直接移除，不再有替代物。GUI 与 bitcoin-cli -netinfo 的 peer 展示同步改用了 connection_type 与 permissions 语义。

scriptPubKey 输出弃用 addresses / reqSigs

受 #20286 影响，以下 RPC：gettxout、getrawtransaction、decoderawtransaction、decodescript、gettransaction，以及 REST 端点 /rest/tx、/rest/getutxos、/rest/block，默认不再返回 addresses 与 reqSigs 两个字段（它们本属于响应中 scriptPubKey 对象的属性）。需要继续获取这些字段，必须显式传入启动参数 -deprecatedrpc=addresses。该兼容开关仅存在于 22.0 这一个主版本，之后的版本会将其彻底删除，因此依赖这些字段的调用方应尽快迁移到 scriptPubKey 内新引入的 address（单数）等现代字段。此外用 bitcoin-tx -json 构造十六进制交易时，其输出中同样不再返回这两个字段。

listbanned / setban / getnodeaddresses 的细节变化

• listbanned（#21602）新增两个数值字段：ban_duration（禁封时长，秒）与 time_remaining（距禁封到期剩余秒数），并将 ban_created 重新排到 banned_until 之前。源码中（src/rpc/net.cpp、第 896–897 行）由 banEntry.nBanUntil、nCreateTime 计算得出；src/test/rpc_tests.cpp 的单元测试验证了 ban_duration == banned_until - ban_created 与 time_remaining 的精确语义。
• setban（#20852）修复了 0.21.0 引入的回归，可以再次封禁 onion 地址。
• getnodeaddresses（#21594、#21843）的每个返回地址新增 network 字段，取值 ipv4/ipv6/onion/i2p；同时该 RPC 现在接受一个可选的 network 参数，只返回指定网络类型的地址。

testmempoolaccept 支持交易包（package）测试

testmempoolaccept 升级为可一次接收多个交易（#20833，当前仍为实验性、API 可能变动），其设计目的是测试带依赖关系的交易包（package），官方明确不推荐用于批量校验相互独立的交易。除常规 mempool 策略外还适用包级策略：

• 列表内交易不能超过 25 笔，或总大小超过 101K vbytes；
• 列表内交易之间、以及与当前 mempool 之间不得冲突（花费相同输入），即便按 BIP 125 的 RBF 规则本可合法替换也不允许。

已知局限是：testmempoolaccept 对一组交易可能返回 "allowed": True，但实际提交时却因 too-long-mempool-chain 被拒。相关后续收尾工作见 #22084。该方向是 22.0 为后续 package relay/validation（比特币核心 0.21.1 之后持续推进的领域）打下的早期地基，当前仓库 doc/policy 与 doc/policy/mempool-design.md 记录了该机制的更完整设计。

其他 RPC 兼容性修正

• 20 密钥多签（#20867）：Segwit 场景下 addmultisigaddress 与 createmultisig 支持最多 20 个密钥。
• 错误码修正（#18466）：signmessage 与 verifymessage 对无效地址返回 RPC_INVALID_ADDRESS_OR_KEY (-5)（此前为 RPC_TYPE_ERROR (-3)）；verifymessage 对格式错误的签名返回 RPC_TYPE_ERROR (-3)（此前误返回 -5）。
• RPC 工作队列过载（#18335）：RPC 服务器同时处理的请求数有上限，超限时旧版本返回 HTTP 500，22.0 起返回 HTTP 503（HTTP_SERVICE_UNAVAILABLE），语义更准确。
• -rpcauth 校验（#20461）：传入无效的 -rpcauth 参数将导致 bitcoind 启动失败，避免以错误鉴权配置静默运行。

数据文件与新增/更新设置

banlist.dat 迁移为 JSON 格式 banlist.json

被封禁主机与网络（通过 setban RPC 管理）的持久化列表（#20966）改以 JSON 格式保存在 banlist.json，取代旧的 banlist.dat。兼容策略是：

• 若启动时不存在 banlist.json，才读取旧的 banlist.dat；
• 所有变更只写入新的 banlist.json；
• 未来的版本可能完全忽略 banlist.dat，请尽早自然完成迁移。

当前仓库中该数据库的访问入口仍以 banlist.json 为契约（见 src/addrdb.h 中 “Access to the banlist database (banlist.json)” 的注释），banman 相关文件与 src/test/rpc_tests.cpp 中的测试共同覆盖了禁封逻辑。

新增/更新的设置项速查

设置项	类型	说明
-natpmp	新增	使用 NAT-PMP 映射监听端口；若 UPnP 与 NAT-PMP 都启用，UPnP 的成功分配优先（#18077）
-rpcauth	更新	无效参数使 bitcoind 启动失败（#20461）
-i2psam / -i2pacceptincoming	新增	I2P SAM 代理地址 / 是否接受 I2P 入站（#20685，详见 doc/i2p.md）

命令行工具：-addrinfo 与 -rpcwaittimeout

22.0 为 bitcoin-cli 新增了两个面向网络运维的能力：

• -addrinfo（#21595）：输出节点已知的各网络类型地址数量（含区分 Tor v2 与 v3，虽然 v2 已被本版移除）与总数。该命令在设计上服务于两个典型诉求：判断节点是否掌握足够多的某网络地址以安全使用 -onlynet=<network>；以及评估是否可以升级到本版——因为 22.0 只支持 Tor v3，若节点已知的 Tor v3 地址太少则出站连接可能受限。bitcoin-cli -addrinfo 命令在 src/bitcoin-cli.cpp 中注册（-addrinfo “Get the number of addresses known to the node, per network and total”）。注意该命令依赖后端 RPC，且随版本演进已改为基于 getaddrmaninfo 实现；在非常新的 bitcoind 上使用旧版 cli（或反之）会得到明确的版本不匹配提示（同文件第 294 行左右的运行时检查）。
• -rpcwaittimeout（#21056）：设置与 -rpcwait 配合使用的超时秒数，超时后 bitcoin-cli 报告失败，避免脚本被无限阻塞。该参数由 ArgsManager 注册并避免被意外截断（#22327）。

构建系统：Guix 可复现构建正式接管发布

22.0 起官方发布二进制改用基于 Guix 的全新构建系统产出（相关 PR 贯穿该版本，如 #17920 macOS 支持、#20937 NSIS 可复现、#21462 guix-attest/guix-verify 脚本等），并据此更新了 doc/release-process.md。发布流程同时拆分为独立的 sha256sums 与签名文件（#22642）。如果希望深入理解可复现构建与签名验证的实操流程，仓库提供了完整的一手资料：

• contrib/guix/README.md：安装与日常使用文档；
• doc/release-process.md：发版操作说明；
• 脚本工具链 contrib/guix/guix-verify（验签）、contrib/guix/guix-attest（签名背书）、contrib/guix/guix-clean（清理缓存）。

钱包与 GUI：外部签名者、描述符钱包与 Taproot 前夜

外部签名者（硬件钱包）支持：enumeratesigners / displayaddress

22.0 为钱包引入实验性的外部签名者支持（#16546），允许通过新的 RPC 方法使用硬件钱包：enumeratesigners 枚举已连接设备、displayaddress 在设备上展示地址，send RPC 也支持外部签名流程。操作细节见仓库文档 doc/external-signer.md。配套改动包括支持 HWI 2（#21417）、把外部签名者逻辑移出钱包模块（#21467）、在不支持的平台上不加载外部签名者钱包（#22173）等。

GUI 侧同步跟进（bitcoin-core/gui#4、#21935、#396）：需在 Options → Wallet 中安装并配置外部工具（如 HWI）；创建新钱包时对话框会出现 “External signer” 选项，若检测到设备则以其名称为钱包命名建议，随后自动导入 watch-only 密钥；收款地址可在设备上验证；发送对话框自动使用已连接设备。官方提示：此功能仍为实验性，执行这些动作时 UI 可能冻结数秒。

描述符钱包审计工具：listdescriptors

新增 listdescriptors RPC（#20226、#21277 等）用于检视描述符钱包（descriptor-enabled wallet）内容：返回所有已导入描述符的公钥版本，含其时间戳与 flags；对 ranged（带范围）描述符还会返回范围边界以及下一次生成地址所用的索引，便于钱包备份与审计。相关测试与使用可参考仓库 doc/descriptors.md。

fundrawtransaction 系列新增 include_unsafe

fundrawtransaction、send、walletcreatefundedpsbt 新增 include_unsafe 选项（#21359）：为 true 时允许用“不安全”输入（unsafe inputs）为交易注资。注意后果自负：若其中一个不安全输入消失，结果交易可能失效，此时必须改用其他输入重新注资并发布。

其他钱包行为调整

• bumpfee 在禁用私钥的钱包中不可用，改用 psbtbumpfee（#20891，移除了旧的弃用行为）。
• 描述符钱包对 multi()/sortedmulti() 包在 wsh() 内时支持最多 20 个密钥（#20867）。
• Taproot 描述符只能在 Taproot 已激活的网络（mainnet/testnet/signet）上导入（#22156），为 BIP 341 落地做准备；tr() 描述符的推断支持也在本版引入（#22166）。

为 Taproot 准备的底层累积

22.0 是 Taproot（BIP 341）激活前的最后一个大版本，钱包与地址层做了大量铺垫：新增 OutputType::BECH32M 并支持为钱包抓取 bech32m 地址（#22154）、描述符钱包基础 Taproot 派生与签名支持（#21365、#22051）、IsSegWitOutput 对 taproot 输出返回 true（#22421）等。因此理解 22.0 的 Bech32m 规则（上文 RPC 一节）与描述符能力，是评估 Taproot 工具链兼容性的关键上下文。

低频底层改进一览

除上述高可见度变更外，22.0 还包含一批值得关注的低层改进：

• 区块与交易处理：为 CCheckQueue 增加本地线程池（#18710）、Coinstats Index 基础工作（#19521）、UTXO 快照激活（#19806，assumeutxo 方向）、libsecp256k1 子树更新到最新 master（#21573）、在 testmempoolaccept 路径打通 package 验证（#20833）等；
• P2P 内部：per-peer 消息捕获（#19509）、周期性地做区块中继连接与头同步（#19858）、addrv2 下的 anchors.dat（#20516）、移除了 -feefilter 选项（#21992）、对 rumoured 地址的处理做速率限制（#22387）、随机化消息处理顺序以抗针对性攻击（#22144）等；
• 策略层：禁用 blocksonly 模式下的费率估算（#18766）、新增 MAX_STANDARD_SCRIPTSIG_SIZE 策略常量（#20497）；
• 其他工具：bitcoind 新增 -daemonwait 选项以等待初始化完成（#21007）；signet 挖矿工具（#19937、#20923）落地。

完整清单可查阅 release-notes-22.0.md 后半部分的 22.0 change log（按 Consensus、Policy、Wallet、RPC、GUI、Build system、Tests、Miscellaneous、Documentation 分类，条目与 PR 号一一对应），也可在仓库根目录的 README.md 中了解整体架构后自行定位对应源码模块。

小结：从 22.0 看 Bitcoin Core 的演进主线

综合来看，22.0 的变更清晰地指向三条主线：

1. 网络访问的多样化与安全清理：I2P 加入四大网络族（IPv4/IPv6/onion/I2P），配合 NAT-PMP 入站映射与 Tor v3-only 策略，使节点运营者有更丰富的抗审查与连接冗余选择；
2. 为 Taproot 激活做全链路准备：Bech32m、20 密钥多签、Taproot 描述符门控等规则与钱包改动互相咬合；
3. 运维与 API 可观测性的持续打磨：banlist.json、RPC 字段增删与错误码修正、-addrinfo/-rpcwaittimeout 工具以及 Guix 可复现发布，都降低了大规模节点运维与版本审计的成本。

对于正运行 22.0 或计划升级的开发者，建议重点核对本文“升级方式”“RPC 变更”“设置项速查”三节的内容，尤其关注 -deprecatedrpc=addresses 仅在 22.0 单版本有效的窗口期限制，以及脚本中对 getpeerinfo 旧字段（addnode/banscore/whitelisted）的依赖是否已迁移完毕。