feature: arbitrator for early withdrawals

Author: eigenmikem

src/contracts/interfaces/IDurationVaultStrategy.sol

@@ -17,6 +17,10 @@ interface IDurationVaultStrategyErrors {
     error InvalidDuration();
     /// @dev Thrown when attempting to mutate configuration from a non-admin.
     error OnlyVaultAdmin();
+    /// @dev Thrown when attempting to call arbitrator-only functionality from a non-arbitrator.
+    error OnlyArbitrator();
+    /// @dev Thrown when attempting to configure a zero-address arbitrator.
+    error InvalidArbitrator();
     /// @dev Thrown when attempting to lock an already locked vault.
     error VaultAlreadyLocked();
     /// @dev Thrown when attempting to deposit after the vault has been locked.
@@ -27,6 +31,10 @@ interface IDurationVaultStrategyErrors {
     error MustBeDelegatedToVaultOperator();
     /// @dev Thrown when attempting to mark the vault as matured before duration elapses.
     error DurationNotElapsed();
+    /// @dev Thrown when attempting to use the arbitrator early-advance after the duration has elapsed.
+    error DurationAlreadyElapsed();
+    /// @dev Thrown when attempting to use the arbitrator early-advance before the vault is locked.
+    error VaultNotLocked();
     /// @dev Thrown when operator integration inputs are missing or invalid.
     error OperatorIntegrationInvalid();
     /// @dev Thrown when attempting to deposit into a vault whose underlying token is blacklisted.
@@ -61,6 +69,7 @@ interface IDurationVaultStrategyTypes {
     struct VaultConfig {
         IERC20 underlyingToken;
         address vaultAdmin;
+        address arbitrator;
         uint32 duration;
         uint256 maxPerDeposit;
         uint256 stakeCap;
@@ -99,6 +108,11 @@ interface IDurationVaultStrategyEvents {
     /// @param maturedAt Timestamp when the vault matured.
     event VaultMatured(uint32 maturedAt);
 
+    /// @notice Emitted when the vault is advanced to WITHDRAWALS early by the arbitrator.
+    /// @param arbitrator The arbitrator that performed the early advance.
+    /// @param maturedAt Timestamp when the vault transitioned to WITHDRAWALS.
+    event VaultAdvancedToWithdrawals(address indexed arbitrator, uint32 maturedAt);
+
     /// @notice Emitted when the vault metadata URI is updated.
     /// @param newMetadataURI The new metadata URI.
     event MetadataURIUpdated(string newMetadataURI);
@@ -138,6 +152,11 @@ interface IDurationVaultStrategy is
     /// the duration has elapsed.
     function markMatured() external;
 
+    /// @notice Advances the vault to WITHDRAWALS early, after lock but before duration elapses.
+    /// @dev Transitions state from ALLOCATIONS to WITHDRAWALS, and triggers the same best-effort operator cleanup
+    /// as `markMatured()`. Only callable by the configured arbitrator.
+    function advanceToWithdrawals() external;
+
     /// @notice Updates the vault metadata URI.
     /// @param newMetadataURI The new metadata URI to set.
     /// @dev Only callable by the vault admin.
@@ -157,6 +176,9 @@ interface IDurationVaultStrategy is
     /// @notice Returns the vault administrator address.
     function vaultAdmin() external view returns (address);
 
+    /// @notice Returns the arbitrator address.
+    function arbitrator() external view returns (address);
+
     /// @notice Returns the configured lock duration in seconds.
     function duration() external view returns (uint32);
 

src/contracts/strategies/DurationVaultStrategy.sol

@@ -43,6 +43,12 @@ contract DurationVaultStrategy is DurationVaultStrategyStorage, StrategyBase {
         _;
     }
 
+    /// @dev Restricts function access to the vault arbitrator.
+    modifier onlyArbitrator() {
+        require(msg.sender == arbitrator, OnlyArbitrator());
+        _;
+    }
+
     /// @param _strategyManager The StrategyManager contract.
     /// @param _pauserRegistry The PauserRegistry contract.
     /// @param _delegationManager The DelegationManager contract for operator registration.
@@ -75,11 +81,13 @@ contract DurationVaultStrategy is DurationVaultStrategyStorage, StrategyBase {
         VaultConfig memory config
     ) public initializer {
         require(config.vaultAdmin != address(0), InvalidVaultAdmin());
+        require(config.arbitrator != address(0), InvalidArbitrator());
         require(config.duration != 0 && config.duration <= MAX_DURATION, InvalidDuration());
         _setTVLLimits(config.maxPerDeposit, config.stakeCap);
         _initializeStrategyBase(config.underlyingToken);
 
         vaultAdmin = config.vaultAdmin;
+        arbitrator = config.arbitrator;
         duration = config.duration;
         metadataURI = config.metadataURI;
 
@@ -127,6 +135,26 @@ contract DurationVaultStrategy is DurationVaultStrategyStorage, StrategyBase {
         _deregisterFromOperatorSet();
     }
 
+    /// @notice Advances the vault to withdrawals early, after lock but before duration elapses.
+    /// @dev Only callable by the configured arbitrator.
+    function advanceToWithdrawals() external override onlyArbitrator {
+        if (_state == VaultState.WITHDRAWALS) {
+            // already recorded; noop
+            return;
+        }
+        require(_state == VaultState.ALLOCATIONS, VaultNotLocked());
+        require(block.timestamp < unlockAt, DurationAlreadyElapsed());
+
+        _state = VaultState.WITHDRAWALS;
+        maturedAt = uint32(block.timestamp);
+
+        emit VaultMatured(maturedAt);
+        emit VaultAdvancedToWithdrawals(msg.sender, maturedAt);
+
+        _deallocateAll();
+        _deregisterFromOperatorSet();
+    }
+
     /// @notice Updates the metadata URI describing the vault.
     function updateMetadataURI(
         string calldata newMetadataURI

src/contracts/strategies/DurationVaultStrategyStorage.sol

@@ -17,6 +17,9 @@ abstract contract DurationVaultStrategyStorage is IDurationVaultStrategy {
     /// @notice Address empowered to configure and lock the vault.
     address public vaultAdmin;
 
+    /// @notice Address empowered to advance the vault to withdrawals early (after lock, before duration elapses).
+    address public arbitrator;
+
     /// @notice The enforced lock duration once `lock` is called.
     uint32 public duration;
 
@@ -46,8 +49,8 @@ abstract contract DurationVaultStrategyStorage is IDurationVaultStrategy {
 
     /// @dev This empty reserved space is put in place to allow future versions to add new
     /// variables without shifting down storage in the inheritance chain.
-    /// Storage slots used: vaultAdmin (1) + duration/lockedAt/unlockAt/maturedAt/_state (packed, 1) +
+    /// Storage slots used: vaultAdmin (1) + arbitrator (1) + duration/lockedAt/unlockAt/maturedAt/_state (packed, 1) +
     /// metadataURI (1) + _operatorSet (1) + maxPerDeposit (1) + maxTotalDeposits (1) = 6.
-    /// Gap: 50 - 6 = 44.
-    uint256[44] private __gap;
+    /// Gap: 50 - 7 = 43.
+    uint256[43] private __gap;
 }

src/test/integration/tests/DurationVaultIntegration.t.sol

@@ -201,6 +201,50 @@ contract Integration_DurationVault is IntegrationCheckUtils {
         assertEq(ctx.asset.balanceOf(address(staker)), depositAmount, "staker should recover deposit");
     }
 
+    function test_durationVault_arbitrator_can_advance_to_withdrawals_early() public {
+        DurationVaultContext memory ctx = _deployDurationVault(_randomInsuranceRecipient());
+        User staker = new User("duration-arbitrator-staker");
+
+        uint depositAmount = 50 ether;
+        ctx.asset.transfer(address(staker), depositAmount);
+        IStrategy[] memory strategies = _durationStrategyArray(ctx.vault);
+        uint[] memory tokenBalances = _singleAmountArray(depositAmount);
+        _delegateToVault(staker, ctx.vault);
+        staker.depositIntoEigenlayer(strategies, tokenBalances);
+
+        // Arbitrator cannot advance before lock.
+        cheats.expectRevert(IDurationVaultStrategyErrors.VaultNotLocked.selector);
+        ctx.vault.advanceToWithdrawals();
+
+        ctx.vault.lock();
+        assertTrue(ctx.vault.allocationsActive(), "allocations should be active after lock");
+        assertFalse(ctx.vault.withdrawalsOpen(), "withdrawals should be closed while locked");
+
+        // Non-arbitrator cannot advance.
+        cheats.prank(address(0x1234));
+        cheats.expectRevert(IDurationVaultStrategyErrors.OnlyArbitrator.selector);
+        ctx.vault.advanceToWithdrawals();
+
+        // Arbitrator can advance after lock but before duration elapses.
+        cheats.warp(block.timestamp + 1);
+        ctx.vault.advanceToWithdrawals();
+
+        assertTrue(ctx.vault.withdrawalsOpen(), "withdrawals should open after arbitrator advance");
+        assertFalse(ctx.vault.allocationsActive(), "allocations should be inactive after arbitrator advance");
+        assertTrue(ctx.vault.isMatured(), "vault should be matured after arbitrator advance");
+
+        // Withdrawals should actually be possible in this early-advance path.
+        uint[] memory withdrawableShares = _getStakerWithdrawableShares(staker, strategies);
+        Withdrawal[] memory withdrawals = staker.queueWithdrawals(strategies, withdrawableShares);
+        _rollBlocksForCompleteWithdrawals(withdrawals);
+        IERC20[] memory tokens = staker.completeWithdrawalAsTokens(withdrawals[0]);
+        assertEq(address(tokens[0]), address(ctx.asset), "unexpected token returned");
+        assertEq(ctx.asset.balanceOf(address(staker)), depositAmount, "staker should recover deposit after arbitrator advance");
+
+        // markMatured should be a noop after the state has already transitioned.
+        ctx.vault.markMatured();
+    }
+
     function test_durationVault_operatorIntegrationAndMetadataUpdate() public {
         DurationVaultContext memory ctx = _deployDurationVault(_randomInsuranceRecipient());
 
@@ -396,6 +440,7 @@ contract Integration_DurationVault is IntegrationCheckUtils {
         IDurationVaultStrategyTypes.VaultConfig memory config;
         config.underlyingToken = asset;
         config.vaultAdmin = address(this);
+        config.arbitrator = address(this);
         config.duration = DEFAULT_DURATION;
         config.maxPerDeposit = VAULT_MAX_PER_DEPOSIT;
         config.stakeCap = VAULT_STAKE_CAP;

src/test/unit/DurationVaultStrategyUnit.t.sol

@@ -57,6 +57,7 @@ contract DurationVaultStrategyUnitTests is StrategyBaseUnitTests {
         IDurationVaultStrategyTypes.VaultConfig memory config = IDurationVaultStrategyTypes.VaultConfig({
             underlyingToken: underlyingToken,
             vaultAdmin: address(this),
+            arbitrator: address(this),
             duration: defaultDuration,
             maxPerDeposit: maxPerDeposit,
             stakeCap: maxTotalDeposits,
@@ -168,6 +169,28 @@ contract DurationVaultStrategyUnitTests is StrategyBaseUnitTests {
         assertEq(allocationManagerMock.deregisterFromOperatorSetsCallCount(), 0, "unexpected deregister count");
     }
 
+    function testAdvanceToWithdrawals_onlyArbitrator_and_onlyBeforeUnlock() public {
+        // Cannot advance before lock (even as arbitrator).
+        cheats.expectRevert(IDurationVaultStrategyErrors.VaultNotLocked.selector);
+        durationVault.advanceToWithdrawals();
+
+        durationVault.lock();
+
+        // Non-arbitrator cannot advance.
+        cheats.prank(address(0xBEEF));
+        cheats.expectRevert(IDurationVaultStrategyErrors.OnlyArbitrator.selector);
+        durationVault.advanceToWithdrawals();
+
+        // After unlockAt, arbitrator advance is not allowed.
+        cheats.warp(block.timestamp + defaultDuration + 1);
+        cheats.expectRevert(IDurationVaultStrategyErrors.DurationAlreadyElapsed.selector);
+        durationVault.advanceToWithdrawals();
+
+        // markMatured works once duration has elapsed.
+        durationVault.markMatured();
+        assertTrue(durationVault.withdrawalsOpen(), "withdrawals should open after maturity");
+    }
+
     // ===================== VAULT STATE TESTS =====================
 
     function testDepositsBlockedAfterLock() public {

src/test/unit/StrategyFactoryUnit.t.sol

@@ -151,6 +151,7 @@ contract StrategyFactoryUnitTests is EigenLayerUnitTestSetup {
         IDurationVaultStrategyTypes.VaultConfig memory config = IDurationVaultStrategyTypes.VaultConfig({
             underlyingToken: underlyingToken,
             vaultAdmin: address(this),
+            arbitrator: address(this),
             duration: uint32(30 days),
             maxPerDeposit: 10 ether,
             stakeCap: 100 ether,
@@ -176,6 +177,7 @@ contract StrategyFactoryUnitTests is EigenLayerUnitTestSetup {
         IDurationVaultStrategyTypes.VaultConfig memory config = IDurationVaultStrategyTypes.VaultConfig({
             underlyingToken: underlyingToken,
             vaultAdmin: address(this),
+            arbitrator: address(this),
             duration: uint32(7 days),
             maxPerDeposit: 5 ether,
             stakeCap: 50 ether,

src/test/unit/StrategyManagerDurationUnit.t.sol

@@ -73,6 +73,7 @@ contract StrategyManagerDurationUnitTests is EigenLayerUnitTestSetup, IStrategyM
         IDurationVaultStrategyTypes.VaultConfig memory cfg = IDurationVaultStrategyTypes.VaultConfig({
             underlyingToken: IERC20(address(underlyingToken)),
             vaultAdmin: address(this),
+            arbitrator: address(this),
             duration: uint32(30 days),
             maxPerDeposit: 1_000_000 ether,
             stakeCap: 10_000_000 ether,