Module 0x2::coin
Defines the Coin
type - platform wide representation of fungible
tokens and coins. Coin
can be described as a secure wrapper around
Balance
type.
- Resource
Coin
- Resource
CoinMetadata
- Resource
RegulatedCoinMetadata
- Resource
TreasuryCap
- Resource
DenyCapV1
- Constants
- Function
total_supply
- Function
treasury_into_supply
- Function
supply_immut
- Function
supply_mut
- Function
value
- Function
balance
- Function
balance_mut
- Function
from_balance
- Function
into_balance
- Function
take
- Function
put
- Function
join
- Function
split
- Function
divide_into_n
- Function
zero
- Function
destroy_zero
- Function
create_currency
- Function
create_regulated_currency_v1
- Function
mint
- Function
mint_balance
- Function
burn
- Function
deny_list_v1_add
- Function
deny_list_v1_remove
- Function
deny_list_v1_contains_current_epoch
- Function
deny_list_v1_contains_next_epoch
- Function
deny_list_v1_enable_global_pause
- Function
deny_list_v1_disable_global_pause
- Function
deny_list_v1_is_global_pause_enabled_current_epoch
- Function
deny_list_v1_is_global_pause_enabled_next_epoch
- Function
mint_and_transfer
- Function
update_name
- Function
update_symbol
- Function
update_description
- Function
update_icon_url
- Function
get_decimals
- Function
get_name
- Function
get_symbol
- Function
get_description
- Function
get_icon_url
use 0x1::ascii;
use 0x1::option;
use 0x1::string;
use 0x1::type_name;
use 0x2::balance;
use 0x2::deny_list;
use 0x2::object;
use 0x2::transfer;
use 0x2::tx_context;
use 0x2::types;
use 0x2::url;
Resource Coin
A coin of type T
worth value
. Transferable and storable
struct Coin<T> has store, key
Fields
Resource CoinMetadata
Each Coin type T created through create_currency
function will have a
unique instance of CoinMetadata<T>
that stores the metadata for this coin type.
struct CoinMetadata<T> has store, key
Fields
Resource RegulatedCoinMetadata
Similar to CoinMetadata, but created only for regulated coins that use the DenyList. This object is always immutable.
struct RegulatedCoinMetadata<T> has key
Fields
Resource TreasuryCap
Capability allowing the bearer to mint and burn
coins of type T
. Transferable
struct TreasuryCap<T> has store, key
Fields
Resource DenyCapV1
Capability allowing the bearer to deny addresses from using the currency's coins--
immediately preventing those addresses from interacting with the coin as an input to a
transaction and at the start of the next preventing them from receiving the coin.
If allow_global_pause
is true, the bearer can enable a global pause that behaves as if
all addresses were added to the deny list.
struct DenyCapV1<T> has store, key
Fields
Constants
Trying to split a coin more times than its balance allows.
const ENotEnough: u64 = 2;
The index into the deny list vector for the iota::coin::Coin
type.
const DENY_LIST_COIN_INDEX: u64 = 0;
A type passed to create_supply is not a one-time witness.
const EBadWitness: u64 = 0;
const EGlobalPauseNotAllowed: u64 = 3;
Invalid arguments are passed to a function.
const EInvalidArg: u64 = 1;
Function total_supply
Return the total number of T
's in circulation.
public fun total_supply<T>(cap: &coin::TreasuryCap<T>): u64
Implementation
Function treasury_into_supply
Unwrap TreasuryCap
getting the Supply
.
Operation is irreversible. Supply cannot be converted into a TreasuryCap
due
to different security guarantees (TreasuryCap can be created only once for a type)
public fun treasury_into_supply<T>(treasury: coin::TreasuryCap<T>): balance::Supply<T>
Implementation
Function supply_immut
Get immutable reference to the treasury's Supply
.
public fun supply_immut<T>(treasury: &coin::TreasuryCap<T>): &balance::Supply<T>
Implementation
Function supply_mut
Get mutable reference to the treasury's Supply
.
public fun supply_mut<T>(treasury: &mut coin::TreasuryCap<T>): &mut balance::Supply<T>
Implementation
Function value
Public getter for the coin's value
public fun value<T>(self: &coin::Coin<T>): u64
Implementation
Function balance
Get immutable reference to the balance of a coin.
public fun balance<T>(coin: &coin::Coin<T>): &balance::Balance<T>
Implementation
Function balance_mut
Get a mutable reference to the balance of a coin.
public fun balance_mut<T>(coin: &mut coin::Coin<T>): &mut balance::Balance<T>
Implementation
Function from_balance
Wrap a balance into a Coin to make it transferable.
public fun from_balance<T>(balance: balance::Balance<T>, ctx: &mut tx_context::TxContext): coin::Coin<T>
Implementation
Function into_balance
Destruct a Coin wrapper and keep the balance.
public fun into_balance<T>(coin: coin::Coin<T>): balance::Balance<T>
Implementation
Function take
Take a Coin
worth of value
from Balance
.
Aborts if value > balance.value
public fun take<T>(balance: &mut balance::Balance<T>, value: u64, ctx: &mut tx_context::TxContext): coin::Coin<T>
Implementation
Function put
Put a Coin<T>
to the Balance<T>
.
public fun put<T>(balance: &mut balance::Balance<T>, coin: coin::Coin<T>)
Implementation
Function join
Consume the coin c
and add its value to self
.
Aborts if c.value + self.value > U64_MAX
public entry fun join<T>(self: &mut coin::Coin<T>, c: coin::Coin<T>)
Implementation
Function split
Split coin self
to two coins, one with balance split_amount
,
and the remaining balance is left is self
.
public fun split<T>(self: &mut coin::Coin<T>, split_amount: u64, ctx: &mut tx_context::TxContext): coin::Coin<T>
Implementation
Function divide_into_n
Split coin self
into n - 1
coins with equal balances. The remainder is left in
self
. Return newly created coins.
public fun divide_into_n<T>(self: &mut coin::Coin<T>, n: u64, ctx: &mut tx_context::TxContext): vector<coin::Coin<T>>
Implementation
Function zero
Make any Coin with a zero value. Useful for placeholding bids/payments or preemptively making empty balances.
public fun zero<T>(ctx: &mut tx_context::TxContext): coin::Coin<T>
Implementation
Function destroy_zero
Destroy a coin with value zero
public fun destroy_zero<T>(c: coin::Coin<T>)
Implementation
Function create_currency
Create a new currency type T
as and return the TreasuryCap
for
T
to the caller. Can only be called with a one-time-witness
type, ensuring that there's only one TreasuryCap
per T
.
public fun create_currency<T: drop>(witness: T, decimals: u8, symbol: vector<u8>, name: vector<u8>, description: vector<u8>, icon_url: option::Option<url::Url>, ctx: &mut tx_context::TxContext): (coin::TreasuryCap<T>, coin::CoinMetadata<T>)
Implementation
Function create_regulated_currency_v1
This creates a new currency, via create_currency
, but with an extra capability that
allows for specific addresses to have their coins frozen. When an address is added to the
deny list, it is immediately unable to interact with the currency's coin as input objects.
Additionally at the start of the next epoch, they will be unable to receive the currency's
coin.
The allow_global_pause
flag enables an additional API that will cause all addresses to
be denied. Note however, that this doesn't affect per-address entries of the deny list and
will not change the result of the "contains" APIs.
public fun create_regulated_currency_v1<T: drop>(witness: T, decimals: u8, symbol: vector<u8>, name: vector<u8>, description: vector<u8>, icon_url: option::Option<url::Url>, allow_global_pause: bool, ctx: &mut tx_context::TxContext): (coin::TreasuryCap<T>, coin::DenyCapV1<T>, coin::CoinMetadata<T>)
Implementation
Function mint
Create a coin worth value
and increase the total supply
in cap
accordingly.
public fun mint<T>(cap: &mut coin::TreasuryCap<T>, value: u64, ctx: &mut tx_context::TxContext): coin::Coin<T>
Implementation
Function mint_balance
Mint some amount of T as a Balance
and increase the total
supply in cap
accordingly.
Aborts if value
+ cap.total_supply
>= U64_MAX
public fun mint_balance<T>(cap: &mut coin::TreasuryCap<T>, value: u64): balance::Balance<T>
Implementation
Function burn
Destroy the coin c
and decrease the total supply in cap
accordingly.
public entry fun burn<T>(cap: &mut coin::TreasuryCap<T>, c: coin::Coin<T>): u64
Implementation
Function deny_list_v1_add
Adds the given address to the deny list, preventing it from interacting with the specified coin type as an input to a transaction. Additionally at the start of the next epoch, the address will be unable to receive objects of this coin type.
public fun deny_list_v1_add<T>(deny_list: &mut deny_list::DenyList, _deny_cap: &mut coin::DenyCapV1<T>, addr: address, ctx: &mut tx_context::TxContext)
Implementation
Function deny_list_v1_remove
Removes an address from the deny list. Similar to deny_list_v1_add
, the effect for input
objects will be immediate, but the effect for receiving objects will be delayed until the
next epoch.
public fun deny_list_v1_remove<T>(deny_list: &mut deny_list::DenyList, _deny_cap: &mut coin::DenyCapV1<T>, addr: address, ctx: &mut tx_context::TxContext)
Implementation
Function deny_list_v1_contains_current_epoch
Check if the deny list contains the given address for the current epoch. Denied addresses in the current epoch will be unable to receive objects of this coin type.
public fun deny_list_v1_contains_current_epoch<T>(deny_list: &deny_list::DenyList, addr: address, ctx: &tx_context::TxContext): bool
Implementation
Function deny_list_v1_contains_next_epoch
Check if the deny list contains the given address for the next epoch. Denied addresses in the next epoch will immediately be unable to use objects of this coin type as inputs. At the start of the next epoch, the address will be unable to receive objects of this coin type.
public fun deny_list_v1_contains_next_epoch<T>(deny_list: &deny_list::DenyList, addr: address): bool
Implementation
Function deny_list_v1_enable_global_pause
Enable the global pause for the given coin type. This will immediately prevent all addresses from using objects of this coin type as inputs. At the start of the next epoch, all addresses will be unable to receive objects of this coin type.
public fun deny_list_v1_enable_global_pause<T>(deny_list: &mut deny_list::DenyList, deny_cap: &mut coin::DenyCapV1<T>, ctx: &mut tx_context::TxContext)
Implementation
Function deny_list_v1_disable_global_pause
Disable the global pause for the given coin type. This will immediately allow all addresses to resume using objects of this coin type as inputs. However, receiving objects of this coin type will still be paused until the start of the next epoch.
public fun deny_list_v1_disable_global_pause<T>(deny_list: &mut deny_list::DenyList, deny_cap: &mut coin::DenyCapV1<T>, ctx: &mut tx_context::TxContext)
Implementation
Function deny_list_v1_is_global_pause_enabled_current_epoch
Check if the global pause is enabled for the given coin type in the current epoch.
public fun deny_list_v1_is_global_pause_enabled_current_epoch<T>(deny_list: &deny_list::DenyList, ctx: &tx_context::TxContext): bool
Implementation
Function deny_list_v1_is_global_pause_enabled_next_epoch
Check if the global pause is enabled for the given coin type in the next epoch.
public fun deny_list_v1_is_global_pause_enabled_next_epoch<T>(deny_list: &deny_list::DenyList): bool
Implementation
Function mint_and_transfer
Mint amount
of Coin
and send it to recipient
. Invokes mint()
.
public entry fun mint_and_transfer<T>(c: &mut coin::TreasuryCap<T>, amount: u64, recipient: address, ctx: &mut tx_context::TxContext)
Implementation
Function update_name
Update name of the coin in CoinMetadata
public entry fun update_name<T>(_treasury: &coin::TreasuryCap<T>, metadata: &mut coin::CoinMetadata<T>, name: string::String)
Implementation
Function update_symbol
Update the symbol of the coin in CoinMetadata
public entry fun update_symbol<T>(_treasury: &coin::TreasuryCap<T>, metadata: &mut coin::CoinMetadata<T>, symbol: ascii::String)
Implementation
Function update_description
Update the description of the coin in CoinMetadata
public entry fun update_description<T>(_treasury: &coin::TreasuryCap<T>, metadata: &mut coin::CoinMetadata<T>, description: string::String)
Implementation
Function update_icon_url
Update the url of the coin in CoinMetadata
public entry fun update_icon_url<T>(_treasury: &coin::TreasuryCap<T>, metadata: &mut coin::CoinMetadata<T>, url: ascii::String)
Implementation
Function get_decimals
public fun get_decimals<T>(metadata: &coin::CoinMetadata<T>): u8
Implementation
Function get_name
public fun get_name<T>(metadata: &coin::CoinMetadata<T>): string::String
Implementation
Function get_symbol
public fun get_symbol<T>(metadata: &coin::CoinMetadata<T>): ascii::String
Implementation
Function get_description
public fun get_description<T>(metadata: &coin::CoinMetadata<T>): string::String
Implementation
Function get_icon_url
public fun get_icon_url<T>(metadata: &coin::CoinMetadata<T>): option::Option<url::Url>