frame_support/traits/tokens/fungibles/freeze.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 traits for putting freezes within a single fungible token class.
19//!
20//! See the [`crate::traits::fungibles`] doc for more information about fungibles traits.
21
22use crate::{ensure, traits::tokens::Fortitude};
23use scale_info::TypeInfo;
24use sp_arithmetic::{
25 traits::{CheckedAdd, CheckedSub},
26 ArithmeticError,
27};
28use sp_runtime::{DispatchResult, TokenError};
29
30/// Trait for inspecting a fungible asset which can be frozen. Freezing is essentially setting a
31/// minimum balance below which the total balance (inclusive of any funds placed on hold) may not
32/// be normally allowed to drop. Generally, freezers will provide an "update" function such that
33/// if the total balance does drop below the limit, then the freezer can update their housekeeping
34/// accordingly.
35pub trait Inspect<AccountId>: super::Inspect<AccountId> {
36 /// An identifier for a freeze.
37 type Id: codec::Encode + TypeInfo + 'static;
38
39 /// Amount of funds held in reserve by `who` for the given `id`.
40 fn balance_frozen(asset: Self::AssetId, id: &Self::Id, who: &AccountId) -> Self::Balance;
41
42 /// The amount of the balance which can become frozen. Defaults to `total_balance()`.
43 fn balance_freezable(asset: Self::AssetId, who: &AccountId) -> Self::Balance {
44 Self::total_balance(asset, who)
45 }
46
47 /// Returns `true` if it's possible to introduce a freeze for the given `id` onto the
48 /// account of `who`. This will be true as long as the implementor supports as many
49 /// concurrent freeze locks as there are possible values of `id`.
50 fn can_freeze(asset: Self::AssetId, id: &Self::Id, who: &AccountId) -> bool;
51}
52
53/// Trait for introducing, altering and removing locks to freeze an account's funds so they never
54/// go below a set minimum.
55pub trait Mutate<AccountId>: Inspect<AccountId> {
56 /// Prevent actions which would reduce the balance of the account of `who` below the given
57 /// `amount` and identify this restriction though the given `id`. Unlike `extend_freeze`, any
58 /// outstanding freeze in place for `who` under the `id` are dropped.
59 ///
60 /// If `amount` is zero, it is equivalent to using `thaw`.
61 ///
62 /// Note that `amount` can be greater than the total balance, if desired.
63 fn set_freeze(
64 asset: Self::AssetId,
65 id: &Self::Id,
66 who: &AccountId,
67 amount: Self::Balance,
68 ) -> DispatchResult;
69
70 /// Prevent the balance of the account of `who` from being reduced below the given `amount` and
71 /// identify this restriction though the given `id`. Unlike `set_freeze`, this does not
72 /// counteract any pre-existing freezes in place for `who` under the `id`. Also unlike
73 /// `set_freeze`, in the case that `amount` is zero, this is no-op and never fails.
74 ///
75 /// Note that more funds can be locked than the total balance, if desired.
76 fn extend_freeze(
77 asset: Self::AssetId,
78 id: &Self::Id,
79 who: &AccountId,
80 amount: Self::Balance,
81 ) -> DispatchResult;
82
83 /// Remove an existing lock.
84 fn thaw(asset: Self::AssetId, id: &Self::Id, who: &AccountId) -> DispatchResult;
85
86 /// Attempt to alter the amount frozen under the given `id` to `amount`.
87 ///
88 /// Fail if the account of `who` has fewer freezable funds than `amount`, unless `fortitude` is
89 /// `Fortitude::Force`.
90 fn set_frozen(
91 asset: Self::AssetId,
92 id: &Self::Id,
93 who: &AccountId,
94 amount: Self::Balance,
95 fortitude: Fortitude,
96 ) -> DispatchResult {
97 let force = fortitude == Fortitude::Force;
98 ensure!(
99 force || Self::balance_freezable(asset.clone(), who) >= amount,
100 TokenError::FundsUnavailable
101 );
102 Self::set_freeze(asset, id, who, amount)
103 }
104
105 /// Attempt to set the amount frozen under the given `id` to `amount`, iff this would increase
106 /// the amount frozen under `id`. Do nothing otherwise.
107 ///
108 /// Fail if the account of `who` has fewer freezable funds than `amount`, unless `fortitude` is
109 /// `Fortitude::Force`.
110 fn ensure_frozen(
111 asset: Self::AssetId,
112 id: &Self::Id,
113 who: &AccountId,
114 amount: Self::Balance,
115 fortitude: Fortitude,
116 ) -> DispatchResult {
117 let force = fortitude == Fortitude::Force;
118 ensure!(
119 force || Self::balance_freezable(asset.clone(), who) >= amount,
120 TokenError::FundsUnavailable
121 );
122 Self::extend_freeze(asset, id, who, amount)
123 }
124
125 /// Decrease the amount which is being frozen for a particular lock, failing in the case of
126 /// underflow.
127 fn decrease_frozen(
128 asset: Self::AssetId,
129 id: &Self::Id,
130 who: &AccountId,
131 amount: Self::Balance,
132 ) -> DispatchResult {
133 let a = Self::balance_frozen(asset.clone(), id, who)
134 .checked_sub(&amount)
135 .ok_or(ArithmeticError::Underflow)?;
136 Self::set_frozen(asset, id, who, a, Fortitude::Polite)
137 }
138
139 /// Increase the amount which is being frozen for a particular lock, failing in the case that
140 /// too little balance is available for being frozen.
141 fn increase_frozen(
142 asset: Self::AssetId,
143 id: &Self::Id,
144 who: &AccountId,
145 amount: Self::Balance,
146 ) -> DispatchResult {
147 let a = Self::balance_frozen(asset.clone(), id, who)
148 .checked_add(&amount)
149 .ok_or(ArithmeticError::Overflow)?;
150 Self::set_frozen(asset, id, who, a, Fortitude::Polite)
151 }
152}