Rust智能合约开发库soroban-token-sdk的使用：Stellar链上代币与资产管理的标准实现

概述

soroban-token-sdk 是 Stellar 区块链上用于开发智能合约的标准代币库，专门为 Soroban (Stellar 的智能合约平台) 设计。它提供了一套完整的工具和接口，用于在 Stellar 网络上创建和管理代币资产。

主要功能

1. 代币创建与管理
2. 代币转账功能
3. 余额查询
4. 授权与批准机制
5. 元数据管理

安装与设置

在项目的 Cargo.toml 中添加依赖：

[dependencies]
soroban-token-sdk = { version = "0.9.0", features = ["token"] }
soroban-sdk = "0.9.0"

基本使用方法

1. 创建代币合约

use soroban_sdk::{contractimpl, Env, Symbol};
use soroban_token_sdk::Token;

pub struct TokenContract;

#[contractimpl]
impl TokenContract {
    pub fn initialize(e: Env, admin: Address, decimal: u32, name: Symbol, symbol: Symbol) {
        Token::initialize(&e, admin, decimal, name, symbol);
    }
}

2. 代币转账

#[contractimpl]
impl TokenContract {
    pub fn transfer(e: Env, from: Address, to: Address, amount: i128) {
        Token::transfer(&e, from, to, amount);
    }
}

3. 查询余额

#[contractimpl]
impl TokenContract {
    pub fn balance(e: Env, id: Address) -> i128 {
        Token::balance(&e, id)
    }
}

4. 授权与批准

#[contractimpl]
impl TokenContract {
    pub fn approve(e: Env, from: Address, spender: Address, amount: i128, expiration: u32) {
        Token::approve(&e, from, spender, amount, expiration);
    }
    
    pub fn allowance(e: Env, from: Address, spender: Address) -> i128 {
        Token::allowance(&e, from, spender)
    }
}

完整示例

下面是一个完整的代币合约示例：

use soroban_sdk::{contractimpl, contracttype, Address, Env, Symbol};
use soroban_token sdk::Token;

#[contracttype]
pub enum DataKey {
    Token,
}

pub struct TokenContract;

#[contractimpl]
impl TokenContract {
    pub fn initialize(
        e: Env,
        admin: Address,
        decimal: u32,
        name: Symbol,
        symbol: Symbol,
    ) {
        Token::initialize(&e, admin, decimal, name, symbol);
    }

    pub fn transfer(e: Env, from: Address, to: Address, amount: i128) {
        Token::transfer(&e, from, to, amount);
    }

    pub fn balance(e: Env, id: Address) -> i128 {
        Token::balance(&e, id)
    }

    pub fn approve(e: Env, from: Address, spender: Address, amount: i128, expiration: u32) {
        Token::approve(&e, from, spender, amount, expiration);
    }

    pub fn allowance(e: Env, from: Address, spender: Address) -> i128 {
        Token::allowance(&极e, from, spender)
    }

    pub fn mint(e: Env, to: Address, amount: i128) {
        Token::mint(&e, to, amount);
    }

    pub fn burn(e: Env, from: Address, amount: i128) {
        Token::burn(&e, from, amount);
    }
}

高级功能

1. 元数据管理

#[contractimpl]
impl TokenContract {
    pub fn set_metadata(e: Env, key: Symbol, value: Symbol) {
        Token::set_metadata(&e, key, value);
    }
    
    pub fn get_metadata(e: Env, key: Symbol) -> Symbol {
        Token::get_metadata(&e, key)
    }
}

2. 批量转账

#[contractimpl]
impl TokenContract {
    pub fn transfer_batch(e: Env, from: Address, recipients: Vec<Address>, amounts: Vec<i128>) {
        Token::transfer_batch(&e, from, recipients, amounts);
    }
}

测试示例

#[cfg(test)]
mod test {
    use super::*;
    use soroban_sdk::testutils::Address as _;
    use soroban_sdk::{Address, Env};

    #[test]
    fn test_token_lifecycle() {
        let env = Env::default();
        let contract_id = env.register_contract(None, TokenContract);
        let client = TokenContractClient::new(&env, &contract_id);
        
        let admin = Address::generate(&env);
        let user1 = Address::generate(&env);
        let user2 = Address::generate(&env);
        
        // 初始化代币
        client.initialize(
            &admin,
            &7u32,
            &Symbol::short("MyToken"),
            &Symbol::short("MTK"),
        );
        
        // 铸造代币
        client.mint(&user1, &1000);
        assert_eq!(client.balance(&user1), 1000);
        
        // 转账
        client.transfer(&user1, &user2, &500);
        assert_eq!(client.balance(&user1), 500);
        assert_eq!(client.balance(&user2), 500);
        
        // 授权
        client.approve(&user1, &user2, &300, &1000);
        assert_eq!(client.allowance(&user1, &user2), 300);
    }
}

最佳实践

1. 权限控制：确保关键操作如 mint 和 burn 有适当的权限检查
2. 输入验证：验证所有输入参数的有效性
3. 事件记录：记录重要操作的事件以便追踪
4. 错误处理：提供清晰的错误信息
5. 测试覆盖：确保全面的测试覆盖，特别是边界条件

完整示例Demo

以下是一个完整的代币合约实现示例，包含所有核心功能：

//! 完整的代币合约示例

use soroban_sdk::{contractimpl, contracttype, Address, Env, Symbol};
use soroban_token_sdk::Token;

// 定义合约数据键
#[contracttype]
pub enum DataKey {
    Token,
    Admin,
}

pub struct TokenContract;

#[contractimpl]
impl TokenContract {
    // 初始化代币合约
    pub fn initialize(
        e: Env,
        admin: Address,
        decimal: u32,
        name: Symbol,
        symbol: Symbol,
    ) {
        // 验证管理员地址
        require!(!admin.is_empty(), "Admin address cannot be empty");
        
        // 初始化代币
        Token::initialize(&e, admin.clone(), decimal, name, symbol);
        
        // 存储管理员地址
        e.storage().set(&DataKey::Admin, &admin);
    }
    
    // 转账功能
    pub fn transfer(e: Env, from: Address, to: Address, amount: i128) {
        // 验证金额
        require!(amount > 0, "Amount must be positive");
        
        Token::transfer(&e, from, to, amount);
    }
    
    // 查询余额
    pub fn balance(e: Env, id: Address) -> i128 {
        Token::balance(&e, id)
    }
    
    // 授权功能
    pub fn approve(e: Env, from: Address, spender: Address, amount: i128, expiration: u32) {
        // 验证授权参数
        require!(amount >= 0, "Amount cannot be negative");
        require!(expiration > e.ledger().timestamp(), "Expiration must be in the future");
        
        Token::approve(&e, from, spender, amount, expiration);
    }
    
    // 查询授权额度
    pub fn allowance(e: Env, from: Address, spender: Address) -> i128 {
        Token::allowance(&e, from, spender)
    }
    
    // 铸造新代币(仅管理员可调用)
    pub fn mint(e: Env, to: Address, amount: i128) {
        // 获取管理员地址
        let admin: Address = e.storage().get(&DataKey::Admin)
            .expect("Admin not initialized")
            .unwrap();
            
        // 验证调用者权限
        admin.require_auth();
        
        // 验证金额
        require!(amount > 0, "Amount must be positive");
        
        Token::mint(&e, to, amount);
    }
    
    // 销毁代币(仅管理员可调用)
    pub fn burn(e: Env, from: Address, amount: i128) {
        // 获取管理员地址
        let admin: Address = e.storage().get(&DataKey::Admin)
            .expect("Admin not initialized")
            .unwrap();
            
        // 验证调用者权限
        admin.require_auth();
        
        // 验证金额
        require!(amount > 0, "Amount must be positive");
        
        Token::burn(&e, from, amount);
    }
    
    // 设置元数据
    pub fn set_metadata(e: Env, key: Symbol, value: Symbol) {
        // 获取管理员地址
        let admin: Address = e.storage().get(&DataKey::Admin)
            .expect("Admin not initialized")
            .unwrap();
            
        // 验证调用者权限
        admin.require_auth();
        
        Token::set_metadata(&e, key, value);
    }
    
    // 获取元数据
    pub fn get_metadata(e: Env, key: Symbol) -> Symbol {
        Token::get_metadata(&e, key)
    }
    
    // 批量转账
    pub fn transfer_batch(e: Env, from: Address, recipients: Vec<Address>, amounts: Vec<i128>) {
        // 验证输入
        require!(!recipients.is_empty(), "Recipients list cannot be empty");
        require!(recipients.len() == amounts.len(), "Recipients and amounts length mismatch");
        
        for amount in amounts.iter() {
            require!(*amount > 0, "Amount must be positive");
        }
        
        Token::transfer_batch(&e, from, recipients, amounts);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use soroban_sdk::testutils::{Address as _, Ledger};
    use soroban_sdk::{Address, Env, Symbol};
    
    #[test]
    fn test_token_contract() {
        // 初始化测试环境
        let env = Env::default();
        env.ledger().set(Ledger {
            timestamp: 1000,
            protocol_version: 1,
            sequence_number: 1,
            network_id: Default::default(),
            base_reserve: 10,
        });
        
        // 注册合约
        let contract_id = env.register_contract(None, TokenContract);
        let client = TokenContractClient::new(&env, &contract_id);
        
        // 生成测试账户
        let admin = Address::generate(&env);
        let user1 = Address::generate(&env);
        let user2 = Address::generate(&env);
        
        // 初始化代币
        client.initialize(
            &admin,
            &7u32,
            &Symbol::short("MyToken"),
            &Symbol::short("MTK"),
        );
        
        // 测试铸造功能
        client.mint(&user1, &1000);
        assert_eq!(client.balance(&user1), 1000);
        
        // 测试转账功能
        client.transfer(&user1, &user2, &500);
        assert_eq!(client.balance(&user1), 500);
        assert_eq!(client.balance(&user2), 500);
        
        // 测试授权功能
        client.approve(&user1, &user2, &300, &2000);
        assert_eq!(client.allowance(&user1, &user2), 300);
        
        // 测试元数据功能
        client.set_metadata(&Symbol::short("website"), &Symbol::short("example.com"));
        assert_eq!(
            client.get_metadata(&Symbol::short("website")),
            Symbol::short("example.com")
        );
        
        // 测试批量转账
        let recipients = vec![user1.clone(), user2.clone()];
        let amounts = vec![100, 200];
        client.transfer_batch(&admin, &recipients, &amounts);
        assert_eq!(client.balance(&user1), 600); // 500 + 100
        assert_eq!(client.balance(&user2), 700); // 500 + 200
    }
}

这个完整示例展示了如何使用 soroban-token-sdk 创建一个功能完善的代币合约，包含：

1. 代币初始化
2. 转账功能
3. 余额查询
4. 授权机制
5. 铸造和销毁功能
6. 元数据管理
7. 批量转账
8. 完整的权限控制和输入验证
9. 单元测试

所有功能都遵循最佳实践，包括严格的输入验证和权限控制，确保合约的安全性和可靠性。