Skip to main content

Module sui::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 
Balance
s.

use std::address;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::type_name;
use std::vector;
use sui::accumulator;
use sui::address;
use sui::dynamic_field;
use sui::funds_accumulator;
use sui::hex;
use sui::object;
use sui::party;
use sui::transfer;
use sui::tx_context;
use sui::vec_map;

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
Click to open
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
Click to open
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;

System operation performed for a coin other than SUI

const ENotSUI: u64 = 4;

const SUI_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, 115, 117, 105, 58, 58, 83, 85, 73];

Function value​

Get the amount stored in a 

Balance
.

public fun value<T>(self: &sui::balance::Balance<T>): u64
Click to open
Implementation
public fun value<T>(self: &Balance<T>): u64 {
    self.value
}

Function supply_value​

Get the 

Supply
value.

public fun supply_value<T>(supply: &sui::balance::Supply<T>): u64
Click to open
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): sui::balance::Supply<T>
Click to open
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 sui::balance::Supply<T>, value: u64): sui::balance::Balance<T>
Click to open
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 sui::balance::Supply<T>, balance: sui::balance::Balance<T>): u64
Click to open
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>(): sui::balance::Balance<T>
Click to open
Implementation
public fun zero<T>(): Balance<T> {
    Balance { value: 0 }
}

Function join​

Join two balances together.

public fun join<T>(self: &mut sui::balance::Balance<T>, balance: sui::balance::Balance<T>): u64
Click to open
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 sui::balance::Balance<T>, value: u64): sui::balance::Balance<T>
Click to open
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 sui::balance::Balance<T>): sui::balance::Balance<T>
Click to open
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: sui::balance::Balance<T>)
Click to open
Implementation
public fun destroy_zero<T>(balance: Balance<T>) {
    assert!(balance.value == 0, ENonZero);
    let Balance { value: _ } = balance;
}

Function send_funds​

Send a 

Balance
to an address's funds accumulator.

public(package) fun send_funds<T>(balance: sui::balance::Balance<T>, recipient: address)
Click to open
Implementation
public(package) fun send_funds<T>(balance: Balance<T>, recipient: address) {
    sui::funds_accumulator::add_impl(balance, recipient);
}

Function redeem_funds​

Redeem a 

Withdrawal<Balance<T>>
to get the underlying 
Balance<T>
from an address's funds accumulator.

public(package) fun redeem_funds<T>(withdrawal: sui::funds_accumulator::Withdrawal<sui::balance::Balance<T>>): sui::balance::Balance<T>
Click to open
Implementation
public(package) fun redeem_funds<T>(
    withdrawal: sui::funds_accumulator::Withdrawal<Balance<T>>,
): Balance<T> {
    withdrawal.redeem()
}

Function withdraw_funds_from_object​

Create a 

Withdrawal<Balance<T>>
from an object to withdraw funds from it.

public(package) fun withdraw_funds_from_object<T>(obj: &mut sui::object::UID, value: u64): sui::funds_accumulator::Withdrawal<sui::balance::Balance<T>>
Click to open
Implementation
public(package) fun withdraw_funds_from_object<T>(
    obj: &mut UID,
    value: u64,
): Withdrawal<Balance<T>> {
    sui::funds_accumulator::withdraw_from_object(obj, value as u256)
}

Function create_supply_internal​

public(package) fun create_supply_internal<T>(): sui::balance::Supply<T>
Click to open
Implementation
public(package) fun create_supply_internal<T>(): Supply<T> {
    Supply { value: 0 }
}

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: &sui::tx_context::TxContext): sui::balance::Balance<T>
Click to open
Implementation
fun create_staking_rewards<T>(value: u64, ctx: &TxContext): Balance<T> {
    assert!(ctx.sender() == @0x0, ENotSystemAddress);
    assert!(
        std::type_name::with_defining_ids<T>().into_string().into_bytes() == SUI_TYPE_NAME,
        ENotSUI,
    );
    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: sui::balance::Balance<T>, ctx: &sui::tx_context::TxContext)
Click to open
Implementation
fun destroy_storage_rebates<T>(self: Balance<T>, ctx: &TxContext) {
    assert!(ctx.sender() == @0x0, ENotSystemAddress);
    assert!(
        std::type_name::with_defining_ids<T>().into_string().into_bytes() == SUI_TYPE_NAME,
        ENotSUI,
    );
    let Balance { value: _ } = self;
}

Function destroy_supply​

Destroy a 

Supply
preventing any further minting and burning.

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

Function send_to_account​

fun send_to_account<T>(balance: sui::balance::Balance<T>, recipient: address)
Click to open
Implementation
fun send_to_account<T>(balance: Balance<T>, recipient: address) {
    balance.send_funds(recipient)
}

Function withdraw_from_account​

fun withdraw_from_account<T>(amount: u64, ctx: &sui::tx_context::TxContext): sui::balance::Balance<T>
Click to open
Implementation
fun withdraw_from_account<T>(amount: u64, ctx: &TxContext): Balance<T> {
    let owner = ctx.sender();
    let withdrawal = sui::funds_accumulator::create_withdrawal<Balance<T>>(owner, amount as u256);
    withdrawal.redeem()
}