Reframe Lean as "client-only today, EL pairing later"

The earlier wording described Lean consensus as architecturally
standalone ("no EL pairing", "no Engine API", "fully standalone"). That
isn't the long-term picture: Lean clients are designed to pair with EL
clients in the regular EL+CL devnet shape; they just don't implement
Engine API yet, so present-day devnets are client-only.

Reframe both code comments and docs around that distinction:

- main.star and lean_launcher.star comments now say "no Engine API yet"
  / "until Engine API ships" instead of declaring Lean architecturally
  EL-less.
- docs/lean-consensus.md introduces Lean as "client-only today, EL
  pairing later" and notes the motivation for landing it in this
  package is exactly to be ready for the EL+Lean shape when it ships.
- The why-a-parallel-pipeline table is retitled "Lean (today)" and adds
  a follow-up paragraph on how the two pipelines compose once Engine
  API lands.

Author: ilitteri

docs/lean-consensus.md

@@ -6,10 +6,14 @@
 > have stub launchers covered by the same contract.
 
 The Lean Ethereum protocol — sometimes called "Beam Chain" — is a redesign of
-Ethereum's consensus layer with **no EL pairing**, **no Engine API**, **no
-JWT**, and **post-quantum (XMSS / hash-sig) validator signatures**. Lean
-consensus clients are standalone consensus nodes that talk only to each other
-over QUIC + libp2p gossipsub. The Lean protocol specification lives at
+Ethereum's consensus layer built around **post-quantum (XMSS / hash-sig)
+validator signatures**. Today's Lean clients run client-only devnets while
+the spec stabilises: no Engine API integration yet, no JWT, just consensus
+nodes peering over QUIC + libp2p gossipsub. Engine API support is on the
+roadmap, after which the same Lean clients are designed to pair with EL
+clients in the regular EL+CL devnet shape — which is exactly the motivation
+for landing them in this package alongside the existing EL pipeline. The
+Lean protocol specification lives at
 [ReamLabs/leanSpecs](https://github.com/ReamLabs/leanSpecs) and is
 co-developed by the teams behind
 [ream](https://github.com/ReamLabs/ream) (Rust),
@@ -28,16 +32,17 @@ new Lean client, see
 
 ## Why a parallel pipeline?
 
-Lean consensus differs from the existing EL/CL pipeline along every axis that
+Lean consensus today differs from the EL/CL pipeline along several axes that
 shaped the original `participant_network` design:
 
-| Concern                | EL/CL                          | Lean                          |
+| Concern                | EL/CL                          | Lean (today)                  |
 |------------------------|--------------------------------|-------------------------------|
 | Genesis tool           | `ethereum-genesis-generator`   | `eth-beacon-genesis leanchain` |
 | Validator signatures   | BLS                            | XMSS (hash-sig)               |
 | Validator key keystore | EIP-2335 JSON                  | SSZ `validator_N_*_key_*.ssz` |
-| Pairing                | 1 EL + 1 CL (+ optional VC)    | Standalone, no EL             |
-| RPC ports              | Engine RPC + JWT + REST + WS   | REST + Prometheus only        |
+| EL pairing             | 1 EL + 1 CL (+ optional VC)    | Client-only (no EL yet)       |
+| Engine API + JWT       | Required                       | Not implemented yet           |
+| RPC ports              | Engine RPC + JWT + REST + WS   | REST + Prometheus             |
 | P2P transport          | TCP + UDP discovery + libp2p   | QUIC-only (libp2p)            |
 | Block production       | EL builds payload, CL attests  | Single-stack: 4 s slots       |
 
@@ -48,6 +53,12 @@ the snooper, etc. A parallel pipeline keeps those code paths untouched and
 isolates Lean-specific concerns under `src/lean/` and
 `src/prelaunch_data_generator/lean_genesis/`.
 
+Once Lean clients ship Engine API support, the design intent is for the
+two pipelines to compose: a Lean participant declares its EL counterpart
+the same way today's CL clients do, JWT is shared, and the existing
+EL-side plumbing (image discovery, MEV-boost, snooper, dora) keeps
+working. Until then, the realistic devnet shape is Lean-only.
+
 The package still composes the two: Prometheus/Grafana discover Lean nodes
 through their service labels and metrics ports, and additional services that
 don't depend on EL state (e.g. dora's beacon explorer) can be pointed at Lean
@@ -57,9 +68,9 @@ nodes by URL.
 
 ## Quick start
 
-Lean consensus is fully standalone — no Engine API, no EL counterpart.
-A Lean network configuration therefore contains ONLY `lean_participants:`
-(set `participants: []` to skip the Eth1 EL/CL flow entirely):
+Today's Lean clients run client-only (no Engine API yet), so the realistic
+devnet shape is Lean-only — the args file contains `lean_participants:` and
+`participants: []` to skip the Eth1 EL/CL flow:
 
 ```yaml
 participants: []

main.star

@@ -90,12 +90,15 @@ def run(plan, args={}):
     network_params = args_with_right_defaults.network_params
 
     # Lean-only mode: when the operator configured `lean_participants:` but
-    # no Eth1 `participants:` entries, run ONLY the Lean pipeline. Lean
-    # consensus is fully standalone (no Engine API, no EL counterpart), so
-    # spinning up an EL+CL pair as a "placeholder" would just waste resources
-    # and confuse downstream services that try to call the Engine API.
-    # The lean_launcher returns the per-node contexts; downstream consumers
-    # (prometheus, grafana, dora) can be wired through in a follow-up.
+    # no Eth1 `participants:` entries, run ONLY the Lean pipeline. Today's
+    # Lean clients don't implement Engine API yet, so spinning up an EL+CL
+    # pair alongside would just waste resources and confuse downstream
+    # services that try to call into a non-existent Engine API. Once Lean
+    # clients ship Engine API support, the same `lean_participants:` entries
+    # will be able to pair with EL `participants:` and reuse the existing
+    # JWT + payload-attestation plumbing. The lean_launcher returns the
+    # per-node contexts; downstream consumers (prometheus, grafana, dora)
+    # can be wired through in a follow-up.
     if num_participants == 0 and args_with_right_defaults.lean_participants:
         plan.print(
             "Lean-only mode: {0} lean participant entries, 0 EL/CL participants".format(
@@ -361,9 +364,11 @@ def run(plan, args={}):
         all_xatu_sentry_contexts.append(participant.xatu_sentry_context)
 
     # Launch Lean Ethereum consensus participants alongside the EL/CL network.
-    # Lean is a standalone consensus stack (no EL pairing, no Engine API, no
-    # JWT, post-quantum signatures); it runs through its own pipeline and
-    # produces independent file artifacts + services. The list is empty
+    # Today's Lean clients run client-only (no Engine API yet) and use
+    # post-quantum signatures; the pipeline brings them up against their
+    # own genesis + libp2p QUIC mesh. Once Engine API lands on the Lean
+    # side, these participants will be able to pair with `participants:`
+    # EL clients and reuse the existing JWT plumbing. The list is empty
     # unless the user populated `lean_participants:` in their args.
     # See docs/lean-consensus.md for the architecture.
     all_lean_contexts = lean_launcher.launch(

src/lean/lean_launcher.star

@@ -11,8 +11,12 @@ Orchestrates the entire Lean pipeline:
      binary via `plan.exec`.
 
 This is intentionally independent of the EL/CL `participant_network` pipeline:
-Lean consensus has no Engine API, no JWT, no EL pairing. Operators opt in by
-populating `lean_participants:` in their args; the existing EL/CL flow runs
+Today's Lean devnets run client-only (no EL pairing yet), so this pipeline
+brings up a Lean-only mesh. Engine API support is on the roadmap for the
+Lean clients, after which the same `lean_participants:` entries will be
+able to pair with EL clients from `participants:` and share the existing
+package's Engine API / JWT plumbing. Operators opt in to Lean by populating
+`lean_participants:` in their args; the existing EL/CL flow runs
 unchanged either way.
 """