Rust智能合约开发库soroban-builtin-sdk-macros的使用，为Soroban区块链平台提供内置SDK宏功能

Rust智能合约开发库soroban-builtin-sdk-macros的使用，为Soroban区块链平台提供内置SDK宏功能

安装

在项目目录中运行以下Cargo命令：

cargo add soroban-builtin-sdk-macros

或者在Cargo.toml中添加以下行：

soroban-builtin-sdk-macros = "23.0.0"

示例代码

以下是使用soroban-builtin-sdk-macros开发Soroban智能合约的完整示例：

use soroban_sdk::{contractimpl, Env};

// 使用合约宏标记合约实现
#[contractimpl]
impl MyContract {
    // 合约初始化函数
    pub fn init(env: Env, initial_value: i32) -> i32 {
        env.storage().set(&"value", &initial_value);
        initial_value
    }

    // 获取存储值函数
    pub fn get_value(env: Env) -> i32 {
        env.storage().get(&"value").unwrap_or(Ok(0)).unwrap()
    }

    // 设置存储值函数
    pub fn set_value(env: Env, new_value: i32) -> i32 {
        env.storage().set(&"value", &new_value);
        new_value
    }

    // 递增存储值函数
    pub fn increment(env: Env) -> i32 {
        let current = Self::get_value(env.clone());
        let new_value = current + 1;
        Self::set_value(env, new_value);
        new_value
    }
}

完整示例DEMO

以下是一个更完整的智能合约示例，展示了soroban-builtin-sdk-macros的更多功能：

use soroban_sdk::{contractimpl, symbol_short, Env, Symbol};

// 定义合约结构体
pub struct TokenContract;

// 使用contractimpl宏实现合约逻辑
#[contractimpl]
impl TokenContract {
    // 初始化代币合约
    pub fn initialize(env: Env, admin: Address, total_supply: i128) {
        // 保存管理员地址
        env.storage().set(&symbol_short!("admin"), &admin);
        
        // 设置总供应量
        env.storage().set(&symbol_short!("total"), &total_supply);
        
        // 将总供应量分配给管理员
        env.storage().set(&(symbol_short!("balance"), admin), &total_supply);
    }

    // 获取代币余额
    pub fn balance(env: Env, owner: Address) -> i128 {
        env.storage()
            .get(&(symbol_short!("balance"), owner))
            .unwrap_or(Ok(0))
            .unwrap()
    }

    // 转账函数
    pub fn transfer(env: Env, from: Address, to: Address, amount: i128) {
        // 检查from地址余额是否足够
        let from_balance = Self::balance(env.clone(), from.clone());
        if from_balance < amount {
            panic!("insufficient balance");
        }
        
        // 更新from地址余额
        env.storage().set(
            &(symbol_short!("balance"), from), 
            &(from_balance - amount)
        );
        
        // 更新to地址余额
        let to_balance = Self::balance(env.clone(), to.clone());
        env.storage().set(
            &(symbol_short!("balance"), to), 
            &(to_balance + amount)
        );
    }
}

关键特性

  1. #[contractimpl]宏自动处理合约接口暴露
  2. 简化了与Soroban环境的交互
  3. 自动生成ABI(应用程序二进制接口)
  4. 提供类型安全的存储操作

所有者

该库由Stellar官方维护


1 回复

Rust智能合约开发库soroban-builtin-sdk-macros使用指南

概述

soroban-builtin-sdk-macros是为Soroban区块链平台提供的Rust智能合约开发库中的宏功能部分，它简化了Soroban智能合约的开发流程，提供了一系列便捷宏来定义合约接口、处理数据结构和实现合约功能。

主要功能

  1. 合约接口定义宏
  2. 数据结构序列化/反序列化宏
  3. 合约方法绑定宏
  4. 类型转换辅助宏

安装

在Cargo.toml中添加依赖：

[dependencies]
soroban-builtin-sdk = { version = "0.9.0" }
soroban-builtin-sdk-macros = { version = "0.9.0" }

核心宏使用示例

1. 定义合约结构体

use soroban_builtin_sdk_macros::contract;

#[contract]
pub struct MyContract {
    value: i64,
}

2. 实现合约方法

use soroban_builtin_sdk_macros::contractimpl;

#[contractimpl]
impl MyContract {
    pub fn init(&mut self, value: i64) {
        self.value = value;
    }
    
    pub fn get_value(&self) -> i64 {
        self.value
    }
    
    pub fn set_value(&mut self, value: i64) {
        self.value = value;
    }
}

3. 定义自定义类型

use soroban_builtin_sdk_macros::contracttype;

#[contracttype]
pub enum Status {
    Pending,
    Active,
    Inactive,
}

#[contracttype]
pub struct User {
    pub id: u32,
    pub name: String,
    pub status: Status,
}

4. 事件记录

use soroban_builtin_sdk_macros::event;

#[event]
pub struct ValueChanged {
    pub old_value: i64,
    pub new_value: i64,
    pub by: Address,
}

完整合约示例

use soroban_builtin_sdk::{Address, Env};
use soroban_builtin_sdk_macros::{contract, contractimpl, contracttype, event};

// 定义合约状态
#[contract]
pub struct Token {
    admin: Address,
    balances: Map<Address, i64>,
    total_supply: i64,
}

// 定义事件
#[event]
pub struct Transfer {
    from: Option<Address>,
    to: Option<Address>,
    amount: i64,
}

// 实现合约方法
#[contractimpl]
impl Token {
    pub fn initialize(env: Env, admin: Address, total_supply: i64) {
        let mut token = Token::new(env);
        token.admin = admin;
        token.total_supply = total_supply;
        token.balances.set(admin.clone(), total_supply);
    }
    
    pub fn transfer(&mut self, from: Address, to: Address, amount: i64) {
        // 检查余额
        let from_balance = self.balances.get(from.clone()).unwrap_or(0);
        assert!(from_balance >= amount, "Insufficient balance");
        
        // 更新余额
        let to_balance = self.balances.get(to.clone()).unwrap_or(0);
        self.balances.set(from.clone(), from_balance - amount);
        self.balances.set(to.clone(), to_balance + amount);
        
        // 记录事件
        Transfer {
            from: Some(from),
            to: Some(to),
            amount,
        }
        .publish();
    }
    
    pub fn balance_of(&self, address: Address) -> i64 {
        self.balances.get(address).unwrap_or(0)
    }
}

最佳实践

  1. 模块化设计：将合约逻辑拆分为多个模块，使用宏来简化接口定义
  2. 充分测试：利用Soroban测试环境测试所有合约方法
  3. 事件记录：为重要状态变更添加事件记录
  4. 错误处理：合理使用assert宏进行参数校验
  5. 文档注释：为所有公共方法添加文档注释

注意事项

  1. 宏展开后的代码会依赖Soroban环境，不能在标准Rust程序中使用
  2. 所有公共方法都会暴露为合约接口
  3. 自定义类型需要实现必要的trait以支持序列化
  4. 合约状态会被持久化到区块链上，设计数据结构时要考虑存储成本

通过使用soroban-builtin-sdk-macros，开发者可以更高效地构建Soroban智能合约，减少样板代码，专注于业务逻辑实现。

回到顶部