feat: make allowed timestamp future a protocol param (#146)

When validators verify the timestamp of a proposed block they check that the timestamp is later than the parent timestamp, and that the timestamp is not too far in the future, relative to the local time.
This change turns this parameter into a protocol param, that can be updated via execution request.

Author: matthias-wright

application/src/actor.rs

@@ -46,7 +46,6 @@ pub struct Actor<
     built_block: Arc<Mutex<Option<(Block, Round)>>>,
     genesis_hash: [u8; 32],
     epocher: ES,
-    allowed_timestamp_future_ms: u64,
     cancellation_token: CancellationToken,
     _scheme_marker: PhantomData<S>,
     _key_marker: PhantomData<P>,
@@ -77,7 +76,6 @@ impl<
                 built_block: Arc::new(Mutex::new(None)),
                 genesis_hash,
                 epocher: cfg.epocher,
-                allowed_timestamp_future_ms: cfg.allowed_timestamp_future.as_millis() as u64,
                 cancellation_token: cfg.cancellation_token,
                 _scheme_marker: PhantomData,
                 _key_marker: PhantomData,
@@ -236,7 +234,6 @@ impl<
                                 let mut syncer = syncer.clone();
                                 let mut finalizer_clone = finalizer.clone();
                                 let epocher = self.epocher.clone();
-                                let allowed_timestamp_future_ms = self.allowed_timestamp_future_ms;
                                 move |context| async move {
                                     let requester = try_join(parent_request, block_request);
                                     select! {
@@ -282,7 +279,7 @@ impl<
                                                 }
 
                                                 let now_millis = context.current().epoch_millis();
-                                                if handle_verify(&block, parent, &epocher, &aux_data, now_millis, allowed_timestamp_future_ms) {
+                                                if handle_verify(&block, parent, &epocher, &aux_data, now_millis) {
                                                     // persist valid block
                                                     syncer.verified(round, block).await;
 
@@ -581,7 +578,6 @@ fn handle_verify<ES: Epocher>(
     epocher: &ES,
     aux_data: &BlockAuxData,
     now_millis: u64,
-    allowed_timestamp_future_ms: u64,
 ) -> bool {
     // You can only re-propose the same block if it's the last height in the epoch.
     if parent.digest() == block.digest() {
@@ -604,10 +600,12 @@ fn handle_verify<ES: Epocher>(
         warn!("block timestamp not increasing");
         return false;
     }
-    if block.timestamp() > now_millis + allowed_timestamp_future_ms {
+    if block.timestamp() > now_millis + aux_data.allowed_timestamp_future_ms {
         warn!(
             block_timestamp = block.timestamp(),
-            now_millis, allowed_timestamp_future_ms, "block timestamp too far in the future"
+            now_millis,
+            allowed_timestamp_future_ms = aux_data.allowed_timestamp_future_ms,
+            "block timestamp too far in the future"
         );
         return false;
     }

application/src/config.rs

@@ -1,5 +1,4 @@
 use commonware_consensus::types::Epocher;
-use std::time::Duration;
 use summit_types::EngineClient;
 use tokio_util::sync::CancellationToken;
 
@@ -18,11 +17,5 @@ pub struct ApplicationConfig<C: EngineClient, ES: Epocher> {
     /// Epocher for determining epoch boundaries.
     pub epocher: ES,
 
-    /// Maximum allowed delta between a block's timestamp and the
-    /// local wall clock. Blocks with timestamps that differ from
-    /// the local time by more than this are rejected during
-    /// verification.
-    pub allowed_timestamp_future: Duration,
-
     pub cancellation_token: CancellationToken,
 }

docs/ssz-merklization.md

@@ -36,7 +36,7 @@ The state tree is a two-level design: a fixed top-level tree containing scalar f
 
 ### Top-Level Tree
 
-32 leaf slots (depth 5), 17 used. Each leaf is a 32-byte `hash_tree_root` value. Leaves 17–31 are unused (zero-filled).
+32 leaf slots (depth 5), 18 used. Each leaf is a 32-byte `hash_tree_root` value. Leaves 18–31 are unused (zero-filled).
 
 | Leaf Index | Field | Type |
 |------------|-------|------|
@@ -51,12 +51,13 @@ The state tree is a two-level design: a fixed top-level tree containing scalar f
 | 8 | `forkchoice_head_block_hash` | Scalar |
 | 9 | `forkchoice_safe_block_hash` | Scalar |
 | 10 | `forkchoice_finalized_block_hash` | Scalar |
-| 11 | `validator_accounts` | Collection root |
-| 12 | `deposit_queue` | Collection root |
-| 13 | `withdrawal_queue` | Collection root |
-| 14 | `protocol_param_changes` | Collection root |
-| 15 | `added_validators` | Collection root |
-| 16 | `removed_validators` | Collection root |
+| 11 | `allowed_timestamp_future_ms` | Scalar |
+| 12 | `validator_accounts` | Collection root |
+| 13 | `deposit_queue` | Collection root |
+| 14 | `withdrawal_queue` | Collection root |
+| 15 | `protocol_param_changes` | Collection root |
+| 16 | `added_validators` | Collection root |
+| 17 | `removed_validators` | Collection root |
 
 ### Collection Subtrees
 
@@ -141,7 +142,7 @@ A `HashMap<pubkey, (epoch_slot, item_slot)>` index enables O(1) proof lookup by
 
 All leaf values are 32 bytes, produced by SSZ `hash_tree_root`:
 
-- **`u64`**: Little-endian encoded, zero-padded to 32 bytes. Used by: epoch, view, latest_height, balance, amount, index, joining_epoch, last_deposit_index, next_withdrawal_index, minimum/maximum_stake, validator_index, balance_deduction.
+- **`u64`**: Little-endian encoded, zero-padded to 32 bytes. Used by: epoch, view, latest_height, balance, amount, index, joining_epoch, last_deposit_index, next_withdrawal_index, minimum/maximum_stake, allowed_timestamp_future_ms, validator_index, balance_deduction.
 - **`bool`**: `0x01` or `0x00`, zero-padded to 32 bytes. Used by: has_pending_deposit, has_pending_withdrawal.
 - **`ValidatorStatus` (enum)**: Single byte (Active=0, Inactive=1, SubmittedExitRequest=2, Joining=3), zero-padded to 32 bytes.
 - **`[u8; 32]`**: Used directly as the leaf value. Used by: head_digest, epoch_genesis_hash, forkchoice hashes, withdrawal_credentials (deposit), pubkey (withdrawal).
@@ -168,6 +169,7 @@ Single top-level leaf write + rehash of the 5-level path to root.
 | `set_epoch_genesis_hash()` | `ssz_tree.set_epoch_genesis_hash()` |
 | `set_minimum_stake()` | `ssz_tree.set_validator_minimum_stake()` |
 | `set_maximum_stake()` | `ssz_tree.set_validator_maximum_stake()` |
+| `set_allowed_timestamp_future_ms()` | `ssz_tree.set_allowed_timestamp_future_ms()` |
 | `set_next_withdrawal_index()` | `ssz_tree.set_next_withdrawal_index()` |
 | `set_forkchoice_head()` | `ssz_tree.set_forkchoice_head_block_hash()` |
 | `set_forkchoice_safe_and_finalized()` | Two setter calls (safe + finalized) |
@@ -392,6 +394,7 @@ Keys are human-readable strings parsed by `types/src/ssz_tree_key.rs`:
 | `epoch_genesis_hash` | Genesis hash for current epoch |
 | `validator_minimum_stake` | Minimum validator stake |
 | `validator_maximum_stake` | Maximum validator stake |
+| `allowed_timestamp_future_ms` | Allowed timestamp future (ms) |
 | `next_withdrawal_index` | Next withdrawal index |
 | `forkchoice_head_block_hash` | Forkchoice head hash |
 | `forkchoice_safe_block_hash` | Forkchoice safe hash |

example_genesis.toml

@@ -9,6 +9,7 @@ namespace = "_SUMMIT"
 validator_minimum_stake = 32000000000
 validator_maximum_stake = 32000000000
 blocks_per_epoch = 10000
+allowed_timestamp_future_ms = 10000
 
 [[validators]]
 node_public_key = "1be3cb06d7cc347602421fb73838534e4b54934e28959de98906d120d0799ef2"

finalizer/src/actor.rs

@@ -889,6 +889,7 @@ impl<
                 forkchoice: *state.get_forkchoice(),
                 withdrawal_credentials,
                 state_root: state.get_state_root(),
+                allowed_timestamp_future_ms: state.get_allowed_timestamp_future_ms(),
             }
         } else {
             BlockAuxData {
@@ -901,6 +902,7 @@ impl<
                 forkchoice: *state.get_forkchoice(),
                 withdrawal_credentials,
                 state_root: state.get_state_root(),
+                allowed_timestamp_future_ms: state.get_allowed_timestamp_future_ms(),
             }
         };
         trace!(
@@ -970,6 +972,10 @@ impl<
                 let length = self.canonical_state.get_epocher().current_length();
                 let _ = sender.send(ConsensusStateResponse::EpochLength(length));
             }
+            ConsensusStateRequest::GetAllowedTimestampFuture => {
+                let ms = self.canonical_state.get_allowed_timestamp_future_ms();
+                let _ = sender.send(ConsensusStateResponse::AllowedTimestampFuture(ms));
+            }
             ConsensusStateRequest::GetEpochBounds(epoch) => {
                 let bounds = self
                     .canonical_state

finalizer/src/ingress.rs

@@ -279,6 +279,24 @@ impl<S: Scheme<B::Digest>, B: ConsensusBlock> FinalizerMailbox<S, B> {
         length
     }
 
+    pub async fn get_allowed_timestamp_future(&self) -> u64 {
+        let (response, rx) = oneshot::channel();
+        let request = ConsensusStateRequest::GetAllowedTimestampFuture;
+        let _ = self
+            .sender
+            .clone()
+            .send(FinalizerMessage::QueryState { request, response })
+            .await;
+
+        let res = rx
+            .await
+            .expect("consensus state query response sender dropped");
+        let ConsensusStateResponse::AllowedTimestampFuture(ms) = res else {
+            unreachable!("request and response variants must match");
+        };
+        ms
+    }
+
     pub async fn get_epoch_bounds(&self, epoch: u64) -> Option<(u64, u64)> {
         let (response, rx) = oneshot::channel();
         let request = ConsensusStateRequest::GetEpochBounds(epoch);

finalizer/src/tests/fork_handling.rs

@@ -113,7 +113,13 @@ fn create_test_initial_state(genesis_hash: [u8; 32], epoch_length: NonZeroU64) -
         safe_block_hash: genesis_hash.into(),
         finalized_block_hash: genesis_hash.into(),
     };
-    let mut state = ConsensusState::new(forkchoice, 32_000_000_000, 64_000_000_000, epoch_length);
+    let mut state = ConsensusState::new(
+        forkchoice,
+        32_000_000_000,
+        64_000_000_000,
+        epoch_length,
+        10_000,
+    );
     state.set_validator_accounts(validator_accounts);
     state
 }

finalizer/src/tests/state_queries.rs

@@ -119,7 +119,13 @@ fn create_test_initial_state(genesis_hash: [u8; 32], epoch_length: NonZeroU64) -
         safe_block_hash: genesis_hash.into(),
         finalized_block_hash: genesis_hash.into(),
     };
-    let mut state = ConsensusState::new(forkchoice, 32_000_000_000, 64_000_000_000, epoch_length);
+    let mut state = ConsensusState::new(
+        forkchoice,
+        32_000_000_000,
+        64_000_000_000,
+        epoch_length,
+        10_000,
+    );
     state.set_validator_accounts(validator_accounts);
     state
 }

finalizer/src/tests/syncing.rs

@@ -113,7 +113,13 @@ fn create_test_initial_state(genesis_hash: [u8; 32], epoch_length: NonZeroU64) -
         safe_block_hash: genesis_hash.into(),
         finalized_block_hash: genesis_hash.into(),
     };
-    let mut state = ConsensusState::new(forkchoice, 32_000_000_000, 64_000_000_000, epoch_length);
+    let mut state = ConsensusState::new(
+        forkchoice,
+        32_000_000_000,
+        64_000_000_000,
+        epoch_length,
+        10_000,
+    );
     state.set_validator_accounts(validator_accounts);
     state
 }

finalizer/src/tests/validator_lifecycle.rs

@@ -119,7 +119,13 @@ fn create_test_initial_state(genesis_hash: [u8; 32], epoch_length: NonZeroU64) -
         safe_block_hash: genesis_hash.into(),
         finalized_block_hash: genesis_hash.into(),
     };
-    let mut state = ConsensusState::new(forkchoice, 32_000_000_000, 64_000_000_000, epoch_length);
+    let mut state = ConsensusState::new(
+        forkchoice,
+        32_000_000_000,
+        64_000_000_000,
+        epoch_length,
+        10_000,
+    );
     state.set_validator_accounts(validator_accounts);
     state
 }