soroban-tools

此包是 soroban-kit 的一部分：[Github] | [crates.io]

为Soroban智能合约开发提供的快速、轻量级的函数和宏，具有简洁、目标明确的功能。

soroban-kit 旨在紧凑，专注于简洁的构造。它基于Rust的无需依赖的 core 库和 soroban-sdk 构建。所有模块都是 特性标志，允许您只编译所需的内容，而无需更多内容！

许可协议为MIT。本软件按“原样”提供，不承担任何责任。 [更多详情](https://github.com/fredericrezeau/soroban-kit/blob/4026917a31015b05537f6ac90aab082efb592237/crates/soroban-tools/LICENSE)

• soroban-tools
  • 功能
    • 扩展状态机
      • 背景
      • 文档
      • 示例
    • 预言机
      • 背景
      • 文档
      • 示例
    • 承诺方案
      • 背景
      • 文档
      • 示例
    • 断路器
      • 背景
      • 文档
      • 示例
    • 类型安全存储
      • 背景
      • 文档
      • 示例
    • 工具
  • 智能合约演示
  • 贡献
  • 许可协议
  • 联系方式

功能

扩展状态机

[dependencies]
soroban-kit = { version = "0.1.11", default-features = false, features = ["state-machine"] }

可以使用 state_machine 属性宏在Soroban智能合约中实现多功能状态机（请参阅 fsm/impl.rs）。它具有通过区域（复合状态）实现状态并发，通过扩展状态变量进行运行时行为建模，通过守卫和效果进行转换控制，以及使用Soroban存储进行状态持久化的功能。

背景

虽然状态机在Solidity智能合约中是一种常见的模式，但由于Solidity僵化的架构，其实现通常受到限制，导致并发和运行时行为的复杂性，有时甚至无法实现。

借助Rust的高级类型系统，soroban-kit state_machine 可以处理复杂的交互和并发状态执行，为Soroban智能合约提供灵活且直接的解决方案。

文档

为您有限状态机中的状态转换配置一个函数。

#[state_machine] 选项

• state: StatePath := EnumName ":" VariantName [":" TupleVariableName]
• region: RegionPath := EnumName ":" VariantName [":" TupleVariableName]
• storage: "instance" (默认) | "persistent" | "temporary"

    // Example
    #[state_machine(
      state = "Phase:Committing:voter",
      region = "Domain:Booth:voter")]
    fn my_state_machine_function(&self, env: &Env, voter: &Voter) {
    }

使用 TransitionHandler 特性，通过守卫和效果来控制状态转换。

#[derive(TransitionHandler)]
pub struct MyStateMachine;

impl MyStateMachine {
    // Implement to provide guard conditions for the transition
    // (e.g., ledger sequence or time-based guards).
    fn on_guard(/* omitted parameters */) {}

    // Implement the effect from transitioning.
    fn on_effect(/* omitted parameters */) {}
}

示例

• 投票站示例
• 游戏大厅示例
• hello-soroban-kit

预言机

oracle_broker 和 oracle_subscriber 属性宏旨在通用化异步和同步跨合约通信的接口。利用发布者-订阅者模式，系统允许订阅者与预言机经纪人合约建立多个连接，反之亦然。

这些宏生成一个轻量级框架（见oracle.rs），确保通信和事件驱动交互的一致性（见impl.rs）。可以通过宏参数自定义 topic 和 data 类型，您可以使用任何用户定义和内置的 Soroban 类型。

背景

预言机在区块链和外部数据源之间充当桥梁。实现 Oracle 服务存在许多关键挑战，包括去中心化、同步性、解耦和多重性。

soroban-kit 提出了一种轻量级解决方案，以实现 pub/sub 消息模式，帮助解决跨合约通信的这些挑战。

请参阅 oracle-soroban-kit 合约，该合约展示了基本的预言机经纪人实现，其中包括从订阅者那里收取费用，并且可以根据可用性同步和异步地提供服务。

文档

#[oracle_broker] 选项（位置参数）

• Topic Type：内置或自定义类型
• Data Type：内置或自定义类型

    // Implement the oracle broker interface for your contract.
    #[contract]
    #[oracle_broker(Bytes, MyDataType)]
    pub struct OracleContract;

#[oracle_subscriber] 选项（位置参数）

• Topic Type：内置或自定义类型
• Data Type：内置或自定义类型

    // Implement the oracle subscriber interface for your contract.
    #[contract]
    #[oracle_subscriber(Bytes, MyDataType)]
    pub struct TestContract;

该框架允许您通过 oracle:Events 特性实现来处理各种事件

    // Example, receiving data asynchronously.
    fn on_async_receive(env: &Env, topic: &Bytes, envelope: &oracle::Envelope, data: &Message) {
        // Only allow whitelisted oracle broker.
        assert_eq!(
            storage::get(&env, &WhitelistKey::Broker).unwrap().broker,
            envelope.broker
        );
        // Make sure the broker is authorized (i.e., made the cross-contract call).
        envelope.broker.require_auth();
        // Set the data.
        storage::set(&env, &MessageKey::Topic(topic.clone()), &data);
    }

示例

• oracle-soroban-kit
• hello-soroban-kit

承诺方案

[dependencies]
soroban-kit = { version = "0.1.11", default-features = false, features = ["commitment-scheme"] }

commit 和 reveal 属性宏旨在轻松实现 Soroban 智能合约中的承诺方案。它们使用 soroban-sdk 的 sha256 或 keccak256 哈希函数和存储，并自动移除哈希。

这些属性也可以与 state-machine 属性配对，以管理多方的承诺和揭示阶段。有关此类配对的完整演示，请参阅 投票站 示例。

        #[commit]
        #[state_machine(state = "Phase:Committing")]
        fn vote(&self, env: &Env, hash: &BytesN<32>) {
        }

        #[reveal]
        #[state_machine(state = "Phase:Revealing")]
        fn reveal(&self, env: &Env, data: &Bytes) {
        }

背景

承诺方案允许各方承诺一个值，在稍后的时间隐藏它。这种技术可以应用于投票系统、零知识证明（ZKPs）、伪随机数生成（PRNG）种子等用例。

soroban-kit 中的 commit 和 reveal 宏允许使用 rust 属性无样板地实现承诺方案。

文档

#[commit] 选项

• hash：变量名（默认 = "hash"）
• storage: "instance" (默认) | "persistent" | "temporary"

    // Example
    #[commit]
    fn my_commit_function(env: &Env, hash: &BytesN<32>) {
    }

#[reveal] 选项

• data：变量名（默认 = "data"）
• hash_func："sha256"（默认）| "keccak256"
• clear_commit：true（默认）| false
• storage: "instance" (默认) | "persistent" | "temporary"

    // Example
    #[reveal]
    fn my_reveal_function(env: &Env, data: &Bytes) {
    }

示例

• 投票站示例
• hello-soroban-kit

断路器

[dependencies]
soroban-kit = { version = "0.1.11", default-features = false, features = ["circuit-breaker"] }

when_opened 和 when_closed 属性宏提供了一种简化的方式，将断路器模式集成到您的 Soroban 智能合约中。

这些宏利用了 state-machine 模块，能够实现对状态转换的详细控制（见 circuit_breaker.rs）和复合电路的构建（即，在子电路中分组操作）。

背景

在智能合约的背景下，断路器模式作为一种重要的安全机制，能够在合约行为意外或遭受外部攻击时保护利益相关者。这种模式在 Solidity 智能合约中很常见，尤其是在 OpenZeppelin 的流行 可暂停合约 模块中。

soroban-kit 宏允许在合约的任何操作和操作子集中直接实现断路器模式。

文档

#[when_opened] / #[when_closed] 选项

• region: RegionPath := EnumName ":" VariantName [":" TupleVariableName]
• trigger：一个布尔值，指示函数调用是否应该触发状态改变（默认：false）。

    #[derive(CircuitBreaker)]
    struct Circuit; 
    
    impl Circuit {
        // bid() is usable when the circuit is closed (operational).
        #[when_closed]
        fn bid(&self, env: &Env) {
        }

        // emergency_stop() triggers a state change.
        #[when_closed(trigger = true)]
        fn emergency_stop(&self, env: &Env) {
        }

        // upgrade() also restores bid() operation.
        #[when_opened(trigger = true)]
        fn upgrade(&self, env: &Env) {
          // e.g., upgrade contract.
        }
    }

使用守卫和效果控制状态转换。

    impl Circuit {
        // Define guard conditions for state transitions (open/close).
        fn on_guard(/* omitted parameters */) {}

        // Define effects of state transitions
        fn on_effect(/* omitted parameters */) {}
    }

示例

• 断路器示例
• hello-soroban-kit

类型安全存储

[dependencies]
soroban-kit = { version = "0.1.11", default-features = false, features = ["storage"] }

storage 和 key_constraint 宏生成一个最小的包装器（见 storage/impl.rs），在存储操作中提供类型安全，同时也在编译时强制执行类型规则，绑定 Soroban 存储、数据类型和键。为了性能，生成的代码处理键和数据操作而不重复，利用 Rust 生命周期进行安全借用。

背景

在处理 Soroban 存储时，通常需要重复编写样板代码来实现封装和泛型存储函数的类型安全。

storage 宏通过自动生成样板代码，在编译时强制执行类型规则，将存储与自定义数据类型绑定，并可选地应用于存储键的 Trait 约束来简化此过程。

文档

#[storage] 选项（位置参数）

• Storage：实例（默认）| 持久化 | 临时
• Key：Trait

    // Example
    #[storage(Instance, AdminKeyConstraint)]
    pub struct AdminData {
        pub address: Address,
    }

#[key-constraint] 选项（位置参数）

• Key：Trait

    // Example
    #[key_constraint(AdminKeyConstraint)]
    pub enum Key {
        Admin,
    }

示例

• 教程视频
• 集成测试
• hello-soroban-kit

工具

[dependencies]
soroban-kit = { version = "0.1.11", default-features = false, features = ["utils"] }

此模块包含实用宏，包括

• reflective_enum：使 C-style 枚举能够反映其自己的变体。

智能合约演示

hello-soroban-kit 是一个简单的 Soroban 智能合约演示，展示了所有 soroban-kit 功能的使用。请参阅 hello-soroban-kit 文档。

贡献

欢迎贡献！如果您有改进此项目的建议，请 fork 存储库并创建一个 pull request。

许可协议

soroban-kit 根据 MIT 许可证授权。有关详细信息，请参阅 LICENSE。

联系方式

有关查询或合作

Fred Kyung-jin Rezeau - @FredericRezeau