Implementer's guide: Approval Voting Subsystem (#1691)

* add storage for approvals module

* basics of approval logic

* fix links

* Session info module

* create an approvals_inherent module

* integrate approvals module with inclusion

* Remove approvals runtime

* tweak mentions of on-chain logic

* add note on finality-grandpa voting rule

* elaborate on node-side components

* stub for availability recovery

* add another note on voting rule

* Beginnings of approval subsystems

* flesh out approval voting now

* logic for checking assignment certs

* initial scheduler logic

* scheduler logic

* adjst tranche taking logic

* approval voting import

* approval work (voting side)

* amend some TODOs

* mark some TODOs

* describe `ApprovedAncestor`

* reference protocol-approval.md

* clarity on bitfield

* remove approvals_inherent

* tweak session_info module according to review

* formatting & nits

Co-authored-by: Robert Habermeier <robert@Roberts-MacBook-Pro.local>

polkadot/roadmap/implementers-guide/src/runtime/inclusion.md

@@ -56,7 +56,6 @@ All failed checks should lead to an unrecoverable error making the block invalid
   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`.

polkadot/roadmap/implementers-guide/src/runtime/session_info.md

@@ -0,0 +1,55 @@
+# Session Info
+
+For disputes and approvals, we need access to information about validator sets from prior sessions. We also often want easy access to the same information about the current session's validator set. This module aggregates and stores this information in a rolling window while providing easy APIs for access.
+
+## Storage
+
+Helper structs:
+
+```rust
+struct SessionInfo {
+    // validators in canonical ordering.
+    validators: Vec<ValidatorId>,
+    // validators' authority discovery keys for the session in canonical ordering.
+    discovery_keys: Vec<DiscoveryId>,
+    // The assignment and approval keys for validators.
+    approval_keys: Vec<(AssignmentId, ApprovalId)>,
+    // validators in shuffled ordering - these are the validator groups as produced
+    // by the `Scheduler` module for the session and are typically referred to by
+    // `GroupIndex`.
+    validator_groups: Vec<Vec<ValidatorIndex>>,
+    // The number of availability cores used by the protocol during this session.
+    n_cores: u32,
+    // the zeroth delay tranche width.
+    zeroth_delay_tranche_width: u32,
+    // The number of samples we do of relay_vrf_modulo.
+    relay_vrf_modulo_samples: u32,
+    // The number of delay tranches in total.
+    n_delay_tranches: u32,
+    // How many slots (BABE / SASSAFRAS) must pass before an assignment is considered a
+    // no-show.
+    no_show_slots: u32,
+    /// The number of validators needed to approve a block.
+	needed_approvals: u32,
+}
+```
+
+Storage Layout: 
+
+```rust
+/// The earliest session for which previous session info is stored.
+EarliestStoredSession: SessionIndex,
+/// Session information. Should have an entry from `EarliestStoredSession..=CurrentSessionIndex`
+Sessions: map SessionIndex => Option<SessionInfo>,
+```
+
+## Session Change
+
+1. Update the `CurrentSessionIndex`.
+1. Update `EarliestStoredSession` based on `config.dispute_period` and remove all entries from `Sessions` from the previous value up to the new value.
+1. Create a new entry in `Sessions` with information about the current session.
+
+## Routines
+
+* `earliest_stored_session() -> SessionIndex`: Yields the earliest session for which we have information stored.
+* `session_info(session: SessionIndex) -> Option<SessionInfo>`: Yields the session info for the given session, if stored.