referrerpolicy=no-referrer-when-downgrade

staging_xcm/v3/
traits.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// This file is part of Polkadot.
3
4// Polkadot is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Polkadot is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
16
17//! Cross-Consensus Message format data structures.
18
19use crate::v5::Error as NewError;
20use core::result;
21use scale_info::TypeInfo;
22
23pub use sp_weights::Weight;
24
25// A simple trait to get the weight of some object.
26pub trait GetWeight<W> {
27	fn weight(&self) -> sp_weights::Weight;
28}
29
30use super::*;
31
32/// Error codes used in XCM. The first errors codes have explicit indices and are part of the XCM
33/// format. Those trailing are merely part of the XCM implementation; there is no expectation that
34/// they will retain the same index over time.
35#[derive(
36	Copy,
37	Clone,
38	Encode,
39	Decode,
40	DecodeWithMemTracking,
41	Eq,
42	PartialEq,
43	Debug,
44	TypeInfo,
45	MaxEncodedLen,
46)]
47#[scale_info(replace_segment("staging_xcm", "xcm"))]
48#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
49pub enum Error {
50	// Errors that happen due to instructions being executed. These alone are defined in the
51	// XCM specification.
52	/// An arithmetic overflow happened.
53	#[codec(index = 0)]
54	Overflow,
55	/// The instruction is intentionally unsupported.
56	#[codec(index = 1)]
57	Unimplemented,
58	/// Origin Register does not contain a value value for a reserve transfer notification.
59	#[codec(index = 2)]
60	UntrustedReserveLocation,
61	/// Origin Register does not contain a value value for a teleport notification.
62	#[codec(index = 3)]
63	UntrustedTeleportLocation,
64	/// `MultiLocation` value too large to descend further.
65	#[codec(index = 4)]
66	LocationFull,
67	/// `MultiLocation` value ascend more parents than known ancestors of local location.
68	#[codec(index = 5)]
69	LocationNotInvertible,
70	/// The Origin Register does not contain a valid value for instruction.
71	#[codec(index = 6)]
72	BadOrigin,
73	/// The location parameter is not a valid value for the instruction.
74	#[codec(index = 7)]
75	InvalidLocation,
76	/// The given asset is not handled.
77	#[codec(index = 8)]
78	AssetNotFound,
79	/// An asset transaction (like withdraw or deposit) failed (typically due to type conversions).
80	#[codec(index = 9)]
81	FailedToTransactAsset(#[codec(skip)] &'static str),
82	/// An asset cannot be withdrawn, potentially due to lack of ownership, availability or rights.
83	#[codec(index = 10)]
84	NotWithdrawable,
85	/// An asset cannot be deposited under the ownership of a particular location.
86	#[codec(index = 11)]
87	LocationCannotHold,
88	/// Attempt to send a message greater than the maximum supported by the transport protocol.
89	#[codec(index = 12)]
90	ExceedsMaxMessageSize,
91	/// The given message cannot be translated into a format supported by the destination.
92	#[codec(index = 13)]
93	DestinationUnsupported,
94	/// Destination is routable, but there is some issue with the transport mechanism.
95	#[codec(index = 14)]
96	Transport(#[codec(skip)] &'static str),
97	/// Destination is known to be unroutable.
98	#[codec(index = 15)]
99	Unroutable,
100	/// Used by `ClaimAsset` when the given claim could not be recognized/found.
101	#[codec(index = 16)]
102	UnknownClaim,
103	/// Used by `Transact` when the functor cannot be decoded.
104	#[codec(index = 17)]
105	FailedToDecode,
106	/// Used by `Transact` to indicate that the given weight limit could be breached by the
107	/// functor.
108	#[codec(index = 18)]
109	MaxWeightInvalid,
110	/// Used by `BuyExecution` when the Holding Register does not contain payable fees.
111	#[codec(index = 19)]
112	NotHoldingFees,
113	/// Used by `BuyExecution` when the fees declared to purchase weight are insufficient.
114	#[codec(index = 20)]
115	TooExpensive,
116	/// Used by the `Trap` instruction to force an error intentionally. Its code is included.
117	#[codec(index = 21)]
118	Trap(u64),
119	/// Used by `ExpectAsset`, `ExpectError` and `ExpectOrigin` when the expectation was not true.
120	#[codec(index = 22)]
121	ExpectationFalse,
122	/// The provided pallet index was not found.
123	#[codec(index = 23)]
124	PalletNotFound,
125	/// The given pallet's name is different to that expected.
126	#[codec(index = 24)]
127	NameMismatch,
128	/// The given pallet's version has an incompatible version to that expected.
129	#[codec(index = 25)]
130	VersionIncompatible,
131	/// The given operation would lead to an overflow of the Holding Register.
132	#[codec(index = 26)]
133	HoldingWouldOverflow,
134	/// The message was unable to be exported.
135	#[codec(index = 27)]
136	ExportError,
137	/// `MultiLocation` value failed to be reanchored.
138	#[codec(index = 28)]
139	ReanchorFailed,
140	/// No deal is possible under the given constraints.
141	#[codec(index = 29)]
142	NoDeal,
143	/// Fees were required which the origin could not pay.
144	#[codec(index = 30)]
145	FeesNotMet,
146	/// Some other error with locking.
147	#[codec(index = 31)]
148	LockError,
149	/// The state was not in a condition where the operation was valid to make.
150	#[codec(index = 32)]
151	NoPermission,
152	/// The universal location of the local consensus is improper.
153	#[codec(index = 33)]
154	Unanchored,
155	/// An asset cannot be deposited, probably because (too much of) it already exists.
156	#[codec(index = 34)]
157	NotDepositable,
158
159	// Errors that happen prior to instructions being executed. These fall outside of the XCM
160	// spec.
161	/// XCM version not able to be handled.
162	UnhandledXcmVersion,
163	/// Execution of the XCM would potentially result in a greater weight used than weight limit.
164	WeightLimitReached(Weight),
165	/// The XCM did not pass the barrier condition for execution.
166	///
167	/// The barrier condition differs on different chains and in different circumstances, but
168	/// generally it means that the conditions surrounding the message were not such that the chain
169	/// considers the message worth spending time executing. Since most chains lift the barrier to
170	/// execution on appropriate payment, presentation of an NFT voucher, or based on the message
171	/// origin, it means that none of those were the case.
172	Barrier,
173	/// The weight of an XCM message is not computable ahead of execution.
174	WeightNotComputable,
175	/// Recursion stack limit reached
176	ExceedsStackLimit,
177}
178
179impl TryFrom<NewError> for Error {
180	type Error = ();
181	fn try_from(new_error: NewError) -> result::Result<Error, ()> {
182		use NewError::*;
183		Ok(match new_error {
184			Overflow => Self::Overflow,
185			Unimplemented => Self::Unimplemented,
186			UntrustedReserveLocation => Self::UntrustedReserveLocation,
187			UntrustedTeleportLocation => Self::UntrustedTeleportLocation,
188			LocationFull => Self::LocationFull,
189			LocationNotInvertible => Self::LocationNotInvertible,
190			BadOrigin => Self::BadOrigin,
191			InvalidLocation => Self::InvalidLocation,
192			AssetNotFound => Self::AssetNotFound,
193			FailedToTransactAsset(s) => Self::FailedToTransactAsset(s),
194			NotWithdrawable => Self::NotWithdrawable,
195			LocationCannotHold => Self::LocationCannotHold,
196			ExceedsMaxMessageSize => Self::ExceedsMaxMessageSize,
197			DestinationUnsupported => Self::DestinationUnsupported,
198			Transport(s) => Self::Transport(s),
199			Unroutable => Self::Unroutable,
200			UnknownClaim => Self::UnknownClaim,
201			FailedToDecode => Self::FailedToDecode,
202			MaxWeightInvalid => Self::MaxWeightInvalid,
203			NotHoldingFees => Self::NotHoldingFees,
204			TooExpensive => Self::TooExpensive,
205			Trap(i) => Self::Trap(i),
206			ExpectationFalse => Self::ExpectationFalse,
207			PalletNotFound => Self::PalletNotFound,
208			NameMismatch => Self::NameMismatch,
209			VersionIncompatible => Self::VersionIncompatible,
210			HoldingWouldOverflow => Self::HoldingWouldOverflow,
211			ExportError => Self::ExportError,
212			ReanchorFailed => Self::ReanchorFailed,
213			NoDeal => Self::NoDeal,
214			FeesNotMet => Self::FeesNotMet,
215			LockError => Self::LockError,
216			NoPermission => Self::NoPermission,
217			Unanchored => Self::Unanchored,
218			NotDepositable => Self::NotDepositable,
219			_ => return Err(()),
220		})
221	}
222}
223
224impl From<SendError> for Error {
225	fn from(e: SendError) -> Self {
226		match e {
227			SendError::NotApplicable | SendError::Unroutable | SendError::MissingArgument =>
228				Error::Unroutable,
229			SendError::Transport(s) => Error::Transport(s),
230			SendError::DestinationUnsupported => Error::DestinationUnsupported,
231			SendError::ExceedsMaxMessageSize => Error::ExceedsMaxMessageSize,
232			SendError::Fees => Error::FeesNotMet,
233		}
234	}
235}
236
237pub type Result = result::Result<(), Error>;
238
239/// Outcome of an XCM execution.
240#[derive(Clone, Encode, Decode, Eq, PartialEq, Debug, TypeInfo)]
241#[scale_info(replace_segment("staging_xcm", "xcm"))]
242pub enum Outcome {
243	/// Execution completed successfully; given weight was used.
244	Complete(Weight),
245	/// Execution started, but did not complete successfully due to the given error; given weight
246	/// was used.
247	Incomplete(Weight, Error),
248	/// Execution did not start due to the given error.
249	Error(Error),
250}
251
252impl Outcome {
253	pub fn ensure_complete(self) -> result::Result<Weight, Error> {
254		match self {
255			Outcome::Complete(weight) => Ok(weight),
256			Outcome::Incomplete(_, e) => Err(e),
257			Outcome::Error(e) => Err(e),
258		}
259	}
260	pub fn ensure_execution(self) -> result::Result<Weight, Error> {
261		match self {
262			Outcome::Complete(w) => Ok(w),
263			Outcome::Incomplete(w, _) => Ok(w),
264			Outcome::Error(e) => Err(e),
265		}
266	}
267	/// How much weight was used by the XCM execution attempt.
268	pub fn weight_used(&self) -> Weight {
269		match self {
270			Outcome::Complete(w) => *w,
271			Outcome::Incomplete(w, _) => *w,
272			Outcome::Error(_) => Weight::zero(),
273		}
274	}
275}
276
277pub trait PreparedMessage {
278	fn weight_of(&self) -> Weight;
279}
280
281/// Type of XCM message executor.
282pub trait ExecuteXcm<Call> {
283	type Prepared: PreparedMessage;
284	fn prepare(message: Xcm<Call>) -> result::Result<Self::Prepared, Xcm<Call>>;
285	fn execute(
286		origin: impl Into<MultiLocation>,
287		pre: Self::Prepared,
288		id: &mut XcmHash,
289		weight_credit: Weight,
290	) -> Outcome;
291	fn prepare_and_execute(
292		origin: impl Into<MultiLocation>,
293		message: Xcm<Call>,
294		id: &mut XcmHash,
295		weight_limit: Weight,
296		weight_credit: Weight,
297	) -> Outcome {
298		let pre = match Self::prepare(message) {
299			Ok(x) => x,
300			Err(_) => return Outcome::Error(Error::WeightNotComputable),
301		};
302		let xcm_weight = pre.weight_of();
303		if xcm_weight.any_gt(weight_limit) {
304			return Outcome::Error(Error::WeightLimitReached(xcm_weight))
305		}
306		Self::execute(origin, pre, id, weight_credit)
307	}
308
309	/// Execute some XCM `message` with the message `hash` from `origin` using no more than
310	/// `weight_limit` weight.
311	///
312	/// The weight limit is a basic hard-limit and the implementation may place further
313	/// restrictions or requirements on weight and other aspects.
314	fn execute_xcm(
315		origin: impl Into<MultiLocation>,
316		message: Xcm<Call>,
317		hash: XcmHash,
318		weight_limit: Weight,
319	) -> Outcome {
320		let origin = origin.into();
321		tracing::trace!(
322			target: "xcm::execute_xcm",
323			?origin,
324			?message,
325			?weight_limit,
326		);
327		Self::execute_xcm_in_credit(origin, message, hash, weight_limit, Weight::zero())
328	}
329
330	/// Execute some XCM `message` with the message `hash` from `origin` using no more than
331	/// `weight_limit` weight.
332	///
333	/// Some amount of `weight_credit` may be provided which, depending on the implementation, may
334	/// allow execution without associated payment.
335	fn execute_xcm_in_credit(
336		origin: impl Into<MultiLocation>,
337		message: Xcm<Call>,
338		mut hash: XcmHash,
339		weight_limit: Weight,
340		weight_credit: Weight,
341	) -> Outcome {
342		let pre = match Self::prepare(message) {
343			Ok(x) => x,
344			Err(_) => return Outcome::Error(Error::WeightNotComputable),
345		};
346		let xcm_weight = pre.weight_of();
347		if xcm_weight.any_gt(weight_limit) {
348			return Outcome::Error(Error::WeightLimitReached(xcm_weight))
349		}
350		Self::execute(origin, pre, &mut hash, weight_credit)
351	}
352
353	/// Deduct some `fees` to the sovereign account of the given `location` and place them as per
354	/// the convention for fees.
355	fn charge_fees(location: impl Into<MultiLocation>, fees: MultiAssets) -> Result;
356}
357
358pub enum Weightless {}
359impl PreparedMessage for Weightless {
360	fn weight_of(&self) -> Weight {
361		unreachable!()
362	}
363}
364
365impl<C> ExecuteXcm<C> for () {
366	type Prepared = Weightless;
367	fn prepare(message: Xcm<C>) -> result::Result<Self::Prepared, Xcm<C>> {
368		Err(message)
369	}
370	fn execute(
371		_: impl Into<MultiLocation>,
372		_: Self::Prepared,
373		_: &mut XcmHash,
374		_: Weight,
375	) -> Outcome {
376		unreachable!()
377	}
378	fn charge_fees(_location: impl Into<MultiLocation>, _fees: MultiAssets) -> Result {
379		Err(Error::Unimplemented)
380	}
381}
382
383/// Error result value when attempting to send an XCM message.
384#[derive(
385	Clone, Encode, Decode, DecodeWithMemTracking, Eq, PartialEq, Debug, scale_info::TypeInfo,
386)]
387#[scale_info(replace_segment("staging_xcm", "xcm"))]
388pub enum SendError {
389	/// The message and destination combination was not recognized as being reachable.
390	///
391	/// This is not considered fatal: if there are alternative transport routes available, then
392	/// they may be attempted.
393	NotApplicable,
394	/// Destination is routable, but there is some issue with the transport mechanism. This is
395	/// considered fatal.
396	/// A human-readable explanation of the specific issue is provided.
397	Transport(#[codec(skip)] &'static str),
398	/// Destination is known to be unroutable. This is considered fatal.
399	Unroutable,
400	/// The given message cannot be translated into a format that the destination can be expected
401	/// to interpret.
402	DestinationUnsupported,
403	/// Message could not be sent due to its size exceeding the maximum allowed by the transport
404	/// layer.
405	ExceedsMaxMessageSize,
406	/// A needed argument is `None` when it should be `Some`.
407	MissingArgument,
408	/// Fees needed to be paid in order to send the message and they were unavailable.
409	Fees,
410}
411
412/// A hash type for identifying messages.
413pub type XcmHash = [u8; 32];
414
415/// Result value when attempting to send an XCM message.
416pub type SendResult<T> = result::Result<(T, MultiAssets), SendError>;
417
418/// Utility for sending an XCM message to a given location.
419///
420/// These can be amalgamated in tuples to form sophisticated routing systems. In tuple format, each
421/// router might return `NotApplicable` to pass the execution to the next sender item. Note that
422/// each `NotApplicable` might alter the destination and the XCM message for to the next router.
423///
424/// # Example
425/// ```rust
426/// # use codec::Encode;
427/// # use staging_xcm::v3::{prelude::*, Weight};
428/// # use staging_xcm::VersionedXcm;
429/// # use std::convert::Infallible;
430///
431/// /// A sender that only passes the message through and does nothing.
432/// struct Sender1;
433/// impl SendXcm for Sender1 {
434///     type Ticket = Infallible;
435///     fn validate(_: &mut Option<MultiLocation>, _: &mut Option<Xcm<()>>) -> SendResult<Infallible> {
436///         Err(SendError::NotApplicable)
437///     }
438///     fn deliver(_: Infallible) -> Result<XcmHash, SendError> {
439///         unreachable!()
440///     }
441/// }
442///
443/// /// A sender that accepts a message that has an X2 junction, otherwise stops the routing.
444/// struct Sender2;
445/// impl SendXcm for Sender2 {
446///     type Ticket = ();
447///     fn validate(destination: &mut Option<MultiLocation>, message: &mut Option<Xcm<()>>) -> SendResult<()> {
448///         match destination.as_ref().ok_or(SendError::MissingArgument)? {
449///             MultiLocation { parents: 0, interior: X2(j1, j2) } => Ok(((), MultiAssets::new())),
450///             _ => Err(SendError::Unroutable),
451///         }
452///     }
453///     fn deliver(_: ()) -> Result<XcmHash, SendError> {
454///         Ok([0; 32])
455///     }
456/// }
457///
458/// /// A sender that accepts a message from a parent, passing through otherwise.
459/// struct Sender3;
460/// impl SendXcm for Sender3 {
461///     type Ticket = ();
462///     fn validate(destination: &mut Option<MultiLocation>, message: &mut Option<Xcm<()>>) -> SendResult<()> {
463///         match destination.as_ref().ok_or(SendError::MissingArgument)? {
464///             MultiLocation { parents: 1, interior: Here } => Ok(((), MultiAssets::new())),
465///             _ => Err(SendError::NotApplicable),
466///         }
467///     }
468///     fn deliver(_: ()) -> Result<XcmHash, SendError> {
469///         Ok([0; 32])
470///     }
471/// }
472///
473/// // A call to send via XCM. We don't really care about this.
474/// # fn main() {
475/// let call: Vec<u8> = ().encode();
476/// let message = Xcm(vec![Instruction::Transact {
477///     origin_kind: OriginKind::Superuser,
478///     require_weight_at_most: Weight::zero(),
479///     call: call.into(),
480/// }]);
481/// let message_hash = message.using_encoded(sp_io::hashing::blake2_256);
482///
483/// // Sender2 will block this.
484/// assert!(send_xcm::<(Sender1, Sender2, Sender3)>(Parent.into(), message.clone()).is_err());
485///
486/// // Sender3 will catch this.
487/// assert!(send_xcm::<(Sender1, Sender3)>(Parent.into(), message.clone()).is_ok());
488/// # }
489/// ```
490pub trait SendXcm {
491	/// Intermediate value which connects the two phases of the send operation.
492	type Ticket;
493
494	/// Check whether the given `message` is deliverable to the given `destination` and if so
495	/// determine the cost which will be paid by this chain to do so, returning a `Validated` token
496	/// which can be used to enact delivery.
497	///
498	/// The `destination` and `message` must be `Some` (or else an error will be returned) and they
499	/// may only be consumed if the `Err` is not `NotApplicable`.
500	///
501	/// If it is not a destination which can be reached with this type but possibly could by others,
502	/// then this *MUST* return `NotApplicable`. Any other error will cause the tuple
503	/// implementation to exit early without trying other type fields.
504	fn validate(
505		destination: &mut Option<MultiLocation>,
506		message: &mut Option<Xcm<()>>,
507	) -> SendResult<Self::Ticket>;
508
509	/// Actually carry out the delivery operation for a previously validated message sending.
510	fn deliver(ticket: Self::Ticket) -> result::Result<XcmHash, SendError>;
511}
512
513#[impl_trait_for_tuples::impl_for_tuples(30)]
514impl SendXcm for Tuple {
515	for_tuples! { type Ticket = (#( Option<Tuple::Ticket> ),* ); }
516
517	fn validate(
518		destination: &mut Option<MultiLocation>,
519		message: &mut Option<Xcm<()>>,
520	) -> SendResult<Self::Ticket> {
521		let mut maybe_cost: Option<MultiAssets> = None;
522		let one_ticket: Self::Ticket = (for_tuples! { #(
523			if maybe_cost.is_some() {
524				None
525			} else {
526				match Tuple::validate(destination, message) {
527					Err(SendError::NotApplicable) => None,
528					Err(e) => { return Err(e) },
529					Ok((v, c)) => {
530						maybe_cost = Some(c);
531						Some(v)
532					},
533				}
534			}
535		),* });
536		if let Some(cost) = maybe_cost {
537			Ok((one_ticket, cost))
538		} else {
539			Err(SendError::NotApplicable)
540		}
541	}
542
543	fn deliver(one_ticket: Self::Ticket) -> result::Result<XcmHash, SendError> {
544		for_tuples!( #(
545			if let Some(validated) = one_ticket.Tuple {
546				return Tuple::deliver(validated);
547			}
548		)* );
549		Err(SendError::Unroutable)
550	}
551}
552
553/// Convenience function for using a `SendXcm` implementation. Just interprets the `dest` and wraps
554/// both in `Some` before passing them as mutable references into `T::send_xcm`.
555pub fn validate_send<T: SendXcm>(dest: MultiLocation, msg: Xcm<()>) -> SendResult<T::Ticket> {
556	T::validate(&mut Some(dest), &mut Some(msg))
557}
558
559/// Convenience function for using a `SendXcm` implementation. Just interprets the `dest` and wraps
560/// both in `Some` before passing them as mutable references into `T::send_xcm`.
561///
562/// Returns either `Ok` with the price of the delivery, or `Err` with the reason why the message
563/// could not be sent.
564///
565/// Generally you'll want to validate and get the price first to ensure that the sender can pay it
566/// before actually doing the delivery.
567pub fn send_xcm<T: SendXcm>(
568	dest: MultiLocation,
569	msg: Xcm<()>,
570) -> result::Result<(XcmHash, MultiAssets), SendError> {
571	let (ticket, price) = T::validate(&mut Some(dest), &mut Some(msg))?;
572	let hash = T::deliver(ticket)?;
573	Ok((hash, price))
574}