Trait frame_support::traits::tokens::fungible::Unbalanced

source ·

pub trait Unbalanced<AccountId>: Inspect<AccountId> {
    // Required methods
    fn handle_dust(dust: Dust<AccountId, Self>);
    fn write_balance(
        who: &AccountId,
        amount: Self::Balance,
    ) -> Result<Option<Self::Balance>, DispatchError>;
    fn set_total_issuance(amount: Self::Balance);

    // Provided methods
    fn handle_raw_dust(amount: Self::Balance) { ... }
    fn decrease_balance(
        who: &AccountId,
        amount: Self::Balance,
        precision: Precision,
        preservation: Preservation,
        force: Fortitude,
    ) -> Result<Self::Balance, DispatchError> { ... }
    fn increase_balance(
        who: &AccountId,
        amount: Self::Balance,
        precision: Precision,
    ) -> Result<Self::Balance, DispatchError> { ... }
    fn deactivate(_: Self::Balance) { ... }
    fn reactivate(_: Self::Balance) { ... }
}

Expand description

A fungible token class where the balance can be set arbitrarily.

WARNING Do not use this directly unless you want trouble, since it allows you to alter account balances without keeping the issuance up to date. It has no safeguards against accidentally creating token imbalances in your system leading to accidental inflation or deflation. It’s really just for the underlying datatype to implement so the user gets the much safer Balanced trait to use.

Required Methods§

source

fn handle_dust(dust: Dust<AccountId, Self>)

Do something with the dust which has been destroyed from the system. Dust can be converted into a Credit with the Balanced trait impl.

source

fn write_balance( who: &AccountId, amount: Self::Balance, ) -> Result<Option<Self::Balance>, DispatchError>

Forcefully set the balance of who to amount.

If this call executes successfully, you can assert_eq!(Self::balance(), amount);.

For implementations which include one or more balances on hold, then these are not included in the amount.

This function does its best to force the balance change through, but will not break system invariants such as any Existential Deposits needed or overflows/underflows. If this cannot be done for some reason (e.g. because the account cannot be created, deleted or would overflow) then an Err is returned.

If Ok is returned then its inner, then Some is the amount which was discarded as dust due to existential deposit requirements. The default implementation of Unbalanced::decrease_balance and Unbalanced::increase_balance converts this into an Imbalance and then passes it into Unbalanced::handle_dust.

source

fn set_total_issuance(amount: Self::Balance)

Set the total issuance to amount.

Provided Methods§

source

fn handle_raw_dust(amount: Self::Balance)

Create some dust and handle it with Unbalanced::handle_dust. This is an unbalanced operation and it must only be used when an account is modified in a raw fashion, outside of the entire fungibles API. The amount is capped at Inspect::minimum_balance() - 1`.

This should not be reimplemented.

source

fn decrease_balance( who: &AccountId, amount: Self::Balance, precision: Precision, preservation: Preservation, force: Fortitude, ) -> Result<Self::Balance, DispatchError>

Reduce the balance of who by amount.

If precision is Exact and it cannot be reduced by that amount for some reason, return Err and don’t reduce it at all. If precision is BestEffort, then reduce the balance of who by the most that is possible, up to amount.

In either case, if Ok is returned then the inner is the amount by which is was reduced. Minimum balance will be respected and thus the returned amount may be up to Inspect::minimum_balance() - 1greater thanamount` in the case that the reduction caused the account to be deleted.

source

fn increase_balance( who: &AccountId, amount: Self::Balance, precision: Precision, ) -> Result<Self::Balance, DispatchError>

Increase the balance of who by amount.

If it cannot be increased by that amount for some reason, return Err and don’t increase it at all. If Ok, return the imbalance. Minimum balance will be respected and an error will be returned if amount < Inspect::minimum_balance() when the account of who is zero.

source