This module provides the foundation for typesafe Coins.
- Struct
Coin - Resource
CoinInfo - Resource
CoinMetadata - Resource
CoinRegistry - Struct
MintEvent - Struct
BurnEvent - Constants
- Function
genesis_init - Function
init_coin_registry - Function
coin_address - Function
check_coin_info_registered - Function
is_registered - Function
coin_info_id - Function
name - Function
name_by_type - Function
symbol - Function
symbol_by_type - Function
decimals - Function
decimals_by_type - Function
supply - Function
supply_by_type - Function
icon_url - Function
icon_url_by_type - Function
is_same_coin - Function
destroy_zero - Function
extract - Function
extract_all - Function
merge - Function
value - Function
zero - Function
coin_info - Function
upsert_icon_url - Function
register_extend - Function
init_metadata - Function
mint - Function
mint_extend - Function
burn - Function
burn_extend - Function
unpack - Function
pack
use 0x1::option;
use 0x1::string;
use 0x2::event;
use 0x2::object;
use 0x2::type_info;
Main structure representing a coin.
Note the CoinType must have key ability.
if the CoinType has store ability, the Coin is a public coin, the user can operate it directly by coin module's function.
Otherwise, the Coin is a private coin, the user can only operate it by CoinType module's function.
The Coin has no ability, it is a hot potato type, only can handle by Coin module.
struct Coin<CoinType: key>
Information about a specific coin type. Stored in the global Object storage.
CoinInfo is a named Object, the coin_type is the unique key.
struct CoinInfo<CoinType: key> has store, key
Coin metadata is copied from CoinInfo, and stored as dynamic field of CoinRegistry
struct CoinMetadata has store, key
The registry of all coin types.
struct CoinRegistry has key
Event emitted when coin minted.
struct MintEvent has copy, drop, store
Event emitted when coin burned.
struct BurnEvent has copy, drop, store
Maximum possible aggregatable coin value.
const MAX_U64: u128 = 18446744073709551615;
Maximum possible coin supply.
const MAX_U128: u128 = 340282366920938463463374607431768211455;
const MAX_U256: u256 = 115792089237316195423570985008687907853269984665640564039457584007913129639935;
CoinType is already registered as a coin
const ErrorCoinInfoAlreadyRegistered: u64 = 2;
CoinType is not registered as a coin
const ErrorCoinInfoNotRegistered: u64 = 1;
Global CoinInfos should exist
const ErrorCoinInfosNotFound: u64 = 8;
Name of the coin is too long
const ErrorCoinNameTooLong: u64 = 6;
CoinRegister is already initialized
const ErrorCoinRegisterAlreadyInitialized: u64 = 9;
Symbol of the coin is too long
const ErrorCoinSymbolTooLong: u64 = 7;
The function is deprecated
const ErrorDeprecated: u64 = 10;
Cannot destroy non-zero coins
const ErrorDestroyOfNonZeroCoin: u64 = 4;
Not enough coins to extract
const ErrorInsufficientBalance: u64 = 3;
Coin amount cannot be zero
const ErrorZeroCoinAmount: u64 = 5;
const MAX_COIN_NAME_LENGTH: u64 = 32;
const MAX_COIN_SYMBOL_LENGTH: u64 = 10;
public(friend) fun genesis_init(__genesis_account: &signer)
Initialize the CoinRegistry, this function is for framework upgrade.
entry fun init_coin_registry()
A helper function that returns the address of CoinType.
public fun coin_address<CoinType: key>(): address
A helper function that check the CoinType is registered, if not, abort.
public fun check_coin_info_registered<CoinType: key>()
Returns true if the type CoinType is an registered coin.
public fun is_registered<CoinType: key>(): bool
Return the ObjectID of Object<CoinInfo>
public fun coin_info_id<CoinType: key>(): object::ObjectID
Returns the name of the coin.
public fun name<CoinType: key>(coin_info: &coin::CoinInfo<CoinType>): string::String
Returns the name of the coin by the type CoinType
public fun name_by_type<CoinType: key>(): string::String
Returns the symbol of the coin, usually a shorter version of the name.
public fun symbol<CoinType: key>(coin_info: &coin::CoinInfo<CoinType>): string::String
Returns the symbol of the coin by the type CoinType
public fun symbol_by_type<CoinType: key>(): string::String
Returns the number of decimals used to get its user representation.
For example, if decimals equals 2, a balance of 505 coins should
be displayed to a user as 5.05 (505 / 10 ** 2).
public fun decimals<CoinType: key>(coin_info: &coin::CoinInfo<CoinType>): u8
Returns the decimals of the coin by the type CoinType
public fun decimals_by_type<CoinType: key>(): u8
Returns the amount of coin in existence.
public fun supply<CoinType: key>(coin_info: &coin::CoinInfo<CoinType>): u256
Returns the amount of coin in existence by the type CoinType
public fun supply_by_type<CoinType: key>(): u256
Returns the icon url of coin.
public fun icon_url<CoinType: key>(coin_info: &coin::CoinInfo<CoinType>): option::Option<string::String>
Returns the icon url of coin by the type CoinType
public fun icon_url_by_type<CoinType: key>(): option::Option<string::String>
Return true if the type CoinType1 is same with CoinType2
public fun is_same_coin<CoinType1, CoinType2>(): bool
Destroys a zero-value coin. Calls will fail if the value in the passed-in coin is non-zero
so it is impossible to "burn" any non-zero amount of Coin.
public fun destroy_zero<CoinType: key>(zero_coin: coin::Coin<CoinType>)
Extracts amount from the passed-in coin, where the original coin is modified in place.
public fun extract<CoinType: key>(coin: &mut coin::Coin<CoinType>, amount: u256): coin::Coin<CoinType>
Extracts the entire amount from the passed-in coin, where the original coin is modified in place.
public fun extract_all<CoinType: key>(coin: &mut coin::Coin<CoinType>): coin::Coin<CoinType>
"Merges" the two given coins. The coin passed in as dst_coin will have a value equal
to the sum of the two coins (dst_coin and source_coin).
public fun merge<CoinType: key>(dst_coin: &mut coin::Coin<CoinType>, source_coin: coin::Coin<CoinType>)
Returns the value passed in coin.
public fun value<CoinType: key>(coin: &coin::Coin<CoinType>): u256
Create a new Coin<CoinType> with a value of 0.
public fun zero<CoinType: key>(): coin::Coin<CoinType>
Borrow the CoinInfo
public fun coin_info<CoinType: key>(): &coin::CoinInfo<CoinType>
This function is protected by private_generics, so it can only be called by the CoinType module.
#[private_generics(#[CoinType])]
public fun upsert_icon_url<CoinType: key>(coin_info_obj: &mut object::Object<coin::CoinInfo<CoinType>>, icon_url: string::String)
Creates a new Coin with given CoinType
This function is protected by private_generics, so it can only be called by the CoinType module.
#[private_generics(#[CoinType])]
public fun register_extend<CoinType: key>(name: string::String, symbol: string::String, icon_url: option::Option<string::String>, decimals: u8): object::Object<coin::CoinInfo<CoinType>>
This function for the old code to initialize the CoinMetadata
public fun init_metadata<CoinType: key>(coin_info: &object::Object<coin::CoinInfo<CoinType>>)
Public coin can mint by anyone with the mutable Object<CoinInfo>
public fun mint<CoinType: store, key>(coin_info: &mut object::Object<coin::CoinInfo<CoinType>>, amount: u256): coin::Coin<CoinType>
Mint new Coin, this function is only called by the CoinType module, for the developer to extend custom mint logic
#[private_generics(#[CoinType])]
public fun mint_extend<CoinType: key>(coin_info: &mut object::Object<coin::CoinInfo<CoinType>>, amount: u256): coin::Coin<CoinType>
Public coin can burn by anyone with the mutable Object<CoinInfo>
public fun burn<CoinType: store, key>(coin_info: &mut object::Object<coin::CoinInfo<CoinType>>, coin: coin::Coin<CoinType>)
Burn coin
This function is only called by the CoinType module, for the developer to extend custom burn logic
#[private_generics(#[CoinType])]
public fun burn_extend<CoinType: key>(coin_info: &mut object::Object<coin::CoinInfo<CoinType>>, coin: coin::Coin<CoinType>)
public(friend) fun unpack<CoinType: key>(coin: coin::Coin<CoinType>): u256
public(friend) fun pack<CoinType: key>(value: u256): coin::Coin<CoinType>