Back to Details

setup-stellar-contracts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Stellar Setup

Stellar 项目搭建

Soroban/Stellar Development Setup

Soroban/Stellar 开发环境配置

Install the Rust toolchain (v1.84.0+) and the Soroban WASM target:
bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32v1-none
Install the Stellar CLI:
bash
curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh
Create a new Soroban project:
bash
stellar contract init my_project
This creates a Cargo workspace with contracts in 
contracts/*/
.
安装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 Dependencies

OpenZeppelin 依赖配置

Look up the current version from the stellar-contracts repo before adding. Pin exact versions with 
=
as the library is under active development.
Add OpenZeppelin crates to the root 
Cargo.toml
under 
[workspace.dependencies]
:
toml
[workspace.dependencies]
stellar-tokens = "=<VERSION>"
stellar-access = "=<VERSION>"
stellar-contract-utils = "=<VERSION>"
stellar-macros = "=<VERSION>"
Then reference them in the per-contract 
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 }
Available crates: 
stellar-access
, 
stellar-accounts
, 
stellar-contract-utils
, 
stellar-fee-abstraction
, 
stellar-governance
, 
stellar-macros
, 
stellar-tokens
.
Only add the crates the contract actually uses. 
stellar-macros
provides proc-macro attributes (for example, 
#[when_not_paused]
, 
#[only_owner]
, 
#[derive(Upgradeable)]
) and is needed in most contracts.
添加依赖前，请从stellar-contracts仓库查询当前版本。由于该库正处于活跃开发阶段，请使用
=
固定精确版本。
将OpenZeppelin包添加到根目录
Cargo.toml
的
[workspace.dependencies]
下：
toml
[workspace.dependencies]
stellar-tokens = "=<VERSION>"
stellar-access = "=<VERSION>"
stellar-contract-utils = "=<VERSION>"
stellar-macros = "=<VERSION>"
然后在每个合约的
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 }
可用包包括：
stellar-access
、
stellar-accounts
、
stellar-contract-utils
、
stellar-fee-abstraction
、
stellar-governance
、
stellar-macros
、
stellar-tokens
。
仅添加合约实际需要的包。
stellar-macros
提供过程宏属性（例如
#[when_not_paused]
、
#[only_owner]
、
#[derive(Upgradeable)]
），大多数合约都需要该包。

Code Patterns

代码模式

Imports use underscores as the crate root (Rust convention):
rust
use stellar_tokens::fungible::{Base, FungibleToken};
use stellar_tokens::fungible::burnable::FungibleBurnable;
use stellar_access::ownable::Ownable;
use stellar_contract_utils::pausable::Pausable;
use stellar_macros::when_not_paused;
Contracts use 
#[contract]
on the struct and 
#[contractimpl]
on the impl block (from 
soroban_sdk
):
rust
use soroban_sdk::{contract, contractimpl, Env};

#[contract]
pub struct MyToken;

#[contractimpl]
impl MyToken {
    // Implement trait methods here
}
Trait implementations are separate 
impl
blocks per trait (e.g., 
FungibleToken
, 
Pausable
). Guard macros like 
#[when_not_paused]
and 
#[only_owner]
decorate individual functions.
导入时以下划线作为包根（Rust约定）：
rust
use stellar_tokens::fungible::{Base, FungibleToken};
use stellar_tokens::fungible::burnable::FungibleBurnable;
use stellar_access::ownable::Ownable;
use stellar_contract_utils::pausable::Pausable;
use stellar_macros::when_not_paused;
合约需在结构体上使用
#[contract]
宏，在实现块上使用
#[contractimpl]
宏（来自
soroban_sdk
）：
rust
use soroban_sdk::{contract, contractimpl, Env};

#[contract]
pub struct MyToken;

#[contractimpl]
impl MyToken {
    // Implement trait methods here
}
Trait实现需为每个trait单独编写
impl
块（例如
FungibleToken
、
Pausable
）。
#[when_not_paused]
和
#[only_owner]
等守卫宏用于修饰单个函数。

Platform Notes

平台注意事项

  • Read operations are free in Stellar. Optimize for minimizing writes; reads and computation are cheap. Prefer clean, readable code over micro-optimizations.
  • Instance storage TTL extension is the developer's responsibility. The OpenZeppelin library handles TTL extension for other storage entries, but contracts must extend their own 
    instance
    storage entries to prevent expiration.
  • Stellar中的读取操作是免费的。应尽量减少写入操作；读取和计算的成本很低。优先选择清晰、易读的代码，而非微优化。
  • 实例存储的TTL续期由开发者负责。OpenZeppelin库会处理其他存储条目的TTL续期，但合约必须自行对
    instance
    存储条目进行续期，以防止过期。

Build & Test

构建与测试

Build the contract to WASM:
bash
stellar contract build
This is a shortcut for 
cargo build --target wasm32v1-none --release
. Output appears in 
target/wasm32v1-none/release/
.
Run tests:
bash
cargo test
soroban-sdk
testutils are automatically enabled for in-crate unit tests.
将合约构建为WASM文件：
bash
stellar contract build
这是
cargo build --target wasm32v1-none --release
的快捷命令。构建产物将输出到
target/wasm32v1-none/release/
目录下。
运行测试：
bash
cargo test
对于 crate 内的单元测试，
soroban-sdk
的测试工具会自动启用。