From 5f0908211545200c0b4da567f07eb496be8f087e Mon Sep 17 00:00:00 2001 From: Pablo Deymonnaz Date: Fri, 13 Feb 2026 17:13:20 -0300 Subject: [PATCH] Document that --is-aggregator flag is required for finalization Without this flag, attestations pass signature verification but the signature is never stored for aggregation (store.rs:368), so blocks are always built with attestation_count=0 and the network never finalizes. At least one node must run as aggregator. --- CLAUDE.md | 7 +++++++ README.md | 2 ++ 2 files changed, 9 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 19864d7..e612769 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -308,6 +308,13 @@ cargo test -p ethlambda-blockchain --features skip-signature-verification --test ## Common Gotchas +### Aggregator Flag Required for Finalization +- At least one node **must** be started with `--is-aggregator` to finalize blocks in production (without `skip-signature-verification`) +- Without this flag, attestations pass signature verification and are logged as "Attestation processed", but the signature is never stored for aggregation (`store.rs:368`), so blocks are always built with `attestation_count=0` +- The attestation pipeline: gossip → verify signature → store gossip signature (only if `is_aggregator`) → aggregate at interval 2 → promote to known → pack into blocks +- With `skip-signature-verification` (tests only), attestations bypass aggregation and go directly to `new_aggregated_payloads`, so the flag is not needed +- **Symptom**: `justified_slot=0` and `finalized_slot=0` indefinitely despite healthy block production and attestation gossip + ### Signature Verification - Tests require `skip-signature-verification` feature for performance - Crypto tests marked `#[ignore]` (slow leanVM operations) diff --git a/README.md b/README.md index 0fa249d..8f870a9 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ make run-devnet This generates fresh genesis files and starts all configured clients with metrics enabled. Press `Ctrl+C` to stop all nodes. +> **Important:** When running nodes manually (outside `make run-devnet`), at least one node must be started with `--is-aggregator` for attestations to be aggregated and included in blocks. Without this flag, the network will produce blocks but never finalize. + For custom devnet configurations, go to `lean-quickstart/local-devnet/genesis/validator-config.yaml` and edit the file before running the command above. See `lean-quickstart`'s documentation for more details on how to configure the devnet. ## Philosophy