Token Policy

TokenPolicy is a shared object which can be created by the Token owner using the TreasuryCap. Having a publicly available TokenPolicy would enable on-chain discovery of allowed actions and their conditions. This is useful for wallets and other services that want to provide a better user experience for token holders.

Create & Share

A new TokenPolicy is created using the token::new_policy function. The function takes the TreasuryCap as an argument and returns a TokenPolicy object and a managing capability.

// module: sui::token
public fun new_policy<T>(
    treasury_cap: &TreasuryCap<T>,
    ctx: &mut TxContext
): (TokenPolicy<TokenType>, TokenPolicyCap<TokenType>);

The TokenPolicy object must be shared with the token::share_policy function

Allow & Disallow

To allow method without any conditions, use the token::allow function. The function takes a TokenPolicy and TokenPolicyCap as arguments. If allowed, the action can be confirmed in the TokenPolicy using the token::confirm_request function (see ActionRequest).

// module sui::token
public fun allow<T>(
    policy: &mut TokenPolicy<T>,
    policy_cap: &TokenPolicyCap<T>,
    action: String,
    ctx: &mut TxContext
);

Similarly, the token::disallow function can be used to completely disable an action; it takes the same arguments as token::allow.

Adding Rules

TokenPolicy can specify custom conditions for each action. These conditions are called "Rules" and are typically implemented as separate Move modules. The identifier of the Rule is its type.

info

Visit the Rules section for more information.

Structure of the TokenPolicy is as follows (pseudo-code). Each action can have multiple Rules associated with it.

TokenPolicy
  rules:
    - action: "transfer"
      rules:
        - 0x0...::denylist::Denylist
    - action: "to_coin"
      rules:
        - 0x0...::limiter::Limiter
        - 0x0...::allowlist::Allowlist
    ...

To add a Rule for an action, use the token::add_rule_for_action function. The function takes a TokenPolicy and TokenPolicyCap as arguments. The Rule is specified by its type (eg 0x0...::denylist::Denylist).

// module: sui::token
public fun add_rule_for_action<T, Rule: drop>(
    policy: &mut TokenPolicy<T>,
    policy_cap: &TokenPolicyCap<T>,
    action: String,
    ctx: &mut TxContext
);

Signature for the reverse operation token::remove_rule_for_action is symmetrical to token::add_rule_for_action.

Consume Spent Balance

Spent balance can be consumed from the TokenPolicy using the token::flush function. It requires a TreasuryCap.

// module sui::token
public fun flush<T>(
    policy: &mut TokenPolicy<T>,
    treasury_cap: &mut TreasuryCap<T>,
    ctx: &mut TxContext
);

Cheatsheet: TokenPolicy API

Function	Note
new_policy	Create a new TokenPolicy using the TreasuryCap
allow	Allow an action in the TokenPolicy
disallow	Disallow an action in the TokenPolicy
add_rule_for_action	Add a Rule for an action in the TokenPolicy
remove_rule_for_action	Remove a Rule for an action in the TokenPolicy
confirm_request	Confirm an ActionRequest with a TokenPolicy
confirm_request_mut	Similar to confirm_request but only works for "spend" action
flush	Flush the spent balance from the TokenPolicy (see Spending)