区块链【免费下载链接】polkadotPolkadot Node Implementation项目地址https://gitcode.com/gh_mirrors/po/polkadot点击查看免费下载导读candidate_pending_availability是 Polkadot 中继链ParachainHost运行时 API 家族中的一员用于按ParaId查询正处于“等待可用性pending availability”状态的候选区块收据CommittedCandidateReceipt。本文以其在 implementers-guide 中的定义为主线结合本仓库的运行时实现、inclusion 模块存储结构与节点子系统调用链说明该 API 的语义、数据来源、节点侧消费方式及典型应用场景帮助读者理解中继链上候选区块从“被背书”到“可用性确认”这一关键状态的数据面。一、API 签名与语义从文档定义出发implementers-guide 中对该 API 的定义非常简洁只有一条函数签名fn candidate_pending_availability(at: Block, ParaId) - OptionCommittedCandidateReceipt;其文档语义为Get the receipt of a candidate pending availability. This returnsSomefor any paras assigned to occupied cores inavailability_coresandNoneotherwise.即返回指定平行链Para当前正处于“等待可用性”阶段的候选区块收据。判定规则与核心core状态直接挂钩——只有当该 Para 被分配到了availability_cores中某个“被占用occupied”的核心时才返回Some否则返回None。这一语义在中继链运行时原语库 primitives/src/runtime_api.rs 的 trait 声明中得到了完全一致的复刻/// Get the receipt of a candidate pending availability. This returns Some for any paras /// assigned to occupied cores in availability_cores and None otherwise. fn candidate_pending_availability(para_id: ppp::Id) - OptionCommittedCandidateReceiptH;注意这里的参数形态文档中写作(at: Block, ParaId)其中at表示查询所针对的中继链区块运行时 API 的通用查询上下文用于确定状态版本而在 trait 声明与实现中仅保留业务参数para_id: ppp::Id即polkadot_primitives::parachain::Id。这与availability_cores、persisted_validation_data等同族 API 的模式一致——at是框架层RuntimeApi注入的查询目标块业务层只关心ParaId。二、返回值CommittedCandidateReceipt是什么OptionCommittedCandidateReceipt中的CommittedCandidateReceipt提交候选收据是候选区块的“正式化”表示由两部分组成在中继链运行时 inclusion 模块的 runtime/parachains/src/inclusion/mod.rs 中可以清晰地看到它的拼装方式PendingAvailabilityT::get(para) .map(|p| p.descriptor) .and_then(|d| PendingAvailabilityCommitmentsT::get(para).map(move |c| (d, c))) .map(|(d, c)| CommittedCandidateReceipt { descriptor: d, commitments: c })即descriptor候选描述符来自PendingAvailability存储项包含候选者的中继父区块哈希、平行链 ID、验证数据哈希、上行消息数、时隙占位等背书时锁定的信息commitments候选承诺来自PendingAvailabilityCommitments存储项包含候选者承诺的头部数据HeadData、上行消息UpwardMessage、HRMP 水平消息、处理后的下行消息水位等执行结果。二者一旦组合CommittedCandidateReceipt便完整描述了“这个候选者提议了什么、承诺产出什么”这也是后续enact_candidate候选者生效流程所消费的输入格式——参见 implementers-guide 中 inclusion 模块的enact_candidate例程。三、数据从哪来inclusion 模块的两张存储表要理解candidate_pending_availability的语义必须理解它背后读取的两张存储映射。implementers-guide 的 Inclusion Pallet 存储布局 给出了权威定义/// The latest bitfield for each validator, referred to by index. bitfields: map ValidatorIndex AvailabilityBitfield; /// Candidates pending availability. PendingAvailability: map ParaId CandidatePendingAvailability; /// The commitments of candidates pending availability, by ParaId. PendingAvailabilityCommitments: map ParaId CandidateCommitments;其中CandidatePendingAvailability辅助结构体记录了候选者在等待可用性期间的完整元数据struct CandidatePendingAvailability { core: CoreIndex, // availability core hash: CandidateHash, descriptor: CandidateDescriptor, availability_votes: Bitfield, // one bit per validator. relay_parent_number: BlockNumber, // number of the relay-parent. backers: Bitfield, // one bit per validator, set for those who backed the candidate. backed_in_number: BlockNumber, backing_group: GroupIndex, }关键字段的含义core候选者当前占用的可用性核心索引正是它决定了availability_cores中该 core 处于occupied状态availability_votes每个验证者一比特记录哪些验证者已经为这个候选者提交了可用性比特availability bitfield当设置比特数超过 2/3 阈值时候选者即可被enact_candidate生效backers每个验证者一比特记录哪些验证者所在的验证组在process_candidates阶段为这个候选者提供了背书签名。这两张表在同一笔交易中成对写入当process_candidates例程通过全部校验后“create an entry in thePendingAvailabilitymap for each backed candidate with a blankavailability_votesbitfield”并“create a corresponding entry in thePendingAvailabilityCommitmentswith the commitments”见 inclusion.md 的 process_candidates 步骤。因此两张表要么同时存在、要么同时不存在candidate_pending_availability用双重get串起两张表天然保证返回的收据是完整的。四、运行时实现从 API 层到 Pallet 层的调用链中继链运行时通过 runtime/parachains/src/runtime_api_impl/v5.rs 将上述 trait 方法映射到 inclusion pallet 的实现/// Implementation for the candidate_pending_availability function of the runtime API. pub fn candidate_pending_availabilityT: initializer::Config( para_id: ParaId, ) - OptionCommittedCandidateReceiptT::Hash { inclusion::PalletT::candidate_pending_availability(para_id) }而 inclusion pallet 中的 candidate_pending_availability 例程pub(crate)可见性正是前面展示的“双表拼装”逻辑。整条调用链可以概括为ParachainHost::candidate_pending_availability(para_id) └─ runtime_api_impl::v5::candidate_pending_availability::T(para_id) └─ inclusion::Pallet::T::candidate_pending_availability(para_id) ├─ PendingAvailability::T::get(para) // → descriptor └─ PendingAvailabilityCommitments::T::get(para) // → commitments从源码结构看这条链是纯读路径无状态变更因此该 API 适合在查询类场景中高频调用且与 implementers-guide 中该模块“All failed checks should lead to an unrecoverable error”的写入路径process_candidates、process_bitfields严格分离。此外inclusion pallet 还提供配套例程pending_availability(ParaId) - OptionCandidatePendingAvailability用于返回未拼装 commitments 的候选者元数据以及force_enact(ParaId)用于在运行时 API 执行等“状态变更将被丢弃”的场景下强制生效候选者inclusion.md 的 Routines 小节。五、各链运行时的导出与测试桩该 API 属于ParachainHost运行时 API即平行链宿主 API的一部分各中继链运行时均将其纳入实现并对外导出。从仓库搜索结果看runtime/polkadot/src/lib.rs、runtime/kusama/src/lib.rs、runtime/rococo/src/lib.rs、runtime/westend/src/lib.rs以及runtime/test-runtime/src/lib.rs中都引用了candidate_pending_availability表明 Polkadot、Kusama、Rococo、Westend 与测试运行时均导出了该接口。在测试与开发环境中node/service/src/fake_runtime_api.rs 提供了一个恒定返回None的模拟实现fn candidate_pending_availability(_: ParaId) - OptionCommittedCandidateReceiptHash { None }这保证了在没有真实运行时或运行时不包含完整 state的情况下依赖该 API 的节点流程也能以“无候选者待可用”的基线状态启动。六、节点侧消费路径Runtime API 子系统与缓存在节点侧candidate_pending_availability由runtime-api子系统封装为面向其他子系统的请求-响应服务。其核心链路位于 node/core/runtime-api/src/lib.rs子系统收到RuntimeApiRequest::CandidatePendingAvailability(para_id, tx)请求后通过RuntimeApiSubsystem的查询逻辑调用运行时 API并将结果回传给请求方查询结果会被写入缓存第 132 行附近通过cache_candidate_pending_availability((relay_parent, para_id), candidate)将“中继父区块 ParaId”二元组映射到候选者收据缓存实现见 node/core/runtime-api/src/cache.rs。由于同一 relay-parent 下候选者状态短期内稳定这种缓存能显著降低对运行时的重复调用开销。子系统对客户端的抽象定义在 node/subsystem-types/src/runtime_client.rsasync fn candidate_pending_availability( at: Hash, para_id: ParaId, ) - ResultOptionCommittedCandidateReceipt, ApiError { self.client.runtime_api().candidate_pending_availability(at, para_id) }与此同时node/subsystem-util/src/lib.rs 通过specialize_requests!宏为各子系统生成类型安全的请求辅助函数fn request_candidate_pending_availability(para_id: ParaId) - OptionCommittedCandidateReceipt; CandidatePendingAvailability;任何子系统只需持有RuntimeApiSender与 relay-parent 上下文即可通过request_candidate_pending_availability(para_id).await发起查询无需关心底层如何路由到运行时。节点侧测试验证node/core/runtime-api/src/tests.rs 中的requests_candidate_pending_availability测试演示了完整用法构造MockSubsystemClient向candidate_pending_availability映射预置一条CommittedCandidateReceipt然后启动子系统、发送请求并断言返回结果。该测试同时覆盖了“para 无待可用候选者时返回None”的边界情况第 650 行附近assert_eq!(rx.await.unwrap().unwrap(), None)与 API 文档语义occupied core 之外的 para 返回None形成对照验证。七、典型应用场景结合availability_cores与可用性流程candidate_pending_availability的语义与availability_cores()API 强耦合availability_cores返回每个核心的CoreStateOccupied/Free等而本 API 进一步揭示“被占用核心上的那个候选者具体长什么样”。从 implementers-guide 中 inclusion 模块的例程 可以梳理出它对应的完整生命周期写入阶段process_candidates通过全部检查后将每个已背书候选者写入PendingAvailability与PendingAvailabilityCommitments此时对应核心在availability_cores中呈现为 occupied可用性收集阶段验证者通过process_bitfields提交可用性比特每比特对应写入候选者的availability_votes当超过 2/3 验证者投票后候选者进入enact_candidate阶段存储被清理、核心被释放查询阶段在这两阶段之间任何需要“读取当前待可用候选者收据”的组件例如追踪候选者进度、准备后续 dispute 证据或做账本数据采集的子系统都可以调用candidate_pending_availability获取该 Para 的当前候选者收据候选者被生效或 session 变更清空存储后inclusion 模块在 Session Change 时会“Clear out all candidates pending availability”查询即返回None。从代码结构可以推断该 API 的典型消费者是那些需要与availability_cores配合、做只读状态审计的节点组件如 node/subsystem-util 中基于specialize_requests!的通用请求层它避免了直接读取 pallet 内部存储的私有结构为子系统提供了稳定、原子的数据视图。八、小结candidate_pending_availability虽然只有一行签名但其背后串联起了 Polkadot 中继链三条关键事实核心占用语义仅 occupied core 上的 para 有返回值、inclusion pallet 的双表存储PendingAvailabilityPendingAvailabilityCommitments以及节点子系统统一的运行时 API 请求通道runtime-api 子系统 缓存 请求宏。理解这条 API也就理解了中继链上“候选者被背书后、可用性确认前”这一关键状态窗口的数据表示与访问方式是深入阅读 implementers-guide 的 inclusion 章节 与 ParachainHost API 定义 时非常合适的切入点。赞分享区块链【免费下载链接】polkadotPolkadot Node Implementation项目地址https://gitcode.com/gh_mirrors/po/polkadot点击查看免费下载相关推荐Polkadot Candidates Included 运行时 API 详解本地查询候选人是否已被纳入链上Polkadot Candidates Included 运行时 API 详解本地查询候选人是否已被纳入链上 导读 CandidatesIncluded c区块链gws Google Workspace CLI 实战用 recipe-log-deal-update 将交易状态更新追加进 Google Sheets 销售追踪表gws Google Workspace CLI 实战用 recipe log deal update 将交易状态更新追加进 Google Sheets 销售区块链Vibe-Trading screen_market 完整指南免费一次调用拉出全市场行情排行榜Vibe Trading screen_market 完整指南免费一次调用拉出全市场行情排行榜 今天全市场谁涨得最猛哪些标的成交最活跃传统做法是循环候区块链上一篇Habitat-Sim 传感器配置详解RGB-D相机与运动感知的终极指南下一篇Atom Flight Manual查找替换与多光标编辑的12个进阶技巧从新手到高手的捷径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考