Implementer's guide: Messaging overview stub (#1405)

* Introduce the Messaging Overview doc * Update to the latest thinking
2026-04-29 20:47:56 +00:00 · 2020-08-07 18:01:05 +02:00
parent 7428a47373
commit f6f80ece18
2 changed files with 92 additions and 0 deletions
@@ -5,6 +5,7 @@
 - [Whence Parachains](whence-parachains.md)
 - [Parachains Overview](parachains-overview.md)
 - [Architecture Overview](architecture.md)
+- [Messaging Overview](messaging.md)
 - [Runtime Architecture](runtime/README.md)
  - [Initializer Module](runtime/initializer.md)
  - [Configuration Module](runtime/configuration.md)
@@ -0,0 +1,91 @@
+# Messaging Overview
+
+Polkadot has a few mechanisms that are responsible for message passing. They can be generally divided
+on two categories: Horizontal and Vertical. Horizontal Message Passing (HMP) refers to mechanisms
+that are responsible for exchanging messages between parachains. Vertical Message Passing (VMP) is
+used for communication between the relay chain and parachains.
+
+## Vertical Message Passing
+
+```dot process
+digraph {
+    rc [shape=Mdiamond label="Relay Chain"];
+    p1 [shape=box label = "Parachain"];
+
+    rc -> p1 [label="DMP"];
+    p1 -> rc [label="UMP"];
+}
+```
+
+Downward Message Passing (DMP) is a mechanism for delivering messages to parachains from the relay chain. Downward
+messages may originate not from the relay chain, but rather from another parachain via a mechanism
+called HRMP (Will be described later).
+
+Each parachain has its own queue that stores all pending inbound downward messages. A parachain
+doesn't have to process all messages at once, however, there are rules as to how the downward message queue
+should be processed. Currently, at least one message must be consumed per candidate if the queue is not empty.
+The downward message queue doesn't have a cap on its size and it is up to the relay-chain to put mechanisms
+that prevent spamming in place.
+
+Upward Message Passing (UMP) is a mechanism responsible for delivering messages in the opposite direction:
+from a parachain up to the relay chain. Upward messages are dispatched to Runtime entrypoints and
+typically used for invoking some actions on the relay chain on behalf of the parachain.
+
+> NOTE: It is conceivable that upward messages will be divided to more fine-grained kinds with a dispatchable upward message
+being only one kind of multiple. That would make upward messages inspectable and therefore would allow imposing additional
+validity criteria for the candidates that contain these messages.
+
+Semantically, there is a queue of upward messages queue where messages from each parachain are stored. Each parachain
+can have a limited number of messages and the total sum of pending messages is also limited. Each parachain can dispatch
+multiple upward messages per candidate.
+
+## Horizontal Message Passing
+
+```dot process
+digraph {
+    rc [shape=Mdiamond color="gray" fontcolor="gray" label="Relay Chain"];
+
+    subgraph {
+        rank = "same"
+        p1 [shape=box label = "Parachain 1"];
+        p2 [shape=box label = "Parachain 2"];
+    }
+
+    rc -> p1 [label="DMP" color="gray" fontcolor="gray"];
+    p1 -> rc [label="UMP" color="gray" fontcolor="gray"];
+
+    rc -> p2 [label="DMP" color="gray" fontcolor="gray"];
+    p2 -> rc [label="UMP" color="gray" fontcolor="gray"];
+
+    p2 -> p1 [dir=both label="XCMP"];
+}
+```
+
+The most important member of this family is XCMP.
+
+> ℹ️ XCMP is currently under construction and details are subject for change.
+
+XCMP is a message passing mechanism between parachains that require minimal involvement of the relay chain.
+The relay chain provides means for sending parachains to authenticate messages sent to recipient parachains.
+
+Semantically communication occurs through so called channels. A channel is unidirectional and it has
+two endpoints, for sender and for recipient. A channel can be opened only if the both parties agree
+and closed unilaterally.
+
+Only the channel metadata is stored on the relay-chain in a very compact form: all messages and their
+contents sent by the sender parachain are encoded using only one root hash. This root is referred as
+MQC head.
+
+The authenticity of the messages must be proven using that root hash to the receiving party at the
+candidate authoring time. The proof stems from the relay parent storage that contains the root hash of the channel.
+Since not all messages are required to be processed by the receiver's candidate, only the processed
+messages are supplied (i.e. preimages), rest are provided as hashes.
+
+Further details can be found at the [W3F research website](https://research.web3.foundation/en/latest/polkadot/XCMP.html)
+and [this blogpost](https://medium.com/web3foundation/polkadots-messaging-scheme-b1ec560908b7).
+
+HRMP (Horizontally Relay-routed Message Passing) is a stop gap that predates XCMP. Semantically, it mimics XCMP's interface.
+The crucial difference from XCMP though is that all the messages are stored in the relay-chain storage. That makes
+things simple but at the same time that makes HRMP more demanding in terms of resources thus making it more expensive.
+
+Once XCMP is available we expect to retire HRMP.