Skip to main content

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.

use 0x2::tx_context;

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​

Sender is not @0x0 the system address.

const ENotSystemAddress: u64 = 3;

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;

Epoch is not 0 (the genesis epoch).

const ENotGenesisEpoch: u64 = 4;

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<T> and decrease Supply<T>.

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 }
}

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
}

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 }
}

Function withdraw_all​

Withdraw all balance. After this the remaining balance must be 0.

public fun withdraw_all<T>(self: &mut balance::Balance<T>): balance::Balance<T>
Implementation
public fun withdraw_all<T>(self: &mut Balance<T>): Balance<T> {
let value = self.value;
split(self, 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;
}

Function create_staking_rewards​

CAUTION: this function creates a Balance without increasing the supply. It should only be called by the epoch change system txn to create staking rewards, and nowhere else.

fun create_staking_rewards<T>(value: u64, ctx: &tx_context::TxContext): balance::Balance<T>
Implementation
fun create_staking_rewards<T>(value: u64, ctx: &TxContext): Balance<T> {
assert!(ctx.sender() == @0x0, ENotSystemAddress);
Balance { value }
}

Function destroy_storage_rebates​

CAUTION: this function destroys a Balance without decreasing the supply. It should only be called by the epoch change system txn to destroy storage rebates, and nowhere else.

fun destroy_storage_rebates<T>(self: balance::Balance<T>, ctx: &tx_context::TxContext)
Implementation
fun destroy_storage_rebates<T>(self: Balance<T>, ctx: &TxContext) {
assert!(ctx.sender() == @0x0, ENotSystemAddress);
let Balance { value: _ } = self;
}

Function destroy_genesis_supply​

CAUTION: this function destroys a Balance without decreasing the supply. It should only be called by the genesis txn to destroy parts of the IOTA supply which was created during the migration and for no other reason.

fun destroy_genesis_supply<T>(self: balance::Balance<T>, ctx: &tx_context::TxContext)
Implementation
fun destroy_genesis_supply<T>(self: Balance<T>, ctx: &TxContext) {
assert!(ctx.sender() == @0x0, ENotSystemAddress);
assert!(ctx.epoch() == 0, ENotGenesisEpoch);
let Balance { value: _ } = self;
}

Function destroy_supply​

Destroy a Supply preventing any further minting and burning.

public(friend) fun destroy_supply<T>(self: balance::Supply<T>): u64
Implementation
public(package) fun destroy_supply<T>(self: Supply<T>): u64 {
let Supply { value } = self;
value
}