# 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. - [Struct `Supply`](#iota_balance_Supply) - [Struct `Balance`](#iota_balance_Balance) - [Constants](#@Constants_0) - [Function `value`](#iota_balance_value) - [Function `supply_value`](#iota_balance_supply_value) - [Function `create_supply`](#iota_balance_create_supply) - [Function `increase_supply`](#iota_balance_increase_supply) - [Function `decrease_supply`](#iota_balance_decrease_supply) - [Function `zero`](#iota_balance_zero) - [Function `join`](#iota_balance_join) - [Function `split`](#iota_balance_split) - [Function `withdraw_all`](#iota_balance_withdraw_all) - [Function `destroy_zero`](#iota_balance_destroy_zero) - [Function `create_staking_rewards`](#iota_balance_create_staking_rewards) - [Function `destroy_storage_rebates`](#iota_balance_destroy_storage_rebates) - [Function `destroy_genesis_supply`](#iota_balance_destroy_genesis_supply) - [Function `destroy_supply`](#iota_balance_destroy_supply)

use iota::tx_context;
use std::address;
use std::ascii;
use std::option;
use std::type_name;
use std::vector;

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

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

## Constants For when trying to destroy a non-zero balance.

const ENonZero: u64 = 0;

For when an overflow is happening on Supply operations.

const EOverflow: u64 = 1;

For when trying to withdraw more than there is.

const ENotEnough: u64 = 2;

Sender is not @0x0 the system address.

const ENotSystemAddress: u64 = 3;

Epoch is not 0 (the genesis epoch).

const ENotGenesisEpoch: u64 = 4;

System operation performed for a coin other than IOTA

const ENotIOTA: u64 = 5;

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];

## Function `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
}

## Function `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
}

## Function `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 }
}

## Function `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 }
}

## Function `decrease_supply` Burn a Balance and decrease Supply.

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
}

## Function `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 }
}

## Function `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
}

## Function `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 }
}

## Function `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)
}

## Function `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;
}

## 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: &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 }
}

## 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: 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;
}

## 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: 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;
}

## Function `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
}