frame_support/traits/tokens/
transfer.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//! The transfer trait and associated types
19
20use crate::pallet_prelude::{Decode, Encode};
21use core::fmt::Debug;
22use frame_support::traits::tokens::PaymentStatus;
23use scale_info::TypeInfo;
24use sp_debug_derive::RuntimeDebug;
25use sp_runtime::codec::{FullCodec, MaxEncodedLen};
26
27/// Is intended to be implemented using a `fungible` impl, but can also be implemented with
28/// XCM/Asset and made generic over assets.
29///
30/// It is similar to the `frame_support::traits::tokens::Pay`, but it offers a variable source
31/// account for the payment.
32pub trait Transfer {
33	/// The type by which we measure units of the currency in which we make payments.
34	type Balance;
35	/// The type by which identify the payer involved in the transfer.
36	///
37	/// This is usually and AccountId or a Location.
38	type Sender;
39
40	/// The type by which we identify the beneficiary involved in the transfer.
41	///
42	/// This is usually and AccountId or a Location.
43	type Beneficiary;
44
45	/// The type for the kinds of asset that are going to be paid.
46	///
47	/// The unit type can be used here to indicate there's only one kind of asset to do payments
48	/// with. When implementing, it should be clear from the context what that asset is.
49	type AssetKind;
50
51	/// Asset that is used to pay the xcm execution fees on the remote chain.
52	type RemoteFeeAsset;
53	/// An identifier given to an individual payment.
54	type Id: FullCodec + MaxEncodedLen + TypeInfo + Clone + Eq + PartialEq + Debug + Copy;
55	/// An error which could be returned by the Pay type
56	type Error: Debug;
57	/// Make a payment and return an identifier for later evaluation of success in some off-chain
58	/// mechanism (likely an event, but possibly not on this chain).
59	fn transfer(
60		from: &Self::Sender,
61		to: &Self::Beneficiary,
62		asset_kind: Self::AssetKind,
63		amount: Self::Balance,
64		remote_fee: Option<Self::RemoteFeeAsset>,
65	) -> Result<Self::Id, Self::Error>;
66
67	/// Check how a payment has proceeded. `id` must have been previously returned by `pay` for
68	/// the result of this call to be meaningful.
69	fn check_transfer(id: Self::Id) -> PaymentStatus;
70	/// Ensure that a call to pay with the given parameters will be successful if done immediately
71	/// after this call. Used in benchmarking code.
72	#[cfg(feature = "runtime-benchmarks")]
73	fn ensure_successful(
74		to: &Self::Beneficiary,
75		asset_kind: Self::AssetKind,
76		amount: Self::Balance,
77	);
78	/// Ensure that a call to `check_payment` with the given parameters will return either `Success`
79	/// or `Failure`.
80	#[cfg(feature = "runtime-benchmarks")]
81	fn ensure_concluded(id: Self::Id);
82}
83
84/// Status for making a payment via the `Pay::pay` trait function.
85#[derive(Encode, Decode, Eq, PartialEq, Clone, TypeInfo, MaxEncodedLen, RuntimeDebug)]
86pub enum TransferStatus {
87	/// Payment is in progress. Nothing to report yet.
88	InProgress,
89	/// Payment status is unknowable. It may already have reported the result, or if not then
90	/// it will never be reported successful or failed.
91	Unknown,
92	/// Payment happened successfully.
93	Success,
94	/// Payment failed. It may safely be retried.
95	Failure,
96}
frame_support/traits/tokens/transfer.rs

frame_support/traits/tokens/
transfer.rs
