Inclusion Module (#1242)

* add availability bitfield types to primitives * begin inclusion module * use GitHub issue link for limitation * fix some compiler errors * integrate validators into initializer * add generic signing context * make signing-context more generic * fix issues with inclusion module * add TODO * guide: add validators and session index to inclusion * guide: add session index to change notification * implement session change logic * add BackedCandidate type * guide: refine inclusion pipeline * guide: rename group_on to group_validators * guide: add check about collator for parathread * guide: add last_code_upgrade to paras and use in inclusion * implement Paras::last_code_upgrade * implement most checks in process_candidates * make candidate receipt structs more generic * make BackedCandidate struct more generic * use hash param, not block number * check that candidate is in context of the parent block * include inclusion module in initializer * implement enact-candidate * check that only occupied cores have bits set * finish implementing bitfield processing * restructure consistency checks on candidates * make some more primitives generic * signature checking logic for backed candidates * finish implementing process_candidates * implement collect_pending * add some trait implementations to primitives * implement InclusionInherent and squash warnings * test bitfield signing checks * rename parachain head to para_head * fix note_new_head bug in paras * test bitfield enactment in inclusion * helpers for candidate checks * add test for most candidate checks * add test for backing setting storage * test session change logic * remove extraneous type parameter * remove some allow(unused)s * extract threshold computation to const fn * remove some more allow(unused)s * improve doc * add debug assertion * fix primitive test compilation * tag unanimous variant as unused
2026-05-30 18:41:03 +00:00 · 2020-06-18 19:38:07 -04:00
parent 7accc6e499
commit 879892d3f9
12 changed files with 1969 additions and 74 deletions
@@ -48,6 +48,8 @@ struct SessionChangeNotification {
 new_config: HostConfiguration,
 // A secure randomn seed for the session, gathered from BABE.
 random_seed: [u8; 32],
+ // The session index of the beginning session.
+ session_index: SessionIndex,
 }
 ```

@@ -28,6 +28,12 @@ Storage Layout:
 bitfields: map ValidatorIndex => AvailabilityBitfield;
 /// Candidates pending availability.
 PendingAvailability: map ParaId => CandidatePendingAvailability;
+
+/// The current validators, by their parachain session keys.
+Validators: Vec<ValidatorId>;
+
+/// The current session index.
+CurrentSessionIndex: SessionIndex;
 ```

 > TODO: `CandidateReceipt` and `AbridgedCandidateReceipt` can contain code upgrades which make them very large. the code entries should be split into a different storage map with infrequent access patterns
@@ -36,6 +42,8 @@ PendingAvailability: map ParaId => CandidatePendingAvailability;

 1. Clear out all candidates pending availability.
 1. Clear out all validator bitfields.
+1. Update `Validators` with the validators from the session change notification.
+1. Update `CurrentSessionIndex` with the session index from the session change notification.

 ## Routines

@@ -50,11 +58,15 @@ All failed checks should lead to an unrecoverable error making the block invalid
  1. For all now-available candidates, invoke the `enact_candidate` routine with the candidate and relay-parent number.
  1. > TODO: pass it onwards to `Validity` module.
  1. Return a list of freed cores consisting of the cores where candidates have become available.
-* `process_candidates(BackedCandidates, scheduled: Vec<CoreAssignment>)`:
-  1. check that each candidate corresponds to a scheduled core and that they are ordered in ascending order by `ParaId`.
-  1. Ensure that any code upgrade scheduled by the candidate does not happen within `config.validation_upgrade_frequency` of the currently scheduled upgrade, if any, comparing against the value of `Paras::FutureCodeUpgrades` for the given para ID.
-  1. check the backing of the candidate using the signatures and the bitfields.
-  1. check that the upward messages are not exceeding `config.max_upward_queue_count` and `config.watermark_upward_queue_size` parameters.
+* `process_candidates(BackedCandidates, scheduled: Vec<CoreAssignment>, group_validators: Fn(GroupIndex) -> Option<Vec<ValidatorIndex>>)`:
+  1. check that each candidate corresponds to a scheduled core and that they are ordered in the same order the cores appear in assignments in `scheduled`.
+  1. check that `scheduled` is sorted ascending by `CoreIndex`, without duplicates.
+  1. check that there is no candidate pending availability for any scheduled `ParaId`.
+  1. If the core assignment includes a specific collator, ensure the backed candidate is issued by that collator.
+  1. Ensure that any code upgrade scheduled by the candidate does not happen within `config.validation_upgrade_frequency` of `Paras::last_code_upgrade(para_id, true)`, if any, comparing against the value of `Paras::FutureCodeUpgrades` for the given para ID.
+  1. Check the collator's signature on the pov block.
+  1. check the backing of the candidate using the signatures and the bitfields, comparing against the validators assigned to the groups, fetched with the `group_validators` lookup.
+  1. check that the upward messages, when combined with the existing queue size, are not exceeding `config.max_upward_queue_count` and `config.watermark_upward_queue_size` parameters.
  1. create an entry in the `PendingAvailability` map for each backed candidate with a blank `availability_votes` bitfield.
  1. Return a `Vec<CoreIndex>` of all scheduled cores of the list of passed assignments that a candidate was successfully backed for, sorted ascending by CoreIndex.
 * `enact_candidate(relay_parent_number: BlockNumber, AbridgedCandidateReceipt)`:
@@ -16,9 +16,10 @@ Included: Option<()>,

 ## Entry Points

-* `inclusion`: This entry-point accepts two parameters: [`Bitfields`](../types/availability.html#signed-availability-bitfield) and [`BackedCandidates`](../types/backing.html#backed-candidate).
-    1. The `Bitfields` are first forwarded to the `process_bitfields` routine, returning a set of freed cores. Provide a `Scheduler::core_para` as a core-lookup to the `process_bitfields` routine. Annotate each of these freed cores with `FreedReason::Concluded`.
+* `inclusion`: This entry-point accepts two parameters: [`Bitfields`](../types/availability.html#signed-availability-bitfield) and [`BackedCandidates`](../type-definitions.html#backed-candidate).
+    1. The `Bitfields` are first forwarded to the `Inclusion::process_bitfields` routine, returning a set of freed cores. Provide a `Scheduler::core_para` as a core-lookup to the `process_bitfields` routine. Annotate each of these freed cores with `FreedReason::Concluded`.
    1. If `Scheduler::availability_timeout_predicate` is `Some`, invoke `Inclusion::collect_pending` using it, and add timed-out cores to the free cores, annotated with `FreedReason::TimedOut`.
    1. Invoke `Scheduler::schedule(freed)`
-    1. Call `Scheduler::occupied` for all scheduled cores where a backed candidate was submitted.
+	1. Invoke the `Inclusion::process_candidates` routine with the parameters `(backed_candidates, Scheduler::scheduled(), Scheduler::group_validators)`.
+    1. Call `Scheduler::occupied` using the return value of the `Inclusion::process_candidates` call above, first sorting the list of assigned core indices.
    1. If all of the above succeeds, set `Included` to `Some(())`.
@@ -111,6 +111,8 @@ OutgoingParas: Vec<ParaId>;
 * `validation_code_at(ParaId, at: BlockNumber, assume_intermediate: Option<BlockNumber>)`: Fetches the validation code to be used when validating a block in the context of the given relay-chain height. A second block number parameter may be used to tell the lookup to proceed as if an intermediate parablock has been included at the given relay-chain height. This may return past, current, or (with certain choices of `assume_intermediate`) future code. `assume_intermediate`, if provided, must be before `at`. If the validation code has been pruned, this will return `None`.
 * `is_parathread(ParaId) -> bool`: Returns true if the para ID references any live parathread.

+* `last_code_upgrade(id: ParaId, include_future: bool) -> Option<BlockNumber>`: The block number of the last scheduled upgrade of the requested para. Includes future upgrades if the flag is set. This is the `expected_at` number, not the `activated_at` number.
+
 ## Finalization

 No finalization routine runs for this module.