feat: queue flushing update

Author: LHerskind

l1-contracts/script/StakingAssetHandler.s.sol

@@ -57,7 +57,8 @@ contract StakingAssetHandlerScript is Test {
       domain: DOMAIN,
       scope: SCOPE,
       skipBindCheck: false, // DO NOT: skip bind check
-      skipMerkleCheck: true // DO: skip merkle check
+      skipMerkleCheck: true, // DO: skip merkle check
+      validatorsToFlush: 48
     });
 
     vm.startBroadcast(ME);

l1-contracts/src/core/Rollup.sol

@@ -534,6 +534,14 @@ contract Rollup is IStaking, IValidatorSelection, IRollup, RollupCore {
     return RewardLib.getBlockReward();
   }
 
+  function getAvailableValidatorFlushes() external view override(IStaking) returns (uint256) {
+    return ValidatorOperationsExtLib.getAvailableValidatorFlushes();
+  }
+
+  function getIsBootstrapped() external view override(IStaking) returns (bool) {
+    return StakingLib.getStorage().isBootstrapped;
+  }
+
   function getBurnAddress() external pure override(IRollup) returns (address) {
     return RewardLib.BURN_ADDRESS;
   }

l1-contracts/src/core/RollupCore.sol

@@ -228,6 +228,7 @@ contract RollupCore is EIP712("Aztec Rollup", "1"), Ownable, IStakingCore, IVali
     // from the onset). It might be updated later to 0 by governance in order to close the validator set for this
     // instance. For details see `StakingLib.getEntryQueueFlushSize` function.
     require(_config.stakingQueueConfig.normalFlushSizeMin > 0, Errors.Staking__InvalidStakingQueueConfig());
+    require(_config.stakingQueueConfig.normalFlushSizeQuotient > 0, Errors.Staking__InvalidNormalFlushSizeQuotient());
 
     TimeLib.initialize(
       block.timestamp, _config.aztecSlotDuration, _config.aztecEpochDuration, _config.aztecProofSubmissionEpochs
@@ -448,9 +449,14 @@ contract RollupCore is EIP712("Aztec Rollup", "1"), Ownable, IStakingCore, IVali
    * @notice Processes the validator entry queue to add new validators to the active set
    * @dev Can be called by anyone. The number of validators added is limited by queue configuration.
    *      This helps maintain a controlled growth rate of the validator set.
+   * @param _toAdd - The max number the caller will try to add
    */
+  function flushEntryQueue(uint256 _toAdd) external override(IStakingCore) {
+    ValidatorOperationsExtLib.flushEntryQueue(_toAdd);
+  }
+
   function flushEntryQueue() external override(IStakingCore) {
-    ValidatorOperationsExtLib.flushEntryQueue();
+    ValidatorOperationsExtLib.flushEntryQueue(type(uint256).max);
   }
 
   /**

l1-contracts/src/core/interfaces/IStaking.sol

@@ -46,6 +46,7 @@ interface IStakingCore {
     bool _moveWithLatestRollup
   ) external;
   function flushEntryQueue() external;
+  function flushEntryQueue(uint256 _toAdd) external;
   function initiateWithdraw(address _attester, address _recipient) external returns (bool);
   function finalizeWithdraw(address _attester) external;
   function slash(address _attester, uint256 _amount) external returns (bool);
@@ -71,4 +72,6 @@ interface IStaking is IStakingCore {
   function getStatus(address _attester) external view returns (Status);
   function getNextFlushableEpoch() external view returns (Epoch);
   function getEntryQueueLength() external view returns (uint256);
+  function getAvailableValidatorFlushes() external view returns (uint256);
+  function getIsBootstrapped() external view returns (bool);
 }

l1-contracts/src/core/libraries/Errors.sol

@@ -149,6 +149,7 @@ library Errors {
   error Staking__GovernanceAlreadySet();
   error Staking__InsufficientBootstrapValidators(uint256 queueSize, uint256 bootstrapFlushSize);
   error Staking__InvalidStakingQueueConfig();
+  error Staking__InvalidNormalFlushSizeQuotient();
 
   // Fee Juice Portal
   error FeeJuicePortal__AlreadyInitialized(); // 0xc7a172fe

l1-contracts/src/core/libraries/rollup/StakingLib.sol

@@ -17,7 +17,9 @@ import {Proposal} from "@aztec/governance/interfaces/IGovernance.sol";
 import {ProposalLib} from "@aztec/governance/libraries/ProposalLib.sol";
 import {GovernanceProposer} from "@aztec/governance/proposer/GovernanceProposer.sol";
 import {G1Point, G2Point} from "@aztec/shared/libraries/BN254Lib.sol";
-import {CompressedTimeMath, CompressedTimestamp} from "@aztec/shared/libraries/CompressedTimeMath.sol";
+import {
+  CompressedTimeMath, CompressedTimestamp, CompressedEpoch
+} from "@aztec/shared/libraries/CompressedTimeMath.sol";
 import {IERC20} from "@oz/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@oz/token/ERC20/utils/SafeERC20.sol";
 import {Math} from "@oz/utils/math/Math.sol";
@@ -78,13 +80,15 @@ struct AttesterView {
 struct StakingStorage {
   IERC20 stakingAsset;
   address slasher;
+  uint96 localEjectionThreshold;
   GSE gse;
   CompressedTimestamp exitDelay;
   mapping(address attester => Exit) exits;
   CompressedStakingQueueConfig queueConfig;
   StakingQueue entryQueue;
-  Epoch nextFlushableEpoch;
-  uint256 localEjectionThreshold;
+  CompressedEpoch nextFlushableEpoch;
+  uint32 availableValidatorFlushes;
+  bool isBootstrapped;
 }
 
 library StakingLib {
@@ -96,6 +100,8 @@ library StakingLib {
   using StakingQueueConfigLib for StakingQueueConfig;
   using CompressedTimeMath for CompressedTimestamp;
   using CompressedTimeMath for Timestamp;
+  using CompressedTimeMath for CompressedEpoch;
+  using CompressedTimeMath for Epoch;
 
   bytes32 private constant STAKING_SLOT = keccak256("aztec.core.staking.storage");
 
@@ -114,7 +120,7 @@ library StakingLib {
     store.slasher = _slasher;
     store.queueConfig = _config.compress();
     store.entryQueue.init();
-    store.localEjectionThreshold = _localEjectionThreshold;
+    store.localEjectionThreshold = _localEjectionThreshold.toUint96();
   }
 
   function setSlasher(address _slasher) internal {
@@ -130,7 +136,7 @@ library StakingLib {
     StakingStorage storage store = getStorage();
 
     uint256 oldLocalEjectionThreshold = store.localEjectionThreshold;
-    store.localEjectionThreshold = _localEjectionThreshold;
+    store.localEjectionThreshold = _localEjectionThreshold.toUint96();
 
     emit IStakingCore.LocalEjectionThresholdUpdated(oldLocalEjectionThreshold, _localEjectionThreshold);
   }
@@ -304,10 +310,22 @@ library StakingLib {
     emit IStakingCore.ValidatorQueued(_attester, _withdrawer);
   }
 
+  function updateAndGetAvailableFlushes() internal returns (uint256) {
+    (uint256 flushes, Epoch currentEpoch, bool shouldUpdateState) = _calculateAvailableFlushes();
+
+    if (shouldUpdateState) {
+      StakingStorage storage store = getStorage();
+      store.nextFlushableEpoch = (currentEpoch + Epoch.wrap(1)).compress();
+      store.availableValidatorFlushes = flushes.toUint32();
+    }
+
+    return flushes;
+  }
+
   /**
    * @notice Processes the validator entry queue to add new validators to the active set
-   * @dev Processes up to _maxAddableValidators entries from the queue, attempting to deposit each validator into
-   *      the Governance Staking Escrow (GSE).
+   * @dev Processes up to min(maxAddableValidators, _toAdd) entries from the queue,
+   *      attempting to deposit each validator into the Governance Staking Escrow (GSE).
    *
    *      For each validator:
    *      - Dequeues their entry from the queue
@@ -316,34 +334,34 @@ library StakingLib {
    *      - On failure: refunds their stake and emits FailedDeposit event
    *
    *      The function will revert if:
-   *      - The current epoch is before nextFlushableEpoch (max 1 flush per epoch). This limit:
-   *        1. Controls validator set growth by only allowing a fixed number of additions per epoch (we can flush at
-   *           most maxQueueFlushSize validators at once - hence the limit)
-   *        2. Aligns with committee selection which happens once per epoch anyway
-   *        3. Groups validator additions into epoch-sized chunks for efficient binary searches (fewer snapshots in
-   *           GSE)
    *      - A deposit fails due to out of gas (to prevent queue draining attacks)
    *
    *      The function approves the GSE contract to spend the total stake amount needed for all deposits,
    *      then revokes the approval after processing is complete.
+   *      It also updates the available validator flushes
    *
+   * @param _toAdd - The max number the caller will try to add
    */
-  function flushEntryQueue() internal {
-    uint256 maxAddableValidators = getEntryQueueFlushSize();
+  function flushEntryQueue(uint256 _toAdd) internal {
+    uint256 maxAddableValidators = updateAndGetAvailableFlushes();
+
     if (maxAddableValidators == 0) {
       return;
     }
 
-    Epoch currentEpoch = TimeLib.epochFromTimestamp(Timestamp.wrap(block.timestamp));
     StakingStorage storage store = getStorage();
-    require(store.nextFlushableEpoch <= currentEpoch, Errors.Staking__QueueAlreadyFlushed(currentEpoch));
-    store.nextFlushableEpoch = currentEpoch + Epoch.wrap(1);
-    uint256 amount = store.gse.ACTIVATION_THRESHOLD();
 
     uint256 queueLength = store.entryQueue.length();
-    uint256 numToDequeue = Math.min(maxAddableValidators, queueLength);
+    uint256 numToDequeue = Math.min(Math.min(maxAddableValidators, queueLength), _toAdd);
+
+    if (numToDequeue == 0) {
+      return;
+    }
+
     // Approve the GSE to spend the total stake amount needed for all deposits.
+    uint256 amount = store.gse.ACTIVATION_THRESHOLD();
     store.stakingAsset.approve(address(store.gse), amount * numToDequeue);
+    uint256 depositCount = 0;
     for (uint256 i = 0; i < numToDequeue; i++) {
       DepositArgs memory args = store.entryQueue.dequeue();
       (bool success, bytes memory data) = address(store.gse).call(
@@ -358,6 +376,7 @@ library StakingLib {
         )
       );
       if (success) {
+        depositCount++;
         emit IStakingCore.Deposit(
           args.attester, args.withdrawer, args.publicKeyInG1, args.publicKeyInG2, args.proofOfPossession, amount
         );
@@ -376,6 +395,17 @@ library StakingLib {
       }
     }
     store.stakingAsset.approve(address(store.gse), 0);
+
+    store.availableValidatorFlushes -= depositCount.toUint32();
+
+    // If we have reached the bootstrap size, mark it as bootstrapped such that we don't re-enter it.
+    if (
+      !store.isBootstrapped
+        && getAttesterCountAtTime(Timestamp.wrap(block.timestamp))
+          >= store.queueConfig.decompress().bootstrapValidatorSetSize
+    ) {
+      store.isBootstrapped = true;
+    }
   }
 
   /**
@@ -442,7 +472,7 @@ library StakingLib {
   }
 
   function getNextFlushableEpoch() internal view returns (Epoch) {
-    return getStorage().nextFlushableEpoch;
+    return getStorage().nextFlushableEpoch.decompress();
   }
 
   function getEntryQueueLength() internal view returns (uint256) {
@@ -533,39 +563,66 @@ library StakingLib {
    *      `normalFlushSizeMin` to zero and `normalFlushSizeQuotient` to a very high value. If this is done, this
    *      function will always return zero and no new validator can enter.
    *
+   * @param _activeAttesterCount - The number of active attesters
    * @return - The maximum number of validators that could be flushed from the entry queue.
    */
-  function getEntryQueueFlushSize() internal view returns (uint256) {
+  function getEntryQueueFlushSize(uint256 _activeAttesterCount) internal view returns (uint256) {
     StakingStorage storage store = getStorage();
     StakingQueueConfig memory config = store.queueConfig.decompress();
 
-    uint256 activeAttesterCount = getAttesterCountAtTime(Timestamp.wrap(block.timestamp));
     uint256 queueSize = store.entryQueue.length();
 
     // Only if there is bootstrap values configured will we look into bootstrap or growth phases.
-    if (config.bootstrapValidatorSetSize > 0) {
+    if (config.bootstrapValidatorSetSize > 0 && !store.isBootstrapped) {
       // If bootstrap:
-      if (activeAttesterCount == 0 && queueSize < config.bootstrapValidatorSetSize) {
+      if (_activeAttesterCount == 0 && queueSize < config.bootstrapValidatorSetSize) {
         return 0;
       }
 
       // If growth:
-      if (activeAttesterCount < config.bootstrapValidatorSetSize) {
-        return Math.min(config.bootstrapFlushSize, config.maxQueueFlushSize);
+      if (_activeAttesterCount < config.bootstrapValidatorSetSize) {
+        return config.bootstrapFlushSize;
       }
     }
 
     // If normal:
     return Math.min(
-      Math.max(activeAttesterCount / config.normalFlushSizeQuotient, config.normalFlushSizeMin),
+      Math.max(_activeAttesterCount / config.normalFlushSizeQuotient, config.normalFlushSizeMin),
       config.maxQueueFlushSize
     );
   }
 
+  function getAvailableValidatorFlushes() internal view returns (uint256) {
+    (uint256 flushes,,) = _calculateAvailableFlushes();
+    return flushes;
+  }
+
+  function getCachedAvailableValidatorFlushes() internal view returns (uint256) {
+    return getStorage().availableValidatorFlushes;
+  }
+
   function getStorage() internal pure returns (StakingStorage storage storageStruct) {
     bytes32 position = STAKING_SLOT;
     assembly {
       storageStruct.slot := position
     }
   }
+
+  function _calculateAvailableFlushes()
+    private
+    view
+    returns (uint256 flushes, Epoch currentEpoch, bool shouldUpdateState)
+  {
+    StakingStorage storage store = getStorage();
+    currentEpoch = TimeLib.epochFromTimestamp(Timestamp.wrap(block.timestamp));
+
+    if (store.nextFlushableEpoch.decompress() > currentEpoch) {
+      return (store.availableValidatorFlushes, currentEpoch, false);
+    }
+
+    uint256 activeAttesterCount = getAttesterCountAtTime(Timestamp.wrap(block.timestamp));
+    uint256 newFlushes = getEntryQueueFlushSize(activeAttesterCount);
+
+    return (newFlushes, currentEpoch, true);
+  }
 }

l1-contracts/src/core/libraries/rollup/ValidatorOperationsExtLib.sol

@@ -54,8 +54,8 @@ library ValidatorOperationsExtLib {
     );
   }
 
-  function flushEntryQueue() external {
-    StakingLib.flushEntryQueue();
+  function flushEntryQueue(uint256 _toAdd) external {
+    StakingLib.flushEntryQueue(_toAdd);
   }
 
   function initiateWithdraw(address _attester, address _recipient) external returns (bool) {
@@ -138,6 +138,11 @@ library ValidatorOperationsExtLib {
   }
 
   function getEntryQueueFlushSize() external view returns (uint256) {
-    return StakingLib.getEntryQueueFlushSize();
+    uint256 activeAttesterCount = StakingLib.getAttesterCountAtTime(Timestamp.wrap(block.timestamp));
+    return StakingLib.getEntryQueueFlushSize(activeAttesterCount);
+  }
+
+  function getAvailableValidatorFlushes() external view returns (uint256) {
+    return StakingLib.getAvailableValidatorFlushes();
   }
 }

l1-contracts/src/mock/MultiAdder.sol

@@ -16,7 +16,7 @@ struct CheatDepositArgs {
 
 interface IMultiAdder {
   function addValidators(CheatDepositArgs[] memory _args) external;
-  function addValidators(CheatDepositArgs[] memory _args, bool _skipFlush) external;
+  function addValidators(CheatDepositArgs[] memory _args, uint256 _toFlush) external;
 }
 
 contract MultiAdder is IMultiAdder {
@@ -34,10 +34,10 @@ contract MultiAdder is IMultiAdder {
   }
 
   function addValidators(CheatDepositArgs[] memory _args) public override(IMultiAdder) {
-    addValidators(_args, false);
+    addValidators(_args, type(uint256).max);
   }
 
-  function addValidators(CheatDepositArgs[] memory _args, bool _skipFlush) public override(IMultiAdder) {
+  function addValidators(CheatDepositArgs[] memory _args, uint256 _toFlush) public override(IMultiAdder) {
     require(msg.sender == OWNER, NotOwner());
     for (uint256 i = 0; i < _args.length; i++) {
       STAKING.deposit(
@@ -50,8 +50,8 @@ contract MultiAdder is IMultiAdder {
       );
     }
 
-    if (!_skipFlush && STAKING.getCurrentEpoch() >= STAKING.getNextFlushableEpoch()) {
-      STAKING.flushEntryQueue();
+    if (_toFlush != 0) {
+      STAKING.flushEntryQueue(_toFlush);
     }
   }
 }