1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// 	http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! The traits for dealing with a single fungible token class and any associated types.
//!
//! Also see the [`frame_tokens`] reference docs for more information about the place of
//! `fungible` traits in Substrate.
//!
//! # Available Traits
//! - [`Inspect`]: Regular balance inspector functions.
//! - [`Unbalanced`]: Low-level balance mutating functions. Does not guarantee proper book-keeping
//!   and so should not be called into directly from application code. Other traits depend on this
//!   and provide default implementations based on it.
//! - [`UnbalancedHold`]: Low-level balance mutating functions for balances placed on hold. Does not
//!   guarantee proper book-keeping and so should not be called into directly from application code.
//!   Other traits depend on this and provide default implementations based on it.
//! - [`Mutate`]: Regular balance mutator functions. Pre-implemented using [`Unbalanced`], though
//!   the `done_*` functions should likely be reimplemented in case you want to do something
//!   following the operation such as emit events.
//! - [`InspectHold`]: Inspector functions for balances on hold.
//! - [`MutateHold`]: Mutator functions for balances on hold. Mostly pre-implemented using
//!   [`UnbalancedHold`].
//! - [`InspectFreeze`]: Inspector functions for frozen balance.
//! - [`MutateFreeze`]: Mutator functions for frozen balance.
//! - [`Balanced`]: One-sided mutator functions for regular balances, which return imbalance objects
//!   which guarantee eventual book-keeping. May be useful for some sophisticated operations where
//!   funds must be removed from an account before it is known precisely what should be done with
//!   them.
//!
//! ## Terminology
//!
//! - **Total Issuance**: The total number of units in existence in a system.
//!
//! - **Total Balance**: The sum of an account's free and held balances.
//!
//! - **Free Balance**: A portion of an account's total balance that is not held. Note this is
//!   distinct from the Spendable Balance, which represents how much Balance the user can actually
//!   transfer.
//!
//! - **Held Balance**: Held balance still belongs to the account holder, but is suspended. It can
//!   be slashed, but only after all the free balance has been slashed.
//!
//!   Multiple holds stack rather than overlay. This means that if an account has
//!   3 holds for 100 units, the account can spend its funds for any reason down to 300 units, at
//!   which point the holds will start to come into play.
//!
//! - **Frozen Balance**: A freeze on a specified amount of an account's balance. Tokens that are
//!   frozen cannot be transferred.
//!
//!   Multiple freezes always operate over the same funds, so they "overlay" rather than
//!   "stack". This means that if an account has 3 freezes for 100 units, the account can spend its
//!   funds for any reason down to 100 units, at which point the freezes will start to come into
//!   play.
//!
//!   It's important to note that the frozen balance can exceed the total balance of the account.
//!   This is useful, eg, in cases where you want to prevent a user from transferring any fund. In
//!   such a case, setting the frozen balance to `Balance::MAX` would serve that purpose
//! effectively.
//!
//! - **Minimum Balance (a.k.a. Existential Deposit, a.k.a. ED)**: The minimum balance required to
//!   create or keep an account open. This is to prevent "dust accounts" from filling storage. When
//!   the free plus the held balance (i.e. the total balance) falls below this, then the account is
//!   said to be dead. It loses its functionality as well as any prior history and all information
//!   on it is removed from the chain's state. No account should ever have a total balance that is
//!   strictly between 0 and the existential deposit (exclusive). If this ever happens, it indicates
//!   either a bug in the implementation of this trait or an erroneous raw mutation of storage.
//!
//! - **Untouchable Balance**: The part of a user's free balance they cannot spend, due to ED or
//!   Freeze(s).
//!
//! - **Spendable Balance**: The part of a user's free balance they can actually transfer, after
//!   accounting for Holds and Freezes.
//!
//! - **Imbalance**: A condition when some funds were credited or debited without equal and opposite
//!   accounting (i.e. a difference between total issuance and account balances). Functions that
//!   result in an imbalance will return an object of the [`imbalance::Credit`] or
//!   [`imbalance::Debt`] traits that can be managed within your runtime logic.
//!
//!   If an imbalance is simply dropped, it should automatically maintain any book-keeping such as
//!   total issuance.
//!
//! ## Visualising Balance Components Together 💫
//!
//! ```ignore
//! |__total__________________________________|
//! |__on_hold__|_____________free____________|
//! |__________frozen___________|
//! |__on_hold__|__ed__|
//!             |__untouchable__|__spendable__|
//! ```
//!
//! ## Holds and Freezes
//!
//! Both holds and freezes are used to prevent an account from using some of its balance.
//!
//! The primary distinction between the two are that:
//! - Holds are cumulative (do not overlap) and are distinct from the free balance
//! - Freezes are not cumulative, and can overlap with each other or with holds
//!
//! ```ignore
//! |__total_____________________________|
//! |__hold_a__|__hold_b__|_____free_____|
//! |__on_hold____________|     // <- the sum of all holds
//! |__freeze_a_______________|
//! |__freeze_b____|
//! |__freeze_c________|
//! |__frozen_________________| // <- the max of all freezes
//! ```
//!
//! Holds are designed to be infallibly slashed, meaning that any logic using a `Freeze`
//! must handle the possibility of the frozen amount being reduced, potentially to zero. A
//! permissionless function should be provided in order to allow bookkeeping to be updated in this
//! instance. E.g. some balance is frozen when it is used for voting, one could use held balance for
//! voting, but nothing prevents this frozen balance from being reduced if the overlapping hold is
//! slashed.
//!
//! Every Hold and Freeze is accompanied by a unique `Reason`, making it clear for each instance
//! what the originating pallet and purpose is. These reasons are amalgomated into a single enum
//! `RuntimeHoldReason` and `RuntimeFreezeReason` respectively, when the runtime is compiled.
//!
//! Note that `Hold` and `Freeze` reasons should remain in your runtime for as long as storage
//! could exist in your runtime with those reasons, otherwise your runtime state could become
//! undecodable.
//!
//! ### Should I use a Hold or Freeze?
//!
//! If you require a balance to be infaillibly slashed, then you should use Holds.
//!
//! If you require setting a minimum account balance amount, then you should use a Freezes. Note
//! Freezes do not carry the same guarantees as Holds. Although the account cannot voluntarily
//! reduce their balance below the largest freeze, if Holds on the account are slashed then the
//! balance could drop below the freeze amount.
//!
//! ## Sets of Tokens
//!
//! For managing sets of tokens, see the [`fungibles`](`frame_support::traits::fungibles`) trait
//! which is a wrapper around this trait but supporting multiple asset instances.
//!
//! [`frame_tokens`]: ../../../../polkadot_sdk_docs/reference_docs/frame_tokens/index.html

pub mod conformance_tests;
pub mod freeze;
pub mod hold;
pub(crate) mod imbalance;
mod item_of;
mod regular;
mod union_of;

use codec::{Decode, Encode, MaxEncodedLen};
use core::marker::PhantomData;
use frame_support_procedural::{CloneNoBound, EqNoBound, PartialEqNoBound, RuntimeDebugNoBound};
use scale_info::TypeInfo;

use super::{
	Fortitude::{Force, Polite},
	Precision::BestEffort,
};
pub use freeze::{Inspect as InspectFreeze, Mutate as MutateFreeze};
pub use hold::{
	Balanced as BalancedHold, Inspect as InspectHold, Mutate as MutateHold,
	Unbalanced as UnbalancedHold,
};
pub use imbalance::{Credit, Debt, HandleImbalanceDrop, Imbalance};
pub use item_of::ItemOf;
pub use regular::{
	Balanced, DecreaseIssuance, Dust, IncreaseIssuance, Inspect, Mutate, Unbalanced,
};
use sp_arithmetic::traits::Zero;
use sp_core::Get;
use sp_runtime::{traits::Convert, DispatchError};
pub use union_of::{NativeFromLeft, NativeOrWithId, UnionOf};

use crate::{
	ensure,
	traits::{Consideration, Footprint},
};

/// Consideration method using a `fungible` balance frozen as the cost exacted for the footprint.
///
/// The aggregate amount frozen under `R::get()` for any account which has multiple tickets,
/// is the *cumulative* amounts of each ticket's footprint (each individually determined by `D`).
#[derive(
	CloneNoBound,
	EqNoBound,
	PartialEqNoBound,
	Encode,
	Decode,
	TypeInfo,
	MaxEncodedLen,
	RuntimeDebugNoBound,
)]
#[scale_info(skip_type_params(A, F, R, D, Fp))]
#[codec(mel_bound())]
pub struct FreezeConsideration<A, F, R, D, Fp>(F::Balance, PhantomData<fn() -> (A, R, D, Fp)>)
where
	F: MutateFreeze<A>;
impl<
		A: 'static,
		F: 'static + MutateFreeze<A>,
		R: 'static + Get<F::Id>,
		D: 'static + Convert<Fp, F::Balance>,
		Fp: 'static,
	> Consideration<A, Fp> for FreezeConsideration<A, F, R, D, Fp>
{
	fn new(who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		let new = D::convert(footprint);
		if new.is_zero() {
			Ok(None)
		} else {
			F::increase_frozen(&R::get(), who, new)?;
			Ok(Some(Self(new, PhantomData)))
		}
	}
	fn update(self, who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		let new = D::convert(footprint);
		if self.0 > new {
			F::decrease_frozen(&R::get(), who, self.0 - new)?;
		} else if new > self.0 {
			F::increase_frozen(&R::get(), who, new - self.0)?;
		}
		if new.is_zero() {
			Ok(None)
		} else {
			Ok(Some(Self(new, PhantomData)))
		}
	}
	fn drop(self, who: &A) -> Result<(), DispatchError> {
		F::decrease_frozen(&R::get(), who, self.0).map(|_| ())
	}
}

/// Consideration method using a `fungible` balance frozen as the cost exacted for the footprint.
#[derive(
	CloneNoBound,
	EqNoBound,
	PartialEqNoBound,
	Encode,
	Decode,
	TypeInfo,
	MaxEncodedLen,
	RuntimeDebugNoBound,
)]
#[scale_info(skip_type_params(A, F, R, D, Fp))]
#[codec(mel_bound())]
pub struct HoldConsideration<A, F, R, D, Fp = Footprint>(
	F::Balance,
	PhantomData<fn() -> (A, R, D, Fp)>,
)
where
	F: MutateHold<A>;
impl<
		A: 'static,
		F: 'static + MutateHold<A>,
		R: 'static + Get<F::Reason>,
		D: 'static + Convert<Fp, F::Balance>,
		Fp: 'static,
	> Consideration<A, Fp> for HoldConsideration<A, F, R, D, Fp>
{
	fn new(who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		let new = D::convert(footprint);
		if new.is_zero() {
			Ok(None)
		} else {
			F::hold(&R::get(), who, new)?;
			Ok(Some(Self(new, PhantomData)))
		}
	}
	fn update(self, who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		let new = D::convert(footprint);
		if self.0 > new {
			F::release(&R::get(), who, self.0 - new, BestEffort)?;
		} else if new > self.0 {
			F::hold(&R::get(), who, new - self.0)?;
		}
		if new.is_zero() {
			Ok(None)
		} else {
			Ok(Some(Self(new, PhantomData)))
		}
	}
	fn drop(self, who: &A) -> Result<(), DispatchError> {
		F::release(&R::get(), who, self.0, BestEffort).map(|_| ())
	}
	fn burn(self, who: &A) {
		let _ = F::burn_held(&R::get(), who, self.0, BestEffort, Force);
	}
}

/// Basic consideration method using a `fungible` balance frozen as the cost exacted for the
/// footprint.
///
/// NOTE: This is an optimized implementation, which can only be used for systems where each
/// account has only a single active ticket associated with it since individual tickets do not
/// track the specific balance which is frozen. If you are uncertain then use `FreezeConsideration`
/// instead, since this works in all circumstances.
#[derive(
	CloneNoBound,
	EqNoBound,
	PartialEqNoBound,
	Encode,
	Decode,
	TypeInfo,
	MaxEncodedLen,
	RuntimeDebugNoBound,
)]
#[scale_info(skip_type_params(A, Fx, Rx, D, Fp))]
#[codec(mel_bound())]
pub struct LoneFreezeConsideration<A, Fx, Rx, D, Fp>(PhantomData<fn() -> (A, Fx, Rx, D, Fp)>);
impl<
		A: 'static,
		Fx: 'static + MutateFreeze<A>,
		Rx: 'static + Get<Fx::Id>,
		D: 'static + Convert<Fp, Fx::Balance>,
		Fp: 'static,
	> Consideration<A, Fp> for LoneFreezeConsideration<A, Fx, Rx, D, Fp>
{
	fn new(who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		ensure!(Fx::balance_frozen(&Rx::get(), who).is_zero(), DispatchError::Unavailable);
		let new = D::convert(footprint);
		if new.is_zero() {
			Ok(None)
		} else {
			Fx::set_frozen(&Rx::get(), who, new, Polite).map(|_| Some(Self(PhantomData)))
		}
	}
	fn update(self, who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		let new = D::convert(footprint);
		let _ = Fx::set_frozen(&Rx::get(), who, new, Polite)?;
		if new.is_zero() {
			Ok(None)
		} else {
			Ok(Some(Self(PhantomData)))
		}
	}
	fn drop(self, who: &A) -> Result<(), DispatchError> {
		Fx::thaw(&Rx::get(), who).map(|_| ())
	}
}

/// Basic consideration method using a `fungible` balance placed on hold as the cost exacted for the
/// footprint.
///
/// NOTE: This is an optimized implementation, which can only be used for systems where each
/// account has only a single active ticket associated with it since individual tickets do not
/// track the specific balance which is frozen. If you are uncertain then use `FreezeConsideration`
/// instead, since this works in all circumstances.
#[derive(
	CloneNoBound,
	EqNoBound,
	PartialEqNoBound,
	Encode,
	Decode,
	TypeInfo,
	MaxEncodedLen,
	RuntimeDebugNoBound,
)]
#[scale_info(skip_type_params(A, Fx, Rx, D, Fp))]
#[codec(mel_bound())]
pub struct LoneHoldConsideration<A, Fx, Rx, D, Fp>(PhantomData<fn() -> (A, Fx, Rx, D, Fp)>);
impl<
		A: 'static,
		F: 'static + MutateHold<A>,
		R: 'static + Get<F::Reason>,
		D: 'static + Convert<Fp, F::Balance>,
		Fp: 'static,
	> Consideration<A, Fp> for LoneHoldConsideration<A, F, R, D, Fp>
{
	fn new(who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		ensure!(F::balance_on_hold(&R::get(), who).is_zero(), DispatchError::Unavailable);
		let new = D::convert(footprint);
		if new.is_zero() {
			Ok(None)
		} else {
			F::set_on_hold(&R::get(), who, new).map(|_| Some(Self(PhantomData)))
		}
	}
	fn update(self, who: &A, footprint: Fp) -> Result<Option<Self>, DispatchError> {
		let new = D::convert(footprint);
		let _ = F::set_on_hold(&R::get(), who, new)?;
		if new.is_zero() {
			Ok(None)
		} else {
			Ok(Some(Self(PhantomData)))
		}
	}
	fn drop(self, who: &A) -> Result<(), DispatchError> {
		F::release_all(&R::get(), who, BestEffort).map(|_| ())
	}
	fn burn(self, who: &A) {
		let _ = F::burn_all_held(&R::get(), who, BestEffort, Force);
	}
}