Skip to main content

Module iota::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 iota::tx_context;
use std::address;
use std::ascii;
use std::option;
use std::type_name;
use std::vector;

Module Functions​

pub create_supply​

Create a new supply for type T.

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

pub zero​

Create a zero Balance for type T.

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

prv 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: &iota::tx_context::TxContext): iota::balance::Balance<T>
Implementation
fun create_staking_rewards<T>(value: u64, ctx: &TxContext): Balance<T> {
    assert!(ctx.sender() == @0x0, ENotSystemAddress);
    assert!(std::type_name::get<T>().into_string().into_bytes() == IOTA_TYPE_NAME, ENotIOTA);
    Balance { value }
}

Structs​

struct Supply​

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

public struct Supply<phantom T> has store
Fields
value: u64

pub decrease_supply​

Burn a Balance<T> and decrease Supply<T>.

public fun decrease_supply<T>(self: &mut iota::balance::Supply<T>, balance: iota::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
}

pub increase_supply​

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

public fun increase_supply<T>(self: &mut iota::balance::Supply<T>, value: u64): iota::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 }
}

pub supply_value​

Get the Supply value.

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

pub(pkg) destroy_supply​

Destroy a Supply preventing any further minting and burning.

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

struct Balance​

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

public struct Balance<phantom T> has store
Fields
value: u64

pub destroy_zero​

Destroy a zero Balance.

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

pub join​

Join two balances together.

public fun join<T>(self: &mut iota::balance::Balance<T>, balance: iota::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
}

pub split​

Split a Balance and take a sub balance from it.

public fun split<T>(self: &mut iota::balance::Balance<T>, value: u64): iota::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 }
}

pub value​

Get the amount stored in a Balance.

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

pub withdraw_all​

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

public fun withdraw_all<T>(self: &mut iota::balance::Balance<T>): iota::balance::Balance<T>
Implementation
public fun withdraw_all<T>(self: &mut Balance<T>): Balance<T> {
    let value = self.value;
    split(self, value)
}

prv 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: iota::balance::Balance<T>, ctx: &iota::tx_context::TxContext)
Implementation
fun destroy_genesis_supply<T>(self: Balance<T>, ctx: &TxContext) {
    assert!(ctx.sender() == @0x0, ENotSystemAddress);
    assert!(ctx.epoch() == 0, ENotGenesisEpoch);
    assert!(std::type_name::get<T>().into_string().into_bytes() == IOTA_TYPE_NAME, ENotIOTA);
    let Balance { value: _ } = self;
}

prv 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: iota::balance::Balance<T>, ctx: &iota::tx_context::TxContext)
Implementation
fun destroy_storage_rebates<T>(self: Balance<T>, ctx: &TxContext) {
    assert!(ctx.sender() == @0x0, ENotSystemAddress);
    assert!(std::type_name::get<T>().into_string().into_bytes() == IOTA_TYPE_NAME, ENotIOTA);
    let Balance { value: _ } = self;
}

Constants​

err ENonZero​

For when trying to destroy a non-zero balance.

const ENonZero: u64 = 0;

err EOverflow​

For when an overflow is happening on Supply operations.

const EOverflow: u64 = 1;

err ENotEnough​

For when trying to withdraw more than there is.

const ENotEnough: u64 = 2;

err ENotSystemAddress​

Sender is not @0x0 the system address.

const ENotSystemAddress: u64 = 3;

err ENotGenesisEpoch​

Epoch is not 0 (the genesis epoch).

const ENotGenesisEpoch: u64 = 4;

err ENotIOTA​

System operation performed for a coin other than IOTA

const ENotIOTA: u64 = 5;

const IOTA_TYPE_NAME​

const IOTA_TYPE_NAME: vector<u8> = vector[48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 50, 58, 58, 105, 111, 116, 97, 58, 58, 73, 79, 84, 65];