feat: add nlean consensus client support by GrapeBaBa · Pull Request #137 · blockblaz/lean-quickstart

GrapeBaBa · 2026-03-18T11:27:05Z

Add nlean consensus client integration for lean-quickstart.

Changes

client-cmds/nlean-cmd.sh: Client-cmd contract script for nlean binary and Docker modes
- Supports all nlean CLI flags: validator-config, metrics, api-port, aggregator, checkpoint-sync, log-level
- Configurable via env vars: NLEAN_REPO, NLEAN_DOCKER_IMAGE, NLEAN_NETWORK_NAME, NLEAN_LOG_LEVEL, NLEAN_API_PORT, NLEAN_QUICKSTART_SETUP
- Docker debug env vars forwarded for attestation/block/proof dumping
local-devnet-nlean/genesis/validator-config.yaml: 4-node local devnet config
- Nodes: nlean_0 through nlean_3 with QUIC ports 9101-9104
- Metrics ports 18081-18084, API ports 5052-5055
- Hash-sig key type, activeEpoch 18, roundrobin shuffle

Tested

Binary mode: 4 nodes, finalization past epoch 18
Docker mode: 4 nodes, all in sync, finalization past epoch 29

Copilot

Pull request overview

Adds NLEAN-specific local devnet assets so spin-node.sh can launch an NLEAN-only topology using lean-quickstart’s client-cmd contract and a dedicated validator-config.

Changes:

Added local-devnet-nlean/genesis/validator-config.yaml defining a 4-node NLEAN local topology (ports, keys, aggregator selection).
Added client-cmds/nlean-cmd.sh implementing the lean-quickstart client command contract for running NLEAN via binary or Docker.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
local-devnet-nlean/genesis/validator-config.yaml	Introduces an NLEAN-only validator topology for local deployments.
client-cmds/nlean-cmd.sh	Adds NLEAN client runner wiring (binary/docker) compatible with `spin-node.sh`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ch4r10t33r · 2026-03-19T09:48:32Z

+validators:
+  - name: "nlean_0"
+    privkey: "2e9be3f1b0d32ca3a4d62017fbfafe3950b7e90fed6802ff8bd2e0f8c4e2ca91"
+    enrFields:
+      ip: "127.0.0.1"
+      quic: 9101
+    metricsPort: 18081
+    httpPort: 5052
+    count: 1


does nlean use both apiPort and httpPort? @GrapeBaBa

+
+# Set API port flag if explicitly configured
+api_port_flag=""
+nlean_api_port="${NLEAN_API_PORT:-${httpPort:-}}"


+enable_metrics="${enableMetrics:-false}"
+
+enable_metrics=$(echo "$enable_metrics" | tr '[:upper:]' '[:lower:]')
+if [[ "$enable_metrics" != "true" && "$enable_metrics" != "false" ]]; then
+  enable_metrics="false"
+fi
+


+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_ATTESTATIONS=${NLEAN_DEBUG_DUMP_ATTESTATIONS}"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_DIR:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_DIR=${NLEAN_DEBUG_DUMP_DIR}"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_BLOCKS:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_BLOCKS=${NLEAN_DEBUG_DUMP_BLOCKS}"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_BLOCK_DIR:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_BLOCK_DIR=${NLEAN_DEBUG_DUMP_BLOCK_DIR}"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_PROOFS:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_OBSERVED_PROOFS=${NLEAN_DEBUG_DUMP_OBSERVED_PROOFS}"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_PROOFS_DIR:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_OBSERVED_PROOFS_DIR=${NLEAN_DEBUG_DUMP_OBSERVED_PROOFS_DIR}"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS=${NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS}"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS_DIR:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS_DIR=${NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS_DIR}"


- Add apiPort to validator-config.yaml for leanpoint health-check URLs - Use apiPort instead of httpPort for --api-port flag in nlean-cmd.sh - Always enable client metrics endpoint (enableMetrics only controls external stack) - Use Docker -e VAR (inherit) instead of -e VAR=value to avoid colon-breaking issues

- Add apiPort to validator-config.yaml for leanpoint health-check URLs - Use apiPort instead of httpPort for --api-port flag in nlean-cmd.sh - Use Docker -e VAR (inherit) instead of -e VAR=value to avoid colon-breaking issues

Copilot

Pull request overview

Adds nlean consensus client integration to the lean-quickstart ecosystem, providing both a client-cmd contract script and a matching 4-node local devnet validator configuration.

Changes:

Added client-cmds/nlean-cmd.sh implementing the quickstart client-cmd contract for nlean (binary/docker), including support for aggregator, checkpoint sync, API port, metrics, and log-level configuration via env/flags.
Added local-devnet-nlean/genesis/validator-config.yaml defining a 4-node local nlean devnet topology (ports, metrics, API, hash-sig keys, active epoch).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
local-devnet-nlean/genesis/validator-config.yaml	New 4-node nlean local devnet validator config aligned to quickstart topology/ports.
client-cmds/nlean-cmd.sh	New nlean client-cmd contract script supporting binary/docker execution and quickstart-provided per-node settings.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+log_level="${log_level#${log_level%%[![:space:]]*}}"
+log_level="${log_level%${log_level##*[![:space:]]}}"
+log_level_arg=""
+if [[ -n "$log_level" ]]; then
+  log_level_arg="--log ${log_level}"
+fi


+
+# Set API port flag if explicitly configured
+api_port_flag=""
+nlean_api_port="${NLEAN_API_PORT:-${apiPort:-}}"


+if [[ -n "${NLEAN_DEBUG_DUMP_ATTESTATIONS:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_ATTESTATIONS"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_DIR:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_DIR"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_BLOCKS:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_BLOCKS"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_BLOCK_DIR:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_BLOCK_DIR"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_PROOFS:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_OBSERVED_PROOFS"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_PROOFS_DIR:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_OBSERVED_PROOFS_DIR"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS:-}" ]]; then
+  nlean_docker_extra_env+=" -e NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS"
+fi
+if [[ -n "${NLEAN_DEBUG_DUMP_OBSERVED_BLOCKS_DIR:-}" ]]; then


+# choose either binary or docker
+node_setup="${NLEAN_QUICKSTART_SETUP:-binary}"


- Add apiPort to validator-config.yaml for leanpoint health-check URLs - Use apiPort instead of httpPort for --api-port flag in nlean-cmd.sh - Use Docker -e VAR (inherit) instead of -e VAR=value to avoid colon-breaking issues

ch4r10t33r

Looks good.

feat: add nlean consensus client support

ef7cf34

Copilot AI review requested due to automatic review settings March 18, 2026 11:27

Copilot started reviewing on behalf of GrapeBaBa March 18, 2026 11:27 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 19, 2026 12:34

GrapeBaBa force-pushed the feat/add-nlean-client-v2 branch from bc982a4 to 10ded38 Compare March 19, 2026 12:34

GrapeBaBa force-pushed the feat/add-nlean-client-v2 branch from 10ded38 to f130d9d Compare March 19, 2026 12:40

Copilot AI reviewed Mar 19, 2026

View reviewed changes

fix: address PR #137 review comments

6c1e88a

- Add apiPort to validator-config.yaml for leanpoint health-check URLs - Use apiPort instead of httpPort for --api-port flag in nlean-cmd.sh - Use Docker -e VAR (inherit) instead of -e VAR=value to avoid colon-breaking issues

GrapeBaBa force-pushed the feat/add-nlean-client-v2 branch from f130d9d to 6c1e88a Compare March 19, 2026 13:19

Merge branch 'main' into feat/add-nlean-client-v2

da942fe

ch4r10t33r approved these changes Mar 19, 2026

View reviewed changes

ch4r10t33r merged commit a96b514 into main Mar 19, 2026
4 checks passed

ch4r10t33r deleted the feat/add-nlean-client-v2 branch March 19, 2026 14:11

GrapeBaBa mentioned this pull request Mar 21, 2026

fix: move nlean from standalone devnet to shared local-devnet #143

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add nlean consensus client support#137

feat: add nlean consensus client support#137
ch4r10t33r merged 3 commits into
mainfrom
feat/add-nlean-client-v2

GrapeBaBa commented Mar 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

ch4r10t33r Mar 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

ch4r10t33r left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		# choose either binary or docker
		node_setup="${NLEAN_QUICKSTART_SETUP:-binary}"

Conversation

GrapeBaBa commented Mar 18, 2026

Changes

Tested

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ch4r10t33r Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ch4r10t33r left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants