Integrate DMP into PersistentValidationData (#1666)

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

@@ -23,8 +23,23 @@ NeedsDispatch: Vec<ParaId>;
 /// This is the para that gets will get dispatched first during the next upward dispatchable queue
 /// execution round.
 NextDispatchRoundStartWith: Option<ParaId>;
+```
+
+### Downward Message Passing (DMP)
+
+Storage layout required for implementation of DMP.
+
+```rust
 /// The downward messages addressed for a certain para.
-DownwardMessageQueues: map ParaId => Vec<DownwardMessage>;
+DownwardMessageQueues: map ParaId => Vec<InboundDownwardMessage>;
+/// A mapping that stores the downward message queue MQC head for each para.
+///
+/// Each link in this chain has a form:
+/// `(prev_head, B, H(M))`, where
+/// - `prev_head`: is the previous head hash.
+/// - `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>;
 ```
 
 ### HRMP
@@ -236,12 +251,20 @@ any of dispatchables return an error.
       1. If `RelayDispatchQueues` for `P` became empty, remove `P` from `NeedsDispatch`.
       1. If `NeedsDispatch` became empty then finish processing and set `NextDispatchRoundStartWith` to `None`.
 
+Utility routines.
+
+`queue_downward_message(P: ParaId, M: DownwardMessage)`:
+    1. Wrap `M` into `InboundDownwardMessage` using the current block number for `sent_at`.
+    1. Obtain a new MQC link for the resulting `InboundDownwardMessage` and replace `DownwardMessageQueueHeads` for `P` with the resulting hash.
+    1. Add the resulting `InboundDownwardMessage` into `DownwardMessageQueues` for `P`.
+
 ## Session Change
 
 1. Drain `OutgoingParas`. For each `P` happened to be in the list:
   1. Remove all inbound channels of `P`, i.e. `(_, P)`,
   1. Remove all outbound channels of `P`, i.e. `(P, _)`,
   1. Remove all `DownwardMessageQueues` of `P`.
+  1. Remove `DownwardMessageQueueHeads` for `P`.
   1. Remove `RelayDispatchQueueSize` of `P`.
   1. Remove `RelayDispatchQueues` of `P`.
   1. Remove `HrmpOpenChannelRequestCount` for `P`

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

@@ -125,6 +125,11 @@ struct PersistedValidationData {
 	parent_head: HeadData,
 	/// The relay-chain block number this is in the context of. This informs the collator.
 	block_number: BlockNumber,
+	/// The MQC head for the DMQ.
+	///
+	/// The DMQ MQC head will be used by the validation function to authorize the downward messages
+	/// passed by the collator.
+	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

@@ -115,4 +115,13 @@ enum DownwardMessage {
 	/// 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,
+}
 ```