implement provisioner (#1473)

* sketch out provisioner basics * handle provisionable data * stub out select_inherent_data * split runtime APIs into sub-chapters to improve linkability * explain SignedAvailabilityBitfield semantics * add internal link to further documentation * some more work figuring out how the provisioner can do its thing * fix broken link * don't import enum variants where it's one layer deep * make request_availability_cores a free fn in util * document more precisely what should happen on block production * finish first-draft implementation of provisioner * start working on the full and proper backed candidate selection rule * Pass number of block under construction via RequestInherentData * Revert "Pass number of block under construction via RequestInherentData" This reverts commit 850fe62cc0dfb04252580c21a985962000e693c8. That initially looked like the better approach--it spent the time budget for fetching the block number in the proposer, instead of the provisioner, and that felt more appropriate--but it turns out not to be obvious how to get the block number of the block under construction from within the proposer. The Chain API may be less ideal, but it should be easier to implement. * wip: get the block under production from the Chain API * add ChainApiMessage to AllMessages * don't break the run loop if a provisionable data channel closes * clone only those backed candidates which are coherent * propagate chain_api subsystem through various locations * add delegated_subsystem! macro to ease delegating subsystems Unfortunately, it doesn't work right: ``` error[E0446]: private type `CandidateBackingJob` in public interface --> node/core/backing/src/lib.rs:775:1 | 86 | struct CandidateBackingJob { | - `CandidateBackingJob` declared as private ... 775 | delegated_subsystem!(CandidateBackingJob as CandidateBackingSubsystem); | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ can't leak private type ``` I'm not sure precisely what's going wrong, here; I suspect the problem is the use of `$job as JobTrait>::RunArgs` and `::ToJob`; the failure would be that it's not reifying the types to verify that the actual types are public, but instead referring to them via `CandidateBackingJob`, which is in fact private; that privacy is the point. Going to see if I can generic my way out of this, but we may be headed for a quick revert here. * fix delegated_subsystem The invocation is a bit more verbose than I'd prefer, but it's also more explicit about what types need to be public. I'll take it as a win. * add provisioning subsystem; reduce public interface of provisioner * deny missing docs in provisioner * refactor core selection per code review suggestion This is twice as much code when measured by line, but IMO it is in fact somewhat clearer to read, so overall a win. Also adds an improved rule for selecting availability bitfields, which (unlike the previous implementation) guarantees that the appropriate postconditions hold there. * fix bad merge double-declaration * update guide with (hopefully) complete provisioner candidate selection procedure * clarify candidate selection algorithm * Revert "clarify candidate selection algorithm" This reverts commit c68a02ac9cf42b3a4a28eb197d38633a40d0e3e6. * clarify candidate selection algorithm * update provisioner to implement candidate selection per the guide * add test that no more than one bitfield is selected per validator * add test that each selected bitfield corresponds to an occupied core * add test that more set bits win conflicts * add macro for specializing runtime requests; specailize all runtime requests * add tests harness for select_candidates tests * add first real select_candidates test, fix test_harness * add mock overseer and test that success is possible * add test that the candidate selection algorithm picks the right ones * make candidate selection test somewhat more stringent
2026-06-14 15:41:02 +00:00 · 2020-08-06 18:12:15 +02:00
parent 877a5059aa
commit 21cec309a4
23 changed files with 1434 additions and 380 deletions
@@ -0,0 +1,56 @@
+# Availability Cores
+
+Yields information on all availability cores. Cores are either free or occupied. Free cores can have paras assigned to them. Occupied cores don't, but they can become available part-way through a block due to bitfields and then have something scheduled on them. To allow optimistic validation of candidates, the occupied cores are accompanied by information on what is upcoming. This information can be leveraged when validators perceive that there is a high likelihood of a core becoming available based on bitfields seen, and then optimistically validate something that would become scheduled based on that, although there is no guarantee on what the block producer will actually include in the block.
+
+See also the [Scheduler Module](../runtime/scheduler.md) for a high-level description of what an availability core is and why it exists.
+
+```rust
+fn availability_cores(at: Block) -> Vec<CoreState>;
+```
+
+This is all the information that a validator needs about scheduling for the current block. It includes all information on [Scheduler](../runtime/scheduler.md) core-assignments and [Inclusion](../runtime/inclusion.md) state of blocks occupying availability cores. It includes data necessary to determine not only which paras are assigned now, but which cores are likely to become freed after processing bitfields, and exactly which bitfields would be necessary to make them so.
+
+```rust
+struct OccupiedCore {
+    /// The ID of the para occupying the core.
+    para_id: ParaId,
+    /// If this core is freed by availability, this is the assignment that is next up on this
+    /// core, if any. None if there is nothing queued for this core.
+    next_up_on_available: Option<ScheduledCore>,
+    /// The relay-chain block number this began occupying the core at.
+    occupied_since: BlockNumber,
+    /// The relay-chain block this will time-out at, if any.
+    time_out_at: BlockNumber,
+    /// If this core is freed by being timed-out, this is the assignment that is next up on this
+    /// core. None if there is nothing queued for this core or there is no possibility of timing
+    /// out.
+    next_up_on_time_out: Option<ScheduledCore>,
+    /// A bitfield with 1 bit for each validator in the set. `1` bits mean that the corresponding
+    /// validators has attested to availability on-chain. A 2/3+ majority of `1` bits means that
+    /// this will be available.
+    availability: Bitfield,
+    /// The group assigned to distribute availability pieces of this candidate.
+    group_responsible: GroupIndex,
+}
+
+struct ScheduledCore {
+    /// The ID of a para scheduled.
+    para_id: ParaId,
+    /// The collator required to author the block, if any.
+    collator: Option<CollatorId>,
+}
+
+enum CoreState {
+    /// The core is currently occupied.
+    Occupied(OccupiedCore),
+    /// The core is currently free, with a para scheduled and given the opportunity
+    /// to occupy.
+    ///
+    /// If a particular Collator is required to author this block, that is also present in this
+    /// variant.
+    Scheduled(ScheduledCore),
+    /// The core is currently free and there is nothing scheduled. This can be the case for parathread
+    /// cores when there are no parathread blocks queued. Parachain cores will never be left idle.
+    Free,
+}
+```