referrerpolicy=no-referrer-when-downgrade

staging_xcm/v4/
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
19pub use crate::v3::{Error, Result, SendError, XcmHash};
20use codec::{Decode, Encode};
21use core::result;
22use scale_info::TypeInfo;
23
24pub use sp_weights::Weight;
25
26use super::*;
27
28/// Outcome of an XCM execution.
29#[derive(Clone, Encode, Decode, Eq, PartialEq, Debug, TypeInfo)]
30pub enum Outcome {
31	/// Execution completed successfully; given weight was used.
32	Complete { used: Weight },
33	/// Execution started, but did not complete successfully due to the given error; given weight
34	/// was used.
35	Incomplete { used: Weight, error: Error },
36	/// Execution did not start due to the given error.
37	Error { error: Error },
38}
39
40impl Outcome {
41	pub fn ensure_complete(self) -> Result {
42		match self {
43			Outcome::Complete { .. } => Ok(()),
44			Outcome::Incomplete { error, .. } => Err(error),
45			Outcome::Error { error, .. } => Err(error),
46		}
47	}
48	pub fn ensure_execution(self) -> result::Result<Weight, Error> {
49		match self {
50			Outcome::Complete { used, .. } => Ok(used),
51			Outcome::Incomplete { used, .. } => Ok(used),
52			Outcome::Error { error, .. } => Err(error),
53		}
54	}
55	/// How much weight was used by the XCM execution attempt.
56	pub fn weight_used(&self) -> Weight {
57		match self {
58			Outcome::Complete { used, .. } => *used,
59			Outcome::Incomplete { used, .. } => *used,
60			Outcome::Error { .. } => Weight::zero(),
61		}
62	}
63}
64
65impl From<Error> for Outcome {
66	fn from(error: Error) -> Self {
67		Self::Error { error }
68	}
69}
70
71pub trait PreparedMessage {
72	fn weight_of(&self) -> Weight;
73}
74
75/// Type of XCM message executor.
76pub trait ExecuteXcm<Call> {
77	type Prepared: PreparedMessage;
78	fn prepare(message: Xcm<Call>) -> result::Result<Self::Prepared, Xcm<Call>>;
79	fn execute(
80		origin: impl Into<Location>,
81		pre: Self::Prepared,
82		id: &mut XcmHash,
83		weight_credit: Weight,
84	) -> Outcome;
85	fn prepare_and_execute(
86		origin: impl Into<Location>,
87		message: Xcm<Call>,
88		id: &mut XcmHash,
89		weight_limit: Weight,
90		weight_credit: Weight,
91	) -> Outcome {
92		let pre = match Self::prepare(message) {
93			Ok(x) => x,
94			Err(_) => return Outcome::Error { error: Error::WeightNotComputable },
95		};
96		let xcm_weight = pre.weight_of();
97		if xcm_weight.any_gt(weight_limit) {
98			return Outcome::Error { error: Error::WeightLimitReached(xcm_weight) }
99		}
100		Self::execute(origin, pre, id, weight_credit)
101	}
102
103	/// Deduct some `fees` to the sovereign account of the given `location` and place them as per
104	/// the convention for fees.
105	fn charge_fees(location: impl Into<Location>, fees: Assets) -> Result;
106}
107
108pub enum Weightless {}
109impl PreparedMessage for Weightless {
110	fn weight_of(&self) -> Weight {
111		unreachable!()
112	}
113}
114
115impl<C> ExecuteXcm<C> for () {
116	type Prepared = Weightless;
117	fn prepare(message: Xcm<C>) -> result::Result<Self::Prepared, Xcm<C>> {
118		Err(message)
119	}
120	fn execute(_: impl Into<Location>, _: Self::Prepared, _: &mut XcmHash, _: Weight) -> Outcome {
121		unreachable!()
122	}
123	fn charge_fees(_location: impl Into<Location>, _fees: Assets) -> Result {
124		Err(Error::Unimplemented)
125	}
126}
127
128pub trait Reanchorable: Sized {
129	/// Type to return in case of an error.
130	type Error: Debug;
131
132	/// Mutate `self` so that it represents the same location from the point of view of `target`.
133	/// The context of `self` is provided as `context`.
134	///
135	/// Does not modify `self` in case of overflow.
136	fn reanchor(
137		&mut self,
138		target: &Location,
139		context: &InteriorLocation,
140	) -> core::result::Result<(), ()>;
141
142	/// Consume `self` and return a new value representing the same location from the point of view
143	/// of `target`. The context of `self` is provided as `context`.
144	///
145	/// Returns the original `self` in case of overflow.
146	fn reanchored(
147		self,
148		target: &Location,
149		context: &InteriorLocation,
150	) -> core::result::Result<Self, Self::Error>;
151}
152
153/// Result value when attempting to send an XCM message.
154pub type SendResult<T> = result::Result<(T, Assets), SendError>;
155
156/// Utility for sending an XCM message to a given location.
157///
158/// These can be amalgamated in tuples to form sophisticated routing systems. In tuple format, each
159/// router might return `NotApplicable` to pass the execution to the next sender item. Note that
160/// each `NotApplicable` might alter the destination and the XCM message for to the next router.
161///
162/// # Example
163/// ```rust
164/// # use codec::Encode;
165/// # use staging_xcm::v4::{prelude::*, Weight};
166/// # use staging_xcm::VersionedXcm;
167/// # use std::convert::Infallible;
168///
169/// /// A sender that only passes the message through and does nothing.
170/// struct Sender1;
171/// impl SendXcm for Sender1 {
172///     type Ticket = Infallible;
173///     fn validate(_: &mut Option<Location>, _: &mut Option<Xcm<()>>) -> SendResult<Infallible> {
174///         Err(SendError::NotApplicable)
175///     }
176///     fn deliver(_: Infallible) -> Result<XcmHash, SendError> {
177///         unreachable!()
178///     }
179/// }
180///
181/// /// A sender that accepts a message that has two junctions, otherwise stops the routing.
182/// struct Sender2;
183/// impl SendXcm for Sender2 {
184///     type Ticket = ();
185///     fn validate(destination: &mut Option<Location>, message: &mut Option<Xcm<()>>) -> SendResult<()> {
186///         match destination.as_ref().ok_or(SendError::MissingArgument)?.unpack() {
187///             (0, [j1, j2]) => Ok(((), Assets::new())),
188///             _ => Err(SendError::Unroutable),
189///         }
190///     }
191///     fn deliver(_: ()) -> Result<XcmHash, SendError> {
192///         Ok([0; 32])
193///     }
194/// }
195///
196/// /// A sender that accepts a message from a parent, passing through otherwise.
197/// struct Sender3;
198/// impl SendXcm for Sender3 {
199///     type Ticket = ();
200///     fn validate(destination: &mut Option<Location>, message: &mut Option<Xcm<()>>) -> SendResult<()> {
201///         match destination.as_ref().ok_or(SendError::MissingArgument)?.unpack() {
202///             (1, []) => Ok(((), Assets::new())),
203///             _ => Err(SendError::NotApplicable),
204///         }
205///     }
206///     fn deliver(_: ()) -> Result<XcmHash, SendError> {
207///         Ok([0; 32])
208///     }
209/// }
210///
211/// // A call to send via XCM. We don't really care about this.
212/// # fn main() {
213/// let call: Vec<u8> = ().encode();
214/// let message = Xcm(vec![Instruction::Transact {
215///     origin_kind: OriginKind::Superuser,
216///     require_weight_at_most: Weight::zero(),
217///     call: call.into(),
218/// }]);
219/// let message_hash = message.using_encoded(sp_io::hashing::blake2_256);
220///
221/// // Sender2 will block this.
222/// assert!(send_xcm::<(Sender1, Sender2, Sender3)>(Parent.into(), message.clone()).is_err());
223///
224/// // Sender3 will catch this.
225/// assert!(send_xcm::<(Sender1, Sender3)>(Parent.into(), message.clone()).is_ok());
226/// # }
227/// ```
228pub trait SendXcm {
229	/// Intermediate value which connects the two phases of the send operation.
230	type Ticket;
231
232	/// Check whether the given `_message` is deliverable to the given `_destination` and if so
233	/// determine the cost which will be paid by this chain to do so, returning a `Validated` token
234	/// which can be used to enact delivery.
235	///
236	/// The `destination` and `message` must be `Some` (or else an error will be returned) and they
237	/// may only be consumed if the `Err` is not `NotApplicable`.
238	///
239	/// If it is not a destination which can be reached with this type but possibly could by others,
240	/// then this *MUST* return `NotApplicable`. Any other error will cause the tuple
241	/// implementation to exit early without trying other type fields.
242	fn validate(
243		destination: &mut Option<Location>,
244		message: &mut Option<Xcm<()>>,
245	) -> SendResult<Self::Ticket>;
246
247	/// Actually carry out the delivery operation for a previously validated message sending.
248	fn deliver(ticket: Self::Ticket) -> result::Result<XcmHash, SendError>;
249}
250
251#[impl_trait_for_tuples::impl_for_tuples(30)]
252impl SendXcm for Tuple {
253	for_tuples! { type Ticket = (#( Option<Tuple::Ticket> ),* ); }
254
255	fn validate(
256		destination: &mut Option<Location>,
257		message: &mut Option<Xcm<()>>,
258	) -> SendResult<Self::Ticket> {
259		let mut maybe_cost: Option<Assets> = None;
260		let one_ticket: Self::Ticket = (for_tuples! { #(
261			if maybe_cost.is_some() {
262				None
263			} else {
264				match Tuple::validate(destination, message) {
265					Err(SendError::NotApplicable) => None,
266					Err(e) => { return Err(e) },
267					Ok((v, c)) => {
268						maybe_cost = Some(c);
269						Some(v)
270					},
271				}
272			}
273		),* });
274		if let Some(cost) = maybe_cost {
275			Ok((one_ticket, cost))
276		} else {
277			Err(SendError::NotApplicable)
278		}
279	}
280
281	fn deliver(one_ticket: Self::Ticket) -> result::Result<XcmHash, SendError> {
282		for_tuples!( #(
283			if let Some(validated) = one_ticket.Tuple {
284				return Tuple::deliver(validated);
285			}
286		)* );
287		Err(SendError::Unroutable)
288	}
289}
290
291/// Convenience function for using a `SendXcm` implementation. Just interprets the `dest` and wraps
292/// both in `Some` before passing them as mutable references into `T::send_xcm`.
293pub fn validate_send<T: SendXcm>(dest: Location, msg: Xcm<()>) -> SendResult<T::Ticket> {
294	T::validate(&mut Some(dest), &mut Some(msg))
295}
296
297/// Convenience function for using a `SendXcm` implementation. Just interprets the `dest` and wraps
298/// both in `Some` before passing them as mutable references into `T::send_xcm`.
299///
300/// Returns either `Ok` with the price of the delivery, or `Err` with the reason why the message
301/// could not be sent.
302///
303/// Generally you'll want to validate and get the price first to ensure that the sender can pay it
304/// before actually doing the delivery.
305pub fn send_xcm<T: SendXcm>(
306	dest: Location,
307	msg: Xcm<()>,
308) -> result::Result<(XcmHash, Assets), SendError> {
309	let (ticket, price) = T::validate(&mut Some(dest), &mut Some(msg))?;
310	let hash = T::deliver(ticket)?;
311	Ok((hash, price))
312}