Skip to content

README.md

Latest commit

 

History

History
90 lines (77 loc) · 4.71 KB

README.md

File metadata and controls

90 lines (77 loc) · 4.71 KB
Raw

Simbolik: Stellar Debugger — example workspace

Audience: new user · stellar contract developer (getting started)

TL;DR: A guided tour of the ready-to-run example contracts and launch configs. Start with the zero-dependency Replay … with symbols configs to see source-level, forward-and-backward debugging in seconds — no toolchain needed — then graduate to the full build-and-run pipeline.

This folder is a self-contained example workspace for the Simbolik: Stellar Debugger (komet) extension. Pressing F5 ("Run Extension") in the extension repo opens this folder in an Extension Development Host with the extension already loaded, so you have a real Soroban project to debug immediately.

Contents

  • greeter/ — a contract whose entry point store(value) returns nothing (unit / Void). Uses instance storage.
  • adder/ — the simplest possible contract (add(a, b) -> u32, pure arithmetic).
  • increment/ — a stateful counter (increment(by) -> u32, uses instance storage).
  • stepper/ — sum_triples(n): a real #[inline(never)] call inside a while loop, for exercising step-in / step-over across a call and per-iteration stops.
  • control/ — one entry point per Rust construct (seq, branch if/else, count for, while_call while+call, choose match). It is the fixture behind the systematic stepping suite (test/control*Stepping.test.ts); the debugger builds it at opt-level=0 so every statement keeps its own line (higher optimization collapses a whole function onto one line — see ../docs/stepping.md).
  • traces/add.trace.jsonl — a captured komet-node execution trace for add, so the debugger works with no toolchain and no komet-node. It is the same real trace as ../test/fixtures/adder-debug.trace.jsonl; paired with ../test/fixtures/adder-debug.wasm (a debug build of adder/) it also demonstrates full Rust source mapping offline.

Each contract is an independent crate (its own Cargo.toml/Cargo.lock/ target/), which is what a deploy step's contract field expects.

Try it

Open the Run and Debug view and pick a config from .vscode/launch.json:

  1. Stellar: Replay add(4, 3) with symbols — zero dependencies. Replays the bundled trace together with its matching debug wasm: stack frames open adder/src/lib.rs, breakpoints verify on Rust lines (sliding forward to the nearest executed line), stepping is statement-granular, and right-clicking the stack frame offers Open Disassembly View (annotated wasm, instruction breakpoints, instruction-granular stepping — also backwards). Start here.
  2. Stellar: Replay add(4, 3) trace — the same trace without the wasm: the no-DWARF fallback. Frames carry only an instruction pointer; you debug in the Disassembly View.
  3. Stellar: Replay control while_call(3) / count(3) / branch(3) with symbols — zero-dependency replays of the control fixtures, one per Rust construct: step into bump and back out of a while loop, watch a for body stop once per iteration, or see an if/else enter only the taken arm.
  4. Stellar: Debug store(42) / add(1, 2) / increment(5) / control while_call(3) — the full turnkey pipeline: builds the crate with DWARF debug info at opt-level 0 (the extension injects CARGO_PROFILE_RELEASE_DEBUG=true / CARGO_PROFILE_RELEASE_STRIP=none / CARGO_PROFILE_RELEASE_OPT_LEVEL=0; no Cargo.toml changes needed — opt-level 0 is what keeps per-statement source stepping working), spawns komet-node, deploys, invokes, and replays the resulting trace with Rust source mapping. Requires the toolchain (Rust + wasm target, Stellar CLI, komet-node), all present in the devcontainer. Set "debugInfo": false on a deploy step to opt out of the debug build (you then debug that contract at the wasm level only).

Note: komet-node's tracer stops at instructions it cannot decode (it reports them as unknown, e.g. if), so a trace can end before the invocation does — depending on codegen, some contracts replay only partially.

Adding your own contract

Drop a new crate directory here (with a Cargo.toml exposing a #[contract]), then add a launch config whose transactions deploy it and invoke a function:

{
  "type": "stellar",
  "request": "launch",
  "name": "Stellar: Debug my_fn",
  "transactions": [
    { "kind": "deploy", "id": "mine", "contract": "${workspaceFolder}/my_crate" },
    { "kind": "invoke", "contract": "mine", "function": "my_fn", "args": { "x": 1 } }
  ]
}

See ../docs/debug-config.md for the full configuration reference (multi-contract systems, composite argument types, trace selection, and offline replay).