leanQuickstart

leanQuickstart — operational runbook for the local multi-client devnet

lean-quickstart (github.com/blockblaz/lean-quickstart) is "a utility to quickly spin up a localnet of lean (multi-client) nodes". It is tooling, not a spec or a library: Shell scripts orchestrate genesis generation, per-client launch commands, and an optional Prometheus/Grafana metrics stack, driven by a single validator-config.yaml. Multiple different client implementations (Zeam, Ream, Lighthouse, …) run against one shared genesis so you can test interop on a single local chain.

0. Core principle

• This skill grounds how to run the devnet — flags, config, genesis, metrics — not protocol semantics. The chain behaviour is leanSpec's domain; this is the harness that starts nodes.
• The authoritative source for how to run it is the upstream README.md + the scripts at main. They change (the repo is actively developed). Do not quote flags or filenames from memory or from a stale local clone — read main and cite the SHA.
• "Run the devnet" = edit validator-config.yaml, then invoke spin-node.sh. Everything else (genesis, per-client commands, metrics) is wired from that config.

1. Always read lean-quickstart from the remote main (no local path assumptions)

The tooling evolves. Read the latest main of the canonical upstream directly from the remote — this works for every developer and in CI, with no dependency on a local clone.

Repo: github.com/blockblaz/lean-quickstart (canonical; default branch main. Do not use a personal fork.).

# Latest main commit — cite this SHA in your output:
gh api repos/blockblaz/lean-quickstart/commits/main --jq '.sha'

# Read the README (the authoritative quick-start) at main:
gh api "repos/blockblaz/lean-quickstart/contents/README.md?ref=main" --jq '.content' | base64 -d
# raw fallback (no gh):
curl -s https://raw.githubusercontent.com/blockblaz/lean-quickstart/main/README.md

# Read a specific script (e.g. the entry point) at main:
curl -s https://raw.githubusercontent.com/blockblaz/lean-quickstart/main/spin-node.sh

# Full tree at main:
gh api "repos/blockblaz/lean-quickstart/git/trees/main?recursive=1" --jq '.tree[].path'

No gh/curl? Use WebFetch on https://github.com/blockblaz/lean-quickstart/blob/main/<path>.

If you happen to have a local clone, you may use it for fast navigation/grep — but git fetch origin first and read origin/main (clones drift onto feature branches and forks). Never assume a specific clone path.

2. Quick start (the canonical command)

NETWORK_DIR=local-devnet ./spin-node.sh --node all --generateGenesis --popupTerminal

• --node all — launch every node defined in the config; --node <name> launches a single node by name.
• --generateGenesis — (re)generate genesis state, validator keys, and config from validator-config.yaml before starting (PQ hash-sig keys via ethpandaops/eth-beacon-genesis).
• --popupTerminal — open each node's logs in its own terminal window.
• NETWORK_DIR selects the network directory (local-devnet for local; ansible-devnet for the remote/Ansible flow).

The authoritative, current flag set lives in spin-node.sh --help and the README at main — confirm there before relying on any flag, as options change.

3. Topic → authoritative location map

Paths are relative to the lean-quickstart repo root, read at main.

4. How to use (running / configuring / answering)

1. Read the README and spin-node.sh --help at main first — never quote flags from memory.
2. Edit validator-config.yaml (the single source of truth) to define which nodes, which client implementations, and how many validators each.
3. Run spin-node.sh with the appropriate --node / --generateGenesis flags; bring up metrics/docker-compose-metrics.yaml if you want the Prometheus/Grafana stack.
4. In your output, cite the file/script + the main commit SHA you checked.

5. Relationship to leanSpec, leanVM, leanMetrics & Verity

• leanSpec (separate skill) = consensus protocol & container shapes (the chain rules).
• leanVM (separate skill) = aggregation + zkVM proof internals.
• leanMetrics (separate skill) = the observability metric contract (names/types/ buckets/labels). This skill only covers running the bundled Prometheus/Grafana stack, not what the metrics are.
• leanQuickstart (this skill) = the harness that boots and runs a local multi-client devnet.
• Verity is pre-implementation, so it is not yet a node in validator-config.yaml.