index

Command Cheatsheet

· 8min

Referensi cepat command Stellar CLI yang sering dipakai! 📝

🚀 Project Setup

Create New Project

# Create new Soroban contract project
stellar contract init my-contract

# Create contract within existing project
stellar contract init . --name my-contract

# Or create manually
cargo new --lib my-contract
cd my-contract

Add Dependencies to Cargo.toml

[package]
name = "my-contract"
version = "0.1.0"
edition = "2021"

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

[dependencies]
soroban-sdk = "22"

[dev-dependencies]
soroban-sdk = { version = "22", features = ["testutils"] }

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

[profile.release-with-logs]
inherits = "release"
debug-assertions = true

🔧 Build & Test

Build Contract

# Build optimized WASM
stellar contract build

# Output: target/wasm32v1-none/release/my_contract.wasm

Run Tests

# Run all tests
cargo test

# Run specific test
cargo test test_donate

# Run with output
cargo test -- --nocapture

# Run with backtrace
RUST_BACKTRACE=1 cargo test

🔑 Identity & Accounts

Create Identity

# Generate new identity
stellar keys generate alice --network testnet

# Generate tanpa save
stellar keys generate --network testnet

# List all identities
stellar keys ls

Import from Seed Phrase

# Import existing seed phrase as source account
stellar keys add alice --secret-key

# Paste your 56-character secret key (starts with S)
# Example: SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Show Public Key

# Get public key from identity
stellar keys address alice

# Show identity details
stellar keys show alice

Show / Export Seed Phrase

stellar keys secret alice --phrase

Fund Account (Testnet)

# Fund account with Friendbot
stellar keys fund alice --network testnet

# Or manual via curl
curl "https://friendbot.stellar.org?addr=GXXXXXXXXXXXXXXXXXXXXXXXXX"

📦 Deploy Contract

Understanding Deploy Steps

Deploy sebenarnya ada 2 langkah:

  1. UPLOAD - Upload WASM bytes ke network
  2. DEPLOY - Instantiate contract dari WASM

Quick Deploy (1 Command)

# Deploy with alias (recommended)
stellar contract deploy \
  --wasm target/wasm32v1-none/release/my_contract.wasm \
  --source-account alice \
  --network testnet \
  --alias my_contract

# Returns: CONTRACT_ID (starts with C)

Manual 2-Step Deploy

# Step 1: Upload WASM bytes (install or upload - both work!)
stellar contract install \
  --wasm target/wasm32v1-none/release/my_contract.wasm \
  --source-account alice \
  --network testnet

# Alternative: stellar contract upload (sama saja)
# stellar contract upload \
#   --wasm target/wasm32v1-none/release/my_contract.wasm \
#   --source-account alice \
#   --network testnet

# Returns: WASM_HASH (save this!)

# Step 2: Deploy from uploaded WASM
stellar contract deploy \
  --wasm-hash <WASM_HASH> \
  --source-account alice \
  --network testnet \
  --alias my_contract

Check Deployed WASM File

# List built WASM files
ls target/wasm32v1-none/release/*.wasm

# Example output:
# target/wasm32v1-none/release/my_contract.wasm

Save Contract ID

# Contract ID saved automatically with --alias
# Or save to variable
CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Or save to file
echo "CXXXXX..." > contract_id.txt

🎯 Invoke Contract Functions

Basic Invoke

# Call initialize function
stellar contract invoke \
  --id $CONTRACT_ID \
  --source-account alice \
  --network testnet \
  -- \
  initialize \
  --owner alice

# Call with parameters
stellar contract invoke \
  --id $CONTRACT_ID \
  --source-account alice \
  --network testnet \
  -- \
  donate \
  --donor alice \
  --amount 1000000

View-Only Functions (No Transaction)

# Query read-only functions
stellar contract invoke \
  --id $CONTRACT_ID \
  --source-account alice \
  --network testnet \
  -- \
  get_total_raised

# Get balance
stellar contract invoke \
  --id $CONTRACT_ID \
  --source-account alice \
  --network testnet \
  -- \
  get_donation \
  --donor alice

Multiple Parameters

# Function with multiple params
stellar contract invoke \
  --id $CONTRACT_ID \
  --source-account alice \
  --network testnet \
  -- \
  create_campaign \
  --creator alice \
  --goal 10000000 \
  --deadline 1735689600 \
  --description "My Campaign"

Using Alias Instead of Contract ID

# Invoke dengan alias (easier!)
stellar contract invoke \
  --id my_contract \
  --source-account alice \
  --network testnet \
  -- \
  hello \
  --to "RPC"

🪙 Important: XLM Token Address

Native XLM as Token Contract

Di Soroban, semua assets (termasuk native XLM) adalah token contracts! Kamu perlu address-nya untuk transfer XLM.

Testnet XLM Token Address

CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

Example: Initialize Crowdfunding dengan XLM

stellar contract invoke \
  --id crowdfunding \
  --source-account alice \
  --network testnet \
  -- \
  initialize \
  --owner alice \
  --goal "100000000" \
  --deadline "1735689600" \
  --xlm_token "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"

Using in Contract Code

use soroban_sdk::token;

// In your contract
let xlm_token = token::Client::new(&env, &xlm_token_address);
xlm_token.transfer(&from, &to, &amount);

Why? Consistent API untuk semua assets, XLM dapat fitur token contract (allowances, etc)

🌐 Frontend Integration

Setup Frontend Project

# Create Astro frontend
npm create astro@latest

cd my-frontend

Copy Stellar Config

# Copy .stellar folder dari contract project
cp -R ../my-contract/.stellar .stellar

# Or configure custom directory
stellar config dir

Generate TypeScript Bindings

# Generate bindings untuk frontend (ABI)
stellar contract bindings typescript \
  --network testnet \
  --contract-id my_contract \
  --output-dir packages/my_contract

# Or with contract ID
stellar contract bindings typescript \
  --network testnet \
  --contract-id CXXXXXXXXX \
  --output-dir packages/my_contract

Build Bindings Package

# Install & build bindings
cd packages/my_contract
npm install
npm run build
cd ../..

Use in Frontend

// Import generated client
import { MyContractClient } from 'my_contract'

// Initialize client
const client = new MyContractClient({
  contractId: 'CXXXXXXXXX',
  networkPassphrase: Networks.TESTNET,
  rpcUrl: 'https://soroban-testnet.stellar.org'
})

// Call contract functions
const result = await client.hello({ to: 'World' })

💾 Storage & State Archival

Storage Types di Soroban

3 Jenis Storage dengan TTL (Time To Live):

1. Persistent Storage ⏳

  • Data penting yang harus exist long-term
  • Paling mahal, tapi paling reliable
  • Contoh: Token balances, ownership records
  • TTL: Bisa diperpanjang sampai ~3 bulan
env.storage().persistent().set(&key, &value);
env.storage().persistent().get(&key);

2. Instance Storage 🏠

  • Data terkait contract instance
  • Medium cost, shared lifetime dengan contract
  • Contoh: Contract config, admin address
  • TTL: Tied to contract lifetime
env.storage().instance().set(&key, &value);
env.storage().instance().get(&key);

3. Temporary Storage ⚡

  • Data sementara, bisa hilang
  • Paling murah
  • Contoh: Cache, temporary calculations
  • TTL: Bisa expire cepat (~1 hari)
env.storage().temporary().set(&key, &value);
env.storage().temporary().get(&key);

Why TTL Matters

Storage di Soroban BUKAN permanent by default! Data bisa di-archive (hilang) kalau TTL habis.

Best Practices:

  • Use Persistent untuk data critical (balances, ownership)
  • Use Instance untuk contract config
  • Use Temporary untuk cache/temporary data
  • Extend TTL sebelum expire untuk data penting

Extend Storage TTL

# Extend contract instance TTL
stellar contract extend \
  --id my_contract \
  --ledgers-to-extend 535680 \
  --source-account alice \
  --network testnet

# 535680 ledgers ≈ 31 days (1 ledger ≈ 5 seconds)

Read Contract Storage

# Get all storage entries
stellar contract read \
  --id $CONTRACT_ID \
  --network testnet

# Get specific key
stellar contract read \
  --id $CONTRACT_ID \
  --key "TotalRaised" \
  --network testnet

Contract Info

# Get contract details
stellar contract info \
  --id $CONTRACT_ID \
  --network testnet

# Get WASM hash
stellar contract info wasm \
  --id $CONTRACT_ID \
  --network testnet

🔍 Network & Explorer

Check Transaction

# View transaction on explorer
https://stellar.expert/explorer/testnet/tx/TRANSACTION_HASH

Check Account

# View account balance
stellar account balance alice --network testnet

# View account details
https://stellar.expert/explorer/testnet/account/GXXXXXXXXX

Check Contract

# View contract on explorer
https://stellar.expert/explorer/testnet/contract/CXXXXXXXXX

🧪 Testing Patterns

Setup Test Environment

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

    #[test]
    fn test_example() {
        let env = Env::default();
        let contract_id = env.register_contract(None, MyContract);
        let client = MyContractClient::new(&env, &contract_id);

        // Test code here
    }
}

Common Test Patterns

// Create test addresses
let alice = Address::generate(&env);
let bob = Address::generate(&env);

// Mock auth
env.mock_all_auths();

// Set ledger timestamp
env.ledger().set_timestamp(1234567890);

// Assert results
assert_eq!(result, expected);
assert!(condition);

🐛 Debugging

Common Errors

# Error: "insufficient balance"
# Solution: Fund account with Friendbot

# Error: "contract not found"
# Solution: Check CONTRACT_ID is correct

# Error: "authorization failed"
# Solution: Use correct --source identity

# Error: "WASM validation failed"
# Solution: Rebuild with `stellar contract build`

Verbose Output

# Run with verbose logs
stellar -v contract invoke ...

# Run with debug logs
RUST_LOG=debug stellar contract invoke ...

📋 Quick Reference

Complete Development Workflow

# 1. Create project
stellar contract init my-contract
cd my-contract

# 2. Code your contract
# Edit src/lib.rs

# 3. Build
stellar contract build

# 4. Check WASM file
ls target/wasm32v1-none/release/*.wasm

# 5. Test locally
cargo test

# 6. Setup identity (first time only)
stellar keys generate alice --network testnet
stellar keys fund alice --network testnet

# 7. Deploy with alias
stellar contract deploy \
  --wasm target/wasm32v1-none/release/my_contract.wasm \
  --source-account alice \
  --network testnet \
  --alias my_contract

# 8. Initialize contract
stellar contract invoke \
  --id my_contract \
  --source-account alice \
  --network testnet \
  -- \
  initialize \
  --owner alice

# 9. Test functions on testnet
stellar contract invoke \
  --id my_contract \
  --source-account alice \
  --network testnet \
  -- \
  your_function \
  --param value

# 10. (Optional) Generate frontend bindings
stellar contract bindings typescript \
  --network testnet \
  --contract-id my_contract \
  --output-dir packages/my_contract

# 11. (Optional) Build bindings
cd packages/my_contract && npm install && npm run build && cd ../..

Common Commands Summary

# Build
stellar contract build

# Test
cargo test

# Deploy
stellar contract deploy --wasm <PATH> --source-account <IDENTITY> --network testnet

# Invoke
stellar contract invoke --id <CONTRACT_ID> --source-account <IDENTITY> --network testnet -- <FUNCTION> --<PARAM> <VALUE>

# Generate identity
stellar keys generate <NAME> --network testnet

# Fund account
stellar keys fund <NAME> --network testnet

# Import seed
stellar keys add <NAME> --secret-key

# List identities
stellar keys ls

# Show public key
stellar keys address <NAME>

�️ Development Environment Setup

Required Tools

# 1. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Install WASM target (Rust 1.85+)
rustup target add wasm32v1-none

# For Rust < 1.85, use:
# rustup target add wasm32-unknown-unknown

# 3. Install Stellar CLI
cargo install --locked stellar-cli --features opt

# Verify installation
stellar --version

Install these extensions for better DX:

  1. rust-analyzer - Rust language support
  2. CodeLLDB - Debugging support
  3. Even Better TOML - Cargo.toml syntax
  4. Error Lens - Inline error messages

Browser Extension

Freighter Wallet - Stellar wallet untuk testnet

💡 Pro Tips

  1. Use --alias for deploy - Easier to reference contracts
  2. Save XLM token address - Testnet: CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC
  3. Check WASM file path - Use ls target/wasm32v1-none/release/*.wasm
  4. Understand 2-step deploy - Upload WASM first, then instantiate
  5. Test locally first - Run cargo test before deploying
  6. Use Persistent storage - For critical data that must persist
  7. Extend TTL regularly - Don’t let important data expire!
  8. Remember: XLM is a token - Use token::Client for XLM transfers
  9. Generate bindings - For smooth frontend integration
  10. Use Stellar Expert - To verify transactions and contract state
  11. Backup secret keys - Save your seed phrases securely
  12. Use testnet generously - It’s free, experiment!

Documentation:

Tools:

Examples:

Learning:

📋 Quick Reference Card

Must-Know Addresses (Testnet)

# XLM Token Contract (MUST HAVE!)
CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

# Friendbot (Fund testnet accounts)
https://friendbot.stellar.org?addr=YOUR_PUBLIC_KEY

Most Used Commands

# Setup
stellar keys generate alice --network testnet
stellar keys fund alice --network testnet

# Build & Deploy
stellar contract build
stellar contract deploy --wasm target/wasm32v1-none/release/CONTRACT.wasm --source-account alice --network testnet --alias CONTRACT_NAME

# Invoke
stellar contract invoke --id CONTRACT_NAME --source-account alice --network testnet -- FUNCTION --param value

# With XLM token
stellar contract invoke --id CONTRACT --source-account alice --network testnet -- initialize --xlm_token CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

Common Gotchas ⚠️

  1. XLM is a token contract - Always pass token address for XLM transfers
  2. Use --source-account - NOT --source
  3. WASM path is wasm32v1-none - For Rust 1.85+
  4. TTL expires - Extend storage before it archives
  5. Wait for confirmation - Poll transaction status before assuming success

Happy Building! 🚀