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.
28///
29/// Note: Consider using [`crate::traits::fungible::MutateFreeze`] (and family) as it returns a
30/// `Result`, and is therefore much safer to use.
31pub trait LockableCurrency<AccountId>: Currency<AccountId> {
32 /// The quantity used to denote time; usually just a `BlockNumber`.
33 type Moment;
34
35 /// The maximum number of locks a user should have on their account.
36 type MaxLocks: Get<u32>;
37
38 /// Create a new balance lock on account `who`.
39 ///
40 /// If the new lock is valid (i.e. not already expired), it will push the struct to
41 /// the `Locks` vec in storage. Note that you can lock more funds than a user has.
42 ///
43 /// If the lock `id` already exists, this will update it.
44 fn set_lock(
45 id: LockIdentifier,
46 who: &AccountId,
47 amount: Self::Balance,
48 reasons: WithdrawReasons,
49 );
50
51 /// Changes a balance lock (selected by `id`) so that it becomes less liquid in all
52 /// parameters or creates a new one if it does not exist.
53 ///
54 /// Calling `extend_lock` on an existing lock `id` differs from `set_lock` in that it
55 /// applies the most severe constraints of the two, while `set_lock` replaces the lock
56 /// with the new parameters. As in, `extend_lock` will set:
57 /// - maximum `amount`
58 /// - bitwise mask of all `reasons`
59 fn extend_lock(
60 id: LockIdentifier,
61 who: &AccountId,
62 amount: Self::Balance,
63 reasons: WithdrawReasons,
64 );
65
66 /// Remove an existing lock.
67 fn remove_lock(id: LockIdentifier, who: &AccountId);
68}
69
70/// A inspect interface for a currency whose accounts can have liquidity restrictions.
71pub trait InspectLockableCurrency<AccountId>: LockableCurrency<AccountId> {
72 /// Amount of funds locked for `who` associated with `id`.
73 fn balance_locked(id: LockIdentifier, who: &AccountId) -> Self::Balance;
74}
75
76/// A vesting schedule over a currency. This allows a particular currency to have vesting limits
77/// applied to it.
78pub trait VestingSchedule<AccountId> {
79 /// The quantity used to denote time; usually just a `BlockNumber`.
80 type Moment;
81
82 /// The currency that this schedule applies to.
83 type Currency: Currency<AccountId>;
84
85 /// Get the amount that is currently being vested and cannot be transferred out of this account.
86 /// Returns `None` if the account has no vesting schedule.
87 fn vesting_balance(who: &AccountId)
88 -> Option<<Self::Currency as Currency<AccountId>>::Balance>;
89
90 /// Adds a vesting schedule to a given account.
91 ///
92 /// If the account has `MaxVestingSchedules`, an Error is returned and nothing
93 /// is updated.
94 ///
95 /// Is a no-op if the amount to be vested is zero.
96 ///
97 /// NOTE: This doesn't alter the free balance of the account.
98 fn add_vesting_schedule(
99 who: &AccountId,
100 locked: <Self::Currency as Currency<AccountId>>::Balance,
101 per_block: <Self::Currency as Currency<AccountId>>::Balance,
102 starting_block: Self::Moment,
103 ) -> DispatchResult;
104
105 /// Checks if `add_vesting_schedule` would work against `who`.
106 fn can_add_vesting_schedule(
107 who: &AccountId,
108 locked: <Self::Currency as Currency<AccountId>>::Balance,
109 per_block: <Self::Currency as Currency<AccountId>>::Balance,
110 starting_block: Self::Moment,
111 ) -> DispatchResult;
112
113 /// Remove a vesting schedule for a given account.
114 ///
115 /// NOTE: This doesn't alter the free balance of the account.
116 fn remove_vesting_schedule(who: &AccountId, schedule_index: u32) -> DispatchResult;
117}
118
119/// A vested transfer over a currency. This allows a transferred amount to vest over time.
120pub trait VestedTransfer<AccountId> {
121 /// The quantity used to denote time; usually just a `BlockNumber`.
122 type Moment;
123
124 /// The currency that this schedule applies to.
125 type Currency: Currency<AccountId>;
126
127 /// Execute a vested transfer from `source` to `target` with the given schedule:
128 /// - `locked`: The amount to be transferred and for the vesting schedule to apply to.
129 /// - `per_block`: The amount to be unlocked each block. (linear vesting)
130 /// - `starting_block`: The block where the vesting should start. This block can be in the past
131 /// or future, and should adjust when the tokens become available to the user.
132 ///
133 /// Example: Assume we are on block 100. If `locked` amount is 100, and `per_block` is 1:
134 /// - If `starting_block` is 0, then the whole 100 tokens will be available right away as the
135 /// vesting schedule started in the past and has fully completed.
136 /// - If `starting_block` is 50, then 50 tokens are made available right away, and 50 more
137 /// tokens will unlock one token at a time until block 150.
138 /// - If `starting_block` is 100, then each block, 1 token will be unlocked until the whole
139 /// balance is unlocked at block 200.
140 /// - If `starting_block` is 200, then the 100 token balance will be completely locked until
141 /// block 200, and then start to unlock one token at a time until block 300.
142 fn vested_transfer(
143 source: &AccountId,
144 target: &AccountId,
145 locked: <Self::Currency as Currency<AccountId>>::Balance,
146 per_block: <Self::Currency as Currency<AccountId>>::Balance,
147 starting_block: Self::Moment,
148 ) -> DispatchResult;
149}
150
151// An no-op implementation of `VestedTransfer` for pallets that require this trait, but users may
152// not want to implement this functionality
153pub struct NoVestedTransfers<C> {
154 phantom: core::marker::PhantomData<C>,
155}
156
157impl<AccountId, C: Currency<AccountId>> VestedTransfer<AccountId> for NoVestedTransfers<C> {
158 type Moment = ();
159 type Currency = C;
160
161 fn vested_transfer(
162 _source: &AccountId,
163 _target: &AccountId,
164 _locked: <Self::Currency as Currency<AccountId>>::Balance,
165 _per_block: <Self::Currency as Currency<AccountId>>::Balance,
166 _starting_block: Self::Moment,
167 ) -> DispatchResult {
168 Err(sp_runtime::DispatchError::Unavailable.into())
169 }
170}