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

frame_support/traits/tokens/
transfer.rs
