본문으로 건너뛰기

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.<br/>
Main type:   Balance<T>         Coin<T>               Token<T>.<br/>
Capability:  Supply<T>  <---->  TreasuryCap<T> <----> TreasuryCap<T>.<br/>
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.

use std::address;
use std::ascii;
use std::bcs;
use std::internal;
use std::option;
use std::string;
use std::type_name;
use std::u128;
use std::vector;
use sui::accumulator;
use sui::accumulator_settlement;
use sui::address;
use sui::bag;
use sui::balance;
use sui::bcs;
use sui::coin;
use sui::config;
use sui::deny_list;
use sui::dynamic_field;
use sui::dynamic_object_field;
use sui::event;
use sui::funds_accumulator;
use sui::hash;
use sui::hex;
use sui::object;
use sui::party;
use sui::protocol_config;
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 Token<phantom T> has key
Click to open
Fields
id: sui::object::UID
balance: sui::balance::Balance<T>
The Balance of the Token.

Struct TokenPolicyCap​

A Capability that manages a single TokenPolicy specified in the for field. Created together with TokenPolicy in the new function.

public struct TokenPolicyCap<phantom T> has key, store
Click to open
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 TokenPolicy<phantom T> has key
Click to open
Fields
id: sui::object::UID
spent_balance: sui::balance::Balance<T>
The balance that is effectively spent by the user on the "spend" action. However, actual decrease of the supply can only be done by the TreasuryCap owner when flush is called.
This balance is effectively spent and cannot be accessed by anyone but the TreasuryCap owner.
rules: sui::vec_map::VecMap<std::string::String, sui::vec_set::VecSet<std::type_name::TypeName>>
The set of rules that define what actions can be performed on the token. For each "action" there's a set of Rules that must be satisfied for the ActionRequest to be confirmed.

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 ActionRequest<phantom T>
Click to open
Fields
name: std::string::String
Name of the Action to look up in the Policy. Name can be one of the default actions: transfer, spend, to_coin, from_coin or a custom action.
amount: u64
Amount is present in all of the txs
sender: address
Sender is a permanent field always
recipient: std::option::Option<address>
Recipient is only available in transfer action.
spent_balance: std::option::Option<sui::balance::Balance<T>>
The balance to be "spent" in the TokenPolicy, only available in the spend action.
approvals: sui::vec_set::VecSet<std::type_name::TypeName>
Collected approvals (stamps) from completed Rules. They're matched against TokenPolicy.rules to determine if the request can be confirmed.

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 RuleKey<phantom T> has copy, drop, store
Click to open
Fields
is_protected: bool

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 TokenPolicyCreated<phantom T> has copy, drop
Click to open
Fields
id: sui::object::ID
ID of the TokenPolicy that was created.
is_mutable: bool
Whether the TokenPolicy is "shared" (mutable) or "frozen" (immutable) - TBD.

Constants​

The action is not allowed (defined) in the policy.

const EUnknownAction: u64 = 0;

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 too low to perform the action.

const EBalanceTooLow: u64 = 3;

The balance is not zero.

const ENotZero: u64 = 4;

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;

Using confirm_request_mut without spent_balance. Immutable version of the function must be used instead.

const EUseImmutableConfirm: u64 = 7;

A Tag for the spend action.

const SPEND: vector<u8> = vector[115, 112, 101, 110, 100];

A Tag for the transfer action.

const TRANSFER: vector<u8> = vector[116, 114, 97, 110, 115, 102, 101, 114];

A Tag for the to_coin action.

const TO_COIN: vector<u8> = vector[116, 111, 95, 99, 111, 105, 110];

A Tag for the from_coin action.

const FROM_COIN: vector<u8> = vector[102, 114, 111, 109, 95, 99, 111, 105, 110];

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_policy<T>(_treasury_cap: &sui::coin::TreasuryCap<T>, ctx: &mut sui::tx_context::TxContext): (sui::token::TokenPolicy<T>, sui::token::TokenPolicyCap<T>)

Function share_policy​

Share the TokenPolicy. Due to key-only restriction, it must be shared after initialization.

public fun share_policy<T>(policy: sui::token::TokenPolicy<T>)

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 transfer<T>(t: sui::token::Token<T>, recipient: address, ctx: &mut sui::tx_context::TxContext): sui::token::ActionRequest<T>

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 spend<T>(t: sui::token::Token<T>, ctx: &mut sui::tx_context::TxContext): sui::token::ActionRequest<T>

Function to_coin​

Convert Token into an open Coin. Creates an ActionRequest for the "to_coin" action.

public fun to_coin<T>(t: sui::token::Token<T>, ctx: &mut sui::tx_context::TxContext): (sui::coin::Coin<T>, sui::token::ActionRequest<T>)

Function from_coin​

Convert an open Coin into a Token. Creates an ActionRequest for the "from_coin" action.

public fun from_coin<T>(coin: sui::coin::Coin<T>, ctx: &mut sui::tx_context::TxContext): (sui::token::Token<T>, sui::token::ActionRequest<T>)

Function join​

Join two Tokens into one, always available.

public fun join<T>(token: &mut sui::token::Token<T>, another: sui::token::Token<T>)

Function split​

Split a Token with amount.
Aborts if the Token.balance is lower than amount.

public fun split<T>(token: &mut sui::token::Token<T>, amount: u64, ctx: &mut sui::tx_context::TxContext): sui::token::Token<T>

Function zero​

Create a zero Token.

public fun zero<T>(ctx: &mut sui::tx_context::TxContext): sui::token::Token<T>

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_zero<T>(token: sui::token::Token<T>)

Function keep​

Transfer the Token to the transaction sender.

public fun keep<T>(token: sui::token::Token<T>, ctx: &mut sui::tx_context::TxContext)

Function new_request​

Create a new ActionRequest.
Publicly available method to allow for custom actions.

public fun new_request<T>(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>

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:

public fun confirm_request<T>(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>)

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_mut<T>(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>)

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_cap<T>(_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>)

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_cap<T>(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>)

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_approval<T, W: drop>(_t: W, request: &mut sui::token::ActionRequest<T>, _ctx: &mut sui::tx_context::TxContext)

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_config<T, Rule: drop, Config: store>(_rule: Rule, self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, config: Config, _ctx: &mut sui::tx_context::TxContext)

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_config<T, Rule: drop, Config: store>(_rule: Rule, self: &sui::token::TokenPolicy<T>): &Config

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:

public fun rule_config_mut<T, Rule: drop, Config: store>(_rule: Rule, self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>): &mut Config

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:

public fun remove_rule_config<T, Rule, Config: store>(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, _ctx: &mut sui::tx_context::TxContext): Config

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_config<T, Rule>(self: &sui::token::TokenPolicy<T>): bool

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_type<T, Rule, Config: store>(self: &sui::token::TokenPolicy<T>): bool

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 allow<T>(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, _ctx: &mut sui::tx_context::TxContext)

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 disallow<T>(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, _ctx: &mut sui::tx_context::TxContext)

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_action<T, Rule: drop>(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, ctx: &mut sui::tx_context::TxContext)

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_action<T, Rule: drop>(self: &mut sui::token::TokenPolicy<T>, cap: &sui::token::TokenPolicyCap<T>, action: std::string::String, _ctx: &mut sui::tx_context::TxContext)

Function mint​

Mint a Token with a given amount using the TreasuryCap.

public fun mint<T>(cap: &mut sui::coin::TreasuryCap<T>, amount: u64, ctx: &mut sui::tx_context::TxContext): sui::token::Token<T>

Function burn​

Burn a Token using the TreasuryCap.

public fun burn<T>(cap: &mut sui::coin::TreasuryCap<T>, token: sui::token::Token<T>)

Function flush​

Flush the TokenPolicy.spent_balance into the TreasuryCap. This action is only available to the TreasuryCap owner.

public fun flush<T>(self: &mut sui::token::TokenPolicy<T>, cap: &mut sui::coin::TreasuryCap<T>, _ctx: &mut sui::tx_context::TxContext): u64

Function is_allowed​

Check whether an action is present in the rules VecMap.

public fun is_allowed<T>(self: &sui::token::TokenPolicy<T>, action: &std::string::String): bool

Function rules​

Returns the rules required for a specific action.

public fun rules<T>(self: &sui::token::TokenPolicy<T>, action: &std::string::String): sui::vec_set::VecSet<std::type_name::TypeName>

Function spent_balance​

Returns the spent_balance of the TokenPolicy.

public fun spent_balance<T>(self: &sui::token::TokenPolicy<T>): u64

Function value​

Returns the balance of the Token.

public fun value<T>(t: &sui::token::Token<T>): u64

Function transfer_action​

Name of the Transfer action.

public fun transfer_action(): std::string::String

Function spend_action​

Name of the Spend action.

public fun spend_action(): std::string::String

Function to_coin_action​

Name of the ToCoin action.

public fun to_coin_action(): std::string::String

Function from_coin_action​

Name of the FromCoin action.

public fun from_coin_action(): std::string::String

Function action​

The Action in the ActionRequest.

public fun action<T>(self: &sui::token::ActionRequest<T>): std::string::String

Function amount​

Amount of the ActionRequest.

public fun amount<T>(self: &sui::token::ActionRequest<T>): u64

Function sender​

Sender of the ActionRequest.

public fun sender<T>(self: &sui::token::ActionRequest<T>): address

Function recipient​

Recipient of the ActionRequest.

public fun recipient<T>(self: &sui::token::ActionRequest<T>): std::option::Option<address>

Function approvals​

Approvals of the ActionRequest.

public fun approvals<T>(self: &sui::token::ActionRequest<T>): sui::vec_set::VecSet<std::type_name::TypeName>

Function spent​

Burned balance of the ActionRequest.

public fun spent<T>(self: &sui::token::ActionRequest<T>): std::option::Option<u64>

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 key<Rule>(): sui::token::RuleKey<Rule>