Bitcoin Core IPC 接口升级BlockTemplate.submitSolution 返回拒绝原因与重复块失败语义#34672【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本篇围绕 Bitcoin Core 一次 IPCMultiprocess接口变更展开BlockTemplate.submitSolution方法的新返回值签名、Capn Proto 模式升级与旧版本兼容策略以及重复块提交语义与Mining.submitBlock对齐的底层实现。读完后你将理解如何基于 mining.capnp 重新生成 IPC 绑定、如何正确处理reason/debug拒绝字段以及为什么旧版7客户端会收到明确的升级提示而不是静默成功。背景Bitcoin Core 的 IPC 挖矿接口Bitcoin Core 引入了基于 Capn Proto 与 libmultiprocess 的进程间通信IPC层允许独立进程的客户端如未来的 Stratum v2 Template Provider以类型安全、无 JSON 序列化开销的方式访问节点能力。挖矿相关的接口定义在 mining.capnp 中包含两个核心接口Mining链状态查询、模板创建、整块提交submitBlock 7等BlockTemplate块模板访问与挖矿产物提交包括submitSolution、waitNext、interruptWait。这些 Capn Proto 接口通过$Proxy.wrap映射到 C 抽象接口interfaces::Mining/interfaces::BlockTemplate定义于 mining.h并在 node/interfaces.cpp 中给出具体实现。本次变更#34672修改的正是BlockTemplate.submitSolution的返回值语义与协议版本。变更一submitSolution 返回 reason 与 debug 拒绝详情变更前BlockTemplate.submitSolution仅返回一个布尔值成功或失败。挖矿产物被拒绝时客户端无从得知拒绝原因只能盲目重试。变更后方法与Mining.checkBlock、Mining.submitBlock保持一致返回三个字段字段类型含义reasonText失败原因采用 BIP22 拒绝原因编码成功时为空字符串debugText更详细的拒绝描述便于日志与调试成功时为空字符串resultBool块是否被接受为新块在 mining.capnp 中新签名为submitSolution 10 (context: Proxy.Context, version: UInt32, timestamp: UInt32, nonce: UInt32, coinbase :Data) - (reason: Text, debug: Text, result: Bool);对应的 C 抽象接口声明见 mining.h同样以出参形式携带两个字符串并明确了 BIP22 语义与使用限制/** * param[in] version version block header field * param[in] timestamp time block header field (unix timestamp) * param[in] nonce nonce block header field * param[in] coinbase complete coinbase transaction (including witness) * param[out] reason failure reason (BIP22) * param[out] debug more detailed rejection reason * ... */ virtual bool submitSolution(uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase, std::string reason, std::string debug) 0;节点端实现在 node/interfaces.cpp 的BlockTemplateImpl::submitSolution中将客户端提供的 version/timestamp/nonce/coinbase 写入模板块并重新计算 Merkle 根然后调用统一的SubmitBlock见 node/miner.cpp完成验证与进链reason/debug即从该函数带出。这与Mining.submitBlockRPC 之外的共享验证路径复用同一套状态捕获逻辑SubmitBlockStateCatcher保证了 IPC 与 RPC 语义一致。为什么新方法使用 10 而旧方法保留 7Capn Proto 的方法序号ordinal是协议兼容性的锚点。旧版submitSolution占用7无法原地改变其返回值结构——若直接修改7的签名按旧字节格式解包的客户端将产生未定义行为。因此本变更采用了“保留旧槽位、新增槽位”的迁移方案见 mining.capnpsubmitSolution 10 (...) - (reason: Text, debug: Text, result: Bool); ... # DEPRECATED: older version of submitSolution which returns an error. submitSolutionOld7 7 (...) - (result: Bool);新客户端使用10获得完整的reason/debug/result旧序号7被重命名并保留为submitSolutionOld7其实现不是静默兼容而是显式抛出错误。interfaces/mining.h 中的默认实现为virtual bool submitSolutionOld7(uint32_t, uint32_t, uint32_t, CTransactionRef) { throw std::runtime_error(Old submitSolution (7) not supported. Please update your client!); }这意味着仍然携带旧版mining.capnp生成绑定的客户端在调用submitSolution即旧7时会收到“Please update your client!”错误提示从而把“客户端模式过期”从难以诊断的静默异常变为明确的升级指引。这也是发布说明中“Clients must regenerate IPC bindings from the updated mining.capnp schema to use the new method”的落地机制——客户端需要拿到新版 schema 重新生成绑定代码才能调用10。从源码结构看submitSolution与submitBlock的边界也值得注意interfaces/mining.h 的注释与submitblockRPC 不同submitSolution不会调用UpdateUncommittedBlockStructures去补全缺失的 coinbase witness reserved value客户端必须提交包含完整 witness 的 coinbase 交易此外对于高度 16 及以下的链getCoinbaseTx().script_sig_prefix中的 BIP34 高度 push 仅一个字节coinbase scriptSig 需要至少额外一个字节数据以避免bad-cb-length。这些约束在升级客户端时同样适用。变更二重复块提交由“成功”改为“失败reasonduplicate”变更前存在一个语义缺陷Mining.submitBlock对已进链的重复块会报告失败BIP22 风格reasonduplicate而BlockTemplate.submitSolution却把重复提交当作成功返回。两者行为不一致会让依赖返回值做重试决策的矿工客户端误判。变更后submitSolution与submitBlock对齐重复块一律作为失败上报且reason为duplicate。统一后的判定逻辑集中在 node/miner.cpp 的SubmitBlock中bool SubmitBlock(ChainstateManager chainman, const std::shared_ptrconst CBlock block, std::string reason, std::string debug) { ... bool accepted chainman.ProcessNewBlock(block, /*force_processing*/true, /*min_pow_checked*/true, /*new_block*/new_block); ... if (!new_block accepted) { reason duplicate; } else if (!accepted (!sc-m_found || sc-m_state.IsValid())) { reason inconclusive; } else if (!sc-m_found) { reason inconclusive; } else if (!sc-m_state.IsValid()) { reason sc-m_state.GetRejectReason(); debug sc-m_state.GetDebugMessage(); } const bool result{accepted new_block reason.empty()}; ... return result; }结合reason/debug新返回值客户端现在可以区分以下全部情形resulttrue块被接受并连接为新 tipreason/debug为空resultfalse, reasonduplicate块已存在重复提交这是本次变更让submitSolution新增报告的失败类别resultfalse, reasoninconclusiveProcessNewBlock失败但未给出可判定的验证结果例如激活或系统错误或块被接受但未连接例如工作量不大于当前 tip客户端可视为“无法确认”适合触发重新取模/重试resultfalse, reasonBIP22 拒绝原因, debug详细描述块验证失败debug提供可读的失败细节。函数结尾的CHECK_NONFATAL(result reason.empty())还以不变式形式保证成功当且仅当reason为空使布尔结果与字符串原因互不矛盾。测试验证重复块与旧版 7 行为均有回归覆盖src/test/miner_tests.cpp 中的单元测试把两条变更路径都固化为了断言测试交替使用Mining.submitBlock与BlockTemplate.submitSolution提交同一块// 奇偶高度交替走 submitBlock / submitSolution ... BOOST_REQUIRE(!mining-submitBlock(block, reason, debug)); BOOST_REQUIRE_EQUAL(reason, duplicate); BOOST_REQUIRE_EQUAL(debug, ); ... BOOST_REQUIRE(block_template-submitSolution(block.nVersion, block.nTime, block.nNonce, MakeTransactionRef(txCoinbase), reason, debug)); BOOST_REQUIRE_EQUAL(reason, ); BOOST_REQUIRE_EQUAL(debug, ); // 旧版 7 调用必须抛出异常 BOOST_CHECK_THROW(block_template-submitSolutionOld7(block.nVersion, block.nTime, block.nNonce, MakeTransactionRef(txCoinbase)), std::runtime_error);即重复提交返回false且reasonduplicate正常submitSolution成功后reason/debug为空而submitSolutionOld7直接抛出std::runtime_error与 interfaces/mining.h 的“Please update your client!”一致。相关 IPC 测试与 fuzz 目标可继续参考 ipc 测试目录 与 IPC fuzz。客户端迁移指引结合本次变更IPC 挖矿客户端的升级步骤可以归纳为获取新版 schema以仓库内 src/ipc/capnp/mining.capnp 为准确认BlockTemplate.submitSolution为10、返回(reason, debug, result)重新生成 IPC 绑定客户端工程需按 libmultiprocess/Capn Proto 构建流程重新生成绑定代码Bitcoin Core 构建集成见 cmake/libmultiprocess.cmake 与 src/ipc/CMakeLists.txt旧的7绑定调用将收到显式错误而非静默结果按新语义处理返回值以result决定成功与否以reason区分duplicate、inconclusive与 BIP22 拒绝原因将debug记入日志对duplicate直接放弃当前产物、进入下一模板waitNext对inconclusive可重新获取链状态后重试注意 coinbase 完整性约束submitSolution不做 witness reserved value 补全提交的 coinbase 必须含完整 witness存在 witness commitment 时且低高度链需留意 scriptSig 长度要求。小结#34672 虽只涉及 IPC 挖矿接口的一个方法但它同时修复了两类典型问题可诊断性拒绝原因缺失与跨入口语义一致性submitSolution与submitBlock对重复块的处理分歧。通过“保留7旧槽位并显式报错 新增10新签名”的方案Bitcoin Core 在 Capn Proto 层实现了强制且可诊断的客户端升级路径实现上复用 SubmitBlock 的统一状态捕获由 miner_tests.cpp 对重复块与旧版槽位行为提供回归保障。对于正在对接 Bitcoin Core IPC 的挖矿类客户端这组reason/debug字段与明确的兼容性错误是构建健壮重试与监控逻辑的基础。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Bitcoin Core IPC 接口升级：BlockTemplate.submitSolution 返回拒绝原因与重复块失败语义（34672）
Bitcoin Core IPC 接口升级BlockTemplate.submitSolution 返回拒绝原因与重复块失败语义#34672【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本篇围绕 Bitcoin Core 一次 IPCMultiprocess接口变更展开BlockTemplate.submitSolution方法的新返回值签名、Capn Proto 模式升级与旧版本兼容策略以及重复块提交语义与Mining.submitBlock对齐的底层实现。读完后你将理解如何基于 mining.capnp 重新生成 IPC 绑定、如何正确处理reason/debug拒绝字段以及为什么旧版7客户端会收到明确的升级提示而不是静默成功。背景Bitcoin Core 的 IPC 挖矿接口Bitcoin Core 引入了基于 Capn Proto 与 libmultiprocess 的进程间通信IPC层允许独立进程的客户端如未来的 Stratum v2 Template Provider以类型安全、无 JSON 序列化开销的方式访问节点能力。挖矿相关的接口定义在 mining.capnp 中包含两个核心接口Mining链状态查询、模板创建、整块提交submitBlock 7等BlockTemplate块模板访问与挖矿产物提交包括submitSolution、waitNext、interruptWait。这些 Capn Proto 接口通过$Proxy.wrap映射到 C 抽象接口interfaces::Mining/interfaces::BlockTemplate定义于 mining.h并在 node/interfaces.cpp 中给出具体实现。本次变更#34672修改的正是BlockTemplate.submitSolution的返回值语义与协议版本。变更一submitSolution 返回 reason 与 debug 拒绝详情变更前BlockTemplate.submitSolution仅返回一个布尔值成功或失败。挖矿产物被拒绝时客户端无从得知拒绝原因只能盲目重试。变更后方法与Mining.checkBlock、Mining.submitBlock保持一致返回三个字段字段类型含义reasonText失败原因采用 BIP22 拒绝原因编码成功时为空字符串debugText更详细的拒绝描述便于日志与调试成功时为空字符串resultBool块是否被接受为新块在 mining.capnp 中新签名为submitSolution 10 (context: Proxy.Context, version: UInt32, timestamp: UInt32, nonce: UInt32, coinbase :Data) - (reason: Text, debug: Text, result: Bool);对应的 C 抽象接口声明见 mining.h同样以出参形式携带两个字符串并明确了 BIP22 语义与使用限制/** * param[in] version version block header field * param[in] timestamp time block header field (unix timestamp) * param[in] nonce nonce block header field * param[in] coinbase complete coinbase transaction (including witness) * param[out] reason failure reason (BIP22) * param[out] debug more detailed rejection reason * ... */ virtual bool submitSolution(uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase, std::string reason, std::string debug) 0;节点端实现在 node/interfaces.cpp 的BlockTemplateImpl::submitSolution中将客户端提供的 version/timestamp/nonce/coinbase 写入模板块并重新计算 Merkle 根然后调用统一的SubmitBlock见 node/miner.cpp完成验证与进链reason/debug即从该函数带出。这与Mining.submitBlockRPC 之外的共享验证路径复用同一套状态捕获逻辑SubmitBlockStateCatcher保证了 IPC 与 RPC 语义一致。为什么新方法使用 10 而旧方法保留 7Capn Proto 的方法序号ordinal是协议兼容性的锚点。旧版submitSolution占用7无法原地改变其返回值结构——若直接修改7的签名按旧字节格式解包的客户端将产生未定义行为。因此本变更采用了“保留旧槽位、新增槽位”的迁移方案见 mining.capnpsubmitSolution 10 (...) - (reason: Text, debug: Text, result: Bool); ... # DEPRECATED: older version of submitSolution which returns an error. submitSolutionOld7 7 (...) - (result: Bool);新客户端使用10获得完整的reason/debug/result旧序号7被重命名并保留为submitSolutionOld7其实现不是静默兼容而是显式抛出错误。interfaces/mining.h 中的默认实现为virtual bool submitSolutionOld7(uint32_t, uint32_t, uint32_t, CTransactionRef) { throw std::runtime_error(Old submitSolution (7) not supported. Please update your client!); }这意味着仍然携带旧版mining.capnp生成绑定的客户端在调用submitSolution即旧7时会收到“Please update your client!”错误提示从而把“客户端模式过期”从难以诊断的静默异常变为明确的升级指引。这也是发布说明中“Clients must regenerate IPC bindings from the updated mining.capnp schema to use the new method”的落地机制——客户端需要拿到新版 schema 重新生成绑定代码才能调用10。从源码结构看submitSolution与submitBlock的边界也值得注意interfaces/mining.h 的注释与submitblockRPC 不同submitSolution不会调用UpdateUncommittedBlockStructures去补全缺失的 coinbase witness reserved value客户端必须提交包含完整 witness 的 coinbase 交易此外对于高度 16 及以下的链getCoinbaseTx().script_sig_prefix中的 BIP34 高度 push 仅一个字节coinbase scriptSig 需要至少额外一个字节数据以避免bad-cb-length。这些约束在升级客户端时同样适用。变更二重复块提交由“成功”改为“失败reasonduplicate”变更前存在一个语义缺陷Mining.submitBlock对已进链的重复块会报告失败BIP22 风格reasonduplicate而BlockTemplate.submitSolution却把重复提交当作成功返回。两者行为不一致会让依赖返回值做重试决策的矿工客户端误判。变更后submitSolution与submitBlock对齐重复块一律作为失败上报且reason为duplicate。统一后的判定逻辑集中在 node/miner.cpp 的SubmitBlock中bool SubmitBlock(ChainstateManager chainman, const std::shared_ptrconst CBlock block, std::string reason, std::string debug) { ... bool accepted chainman.ProcessNewBlock(block, /*force_processing*/true, /*min_pow_checked*/true, /*new_block*/new_block); ... if (!new_block accepted) { reason duplicate; } else if (!accepted (!sc-m_found || sc-m_state.IsValid())) { reason inconclusive; } else if (!sc-m_found) { reason inconclusive; } else if (!sc-m_state.IsValid()) { reason sc-m_state.GetRejectReason(); debug sc-m_state.GetDebugMessage(); } const bool result{accepted new_block reason.empty()}; ... return result; }结合reason/debug新返回值客户端现在可以区分以下全部情形resulttrue块被接受并连接为新 tipreason/debug为空resultfalse, reasonduplicate块已存在重复提交这是本次变更让submitSolution新增报告的失败类别resultfalse, reasoninconclusiveProcessNewBlock失败但未给出可判定的验证结果例如激活或系统错误或块被接受但未连接例如工作量不大于当前 tip客户端可视为“无法确认”适合触发重新取模/重试resultfalse, reasonBIP22 拒绝原因, debug详细描述块验证失败debug提供可读的失败细节。函数结尾的CHECK_NONFATAL(result reason.empty())还以不变式形式保证成功当且仅当reason为空使布尔结果与字符串原因互不矛盾。测试验证重复块与旧版 7 行为均有回归覆盖src/test/miner_tests.cpp 中的单元测试把两条变更路径都固化为了断言测试交替使用Mining.submitBlock与BlockTemplate.submitSolution提交同一块// 奇偶高度交替走 submitBlock / submitSolution ... BOOST_REQUIRE(!mining-submitBlock(block, reason, debug)); BOOST_REQUIRE_EQUAL(reason, duplicate); BOOST_REQUIRE_EQUAL(debug, ); ... BOOST_REQUIRE(block_template-submitSolution(block.nVersion, block.nTime, block.nNonce, MakeTransactionRef(txCoinbase), reason, debug)); BOOST_REQUIRE_EQUAL(reason, ); BOOST_REQUIRE_EQUAL(debug, ); // 旧版 7 调用必须抛出异常 BOOST_CHECK_THROW(block_template-submitSolutionOld7(block.nVersion, block.nTime, block.nNonce, MakeTransactionRef(txCoinbase)), std::runtime_error);即重复提交返回false且reasonduplicate正常submitSolution成功后reason/debug为空而submitSolutionOld7直接抛出std::runtime_error与 interfaces/mining.h 的“Please update your client!”一致。相关 IPC 测试与 fuzz 目标可继续参考 ipc 测试目录 与 IPC fuzz。客户端迁移指引结合本次变更IPC 挖矿客户端的升级步骤可以归纳为获取新版 schema以仓库内 src/ipc/capnp/mining.capnp 为准确认BlockTemplate.submitSolution为10、返回(reason, debug, result)重新生成 IPC 绑定客户端工程需按 libmultiprocess/Capn Proto 构建流程重新生成绑定代码Bitcoin Core 构建集成见 cmake/libmultiprocess.cmake 与 src/ipc/CMakeLists.txt旧的7绑定调用将收到显式错误而非静默结果按新语义处理返回值以result决定成功与否以reason区分duplicate、inconclusive与 BIP22 拒绝原因将debug记入日志对duplicate直接放弃当前产物、进入下一模板waitNext对inconclusive可重新获取链状态后重试注意 coinbase 完整性约束submitSolution不做 witness reserved value 补全提交的 coinbase 必须含完整 witness存在 witness commitment 时且低高度链需留意 scriptSig 长度要求。小结#34672 虽只涉及 IPC 挖矿接口的一个方法但它同时修复了两类典型问题可诊断性拒绝原因缺失与跨入口语义一致性submitSolution与submitBlock对重复块的处理分歧。通过“保留7旧槽位并显式报错 新增10新签名”的方案Bitcoin Core 在 Capn Proto 层实现了强制且可诊断的客户端升级路径实现上复用 SubmitBlock 的统一状态捕获由 miner_tests.cpp 对重复块与旧版槽位行为提供回归保障。对于正在对接 Bitcoin Core IPC 的挖矿类客户端这组reason/debug字段与明确的兼容性错误是构建健壮重试与监控逻辑的基础。【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
