Advance XMSS key preparation window before signing (#261)

## Summary

- Expose `is_prepared_for(slot)` and `advance_preparation()` on
`ValidatorSecretKey`, delegating to the leansig
`SignatureSchemeSecretKey` trait
- Before signing in `KeyManager::sign_message()`, check if the target
slot is within the prepared window and advance if needed
- Return a descriptive error if the key's activation interval is fully
exhausted
- Add a timing test for `advance_preparation()` (526ms in release mode
on Apple Silicon)

## Root Cause

XMSS keys use a Top-Bottom Tree Traversal scheme where only two
consecutive bottom trees are loaded in memory at any time. Each bottom
tree covers `sqrt(LIFETIME) = 2^16 = 65,536` slots, so the prepared
window spans `131,072` slots (~6 days at 4s/slot).

The leansig library provides `advance_preparation()` to slide this
window forward by computing the next bottom tree, but ethlambda's
`KeyManager` never called it. When the devnet at `admin@ethlambda-1`
reached slot 131,072, all 4 nodes panicked simultaneously:

```
Signing: key not yet prepared for this epoch, try calling sk.advance_preparation.
```

The fix checks the prepared interval before every sign operation and
advances the window on demand. This is a lazy approach —
`advance_preparation` is called at signing time rather than proactively
in the tick loop — because:
- It happens once every ~3 days (65,536 slots)
- The computation (one bottom tree of hash leaves) takes ~526ms in
release mode
- It keeps the change minimal and avoids tick-loop complexity

## Test plan

- [x] `make fmt` clean
- [x] `make lint` clean
- [x] `make test` passes (existing tests use small lifetimes or skip
verification)
- [x] `test_advance_preparation_duration` passes (`cargo test -p
ethlambda-types test_advance_preparation_duration --release -- --ignored
--nocapture`)
- [ ] Deploy to devnet with fresh genesis and verify it runs past slot
131,072 without panic

Author: pablodeymo

Cargo.lock

@@ -5,6 +5,7 @@ use ethlambda_types::{
     primitives::{H256, HashTreeRoot as _},
     signature::{ValidatorSecretKey, ValidatorSignature},
 };
+use tracing::info;
 
 use crate::metrics;
 
@@ -102,6 +103,23 @@ impl KeyManager {
             .get_mut(&validator_id)
             .ok_or(KeyManagerError::ValidatorKeyNotFound(validator_id))?;
 
+        // Advance XMSS key preparation window if the slot is outside the current window.
+        // Each bottom tree covers 65,536 slots; the window holds 2 at a time.
+        // Multiple advances may be needed if the node was offline for an extended period.
+        if !secret_key.is_prepared_for(slot) {
+            info!(validator_id, slot, "Advancing XMSS key preparation window");
+            while !secret_key.is_prepared_for(slot) {
+                let before = secret_key.get_prepared_interval();
+                secret_key.advance_preparation();
+                if secret_key.get_prepared_interval() == before {
+                    return Err(KeyManagerError::SigningError(format!(
+                        "XMSS key exhausted for validator {validator_id}: \
+                         slot {slot} is beyond the key's activation interval"
+                    )));
+                }
+            }
+        }
+
         let signature: ValidatorSignature = {
             let _timing = metrics::time_pq_sig_attestation_signing();
             secret_key

crates/blockchain/src/key_manager.rs

@@ -24,3 +24,4 @@ libssz-types.workspace = true
 [dev-dependencies]
 serde_json.workspace = true
 serde_yaml_ng.workspace = true
+rand.workspace = true

crates/common/types/Cargo.toml

@@ -1,6 +1,8 @@
+use std::ops::Range;
+
 use leansig::{
     serialization::Serializable,
-    signature::{SignatureScheme, SigningError},
+    signature::{SignatureScheme, SignatureSchemeSecretKey as _, SigningError},
 };
 
 use crate::primitives::H256;
@@ -97,4 +99,86 @@ impl ValidatorSecretKey {
         let sig = LeanSignatureScheme::sign(&self.inner, slot, &message.0)?;
         Ok(ValidatorSignature { inner: sig })
     }
+
+    /// Returns true if the key is prepared to sign at the given slot.
+    ///
+    /// XMSS keys maintain a sliding window of two bottom trees. Only slots
+    /// within this window can be signed without advancing the preparation.
+    pub fn is_prepared_for(&self, slot: u32) -> bool {
+        self.inner.get_prepared_interval().contains(&(slot as u64))
+    }
+
+    /// Returns the slot range currently covered by the prepared window.
+    pub fn get_prepared_interval(&self) -> Range<u64> {
+        self.inner.get_prepared_interval()
+    }
+
+    /// Advance the prepared window forward by one bottom tree.
+    ///
+    /// Each call slides the window by sqrt(LIFETIME) = 65,536 slots.
+    /// If the window is already at the end of the key's activation interval,
+    /// this is a no-op.
+    pub fn advance_preparation(&mut self) {
+        self.inner.advance_preparation();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use leansig::serialization::Serializable;
+    use rand::{SeedableRng, rngs::StdRng};
+
+    const LEAVES_PER_BOTTOM_TREE: u32 = 1 << 16; // 65,536
+
+    /// Generate a ValidatorSecretKey with 3 bottom trees so advance_preparation can be tested.
+    ///
+    /// This is slow (~minutes) because it computes 3 bottom trees of 65,536 leaves each.
+    fn generate_key_with_three_bottom_trees() -> ValidatorSecretKey {
+        let mut rng = StdRng::seed_from_u64(42);
+        // Request enough active epochs for 3 bottom trees (> 2 * 65,536)
+        let num_active_epochs = (LEAVES_PER_BOTTOM_TREE as usize) * 2 + 1;
+        let (_pk, sk) = LeanSignatureScheme::key_gen(&mut rng, 0, num_active_epochs);
+        let sk_bytes = sk.to_bytes();
+        ValidatorSecretKey::from_bytes(&sk_bytes).expect("valid secret key")
+    }
+
+    #[test]
+    #[ignore = "slow: generates production-size XMSS key (~minutes)"]
+    fn test_advance_preparation_duration() {
+        println!("Generating XMSS key with 3 bottom trees (this takes a while)...");
+        let keygen_start = std::time::Instant::now();
+        let mut sk = generate_key_with_three_bottom_trees();
+        println!("Key generation took: {:?}", keygen_start.elapsed());
+
+        // Initial window covers [0, 131072)
+        assert!(sk.is_prepared_for(0));
+        assert!(sk.is_prepared_for(LEAVES_PER_BOTTOM_TREE - 1));
+        assert!(sk.is_prepared_for(2 * LEAVES_PER_BOTTOM_TREE - 1));
+        assert!(!sk.is_prepared_for(2 * LEAVES_PER_BOTTOM_TREE));
+
+        // Time the advance_preparation call
+        let advance_start = std::time::Instant::now();
+        sk.advance_preparation();
+        let advance_duration = advance_start.elapsed();
+
+        println!("advance_preparation() took: {advance_duration:?}");
+
+        // Window should now cover [65536, 196608)
+        assert!(!sk.is_prepared_for(0));
+        assert!(sk.is_prepared_for(LEAVES_PER_BOTTOM_TREE));
+        assert!(sk.is_prepared_for(3 * LEAVES_PER_BOTTOM_TREE - 1));
+
+        // Verify signing works in the new window
+        let message = H256::from([42u8; 32]);
+        let slot = 2 * LEAVES_PER_BOTTOM_TREE; // slot 131,072 — the one that crashed the devnet
+        let sign_start = std::time::Instant::now();
+        let result = sk.sign(slot, &message);
+        println!("Signing at slot {slot} took: {:?}", sign_start.elapsed());
+        assert!(
+            result.is_ok(),
+            "signing should succeed after advance: {}",
+            result.err().map_or(String::new(), |e| e.to_string())
+        );
+    }
 }