fix(BUG-8): clarify cooldownDuration units as seconds in NatSpec

contracts/interfaces/ISSVDAO.sol

@@ -94,7 +94,7 @@ interface ISSVDAO is ISSVNetworkCore {
 
     /**
      * @dev Emitted when the unstake cooldown duration is updated
-     * @param newCooldownDuration The new duration
+     * @param newCooldownDuration The new duration in seconds
      */
     event CooldownDurationUpdated(uint64 newCooldownDuration);
 
@@ -204,7 +204,7 @@ interface ISSVDAO is ISSVNetworkCore {
 
     /**
      * @notice Sets the unstake cooldown duration
-     * @param duration The new duration
+     * @param duration The new duration in seconds
      */
     function setUnstakeCooldownDuration(uint64 duration) external;
 

contracts/libraries/storage/SSVStorageStaking.sol

@@ -13,6 +13,7 @@ struct UnstakeRequest {
 }
 
 struct StorageStaking {
+    /// @notice Unstake cooldown duration in seconds
     uint64 cooldownDuration;
     /// @notice Total ETH-denominated rewards (shrunk) allocated to the staking pool
     PackedETH stakingEthPoolBalance;

contracts/upgrades/stage/hoodi/SSVNetworkSSVStakingUpgrade.sol

@@ -5,6 +5,9 @@ import "../../../SSVNetwork.sol";
 import {MAX_DELEGATION_SLOTS} from "../../../libraries/storage/SSVStorageStaking.sol";
 
 contract SSVNetworkSSVStakingUpgrade is SSVNetwork {
+    /// @notice One-time initializer for the SSV Staking upgrade
+    /// @param cooldownDuration Unstake cooldown duration in seconds (e.g. 604800 for 7 days)
+    /// @param defaultOracleIds Default oracle IDs for new delegations
     function initializeSSVStaking(
         uint64 cooldownDuration,
         uint32[MAX_DELEGATION_SLOTS] memory defaultOracleIds,

ssv-review/planning/MAINNET-READINESS.md

@@ -18,7 +18,7 @@
 | BUG-5 | ~~`_liquidateAfterEBUpdateIfNeeded` condition too strict for ETH-only operators~~ | Critical Bug Fix | P1 | ✅ Fixed |
 | BUG-6 | Rewards lost when `totalStaked == 0` in staking `_syncFees` | Critical Bug Fix | P1 | ✅ Mitigated (deployment) |
 | BUG-7 | ~~`DEFAULT_OPERATOR_ETH_FEE` value deviates from DIP-X spec~~ | ~~Critical Bug Fix~~ | ~~P1~~ | ✅ Closed (negligible) |
-| BUG-8 | Cooldown duration uses `block.timestamp` but DIP specifies blocks | Critical Bug Fix |P1 | ❓ Asked Product to change DIP (not a bug) |
+| BUG-8 | ~~ Cooldown duration uses `block.timestamp` but DIP specifies blocks~~ | ~~Critical Bug Fix~~ | ~~P1~~ | ✅ Closed (not a bug, added NatSpec) |
 | BUG-9 | ~~`uint64(delta)` silent truncation in operator earnings accumulation~~ | ~~Critical Bug Fix~~ | ~~P1~~ | ✅ Closed (not realistic) |
 | BUG-10 | Remove liquidation check in `withdraw` function | Critical Bug Fix | P2 | ⚠️ Needs Product approval |
 | BUG-11 | `removeValidator` / `bulkRemoveValidator` blocked for legacy SSV clusters | Critical Bug Fix | P1 | ⚠️ Needs Product approval |

test/unit/SSVStaking/requestUnstake.test.ts

@@ -187,6 +187,27 @@ describe("SSVStaking function `requestUnstake()`", async () => {
     expect(cssvBalance).to.equal(STAKE_AMOUNT - firstAmount - secondAmount);
   });
 
+  it("Uses block.timestamp (seconds) for unlockTime, not block.number", async function () {
+    const { staking } = await networkHelpers.loadFixture(stakeFirst);
+
+    const unstakeAmount = STAKE_AMOUNT / 2n;
+    const receipt = await trackGas(
+      staking.requestUnstake(unstakeAmount),
+      [GasGroup.REQUEST_UNSTAKE]
+    );
+
+    const block = await connection.ethers.provider.getBlock(receipt.blockNumber);
+    const [, unlockTime] = await staking.getWithdrawalRequest(staker.address, 0);
+
+    // unlockTime must equal block.timestamp + cooldown (seconds-based)
+    const expectedFromTimestamp = BigInt(block!.timestamp) + DEFAULT_UNSTAKE_COOLDOWN;
+    expect(unlockTime).to.equal(expectedFromTimestamp);
+
+    // unlockTime must NOT equal block.number + cooldown (blocks-based)
+    const incorrectFromBlockNumber = BigInt(block!.number) + DEFAULT_UNSTAKE_COOLDOWN;
+    expect(unlockTime).to.not.equal(incorrectFromBlockNumber);
+  });
+
   it("Settles pending rewards before unstaking when fees have accrued", async function () {
     const { staking, cssvToken } = await networkHelpers.loadFixture(stakeFirst);