Skip to main content

规则

规则是可编程的限制，可以应用于TokenPolicy中的任何操作。它们是在闭环系统中执行特定业务逻辑的合规、监管和执行工具。

规则结构​

规则表示为证人 - 一种具有 drop 能力的类型。它可以被编码到应用逻辑中，或者为了更模块化的设置，可以作为一个单独的模块的一部分。

/// The Rule type
struct Rule has drop {}

一旦添加到TokenPolicy中的操作，该操作将需要规则的“印记”以通过确认。

有关如何批准操作的详细信息，请参见批准操作部分。

模块化规则​

规则可以作为独立的可重用模块发布。这允许创建一个规则库，可在不同的令牌策略中使用，最大程度地实现代码重用，并最小化错误风险。

规则模块是一个常规模块，具有类似于 verify 的函数，通常接受 TokenPolicy、ActionRequest 和 TxContext 作为参数。该函数负责验证操作并在 ActionRequest 上打上规则类型的印记。

module example::pass_rule {
    use sui::tx_context;
    use sui::token::{Self, ActionRequest, TokenPolicy};

    /// The Rule type
    struct Pass has drop {}

    /// Add approval from the Pass rule to the ActionRequest
    public fun verify<T>(
        _policy: &TokenPolicy<T>,
        action_request: &mut ActionRequest<T>,
        ctx: &mut TxContext,
    ) {
        // ...
        token::add_approval(Pass {}, action_request, ctx)
    }
}

规则配置​

一些规则，比如“拒绝列表”或“允许列表”需要配置。例如，拒绝列表规则可能需要一组不允许执行某些操作的地址。规则模块可以定义一个配置结构，并提供用于添加、修改、检索和删除配置的函数。

info

单个规则具有单个配置，即使分配给多个操作。如果需要每个操作有自己的配置，则规则模块需要定义一个存储结构，可以保存和管理多个配置。

配置系统具有一组保证，以保护令牌所有者免受来自规则模块开发者的恶意操作（或升级）：

  1. 配置的类型和结构由规则模块定义。
  2. 仅允许 TokenPolicy 所有者进行配置的添加/修改和删除。
  3. 配置只能被规则读取。
  4. 规则不能在没有 TokenPolicy 所有者批准的情况下修改配置。

规则创建者唯一的攻击矢量是升级模块并创建绕过限制的函数。请确保使用由受信任的开发者提供的规则。

配置 API​

配置 API 在 sui::token 模块中定义，并具有以下一组函数。

添加新配置项​

新配置必须得到规则（规则证人）和 TokenPolicy 所有者的批准。配置的类型可以是任何类型，只要它具有 store 能力。

// module: sui::token
public fun add_rule_config<T, Rule: drop, Config: store>(
    _rule: Rule,
    policy: &mut TokenPolicy<T>,
    policy_cap: &TokenPolicyCap<T>,
    config: Config,
    _ctx: &mut TxContext
);

读取配置​

规则可以读取存储在 TokenPolicy 中的配置。

// module: sui::token
public fun rule_config<T, Rule: drop, Config: store>(
    _rule: Rule, policy: &TokenPolicy<T>
): &Config;

修改配置​

配置的修改必须得到规则（规则证人）和 TokenPolicy 所有者的批准。

// module: sui::token
public fun rule_config_mut<T, Rule: drop, Config: store>(
    _rule: Rule, policy: &mut TokenPolicy<T>, policy_cap: &TokenPolicyCap<T>
): &mut Config;

移除配置项​

规则的一个良好实践是提供删除配置的方法，因为规则可以使用自定义类型。然而，令牌所有者始终可以通过调用 remove_rule_config 函数来删除配置项。

// module: sui::token
public fun remove_rule_config<T, Rule, Config: store>(
    policy: &mut TokenPolicy<T>,
    policy_cap: &TokenPolicyCap<T>,
    _ctx: &mut TxContext
): Config;

由于配置具有 store，令牌所有者可以包装、转移或将配置存储到其他地方。如果 Config 类型具有 drop，则该值可以被忽略。

备忘录：规则配置 API​

Method nameDescriptionNotes
add_rule_configAdds a new Config for the RuleRequires Rule witness and Token Owner approval
remove_rule_configRemoves Config object from the PolicyCan be performed any time by the Token Owner
rule_configAccess the Config immutablyOnly available to a Rule
rule_config_mutGet mutable reference to ConfigRequires Rule witness and Token Owner approval
has_rule_configCheck if the Rule has a Config set-
has_rule_config_with_typeCheck if the Rule has a Config with type-