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}