Include a reference to the validation data in the candidate descriptor (#1442)

* rename GlobalValidationSchedule to GlobalValidationData

* guide: update candidate descriptor to contain validation data hash

* guide: add note in inclusion module about checking validation data hash

* primitives: update CandidateDescriptor to contain new hash

* fix payload computation

* add helpers for computing validation data to runtime modules

* guide: note routines

* inclusion: check validation data hash and fix local_validation_data bug

* add a case to candidate_checks and improve that test substantially

* bump versions

* address review comments

* add a test for including code upgrade

* bump kusama version

* bump westend & polkadot versions

polkadot/roadmap/implementers-guide/src/runtime-api/README.md

@@ -137,10 +137,10 @@ enum CoreState {
 
 ## Global Validation Schedule
 
-Yields the [`GlobalValidationSchedule`](../types/candidate.md#globalvalidationschedule) at the state of a given block. This applies to all para candidates with the relay-parent equal to that block.
+Yields the [`GlobalValidationData`](../types/candidate.md#globalvalidationschedule) at the state of a given block. This applies to all para candidates with the relay-parent equal to that block.
 
 ```rust
-fn global_validation_schedule(at: Block) -> GlobalValidationSchedule;
+fn global_validation_data(at: Block) -> GlobalValidationData;
 ```
 
 ## Local Validation Data

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

@@ -35,6 +35,9 @@ fn update_configuration(f: impl FnOnce(&mut HostConfiguration)) {
     *pending = Some(x);
   })
 }
+
+/// Get the GlobalValidationData, assuming the context is the parent block.
+fn global_validation_data() -> GlobalValidationData;
 ```
 
 ## Entry-points

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

@@ -62,6 +62,7 @@ All failed checks should lead to an unrecoverable error making the block invalid
   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. check that each candidate's `validation_data_hash` corresponds to a `(LocalValidationData, GlobalValidationData)` computed from the current state.
   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.

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

@@ -112,6 +112,7 @@ OutgoingParas: Vec<ParaId>;
 * `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.
+* `local_validation_data(id: ParaId) -> Option<LocalValidationData>`: Get the LocalValidationData of the given para, assuming the context is the parent block. Returns `None` if the para is not known.
 
 ## Finalization
 

polkadot/roadmap/implementers-guide/src/types/availability.md

@@ -26,12 +26,12 @@ struct PoV(Vec<u8>);
 
 Validation data that is often omitted from types describing candidates as it can be derived from the relay-parent of the candidate. However, with the expectation of state pruning, these are best kept available elsewhere as well.
 
-This contains the [`GlobalValidationSchedule`](candidate.md#globalvalidationschedule) and [`LocalValidationData`](candidate.md#localvalidationdata)
+This contains the [`GlobalValidationData`](candidate.md#globalvalidationschedule) and [`LocalValidationData`](candidate.md#localvalidationdata)
 
 ```rust
 struct OmittedValidationData {
     /// The global validation schedule.
-    global_validation: GlobalValidationSchedule,
+    global_validation: GlobalValidationData,
     /// The local validation data.
     local_validation: LocalValidationData,
 }

polkadot/roadmap/implementers-guide/src/types/candidate.md

@@ -33,7 +33,7 @@ struct CandidateReceipt {
 
 ## Full Candidate Receipt
 
-This is the full receipt type. The `GlobalValidationSchedule` and the `LocalValidationData` are technically redundant with the `inner.relay_parent`, which uniquely describes the a block in the blockchain from whose state these values are derived. The [`CandidateReceipt`](#candidate-receipt) variant is often used instead for this reason.
+This is the full receipt type. The `GlobalValidationData` and the `LocalValidationData` are technically redundant with the `inner.relay_parent`, which uniquely describes the a block in the blockchain from whose state these values are derived. The [`CandidateReceipt`](#candidate-receipt) variant is often used instead for this reason.
 
 However, the Full Candidate Receipt type is useful as a means of avoiding the implicit dependency on availability of old blockchain state. In situations such as availability and approval, having the full description of the candidate within a self-contained struct is convenient.
 
@@ -42,7 +42,7 @@ However, the Full Candidate Receipt type is useful as a means of avoiding the im
 struct FullCandidateReceipt {
 	inner: CandidateReceipt,
 	/// The global validation schedule.
-	global_validation: GlobalValidationSchedule,
+	global_validation: GlobalValidationData,
 	/// The local validation data.
 	local_validation: LocalValidationData,
 }
@@ -77,16 +77,19 @@ struct CandidateDescriptor {
 	relay_parent: Hash,
 	/// The collator's sr25519 public key.
 	collator: CollatorId,
-	/// Signature on blake2-256 of components of this receipt:
-	/// The parachain index, the relay parent, and the pov_hash.
-	signature: CollatorSignature,
+	/// The blake2-256 hash of the validation data. These are extra parameters
+	/// derived from relay-chain state that influence the validity of the block.
+	validation_data_hash: Hash,
 	/// The blake2-256 hash of the pov-block.
 	pov_hash: Hash,
+	/// Signature on blake2-256 of components of this receipt:
+	/// The parachain index, the relay parent, the validation data hash, and the pov_hash.
+	signature: CollatorSignature,
 }
 ```
 
 
-## GlobalValidationSchedule
+## GlobalValidationData
 
 The global validation schedule comprises of information describing the global environment for para execution, as derived from a particular relay-parent. These are parameters that will apply to all parablocks executed in the context of this relay-parent.
 
@@ -95,7 +98,7 @@ The global validation schedule comprises of information describing the global en
 /// to fully validate the candidate.
 ///
 /// These are global parameters that apply to all candidates in a block.
-struct GlobalValidationSchedule {
+struct GlobalValidationData {
 	/// The maximum code size permitted, in bytes.
 	max_code_size: u32,
 	/// The maximum head-data size permitted, in bytes.
@@ -197,7 +200,7 @@ struct ValidationOutputs {
 	/// The head-data produced by validation.
 	head_data: HeadData,
 	/// The global validation schedule.
-	global_validation_schedule: GlobalValidationSchedule,
+	global_validation_data: GlobalValidationData,
 	/// The local validation data.
 	local_validation_data: LocalValidationData,
 	/// Upwards messages to the relay chain.

polkadot/roadmap/implementers-guide/src/types/overseer-protocol.md

@@ -255,7 +255,7 @@ enum RuntimeApiRequest {
 	/// Get the validation code for a specific para, using the given occupied core assumption.
 	ValidationCode(ParaId, OccupiedCoreAssumption, ResponseChannel<Option<ValidationCode>>),
 	/// Get the global validation schedule at the state of a given block.
-	GlobalValidationSchedule(ResponseChannel<GlobalValidationSchedule>),
+	GlobalValidationData(ResponseChannel<GlobalValidationData>),
 	/// Get the local validation data for a specific para, with the given occupied core assumption.
 	LocalValidationData(
 		ParaId,