Stellar 设置

Soroban/Stellar 开发环境配置

安装 Rust 工具链（v1.84.0+）和 Soroban WASM 目标：

bash
curl --proto =https --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32v1-none

安装 Stellar CLI：

bash
curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh

创建新的 Soroban 项目：

bash
stellar contract init my_project

这将创建一个 Cargo 工作区，合约位于 contracts/*/ 目录下。

OpenZeppelin 依赖

在添加依赖前，请查阅 stellar-contracts 仓库 获取当前版本。由于该库处于活跃开发阶段，请使用 = 固定精确版本。

在根目录的 Cargo.toml 的 [workspace.dependencies] 下添加 OpenZeppelin crate：

toml
[workspace.dependencies]
stellar-tokens = =
stellar-access = =
stellar-contract-utils = =
stellar-macros = =

然后在每个合约的 contracts/*/Cargo.toml 中引用它们：

toml
[dependencies]
soroban-sdk = { workspace = true }
stellar-tokens = { workspace = true }
stellar-access = { workspace = true }
stellar-contract-utils = { workspace = true }
stellar-macros = { workspace = true }

可用的 crate：stellar-access、stellar-accounts、stellar-contract-utils、stellar-fee-abstraction、stellar-governance、stellar-macros、stellar-tokens。

仅添加合约实际使用的 crate。stellar-macros 提供过程宏属性（例如 #[whennotpaused]、#[only_owner]、#[derive(Upgradeable)]），大多数合约都需要它。

代码模式

导入时使用下划线作为 crate 根（Rust 惯例）：

rust
use stellar_tokens::fungible::{Base, FungibleToken};
use stellar_tokens::fungible::burnable::FungibleBurnable;
use stellar_access::ownable::Ownable;
use stellarcontractutils::pausable::Pausable;
use stellarmacros::whennot_paused;

合约在结构体上使用 #[contract]，在 impl 块上使用 #[contractimpl]（来自 soroban_sdk）：

rust
use soroban_sdk::{contract, contractimpl, Env};

#[contract]
pub struct MyToken;

#[contractimpl]
impl MyToken {
// 在此实现 trait 方法
}

trait 实现按每个 trait 使用单独的 impl 块（例如 FungibleToken、Pausable）。像 #[whennotpaused] 和 #[only_owner] 这样的守卫宏用于装饰单个函数。

平台说明

• - Stellar 上的读取操作是免费的。 优化以减少写入操作；读取和计算成本低廉。优先选择清晰可读的代码，而非微优化。
• 实例存储 TTL 扩展是开发者的责任。 OpenZeppelin 库会处理其他存储条目的 TTL 扩展，但合约必须自行扩展其 instance 存储条目以防止过期。

构建与测试

将合约构建为 WASM：

bash
stellar contract build

这是 cargo build --target wasm32v1-none --release 的快捷方式。输出文件位于 target/wasm32v1-none/release/ 目录下。

运行测试：

bash
cargo test

soroban-sdk 的测试工具会自动为 crate 内的单元测试启用。