Leader Stream

A Rust/Axum service plus WASM client that serves a live view of upcoming Solana slot leaders and their TPU endpoints, with REST + SSE APIs.

Project layout

• leader-stream/src/main.rs – Axum server, APIs, SSE.
• leader-stream/src/lib.rs, leader-stream/src/wasm_app.rs – WASM client logic.
• leader-stream/public/ – static assets (CSS, og images, bundled WASM/JS, docs).
• k8s/ – Kubernetes manifests (ingress, deployment, config/secret generators).

Getting started

cd leader-stream
cargo run        # dev server at http://localhost:3000

Build WASM assets manually

cd leader-stream
rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown --lib
wasm-bindgen --target no-modules --out-name app --out-dir ./public ./target/wasm32-unknown-unknown/release/leader_stream.wasm
ensure wasm_bindgen loader is appended once
if ! grep -q 'wasmbindgen("/appbg.wasm");' ./public/app.js; then
  printf '\nwasmbindgen("/appbg.wasm");\n' >> ./public/app.js
fi

Alternatively, use the Dockerfile or make wasm (recreates public/app.js & app_bg.wasm).

Run via Docker

docker build -t leader-stream .
docker run -p 3000:3000 --env-file .env leader-stream

Environment variables

| Name | Purpose | Default | | --- | --- | --- | | SOLANARPCURL | Solana JSON-RPC endpoint | https://api.mainnet-beta.solana.com | | SOLANAWSURL / SOLANAWSSURL | Websocket RPC endpoint; inferred from RPC if unset | derived from RPC | | SOLANARPCX_TOKEN | Optional x-token header for RPC | none | | SOLANAWSX_TOKEN | Optional x-token for WS; falls back to RPC token | none | | PORT | HTTP listen port | 3000 | | RPCTIMEOUTMS | RPC timeout | 10000 | | NODECACHETTL_MS | Cache TTL for node list | 5000 | | SSEHEARTBEATMS | SSE heartbeat | 15000 | | WSPINGMS / GRPCPINGMS | WS ping interval | 15000 | | LEADER_LOOKAHEAD | Slots to prefetch | 5000 | | TRACK_LOOKAHEAD | Slots to prefetch per tracked validator | 5000 | | STATIC_DIR | Override static dir | <repo>/leader-stream/public | | NEXTPUBLICLEADERSTREAMURL | Override SSE path injected into HTML | /api/leader-stream | | MAXMINDDBPATH | Path to the MaxMind MMDB file to use for geolocation | ./GeoLite2-City.mmdb | | MAXMINDLICENSEKEY | Optional MaxMind license key for downloading GeoLite/GeoIP2 | none | | MAXMINDDBDOWNLOAD_URL | Override URL for downloading the MMDB (expects raw file or tar.gz) | none | | MAXMINDFALLBACKURL | Fallback URL for a free/test MaxMind database when no key is present | MaxMind test DB | | MAXMINDEDITIONID | Edition ID when downloading via license key | GeoLite2-City |

See .env.example and k8s/secret.env.example for templates.

API docs

Static docs at /docs.html (source: leader-stream/public/docs.html). Key endpoints:

• GET /api/next-leaders?limit=1000
• GET /api/current-slot
• GET /api/leader-stream?track=<validator> (SSE)
• GET /map globe view of upcoming leaders with geolocation (uses /api/leader-path)

Deployment (Kubernetes)

k8s/ uses Kustomize. Replace image ghcr.io/trustless-engineering/leader-stream:${GIT_SHA} and supply your own overlays/secrets:

cp k8s/secret.env.example k8s/secret.env
kubectl kustomize k8s | kubectl apply -f -

Ingress manifests include example domains (areweslotyet.xyz); adjust hosts/secret names as needed.

Frontend assets

leader-stream/public built artifacts (app.js, app_bg.wasm, *.d.ts, styles.css) are generated and not tracked. CI/Docker rebuilds them; run make wasm locally if you need fresh assets.

Contribution

• Rust: rustfmt defaults.
• CSS: 4-space indent, kebab-case classes.
• Tests: cargo test (from leader-stream/) for API smoke tests.
• Manual validation: load /, call /api/next-leaders, /api/current-slot, and stream /api/leader-stream.

License

AGPL-3.0 except if your name is Mert or you are affiliated with Helius Blockchain Technologies, in which case you can kick rocks.