Inclusion Module

primitives/src/parachain.rs

@@ -176,20 +176,20 @@ pub struct DutyRoster {
 /// These are global parameters that apply to all parachain candidates in a block.
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug, Default))]
-pub struct GlobalValidationSchedule {
+pub struct GlobalValidationSchedule<N = BlockNumber> {
 	/// The maximum code size permitted, in bytes.
 	pub max_code_size: u32,
 	/// The maximum head-data size permitted, in bytes.
 	pub max_head_data_size: u32,
 	/// The relay-chain block number this is in the context of.
-	pub block_number: BlockNumber,
+	pub block_number: N,
 }
 
 /// Extra data that is needed along with the other fields in a `CandidateReceipt`
 /// to fully validate the candidate. These fields are parachain-specific.
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug, Default))]
-pub struct LocalValidationData {
+pub struct LocalValidationData<N = BlockNumber> {
 	/// The parent head-data.
 	pub parent_head: HeadData,
 	/// The balance of the parachain at the moment of validation.
@@ -205,28 +205,28 @@ pub struct LocalValidationData {
 	/// height. This may be equal to the current perceived relay-chain block height, in
 	/// which case the code upgrade should be applied at the end of the signaling
 	/// block.
-	pub code_upgrade_allowed: Option<BlockNumber>,
+	pub code_upgrade_allowed: Option<N>,
 }
 
 /// Commitments made in a `CandidateReceipt`. Many of these are outputs of validation.
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug, Default))]
-pub struct CandidateCommitments {
+pub struct CandidateCommitments<H = Hash> {
 	/// Fees paid from the chain to the relay chain validators.
 	pub fees: Balance,
 	/// Messages destined to be interpreted by the Relay chain itself.
 	pub upward_messages: Vec<UpwardMessage>,
 	/// The root of a block's erasure encoding Merkle tree.
-	pub erasure_root: Hash,
+	pub erasure_root: H,
 	/// New validation code.
 	pub new_validation_code: Option<ValidationCode>,
 }
 
 /// Get a collator signature payload on a relay-parent, block-data combo.
-pub fn collator_signature_payload(
-	relay_parent: &Hash,
+pub fn collator_signature_payload<H: AsRef<[u8]>>(
+	relay_parent: &H,
 	parachain_index: &Id,
-	pov_block_hash: &Hash,
+	pov_block_hash: &H,
 ) -> [u8; 68] {
 	// 32-byte hash length is protected in a test below.
 	let mut payload = [0u8; 68];
@@ -238,10 +238,10 @@ pub fn collator_signature_payload(
 	payload
 }
 
-fn check_collator_signature(
-	relay_parent: &Hash,
+fn check_collator_signature<H: AsRef<[u8]>>(
+	relay_parent: &H,
 	parachain_index: &Id,
-	pov_block_hash: &Hash,
+	pov_block_hash: &H,
 	collator: &CollatorId,
 	signature: &CollatorSignature,
 ) -> Result<(),()> {
@@ -258,29 +258,29 @@ fn check_collator_signature(
 /// All data pertaining to the execution of a parachain candidate.
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug, Default))]
-pub struct CandidateReceipt {
+pub struct CandidateReceipt<H = Hash, N = BlockNumber> {
 	/// The ID of the parachain this is a candidate for.
 	pub parachain_index: Id,
 	/// The hash of the relay-chain block this should be executed in
 	/// the context of.
-	pub relay_parent: Hash,
+	pub relay_parent: H,
 	/// The head-data
 	pub head_data: HeadData,
 	/// The collator's relay-chain account ID
 	pub collator: CollatorId,
 	/// Signature on blake2-256 of the block data by collator.
 	pub signature: CollatorSignature,
 	/// The hash of the PoV-block.
-	pub pov_block_hash: Hash,
+	pub pov_block_hash: H,
 	/// The global validation schedule.
-	pub global_validation: GlobalValidationSchedule,
+	pub global_validation: GlobalValidationSchedule<N>,
 	/// The local validation data.
-	pub local_validation: LocalValidationData,
+	pub local_validation: LocalValidationData<N>,
 	/// Commitments made as a result of validation.
-	pub commitments: CandidateCommitments,
+	pub commitments: CandidateCommitments<H>,
 }
 
-impl CandidateReceipt {
+impl<H: AsRef<[u8]>, N> CandidateReceipt<H, N> {
 	/// Check integrity vs. provided block data.
 	pub fn check_signature(&self) -> Result<(), ()> {
 		check_collator_signature(
@@ -294,7 +294,7 @@ impl CandidateReceipt {
 
 	/// Abridge this `CandidateReceipt`, splitting it into an `AbridgedCandidateReceipt`
 	/// and its omitted component.
-	pub fn abridge(self) -> (AbridgedCandidateReceipt, OmittedValidationData) {
+	pub fn abridge(self) -> (AbridgedCandidateReceipt<H>, OmittedValidationData<N>) {
 		let CandidateReceipt {
 			parachain_index,
 			relay_parent,
@@ -345,11 +345,11 @@ impl Ord for CandidateReceipt {
 /// is necessary for validation of the parachain candidate.
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug, Default))]
-pub struct OmittedValidationData {
+pub struct OmittedValidationData<N = BlockNumber> {
 	/// The global validation schedule.
-	pub global_validation: GlobalValidationSchedule,
+	pub global_validation: GlobalValidationSchedule<N>,
 	/// The local validation data.
-	pub local_validation: LocalValidationData,
+	pub local_validation: LocalValidationData<N>,
 }
 
 /// An abridged candidate-receipt.
@@ -359,27 +359,38 @@ pub struct OmittedValidationData {
 /// be re-generated from relay-chain state.
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug, Default))]
-pub struct AbridgedCandidateReceipt {
+pub struct AbridgedCandidateReceipt<H = Hash> {
 	/// The ID of the parachain this is a candidate for.
 	pub parachain_index: Id,
 	/// The hash of the relay-chain block this should be executed in
 	/// the context of.
 	// NOTE: the fact that the hash includes this value means that code depends
 	// on this for deduplication. Removing this field is likely to break things.
-	pub relay_parent: Hash,
+	pub relay_parent: H,
 	/// The head-data
 	pub head_data: HeadData,
 	/// The collator's relay-chain account ID
 	pub collator: CollatorId,
 	/// Signature on blake2-256 of the block data by collator.
 	pub signature: CollatorSignature,
 	/// The hash of the pov-block.
-	pub pov_block_hash: Hash,
+	pub pov_block_hash: H,
 	/// Commitments made as a result of validation.
-	pub commitments: CandidateCommitments,
+	pub commitments: CandidateCommitments<H>,
 }
 
-impl AbridgedCandidateReceipt {
+impl<H: AsRef<[u8]> + Encode> AbridgedCandidateReceipt<H> {
+	/// Check integrity vs. provided block data.
+	pub fn check_signature(&self) -> Result<(), ()> {
+		check_collator_signature(
+			&self.relay_parent,
+			&self.parachain_index,
+			&self.pov_block_hash,
+			&self.collator,
+			&self.signature,
+		)
+	}
+
 	/// Compute the hash of the abridged candidate receipt.
 	///
 	/// This is often used as the canonical hash of the receipt, rather than
@@ -391,10 +402,12 @@ impl AbridgedCandidateReceipt {
 		use runtime_primitives::traits::{BlakeTwo256, Hash};
 		BlakeTwo256::hash_of(self)
 	}
+}
 
+impl AbridgedCandidateReceipt {
 	/// Combine the abridged candidate receipt with the omitted data,
 	/// forming a full `CandidateReceipt`.
-	pub fn complete(self, omitted: OmittedValidationData) -> CandidateReceipt {
+	pub fn complete<N>(self, omitted: OmittedValidationData) -> CandidateReceipt {
 		let AbridgedCandidateReceipt {
 			parachain_index,
 			relay_parent,
@@ -607,13 +620,42 @@ pub enum ValidityAttestation {
 	Explicit(ValidatorSignature),
 }
 
+impl ValidityAttestation {
+	/// Get a reference to the signature.
+	pub fn signature(&self) -> &ValidatorSignature {
+		match *self {
+			ValidityAttestation::Implicit(ref sig) => sig,
+			ValidityAttestation::Explicit(ref sig) => sig,
+		}
+	}
+
+	/// Produce the underlying signed payload of the attestation, given the hash of the candidate,
+	/// which should be known in context.
+	pub fn signed_payload<H: Encode>(
+		&self,
+		candidate_hash: Hash,
+		signing_context: &SigningContext<H>,
+	) -> Vec<u8> {
+		match *self {
+			ValidityAttestation::Implicit(_) => (
+				Statement::Candidate(candidate_hash),
+				signing_context,
+			).encode(),
+			ValidityAttestation::Explicit(_) => (
+				Statement::Valid(candidate_hash),
+				signing_context,
+			).encode(),
+		}
+	}
+}
+
 /// A type returned by runtime with current session index and a parent hash.
 #[derive(Clone, Eq, PartialEq, Default, Decode, Encode, RuntimeDebug)]
-pub struct SigningContext {
+pub struct SigningContext<H = Hash> {
 	/// Current session index.
 	pub session_index: sp_staking::SessionIndex,
 	/// Hash of the parent.
-	pub parent_hash: Hash,
+	pub parent_hash: H,
 }
 
 /// An attested candidate. This is submitted to the relay chain by a block author.
@@ -661,6 +703,147 @@ impl FeeSchedule {
 	}
 }
 
+/// A bitfield concerning availability of backed candidates.
+#[derive(PartialEq, Eq, Clone, Encode, Decode)]
+#[cfg_attr(feature = "std", derive(Debug))]
+pub struct AvailabilityBitfield(pub BitVec<bitvec::order::Lsb0, u8>);
+
+impl From<BitVec<bitvec::order::Lsb0, u8>> for AvailabilityBitfield {
+	fn from(inner: BitVec<bitvec::order::Lsb0, u8>) -> Self {
+		AvailabilityBitfield(inner)
+	}
+}
+
+impl AvailabilityBitfield {
+	/// Encodes the signing payload into the given buffer.
+	pub fn encode_signing_payload_into<H: Encode>(
+		&self,
+		signing_context: &SigningContext<H>,
+		buf: &mut Vec<u8>,
+	) {
+		self.0.encode_to(buf);
+		signing_context.encode_to(buf);
+	}
+
+	/// Encodes the signing payload into a fresh byte-vector.
+	pub fn encode_signing_payload<H: Encode>(
+		&self,
+		signing_context:
+		&SigningContext<H>,
+	) -> Vec<u8> {
+		let mut v = Vec::new();
+		self.encode_signing_payload_into(signing_context, &mut v);
+		v
+	}
+}
+
+/// A bitfield signed by a particular validator about the availability of pending candidates.
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug)]
+pub struct SignedAvailabilityBitfield {
+	/// The index of the validator in the current set.
+	pub validator_index: ValidatorIndex,
+	/// The bitfield itself, with one bit per core. Only occupied cores may have the `1` bit set.
+	pub bitfield: AvailabilityBitfield,
+	/// The signature by the validator on the bitfield's signing payload. The context of the signature
+	/// should be apparent when checking the signature.
+	pub signature: ValidatorSignature,
+}
+
+/// Check a signature on an availability bitfield. Provide the bitfield, the validator who signed it,
+/// the signature, the signing context, and an optional buffer in which to encode.
+///
+/// If the buffer is provided, it is assumed to be empty.
+pub fn check_availability_bitfield_signature<H: Encode>(
+	bitfield: &AvailabilityBitfield,
+	validator: &ValidatorId,
+	signature: &ValidatorSignature,
+	signing_context: &SigningContext<H>,
+	payload_encode_buf: Option<&mut Vec<u8>>,
+) -> Result<(),()> {
+	use runtime_primitives::traits::AppVerify;
+
+	let mut v = Vec::new();
+	let payload_encode_buf = payload_encode_buf.unwrap_or(&mut v);
+
+	bitfield.encode_signing_payload_into(signing_context, payload_encode_buf);
+
+	if signature.verify(&payload_encode_buf[..], validator) {
+		Ok(())
+	} else {
+		Err(())
+	}
+}
+
+/// A set of signed availability bitfields. Should be sorted by validator index, ascending.
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug)]
+pub struct SignedAvailabilityBitfields(pub Vec<SignedAvailabilityBitfield>);
+
+/// A backed (or backable, depending on context) candidate.
+// TODO: yes, this is roughly the same as AttestedCandidate.
+// After https://github.com/paritytech/polkadot/issues/1250
+// they should be unified to this type.
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug)]
+pub struct BackedCandidate<H = Hash> {
+	/// The candidate referred to.
+	pub candidate: AbridgedCandidateReceipt<H>,
+	/// The validity votes themselves, expressed as signatures.
+	pub validity_votes: Vec<ValidityAttestation>,
+	/// The indices of the validators within the group, expressed as a bitfield.
+	pub validator_indices: BitVec<bitvec::order::Lsb0, u8>,
+}
+
+/// Verify the backing of the given candidate.
+///
+/// Provide a lookup from the index of a validator within the group assigned to this para,
+/// as opposed to the index of the validator within the overall validator set, as well as
+/// the number of validators in the group.
+///
+/// Also provide the signing context.
+///
+/// Returns either an error, indicating that one of the signatures was invalid or that the index
+/// was out-of-bounds, or the number of signatures checked.
+pub fn check_candidate_backing<H: AsRef<[u8]> + Encode>(
+	backed: &BackedCandidate<H>,
+	signing_context: &SigningContext<H>,
+	group_len: usize,
+	validator_lookup: impl Fn(usize) -> Option<ValidatorId>,
+) -> Result<usize, ()> {
+	use runtime_primitives::traits::AppVerify;
+
+	if backed.validator_indices.len() != group_len {
+		return Err(())
+	}
+
+	if backed.validity_votes.len() > group_len {
+		return Err(())
+	}
+
+	// this is known, even in runtime, to be blake2-256.
+	let hash: Hash = backed.candidate.hash();
+
+	let mut signed = 0;
+	for ((val_in_group_idx, _), attestation) in backed.validator_indices.iter().enumerate()
+		.filter(|(_, signed)| **signed)
+		.zip(backed.validity_votes.iter())
+	{
+		let validator_id = validator_lookup(val_in_group_idx).ok_or(())?;
+		let payload = attestation.signed_payload(hash.clone(), signing_context);
+		let sig = attestation.signature();
+
+		if sig.verify(&payload[..], &validator_id) {
+			signed += 1;
+		} else {
+			return Err(())
+		}
+	}
+
+	if signed != backed.validity_votes.len() {
+		return Err(())
+	}
+
+	Ok(signed)
+}
+
 sp_api::decl_runtime_apis! {
 	/// The API for querying the state of parachains on-chain.
 	#[api_version(3)]

roadmap/implementors-guide/src/runtime/README.md

@@ -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,
 }
 ```