Rust StarkNet智能合约开发宏库starknet-macros使用指南

starknet-macros是一个简化Rust与Cairo智能合约集成的宏库，专为StarkNet开发设计。它提供了一系列过程宏，让开发者能够更轻松地在Rust中编写与StarkNet兼容的智能合约。

主要功能

• 简化合约接口定义
• 自动生成ABI兼容代码
• 提供类型安全的数据转换
• 减少样板代码

安装

在Cargo.toml中添加依赖：

[dependencies]
starknet-macros = "0.1"

核心宏介绍

#[starknet::contract]

用于标记一个合约实现：

#[starknet::contract]
mod MyContract {
    // 合约代码
}

#[starknet::interface]

定义合约接口：

#[starknet::interface]
trait IMyContract<T> {
    fn get_value(self: @T) -> u32;
    fn set_value(ref self: T, value: u32);
}

#[external]

标记外部可调用的合约函数：

#[external]
impl MyContractImpl of IMyContract<ContractState> {
    fn get_value(self: @ContractState) -> u32 {
        self.value.read()
    }
    
    fn set_value(ref self: ContractState, value: u32) {
        self.value.write(value);
    }
}

#[storage]

定义合约存储：

#[storage]
struct Storage {
    value: u32,
    owner: ContractAddress,
}

完整示例

use starknet::ContractAddress;

#[starknet::interface]
trait ICounter<T> {
    fn get_count(self: @T) -> u32;
    fn increment(ref self: T);
}

#[starknet::contract]
mod Counter {
    use starknet::ContractAddress;
    
    #[storage]
    struct Storage {
        count: u32,
        owner: ContractAddress,
    }
    
    #[external]
    impl CounterImpl of super::ICounter<ContractState> {
        fn get_count(self: @ContractState) -> u32 {
            self.count.read()
        }
        
        fn increment(ref self: ContractState) {
            let current = self.count.read();
            self.count.write(current + 1);
        }
    }
    
    #[constructor]
    fn constructor(ref self: ContractState, owner: ContractAddress) {
        self.count.write(0);
        self.owner.write(owner);
    }
}

扩展完整示例

下面是一个更完整的StarkNet智能合约示例，包含事件定义和错误处理：

use starknet::ContractAddress;

// 定义合约接口
#[starknet::interface]
trait IBankContract<T> {
    fn deposit(ref self: T, amount: u128);
    fn withdraw(ref self: T, amount: u128) -> bool;
    fn get_balance(self: @T) -> u128;
    fn get_owner(self: @T) -> ContractAddress;
}

// 定义合约事件
#[event]
enum Event {
    Deposit: DepositEvent,
    Withdraw: WithdrawEvent,
}

// 事件结构体
#[derive(Drop, starknet::Event)]
struct DepositEvent {
    account: ContractAddress,
    amount: u128,
}

#[derive(Drop, starknet::Event)]
struct WithdrawEvent {
    account: ContractAddress,
    amount: u128,
    success: bool,
}

// 定义自定义错误
#[derive(Drop, starknet::Error)]
enum BankError {
    InsufficientBalance: (),
    Unauthorized: (),
}

#[starknet::contract]
mod BankContract {
    use super::{ContractAddress, IBankContract, BankError, Event, DepositEvent, WithdrawEvent};
    
    #[storage]
    struct Storage {
        balances: LegacyMap<ContractAddress, u128>,  // 用户余额映射
        owner: ContractAddress,  // 合约所有者
    }
    
    #[external]
    impl BankContractImpl of IBankContract<ContractState> {
        fn deposit(ref self: ContractState, amount: u128) {
            let caller = get_caller_address();
            let current_balance = self.balances.read(caller);
            self.balances.write(caller, current_balance + amount);
            
            // 触发存款事件
            self.emit(Event::Deposit(DepositEvent {
                account: caller,
                amount,
            }));
        }
        
        fn withdraw(ref self: ContractState, amount: u128) -> bool {
            let caller = get_caller_address();
            let current_balance = self.balances.read(caller);
            
            if current_balance < amount {
                // 触发取款失败事件
                self.emit(Event::Withdraw(WithdrawEvent {
                    account: caller,
                    amount,
                    success: false,
                }));
                return false;
            }
            
            self.balances.write(caller, current_balance - amount);
            
            // 触发取款成功事件
            self.emit(Event::Withdraw(WithdrawEvent {
                account: caller,
                amount,
                success: true,
            }));
            
            true
        }
        
        fn get_balance(self: @ContractState) -> u128 {
            let caller = get_caller_address();
            self.balances.read(caller)
        }
        
        fn get_owner(self: @ContractState) -> ContractAddress {
            self.owner.read()
        }
    }
    
    #[constructor]
    fn constructor(ref self: ContractState, owner: ContractAddress) {
        self.owner.write(owner);
    }
    
    // 只有所有者可以调用的管理函数
    #[external]
    fn add_liquidity(ref self: ContractState, amount: u128) {
        assert(self.owner.read() == get_caller_address(), BankError::Unauthorized);
        let owner = self.owner.read();
        let current_balance = self.balances.read(owner);
        self.balances.write(owner, current_balance + amount);
    }
}

使用建议

1. 类型安全：宏会自动检查类型是否与Cairo兼容
2. ABI生成：合约编译时会自动生成正确的ABI
3. 错误处理：使用#[derive(starknet::Error)]定义自定义错误
4. 事件：使用#[event]宏定义合约事件

注意事项

• 确保使用的Rust类型与Cairo类型兼容
• 存储结构体中的字段必须是可序列化的
• 函数参数和返回值需要是StarkNet支持的类型

这个宏库大大简化了Rust与StarkNet/Cairo的集成工作，让开发者可以专注于业务逻辑而不是底层细节。