feat: add attestation aggregate coverage metrics

  Port leanSpec PR #735: register three IntGaugeVec metrics describing
  attestation aggregate coverage, with default zero-valued series so
  dashboards render from a fresh node startup.

    - lean_attestation_aggregate_coverage_validators (section, subnet)
    - lean_attestation_aggregate_coverage_subnets    (section)
    - lean_attestation_aggregate_coverage_diff_validators (direction)

  ATTESTATION_AGGREGATE_COVERAGE_SECTIONS and
  ATTESTATION_AGGREGATE_COVERAGE_DIFF_DIRECTIONS are exported as the
  single source of truth for label sets. init() forces the new statics
  and seeds combined-subnet, section, and direction series to 0 (18
  default series total). Per-subnet (subnet="subnet_N") series appear
  lazily when instrumentation writes them.

  Registration only. The producer side (per-slot coverage computation,
  de-duplication across payloads, and the chain-status log line) ports
  zeam #876 and lands in a follow-up PR.

  The diff_validators help text diverges from upstreams terse phrasing
  to spell out the symmetric-difference semantics (block_only: in block
  but not in local timely pool; timely_only: the reverse). Metric name,
  labels, and values are unchanged.

Author: pablodeymo

crates/blockchain/src/metrics.rs

@@ -4,6 +4,27 @@ use std::time::Duration;
 
 use ethlambda_metrics::*;
 
+// --- Label sets ---
+
+/// Section labels for attestation aggregate coverage gauges. Order matches
+/// the names printed in slot/report logs.
+///
+/// Slot is the X-axis (time series), not a label dimension.
+pub const ATTESTATION_AGGREGATE_COVERAGE_SECTIONS: &[&str] = &[
+    "timely",
+    "late",
+    "block",
+    "combined",
+    "agg_start_new",
+    "proposal_payloads",
+    "proposal_gossip",
+    "proposal_combined",
+];
+
+/// Validator-coverage delta directions between block payloads and
+/// locally-aggregated pre-merge (`timely`) payloads.
+pub const ATTESTATION_AGGREGATE_COVERAGE_DIFF_DIRECTIONS: &[&str] = &["block_only", "timely_only"];
+
 // --- Gauges ---
 
 static LEAN_HEAD_SLOT: std::sync::LazyLock<IntGauge> = std::sync::LazyLock::new(|| {
@@ -104,6 +125,42 @@ static LEAN_TABLE_BYTES: std::sync::LazyLock<IntGaugeVec> = std::sync::LazyLock:
     .unwrap()
 });
 
+static LEAN_ATTESTATION_AGGREGATE_COVERAGE_VALIDATORS: std::sync::LazyLock<IntGaugeVec> =
+    std::sync::LazyLock::new(|| {
+        register_int_gauge_vec!(
+            "lean_attestation_aggregate_coverage_validators",
+            "Validator coverage in attestation aggregate reports, labeled by section and \
+             subnet. subnet=combined is the section total; subnet=subnet_N is per-subnet \
+             coverage. Updated each slot (slot is the X-axis).",
+            &["section", "subnet"]
+        )
+        .unwrap()
+    });
+
+static LEAN_ATTESTATION_AGGREGATE_COVERAGE_SUBNETS: std::sync::LazyLock<IntGaugeVec> =
+    std::sync::LazyLock::new(|| {
+        register_int_gauge_vec!(
+            "lean_attestation_aggregate_coverage_subnets",
+            "Number of covered subnets in attestation aggregate reports, labeled by section. \
+             Updated each slot (slot is the X-axis).",
+            &["section"]
+        )
+        .unwrap()
+    });
+
+static LEAN_ATTESTATION_AGGREGATE_COVERAGE_DIFF_VALIDATORS: std::sync::LazyLock<IntGaugeVec> =
+    std::sync::LazyLock::new(|| {
+        register_int_gauge_vec!(
+            "lean_attestation_aggregate_coverage_diff_validators",
+            "Count of validators in the symmetric difference between block-included aggregates \
+             and locally-aggregated pre-merge (timely) aggregates for the same slot. \
+             direction=block_only: in block but not in local pool. direction=timely_only: in \
+             local pool but not in block. Updated each slot (slot is the X-axis).",
+            &["direction"]
+        )
+        .unwrap()
+    });
+
 // --- Counters ---
 
 static LEAN_ATTESTATIONS_VALID_TOTAL: std::sync::LazyLock<IntCounter> =
@@ -409,6 +466,25 @@ pub fn init() {
     std::sync::LazyLock::force(&LEAN_IS_AGGREGATOR);
     std::sync::LazyLock::force(&LEAN_ATTESTATION_COMMITTEE_COUNT);
     std::sync::LazyLock::force(&LEAN_TABLE_BYTES);
+    // Attestation aggregate coverage (leanMetrics: Fork-Choice Metrics).
+    // Per upstream leanSpec, seed only the combined-subnet series for each
+    // section; per-subnet series appear lazily when instrumentation writes them.
+    std::sync::LazyLock::force(&LEAN_ATTESTATION_AGGREGATE_COVERAGE_VALIDATORS);
+    std::sync::LazyLock::force(&LEAN_ATTESTATION_AGGREGATE_COVERAGE_SUBNETS);
+    std::sync::LazyLock::force(&LEAN_ATTESTATION_AGGREGATE_COVERAGE_DIFF_VALIDATORS);
+    for &section in ATTESTATION_AGGREGATE_COVERAGE_SECTIONS {
+        LEAN_ATTESTATION_AGGREGATE_COVERAGE_VALIDATORS
+            .with_label_values(&[section, "combined"])
+            .set(0);
+        LEAN_ATTESTATION_AGGREGATE_COVERAGE_SUBNETS
+            .with_label_values(&[section])
+            .set(0);
+    }
+    for &direction in ATTESTATION_AGGREGATE_COVERAGE_DIFF_DIRECTIONS {
+        LEAN_ATTESTATION_AGGREGATE_COVERAGE_DIFF_VALIDATORS
+            .with_label_values(&[direction])
+            .set(0);
+    }
     // Counters
     std::sync::LazyLock::force(&LEAN_ATTESTATIONS_VALID_TOTAL);
     std::sync::LazyLock::force(&LEAN_ATTESTATIONS_INVALID_TOTAL);