Implementer's Guide: Router fixes (#1727)

* Guide: Reindent the router module with 4 spaces

The guide used to use 2 spaces for indentation. The problem with that is `mdbook` doesn't recognize them as a proper indentation and thus doesn't render indent properly.

A couple of things are not indented here because they will be changed in the following commits

* Guide: a bunch of fixes

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

@@ -22,5 +22,5 @@ Included: Option<()>,
     1. Invoke `Scheduler::schedule(freed)`
 	1. Invoke the `Inclusion::process_candidates` routine with the parameters `(backed_candidates, Scheduler::scheduled(), Scheduler::group_validators)`.
     1. Call `Scheduler::occupied` using the return value of the `Inclusion::process_candidates` call above, first sorting the list of assigned core indices.
-    1. Call the `Router::process_upward_dispatchables` routine to execute all messages in upward dispatch queues.
+    1. Call the `Router::process_pending_upward_dispatchables` routine to execute all messages in upward dispatch queues.
     1. If all of the above succeeds, set `Included` to `Some(())`.

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

@@ -4,23 +4,30 @@ The Router module is responsible for all messaging mechanisms supported between
 
 ## Storage
 
-Storage layout:
+General storage entries
 
 ```rust
 /// Paras that are to be cleaned up at the end of the session.
 /// The entries are sorted ascending by the para id.
 OutgoingParas: Vec<ParaId>;
+```
+
+### Upward Message Passing (UMP)
+
+```rust
 /// Dispatchable objects ready to be dispatched onto the relay chain. The messages are processed in FIFO order.
-/// This is subject to `max_upward_queue_count` and
+RelayDispatchQueues: map ParaId => Vec<(ParachainDispatchOrigin, RawDispatchable)>;
-/// `watermark_queue_size` from `HostConfiguration`.
-RelayDispatchQueues: map ParaId => Vec<RawDispatchable>;
 /// Size of the dispatch queues. Caches sizes of the queues in `RelayDispatchQueue`.
 /// First item in the tuple is the count of messages and second
 /// is the total length (in bytes) of the message payloads.
+///
+/// Note that this is an auxilary mapping: it's possible to tell the byte size  and the number of
+/// messages only looking at `RelayDispatchQueues`. This mapping is separate to avoid the cost of
+/// loading the whole message queue if only the total size and count are required.
 RelayDispatchQueueSize: map ParaId => (u32, u32);
 /// The ordered list of `ParaId`s that have a `RelayDispatchQueue` entry.
 NeedsDispatch: Vec<ParaId>;
-/// This is the para that gets will get dispatched first during the next upward dispatchable queue
+/// This is the para that will get dispatched first during the next upward dispatchable queue
 /// execution round.
 NextDispatchRoundStartWith: Option<ParaId>;
 ```
@@ -36,7 +43,7 @@ DownwardMessageQueues: map ParaId => Vec<InboundDownwardMessage>;
 ///
 /// Each link in this chain has a form:
 /// `(prev_head, B, H(M))`, where
-/// - `prev_head`: is the previous head hash.
+/// - `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>;
@@ -200,12 +207,12 @@ Candidate Enactment:
 * `queue_outbound_hrmp(sender: ParaId, Vec<OutboundHrmpMessage>)`:
     1. For each horizontal message `HM` with the channel `C` identified by `(sender, HM.recipient)`:
         1. Append `HM` into `HrmpChannelContents` that corresponds to `C` with `sent_at` equals to the current block number.
-    1. Locate or create an entry in ``HrmpChannelDigests`` for `HM.recipient` and append `sender` into the entry's list.
+        1. Locate or create an entry in `HrmpChannelDigests` for `HM.recipient` and append `sender` into the entry's list.
         1. Increment `C.used_places`
         1. Increment `C.used_bytes` by `HM`'s payload size
         1. Append a new link to the MQC and save the new head in `C.mqc_head`. Note that the current block number as of enactment is used for the link.
 * `prune_hrmp(recipient, new_hrmp_watermark)`:
-  1. From ``HrmpChannelDigests`` for `recipient` remove all entries up to an entry with block number equal to `new_hrmp_watermark`.
+    1. From `HrmpChannelDigests` for `recipient` remove all entries up to an entry with block number equal to `new_hrmp_watermark`.
     1. From the removed digests construct a set of paras that sent new messages within the interval between the old and new watermarks.
     1. For each channel `C` identified by `(sender, recipient)` for each `sender` coming from the set, prune messages up to the `new_hrmp_watermark`.
     1. For each pruned message `M` from channel `C`:
@@ -245,7 +252,7 @@ The following routine is intended to be called in the same time when `Paras::sch
 The following routine is meant to execute pending entries in upward dispatchable queues. This function doesn't fail, even if
 any of dispatchables return an error.
 
-`process_upward_dispatchables()`:
+`process_pending_upward_dispatchables()`:
     1. Initialize a cumulative weight counter `T` to 0
     1. Iterate over items in `NeedsDispatch` cyclically, starting with `NextDispatchRoundStartWith`. If the item specified is `None` start from the beginning. For each `P` encountered:
         1. Dequeue `D` the first dispatchable `D` from `RelayDispatchQueues` for `P`

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: Hash,
+	dmq_mqc_head: Option<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

@@ -7,7 +7,7 @@ although with smaller scalability potential.
 
 ## HrmpChannelId
 
-A type that uniquely identifies a HRMP channel. A HRMP channel is established between two paras.
+A type that uniquely identifies an HRMP channel. An HRMP channel is established between two paras.
 In text, we use the notation `(A, B)` to specify a channel between A and B. The channels are
 unidirectional, meaning that `(A, B)` and `(B, A)` refer to different channels. The convention is
 that we use the first item tuple for the sender and the second for the recipient. Only one channel

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

@@ -45,8 +45,7 @@ struct HostConfiguration {
 	///
 	/// NOTE that this is a soft limit and could be exceeded.
 	pub preferred_dispatchable_upward_messages_step_weight: u32,
-	/// Any dispatchable upward message that requests more than the critical amount is rejected
+	/// Any dispatchable upward message that requests more than the critical amount is rejected.
-	/// with `DispatchResult::CriticalWeightExceeded`.
 	///
 	/// The parameter value is picked up so that no dispatchable can make the block weight exceed
 	/// the total budget. I.e. that the sum of `preferred_dispatchable_upward_messages_step_weight`