diff --git a/roadmap/implementers-guide/src/SUMMARY.md b/roadmap/implementers-guide/src/SUMMARY.md index b5dc3840c605..e5c2deacb199 100644 --- a/roadmap/implementers-guide/src/SUMMARY.md +++ b/roadmap/implementers-guide/src/SUMMARY.md @@ -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) diff --git a/roadmap/implementers-guide/src/messaging.md b/roadmap/implementers-guide/src/messaging.md new file mode 100644 index 000000000000..3795db37710e --- /dev/null +++ b/roadmap/implementers-guide/src/messaging.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.