frame_support/traits/tokens/currency/
lockable.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 lockable currency trait and some associated types.
19
20use super::{super::misc::WithdrawReasons, Currency};
21use crate::{dispatch::DispatchResult, traits::misc::Get};
22
23/// An identifier for a lock. Used for disambiguating different locks so that
24/// they can be individually replaced or removed.
25pub type LockIdentifier = [u8; 8];
26
27/// A currency whose accounts can have liquidity restrictions.
28pub trait LockableCurrency<AccountId>: Currency<AccountId> {
29	/// The quantity used to denote time; usually just a `BlockNumber`.
30	type Moment;
31
32	/// The maximum number of locks a user should have on their account.
33	type MaxLocks: Get<u32>;
34
35	/// Create a new balance lock on account `who`.
36	///
37	/// If the new lock is valid (i.e. not already expired), it will push the struct to
38	/// the `Locks` vec in storage. Note that you can lock more funds than a user has.
39	///
40	/// If the lock `id` already exists, this will update it.
41	fn set_lock(
42		id: LockIdentifier,
43		who: &AccountId,
44		amount: Self::Balance,
45		reasons: WithdrawReasons,
46	);
47
48	/// Changes a balance lock (selected by `id`) so that it becomes less liquid in all
49	/// parameters or creates a new one if it does not exist.
50	///
51	/// Calling `extend_lock` on an existing lock `id` differs from `set_lock` in that it
52	/// applies the most severe constraints of the two, while `set_lock` replaces the lock
53	/// with the new parameters. As in, `extend_lock` will set:
54	/// - maximum `amount`
55	/// - bitwise mask of all `reasons`
56	fn extend_lock(
57		id: LockIdentifier,
58		who: &AccountId,
59		amount: Self::Balance,
60		reasons: WithdrawReasons,
61	);
62
63	/// Remove an existing lock.
64	fn remove_lock(id: LockIdentifier, who: &AccountId);
65}
66
67/// A inspect interface for a currency whose accounts can have liquidity restrictions.
68pub trait InspectLockableCurrency<AccountId>: LockableCurrency<AccountId> {
69	/// Amount of funds locked for `who` associated with `id`.
70	fn balance_locked(id: LockIdentifier, who: &AccountId) -> Self::Balance;
71}
72
73/// A vesting schedule over a currency. This allows a particular currency to have vesting limits
74/// applied to it.
75pub trait VestingSchedule<AccountId> {
76	/// The quantity used to denote time; usually just a `BlockNumber`.
77	type Moment;
78
79	/// The currency that this schedule applies to.
80	type Currency: Currency<AccountId>;
81
82	/// Get the amount that is currently being vested and cannot be transferred out of this account.
83	/// Returns `None` if the account has no vesting schedule.
84	fn vesting_balance(who: &AccountId)
85		-> Option<<Self::Currency as Currency<AccountId>>::Balance>;
86
87	/// Adds a vesting schedule to a given account.
88	///
89	/// If the account has `MaxVestingSchedules`, an Error is returned and nothing
90	/// is updated.
91	///
92	/// Is a no-op if the amount to be vested is zero.
93	///
94	/// NOTE: This doesn't alter the free balance of the account.
95	fn add_vesting_schedule(
96		who: &AccountId,
97		locked: <Self::Currency as Currency<AccountId>>::Balance,
98		per_block: <Self::Currency as Currency<AccountId>>::Balance,
99		starting_block: Self::Moment,
100	) -> DispatchResult;
101
102	/// Checks if `add_vesting_schedule` would work against `who`.
103	fn can_add_vesting_schedule(
104		who: &AccountId,
105		locked: <Self::Currency as Currency<AccountId>>::Balance,
106		per_block: <Self::Currency as Currency<AccountId>>::Balance,
107		starting_block: Self::Moment,
108	) -> DispatchResult;
109
110	/// Remove a vesting schedule for a given account.
111	///
112	/// NOTE: This doesn't alter the free balance of the account.
113	fn remove_vesting_schedule(who: &AccountId, schedule_index: u32) -> DispatchResult;
114}
frame_support/traits/tokens/currency/lockable.rs

frame_support/traits/tokens/currency/
lockable.rs
