soroban

Stellar 智能合约

使用 Rust 构建 Stellar 智能合约的指南。Stellar 智能合约曾以“Soroban”为品牌名；该平台名称现已弃用，但 Rust SDK（soroban-sdk）和若干工具名称仍保留此前缀。

本文件介绍环境设置和核心工作流。深入内容请参阅相应文件——根据任务阅读对应文件：

任务	文件
存储、授权、跨合约调用、事件、错误、升级、工厂、故障排查	development.md
单元、集成、模糊、属性、分叉和变异测试	testing.md
安全审查、漏洞类别、检查清单、审计准备、工具	security.md

何时使用此技能

• 使用 Rust 编写 Stellar 智能合约
• 设置合约测试（任意层级）
• 审查合约中的安全问题
• 设计可升级合约、工厂、治理或 DeFi 基元
• 调试特定于合约的错误（授权、存储、归档、资源限制）

相关技能

• 资产、信任线和 SAC 桥 → ../assets/SKILL.md
• 调用合约的前端／钱包 → ../dapp/SKILL.md
• 链上数据查询（RPC/Horizon）→ ../data/SKILL.md
• ZK 验证（BLS12-381、Groth16、Circom/Noir/RISC Zero）→ ../zk-proofs/SKILL.md
• SEP/CAP 标准和生态链接 → ../standards/SKILL.md

平台限制

合约使用 Rust 编译为 WebAssembly，并在沙箱化主机中运行：

• 必须使用 #![no_std]——使用 soroban_sdk 类型（String、Vec、Map、Symbol），而非 Rust 标准库
• 编译后的合约大小限制为 64KB——请使用下方的发布配置文件
• Symbol 限长为 32 个字符；symbol_short!() 最多可处理 9 个字符
• 存储采用租赁机制：每个条目都有 TTL，且可能被归档——参见 development.md
• 不支持 delegatecall，也不支持经典的跨合约重入——参见 security.md

项目设置

stellar contract init my-contract   # scaffolds a Cargo workspace with contracts/
cd my-contract

Cargo.toml 核心内容：

[lib]
crate-type = ["cdylib"]

[dependencies]
soroban-sdk = "25.0.1"  # check https://crates.io/crates/soroban-sdk for latest

[dev-dependencies]
soroban-sdk = { version = "25.0.1", features = ["testutils"] }  # match above

[profile.release]
opt-level = "z"
overflow-checks = true
debug = 0
strip = "symbols"
debug-assertions = false
panic = "abort"
codegen-units = 1
lto = true

合约结构

一个精简示例，展示状态、构造函数、授权、TTL 和类型化错误：

#![no_std]
use soroban_sdk::{contract, contracterror, contractimpl, contracttype, Address, Env};

#[contracttype]
#[derive(Clone)]
pub enum DataKey {
    Admin,
    Counter,
}

#[contracterror]
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
#[repr(u32)]
pub enum Error {
    NotInitialized = 1,
}

#[contract]
pub struct CounterContract;

#[contractimpl]
impl CounterContract {
    // Runs once, atomically, at deploy time (Protocol 22+). Must be named
    // `__constructor` and return (). Does not run again on upgrade.
    pub fn __constructor(env: Env, admin: Address) {
        env.storage().instance().set(&DataKey::Admin, &admin);
        env.storage().instance().set(&DataKey::Counter, &0u32);
    }

    pub fn increment(env: Env) -> Result<u32, Error> {
        let admin: Address = env
            .storage()
            .instance()
            .get(&DataKey::Admin)
            .ok_or(Error::NotInitialized)?;
        admin.require_auth();

        let count: u32 = env.storage().instance().get(&DataKey::Counter).unwrap_or(0);
        let count = count + 1;
        env.storage().instance().set(&DataKey::Counter, &count);

        // Extend TTL so contract state is not archived (threshold, extend-to)
        env.storage().instance().extend_ttl(100, 518400);

        Ok(count)
    }

    pub fn get_count(env: Env) -> u32 {
        env.storage().instance().get(&DataKey::Counter).unwrap_or(0)
    }
}

完整模式（三种存储类型、授权变体、跨合约调用、事件、自定义类型）：development.md。

构建、部署、调用

# Build optimized WASM → target/wasm32-unknown-unknown/release/*.wasm
stellar contract build

# Create and fund an identity (testnet)
stellar keys generate --global alice --network testnet --fund

# Deploy (constructor args go after the `--`)
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/my_contract.wasm \
  --source alice \
  --network testnet \
  -- \
  --admin alice

# Invoke
stellar contract invoke \
  --id CONTRACT_ID \
  --source alice \
  --network testnet \
  -- \
  increment

要上传 WASM 但不实例化（例如用于工厂或升级），请使用 stellar contract upload（旧命令 stellar contract install 是已弃用的别名）。

最小测试

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

#[test]
fn test_increment() {
    let env = Env::default();
    env.mock_all_auths();
    let admin = Address::generate(&env);
    let contract_id = env.register(CounterContract, (admin.clone(),));
    let client = CounterContractClient::new(&env, &contract_id);

    assert_eq!(client.increment(), 1);
    assert_eq!(client.get_count(), 1);
}

授权模拟、模糊测试、分叉测试和 CI 设置：testing.md。

主网部署前

请完成 security.md 中的检查清单——授权、重新初始化、算术、存储 TTL 和跨合约验证是反复出现的故障原因。

文档

• 智能合约文档
• 示例合约
• soroban-sdk API 参考
• Stellar CLI 手册