erst debug

Debug failed Soroban transactions and analyze smart contract execution

The debug command is the primary entry point for debugging Soroban transactions. It fetches transaction data from the network, simulates execution locally, and provides detailed error traces.

Usage

erst debug <transaction-hash> [flags]

Description

The debug command helps you understand why a Soroban transaction failed by:

• Fetching the transaction envelope and ledger state from the network
• Simulating execution locally with detailed instrumentation
• Decoding errors and mapping them to readable instructions
• Tracking token flows and contract events
• Generating execution traces for further analysis

Examples

Debug on mainnet

erst debug abc123...def

Flags

Network configuration

--network · string · default: "mainnet"

Stellar network to use: testnet, mainnet, or futurenet

--rpc-url · string

Custom Soroban RPC URL (overrides default for network)

--rpc-token · string

RPC authentication token (can also use ERST_RPC_TOKEN env var)

Local testing

--wasm · string

Path to local WASM file for testing without deploying

--optimize · boolean · default: "false"

Run dead-code elimination on local WASM before simulation

--args · string[]

Mock arguments to pass to the local WASM execution

Output options

--verbose · boolean · default: "false"

Print detailed simulation output and diagnostic information

Alias: -v

--interactive · boolean · default: "false"

Launch interactive trace viewer after debugging

Alias: -i

--theme · string

Color theme for output: default, deuteranopia, protanopia, tritanopia, or high-contrast

Advanced options

--protocol-version · uint32

Override protocol version for simulation (20, 21, 22, etc.)

--sim-path · string

Path to erst-sim binary (overrides auto-discovery)

Interactive mode

When using --interactive, the debug command launches a terminal UI with:

• Search: Press / to search through traces
• Navigation: Use arrow keys to expand/collapse nodes
• Help: Press ? or h to see all keyboard shortcuts
• Syntax highlighting: Color-coded contract IDs, functions, and errors
• Match counter: See “Match 2 of 5” while searching

Performance profiling

When using --profile, generates an interactive flamegraph visualizing CPU and memory consumption:

# Generate interactive HTML flamegraph
erst debug --profile abc123...def

# Generate raw SVG
erst debug --profile --profile-format svg abc123...def

The flamegraph includes:

• Hover tooltips with frame details
• Click-to-zoom for specific call stacks
• Search/highlight to find frames by name
• Dark mode support

Related commands

• trace - Navigate execution traces interactively
• compare - Compare local vs on-chain execution
• profile - Export trace as pprof profile for gas analysis
• session - Save debugging session for later