This module provides the foundation for typesafe Coins.
- Struct
Coin - Resource
CoinInfo - Struct
MintEvent - Struct
BurnEvent - Constants
- Function
genesis_init - Function
coin_address - Function
check_coin_info_registered - Function
is_registered - Function
coin_info_id - Function
name - Function
symbol - Function
decimals - Function
supply - Function
icon_url - 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
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
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;
Symbol of the coin is too long
const ErrorCoinSymbolTooLong: u64 = 7;
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)
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 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 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 amount of coin in existence.
public fun supply<CoinType: key>(coin_info: &coin::CoinInfo<CoinType>): u256
Returns the icon url of coin.
public fun icon_url<CoinType: key>(coin_info: &object::Object<coin::CoinInfo<CoinType>>): 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>
Upsert icon_url asCoinType dynamic field
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, decimals: u8): 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>