soroban-kit

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

soroban-kit 设计紧凑，专注于简洁的构造。它基于 Rust 的无依赖 core 库和 soroban-sdk。所有模块都通过 功能标志，允许您仅编译所需的代码，而不需要更多！

MIT 许可。本软件提供“原样”使用，不承担任何责任。 更多详情。

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

特性

扩展状态机

[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 宏通过自动生成模板代码，在编译时强制执行类型规则，将存储与自定义数据类型绑定，并可选择地应用特质约束到存储键，简化了此过程。

文档

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

• Storage：实例（默认）| 持久 | 临时
• Key：特质

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

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

• Key：特质

    // 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风格 枚举反映其自己的变体。

智能合约演示

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

贡献

欢迎贡献！如果您有使此处更好的建议，请fork存储库并创建一个pull request。

许可

soroban-kit采用MIT许可证。有关详细信息，请参阅LICENSE。

联系方式

有关咨询或合作

Fred Kyung-jin Rezeau - @FredericRezeau