Module sui::token
The Token module which implements a Closed Loop Token with a configurable policy. The policy is defined by a set of rules that must be satisfied for an action to be performed on the token.
The module is designed to be used with a TreasuryCap to allow for minting and burning of the Tokens. And can act as a replacement / extension or a companion to existing open-loop (Coin) systems.
Module: sui::balance sui::coin sui::token
Main type: Balance<T> Coin<T> Token<T>
Capability: Supply<T> <----> TreasuryCap<T> <----> TreasuryCap<T>
Abilities: store key + store key
The Token system allows for fine-grained control over the actions performed on the token. And hence it is highly suitable for applications that require control over the currency which a simple open-loop system can't provide.
- Struct
Token
- Struct
TokenPolicyCap
- Struct
TokenPolicy
- Struct
ActionRequest
- Struct
RuleKey
- Struct
TokenPolicyCreated
- Constants
- Function
new_policy
- Function
share_policy
- Function
transfer
- Function
spend
- Function
to_coin
- Function
from_coin
- Function
join
- Function
split
- Function
zero
- Function
destroy_zero
- Function
keep
- Function
new_request
- Function
confirm_request
- Function
confirm_request_mut
- Function
confirm_with_policy_cap
- Function
confirm_with_treasury_cap
- Function
add_approval
- Function
add_rule_config
- Function
rule_config
- Function
rule_config_mut
- Function
remove_rule_config
- Function
has_rule_config
- Function
has_rule_config_with_type
- Function
allow
- Function
disallow
- Function
add_rule_for_action
- Function
remove_rule_for_action
- Function
mint
- Function
burn
- Function
flush
- Function
is_allowed
- Function
rules
- Function
spent_balance
- Function
value
- Function
transfer_action
- Function
spend_action
- Function
to_coin_action
- Function
from_coin_action
- Function
action
- Function
amount
- Function
sender
- Function
recipient
- Function
approvals
- Function
spent
- Function
key
use std::address;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::type_name;
use std::vector;
use sui::address;
use sui::bag;
use sui::balance;
use sui::coin;
use sui::config;
use sui::deny_list;
use sui::dynamic_field;
use sui::dynamic_object_field;
use sui::event;
use sui::hex;
use sui::object;
use sui::table;
use sui::transfer;
use sui::tx_context;
use sui::types;
use sui::url;
use sui::vec_map;
use sui::vec_set;
Struct Token
A single Token with Balance inside. Can only be owned by an address, and actions performed on it must be confirmed in a matching TokenPolicy.
public struct TokenT has key
Fields
Struct TokenPolicyCap
A Capability that manages a single TokenPolicy specified in the for field. Created together with TokenPolicy in the new function.
public struct TokenPolicyCapT has key, store
Fields
Struct TokenPolicy
TokenPolicy represents a set of rules that define what actions can be performed on a Token and which Rules must be satisfied for the action to succeed.
- For the sake of availability, TokenPolicy is a key-only object.
- Each TokenPolicy is managed by a matching TokenPolicyCap.
- For an action to become available, there needs to be a record in the rules VecMap. To allow an action to be performed freely, there's an allow function that can be called by the TokenPolicyCap owner.
public struct TokenPolicyT has key
Fields
Struct ActionRequest
A request to perform an "Action" on a token. Stores the information about the action to be performed and must be consumed by the confirm_request or confirm_request_mut functions when the Rules are satisfied.
public struct ActionRequestT
Fields
Struct RuleKey
Dynamic field key for the TokenPolicy to store the Config for a specific action Rule. There can be only one configuration per Rule per TokenPolicy.
public struct RuleKeyT has copy, drop, store
Fields
Struct TokenPolicyCreated
An event emitted when a TokenPolicy is created and shared. Because TokenPolicy can only be shared (and potentially frozen in the future), we emit this event in the share_policy function and mark it as mutable.
public struct TokenPolicyCreatedT has copy, drop
Fields
Constants
The balance is too low to perform the action.
const EBalanceTooLow: u64 = 3;
The balance is not zero when trying to confirm with TransferPolicyCap.
const ECantConsumeBalance: u64 = 5;
Rule is trying to access a missing config (with type).
const ENoConfig: u64 = 6;
The rule was not approved.
const ENotApproved: u64 = 1;
Trying to perform an admin action with a wrong cap.
const ENotAuthorized: u64 = 2;
The balance is not zero.
const ENotZero: u64 = 4;
The action is not allowed (defined) in the policy.
const EUnknownAction: u64 = 0;
Using confirm_request_mut without spent_balance. Immutable version of the function must be used instead.
const EUseImmutableConfirm: u64 = 7;
A Tag for the from_coin action.
const FROM_COIN: vector<u8> = vector[102, 114, 111, 109, 95, 99, 111, 105, 110];
A Tag for the spend action.
const SPEND: vector<u8> = vector[115, 112, 101, 110, 100];
A Tag for the to_coin action.
const TO_COIN: vector<u8> = vector[116, 111, 95, 99, 111, 105, 110];
A Tag for the transfer action.
const TRANSFER: vector<u8> = vector[116, 114, 97, 110, 115, 102, 101, 114];
Function new_policy
Create a new TokenPolicy and a matching TokenPolicyCap. The TokenPolicy must then be shared using the share_policy method.
TreasuryCap guarantees full ownership over the currency, and is unique, hence it is safe to use it for authorization.
public fun new_policyT(_treasury_cap: &sui::coin::TreasuryCap<T>, ctx: &mut sui::tx_context::TxContext): (sui::token::TokenPolicy<T>, sui::token::TokenPolicyCap<T>)
Implementation
Function share_policy
Share the TokenPolicy. Due to key-only restriction, it must be shared after initialization.
public fun share_policyT(policy: sui::token::TokenPolicy<T>)
Implementation
Function transfer
Transfer a Token to a recipient. Creates an ActionRequest for the "transfer" action. The ActionRequest contains the recipient field to be used in verification.
public fun transferT(t: sui::token::Token<T>, recipient: address, ctx: &mut sui::tx_context::TxContext): sui::token::ActionRequest<T>
Implementation
Function spend
Spend a Token by unwrapping it and storing the Balance in the ActionRequest for the "spend" action. The ActionRequest contains the spent_balance field to be used in verification.
Spend action requires confirm_request_mut to be called to confirm the request and join the spent balance with the TokenPolicy.spent_balance.
public fun spendT(t: sui::token::Token<T>, ctx: &mut sui::tx_context::TxContext): sui::token::ActionRequest<T>
Implementation
Function to_coin
Convert Token into an open Coin. Creates an ActionRequest for the "to_coin" action.
public fun to_coinT(t: sui::token::Token<T>, ctx: &mut sui::tx_context::TxContext): (sui::coin::Coin<T>, sui::token::ActionRequest<T>)
Implementation
Function from_coin
Convert an open Coin into a Token. Creates an ActionRequest for the "from_coin" action.
public fun from_coinT(coin: sui::coin::Coin<T>, ctx: &mut sui::tx_context::TxContext): (sui::token::Token<T>, sui::token::ActionRequest<T>)
Implementation
Function join
Join two Tokens into one, always available.
public fun joinT(token: &mut sui::token::Token<T>, another: sui::token::Token<T>)
Implementation
Function split
Split a Token with amount. Aborts if the Token.balance is lower than amount.
public fun splitT(token: &mut sui::token::Token<T>, amount: u64, ctx: &mut sui::tx_context::TxContext): sui::token::Token<T>
Implementation
Function zero
Create a zero Token.
public fun zeroT(ctx: &mut sui::tx_context::TxContext): sui::token::Token<T>
Implementation
Function destroy_zero
Destroy an empty Token, fails if the balance is non-zero. Aborts if the Token.balance is not zero.
public fun destroy_zeroT(token: sui::token::Token<T>)
Implementation
Function keep
Transfer the Token to the transaction sender.
public fun keepT(token: sui::token::Token<T>, ctx: &mut sui::tx_context::TxContext)
Implementation
Function new_request
Create a new ActionRequest. Publicly available method to allow for custom actions.
public fun new_requestT(name: std::string::String, amount: u64, recipient: std::option::Option<address>, spent_balance: std::option::Option<sui::balance::Balance<T>>, ctx: &sui::tx_context::TxContext): sui::token::ActionRequest<T>
Implementation
Function confirm_request
Confirm the request against the TokenPolicy and return the parameters of the request: (Name, Amount, Sender, Recipient).
Cannot be used for spend and similar actions that deliver spent_balance to the TokenPolicy. For those actions use confirm_request_mut.
Aborts if:
- the action is not allowed (missing record in rules)
- action contains spent_balance (use confirm_request_mut)
- the ActionRequest does not meet the TokenPolicy rules for the action
public fun confirm_requestT(policy: &sui::token::TokenPolicy<T>, request: sui::token::ActionRequest<T>, _ctx: &mut sui::tx_context::TxContext): (std::string::String, u64, address, std::option::Option<address>)
Implementation
Function confirm_request_mut
Confirm the request against the TokenPolicy and return the parameters of the request: (Name, Amount, Sender, Recipient).
Unlike confirm_request this function requires mutable access to the TokenPolicy and must be used on spend action. After dealing with the spent balance it calls confirm_request internally.
See confirm_request for the list of abort conditions.
public fun confirm_request_mutT(policy: &mut sui::token::TokenPolicy<T>, request: sui::token::ActionRequest<T>, ctx: &mut sui::tx_context::TxContext): (std::string::String, u64, address, std::option::Option<address>)
Implementation
Function confirm_with_policy_cap
Confirm an ActionRequest as the TokenPolicyCap owner. This function allows TokenPolicy owner to perform Capability-gated actions ignoring the ruleset specified in the TokenPolicy.
Aborts if request contains spent_balance due to inability of the TokenPolicyCap to decrease supply. For scenarios like this a TreasuryCap is required (see confirm_with_treasury_cap).
public fun confirm_with_policy_capT(_policy_cap: &sui::token::TokenPolicyCap<T>, request: sui::token::ActionRequest<T>, _ctx: &mut sui::tx_context::TxContext): (std::string::String, u64, address, std::option::Option<address>)
Implementation
Function confirm_with_treasury_cap
Confirm an ActionRequest as the TreasuryCap owner. This function allows TreasuryCap owner to perform Capability-gated actions ignoring the ruleset specified in the TokenPolicy.
Unlike confirm_with_policy_cap this function allows spent_balance to be consumed, decreasing the total_supply of the Token.
public fun confirm_with_treasury_capT(treasury_cap: &mut sui::coin::TreasuryCap<T>, request: sui::token::ActionRequest<T>, _ctx: &mut sui::tx_context::TxContext): (std::string::String, u64, address, std::option::Option<address>)
Implementation
Function add_approval
Add an "approval" to the ActionRequest by providing a Witness. Intended to be used by Rules to add their own approvals, however, can be used to add arbitrary approvals to the request (not only the ones required by the TokenPolicy).
public fun add_approvalT, W(_t: W, request: &mut sui::token::ActionRequest<T>, _ctx: &mut sui::tx_context::TxContext)
Implementation
Function add_rule_config
Add a Config for a Rule in the TokenPolicy. Rule configuration is independent from the TokenPolicy.rules and needs to be managed by the Rule itself. Configuration is stored per Rule and not per Rule per Action to allow reuse in different actions.
- Rule witness guarantees that the Config is approved by the Rule.
- TokenPolicyCap guarantees that the Config setup is initiated by the TokenPolicy owner.
public fun add_rule_configT, Rule, Config(_rule: Rule, self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, config: Config, _ctx: &mut sui::tx_context::TxContext)
Implementation
Function rule_config
Get a Config for a Rule in the TokenPolicy. Requires Rule witness, hence can only be read by the Rule itself. This requirement guarantees safety of the stored Config and allows for simpler dynamic field management inside the Rule Config (custom type keys are not needed for access gating).
Aborts if the Config is not present.
public fun rule_configT, Rule, Config(_rule: Rule, self: &sui::token::TokenPolicy<T>): &Config
Implementation
Function rule_config_mut
Get mutable access to the Config for a Rule in the TokenPolicy. Requires Rule witness, hence can only be read by the Rule itself, as well as TokenPolicyCap to guarantee that the TokenPolicy owner is the one who initiated the Config modification.
Aborts if:
- the Config is not present
- TokenPolicyCap is not matching the TokenPolicy
public fun rule_config_mutT, Rule, Config(_rule: Rule, self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>): &mut Config
Implementation
Function remove_rule_config
Remove a Config for a Rule in the TokenPolicy. Unlike the add_rule_config, this function does not require a Rule witness, hence can be performed by the TokenPolicy owner on their own.
Rules need to make sure that the Config is present when performing verification of the ActionRequest.
Aborts if:
- the Config is not present
- TokenPolicyCap is not matching the TokenPolicy
public fun remove_rule_configT, Rule, Config(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, _ctx: &mut sui::tx_context::TxContext): Config
Implementation
Function has_rule_config
Check if a config for a Rule is set in the TokenPolicy without checking the type of the Config.
public fun has_rule_configT, Rule(self: &sui::token::TokenPolicy<T>): bool
Implementation
Function has_rule_config_with_type
Check if a Config for a Rule is set in the TokenPolicy and that it matches the type provided.
public fun has_rule_config_with_typeT, Rule, Config(self: &sui::token::TokenPolicy<T>): bool
Implementation
Function allow
Allows an action to be performed on the Token freely by adding an empty set of Rules for the action.
Aborts if the TokenPolicyCap is not matching the TokenPolicy.
public fun allowT(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, _ctx: &mut sui::tx_context::TxContext)
Implementation
Function disallow
Completely disallows an action on the Token by removing the record from the TokenPolicy.rules.
Aborts if the TokenPolicyCap is not matching the TokenPolicy.
public fun disallowT(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, _ctx: &mut sui::tx_context::TxContext)
Implementation
Function add_rule_for_action
Adds a Rule for an action with name in the TokenPolicy.
Aborts if the TokenPolicyCap is not matching the TokenPolicy.
public fun add_rule_for_actionT, Rule(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, ctx: &mut sui::tx_context::TxContext)
Implementation
Function remove_rule_for_action
Removes a rule for an action with name in the TokenPolicy. Returns the config object to be handled by the sender (or a Rule itself).
Aborts if the TokenPolicyCap is not matching the TokenPolicy.
public fun remove_rule_for_actionT, Rule(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, _ctx: &mut sui::tx_context::TxContext)
Implementation
Function mint
Mint a Token with a given amount using the TreasuryCap.
public fun mintT(cap: &mut sui::coin::TreasuryCap<T>, amount: u64, ctx: &mut sui::tx_context::TxContext): sui::token::Token<T>
Implementation
Function burn
Burn a Token using the TreasuryCap.
public fun burnT(cap: &mut sui::coin::TreasuryCap<T>, token: sui::token::Token<T>)
Implementation
Function flush
Flush the TokenPolicy.spent_balance into the TreasuryCap. This action is only available to the TreasuryCap owner.
public fun flushT(self: &mut sui::token::TokenPolicy<T>, cap: &mut sui::coin::TreasuryCap<T>, _ctx: &mut sui::tx_context::TxContext): u64
Implementation
Function is_allowed
Check whether an action is present in the rules VecMap.
public fun is_allowedT(self: &sui::token::TokenPolicy<T>, action: &std::string::String): bool
Implementation
Function rules
Returns the rules required for a specific action.
public fun rulesT(self: &sui::token::TokenPolicy<T>, action: &std::string::String): sui::vec_set::VecSet<std::type_name::TypeName>
Implementation
Function spent_balance
Returns the spent_balance of the TokenPolicy.
public fun spent_balanceT(self: &sui::token::TokenPolicy<T>): u64
Implementation
Function value
Returns the balance of the Token.
public fun valueT(t: &sui::token::Token<T>): u64
Implementation
Function transfer_action
Name of the Transfer action.
public fun transfer_action(): std::string::String
Implementation
Function spend_action
Name of the Spend action.
public fun spend_action(): std::string::String
Implementation
Function to_coin_action
Name of the ToCoin action.
public fun to_coin_action(): std::string::String
Implementation
Function from_coin_action
Name of the FromCoin action.
public fun from_coin_action(): std::string::String
Implementation
Function action
The Action in the ActionRequest.
public fun actionT(self: &sui::token::ActionRequest<T>): std::string::String
Implementation
Function amount
Amount of the ActionRequest.
public fun amountT(self: &sui::token::ActionRequest<T>): u64
Implementation
Function sender
Sender of the ActionRequest.
public fun senderT(self: &sui::token::ActionRequest<T>): address
Implementation
Function recipient
Recipient of the ActionRequest.
public fun recipientT(self: &sui::token::ActionRequest<T>): std::option::Option<address>
Implementation
Function approvals
Approvals of the ActionRequest.
public fun approvalsT(self: &sui::token::ActionRequest<T>): sui::vec_set::VecSet<std::type_name::TypeName>
Implementation
Function spent
Burned balance of the ActionRequest.
public fun spentT(self: &sui::token::ActionRequest<T>): std::option::Option<u64>
Implementation
Function key
Create a new RuleKey for a Rule. The is_protected field is kept for potential future use, if Rules were to have a freely modifiable storage as addition / replacement for the Config system.
The goal of is_protected is to potentially allow Rules store a mutable version of their configuration and mutate state on user action.
fun keyRule(): sui::token::RuleKey<Rule>