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

polkadot/runtime/parachains/src/inclusion_inherent.rs

@@ -0,0 +1,120 @@
+// Copyright 2020 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Provides glue code over the scheduler and inclusion modules, and accepting
+//! one inherent per block that can include new para candidates and bitfields.
+//!
+//! Unlike other modules in this crate, it does not need to be initialized by the initializer,
+//! as it has no initialization logic and its finalization logic depends only on the details of
+//! this module.
+
+use sp_std::prelude::*;
+use primitives::{
+	parachain::{BackedCandidate, SignedAvailabilityBitfields},
+};
+use frame_support::{
+	decl_storage, decl_module, decl_error, ensure,
+	dispatch::DispatchResult,
+	weights::{DispatchClass, Weight},
+	traits::Get,
+};
+use system::ensure_none;
+use crate::{inclusion, scheduler::{self, FreedReason}};
+
+pub trait Trait: inclusion::Trait + scheduler::Trait { }
+
+decl_storage! {
+	trait Store for Module<T: Trait> as ParaInclusionInherent {
+		/// Whether the inclusion inherent was included within this block.
+		///
+		/// The `Option<()>` is effectively a bool, but it never hits storage in the `None` variant
+		/// due to the guarantees of FRAME's storage APIs.
+		///
+		/// If this is `None` at the end of the block, we panic and render the block invalid.
+		Included: Option<()>;
+	}
+}
+
+decl_error! {
+	pub enum Error for Module<T: Trait> {
+		/// Inclusion inherent called more than once per block.
+		TooManyInclusionInherents,
+	}
+}
+
+decl_module! {
+	/// The inclusion inherent module.
+	pub struct Module<T: Trait> for enum Call where origin: <T as system::Trait>::Origin {
+		type Error = Error<T>;
+
+		fn on_initialize() -> Weight {
+			T::DbWeight::get().reads_writes(1, 1) // in on_finalize.
+		}
+
+		fn on_finalize() {
+			if Included::take().is_none() {
+				panic!("Bitfields and heads must be included every block");
+			}
+		}
+
+		/// Include backed candidates and bitfields.
+		#[weight = (1_000_000_000, DispatchClass::Mandatory)]
+		pub fn inclusion(
+			origin,
+			signed_bitfields: SignedAvailabilityBitfields,
+			backed_candidates: Vec<BackedCandidate<T::Hash>>,
+		) -> DispatchResult {
+			ensure_none(origin)?;
+			ensure!(!<Included>::exists(), Error::<T>::TooManyInclusionInherents);
+
+			// Process new availability bitfields, yielding any availability cores whose
+			// work has now concluded.
+			let freed_concluded = <inclusion::Module<T>>::process_bitfields(
+				signed_bitfields,
+				<scheduler::Module<T>>::core_para,
+			)?;
+
+			// Handle timeouts for any availability core work.
+			let availability_pred = <scheduler::Module<T>>::availability_timeout_predicate();
+			let freed_timeout = if let Some(pred) = availability_pred {
+				<inclusion::Module<T>>::collect_pending(pred)
+			} else {
+				Vec::new()
+			};
+
+			// Schedule paras again, given freed cores, and reasons for freeing.
+			let freed = freed_concluded.into_iter().map(|c| (c, FreedReason::Concluded))
+				.chain(freed_timeout.into_iter().map(|c| (c, FreedReason::TimedOut)));
+
+			<scheduler::Module<T>>::schedule(freed.collect());
+
+			// Process backed candidates according to scheduled cores.
+			let occupied = <inclusion::Module<T>>::process_candidates(
+				backed_candidates,
+				<scheduler::Module<T>>::scheduled(),
+				<scheduler::Module<T>>::group_validators,
+			)?;
+
+			// Note which of the scheduled cores were actually occupied by a backed candidate.
+			<scheduler::Module<T>>::occupied(&occupied);
+
+			// And track that we've finished processing the inherent for this block.
+			Included::set(Some(()));
+
+			Ok(())
+		}
+	}
+}