Trait polkadot_sdk_frame::traits::tokens::Imbalance

pub trait Imbalance<Balance>: Sized + TryDrop + Default + TryMerge {
    type Opposite: Imbalance<Balance>;

    // Required methods
    fn zero() -> Self;
    fn drop_zero(self) -> Result<(), Self>;
    fn split(self, amount: Balance) -> (Self, Self);
    fn extract(&mut self, amount: Balance) -> Self;
    fn merge(self, other: Self) -> Self;
    fn subsume(&mut self, other: Self);
    fn offset(self, other: Self::Opposite) -> SameOrOther<Self, Self::Opposite>;
    fn peek(&self) -> Balance;

    // Provided methods
    fn ration(self, first: u32, second: u32) -> (Self, Self)
       where Balance: From<u32> + Saturating + Div<Output = Balance> { ... }
    fn split_merge(self, amount: Balance, others: (Self, Self)) -> (Self, Self) { ... }
    fn ration_merge(
        self,
        first: u32,
        second: u32,
        others: (Self, Self),
    ) -> (Self, Self)
       where Balance: From<u32> + Saturating + Div<Output = Balance> { ... }
    fn split_merge_into(self, amount: Balance, others: &mut (Self, Self)) { ... }
    fn ration_merge_into(
        self,
        first: u32,
        second: u32,
        others: &mut (Self, Self),
    )
       where Balance: From<u32> + Saturating + Div<Output = Balance> { ... }
    fn merge_into(self, other: &mut Self) { ... }
    fn maybe_merge(self, other: Option<Self>) -> Self { ... }
    fn maybe_subsume(&mut self, other: Option<Self>) { ... }
}

A trait for a not-quite Linear Type that tracks an imbalance.

Functions that alter account balances return an object of this trait to express how much account balances have been altered in aggregate. If dropped, the currency system will take some default steps to deal with the imbalance (balances module simply reduces or increases its total issuance). Your module should generally handle it in some way, good practice is to do so in a configurable manner using an OnUnbalanced type for each situation in which your module needs to handle an imbalance.

Imbalances can either be Positive (funds were added somewhere without being subtracted elsewhere - e.g. a reward) or Negative (funds deducted somewhere without an equal and opposite addition - e.g. a slash or system fee payment).

Since they are unsigned, the actual type is always Positive or Negative. The trait makes no distinction except to define the Opposite type.

New instances of zero value can be created (zero) and destroyed (drop_zero).

Existing instances can be split and merged either consuming self with merge or mutating self with subsume. If the target is an Option, then maybe_merge and maybe_subsume might work better. Instances can also be offset with an Opposite that is less than or equal to in value.

You can always retrieve the raw balance value using peek.

Required Associated Types

type Opposite: Imbalance<Balance>

The oppositely imbalanced type. They come in pairs.

Required Methods

fn zero() -> Self

The zero imbalance. Can be destroyed with drop_zero.

fn drop_zero(self) -> Result<(), Self>

Drop an instance cleanly. Only works if its self.value() is zero.

fn split(self, amount: Balance) -> (Self, Self)

Consume self and return two independent instances; the first is guaranteed to be at most amount and the second will be the remainder.

fn extract(&mut self, amount: Balance) -> Self

Mutate self by extracting a new instance with at most amount value, reducing self accordingly.

fn merge(self, other: Self) -> Self

Consume self and an other to return a new instance that combines both.

fn subsume(&mut self, other: Self)

Consume an other to mutate self into a new instance that combines both.

fn offset(self, other: Self::Opposite) -> SameOrOther<Self, Self::Opposite>

Consume self and along with an opposite counterpart to return a combined result.

Returns Ok along with a new instance of Self if this instance has a greater value than the other. Otherwise returns Err with an instance of the Opposite. In both cases the value represents the combination of self and other.

fn peek(&self) -> Balance

The raw value of self.

Provided Methods

fn ration(self, first: u32, second: u32) -> (Self, Self)

where Balance: From<u32> + Saturating + Div<Output = Balance>,

Consume self and return two independent instances; the amounts returned will be in approximately the same ratio as first:second.

NOTE: This requires up to first + second room for a multiply, and first + second should fit into a u32. Overflow will safely saturate in both cases.

fn split_merge(self, amount: Balance, others: (Self, Self)) -> (Self, Self)

Consume self and add its two components, defined by the first component’s balance, element-wise to two pre-existing Imbalances.

A convenient replacement for split and merge.

fn ration_merge( self, first: u32, second: u32, others: (Self, Self), ) -> (Self, Self)

where Balance: From<u32> + Saturating + Div<Output = Balance>,

Consume self and add its two components, defined by the ratio first:second, element-wise to two pre-existing Imbalances.

A convenient replacement for split and merge.

fn split_merge_into(self, amount: Balance, others: &mut (Self, Self))

Consume self and add its two components, defined by the first component’s balance, element-wise into two pre-existing Imbalance refs.

A convenient replacement for split and subsume.

fn ration_merge_into(self, first: u32, second: u32, others: &mut (Self, Self))

where Balance: From<u32> + Saturating + Div<Output = Balance>,

Consume self and add its two components, defined by the ratio first:second, element-wise to two pre-existing Imbalances.

A convenient replacement for split and merge.

fn merge_into(self, other: &mut Self)

Consume self to mutate other so that it combines both. Just like subsume, only with reversed arguments.

fn maybe_merge(self, other: Option<Self>) -> Self

Consume self and maybe an other to return a new instance that combines both.

fn maybe_subsume(&mut self, other: Option<Self>)

Maybe consume an other to mutate self into a new instance that combines both.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<Balance> Imbalance<Balance> for ()

where Balance: Default,

type Opposite = ()

fn zero()

fn drop_zero(self) -> Result<(), ()>

fn split(self, _: Balance) -> ((), ())

fn extract(&mut self, _: Balance)

fn ration(self, _: u32, _: u32) -> ((), ())

where Balance: From<u32> + Saturating + Div<Output = Balance>,

fn split_merge(self, _: Balance, _: ((), ())) -> ((), ())

fn ration_merge(self, _: u32, _: u32, _: ((), ())) -> ((), ())

where Balance: From<u32> + Saturating + Div<Output = Balance>,

fn split_merge_into(self, _: Balance, _: &mut ((), ()))

fn ration_merge_into(self, _: u32, _: u32, _: &mut ((), ()))

where Balance: From<u32> + Saturating + Div<Output = Balance>,

fn merge(self, _: ())

fn merge_into(self, _: &mut ())

fn maybe_merge(self, _: Option<()>)

fn subsume(&mut self, _: ())

fn maybe_subsume(&mut self, _: Option<()>)

fn offset( self, _: <() as Imbalance<Balance>>::Opposite, ) -> SameOrOther<(), <() as Imbalance<Balance>>::Opposite>

fn peek(&self) -> Balance

Implementors

impl<B, OnDrop, OppositeOnDrop> Imbalance<B> for Imbalance<B, OnDrop, OppositeOnDrop>

where B: Balance, OnDrop: HandleImbalanceDrop<B>, OppositeOnDrop: HandleImbalanceDrop<B>,

type Opposite = Imbalance<B, OppositeOnDrop, OnDrop>