Skip to content

Commit c0bd64f

Browse files
RaoulSchaffranekclaude
RaoulSchaffranek
and
claude
committed
docs: rewrite README with quick start, usage, and dev guide
Restructure the README around installation paths (kup/Docker/dev container), a curl-based RPC walkthrough, a contract lifecycle demo, and a developer guide with make targets and documentation links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 2a25a2c commit c0bd64f

1 file changed

Lines changed: 177 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 177 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,190 @@
1-
# komet-node
21

2+
<div align="center">
33

4-
## Installation
4+
# 🌠 Komet Node
55

6-
Prerequsites: `python >= 3.10`, [`uv`](https://docs.astral.sh/uv/).
6+
**A local Stellar testnet node based on [K formal semantics](https://github.com/runtimeverification/komet) of Soroban.**
7+
8+
[![Install](https://img.shields.io/badge/install-kup-blue)](https://kframework.org/install)
9+
[![Discord](https://img.shields.io/badge/discord-join-7289da)](https://discord.gg/CurfmXNtbN)
10+
11+
[Installation](#installation) • [Usage](#usage) • [Contribute](#for-developers)• [Community](#community)
12+
13+
</div>
14+
15+
---
16+
17+
## 🌟 Overview
18+
19+
`komet-node` is designed for Soroban developers who need advanced debugging capabilities. It extends the standard Stellar RPC with a `traceTransaction` method that provides instruction-level execution traces. The node's ledger state can be saved to and restored from a single file, enabling developers to reproduce exact network conditions and deterministically replay transactions.
20+
21+
## 🚀 Quick Start
22+
23+
### Installation
24+
25+
Pick the method that matches how you intend to use `komet-node`:
26+
27+
| You are a… | Use |
28+
|---|---|
29+
| User who wants the `komet-node` binary | [**kup**](#install-with-kup-recommended) (recommended) |
30+
| User who prefers containers | [**Docker**](#run-with-docker) |
31+
| Developer hacking on `komet-node` | [**Dev Container**](#develop-with-the-dev-container) |
32+
33+
#### Install with kup (recommended)
34+
35+
`komet-node` is distributed through [`kup`](https://github.com/runtimeverification/kup), Runtime Verification's Nix-based package manager. It pulls prebuilt binaries (including the matching K Framework and kompiled semantics) from RV's binary cache, so there is nothing to compile.
36+
37+
```bash
38+
# 1. Install the kup package manager (one time)
39+
bash <(curl https://kframework.org/install)
40+
41+
# 2. Install komet-node
42+
kup install komet-node
43+
44+
# 3. Verify the installation
45+
komet-node --help
46+
```
47+
48+
To upgrade later, run `kup update komet-node`.
49+
50+
#### Run with Docker
51+
52+
A prebuilt image is published to Docker Hub for each release. It bundles K, the kompiled semantics, and `komet-node` ready to serve.
53+
54+
```bash
55+
# Pull the image (replace the tag with the release you want)
56+
docker pull runtimeverificationinc/komet-node:ubuntu-jammy-0.1.0
57+
58+
# Start the server, exposing the RPC port on the host
59+
docker run --rm -p 8000:8000 \
60+
runtimeverificationinc/komet-node:ubuntu-jammy-0.1.0 \
61+
komet-node --host 0.0.0.0 --port 8000
62+
```
63+
64+
> The server binds to `localhost` by default; pass `--host 0.0.0.0` inside the container so the port is reachable from the host.
65+
66+
---
67+
68+
### Usage
69+
70+
#### Start the server
71+
72+
```bash
73+
komet-node # serve on localhost:8000, state in ./state.kore
74+
komet-node --help # print general usage information
75+
komet-node --port 9000 # custom port
76+
komet-node --trace # enable instruction-level execution tracing
77+
```
78+
79+
| Flag | Default | Description |
80+
|---|---|---|
81+
| `--host` | `localhost` | Bind address |
82+
| `--port` | `8000` | Port to listen on |
83+
| `--state-file` | `state.kore` | Path to the persistent state file |
84+
| `--trace` | off | Enable instruction-level execution tracing |
85+
86+
On first start the server creates an empty `state.kore`. Delete that file to reset the chain, or point `--state-file` at a pre-built configuration to resume from a snapshot.
87+
88+
#### Verify the server with `curl`
89+
90+
The server is operated via the Stellar RPC protocol. The read-only methods below take no transaction payload, which makes them perfect for a quick health check:
91+
92+
```bash
93+
# Is the server alive?
94+
curl -s http://localhost:8000 \
95+
-H 'Content-Type: application/json' \
96+
-d '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":{}}'
97+
# => {"jsonrpc":"2.0","id":1,"result":{"status":"healthy"}}
98+
```
99+
100+
```bash
101+
# Which network am I connected to?
102+
curl -s http://localhost:8000 \
103+
-H 'Content-Type: application/json' \
104+
-d '{"jsonrpc":"2.0","id":1,"method":"getNetwork","params":{}}'
105+
# => {"jsonrpc":"2.0","id":1,"result":{"passphrase":"Test SDF Network ; September 2015","protocolVersion":"22","friendbotUrl":null}}
106+
```
107+
108+
```bash
109+
# What is the current ledger sequence? (increments per committed transaction)
110+
curl -s http://localhost:8000 \
111+
-H 'Content-Type: application/json' \
112+
-d '{"jsonrpc":"2.0","id":1,"method":"getLatestLedger","params":{}}'
113+
# => {"jsonrpc":"2.0","id":1,"result":{"id":"00...00","protocolVersion":"22","sequence":0}}
114+
```
115+
116+
Submitting transactions uses the standard two-step Stellar pattern — `sendTransaction` with a base64 XDR envelope, then poll `getTransaction` by hash:
117+
118+
```bash
119+
# Submit a signed transaction (XDR envelope produced by a Stellar SDK)
120+
curl -s http://localhost:8000 \
121+
-H 'Content-Type: application/json' \
122+
-d '{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":{"transaction":"<base64-XDR-envelope>"}}'
123+
# => {... "result":{"hash":"<64-char hex>","status":"PENDING", ...}}
124+
125+
# Poll for the result using the returned hash
126+
curl -s http://localhost:8000 \
127+
-H 'Content-Type: application/json' \
128+
-d '{"jsonrpc":"2.0","id":1,"method":"getTransaction","params":{"hash":"<64-char hex>"}}'
129+
# => {... "result":{"status":"SUCCESS","ledger":"1", ...}}
130+
```
131+
132+
Because there is no mempool, `komet-node` executes the transaction synchronously inside `sendTransaction`; the result is already available by the time you poll. See [docs/server.md](docs/server.md) for the full RPC reference, including the `traceTransaction` method.
133+
134+
#### Walk through a contract lifecycle
135+
136+
The bundled demo deploys and invokes a Soroban contract end-to-end (create account → upload wasm → deploy → invoke):
137+
138+
```bash
139+
uv run python -m komet_node.demo src/tests/integration/data/wasm/empty.wat
140+
```
141+
142+
This produces `state.kore` plus `state_<n>_<step>.pretty` files under `./out`, letting you inspect exactly how the formal state evolves. (Requires `wat2wasm` from [`wabt`](https://github.com/WebAssembly/wabt) on your `PATH`.)
143+
144+
---
145+
146+
## For Developers
147+
148+
Prerequisites: `python >= 3.10`, [`uv`](https://docs.astral.sh/uv/), [`wabt`](https://github.com/WebAssembly/wabt) (for `wat2wasm`), and the K Framework. The [Dev Container](#develop-with-the-dev-container) provisions all of these for you.
149+
150+
1. Install [VS Code](https://code.visualstudio.com/) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
151+
2. Open this repository in VS Code and choose **Reopen in Container** when prompted.
152+
3. Once the container finishes building, build the semantics and run the test suite:
153+
154+
```bash
155+
make kdist-build # compile the K semantics (first run only; takes a while)
156+
make test-unit # quick sanity check
157+
```
158+
159+
Common tasks are driven by `make` (see the [Makefile](Makefile) for the complete list):
160+
161+
| Target | Description |
162+
|---|---|
163+
| `make kdist-build` | Compile the K semantics (required before running integration tests) |
164+
| `make build` | Build the wheel |
165+
| `make test-unit` | Run unit tests |
166+
| `make test-integration` | Run integration tests |
167+
| `make test` | Run the full test suite |
168+
| `make cov` | Run tests with a coverage report |
169+
| `make check` | Run all style/type checks (flake8, mypy, autoflake, isort, black) |
170+
| `make format` | Auto-format the codebase |
171+
172+
To build the node from source use:
7173

8174
```bash
9175
make build
10176
pip install dist/*.whl
11177
```
12178

179+
### Documentation
13180

14-
## For Developers
181+
- [Architecture overview](docs/architecture.md) — how the pieces fit together
182+
- [Server](docs/server.md) — the RPC layer, state lifecycle, and full method reference
183+
- [Interpreter](docs/interpreter.md) — transaction → K step translation
184+
- [K semantics](docs/node-semantics.md) — the on-chain execution model
15185

16-
Use `make` to run common tasks (see the [Makefile](Makefile) for a complete list of available targets).
186+
---
17187

18-
* `make build`: Build wheel
19-
* `make check`: Check code style
20-
* `make format`: Format code
21-
* `make test-unit`: Run unit tests
22-
* `make test-integration`: Run integration tests
188+
## About
23189

190+
`komet-node` is developed by [Runtime Verification](https://runtimeverification.com/). It builds on [Komet](https://github.com/runtimeverification/komet), the K semantics of Soroban smart contracts, and the [K Framework](https://github.com/runtimeverification/k).

0 commit comments

Comments
 (0)