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
pub use crate::v3::{Error, Result, SendError, XcmHash};
20
use codec::{Decode, Encode};
21
use core::result;
22
use scale_info::TypeInfo;
23

            
24
pub use sp_weights::Weight;
25

            
26
use super::*;
27

            
28
/// Outcome of an XCM execution.
29
#[derive(Clone, Encode, Decode, Eq, PartialEq, Debug, TypeInfo)]
30
pub 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

            
40
impl Outcome {
41
27176
	pub fn ensure_complete(self) -> Result {
42
27176
		match self {
43
3200
			Outcome::Complete { .. } => Ok(()),
44
23652
			Outcome::Incomplete { error, .. } => Err(error),
45
324
			Outcome::Error { error, .. } => Err(error),
46
		}
47
27176
	}
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
27096
	pub fn weight_used(&self) -> Weight {
57
27096
		match self {
58
3200
			Outcome::Complete { used, .. } => *used,
59
23572
			Outcome::Incomplete { used, .. } => *used,
60
324
			Outcome::Error { .. } => Weight::zero(),
61
		}
62
27096
	}
63
}
64

            
65
impl From<Error> for Outcome {
66
	fn from(error: Error) -> Self {
67
		Self::Error { error }
68
	}
69
}
70

            
71
pub trait PreparedMessage {
72
	fn weight_of(&self) -> Weight;
73
}
74

            
75
/// Type of XCM message executor.
76
pub 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
20382
	fn prepare_and_execute(
86
20382
		origin: impl Into<Location>,
87
20382
		message: Xcm<Call>,
88
20382
		id: &mut XcmHash,
89
20382
		weight_limit: Weight,
90
20382
		weight_credit: Weight,
91
20382
	) -> Outcome {
92
20382
		let pre = match Self::prepare(message) {
93
20313
			Ok(x) => x,
94
69
			Err(_) => return Outcome::Error { error: Error::WeightNotComputable },
95
		};
96
20313
		let xcm_weight = pre.weight_of();
97
20313
		if xcm_weight.any_gt(weight_limit) {
98
174
			return Outcome::Error { error: Error::WeightLimitReached(xcm_weight) }
99
20139
		}
100
20139
		Self::execute(origin, pre, id, weight_credit)
101
20382
	}
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

            
108
pub enum Weightless {}
109
impl PreparedMessage for Weightless {
110
	fn weight_of(&self) -> Weight {
111
		unreachable!()
112
	}
113
}
114

            
115
impl<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

            
128
pub 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.
154
pub 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
/// ```
228
pub 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)]
252
impl 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 as mutable references into `T::send_xcm`.
293
6405
pub fn validate_send<T: SendXcm>(dest: Location, msg: Xcm<()>) -> SendResult<T::Ticket> {
294
6405
	T::validate(&mut Some(dest), &mut Some(msg))
295
6405
}
296

            
297
/// Convenience function for using a `SendXcm` implementation. Just interprets the `dest` and wraps
298
/// both in `Some` before passing them as 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.
305
546
pub fn send_xcm<T: SendXcm>(
306
546
	dest: Location,
307
546
	msg: Xcm<()>,
308
546
) -> result::Result<(XcmHash, Assets), SendError> {
309
546
	let (ticket, price) = T::validate(&mut Some(dest), &mut Some(msg))?;
310
207
	let hash = T::deliver(ticket)?;
311
207
	Ok((hash, price))
312
546
}