xcm_docs/glossary.rs
1// Copyright (C) Parity Technologies (UK) Ltd.
2// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
3// This file is part of Polkadot.
4
5// Polkadot is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9
10// Polkadot is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14
15// You should have received a copy of the GNU General Public License
16// along with Polkadot. If not, see <http://www.gnu.org/licenses/>.
17
18//! # Glossary
19//!
20//! ## XCM (Cross-Consensus Messaging)
21//!
22//! A messaging format meant to communicate intentions between consensus systems.
23//! XCM could also refer to a single message.
24//!
25//! ## Instructions
26//!
27//! XCMs are composed of a sequence of instructions.
28//! Each instruction aims to convey a particular intention.
29//! There are instructions for transferring and locking assets, handling fees, calling arbitrary
30//! blobs, and more.
31//!
32//! ## Consensus system
33//!
34//! A system that can reach any kind of consensus.
35//! For example, relay chains, parachains, smart contracts.
36//! Most messaging between consensus systems has to be done asynchronously, for this, XCM is used.
37//! Between two smart contracts on the same parachain, however, communication can be done
38//! synchronously.
39//!
40//! ## [`Location`](xcm::v4::prelude::Location)
41//!
42//! A way of addressing consensus systems.
43//! These could be relative or absolute.
44//!
45//! ## [`Junction`](xcm::v4::prelude::Junction)
46//!
47//! The different ways of descending down a [`Location`](xcm::v4::prelude::Location) hierarchy.
48//! A junction can be a Parachain, an Account, or more.
49//!
50//! ## [`Asset`](xcm::v4::prelude::Asset)
51//!
52//! A way of identifying assets in the same or another consensus system, by using a
53//! [`Location`](xcm::v4::prelude::Location).
54//!
55//! ## Sovereign account
56//!
57//! An account in a consensus system that is controlled by an account in another consensus system.
58//!
59//! Runtimes use a converter between a [`Location`](xcm::v4::prelude::Location) and an account.
60//! These converters implement the [`ConvertLocation`](xcm_executor::traits::ConvertLocation) trait.
61//!
62//! ## Teleport
63//!
64//! A way of transferring assets between two consensus systems without the need of a third party.
65//! It consists of the sender system burning the asset that wants to be sent over and the recipient
66//! minting an equivalent amount of that asset. It requires a lot of trust between the two systems,
67//! since failure to mint or burn will reduce or increase the total issuance of the token.
68//!
69//! ## Reserve asset transfer
70//!
71//! A way of transferring assets between two consensus systems that don't trust each other, by using
72//! a third system they both trust, called the reserve. The real asset only exists on the reserve,
73//! both sender and recipient only deal with derivatives. It consists of the sender burning a
74//! certain amount of derivatives, telling the reserve to move real assets from its sovereign
75//! account to the destination's sovereign account, and then telling the recipient to mint the right
76//! amount of derivatives.
77//! In practice, the reserve chain can also be one of the source or destination.
78//!
79//! ## XCVM
80//!
81//! The virtual machine behind XCM.
82//! Every XCM is an XCVM programme.
83//! Holds state in registers.
84//!
85//! An implementation of the virtual machine is the [`xcm-executor`](xcm_executor::XcmExecutor).
86//!
87//! ## Holding register
88//!
89//! An XCVM register used to hold arbitrary `Asset`s during the execution of an XCVM programme.
90//!
91//! ## Barrier
92//!
93//! An XCM executor configuration item that works as a firewall for incoming XCMs.
94//! All XCMs have to pass the barrier to be executed, else they are dropped.
95//! It can be used for whitelisting only certain types or messages or messages from certain senders.
96//!
97//! Lots of barrier definitions exist in [`xcm-builder`](xcm_builder).
98//!
99//! ## VMP (Vertical Message Passing)
100//!
101//! Umbrella term for both UMP (Upward Message Passing) and DMP (Downward Message Passing).
102//!
103//! The following diagram shows the uses of both protocols:
104#![doc = simple_mermaid::mermaid!("../mermaid/transport_protocols.mmd")]
105//!
106//! ## UMP (Upward Message Passing)
107//!
108//! Transport-layer protocol that allows parachains to send messages upwards to their relay chain.
109//!
110//! ## DMP (Downward Message Passing)
111//!
112//! Transport-layer protocol that allows the relay chain to send messages downwards to one of their
113//! parachains.
114//!
115//! ## XCMP (Cross-Consensus Message Passing)
116//!
117//! Transport-layer protocol that allows parachains to send messages between themselves, without
118//! going through the relay chain.
119//!
120//! ## HRMP (Horizontal Message Passing)
121//!
122//! Transport-layer protocol that allows a parachain to send messages to a sibling parachain going
123//! through the relay chain. It's a precursor to XCMP, also known as XCMP-lite.
124//! It uses a mixture of UMP and DMP.