# Module sui::balance *[Documentation index](/llms.txt) ยท [Full index](/llms-full.txt)* 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](../sui_sui/balance#sui_balance_Supply) and [Balance](../sui_sui/balance#sui_balance_Balance)s. ``` use std::address; use std::ascii; use std::bcs; use std::internal; use std::option; use std::string; use std::type_name; use std::u128; 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::protocol_config; 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 ``` **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; ``` 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](../sui_sui/balance#sui_balance_Balance). ``` public fun value<T>(self: &sui::balance::Balance<T>): u64 ``` ## Function supply_value Get the [Supply](../sui_sui/balance#sui_balance_Supply) value. ``` public fun supply_value<T>(supply: &sui::balance::Supply<T>): u64 ``` ## Function create_supply Create a new supply for type T. ``` public fun create_supply<T: drop>(_: T): sui::balance::Supply<T> ``` ## Function increase_supply Increase supply by [value](../sui_sui/balance#sui_balance_value) and create a new [Balance](../sui_sui/balance#sui_balance_Balance)<T> with this value. ``` public fun increase_supply<T>(self: &mut sui::balance::Supply<T>, value: u64): sui::balance::Balance<T> ``` ## 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 ``` ## Function zero Create a zero [Balance](../sui_sui/balance#sui_balance_Balance) for type T. ``` public fun zero<T>(): sui::balance::Balance<T> ``` ## Function join Join two balances together. ``` public fun join<T>(self: &mut sui::balance::Balance<T>, balance: sui::balance::Balance<T>): u64 ``` ## Function split Split a [Balance](../sui_sui/balance#sui_balance_Balance) and take a sub balance from it. ``` public fun split<T>(self: &mut sui::balance::Balance<T>, value: u64): sui::balance::Balance<T> ``` ## 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> ``` ## Function destroy_zero Destroy a zero [Balance](../sui_sui/balance#sui_balance_Balance). ``` public fun destroy_zero<T>(balance: sui::balance::Balance<T>) ``` ## Function send_funds Send a [Balance](../sui_sui/balance#sui_balance_Balance) to an address's funds accumulator. ``` public fun send_funds<T>(balance: sui::balance::Balance<T>, recipient: address) ``` ## Function redeem_funds Redeem a Withdrawal<[Balance](../sui_sui/balance#sui_balance_Balance)<T>> to get the underlying [Balance](../sui_sui/balance#sui_balance_Balance)<T> from an address's funds accumulator. ``` public fun redeem_funds<T>(withdrawal: sui::funds_accumulator::Withdrawal<sui::balance::Balance<T>>): sui::balance::Balance<T> ``` ## Function withdraw_funds_from_object Create a Withdrawal<[Balance](../sui_sui/balance#sui_balance_Balance)<T>> from an object to withdraw funds from it. ``` public fun withdraw_funds_from_object<T>(obj: &mut sui::object::UID, value: u64): sui::funds_accumulator::Withdrawal<sui::balance::Balance<T>> ``` ## Function settled_funds_value Read the value of the funds of type T owned by **address** as of the beginning of the current consensus commit. Can read either address-owned or object-owned balances. ``` public fun settled_funds_value<T>(root: &sui::accumulator::AccumulatorRoot, address: address): u64 ``` ## Function create_supply_internal ``` public(package) fun create_supply_internal<T>(): sui::balance::Supply<T> ``` ## Function create_staking_rewards CAUTION: this function creates a [Balance](../sui_sui/balance#sui_balance_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> ``` ## Function destroy_storage_rebates CAUTION: this function destroys a [Balance](../sui_sui/balance#sui_balance_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) ``` ## Function destroy_supply Destroy a [Supply](../sui_sui/balance#sui_balance_Supply) preventing any further minting and burning. ``` public(package) fun destroy_supply<T>(self: sui::balance::Supply<T>): u64 ```