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] が必須です。Rust 標準ライブラリではなく、soroban_sdk の型（String、Vec、Map、Symbol）を使用してください
• コンパイル後のコントラクトサイズ上限は 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 マニュアル