Skip to content

Commit 25ff1fb

Browse files
RaoulSchaffranekRaoulSchaffranek
committed
Add example workspace and make the turnkey pipeline work against a live komet-node
Examples: - Add a self-contained examples/ workspace (adder, increment, greeter, plus a captured add trace) and point the "Run Extension" F5 config at it, so the Extension Development Host opens a real Soroban project to debug. - greeter/store demonstrates the live build -> deploy -> invoke -> replay pipeline; the raw-trace config replays with no toolchain or node. komet-node integration: - Align KometClient to the real node API: fetch the JSONL trace by hash via traceTransaction, and read SUCCESS/FAILED from getTransaction. - KometProcess spawns the node detached (its own process group) and kills the whole group on stop, so the K interpreter child is never orphaned holding the port; spawn without a shell so signals reach the node directly. - Surface the invocation failure reason (tx hash + hint) instead of a bare "status FAILED". - Drop the venv/kdist install script; the devcontainer now installs the node with `kup install komet-node`. Configurable binaries: - Add soroban.kometNode.path and soroban.stellar.path settings (default to the binaries on $PATH; a launch config's node.command / buildCommand still wins). - examples/.vscode/settings.json points at the locally rebuilt komet-node until the fixed build lands on the nix cache.
1 parent 7c7d24d commit 25ff1fb

28 files changed

Lines changed: 5563 additions & 205 deletions

‎.devcontainer/Dockerfile‎

Lines changed: 8 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,12 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
5353
| sh -s -- -y --profile minimal \
5454
&& /home/node/.cargo/bin/rustup target add wasm32v1-none wasm32-unknown-unknown
5555

56-
# --- uv (Python package manager for komet-node) ----------------------------
57-
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
58-
59-
# --- Nix + kup + komet semantics -------------------------------------------
60-
# komet-node executes contracts via the K-based `komet` semantics. We install
61-
# the K toolchain through Runtime Verification's `kup` (Nix-based), pulling
62-
# prebuilt binaries from RV's binary cache rather than compiling from source.
56+
# --- Nix + kup + komet-node ------------------------------------------------
57+
# komet-node executes contracts via the K-based `komet` semantics. Both the
58+
# node and its semantics are now published to RV's binary cache, so we install
59+
# the whole thing with a single `kup install komet-node` — pulling prebuilt
60+
# binaries instead of compiling the semantics from source (the old approach
61+
# required uv + a Python venv + a multi-minute `kdist build`).
6362
ENV NIX_CONFIG="experimental-features = nix-command flakes"
6463
RUN curl -L https://nixos.org/nix/install | sh -s -- --no-daemon --yes
6564
ENV PATH="/home/node/.nix-profile/bin:/home/node/.local/bin:/home/node/.cargo/bin:${PATH}"
@@ -74,11 +73,5 @@ RUN sudo mkdir -p /etc/nix \
7473
'extra-trusted-public-keys = k-framework.cachix.org-1:jeyMXB2h28gpNRjuVkehg+zLj62ma1RnyyopA/20yFE= k-framework-binary.cachix.org-1:pJedQ8iG19BW3v/DMMmiRVtwRBGO3fyMv2Ws0OpBADs=' \
7574
| sudo tee -a /etc/nix/nix.conf
7675
RUN curl -L https://kframework.org/install | bash \
77-
&& kup install komet
78-
79-
# --- komet-node (local Stellar testnet on K semantics) ---------------------
80-
# Installed into a dedicated venv; exposes `python -m komet_node`.
81-
# (Finalized after live verification — see scripts/install-komet-node.sh.)
82-
ENV KOMET_NODE_VENV=/home/node/.komet-node
83-
COPY --chown=node:node install-komet-node.sh /tmp/install-komet-node.sh
84-
RUN bash /tmp/install-komet-node.sh
76+
&& kup install komet-node \
77+
&& komet-node --help >/dev/null

‎.devcontainer/install-komet-node.sh‎

Lines changed: 0 additions & 75 deletions
This file was deleted.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ out/
77
state.kore
88
.claude/
99
test/fixtures/sample-contract/target/
10+
examples/*/target/

‎.vscode/launch.json‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,10 @@
77
"request": "launch",
88
"args": [
99
"--extensionDevelopmentPath=${workspaceFolder}",
10-
"${workspaceFolder}"
10+
"${workspaceFolder}/examples"
1111
],
1212
"outFiles": ["${workspaceFolder}/dist/**/*.js"],
1313
"preLaunchTask": "${defaultBuildTask}"
14-
},
15-
{
16-
"name": "Soroban: Replay sample trace",
17-
"type": "soroban",
18-
"request": "launch",
19-
"rawTrace": "${workspaceFolder}/test/fixtures/add.trace.jsonl",
20-
"function": "add"
2114
}
2215
]
2316
}

‎README.md‎

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,9 @@ The replay logic and pipeline are exercised by 38 tests (`npm test`):
5050
## Devcontainer toolchain
5151

5252
The devcontainer installs everything needed to run the pipeline end to end:
53-
Rust + the wasm targets, the Stellar CLI, `uv`, and the K toolchain (`komet`)
54-
plus `komet-node` (via Nix/`kup`). See `.devcontainer/Dockerfile` and
55-
`.devcontainer/install-komet-node.sh`.
53+
Rust + the wasm targets, the Stellar CLI, and `komet-node` (installed straight
54+
from RV's binary cache with `kup install komet-node`, which also pulls the K
55+
toolchain and the prebuilt semantics). See `.devcontainer/Dockerfile`.
5656

5757
## Architecture
5858

@@ -89,21 +89,17 @@ npm run lint
8989
```
9090

9191
Press **F5** (Run Extension) to open an Extension Development Host with the
92-
extension loaded. Then use a launch configuration like:
93-
94-
```jsonc
95-
{
96-
"type": "soroban",
97-
"request": "launch",
98-
"name": "Replay a captured trace",
99-
"rawTrace": "${workspaceFolder}/test/fixtures/add.trace.jsonl",
100-
"function": "add"
101-
}
102-
```
92+
extension loaded. It opens the [`examples/`](examples/) workspace — a
93+
self-contained Soroban project with two contracts (`adder`, `increment`) and a
94+
captured trace — so there is something real to debug immediately.
95+
96+
Pick a config from the Run and Debug view. Start with **Soroban: Replay
97+
add(4, 3) trace**, which replays the bundled trace so you can step
98+
forward/backward, set breakpoints on instructions, and inspect the stack/locals
99+
— end to end, with no komet-node required. The **Debug add(1, 2)** and **Debug
100+
increment(5)** configs exercise the full build → deploy → trace pipeline.
103101

104-
This replays the bundled sample trace so you can step forward/backward, set
105-
breakpoints on instructions, and inspect the stack/locals — end to end, with no
106-
komet-node required.
102+
See [`examples/README.md`](examples/README.md) for details.
107103

108104
## Roadmap
109105

‎examples/.vscode/launch.json‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "Soroban: Replay add(4, 3) trace",
6+
"type": "soroban",
7+
"request": "launch",
8+
"rawTrace": "${workspaceFolder}/traces/add.trace.jsonl",
9+
"function": "add"
10+
},
11+
{
12+
"name": "Soroban: Debug store(42) [live pipeline]",
13+
"type": "soroban",
14+
"request": "launch",
15+
"contract": "${workspaceFolder}/greeter",
16+
"function": "store",
17+
"args": [
18+
{ "value": 42, "type": "u32" }
19+
]
20+
},
21+
{
22+
"name": "Soroban: Debug add(1, 2) [live pipeline]",
23+
"type": "soroban",
24+
"request": "launch",
25+
"contract": "${workspaceFolder}/adder",
26+
"function": "add",
27+
"args": [
28+
{ "value": 1, "type": "u32" },
29+
{ "value": 2, "type": "u32" }
30+
]
31+
},
32+
{
33+
"name": "Soroban: Debug increment(5) [live pipeline]",
34+
"type": "soroban",
35+
"request": "launch",
36+
"contract": "${workspaceFolder}/increment",
37+
"function": "increment",
38+
"args": [
39+
{ "value": 5, "type": "u32" }
40+
]
41+
}
42+
]
43+
}

‎examples/.vscode/settings.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
// The nix-cached `komet-node` on $PATH in this devcontainer predates the fix
3+
// for value-returning contract calls (it hardcoded a Void result and got stuck
4+
// on any function returning a value). The fixed build lives in the uv venv, so
5+
// point the extension at it here. Remove this once the nix cache ships the fix
6+
// and plain `komet-node` on $PATH is current.
7+
"soroban.kometNode.path": "/home/node/.komet-node/bin/komet-node"
8+
}

‎examples/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Soroban Debugger — example workspace
2+
3+
This folder is a **self-contained example workspace** for the Soroban Debugger
4+
(komet) extension. Pressing **F5** ("Run Extension") in the extension repo opens
5+
this folder in an Extension Development Host with the extension already loaded,
6+
so you have a real Soroban project to debug immediately.
7+
8+
## Contents
9+
10+
- `greeter/` — a contract whose entry point `store(value)` returns **nothing**
11+
(unit / `Void`). Uses instance storage.
12+
- `adder/` — the simplest possible contract (`add(a, b) -> u32`, pure arithmetic).
13+
- `increment/` — a stateful counter (`increment(by) -> u32`, uses instance storage).
14+
- `traces/add.trace.jsonl` — a captured `komet-node` execution trace for `add`,
15+
so the debugger works with **no toolchain and no komet-node**.
16+
17+
Each contract is an independent crate (its own `Cargo.toml`/`Cargo.lock`/
18+
`target/`), which is what the extension's `contract` launch attribute expects.
19+
20+
## Try it
21+
22+
Open the Run and Debug view and pick a config from `.vscode/launch.json`:
23+
24+
1. **Soroban: Replay add(4, 3) trace** — zero dependencies. Replays the bundled
25+
trace so you can step forward/backward, set breakpoints, and inspect the
26+
stack/locals. Start here.
27+
2. **Soroban: Debug store(42) / add(1, 2) / increment(5)** — the full turnkey
28+
pipeline: builds the crate, spawns komet-node, deploys, invokes, and replays
29+
the resulting trace. Requires the toolchain (Rust + wasm target, Stellar CLI,
30+
komet-node), all present in the devcontainer.
31+
32+
## komet-node version note
33+
34+
Earlier versions of komet-node reported a `FAILED` transaction for any contract
35+
call that **returns a value** (its `callTx` handling asserted a `Void` result, so
36+
functions like `add`/`increment` got stuck; only no-return functions like
37+
`greeter::store` completed). This is fixed in komet-node — `callTx` now uses
38+
`uncheckedCallTx`, which does not assert the return value.
39+
40+
The fix isn't on the nix binary cache yet, so the `komet-node` on `$PATH` in this
41+
devcontainer is still the older build. `.vscode/settings.json` therefore points
42+
the extension at the rebuilt node via:
43+
44+
```json
45+
{ "soroban.kometNode.path": "/home/node/.komet-node/bin/komet-node" }
46+
```
47+
48+
Once the nix cache ships the fix, delete that setting and the extension will use
49+
`komet-node` from `$PATH`. (The `soroban.stellar.path` setting works the same way
50+
for the Stellar CLI.)
51+
52+
## Adding your own contract
53+
54+
Drop a new crate directory here (with a `Cargo.toml` exposing a `#[contract]`),
55+
then add a launch config pointing `contract` at it and naming the `function`.

0 commit comments

Comments
 (0)