Merge branch 'main' into bf/proposal-epoch-refactor

Author: bfish713

.env

@@ -99,8 +99,8 @@ ESPRESSO_DEMO_SEQUENCER_LIBP2P_PORT_4=7004
 ESPRESSO_SEQUENCER_STAKE_TABLE_CAPACITY=10
 
 # The demo can use a short exit escrow period. It should be the length of at least 3 epochs plus a
-# reasonably timeframe to submit slashing evidence. This assumes the demo is using 20 blocks epoch.
-ESPRESSO_SEQUENCER_STAKE_TABLE_EXIT_ESCROW_PERIOD=3m
+# reasonably timeframe to submit slashing evidence. The stake table contract requires a minimum of 2 days.
+ESPRESSO_SEQUENCER_STAKE_TABLE_EXIT_ESCROW_PERIOD=2d
 
 # Foundry
 # The mnemonic used by foundry to deploy contracts.
@@ -178,4 +178,4 @@ ESPRESSO_OPS_TIMELOCK_EXECUTORS=${ESPRESSO_SEQUENCER_ETH_MULTISIG_ADDRESS}
 ESPRESSO_SAFE_EXIT_TIMELOCK_DELAY=1209600
 ESPRESSO_SAFE_EXIT_TIMELOCK_ADMIN=8626f6940e2eb28930efb4cef49b2d1f2c9c1199
 ESPRESSO_SAFE_EXIT_TIMELOCK_PROPOSERS=${ESPRESSO_SEQUENCER_ETH_MULTISIG_ADDRESS}
-ESPRESSO_SAFE_EXIT_TIMELOCK_EXECUTORS=${ESPRESSO_SEQUENCER_ETH_MULTISIG_ADDRESS}
+ESPRESSO_SAFE_EXIT_TIMELOCK_EXECUTORS=${ESPRESSO_SEQUENCER_ETH_MULTISIG_ADDRESS}

contracts/artifacts/abi/StakeTableV2.json

@@ -30,6 +30,19 @@
     ],
     "stateMutability": "view"
   },
+  {
+    "type": "function",
+    "name": "MAX_EXIT_ESCROW_PERIOD",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint64",
+        "internalType": "uint64"
+      }
+    ],
+    "stateMutability": "view"
+  },
   {
     "type": "function",
     "name": "MAX_METADATA_URI_LENGTH",
@@ -43,6 +56,19 @@
     ],
     "stateMutability": "view"
   },
+  {
+    "type": "function",
+    "name": "MIN_EXIT_ESCROW_PERIOD",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint64",
+        "internalType": "uint64"
+      }
+    ],
+    "stateMutability": "view"
+  },
   {
     "type": "function",
     "name": "PAUSER_ROLE",

contracts/rust/adapter/src/bindings/stake_table.rs

@@ -367,7 +367,9 @@ impl<P: Provider + WalletProvider> DeployerArgs<P> {
                 let lc_addr = contracts
                     .address(Contract::LightClientProxy)
                     .context("no LightClient proxy address")?;
-                let escrow_period = self.exit_escrow_period.unwrap_or(U256::from(250));
+                let escrow_period = self
+                    .exit_escrow_period
+                    .unwrap_or(U256::from(crate::DEFAULT_EXIT_ESCROW_PERIOD_SECONDS));
                 crate::deploy_stake_table_proxy(
                     provider,
                     contracts,

contracts/rust/adapter/src/bindings/stake_table_v2.rs

@@ -110,6 +110,8 @@ pub fn build_random_provider(url: Url) -> HttpProviderWithWallet {
 const LIBRARY_PLACEHOLDER_ADDRESS: &str = "ffffffffffffffffffffffffffffffffffffffff";
 /// `stateHistoryRetentionPeriod` in LightClient.sol as the maximum retention period in seconds
 pub const MAX_HISTORY_RETENTION_SECONDS: u32 = 864000;
+/// Default exit escrow period for stake table (2 days in seconds)
+pub const DEFAULT_EXIT_ESCROW_PERIOD_SECONDS: u64 = 172800;
 
 /// Set of predeployed contracts.
 #[derive(Clone, Debug, Parser)]
@@ -1826,7 +1828,7 @@ mod tests {
         )
         .await?;
         let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
-        let exit_escrow_period = U256::from(1000);
+        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
 
         let stake_table_proxy_addr = deploy_stake_table_proxy(
             &provider,
@@ -2430,7 +2432,7 @@ mod tests {
         .await?;
 
         // deploy stake table
-        let exit_escrow_period = U256::from(250);
+        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
         let owner = init_recipient;
         let stake_table_addr = deploy_stake_table_proxy(
             &provider,
@@ -2489,7 +2491,7 @@ mod tests {
         .await?;
 
         // deploy stake table
-        let exit_escrow_period = U256::from(250);
+        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
         let owner = init_recipient;
         let stake_table_addr = deploy_stake_table_proxy(
             &provider,
@@ -2600,7 +2602,7 @@ mod tests {
         )
         .await?;
 
-        let exit_escrow_period = U256::from(250);
+        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
         let owner = init_recipient;
         let stake_table_proxy_addr = deploy_stake_table_proxy(
             &provider,
@@ -3179,7 +3181,7 @@ mod tests {
                     &mut contracts,
                     token_addr,
                     lc_proxy_addr,
-                    U256::from(1000u64),
+                    U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS),
                     admin,
                 )
                 .await?
@@ -3421,7 +3423,7 @@ mod tests {
         .await?;
 
         let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
-        let exit_escrow_period = U256::from(1000);
+        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
 
         let stake_table_proxy_addr = deploy_stake_table_proxy(
             &provider,
@@ -3458,7 +3460,7 @@ mod tests {
         .await?;
 
         let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
-        let exit_escrow_period = U256::from(1000);
+        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
 
         let stake_table_proxy_addr = deploy_stake_table_proxy(
             &provider,

contracts/rust/deployer/src/builder.rs

@@ -247,8 +247,7 @@ contract StakeTable is Initializable, InitializedAt, OwnableUpgradeable, UUPSUpg
         token = ERC20(_tokenAddress);
         lightClient = ILightClient(_lightClientAddress);
 
-        uint256 minExitEscrowPeriod = 90 seconds; // assuming 15s per block and min blocks per epoch
-            // is 6 in the light client
+        uint256 minExitEscrowPeriod = 2 days;
         if (_exitEscrowPeriod < minExitEscrowPeriod) {
             revert ExitEscrowPeriodInvalid();
         }

contracts/rust/deployer/src/lib.rs

@@ -111,6 +111,20 @@ contract StakeTableV2 is StakeTable, PausableUpgradeable, AccessControlUpgradeab
     /// @notice Maximum commission in basis points (100% = 10000 bps)
     uint16 public constant MAX_COMMISSION_BPS = 10000;
 
+    /// @notice Minimum exit escrow period (2 days)
+    /// @dev This is a technical minimum bound enforced by the contract. Setting the exit escrow
+    /// period
+    /// to this minimum does not guarantee safety. The actual exit escrow period must be set such
+    /// that the contract holds funds long enough until they are no longer staked in Espresso,
+    /// allowing sufficient time for validators to exit the active validator set and for slashing
+    /// evidence to be submitted. Governance should set a value appropriate for Espresso network
+    /// parameters (e.g., blocksPerEpoch, blockTime, and epoch duration) to ensure security.
+    uint64 public constant MIN_EXIT_ESCROW_PERIOD = 2 days;
+
+    /// @notice Maximum exit escrow period (14 days)
+    /// @dev Reasonable upper bound to prevent excessive lockup periods
+    uint64 public constant MAX_EXIT_ESCROW_PERIOD = 14 days;
+
     /// @notice Minimum time interval between commission increases (in seconds)
     uint256 public minCommissionIncreaseInterval;
 
@@ -787,21 +801,25 @@ contract StakeTableV2 is StakeTable, PausableUpgradeable, AccessControlUpgradeab
     /// @notice Update the exit escrow period
     /// @param newExitEscrowPeriod The new exit escrow period
     /// @dev This function ensures that the exit escrow period is within the valid range
-    /// @dev This function is not pausable so that governance can perform emergency updates in the
-    /// presence of system
+    /// (MIN_EXIT_ESCROW_PERIOD
+    /// to MAX_EXIT_ESCROW_PERIOD). However, governance MUST set a value that ensures funds are held
+    /// until they are no longer staked in Espresso, accounting for validator exit time and slashing
+    /// evidence submission windows. This function is not pausable so that governance can perform
+    /// emergency updates in the
+    /// presence of system upgrades.
     function updateExitEscrowPeriod(uint64 newExitEscrowPeriod)
         external
         virtual
         onlyRole(DEFAULT_ADMIN_ROLE)
     {
-        uint64 minExitEscrowPeriod = lightClient.blocksPerEpoch() * 15; // assuming 15 seconds per
-            // block
-        uint64 maxExitEscrowPeriod = 86400 * 14; // 14 days
-
-        if (newExitEscrowPeriod < minExitEscrowPeriod || newExitEscrowPeriod > maxExitEscrowPeriod)
-        {
+        // check if the new exit escrow period is within the valid range
+        if (
+            newExitEscrowPeriod < MIN_EXIT_ESCROW_PERIOD
+                || newExitEscrowPeriod > MAX_EXIT_ESCROW_PERIOD
+        ) {
             revert ExitEscrowPeriodInvalid();
         }
+
         exitEscrowPeriod = newExitEscrowPeriod;
         emit ExitEscrowPeriodUpdated(newExitEscrowPeriod);
     }

contracts/src/StakeTable.sol

@@ -1338,8 +1338,8 @@ contract StakeTableUpgradeV2Test is Test {
         address defaultAdmin = proxy.owner();
         vm.startPrank(defaultAdmin);
         vm.expectEmit(false, false, false, true, address(proxy));
-        emit StakeTableV2.ExitEscrowPeriodUpdated(200 seconds);
-        proxy.updateExitEscrowPeriod(200 seconds);
+        emit StakeTableV2.ExitEscrowPeriodUpdated(2 days);
+        proxy.updateExitEscrowPeriod(2 days);
         vm.stopPrank();
     }
 
@@ -1356,7 +1356,7 @@ contract StakeTableUpgradeV2Test is Test {
                 IAccessControl.AccessControlUnauthorizedAccount.selector, notAdmin, adminRole
             )
         );
-        StakeTableV2(proxy).updateExitEscrowPeriod(200 seconds);
+        StakeTableV2(proxy).updateExitEscrowPeriod(2 days);
         vm.stopPrank();
     }
 

contracts/src/StakeTableV2.sol

@@ -12,6 +12,7 @@ import { OwnableUpgradeable } from
     "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
 import { StakeTableUpgradeV2Test } from "./StakeTable.t.sol";
 import { StakeTable_register_Test } from "./StakeTable.t.sol";
+import { ILightClient } from "../src/interfaces/ILightClient.sol";
 
 /// @title StakeTableV2 Governance Tests
 /// @notice Comprehensive tests for governance functions: transferOwnership, grantRole, revokeRole
@@ -91,12 +92,12 @@ contract StakeTableV2GovernanceTest is Test {
             )
         );
         vm.expectEmit(true, true, true, true, address(proxy));
-        emit StakeTableV2.ExitEscrowPeriodUpdated(200 seconds);
-        proxy.updateExitEscrowPeriod(200 seconds);
+        emit StakeTableV2.ExitEscrowPeriodUpdated(2 days);
+        proxy.updateExitEscrowPeriod(2 days);
         vm.stopPrank();
 
         vm.prank(initialOwner);
-        proxy.updateExitEscrowPeriod(200 seconds);
+        proxy.updateExitEscrowPeriod(2 days);
     }
 
     function test_TransferOwnership_Success() public {
@@ -170,7 +171,7 @@ contract StakeTableV2GovernanceTest is Test {
         vm.stopPrank();
 
         vm.prank(initialOwner);
-        proxy.updateExitEscrowPeriod(200 seconds);
+        proxy.updateExitEscrowPeriod(2 days);
     }
 
     function test_TransferOwnership_RevertsWhenNotAdmin() public {
@@ -196,7 +197,7 @@ contract StakeTableV2GovernanceTest is Test {
 
         vm.startPrank(newOwner);
 
-        uint64 newPeriod = 200 seconds;
+        uint64 newPeriod = 2 days;
         proxy.updateExitEscrowPeriod(newPeriod);
 
         proxy.grantRole(proxy.PAUSER_ROLE(), newOwner);
@@ -221,7 +222,7 @@ contract StakeTableV2GovernanceTest is Test {
                 IAccessControl.AccessControlUnauthorizedAccount.selector, initialOwner, adminRole
             )
         );
-        proxy.updateExitEscrowPeriod(200 seconds);
+        proxy.updateExitEscrowPeriod(2 days);
         vm.stopPrank();
     }