This module provides the foundation for typesafe Coins.
- Struct
Coin - Struct
GenericCoin - 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
coin_info_id_by_type_name - Function
name - Function
name_by_type - Function
name_by_type_name - Function
symbol - Function
symbol_by_type - Function
symbol_by_type_name - Function
decimals - Function
decimals_by_type - Function
decimals_by_type_name - Function
supply - Function
supply_by_type - Function
supply_by_type_name - Function
icon_url - Function
icon_url_by_type - Function
icon_url_by_type_name - Function
is_same_coin - Function
destroy_zero - Function
extract - Function
extract_all - Function
merge - Function
value - Function
zero - Function
coin_info - Function
get_coin_info_by_type_name - Function
upsert_icon_url - Function
register_extend - Function
init_metadata - Function
mint - Function
mint_extend - Function
burn - Function
burn_extend - Function
unpack - Function
pack - Function
convert_coin_to_generic_coin - Function
convert_generic_coin_to_coin - Function
check_coin_info_registered_by_type_name - Function
is_registered_by_type_name - Function
generic_coin_value - Function
unpack_generic_coin - Function
pack_generic_coin - Function
merge_generic - Function
coin_type
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>
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 GenericCoin
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 coin type is invalid
const ErrorCoinTypeInvalid: u64 = 12;
The coin type is not match
const ErrorCoinTypeNotMatch: u64 = 11;
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 coin info id by the coin type name
public fun coin_info_id_by_type_name(coin_type: string::String): 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 name of the coin by the coin type name
public fun name_by_type_name(coin_type_name: &string::String): 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 symbol of the coin by the coin type name
public fun symbol_by_type_name(coin_type_name: &string::String): 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 decimals of the coin by the coin type name
public fun decimals_by_type_name(coin_type_name: &string::String): 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 amount of coin in existence by the coin type name
public fun supply_by_type_name(coin_type_name: &string::String): 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>
Returns the icon url of the coin by the coin type name
public fun icon_url_by_type_name(coin_type_name: &string::String): 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>
public fun get_coin_info_by_type_name(coin_type_name: &string::String): option::Option<object::ObjectID>
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>
public fun convert_coin_to_generic_coin<CoinType: key>(coin: coin::Coin<CoinType>): coin::GenericCoin
public fun convert_generic_coin_to_coin<CoinType: key>(coin: coin::GenericCoin): coin::Coin<CoinType>
public fun check_coin_info_registered_by_type_name(coin_type: string::String)
public fun is_registered_by_type_name(coin_type: string::String): bool
public fun generic_coin_value(coin: &coin::GenericCoin): u256
public(friend) fun unpack_generic_coin(coin: coin::GenericCoin): (string::String, u256)
public(friend) fun pack_generic_coin(coin_type: string::String, value: u256): coin::GenericCoin
"Merges" the two given generic coins. The coin passed in as dst_coin will have a value equal
to the sum of the two generic coins (dst_coin and source_coin).
public fun merge_generic(dst_coin: &mut coin::GenericCoin, source_coin: coin::GenericCoin)
Helper function for getting the coin type name from a GenericCoin
public fun coin_type(coin: &coin::GenericCoin): string::String