DMP follow-ups (#1875)

* remove pending TODO after the DMP impl merge

* DMP: Update the impl guide

* DMP: Incorporate XCM related changes into the guide

This is the DMP related part of https://github.com/paritytech/polkadot/issues/1702

polkadot/node/core/candidate-validation/src/lib.rs

@@ -285,9 +285,9 @@ async fn find_assumed_validation_data(
 	const ASSUMPTIONS: &[OccupiedCoreAssumption] = &[
 		OccupiedCoreAssumption::Included,
 		OccupiedCoreAssumption::TimedOut,
-		// TODO: Why don't we check `Free`? The guide assumes there are only two possible assumptions.
-		//
-		// Source that info and leave a comment here.
+		// `TimedOut` and `Free` both don't perform any speculation and therefore should be the same
+		// for our purposes here. In other words, if `TimedOut` matched then the `Free` must be
+		// matched as well.
 	];
 
 	// Consider running these checks in parallel to reduce validation latency.

polkadot/primitives/src/v1.rs

@@ -687,7 +687,6 @@ sp_api::decl_runtime_apis! {
 		fn persisted_validation_data(para_id: Id, assumption: OccupiedCoreAssumption)
 			-> Option<PersistedValidationData<N>>;
 
-		// TODO: Adding a Runtime API should be backwards compatible... right?
 		/// Checks if the given validation outputs pass the acceptance criteria.
 		fn check_validation_outputs(para_id: Id, outputs: ValidationOutputs) -> bool;
 

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

@@ -46,7 +46,7 @@ DownwardMessageQueues: map ParaId => Vec<InboundDownwardMessage>;
 /// - `prev_head`: is the previous head hash or zero if none.
 /// - `B`: is the relay-chain block number in which a message was appended.
 /// - `H(M)`: is the hash of the message being appended.
-DownwardMessageQueueHeads: map ParaId => Option<Hash>;
+DownwardMessageQueueHeads: map ParaId => Hash;
 ```
 
 ### HRMP

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

@@ -129,7 +129,7 @@ struct PersistedValidationData {
 	///
 	/// The DMQ MQC head will be used by the validation function to authorize the downward messages
 	/// passed by the collator.
-	dmq_mqc_head: Option<Hash>,
+	dmq_mqc_head: Hash,
 	/// The list of MQC heads for the inbound channels paired with the sender para ids. This
 	/// vector is sorted ascending by the para id and doesn't contain multiple entries with the same
 	/// sender.

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

@@ -5,6 +5,29 @@ Types of messages that are passed between parachains and the relay chain: UMP, D
 There is also HRMP (Horizontally Relay-routed Message Passing) which provides the same functionality
 although with smaller scalability potential.
 
+## Vertical Message Passing
+
+Types required for message passing between the relay-chain and a parachain.
+
+Actual contents of the messages is specified by the XCM standard.
+
+```rust,ignore
+/// A message sent from the relay-chain down to a parachain.
+///
+/// The size of the message is limited by the `config.max_downward_message_size`
+/// parameter.
+type DownwardMessage = Vec<u8>;
+
+/// This struct extends `DownwardMessage` by adding the relay-chain block number when the message was
+/// enqueued in the downward message queue.
+struct InboundDownwardMessage {
+	/// The block number at which this messages was put into the downward message queue.
+	pub sent_at: BlockNumber,
+	/// The actual downward message to processes.
+	pub msg: DownwardMessage,
+}
+```
+
 ## HrmpChannelId
 
 A type that uniquely identifies an HRMP channel. An HRMP channel is established between two paras.
@@ -105,32 +128,3 @@ struct InboundHrmpMessage {
 	pub data: Vec<u8>,
 }
 ```
-
-## Downward Message
-
-`DownwardMessage` - is a message that goes down from the relay chain to a parachain. Such a message
-could be seen as a notification, however, it is conceivable that they might be used by the relay
-chain to send a request to the parachain (likely, through the `ParachainSpecific` variant).
-
-The serialized size of the message is limited by the `config.critical_downward_message_size` parameter.
-
-```rust,ignore
-enum DownwardMessage {
-	/// Some funds were transferred into the parachain's account. The hash is the identifier that
-	/// was given with the transfer.
-	TransferInto(AccountId, Balance, Remark),
-	/// An opaque message which interpretation is up to the recipient para. This variant ought
-	/// to be used as a basis for special protocols between the relay chain and, typically system,
-	/// paras.
-	ParachainSpecific(Vec<u8>),
-}
-
-/// A wrapped version of `DownwardMessage`. The difference is that it has attached the block number when
-/// the message was sent.
-struct InboundDownwardMessage {
-	/// The block number at which this messages was put into the downward message queue.
-	pub sent_at: BlockNumber,
-	/// The actual downward message to processes.
-	pub msg: DownwardMessage,
-}
-```

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

@@ -61,7 +61,7 @@ struct HostConfiguration {
 	/// the PoV size. Of course, there is a lot of other different things that a parachain may
 	/// decide to do with its PoV so this value in practice will be picked as a fraction of the PoV
 	/// size.
-	pub critical_downward_message_size: u32,
+	pub max_downward_message_size: u32,
 	/// Number of sessions after which an HRMP open channel request expires.
 	pub hrmp_open_request_ttl: u32,
 	/// The deposit that the sender should provide for opening an HRMP channel.