Guide: router module

roadmap/implementors-guide/src/SUMMARY.md

@@ -13,6 +13,7 @@
   - [Inclusion Module](runtime/inclusion.md)
   - [InclusionInherent Module](runtime/inclusioninherent.md)
   - [Validity Module](runtime/validity.md)
+  - [Router Module](runtime/router.md)
 - [Node Architecture](node/README.md)
   - [Subsystems and Jobs](node/subsystems-and-jobs.md)
   - [Overseer](node/overseer.md)
@@ -44,6 +45,7 @@
     - [Overseer and Subsystem Protocol](types/overseer-protocol.md)
     - [Runtime](types/runtime.md)
     - [Chain](types/chain.md)
+    - [Messages](types/messages.md)
 
 [Glossary](glossary.md)
 [Further Reading](further-reading.md)

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

@@ -54,11 +54,13 @@ 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 ascending order by `ParaId`.
   1. Ensure that any code upgrade scheduled by the candidate does not happen within `config.validation_upgrade_frequency` of the currently scheduled upgrade, if any, comparing against the value of `Paras::FutureCodeUpgrades` for the given para ID.
   1. check the backing of the candidate using the signatures and the bitfields.
+  1. check that the upward messages are not exceeding `config.max_upward_queue_count` and `config.watermark_upward_queue_size` parameters.
   1. create an entry in the `PendingAvailability` map for each backed candidate with a blank `availability_votes` bitfield.
   1. Return a `Vec<CoreIndex>` of all scheduled cores of the list of passed assignments that a candidate was successfully backed for, sorted ascending by CoreIndex.
 * `enact_candidate(relay_parent_number: BlockNumber, AbridgedCandidateReceipt)`:
   1. If the receipt contains a code upgrade, Call `Paras::schedule_code_upgrade(para_id, code, relay_parent_number + config.validationl_upgrade_delay)`.
     > TODO: Note that this is safe as long as we never enact candidates where the relay parent is across a session boundary. In that case, which we should be careful to avoid with contextual execution, the configuration might have changed and the para may de-sync from the host's understanding of it.
+  1. call `Router::queue_upward_messages` for each backed candidate.
   1. Call `Paras::note_new_head` using the `HeadData` from the receipt and `relay_parent_number`.
 * `collect_pending`:
 

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

@@ -17,6 +17,7 @@ The other modules are initialized in this order:
 1. Scheduler
 1. Inclusion
 1. Validity.
+1. Router.
 
 The [Configuration Module](configuration.html) is first, since all other modules need to operate under the same configuration as each other. It would lead to inconsistency if, for example, the scheduler ran first and then the configuration was updated before the Inclusion module.
 

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

@@ -0,0 +1,35 @@
+# Router Module
+
+The Router module is responsible for storing and dispatching Upward and Downward messages from and to parachains respectively. It is intended to later handle the XCMP logic as well.
+
+For each enacted block the `queue_upward_messages` entry-point is called.
+
+## Storage
+
+Storage layout:
+
+```rust,ignore
+/// Messages ready to be dispatched onto the relay chain.
+/// This is subject to `max_upward_queue_count` and
+/// `watermark_queue_size` from `HostConfiguration`.
+RelayDispatchQueues: map ParaId => Vec<UpwardMessage>;
+/// 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.
+RelayDispatchQueueSize: map ParaId => (u32, u32);
+/// The ordered list of `ParaId`s that have a `RelayDispatchQueue` entry.
+NeedsDispatch: Vec<ParaId>;
+```
+
+## Initialization
+
+No initialization routine runs for this module.
+
+## Routines
+
+* `queue_upward_messages(AbridgedCandidateReceipt)`:
+  1. Updates `NeedsDispatch`, and enqueues upward messages into `RelayDispatchQueue` and modifies the respective entry in `RelayDispatchQueueSize`.
+
+## Finalization 
+
+  1. Dispatch queued upward messages from `RelayDispatchQueues` in a FIFO order applying the `config.watermark_upward_queue_size` and `config.max_upward_queue_count` limits.

roadmap/implementors-guide/src/types/messages.md

@@ -0,0 +1,28 @@
+# Message types
+
+Types of messages that are passed between parachains and the relay chain: UMP, DMP, XCMP.
+
+## Upward Message
+
+A type of messages dispatched from a parachain to the relay chain.
+
+```rust,ignore
+enum ParachainDispatchOrigin {
+	/// As a simple `Origin::Signed`, using `ParaId::account_id` as its value. This is good when
+	/// interacting with standard modules such as `balances`.
+	Signed,
+	/// As the special `Origin::Parachain(ParaId)`. This is good when interacting with parachain-
+	/// aware modules which need to succinctly verify that the origin is a parachain.
+	Parachain,
+	/// As the simple, superuser `Origin::Root`. This can only be done on specially permissioned
+	/// parachains.
+	Root,
+}
+
+struct UpwardMessage {
+	/// The origin for the message to be sent from.
+	pub origin: ParachainDispatchOrigin,
+	/// The message data.
+	pub data: Vec<u8>,
+}
+```

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

@@ -34,5 +34,11 @@ struct HostConfiguration {
 	pub thread_availability_period: BlockNumber,
 	/// The amount of blocks ahead to schedule parathreads.
 	pub scheduling_lookahead: u32,
+	/// Total number of individual messages allowed in the parachain -> relay-chain message queue.
+	pub max_upward_queue_count: u32,
+	/// Total size of messages allowed in the parachain -> relay-chain message queue before which
+	/// no further messages may be added to it. If it exceeds this then the queue may contain only
+	/// a single message.
+	pub watermark_upward_queue_size: u32,
 }
 ```