Skip to content

API_REFERENCE.md

Latest commit

 

History

History
1210 lines (856 loc) · 24 KB

API_REFERENCE.md

File metadata and controls

1210 lines (856 loc) · 24 KB

StarForge API Reference

Complete reference for all StarForge commands, options, and utilities.

For a concise, navigable index of every CLI subcommand see docs/COMMAND_REFERENCE.md.

Table of Contents

  1. Command Line Interface
  2. Wallet Commands
  3. Template Commands
  4. Contract Commands
  5. Network Commands
  6. Transaction Commands
  7. Utility Commands
  8. Configuration
  9. Exit Codes

Command Line Interface

Global Options

starforge [OPTIONS] <COMMAND>
Option Description
-q, --quiet Suppress ASCII banner and decorative output
-h, --help Print help information
-V, --version Print version information

Environment Variables

Variable Description Default
STARFORGE_CONFIG_DIR Configuration directory ~/.starforge
STARFORGE_TELEMETRY Enable/disable telemetry true
RUST_LOG Logging level info

Wallet Commands

starforge wallet create

Create a new Stellar keypair and save it locally.

Usage:

starforge wallet create <NAME> [OPTIONS]

Arguments:

  • <NAME> - Friendly name for the wallet (alphanumeric, dash, underscore)

Options:

  • --fund - Fund the wallet via Friendbot immediately (testnet only)
  • --network <NETWORK> - Network to associate with wallet (testnet, mainnet)
  • --encrypt - Encrypt the secret key with a passphrase

Examples:

# Create basic wallet
starforge wallet create alice

# Create and fund on testnet
starforge wallet create deployer --fund

# Create with encryption
starforge wallet create secure-wallet --encrypt

# Create on mainnet
starforge wallet create mainnet-wallet --network mainnet

Output:

◆ Creating wallet 'alice'

[1/2] Generating keypair…

Public Key     : GABC...XYZ
Secret Key     : Stored in plaintext (not recommended for mainnet).

[2/2] Saving to ~/.starforge/config.toml…

✓ Wallet 'alice' created and saved!

View it with: starforge wallet show alice

starforge wallet list

List all saved wallets.

Usage:

starforge wallet list

Output:

◆ Saved Wallets
─────────────────────────────────────────────────────────────

  1. alice [funded]
     Key : GABC...XYZ
     Net : testnet

  2. bob [unfunded]
     Key : GDEF...ABC
     Net : testnet

─────────────────────────────────────────────────────────────
2 wallet(s) on testnet — ~/.starforge/config.toml

starforge wallet show

Show details of a saved wallet including live balance.

Usage:

starforge wallet show <NAME> [OPTIONS]

Arguments:

  • <NAME> - Wallet name

Options:

  • --reveal - Show the secret key in plaintext

Examples:

# Show wallet details
starforge wallet show alice

# Reveal secret key
starforge wallet show alice --reveal

Output:

◆ Wallet: alice
─────────────────────────────────────────────────────────────

Public Key     : GABC...XYZ
Secret Key     : ******************** (--reveal to show)
Network        : testnet
Funded         : yes
Created        : 2025-01-01T00:00:00Z

─────────────────────────────────────────────────────────────

Fetching live balance on testnet…

XLM            : 10000.0000000 XLM

starforge wallet fund

Fund a wallet via Friendbot (testnet only).

Usage:

starforge wallet fund <NAME>

Arguments:

  • <NAME> - Wallet name to fund

Example:

starforge wallet fund alice

starforge wallet remove

Remove a wallet from local storage.

Usage:

starforge wallet remove <NAME>

Arguments:

  • <NAME> - Wallet name to remove

Example:

starforge wallet remove alice

starforge wallet rename

Rename a wallet.

Usage:

starforge wallet rename <OLD_NAME> <NEW_NAME>

Arguments:

  • <OLD_NAME> - Current wallet name
  • <NEW_NAME> - New wallet name

Example:

starforge wallet rename alice alice-testnet

starforge wallet export

Export a wallet to a JSON backup file.

Usage:

starforge wallet export <NAME> --output <FILE>

Arguments:

  • <NAME> - Wallet name to export

Options:

  • --output <FILE> - Output file path for the backup JSON

Example:

starforge wallet export alice --output ./wallet-backup.json

Notes:

  • Secrets are written only to the backup file and are never printed to stdout.

starforge wallet import

Import wallets from a JSON backup file.

Usage:

starforge wallet import --file <FILE>

Options:

  • --file <FILE> - Path to a wallet backup JSON file

Example:

starforge wallet import --file ./wallet-backup.json

starforge wallet sign

Sign an arbitrary message using a wallet.

Usage:

starforge wallet sign <NAME> <MESSAGE> [OPTIONS]

Arguments:

  • <NAME> - Wallet name to use for signing
  • <MESSAGE> - Message to sign (UTF-8 string)

Options:

  • --hardware <DEVICE> - Use hardware wallet (ledger, trezor)

Examples:

# Sign with local key
starforge wallet sign alice "Hello, Stellar!"

# Sign with hardware wallet
starforge wallet sign alice "Transaction data" --hardware ledger

starforge wallet multisig

Multi-signature account management.

starforge wallet multisig create

Create a multi-sig configuration.

Usage:

starforge wallet multisig create <NAME> --threshold <N> --signers <WALLETS>

Arguments:

  • <NAME> - Multi-sig account name

Options:

  • --threshold <N> - Required signature weight
  • --signers <WALLETS> - Comma-separated wallet names
  • --network <NETWORK> - Network override

Example:

starforge wallet multisig create treasury \
  --threshold 2 \
  --signers alice,bob,charlie

starforge wallet multisig sign

Sign a multi-sig transaction.

Usage:

starforge wallet multisig sign <NAME> --transaction <FILE> [OPTIONS]

Arguments:

  • <NAME> - Multi-sig account name

Options:

  • --transaction <FILE> - Path to transaction JSON
  • --output <FILE> - Output file (defaults to in-place update)

Example:

starforge wallet multisig sign treasury --transaction tx.json

starforge wallet multisig list

List multi-sig accounts.

Usage:

starforge wallet multisig list

starforge wallet multisig show

Show multi-sig account details.

Usage:

starforge wallet multisig show <NAME>

starforge wallet multisig submit

Submit a fully-signed multi-sig transaction.

Usage:

starforge wallet multisig submit <NAME> --transaction <FILE> [OPTIONS]

Options:

  • --transaction <FILE> - Path to signed transaction JSON
  • --network <NETWORK> - Network to submit on

Template Commands

starforge template init

Initialize template registry with example templates.

Usage:

starforge template init

Output:

◆ Initialize Template Registry

Adding example templates to the marketplace...

✓ Added: uniswap-v2
✓ Added: lending-pool
✓ Added: governance
✓ Added: multisig-wallet

✓ Template registry initialized with 4 example templates

Browse templates:
  starforge template list
  starforge template search defi

starforge template search

Search for templates in the marketplace.

Usage:

starforge template search <QUERY> [OPTIONS]

Arguments:

  • <QUERY> - Search query (matches name, description, tags)

Options:

  • --tags <TAGS> - Filter by tags (comma-separated)

Examples:

# Search by keyword
starforge template search defi

# Search with tag filter
starforge template search dex --tags amm,swap

# Search for governance
starforge template search governance

Output:

◆ Template Marketplace — Search
Query          : defi
─────────────────────────────────────────────────────────────

Found 2 template(s):

1. uniswap-v2 ✓
   Uniswap V2 style automated market maker (AMM) DEX implementation
   1.0.0 • Stellar Community • 42 downloads
   Tags: defi, dex, amm, swap

2. lending-pool ✓
   Decentralized lending and borrowing protocol
   1.0.0 • Stellar Community • 28 downloads
   Tags: defi, lending, borrowing

─────────────────────────────────────────────────────────────

Use a template:
  starforge new contract my-project --template uniswap-v2 --from marketplace

starforge template list

List all available templates.

Usage:

starforge template list

starforge template show

Show details of a specific template.

Usage:

starforge template show <NAME>

Arguments:

  • <NAME> - Template name

Example:

starforge template show uniswap-v2

Output:

◆ Template: uniswap-v2
─────────────────────────────────────────────────────────────

uniswap-v2 ✓

Description    : Uniswap V2 style automated market maker (AMM) DEX
Version        : 1.0.0
Author         : Stellar Community
Downloads      : 42
Tags           : defi, dex, amm, swap

Created        : 2025-01-01T00:00:00Z
Updated        : 2025-01-15T00:00:00Z

Source         : Git Repository
URL            : https://github.com/stellar/soroban-examples
Branch         : main

─────────────────────────────────────────────────────────────

Use this template:
  starforge new contract my-project --template uniswap-v2 --from marketplace

starforge template publish

Publish a template to the local marketplace.

Usage:

starforge template publish <PATH> [OPTIONS]

Arguments:

  • <PATH> - Path to template directory

Options:

  • --name <NAME> - Template name
  • --description <DESC> - Template description
  • --author <AUTHOR> - Author name
  • --tags <TAGS> - Comma-separated tags
  • --version <VERSION> - Version (default: 1.0.0)

Examples:

# Publish with all options
starforge template publish ./my-template \
  --name my-awesome-template \
  --description "An awesome contract" \
  --author "Your Name" \
  --tags "defi,custom" \
  --version "1.0.0"

# Interactive publish (prompts for missing info)
starforge template publish ./my-template

starforge template remove

Remove a template from the local marketplace.

Usage:

starforge template remove <NAME>

Arguments:

  • <NAME> - Template name to remove

Example:

starforge template remove my-template

Contract Commands

starforge new contract

Scaffold a new Soroban smart contract project.

Usage:

starforge new contract <NAME> [OPTIONS]

Arguments:

  • <NAME> - Project name

Options:

  • --template <TEMPLATE> - Template to use (hello-world, token, nft, voting)
  • --interactive - Interactively customize the contract
  • --from <SOURCE> - Use template from source (marketplace)
  • --search <QUERY> - Search for templates
  • --tags <TAGS> - Filter templates by tags
  • --ci - Generate .github/workflows/stellar-ci.yml (cargo test + WASM size checks)

Examples:

# Basic contract
starforge new contract my-contract

# Use specific template
starforge new contract my-token --template token

# Interactive mode
starforge new contract my-contract --interactive

# From marketplace
starforge new contract my-dex --template uniswap-v2 --from marketplace

# Search templates
starforge new contract --search defi --tags dex

# Include GitHub Actions CI
starforge new contract my-contract --ci

starforge contract inspect

Inspect a deployed contract instance.

Usage:

starforge contract inspect <CONTRACT_ID> [OPTIONS]

Arguments:

  • <CONTRACT_ID> - Contract ID (starts with 'C')

Options:

  • --network <NETWORK> - Network to use
  • --json - Print machine-readable JSON output

Example:

starforge contract inspect CCPYZFKEAXHHS5VVW5J45TOU7S2EODJ7TZNJIA5LKDVL3PESCES6FNCI

JSON schema (--json):

  • contract_id (string)
  • executable (string)
  • wasm_hash (string|null)
  • storage_durability (string)
  • latest_ledger (number)
  • last_modified_ledger_seq (number|null)
  • live_until_ledger_seq (number|null)
  • instance_storage (array of objects): { "key": string, "value": string }

starforge deploy

Deploy a compiled Soroban contract.

Usage:

starforge deploy --wasm <FILE> [OPTIONS]

Options:

  • --wasm <FILE> - Path to compiled .wasm file (required)
  • --network <NETWORK> - Network to deploy to (testnet, mainnet)
  • --wallet <NAME> - Wallet name to use for deployment
  • --optimize - Run built-in WASM optimizer before deployment prep
  • --simulate - Simulate deploy via Soroban RPC (fee estimate, error check)
  • --yes - Skip confirmation prompt
  • --execute - Execute stellar contract deploy ... when stellar CLI is on PATH (default is dry-run)

Examples:

# Deploy to testnet
starforge deploy --wasm target/wasm32-unknown-unknown/release/my_contract.wasm

# Deploy to mainnet with specific wallet
starforge deploy \
  --wasm ./my_contract.wasm \
  --network mainnet \
  --wallet deployer

# Skip confirmation (for CI)
starforge deploy --wasm ./my_contract.wasm --yes

# Simulate fees before confirming
starforge deploy --wasm ./my_contract.wasm --simulate --wallet deployer

# Execute immediately (requires stellar CLI on PATH)
starforge deploy --wasm ./my_contract.wasm --execute

Network Commands

starforge network show

Show current network and available networks.

Usage:

starforge network show

starforge network switch

Switch the active network.

Usage:

starforge network switch <NETWORK>

Arguments:

  • <NETWORK> - Target network (testnet, mainnet, or custom)

Example:

starforge network switch mainnet

starforge network add

Add a custom network endpoint.

Usage:

starforge network add <NAME> --horizon-url <URL> [OPTIONS]

Arguments:

  • <NAME> - Network name

Options:

  • --horizon-url <URL> - Horizon API URL (required)
  • --soroban-rpc-url <URL> - Soroban RPC URL (optional)

Example:

starforge network add mynet \
  --horizon-url https://my-horizon.example.com \
  --soroban-rpc-url https://my-soroban.example.com

starforge network test

Test connectivity to a network.

Usage:

starforge network test [NETWORK]

Arguments:

  • [NETWORK] - Network to test (defaults to current)

Example:

starforge network test mainnet

Transaction Commands

starforge tx send

Send a Stellar payment transaction.

Usage:

starforge tx send --from <WALLET> --to <ADDRESS> --amount <AMOUNT> [OPTIONS]

Options:

  • --from <WALLET> - Source wallet name (required)
  • --to <ADDRESS> - Destination public key (required)
  • --amount <AMOUNT> - Amount to send (required)
  • --asset <ASSET> - Asset to send (default: XLM, format: CODE:ISSUER)
  • --network <NETWORK> - Network to use
  • --yes - Skip confirmation prompt

Examples:

# Send XLM
starforge tx send --from alice --to GDEF... --amount 100

# Send custom asset
starforge tx send \
  --from alice \
  --to GDEF... \
  --amount 50 \
  --asset USDC:GABC...

# Skip confirmation
starforge tx send --from alice --to GDEF... --amount 10 --yes

starforge tx batch

Submit multiple Stellar operations in a single transaction from a JSON file.

Usage:

starforge tx batch --file <FILE> --from <WALLET> [OPTIONS]

Options:

  • --file <FILE> - Path to operations JSON (required)
  • --from <WALLET> - Source wallet name (required)
  • --network <NETWORK> - Network to use (testnet or mainnet, default: testnet)
  • --yes - Skip confirmation prompt

Operations file schema:

{
  "operations": [
    {
      "type": "payment",
      "to": "GDEF...",
      "amount": "100",
      "asset": "XLM"
    }
  ]
}

Supported operation types: payment (to, amount, optional asset as XLM or CODE:ISSUER).

Examples:

starforge tx batch --file operations.json --from alice
starforge tx batch --file ops.json --from alice --network testnet --yes

starforge tx history

Fetch and display recent transactions.

Usage:

starforge tx history <PUBLIC_KEY> [OPTIONS]

Arguments:

  • <PUBLIC_KEY> - Account public key

Options:

  • -l, --limit <N> - Number of transactions (max 200, default: 10)
  • -n, --network <NETWORK> - Network to use
  • --cursor <CURSOR> - Pagination cursor
  • --after <DATE> - Show transactions after date (ISO 8601)
  • --before <DATE> - Show transactions before date (ISO 8601)
  • --successful - Show only successful transactions
  • --details - Show full transaction details

Examples:

# Recent transactions
starforge tx history GABC...

# Last 50 transactions
starforge tx history GABC... --limit 50

# Filter by date
starforge tx history GABC... --after 2025-01-01 --before 2025-01-31

# Only successful
starforge tx history GABC... --successful

# With details
starforge tx history GABC... --details

Utility Commands

starforge info

Show starforge config and environment info.

Usage:

starforge info

starforge completions

Generate shell completions.

Usage:

starforge completions <SHELL>

Arguments:

  • <SHELL> - Shell type (bash, zsh, fish)

Examples:

# Bash
starforge completions bash > ~/.bash_completion.d/starforge

# Zsh
starforge completions zsh > ~/.zsh/completions/_starforge

# Fish
starforge completions fish > ~/.config/fish/completions/starforge.fish

starforge shell

Interactive REPL for local contract testing.

Usage:

starforge shell --contract <WASM>

Options:

  • --contract <WASM> - Path to compiled contract
  • --no-history - Disable persistent history for this session
  • --history-max-lines <N> - Max lines to keep in ~/.starforge/repl_history (default: 1000)

Example:

starforge shell --contract target/wasm32-unknown-unknown/release/my_contract.wasm

starforge monitor

Live monitoring of contracts or wallets.

Usage:

starforge monitor [OPTIONS]

Options:

  • --contract <ID> - Contract ID to monitor
  • --events <EVENTS> - Comma-separated event names to filter
  • --wallet <NAME> - Wallet name to monitor
  • --threshold <AMOUNT> - XLM threshold for notifications
  • --network <NETWORK> - Network to use
  • --interval <SECONDS> - Poll interval (default: 2)

Examples:

# Monitor contract events
starforge monitor --contract CCPYZ... --events transfer,mint

# Monitor wallet balance
starforge monitor --wallet alice --threshold 1000

starforge test

Run contract tests.

Usage:

starforge test --wasm <FILE> [OPTIONS]

Options:

  • --wasm <FILE> - Path to compiled wasm (required)
  • --coverage - Collect coverage report
  • --report <FORMAT> - Output report format (html, json)

Example:

starforge test --wasm target/wasm32-unknown-unknown/release/my_contract.wasm --coverage

starforge gas

Gas analysis and optimization.

starforge gas analyze

Analyze gas costs.

Usage:

starforge gas analyze --wasm <FILE> [OPTIONS]

Options:

  • --wasm <FILE> - Path to wasm file (required)
  • --network <NETWORK> - Network to use

starforge gas optimize

Optimize wasm for gas efficiency.

Usage:

starforge gas optimize --target <INPUT> --output <OUTPUT>

Options:

  • --target <INPUT> - Input wasm file (required)
  • --output <OUTPUT> - Output wasm file (required)

starforge gas diff

Compare two wasm builds side-by-side and diff estimated simulation cost.

Usage:

starforge gas diff <OLD_WASM> <NEW_WASM>

Arguments:

  • <OLD_WASM> - Baseline wasm file
  • <NEW_WASM> - Candidate wasm file

Output includes:

  • Old/new wasm size
  • Old/new estimated simulation cost
  • Delta and percentage change
  • Profiling timings per analysis step

starforge inspect storage

List decoded storage entries for a contract scope.

Usage:

starforge inspect storage <CONTRACT_ID> [OPTIONS]

Options:

  • --scope <SCOPE> - instance, persistent, or temporary
  • --network <NETWORK> - Network to use (testnet, mainnet)
  • --json - Print machine-readable JSON output

JSON schema (--json):

  • contract_id (string)
  • scope (string)
  • entries (array of objects): { "key": string, "value": string }

starforge benchmark

Performance benchmarking.

Usage:

starforge benchmark [OPTIONS]

starforge plugin

Manage third-party plugins.

starforge plugin install

Install a plugin.

Usage:

starforge plugin install <NAME> --path <LIB>

starforge plugin list

List installed plugins.

Usage:

starforge plugin list

starforge plugin load

Load and verify plugins.

Usage:

starforge plugin load

Configuration

Config File Location

~/.starforge/config.toml

Config Structure

version = "1"
network = "testnet"
telemetry_enabled = true

[[wallets]]
name = "alice"
public_key = "GABC...XYZ"
secret_key = "SABC...XYZ"  # or encrypted: "salt:nonce:ciphertext"
network = "testnet"
created_at = "2025-01-01T00:00:00Z"
funded = true

[networks.testnet]
horizon_url = "https://horizon-testnet.stellar.org"
soroban_rpc_url = "https://soroban-testnet.stellar.org"

[networks.mainnet]
horizon_url = "https://horizon.stellar.org"
soroban_rpc_url = "https://mainnet.sorobanrpc.com"

Exit Codes

Code Meaning
0 Success
1 General error
2 Invalid arguments
3 Configuration error
4 Network error
5 Validation error

Template Placeholders

When creating templates, use these placeholders:

Placeholder Description Example
{{PROJECT_NAME}} Original project name my-project
{{PROJECT_NAME_SNAKE}} Snake case my_project
{{PROJECT_NAME_PASCAL}} Pascal case MyProject

Error Messages

Common Errors

Wallet not found:

✗ Error: Wallet 'alice' not found

Try: starforge wallet list

Network unreachable:

✗ Error: Failed to reach Horizon on testnet

Check your internet connection or try: starforge network test

Invalid public key:

✗ Error: Invalid public key: must start with 'G'

A valid Stellar public key looks like: GABC...XYZ (56 characters)

Best Practices

  1. Always encrypt mainnet wallets: Use --encrypt flag
  2. Test on testnet first: Verify everything works before mainnet
  3. Use descriptive wallet names: e.g., deployer-testnet, treasury-mainnet
  4. Keep backups: Export and securely store secret keys
  5. Review templates: Always review template code before using
  6. Use verified templates: Look for the ✓ badge

Support