referrerpolicy=no-referrer-when-downgrade

hrmp_primitives/
lib.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! # HRMP-channel shared primitives
19//!
20//! Types shared by the parachain pallet (`pallet-hrmp-para`) and relay-chain pallet
21//! (`pallet-hrmp-relay`). This crate is deliberately free of any FRAME, XCM, or network-specific
22//! dependency, so a single version of the wire types serves Westend, Kusama and Polkadot, and so
23//! both pallets can depend on it without forming a dependency cycle.
24
25#![cfg_attr(not(feature = "std"), no_std)]
26
27use codec::{Decode, DecodeWithMemTracking, Encode, MaxEncodedLen};
28use scale_info::TypeInfo;
29
30/// A parachain id.
31pub type ParaId = u32;
32
33/// A deposit amount, in the relay chain's native token.
34pub type Balance = u128;
35
36/// One end of a channel, in the order the relay chain names them.
37#[derive(
38	Encode,
39	Decode,
40	DecodeWithMemTracking,
41	Clone,
42	Copy,
43	Eq,
44	PartialEq,
45	Ord,
46	PartialOrd,
47	Debug,
48	TypeInfo,
49	MaxEncodedLen,
50)]
51pub struct ChannelId {
52	/// The para that sends on this channel.
53	pub sender: ParaId,
54	/// The para that receives on this channel.
55	pub recipient: ParaId,
56}
57
58/// Which end of a channel pays a deposit.
59#[derive(
60	Encode,
61	Decode,
62	DecodeWithMemTracking,
63	Clone,
64	Copy,
65	Eq,
66	PartialEq,
67	Ord,
68	PartialOrd,
69	Debug,
70	TypeInfo,
71	MaxEncodedLen,
72)]
73pub enum DepositSide {
74	/// The para that sends on the channel.
75	#[codec(index = 0)]
76	Sender,
77	/// The para that receives on the channel.
78	#[codec(index = 1)]
79	Recipient,
80}
81
82impl DepositSide {
83	/// The para of `channel` that pays this side's deposit.
84	pub fn para(&self, channel: &ChannelId) -> ParaId {
85		match self {
86			Self::Sender => channel.sender,
87			Self::Recipient => channel.recipient,
88		}
89	}
90}
91
92/// Why the parachain could not set the deposits it was asked to.
93#[derive(
94	Encode,
95	Decode,
96	DecodeWithMemTracking,
97	Clone,
98	Copy,
99	Eq,
100	PartialEq,
101	Debug,
102	TypeInfo,
103	MaxEncodedLen,
104)]
105pub enum DepositError {
106	/// A side cannot cover its deposit.
107	#[codec(index = 0)]
108	InsufficientFunds,
109	/// Any other reason.
110	#[codec(index = 1)]
111	Other,
112}
113
114/// Messages from the relay chain to the parachain that holds the deposits.
115///
116/// The variant's `#[codec(index)]` is the on-wire version tag.
117#[derive(
118	Encode, Decode, DecodeWithMemTracking, Clone, Eq, PartialEq, Debug, TypeInfo, MaxEncodedLen,
119)]
120pub enum MessageToPara {
121	/// Version 1.
122	#[codec(index = 0)]
123	V1(MessageToParaV1),
124}
125
126/// Version 1 payloads for [`MessageToPara`].
127#[derive(
128	Encode, Decode, DecodeWithMemTracking, Clone, Eq, PartialEq, Debug, TypeInfo, MaxEncodedLen,
129)]
130pub enum MessageToParaV1 {
131	/// Request to set the deposits for some sides of `channel`.
132	///
133	/// For each side, `Some(amount)` means to set that side's deposit to `amount`, and `None`
134	/// means to not modify that side's deposit. The request fails without touching any deposit
135	/// if any side's operation fails.
136	///
137	/// The request is answered with [`MessageToRelayV1::DepositsSet`] carrying `id`.
138	#[codec(index = 0)]
139	SetDeposits {
140		/// Chosen by the relay chain, echoed back in the answer.
141		id: u64,
142		/// The channel whose deposits change.
143		channel: ChannelId,
144		/// What the sender deposit for this channel is requested to be.
145		sender: Option<Balance>,
146		/// What the recipient deposit for this channel is requested to be.
147		recipient: Option<Balance>,
148	},
149	/// Request to release everything held for the named sides of `channel`.
150	///
151	/// Never fails, never answered.
152	#[codec(index = 1)]
153	Release {
154		/// The channel whose deposits are given back.
155		channel: ChannelId,
156		/// Whether the sender's deposit is given back.
157		sender: bool,
158		/// Whether the recipient's deposit is given back.
159		recipient: bool,
160	},
161}
162
163/// Messages from the parachain that holds the deposits to the relay chain.
164///
165/// The variant's `#[codec(index)]` is the on-wire version tag.
166#[derive(
167	Encode, Decode, DecodeWithMemTracking, Clone, Eq, PartialEq, Debug, TypeInfo, MaxEncodedLen,
168)]
169pub enum MessageToRelay {
170	/// Version 1.
171	#[codec(index = 0)]
172	V1(MessageToRelayV1),
173}
174
175/// Version 1 payloads for [`MessageToRelay`].
176#[derive(
177	Encode, Decode, DecodeWithMemTracking, Clone, Eq, PartialEq, Debug, TypeInfo, MaxEncodedLen,
178)]
179pub enum MessageToRelayV1 {
180	/// The answer to [`MessageToParaV1::SetDeposits`] with this `id`.
181	#[codec(index = 0)]
182	DepositsSet {
183		/// The `id` of the request.
184		id: u64,
185		/// The `result` of the request.
186		result: Result<(), DepositError>,
187	},
188}
189
190/// What a deposit is held for: one side of one channel.
191#[derive(
192	Encode,
193	Decode,
194	DecodeWithMemTracking,
195	Clone,
196	Copy,
197	Eq,
198	PartialEq,
199	Ord,
200	PartialOrd,
201	Debug,
202	TypeInfo,
203	MaxEncodedLen,
204)]
205pub struct DepositKey {
206	/// The channel the deposit is for.
207	pub channel: ChannelId,
208	/// The side that pays it.
209	pub side: DepositSide,
210}
211
212impl DepositKey {
213	/// The para that pays this deposit.
214	pub fn para(&self) -> ParaId {
215		self.side.para(&self.channel)
216	}
217}
218
219/// Receive a migrated HRMP deposit.
220///
221/// `HoldReason` is the hold reason type of the currency the deposits are held in.
222pub trait ReceiveMigratedDeposits<HoldReason> {
223	/// Set the deposit of `key` to `amount`, by moving the balance from/into the `source` hold
224	/// reason.
225	///
226	/// The function is idempotent, the current deposit is reset, so a deposit can be delivered
227	/// twice.
228	fn receive_deposit(
229		key: DepositKey,
230		amount: Balance,
231		source: &HoldReason,
232	) -> sp_runtime::DispatchResult;
233
234	/// The weight of [`Self::receive_deposit`].
235	fn weight_of_receive_deposit() -> sp_runtime::Weight;
236}
237
238impl<HoldReason> ReceiveMigratedDeposits<HoldReason> for () {
239	fn receive_deposit(_: DepositKey, _: Balance, _: &HoldReason) -> sp_runtime::DispatchResult {
240		Err(sp_runtime::DispatchError::Unavailable)
241	}
242
243	fn weight_of_receive_deposit() -> sp_runtime::Weight {
244		sp_runtime::Weight::zero()
245	}
246}