soroban-macros

此crate是 soroban-kit 的一部分： Github | crates.io.

为 Soroban 智能合约开发提供快速、轻量级的功能和宏，具有精简、目标化的功能。

soroban-kit 设计用于紧凑性，专注于简洁的结构。它建立在 Rust 的无依赖库 core 和 soroban-sdk 之上。所有模块都 带有功能标志，允许您仅编译所需内容，无需更多！

根据 MIT 许可证授权。本软件提供“现状”不得承担任何责任。 更多信息.

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

功能

扩展状态机

[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

预言机

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

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

背景

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

《code>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"] }

《code>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）播种等用例。

《code>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的流行Pausable contract模块中。

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"] }

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

背景

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

存储宏通过自动生成样板代码、在编译时强制类型规则以及将存储与自定义数据类型绑定，简化了这一过程，并且可以选择应用特性约束到存储键。

文档

#[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