I am dumb and can't spell (#1366)

* rename implementor's guide to implementer's guide * fix typos in more places
2026-07-20 23:15:42 +00:00 · 2020-07-07 10:10:36 -04:00
parent 37da08a764
commit 42bd096413
54 changed files with 5 additions and 5 deletions
@@ -0,0 +1,87 @@
+# Inclusion Module
+
+The inclusion module is responsible for inclusion and availability of scheduled parachains and parathreads.
+
+## Storage
+
+Helper structs:
+
+```rust
+struct AvailabilityBitfield {
+  bitfield: BitVec, // one bit per core.
+  submitted_at: BlockNumber, // for accounting, as meaning of bits may change over time.
+}
+
+struct CandidatePendingAvailability {
+  core: CoreIndex, // availability core
+  receipt: CandidateReceipt,
+  availability_votes: Bitfield, // one bit per validator.
+  relay_parent_number: BlockNumber, // number of the relay-parent.
+  backed_in_number: BlockNumber,
+}
+```
+
+Storage Layout:
+
+```rust
+/// 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;
+
+/// The current validators, by their parachain session keys.
+Validators: Vec<ValidatorId>;
+
+/// The current session index.
+CurrentSessionIndex: SessionIndex;
+```
+
+## Session Change
+
+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
+
+All failed checks should lead to an unrecoverable error making the block invalid.
+
+* `process_bitfields(Bitfields, core_lookup: Fn(CoreIndex) -> Option<ParaId>)`:
+  1. check that the number of bitfields and bits in each bitfield is correct.
+  1. check that there are no duplicates
+  1. check all validator signatures.
+  1. apply each bit of bitfield to the corresponding pending candidate. looking up parathread cores using the `core_lookup`. Disregard bitfields that have a `1` bit for any free cores.
+  1. For each applied bit of each availability-bitfield, set the bit for the validator in the `CandidatePendingAvailability`'s `availability_votes` bitfield. Track all candidates that now have >2/3 of bits set in their `availability_votes`. These candidates are now available and can be enacted.
+  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>, 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 candidate data.
+  1. Transform each [`CommittedCandidateReceipt`](../types/candidate.md#committed-candidate-receipt) into the corresponding [`CandidateReceipt`](../types/candidate.md#candidate-receipt), setting the commitments aside.
+  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. create a corresponding entry in the `PendingAvailabilityCommitments` with the commitments.
+  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, CommittedCandidateReceipt)`:
+  1. If the receipt contains a code upgrade, Call `Paras::schedule_code_upgrade(para_id, code, relay_parent_number + config.validationl_upgrade_delay)`.
+    > TODO: Note that this is safe as long as we never enact candidates where the relay parent is across a session boundary. In that case, which we should be careful to avoid with contextual execution, the configuration might have changed and the para may de-sync from the host's understanding of it.
+  1. call `Router::queue_upward_messages` for each backed candidate, using the [`UpwardMessage`s](../types/messages.md#upward-message) from the [`CandidateCommitments`](../types/candidate.md#candidate-commitments).
+  1. Call `Paras::note_new_head` using the `HeadData` from the receipt and `relay_parent_number`.
+* `collect_pending`:
+
+  ```rust
+    fn collect_pending(f: impl Fn(CoreIndex, BlockNumber) -> bool) -> Vec<u32> {
+      // sweep through all paras pending availability. if the predicate returns true, when given the core index and
+      // the block number the candidate has been pending availability since, then clean up the corresponding storage for that candidate.
+      // return a vector of cleaned-up core IDs.
+    }
+  ```