balance.md

Module 0x2::balance

A storable handler for Balances in general. Is used in the Coin module to allow balance operations and can be used to implement custom coins with Supply and Balances.

• Struct Supply
• Struct Balance
• Constants
• Function value
• Function supply_value
• Function create_supply
• Function increase_supply
• Function decrease_supply
• Function zero
• Function join
• Function split
• Function destroy_zero

Struct Supply

A Supply of T. Used for minting and burning. Wrapped into a TreasuryCap in the Coin module.

struct Supply<T> has store

Fields

value: u64

Struct Balance

Storable balance - an inner struct of a Coin type. Can be used to store coins which don't need the key ability.

struct Balance<T> has store

Fields

value: u64

Constants

For when trying to destroy a non-zero balance.

const ENonZero: u64 = 0;

For when trying to withdraw more than there is.

const ENotEnough: u64 = 2;

For when an overflow is happening on Supply operations.

const EOverflow: u64 = 1;

Function value

Get the amount stored in a Balance.

public fun value<T>(self: &balance::Balance<T>): u64

Implementation

public fun value<T>(self: &Balance<T>): u64 {
    self.value
}

Function supply_value

Get the Supply value.

public fun supply_value<T>(supply: &balance::Supply<T>): u64

Implementation

public fun supply_value<T>(supply: &Supply<T>): u64 {
    supply.value
}

Function create_supply

Create a new supply for type T.

public fun create_supply<T: drop>(_: T): balance::Supply<T>

Implementation

public fun create_supply<T: drop>(_: T): Supply<T> {
    Supply { value: 0 }
}

Function increase_supply

Increase supply by value and create a new Balance<T> with this value.

public fun increase_supply<T>(self: &mut balance::Supply<T>, value: u64): balance::Balance<T>

Implementation

public fun increase_supply<T>(self: &mut Supply<T>, value: u64): Balance<T> {
    assert!(value < (18446744073709551615u64 - self.value), EOverflow);
    self.value = self.value + value;
    Balance { value }
}

Function decrease_supply

Burn a Balance and decrease Supply.

public fun decrease_supply<T>(self: &mut balance::Supply<T>, balance: balance::Balance<T>): u64

Implementation

public fun decrease_supply<T>(self: &mut Supply<T>, balance: Balance<T>): u64 {
    let Balance { value } = balance;
    assert!(self.value >= value, EOverflow);
    self.value = self.value - value;
    value
}

Function zero

Create a zero Balance for type T.

public fun zero<T>(): balance::Balance<T>

Implementation

public fun zero<T>(): Balance<T> {
    Balance { value: 0 }
}

Specification

aborts_if false;
ensures result.value == 0;

Function join

Join two balances together.

public fun join<T>(self: &mut balance::Balance<T>, balance: balance::Balance<T>): u64

Implementation

public fun join<T>(self: &mut Balance<T>, balance: Balance<T>): u64 {
    let Balance { value } = balance;
    self.value = self.value + value;
    self.value
}

Specification

ensures self.value == old(self.value) + balance.value;
ensures result == self.value;

Function split

Split a Balance and take a sub balance from it.

public fun split<T>(self: &mut balance::Balance<T>, value: u64): balance::Balance<T>

Implementation

public fun split<T>(self: &mut Balance<T>, value: u64): Balance<T> {
    assert!(self.value >= value, ENotEnough);
    self.value = self.value - value;
    Balance { value }
}

Specification

aborts_if self.value < value with ENotEnough;
ensures self.value == old(self.value) - value;
ensures result.value == value;

Function destroy_zero

Destroy a zero Balance.

public fun destroy_zero<T>(balance: balance::Balance<T>)

Implementation

public fun destroy_zero<T>(balance: Balance<T>) {
    assert!(balance.value == 0, ENonZero);
    let Balance { value: _ } = balance;
}

Specification

aborts_if balance.value != 0 with ENonZero;