Soroban Debugger

A command-line debugger for Soroban smart contracts on the Stellar network. Debug your contracts interactively with breakpoints, step-through execution, state inspection, and budget tracking.

Features

Step-through execution of Soroban contracts
Set breakpoints at function boundaries
Inspect contract storage and state
Track resource usage (CPU and memory budget)
View call stacks for contract invocations
Interactive terminal UI for debugging sessions
Support for cross-contract calls

Installation

From Source

git clone https://github.com/Timi16/soroban-debugger.git
cd soroban-debugger
cargo install --path .

Using Cargo

cargo install soroban-debugger

Quick Start

Basic Usage

Debug a contract by specifying the WASM file and function to execute:

# Array arguments
soroban-debug run --contract token.wasm --function transfer --args '["Alice", "Bob", 100]'

# Map argument (JSON object)
soroban-debug run --contract token.wasm --function update --args '{"user":"Alice","balance":1000}'

Interactive Mode

Start an interactive debugging session:

soroban-debug interactive --contract my_contract.wasm

Then use commands like:

s or step - Execute next instruction
c or continue - Run until next breakpoint
i or inspect - Show current state
storage - Display contract storage
budget - Show resource usage
q or quit - Exit debugger

Commands

Run Command

Execute a contract function with the debugger:

soroban-debug run [OPTIONS]

Options:
  -c, --contract <FILE>     Path to the contract WASM file
  -f, --function <NAME>     Function name to execute
  -a, --args <JSON>         Function arguments as JSON array
  -s, --storage <JSON>      Initial storage state as JSON
  -b, --breakpoint <NAME>   Set breakpoint at function name

Interactive Command

Start an interactive debugging session:

soroban-debug interactive [OPTIONS]

Options:
  -c, --contract <FILE>     Path to the contract WASM file

Inspect Command

View contract information without executing:

soroban-debug inspect [OPTIONS]

Options:
  -c, --contract <FILE>     Path to the contract WASM file

Examples

Example 1: Debug a Token Transfer

soroban-debug run \
  --contract token.wasm \
  --function transfer \
  --args '["user1", "user2", 100]'

Example 1a: Debug with Map Arguments

Pass JSON objects as Map arguments:

# Flat map argument
soroban-debug run \
  --contract token.wasm \
  --function update_user \
  --args '{"user":"ABC","balance":1000}'

# Nested map argument
soroban-debug run \
  --contract token.wasm \
  --function update_user \
  --args '{"user":"ABC","balance":1000,"metadata":{"verified":true,"level":"premium"}}'

# Mixed-type values in map
soroban-debug run \
  --contract dao.wasm \
  --function create_proposal \
  --args '{"title":"Proposal 1","votes":42,"active":true,"tags":["important","urgent"]}'

Output:

> Debugger started
> Paused at: transfer
> Args: from=user1, to=user2, amount=100

(debug) s
> Executing: get_balance(user1)
> Storage: balances[user1] = 500

(debug) s
> Executing: set_balance(user1, 400)

(debug) storage
Storage:
  balances[user1] = 400
  balances[user2] = 100

(debug) c
> Execution completed
> Result: Ok(())

Example 2: Set Breakpoints

soroban-debug run \
  --contract dao.wasm \
  --function execute \
  --breakpoint verify_signature \
  --breakpoint update_state

Example 3: Initial Storage State

soroban-debug run \
  --contract token.wasm \
  --function mint \
  --storage '{"balances": {"Alice": 1000}, "total_supply": 5000}'

Example 4: Track Budget Usage

soroban-debug run --contract complex.wasm --function expensive_operation

> Budget: CPU 45000/100000 (45%), Memory 15KB/40KB (37%)
> Warning: High CPU usage detected

Interactive Commands Reference

During an interactive debugging session, you can use:

Commands:
  s, step              Execute next instruction
  c, continue          Run until breakpoint or completion
  n, next              Step over function calls
  i, inspect           Show current execution state
  storage              Display all storage entries
  stack                Show call stack
  budget               Show resource usage (CPU/memory)
  args                 Display function arguments
  break <function>     Set breakpoint at function
  list-breaks          List all breakpoints
  clear <function>     Remove breakpoint
  help                 Show this help message
  q, quit              Exit debugger

Use Cases

Debugging Failed Transactions

When your contract transaction fails without clear error messages, use the debugger to step through execution and identify where and why it fails.

Storage Inspection

Verify that your contract is reading and writing storage correctly by inspecting storage state at each step.

Budget Optimization

Identify which operations consume the most CPU or memory to optimize your contract's resource usage.

Cross-Contract Call Tracing

Debug interactions between multiple contracts by following the call stack through contract boundaries.

Testing Edge Cases

Quickly test different input scenarios interactively without redeploying your contract.

Development

Building from Source

git clone https://github.com/Timi16/soroban-debugger.git
cd soroban-debugger
cargo build --release

Running Tests

cargo test

Running Examples

cargo run --example simple_token

Requirements

Rust 1.75 or later
Soroban SDK 22.0.0 or later

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Development Setup

Fork the repository
Create a feature branch
Make your changes
Run tests: cargo test
Submit a pull request

Code Style

This project follows standard Rust formatting:

cargo fmt
cargo clippy

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Resources

Soroban Documentation: https://soroban.stellar.org/docs
Stellar Developer Discord: https://discord.gg/stellardev
Issue Tracker: https://github.com/Timi16/soroban-debugger/issues
CHANGELOG - Release history and changes

Acknowledgments

Built for the Stellar ecosystem to improve the Soroban smart contract development experience.

Docker

Build Locally

docker build -t soroban-debugger:local .

Run with a Mounted WASM

docker run --rm -v "$(pwd):/contracts" ghcr.io/your-org/soroban-debug run --contract /contracts/token.wasm --function transfer

Interactive Mode (TTY)

docker run --rm -it -v "$(pwd):/contracts" ghcr.io/your-org/soroban-debug interactive --contract /contracts/token.wasm

Docker Compose

docker compose run --rm soroban-debug run --contract /contracts/token.wasm --function transfer

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
.github/workflows		.github/workflows
examples		examples
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTION.md		CONTRIBUTION.md
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
Readme.md		Readme.md
cliff.toml		cliff.toml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Soroban Debugger

Features

Installation

From Source

Using Cargo

Quick Start

Basic Usage

Interactive Mode

Commands

Run Command

Interactive Command

Inspect Command

Examples

Example 1: Debug a Token Transfer

Example 1a: Debug with Map Arguments

Example 2: Set Breakpoints

Example 3: Initial Storage State

Example 4: Track Budget Usage

Interactive Commands Reference

Use Cases

Debugging Failed Transactions

Storage Inspection

Budget Optimization

Cross-Contract Call Tracing

Testing Edge Cases

Development

Building from Source

Running Tests

Running Examples

Requirements

Contributing

Development Setup

Code Style

License

Resources

Acknowledgments

Docker

Build Locally

Run with a Mounted WASM

Interactive Mode (TTY)

Docker Compose

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages