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.

Table of Contents

• Quick Start
• User Journeys
• Command Index
• Reference
  • Supported Argument Types
  • Storage Filtering
  • Exporting Execution Traces
• Interactive Commands
• Examples
• Troubleshooting
• Contributing
• License

---

Quick Start

1. Installation

Using Cargo (Recommended)

cargo install soroban-debugger

From Source

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

2. Your First Debug Run

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

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

For an interactive session with a terminal UI:

soroban-debug interactive --contract my_contract.wasm --function hello

For a comprehensive introduction, see the Getting Started Guide.

---

User Journeys

🛠️ Debugging Your First Contract

Learn how to execute functions, pass complex arguments, and use the interactive debugger.

• Basic Execution: Use the run command to execute functions and see results immediately.
• Interactive Mode: Use interactive for a step-by-step walkthrough with breakpoints.
• REPL: Use repl for repeated calls and exploration without restarting.
• Complex Arguments: Support for JSON-nested vectors, maps, and typed annotations.

🔍 Source-Level Debugging

Debug your Rust code directly instead of raw WASM instructions.

• Rust Source Mapping: Automatically maps WASM offsets back to Rust lines using DWARF debug info.
• Instruction Stepping: Step into, over, or out of functions at the source level.
• Source Map Caching: Fast O(1) lookups for source locations after the first load.

See Source-Level Debugging Guide for details.

🌐 Remote Debugging Sessions

Debug contracts running on remote servers or in CI environments.

• Debug Server: Start a server process to host a debugging session.
• Remote Client: Connect to a running server using the remote command.
• Secure Connections: Support for TLS and token-based authentication.

See Remote Debugging Guide for setup instructions.

📈 Analysis & Optimization

Analyze contract metadata, resource usage, and upgrade compatibility.

• Inspection: Use inspect to view contract functions and metadata without executing.
• Profiling: Use profile to find hotspots and budget-heavy execution paths.
• Optimization: Use optimize for automated gas and performance suggestions.
• Upgrade Checks: Use upgrade-check to ensure API compatibility between versions.

🤖 Regression & Automated Testing

Integrate debugging into your CI/CD pipeline and discover edge cases.

• Scenarios: Define multi-step integration tests in simple TOML files.
• Batch Execution: Run the same function with multiple argument sets in parallel.
• Symbolic Analysis: Automatically explore input spaces to find panics and edge cases.
• Test Generation: Generate ready-to-run Rust unit tests from any debug session.

---

Command Index

Category	Commands
Run & Debug	run, interactive, repl, tui, scenario, replay
Analyze & Compare	inspect, upgrade-check, optimize, profile, compare, symbolic, analyze
Remote & Server	server, remote
Utilities	completions, history-prune

Use soroban-debug <command> --help for full flags and examples.

---

Reference

Supported Argument Types

The debugger supports passing typed arguments via the --args flag.

JSON Value	Soroban Type	Example
Number	i128	10, -5
String	Symbol	"hello"
Boolean	Bool	true
Array	Vec<Val>	[1, 2, 3]
Object	Map	{"key": "value"}

Typed Annotations

For precise control, use {"type": "...", "value": ...}: u32, i32, u64, i64, u128, i128, bool, symbol, string, address.

Storage Filtering

Filter large storage outputs by key pattern using --storage-filter:

# Prefix match: keys starting with "balance:"
soroban-debug run --contract token.wasm --function mint \
  --storage-filter 'balance:*'

# Regex match: keys matching a pattern
soroban-debug run --contract token.wasm --function mint \
  --storage-filter 're:^user_\d+$'

# Exact match
soroban-debug run --contract token.wasm --function mint \
  --storage-filter 'total_supply'

# Multiple filters (combined with OR)
soroban-debug run --contract token.wasm --function mint \
  --storage-filter 'balance:*' \
  --storage-filter 'total_supply'

Exporting Execution Traces

You can export a full record of the contract execution to a JSON file using the --trace-output flag. This trace captures function calls, arguments, return values, storage snapshots (before and after), events, and budget consumption.

soroban-debug run \
  --contract contract.wasm \
  --function hello \
  --trace-output execution_trace.json

These traces can later be used with the compare command to identify regressions or differences between runs.

Example Trace Output (JSON)

An exported trace includes versioning, metadata, and full execution state:

{
  "version": "1.0",
  "label": "Execution of hello",
  "contract": "CA7QYNF5GE5XEC4HALXWFVQQ5TQWQ5LF7WMXMEQG7BWHBQV26YCWL5",
  "function": "hello",
  "args": "[\"world\"]",
  "storage_before": {
    "counter": "0"
  },
  "storage": {
    "counter": "1"
  },
  "budget": {
    "cpu_instructions": 1540,
    "memory_bytes": 450,
    "cpu_limit": 1000000,
    "memory_limit": 1000000
  },
  "return_value": "void",
  "call_sequence": [
    {
      "function": "hello",
      "args": "[\"world\"]",
      "depth": 0,
      "budget": {
        "cpu_instructions": 1540,
        "memory_bytes": 450
      }
    }
  ],
  "events": [
    {
      "contract_id": "CA7Q...",
      "topics": ["\"greeting\""],
      "data": "\"Hello, world!\""
    }
  ]
}

Pattern	Type	Matches
balance:*	Prefix	Keys starting with balance:
re:^user_\d+$	Regex	Keys matching the regex
total_supply	Exact	Only the key total_supply

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
      --source-map-diagnostics
                            Print resolved mappings, missing DWARF sections, and fallback behavior
      --dependency-graph     Export cross-contract dependency graph (DOT + Mermaid)

Use soroban-debug inspect --contract my_contract.wasm --source-map-diagnostics --format json when you want a non-interactive DWARF triage report for CI or editor tooling.

For full examples, see docs/dependency-graph.md.

Upgrade Check Command

Compare two contract binaries for API breakage and execution differences before releasing:

soroban-debug upgrade-check --old current.wasm --new upgraded.wasm

The debugger runs parallel traces and classifies the upgrade:

• Safe: No breaking changes, stable inputs execution.
• Caution: Non-breaking changes like new map arguments or endpoints.
• Breaking: Removed functions, changed signatures, or execution panic regressions.

Completions Command

Generate shell completion scripts for your favorite shell:

soroban-debug completions bash > /usr/local/etc/bash_completion.d/soroban-debug

Supported shells: bash, zsh, fish, powershell.

Installation Instructions

Bash:

soroban-debug completions bash > /usr/local/etc/bash_completion.d/soroban-debug

Zsh:

soroban-debug completions zsh > /usr/local/share/zsh/site-functions/_soroban-debug

Fish:

soroban-debug completions fish > ~/.config/fish/completions/soroban-debug.fish

PowerShell:

soroban-debug completions powershell >> $PROFILE

Compare Command

Compare two execution trace JSON files side-by-side to identify differences and regressions in storage, budget, return values, and execution flow:

soroban-debug compare <TRACE_A> <TRACE_B> [OPTIONS]

Options:
  -o, --output <FILE>       Output file for the comparison report (default: stdout)

Example:

# Compare two saved execution traces
soroban-debug compare examples/trace_a.json examples/trace_b.json

# Save report to a file
soroban-debug compare baseline.json new.json --output diff_report.txt

See doc/compare.md for the full trace JSON format reference and a regression testing workflow guide.

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-filter 'balance:*'

Supports prefix*, re:<regex>, and exact_match.

Configuration File

Load default settings from .soroban-debug.toml:

[debug]
breakpoints = ["verify", "auth"]
[output]
show_events = true

---

Troubleshooting

Symptom	Likely Cause	Solution
Request timed out	Slow host or low timeout	Increase --timeout-ms
Incompatible protocol	Build version mismatch	Reinstall client/server from same release
Auth failed	Token mismatch	Verify --token values match

For more scenarios, see the Full FAQ and Remote Troubleshooting Guide.

---

Contributing

Please see CONTRIBUTING.md for setup and workflow.

License

Licensed under Apache 2.0 or MIT.