Debugging

Debug and trace tools for transaction analysis on the chain.

Quick Start

# Trace a transaction (tree view)
ashen debug trace 0xabc123...

# Interactive replay
ashen debug replay 0xabc123... --step

# Gas analysis
ashen debug gas 0xabc123...

Commands

ashen debug trace

Trace an already-included transaction and display the call tree.

ashen debug trace <TX_HASH> [OPTIONS]

Options:
  --max-depth <N>      Maximum call depth (default: 8)
  --format <FORMAT>    Output: "tree" (default), "json", "chrome"
  -o, --output <PATH>  Write to file instead of stdout
  --rpc-url <URL>      RPC endpoint (env: NODE_RPC_URL)

Examples:

# Human-readable tree
ashen debug trace 0xabc123

# Full JSON (for programmatic use)
ashen debug trace 0xabc123 --format json -o trace.json

# Chrome Trace Format (open in chrome://tracing)
ashen debug trace 0xabc123 --format chrome -o trace.json

Tree output:

Transaction: 0xabc123...
Block: 42

call 0x1234...5678 -> 0xabcd...ef01 (gas: 45000/100000)
  input: 0xa9059cbb000000000000000000000000...
  storage.write: 0xbalance:alice (gas: 5000)
  storage.write: 0xbalance:bob (gas: 5000)
  event: 0xabcd...ef01 topics=3
  call 0xabcd...ef01 -> 0x9876...5432 (gas: 12000/50000)
    storage.read: 0xallowance (gas: 2100)

ashen debug trace-call

Trace a read-only view call without submitting a transaction.

ashen debug trace-call <CONTRACT> <CALLDATA> [OPTIONS]

Options:
  --origin <ADDRESS>   Caller address (defaults to zero)
  --gas-limit <N>      Gas limit (default: 1000000)
  --value <N>          Attached value (default: 0)
  --format <FORMAT>    Output: "tree", "json", "chrome"
  -o, --output <PATH>  Write to file

Example:

ashen debug trace-call 0xcontract 0x70a08231000000000000000000000000abcdef

ashen debug replay

Step through a transaction interactively, inspecting state at each operation.

ashen debug replay <TX_HASH> [OPTIONS]

Options:
  --step                Single-step mode (pause after each operation)
  -b, --breakpoint <BP> Set breakpoint(s), repeatable
  --rpc-url <URL>       RPC endpoint

Breakpoint formats:

Format	Description	Example
step:N	Break at operation N	--breakpoint step:5
storage:KEY	Break on storage op matching KEY	--breakpoint storage:balance
gas:N	Break when gas exceeds N	--breakpoint gas:50000

Interactive commands:

Key	Action
Enter / n	Step to next operation
s<N>	Seek to step N (e.g., s5)
r	Run to next breakpoint (or end)
i	Inspect current operation (full JSON)
b<spec>	Add breakpoint (e.g., bstep:10)
q	Quit

Example session:

$ ashen debug replay 0xabc123 --step
Replaying 0xabc123 (6 operations, block 42)
Commands: [enter]=step, [n]=next, [s]=seek N, [b]=add breakpoint, [r]=run, [i]=inspect, [q]=quit

[  0] call 0x1234... -> 0xabcd... (gas: 45000)
        storage.write balance:alice
(step 0/5) >
[  1] call 0xabcd... -> 0x9876... (gas: 12000)
(step 1/5) > i
{
  "step": 1,
  "depth": 1,
  "op_type": "call",
  "from": "0xabcd...",
  "to": "0x9876...",
  "gas_used": 12000
}
(step 1/5) > r
[  5] call 0x1234... -> 0xabcd... (gas: 45000)
  End of trace.

ashen debug gas

Show gas breakdown for a transaction.

ashen debug gas <TX_HASH> [OPTIONS]

Options:
  --rpc-url <URL>  RPC endpoint

Output:

Gas Analysis: 0xabc123...
Block: 42
-----------------------------------
Total gas used: 45000
Gas limit:      100000
Utilization:    45.0%

Storage operations (3):
  write 0xbalance:ali... (gas: 5000)
  write 0xbalance:bob... (gas: 5000)
  read 0xallowance... (gas: 2100)
  Total storage gas: 12100

Child calls (1):
  call 0x1234...5678 -> 0x9876...5432 (gas: 12000, OK)

Workflows

Debug a Failed Transaction

# 1. Check the transaction status
ashen tx by-hash --tx-hash 0xfailed... --wait

# 2. Get the full trace to see where it failed
ashen debug trace 0xfailed...

# 3. Inspect storage operations step by step
ashen debug replay 0xfailed... --step

# 4. Check gas usage
ashen debug gas 0xfailed...

Gas Optimization

# 1. Get gas breakdown
ashen debug gas 0xtx...

# 2. Export full trace for analysis
ashen debug trace 0xtx... --format json -o trace.json

# 3. Open in Chrome for visual inspection
ashen debug trace 0xtx... --format chrome -o chrome-trace.json
# Then open chrome://tracing and load chrome-trace.json

Compare Two Executions

# Export both as JSON
ashen debug trace 0xtx_before... --format json -o before.json
ashen debug trace 0xtx_after... --format json -o after.json

# Diff with your preferred tool
diff before.json after.json
# or: jq for structured comparison

Chrome Trace Format

The --format chrome option exports traces in Chrome Trace Format, viewable in:

• chrome://tracing (Chrome/Chromium)
• Perfetto UI
• Speedscope

Each call frame becomes a duration event showing gas usage and call depth.

Environment Variables

Variable	Description	Default
NODE_RPC_URL	RPC endpoint URL	http://127.0.0.1:3030
NODE_AUTH_TOKEN	Bearer auth token	(none)

Programmatic Access (RPC)

The debug commands use these RPC methods directly:

RPC Method	CLI Command
NodeRpcV1.chain_traceTransaction	ashen debug trace
NodeRpcV1.chain_traceCall	ashen debug trace-call
NodeRpcV1.tx_simulate_trace	(simulation with trace)

Example: Direct RPC Call

curl -X POST http://localhost:3030/v2/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "method": "NodeRpcV1.chain_traceTransaction",
    "params": {
      "tx_hash": "0xabc123...",
      "max_depth": 8
    }
  }'

---

DAP Debugger (VS Code Integration)

The DAP (Debug Adapter Protocol) adapter enables interactive debugging of contract execution directly in VS Code or any DAP-compatible IDE.

Quick Start

# 1. Build the DAP adapter
cargo build -p dap-adapter

# 2. Build your contract with debug symbols
cd contracts/zig_fixture
zig build

# 3. Open VS Code and start debugging (F5)

Setup

1. Install the DAP Adapter

target/release/ashen-dap

cargo build -p dap-adapter --release

2. Configure VS Code

Create or update .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Contract",
            "type": "ashen-vm",
            "request": "launch",
            "program": "${workspaceFolder}/contracts/zig_fixture/zig-out/bin/zig_fixture",
            "sourceDir": "${workspaceFolder}/contracts/zig_fixture/src",
            "stopOnEntry": true,
            "trace": true
        }
    ]
}

3. Configure the Debug Extension

In VS Code settings, point to the adapter binary:

{
    "ashen-vm.adapterPath": "${workspaceFolder}/target/release/ashen-dap"
}

Supported Features

Feature	Description
Breakpoints	Set breakpoints on source lines
Step Over (F10)	Execute next operation
Step Into (F11)	Step into function calls
Step Out	Step out of current function
Step Back	Time-travel to previous operation
Variables	Inspect registers, memory, storage
Stack Trace	View call stack
Continue (F5)	Run to next breakpoint
Pause	Pause execution

Launch Configuration Options

Option	Type	Description
program	string	Path to contract ELF binary
sourceDir	string	Path to source directory for mapping
stopOnEntry	boolean	Pause at contract entry point
trace	boolean	Enable execution trace recording
mode	string	"launch" or "replay"
txHash	string	Transaction hash (replay mode only)
rpcUrl	string	RPC endpoint (replay mode only)

Debug Session Example

1. Set breakpoint at line 28 in main.zig (click gutter)
2. Press F5 to start debugging
3. Execution pauses at entry (stopOnEntry: true)
4. Press F5 to continue to breakpoint
5. Use Variables panel to inspect state:
   - Registers: pc, sp, a0-a7
   - Memory: heap, stack contents
   - Storage: contract storage slots
6. Press F10 to step over
7. Press Shift+F10 to step back (time-travel)
8. Press F5 to continue or Shift+F5 to stop

Debugging Modes

Launch Mode

Debug a contract from the start with specified calldata:

{
    "type": "ashen-vm",
    "request": "launch",
    "program": "path/to/contract.elf",
    "calldata": "0x4543484f48656c6c6f"
}

Replay Mode

Debug an already-executed transaction:

{
    "type": "ashen-vm",
    "request": "launch",
    "mode": "replay",
    "txHash": "0xabc123...",
    "rpcUrl": "http://127.0.0.1:3030"
}

Troubleshooting

Breakpoints show as unverified (gray)

• Contract must be built with debug symbols
• Source paths must match exactly
• Try rebuilding without optimization

“Session not initialized” error

• Check that ashen-dap binary is accessible
• Verify VS Code extension configuration

Step back doesn’t work

• Set trace: true in launch configuration
• Trace recording must be enabled for time-travel

Variables panel is empty

• Click on a stack frame first
• Expand the Registers/Memory/Storage scopes