1
// Copyright (C) Parity Technologies (UK) Ltd.
2
// This file is part of Polkadot.
3

            
4
// Substrate 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
// Substrate 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

            
19
use crate::v2::Error as OldError;
20
use codec::{Decode, Encode, MaxEncodedLen};
21
use core::result;
22
use scale_info::TypeInfo;
23

            
24
pub use sp_weights::Weight;
25

            
26
use super::*;
27

            
28
// A simple trait to get the weight of some object.
29
pub trait GetWeight<W> {
30
	fn weight(&self) -> sp_weights::Weight;
31
}
32

            
33
/// Error codes used in XCM. The first errors codes have explicit indices and are part of the XCM
34
/// format. Those trailing are merely part of the XCM implementation; there is no expectation that
35
/// they will retain the same index over time.
36
15
#[derive(Copy, Clone, Encode, Decode, Eq, PartialEq, Debug, TypeInfo)]
37
#[scale_info(replace_segment("staging_xcm", "xcm"))]
38
#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
39
pub enum Error {
40
	// Errors that happen due to instructions being executed. These alone are defined in the
41
	// XCM specification.
42
366
	/// An arithmetic overflow happened.
43
366
	#[codec(index = 0)]
44
366
	Overflow,
45
72
	/// The instruction is intentionally unsupported.
46
72
	#[codec(index = 1)]
47
72
	Unimplemented,
48
18
	/// Origin Register does not contain a value value for a reserve transfer notification.
49
18
	#[codec(index = 2)]
50
18
	UntrustedReserveLocation,
51
30
	/// Origin Register does not contain a value value for a teleport notification.
52
30
	#[codec(index = 3)]
53
30
	UntrustedTeleportLocation,
54
18
	/// `MultiLocation` value too large to descend further.
55
18
	#[codec(index = 4)]
56
18
	LocationFull,
57
18
	/// `MultiLocation` value ascend more parents than known ancestors of local location.
58
18
	#[codec(index = 5)]
59
18
	LocationNotInvertible,
60
18
	/// The Origin Register does not contain a valid value for instruction.
61
18
	#[codec(index = 6)]
62
18
	BadOrigin,
63
9
	/// The location parameter is not a valid value for the instruction.
64
9
	#[codec(index = 7)]
65
9
	InvalidLocation,
66
48
	/// The given asset is not handled.
67
48
	#[codec(index = 8)]
68
48
	AssetNotFound,
69
21
	/// An asset transaction (like withdraw or deposit) failed (typically due to type conversions).
70
21
	#[codec(index = 9)]
71
21
	FailedToTransactAsset(#[codec(skip)] &'static str),
72
75
	/// An asset cannot be withdrawn, potentially due to lack of ownership, availability or rights.
73
75
	#[codec(index = 10)]
74
75
	NotWithdrawable,
75
12
	/// An asset cannot be deposited under the ownership of a particular location.
76
12
	#[codec(index = 11)]
77
12
	LocationCannotHold,
78
27
	/// Attempt to send a message greater than the maximum supported by the transport protocol.
79
27
	#[codec(index = 12)]
80
27
	ExceedsMaxMessageSize,
81
12
	/// The given message cannot be translated into a format supported by the destination.
82
12
	#[codec(index = 13)]
83
12
	DestinationUnsupported,
84
21
	/// Destination is routable, but there is some issue with the transport mechanism.
85
21
	#[codec(index = 14)]
86
21
	Transport(#[codec(skip)] &'static str),
87
3
	/// Destination is known to be unroutable.
88
3
	#[codec(index = 15)]
89
3
	Unroutable,
90
12
	/// Used by `ClaimAsset` when the given claim could not be recognized/found.
91
12
	#[codec(index = 16)]
92
12
	UnknownClaim,
93
9
	/// Used by `Transact` when the functor cannot be decoded.
94
9
	#[codec(index = 17)]
95
9
	FailedToDecode,
96
9
	/// Used by `Transact` to indicate that the given weight limit could be breached by the
97
9
	/// functor.
98
9
	#[codec(index = 18)]
99
9
	MaxWeightInvalid,
100
9
	/// Used by `BuyExecution` when the Holding Register does not contain payable fees.
101
9
	#[codec(index = 19)]
102
9
	NotHoldingFees,
103
18
	/// Used by `BuyExecution` when the fees declared to purchase weight are insufficient.
104
18
	#[codec(index = 20)]
105
18
	TooExpensive,
106
36
	/// Used by the `Trap` instruction to force an error intentionally. Its code is included.
107
	#[codec(index = 21)]
108
36
	Trap(u64),
109
9
	/// Used by `ExpectAsset`, `ExpectError` and `ExpectOrigin` when the expectation was not true.
110
9
	#[codec(index = 22)]
111
9
	ExpectationFalse,
112
84
	/// The provided pallet index was not found.
113
84
	#[codec(index = 23)]
114
84
	PalletNotFound,
115
12
	/// The given pallet's name is different to that expected.
116
12
	#[codec(index = 24)]
117
12
	NameMismatch,
118
51
	/// The given pallet's version has an incompatible version to that expected.
119
51
	#[codec(index = 25)]
120
51
	VersionIncompatible,
121
42
	/// The given operation would lead to an overflow of the Holding Register.
122
42
	#[codec(index = 26)]
123
42
	HoldingWouldOverflow,
124
15
	/// The message was unable to be exported.
125
15
	#[codec(index = 27)]
126
15
	ExportError,
127
30
	/// `MultiLocation` value failed to be reanchored.
128
30
	#[codec(index = 28)]
129
30
	ReanchorFailed,
130
27
	/// No deal is possible under the given constraints.
131
27
	#[codec(index = 29)]
132
27
	NoDeal,
133
6
	/// Fees were required which the origin could not pay.
134
6
	#[codec(index = 30)]
135
6
	FeesNotMet,
136
96
	/// Some other error with locking.
137
96
	#[codec(index = 31)]
138
96
	LockError,
139
27
	/// The state was not in a condition where the operation was valid to make.
140
27
	#[codec(index = 32)]
141
27
	NoPermission,
142
12
	/// The universal location of the local consensus is improper.
143
12
	#[codec(index = 33)]
144
12
	Unanchored,
145
15
	/// An asset cannot be deposited, probably because (too much of) it already exists.
146
15
	#[codec(index = 34)]
147
15
	NotDepositable,
148

            
149
	// Errors that happen prior to instructions being executed. These fall outside of the XCM
150
	// spec.
151
12
	/// XCM version not able to be handled.
152
12
	UnhandledXcmVersion,
153
36
	/// Execution of the XCM would potentially result in a greater weight used than weight limit.
154
36
	WeightLimitReached(Weight),
155
15
	/// The XCM did not pass the barrier condition for execution.
156
15
	///
157
15
	/// The barrier condition differs on different chains and in different circumstances, but
158
15
	/// generally it means that the conditions surrounding the message were not such that the chain
159
15
	/// considers the message worth spending time executing. Since most chains lift the barrier to
160
15
	/// execution on appropriate payment, presentation of an NFT voucher, or based on the message
161
15
	/// origin, it means that none of those were the case.
162
15
	Barrier,
163
9
	/// The weight of an XCM message is not computable ahead of execution.
164
9
	WeightNotComputable,
165
9
	/// Recursion stack limit reached
166
9
	ExceedsStackLimit,
167
}
168

            
169
impl MaxEncodedLen for Error {
170
	fn max_encoded_len() -> usize {
171
		// TODO: max_encoded_len doesn't quite work here as it tries to take notice of the fields
172
		// marked `codec(skip)`. We can hard-code it with the right answer for now.
173
		1
174
	}
175
}
176

            
177
impl TryFrom<OldError> for Error {
178
	type Error = ();
179
248
	fn try_from(old_error: OldError) -> result::Result<Error, ()> {
180
		use OldError::*;
181
248
		Ok(match old_error {
182
46
			Overflow => Self::Overflow,
183
20
			Unimplemented => Self::Unimplemented,
184
8
			UntrustedReserveLocation => Self::UntrustedReserveLocation,
185
26
			UntrustedTeleportLocation => Self::UntrustedTeleportLocation,
186
20
			MultiLocationFull => Self::LocationFull,
187
6
			MultiLocationNotInvertible => Self::LocationNotInvertible,
188
2
			BadOrigin => Self::BadOrigin,
189
2
			InvalidLocation => Self::InvalidLocation,
190
2
			AssetNotFound => Self::AssetNotFound,
191
6
			FailedToTransactAsset(s) => Self::FailedToTransactAsset(s),
192
6
			NotWithdrawable => Self::NotWithdrawable,
193
2
			LocationCannotHold => Self::LocationCannotHold,
194
2
			ExceedsMaxMessageSize => Self::ExceedsMaxMessageSize,
195
2
			DestinationUnsupported => Self::DestinationUnsupported,
196
			Transport(s) => Self::Transport(s),
197
2
			Unroutable => Self::Unroutable,
198
8
			UnknownClaim => Self::UnknownClaim,
199
2
			FailedToDecode => Self::FailedToDecode,
200
2
			MaxWeightInvalid => Self::MaxWeightInvalid,
201
6
			NotHoldingFees => Self::NotHoldingFees,
202
6
			TooExpensive => Self::TooExpensive,
203
12
			Trap(i) => Self::Trap(i),
204
60
			_ => return Err(()),
205
		})
206
248
	}
207
}
208

            
209
impl From<SendError> for Error {
210
6400
	fn from(e: SendError) -> Self {
211
6400
		match e {
212
			SendError::NotApplicable | SendError::Unroutable | SendError::MissingArgument =>
213
6145
				Error::Unroutable,
214
			SendError::Transport(s) => Error::Transport(s),
215
			SendError::DestinationUnsupported => Error::DestinationUnsupported,
216
255
			SendError::ExceedsMaxMessageSize => Error::ExceedsMaxMessageSize,
217
			SendError::Fees => Error::FeesNotMet,
218
		}
219
6400
	}
220
}
221

            
222
pub type Result = result::Result<(), Error>;
223

            
224
/// Outcome of an XCM execution.
225
#[derive(Clone, Encode, Decode, Eq, PartialEq, Debug, TypeInfo)]
226
#[scale_info(replace_segment("staging_xcm", "xcm"))]
227
pub enum Outcome {
228
	/// Execution completed successfully; given weight was used.
229
	Complete(Weight),
230
	/// Execution started, but did not complete successfully due to the given error; given weight
231
	/// was used.
232
	Incomplete(Weight, Error),
233
	/// Execution did not start due to the given error.
234
	Error(Error),
235
}
236

            
237
impl Outcome {
238
	pub fn ensure_complete(self) -> result::Result<Weight, Error> {
239
		match self {
240
			Outcome::Complete(weight) => Ok(weight),
241
			Outcome::Incomplete(_, e) => Err(e),
242
			Outcome::Error(e) => Err(e),
243
		}
244
	}
245
	pub fn ensure_execution(self) -> result::Result<Weight, Error> {
246
		match self {
247
			Outcome::Complete(w) => Ok(w),
248
			Outcome::Incomplete(w, _) => Ok(w),
249
			Outcome::Error(e) => Err(e),
250
		}
251
	}
252
	/// How much weight was used by the XCM execution attempt.
253
	pub fn weight_used(&self) -> Weight {
254
		match self {
255
			Outcome::Complete(w) => *w,
256
			Outcome::Incomplete(w, _) => *w,
257
			Outcome::Error(_) => Weight::zero(),
258
		}
259
	}
260
}
261

            
262
pub trait PreparedMessage {
263
	fn weight_of(&self) -> Weight;
264
}
265

            
266
/// Type of XCM message executor.
267
pub trait ExecuteXcm<Call> {
268
	type Prepared: PreparedMessage;
269
	fn prepare(message: Xcm<Call>) -> result::Result<Self::Prepared, Xcm<Call>>;
270
	fn execute(
271
		origin: impl Into<MultiLocation>,
272
		pre: Self::Prepared,
273
		id: &mut XcmHash,
274
		weight_credit: Weight,
275
	) -> Outcome;
276
	fn prepare_and_execute(
277
		origin: impl Into<MultiLocation>,
278
		message: Xcm<Call>,
279
		id: &mut XcmHash,
280
		weight_limit: Weight,
281
		weight_credit: Weight,
282
	) -> Outcome {
283
		let pre = match Self::prepare(message) {
284
			Ok(x) => x,
285
			Err(_) => return Outcome::Error(Error::WeightNotComputable),
286
		};
287
		let xcm_weight = pre.weight_of();
288
		if xcm_weight.any_gt(weight_limit) {
289
			return Outcome::Error(Error::WeightLimitReached(xcm_weight))
290
		}
291
		Self::execute(origin, pre, id, weight_credit)
292
	}
293

            
294
	/// Execute some XCM `message` with the message `hash` from `origin` using no more than
295
	/// `weight_limit` weight.
296
	///
297
	/// The weight limit is a basic hard-limit and the implementation may place further
298
	/// restrictions or requirements on weight and other aspects.
299
	fn execute_xcm(
300
		origin: impl Into<MultiLocation>,
301
		message: Xcm<Call>,
302
		hash: XcmHash,
303
		weight_limit: Weight,
304
	) -> Outcome {
305
		let origin = origin.into();
306
		log::debug!(
307
			target: "xcm::execute_xcm",
308
			"origin: {:?}, message: {:?}, weight_limit: {:?}",
309
			origin,
310
			message,
311
			weight_limit,
312
		);
313
		Self::execute_xcm_in_credit(origin, message, hash, weight_limit, Weight::zero())
314
	}
315

            
316
	/// Execute some XCM `message` with the message `hash` from `origin` using no more than
317
	/// `weight_limit` weight.
318
	///
319
	/// Some amount of `weight_credit` may be provided which, depending on the implementation, may
320
	/// allow execution without associated payment.
321
	fn execute_xcm_in_credit(
322
		origin: impl Into<MultiLocation>,
323
		message: Xcm<Call>,
324
		mut hash: XcmHash,
325
		weight_limit: Weight,
326
		weight_credit: Weight,
327
	) -> Outcome {
328
		let pre = match Self::prepare(message) {
329
			Ok(x) => x,
330
			Err(_) => return Outcome::Error(Error::WeightNotComputable),
331
		};
332
		let xcm_weight = pre.weight_of();
333
		if xcm_weight.any_gt(weight_limit) {
334
			return Outcome::Error(Error::WeightLimitReached(xcm_weight))
335
		}
336
		Self::execute(origin, pre, &mut hash, weight_credit)
337
	}
338

            
339
	/// Deduct some `fees` to the sovereign account of the given `location` and place them as per
340
	/// the convention for fees.
341
	fn charge_fees(location: impl Into<MultiLocation>, fees: MultiAssets) -> Result;
342
}
343

            
344
pub enum Weightless {}
345
impl PreparedMessage for Weightless {
346
	fn weight_of(&self) -> Weight {
347
		unreachable!()
348
	}
349
}
350

            
351
impl<C> ExecuteXcm<C> for () {
352
	type Prepared = Weightless;
353
	fn prepare(message: Xcm<C>) -> result::Result<Self::Prepared, Xcm<C>> {
354
		Err(message)
355
	}
356
	fn execute(
357
		_: impl Into<MultiLocation>,
358
		_: Self::Prepared,
359
		_: &mut XcmHash,
360
		_: Weight,
361
	) -> Outcome {
362
		unreachable!()
363
	}
364
	fn charge_fees(_location: impl Into<MultiLocation>, _fees: MultiAssets) -> Result {
365
		Err(Error::Unimplemented)
366
	}
367
}
368

            
369
/// Error result value when attempting to send an XCM message.
370
#[derive(Clone, Encode, Decode, Eq, PartialEq, Debug, scale_info::TypeInfo)]
371
#[scale_info(replace_segment("staging_xcm", "xcm"))]
372
pub enum SendError {
373
	/// The message and destination combination was not recognized as being reachable.
374
	///
375
	/// This is not considered fatal: if there are alternative transport routes available, then
376
	/// they may be attempted.
377
	NotApplicable,
378
	/// Destination is routable, but there is some issue with the transport mechanism. This is
379
	/// considered fatal.
380
	/// A human-readable explanation of the specific issue is provided.
381
	Transport(#[codec(skip)] &'static str),
382
	/// Destination is known to be unroutable. This is considered fatal.
383
	Unroutable,
384
	/// The given message cannot be translated into a format that the destination can be expected
385
	/// to interpret.
386
	DestinationUnsupported,
387
	/// Message could not be sent due to its size exceeding the maximum allowed by the transport
388
	/// layer.
389
	ExceedsMaxMessageSize,
390
	/// A needed argument is `None` when it should be `Some`.
391
	MissingArgument,
392
	/// Fees needed to be paid in order to send the message and they were unavailable.
393
	Fees,
394
}
395

            
396
/// A hash type for identifying messages.
397
pub type XcmHash = [u8; 32];
398

            
399
/// Result value when attempting to send an XCM message.
400
pub type SendResult<T> = result::Result<(T, MultiAssets), SendError>;
401

            
402
/// Utility for sending an XCM message to a given location.
403
///
404
/// These can be amalgamated in tuples to form sophisticated routing systems. In tuple format, each
405
/// router might return `NotApplicable` to pass the execution to the next sender item. Note that
406
/// each `NotApplicable` might alter the destination and the XCM message for to the next router.
407
///
408
/// # Example
409
/// ```rust
410
/// # use codec::Encode;
411
/// # use staging_xcm::v3::{prelude::*, Weight};
412
/// # use staging_xcm::VersionedXcm;
413
/// # use std::convert::Infallible;
414
///
415
/// /// A sender that only passes the message through and does nothing.
416
/// struct Sender1;
417
/// impl SendXcm for Sender1 {
418
///     type Ticket = Infallible;
419
///     fn validate(_: &mut Option<MultiLocation>, _: &mut Option<Xcm<()>>) -> SendResult<Infallible> {
420
///         Err(SendError::NotApplicable)
421
///     }
422
///     fn deliver(_: Infallible) -> Result<XcmHash, SendError> {
423
///         unreachable!()
424
///     }
425
/// }
426
///
427
/// /// A sender that accepts a message that has an X2 junction, otherwise stops the routing.
428
/// struct Sender2;
429
/// impl SendXcm for Sender2 {
430
///     type Ticket = ();
431
///     fn validate(destination: &mut Option<MultiLocation>, message: &mut Option<Xcm<()>>) -> SendResult<()> {
432
///         match destination.as_ref().ok_or(SendError::MissingArgument)? {
433
///             MultiLocation { parents: 0, interior: X2(j1, j2) } => Ok(((), MultiAssets::new())),
434
///             _ => Err(SendError::Unroutable),
435
///         }
436
///     }
437
///     fn deliver(_: ()) -> Result<XcmHash, SendError> {
438
///         Ok([0; 32])
439
///     }
440
/// }
441
///
442
/// /// A sender that accepts a message from a parent, passing through otherwise.
443
/// struct Sender3;
444
/// impl SendXcm for Sender3 {
445
///     type Ticket = ();
446
///     fn validate(destination: &mut Option<MultiLocation>, message: &mut Option<Xcm<()>>) -> SendResult<()> {
447
///         match destination.as_ref().ok_or(SendError::MissingArgument)? {
448
///             MultiLocation { parents: 1, interior: Here } => Ok(((), MultiAssets::new())),
449
///             _ => Err(SendError::NotApplicable),
450
///         }
451
///     }
452
///     fn deliver(_: ()) -> Result<XcmHash, SendError> {
453
///         Ok([0; 32])
454
///     }
455
/// }
456
///
457
/// // A call to send via XCM. We don't really care about this.
458
/// # fn main() {
459
/// let call: Vec<u8> = ().encode();
460
/// let message = Xcm(vec![Instruction::Transact {
461
///     origin_kind: OriginKind::Superuser,
462
///     require_weight_at_most: Weight::zero(),
463
///     call: call.into(),
464
/// }]);
465
/// let message_hash = message.using_encoded(sp_io::hashing::blake2_256);
466
///
467
/// // Sender2 will block this.
468
/// assert!(send_xcm::<(Sender1, Sender2, Sender3)>(Parent.into(), message.clone()).is_err());
469
///
470
/// // Sender3 will catch this.
471
/// assert!(send_xcm::<(Sender1, Sender3)>(Parent.into(), message.clone()).is_ok());
472
/// # }
473
/// ```
474
pub trait SendXcm {
475
	/// Intermediate value which connects the two phases of the send operation.
476
	type Ticket;
477

            
478
	/// Check whether the given `message` is deliverable to the given `destination` and if so
479
	/// determine the cost which will be paid by this chain to do so, returning a `Validated` token
480
	/// which can be used to enact delivery.
481
	///
482
	/// The `destination` and `message` must be `Some` (or else an error will be returned) and they
483
	/// may only be consumed if the `Err` is not `NotApplicable`.
484
	///
485
	/// If it is not a destination which can be reached with this type but possibly could by others,
486
	/// then this *MUST* return `NotApplicable`. Any other error will cause the tuple
487
	/// implementation to exit early without trying other type fields.
488
	fn validate(
489
		destination: &mut Option<MultiLocation>,
490
		message: &mut Option<Xcm<()>>,
491
	) -> SendResult<Self::Ticket>;
492

            
493
	/// Actually carry out the delivery operation for a previously validated message sending.
494
	fn deliver(ticket: Self::Ticket) -> result::Result<XcmHash, SendError>;
495
}
496

            
497
#[impl_trait_for_tuples::impl_for_tuples(30)]
498
impl SendXcm for Tuple {
499
	for_tuples! { type Ticket = (#( Option<Tuple::Ticket> ),* ); }
500

            
501
	fn validate(
502
		destination: &mut Option<MultiLocation>,
503
		message: &mut Option<Xcm<()>>,
504
	) -> SendResult<Self::Ticket> {
505
		let mut maybe_cost: Option<MultiAssets> = None;
506
		let one_ticket: Self::Ticket = (for_tuples! { #(
507
			if maybe_cost.is_some() {
508
				None
509
			} else {
510
				match Tuple::validate(destination, message) {
511
					Err(SendError::NotApplicable) => None,
512
					Err(e) => { return Err(e) },
513
					Ok((v, c)) => {
514
						maybe_cost = Some(c);
515
						Some(v)
516
					},
517
				}
518
			}
519
		),* });
520
		if let Some(cost) = maybe_cost {
521
			Ok((one_ticket, cost))
522
		} else {
523
			Err(SendError::NotApplicable)
524
		}
525
	}
526

            
527
	fn deliver(one_ticket: Self::Ticket) -> result::Result<XcmHash, SendError> {
528
		for_tuples!( #(
529
			if let Some(validated) = one_ticket.Tuple {
530
				return Tuple::deliver(validated);
531
			}
532
		)* );
533
		Err(SendError::Unroutable)
534
	}
535
}
536

            
537
/// Convenience function for using a `SendXcm` implementation. Just interprets the `dest` and wraps
538
/// both in `Some` before passing them as as mutable references into `T::send_xcm`.
539
pub fn validate_send<T: SendXcm>(dest: MultiLocation, msg: Xcm<()>) -> SendResult<T::Ticket> {
540
	T::validate(&mut Some(dest), &mut Some(msg))
541
}
542

            
543
/// Convenience function for using a `SendXcm` implementation. Just interprets the `dest` and wraps
544
/// both in `Some` before passing them as as mutable references into `T::send_xcm`.
545
///
546
/// Returns either `Ok` with the price of the delivery, or `Err` with the reason why the message
547
/// could not be sent.
548
///
549
/// Generally you'll want to validate and get the price first to ensure that the sender can pay it
550
/// before actually doing the delivery.
551
pub fn send_xcm<T: SendXcm>(
552
	dest: MultiLocation,
553
	msg: Xcm<()>,
554
) -> result::Result<(XcmHash, MultiAssets), SendError> {
555
	let (ticket, price) = T::validate(&mut Some(dest), &mut Some(msg))?;
556
	let hash = T::deliver(ticket)?;
557
	Ok((hash, price))
558
}