Additions and Updates to Specification and NatSpec

contracts/DualGovernance.sol

@@ -299,8 +299,8 @@ contract DualGovernance is IDualGovernance {
         _stateMachine.activateNextState();
     }
 
-    /// @notice Updates the address of the configuration provider for the Dual Governance system.
-    /// @param newConfigProvider The address of the new configuration provider contract.
+    /// @notice Sets the configuration provider for the Dual Governance system.
+    /// @param newConfigProvider The contract implementing the `IDualGovernanceConfigProvider` interface.
     function setConfigProvider(IDualGovernanceConfigProvider newConfigProvider) external {
         _checkCallerIsAdminExecutor();
         _stateMachine.setConfigProvider(newConfigProvider);
@@ -319,14 +319,14 @@ contract DualGovernance is IDualGovernance {
         emit ProposalsCancellerSet(newProposalsCanceller);
     }
 
-    /// @notice Retrieves the current proposals canceller address.
+    /// @notice Returns the current proposals canceller address.
     /// @return address The address of the current proposals canceller.
     function getProposalsCanceller() external view returns (address) {
         return _proposalsCanceller;
     }
 
-    /// @notice Returns the current configuration provider address for the Dual Governance system.
-    /// @return configProvider The address of the current configuration provider contract.
+    /// @notice Returns the current configuration provider for the Dual Governance system.
+    /// @return configProvider The contract implementing the `IDualGovernanceConfigProvider` interface.
     function getConfigProvider() external view returns (IDualGovernanceConfigProvider) {
         return _stateMachine.configProvider;
     }
@@ -412,7 +412,7 @@ contract DualGovernance is IDualGovernance {
     }
 
     /// @notice Returns the proposer data if the given `proposerAccount` is a registered proposer.
-    /// @param proposerAccount The address of the proposer to retrieve information for.
+    /// @param proposerAccount The address of the proposer to return information for.
     /// @return proposer A Proposer struct containing the data of the registered proposer, including:
     ///     - `account`: The address of the registered proposer.
     ///     - `executor`: The address of the executor associated with the proposer.
@@ -426,15 +426,15 @@ contract DualGovernance is IDualGovernance {
         proposers = _proposers.getAllProposers();
     }
 
-    /// @notice Checks whether the given `proposerAccount` is a registered proposer.
+    /// @notice Returns whether the given `proposerAccount` is a registered proposer.
     /// @param proposerAccount The address to check.
     /// @return isProposer A boolean value indicating whether the `proposerAccount` is a registered
     ///     proposer (`true`) or not (`false`).
     function isProposer(address proposerAccount) external view returns (bool) {
         return _proposers.isRegisteredProposer(proposerAccount);
     }
 
-    /// @notice Checks whether the given `executor` address is associated with an executor contract in the system.
+    /// @notice Returns whether the given `executor` address is associated with an executor contract in the system.
     /// @param executor The address to check.
     /// @return isExecutor A boolean value indicating whether the `executor` is a registered
     ///     executor (`true`) or not (`false`).
@@ -536,20 +536,20 @@ contract DualGovernance is IDualGovernance {
         _resealer.setResealCommittee(newResealCommittee);
     }
 
-    /// @notice Sets the address of the Reseal Manager.
-    /// @param newResealManager The address of the new Reseal Manager.
+    /// @notice Sets the address of the Reseal Manager contract.
+    /// @param newResealManager The contract implementing the `IResealManager` interface.
     function setResealManager(IResealManager newResealManager) external {
         _checkCallerIsAdminExecutor();
         _resealer.setResealManager(newResealManager);
     }
 
-    /// @notice Gets the address of the Reseal Manager.
-    /// @return resealManager The address of the Reseal Manager.
+    /// @notice Returns the address of the Reseal Manager contract.
+    /// @return resealManager The contract implementing the `IResealManager` interface.
     function getResealManager() external view returns (IResealManager) {
         return _resealer.resealManager;
     }
 
-    /// @notice Gets the address of the reseal committee.
+    /// @notice Returns the address of the reseal committee.
     /// @return resealCommittee The address of the reseal committee.
     function getResealCommittee() external view returns (address) {
         return _resealer.resealCommittee;

contracts/EmergencyProtectedTimelock.sol

@@ -12,10 +12,25 @@ import {TimelockState} from "./libraries/TimelockState.sol";
 import {ExecutableProposals} from "./libraries/ExecutableProposals.sol";
 import {EmergencyProtection} from "./libraries/EmergencyProtection.sol";
 
-/// @title EmergencyProtectedTimelock
-/// @dev A timelock contract with emergency protection functionality. The contract allows for submitting, scheduling,
-///     and executing proposals, while providing emergency protection features to prevent unauthorized execution during
-///     emergency situations.
+/// @notice Timelock contract facilitating the submission, scheduling, and execution of governance proposals.
+///     It provides time-limited Emergency Protection to prevent the execution of proposals submitted by
+///     a compromised or misbehaving (including those caused by code vulnerabilities) governance entity.
+/// @dev The proposal lifecycle:
+///
+///                                         afterSubmitDelay          afterScheduleDelay
+///                                              passed                     passed
+///     ┌──────────┐            ┌───────────┐              ┌───────────┐             ╔══════════╗
+///     │ NotExist ├ submit() ─>│ Submitted ├ schedule() ─>│ Scheduled ├ execute() ─>║ Executed ║
+///     └──────────┘            └────────┬──┘              └──┬────────┘             ╚══════════╝
+///                                  cancelAllNonExecutedProposals()
+///                                      │   ╔═══════════╗    │
+///                                      └──>║ Cancelled ║<───┘
+///                                          ╚═══════════╝
+///
+///     The afterSubmit and afterSchedule delays should be configured appropriately to provide the Emergency Activation
+///     Committee sufficient time to activate Emergency Mode if a malicious proposal has been submitted or was
+///     unexpectedly scheduled for execution due to governance capture or a vulnerability in the governance contract.
+///     While Emergency Mode is active, the execution of proposals is restricted to the Emergency Execution Committee.
 contract EmergencyProtectedTimelock is IEmergencyProtectedTimelock {
     using TimelockState for TimelockState.Context;
     using ExecutableProposals for ExecutableProposals.Context;
@@ -134,7 +149,7 @@ contract EmergencyProtectedTimelock is IEmergencyProtectedTimelock {
     // Timelock Management
     // ---
 
-    /// @notice Updates the address of the governance contract.
+    /// @notice Updates the address of the governance contract  and cancels all non-executed proposals.
     /// @param newGovernance The address of the new governance contract to be set.
     function setGovernance(address newGovernance) external {
         _timelockState.checkCallerIsAdminExecutor();
@@ -308,7 +323,7 @@ contract EmergencyProtectedTimelock is IEmergencyProtectedTimelock {
         return _timelockState.getAfterScheduleDelay();
     }
 
-    /// @notice Retrieves the details of a proposal.
+    /// @notice Returns the details of a proposal.
     /// @param proposalId The id of the proposal.
     /// @return proposalDetails The Proposal struct containing the details of the proposal.
     /// @return calls An array of ExternalCall structs representing the sequence of calls to be executed for the proposal.
@@ -321,12 +336,11 @@ contract EmergencyProtectedTimelock is IEmergencyProtectedTimelock {
         calls = _proposals.getProposalCalls(proposalId);
     }
 
-    /// @notice Retrieves information about a proposal, excluding the external calls associated with it.
-    /// @param proposalId The id of the proposal to retrieve information for.
+    /// @notice Returns information about a proposal, excluding the external calls associated with it.
+    /// @param proposalId The id of the proposal to return information for.
     /// @return proposalDetails A ProposalDetails struct containing the details of the proposal, with the following data:
     ///     - `id`: The id of the proposal.
     ///     - `status`: The current status of the proposal. Possible values are:
-    ///         0 - The proposal does not exist.
     ///         1 - The proposal was submitted but not scheduled.
     ///         2 - The proposal was submitted and scheduled but not yet executed.
     ///         3 - The proposal was submitted, scheduled, and executed. This is the final state of the proposal lifecycle.
@@ -340,14 +354,14 @@ contract EmergencyProtectedTimelock is IEmergencyProtectedTimelock {
         return _proposals.getProposalDetails(proposalId);
     }
 
-    /// @notice Retrieves the external calls associated with the specified proposal.
-    /// @param proposalId The id of the proposal to retrieve external calls for.
+    /// @notice Returns the external calls associated with the specified proposal.
+    /// @param proposalId The id of the proposal to return external calls for.
     /// @return calls An array of ExternalCall structs representing the sequence of calls to be executed for the proposal.
     function getProposalCalls(uint256 proposalId) external view returns (ExternalCall[] memory calls) {
         calls = _proposals.getProposalCalls(proposalId);
     }
 
-    /// @notice Retrieves the total number of proposals.
+    /// @notice Returns the total number of proposals.
     /// @return count The total number of proposals.
     function getProposalsCount() external view returns (uint256 count) {
         count = _proposals.getProposalsCount();

contracts/Escrow.sol

@@ -145,7 +145,7 @@ contract Escrow is ISignallingEscrow, IRageQuitEscrow {
         ST_ETH.approve(address(WITHDRAWAL_QUEUE), type(uint256).max);
     }
 
-    /// @notice Retrieves the current state of the Escrow.
+    /// @notice Returns the current state of the Escrow.
     /// @return State The current state of the Escrow.
     function getEscrowState() external view returns (State) {
         return _escrowState.state;
@@ -305,7 +305,7 @@ contract Escrow is ISignallingEscrow, IRageQuitEscrow {
     // ---
 
     /// @notice Sets the minimum duration that must elapse after the last stETH, wstETH, or unstETH lock
-    ///     by a vetoer before they are permitted to unlock their assets from the Escrow.
+    ///     by a vetoer before they are permitted to unlock their assets from the Signalling Escrow.
     /// @param newMinAssetsLockDuration The new minimum lock duration to be set.
     function setMinAssetsLockDuration(Duration newMinAssetsLockDuration) external {
         _checkCallerIsDualGovernance();
@@ -353,7 +353,7 @@ contract Escrow is ISignallingEscrow, IRageQuitEscrow {
         details.lastAssetsLockTimestamp = assets.lastAssetsLockTimestamp;
     }
 
-    // @notice Retrieves the unstETH NFT ids of the specified vetoer.
+    /// @notice Returns the unstETH NFT ids of the specified vetoer.
     /// @param vetoer The address of the vetoer whose unstETH NFTs are being queried.
     /// @return unstETHIds An array of unstETH NFT ids locked by the vetoer.
     function getVetoerUnstETHIds(address vetoer) external view returns (uint256[] memory unstETHIds) {
@@ -376,8 +376,8 @@ contract Escrow is ISignallingEscrow, IRageQuitEscrow {
         details.totalUnstETHFinalizedETH = unstETHTotals.finalizedETH;
     }
 
-    /// @notice Retrieves details of locked unstETH records for the given ids.
-    /// @param unstETHIds The array of ids for the unstETH records to retrieve.
+    /// @notice Returns details of locked unstETH records for the given ids.
+    /// @param unstETHIds The array of ids for the unstETH records to return.
     /// @return unstETHDetails An array of `LockedUnstETHDetails` containing the details for each provided unstETH id.
     ///
     /// The details include:
@@ -568,7 +568,7 @@ contract Escrow is ISignallingEscrow, IRageQuitEscrow {
     // Rage Quit Escrow: Getters
     // ---
 
-    /// @notice Retrieves the unstETH NFT ids of the next batch available for claiming.
+    /// @notice Returns the unstETH NFT ids of the next batch available for claiming.
     /// @param limit The maximum number of unstETH NFTs to return in the batch.
     /// @return unstETHIds An array of unstETH NFT ids available for the next withdrawal batch.
     function getNextWithdrawalBatch(uint256 limit) external view returns (uint256[] memory unstETHIds) {
@@ -598,7 +598,7 @@ contract Escrow is ISignallingEscrow, IRageQuitEscrow {
         return _escrowState.isRageQuitExtensionPeriodPassed();
     }
 
-    /// @notice Retrieves details about the current state of the rage quit escrow.
+    /// @notice Returns details about the current state of the rage quit escrow.
     /// @return details A `RageQuitEscrowDetails` struct containing the following fields:
     /// - `isRageQuitExtensionPeriodStarted`: Indicates whether the rage quit extension period has started.
     /// - `rageQuitEthWithdrawalsDelay`: The delay period for ETH withdrawals during rage quit.

contracts/ImmutableDualGovernanceConfigProvider.sol

@@ -18,11 +18,11 @@ contract ImmutableDualGovernanceConfigProvider is IDualGovernanceConfigProvider
     // Immutable Variables
     // ---
 
-    /// @notice The percentage of the total stETH supply that must be exceeded in the Signalling Escrow to transition
+    /// @notice The percentage of the total stETH supply that must be reached in the Signalling Escrow to transition
     ///     Dual Governance from the Normal state to the VetoSignalling state.
     PercentD16 public immutable FIRST_SEAL_RAGE_QUIT_SUPPORT;
 
-    /// @notice The percentage of the total stETH supply that must be exceeded in the Signalling Escrow to transition
+    /// @notice The percentage of the total stETH supply that must be reached in the Signalling Escrow to transition
     ///     Dual Governance into the RageQuit state.
     PercentD16 public immutable SECOND_SEAL_RAGE_QUIT_SUPPORT;
 

contracts/ResealManager.sol

@@ -29,7 +29,7 @@ contract ResealManager is IResealManager {
     // ---
 
     /// @notice Initializes the ResealManager contract.
-    /// @param emergencyProtectedTimelock The address of the EmergencyProtectedTimelock contract.
+    /// @param emergencyProtectedTimelock The address of the Timelock contract.
     constructor(ITimelock emergencyProtectedTimelock) {
         EMERGENCY_PROTECTED_TIMELOCK = emergencyProtectedTimelock;
     }
@@ -40,7 +40,7 @@ contract ResealManager is IResealManager {
 
     /// @notice Extends the pause of the specified sealable contract.
     /// @dev Works only if conditions are met:
-    /// - ResealManager has PAUSE_ROLE for target contract;
+    /// - ResealManager has PAUSE_ROLE and RESUME_ROLE for target contract;
     /// - Contract are paused until timestamp after current timestamp and not for infinite time;
     /// - The DAO governance is blocked by DualGovernance;
     /// - Function is called by the governance contract.

contracts/libraries/DualGovernanceConfig.sol

@@ -24,9 +24,9 @@ library DualGovernanceConfig {
     // ---
 
     /// @notice Configuration values for Dual Governance.
-    /// @param firstSealRageQuitSupport The percentage of the total stETH supply that must be exceeded in the Signalling
+    /// @param firstSealRageQuitSupport The percentage of the total stETH supply that must be reached in the Signalling
     ///     Escrow to transition Dual Governance from the Normal state to the VetoSignalling state.
-    /// @param secondSealRageQuitSupport The percentage of the total stETH supply that must be exceeded in the
+    /// @param secondSealRageQuitSupport The percentage of the total stETH supply that must be reached in the
     ///     Signalling Escrow to transition Dual Governance into the RageQuit state.
     ///
     /// @param minAssetsLockDuration The minimum duration that assets must remain locked in the Signalling Escrow contract

contracts/libraries/DualGovernanceStateTransitions.sol

@@ -8,7 +8,25 @@ import {DualGovernanceConfig} from "./DualGovernanceConfig.sol";
 import {State, DualGovernanceStateMachine} from "./DualGovernanceStateMachine.sol";
 
 /// @title Dual Governance State Transitions Library
-/// @notice Library containing the transitions logic for the Dual Governance system
+/// @notice Library containing the transition logic for the Dual Governance system.
+/// @dev The graph of the state transitions:
+///
+///        ┌─────────────┐     ┌──────────────────┐
+///        │    Normal   ├────>│  VetoSignalling  │<───────┐
+///     ┌─>│  [SUB, EXE] │     │      [SUB]       │<────┐  │
+///     │  └─────────────┘     │ ┌──────────────┐ │     │  │
+///     │                   ┌──┼─┤ Deactivation ├─┼──┐  │  │
+///     │                   │  │ │     [ ]      │ │  │  │  │
+///     │                   │  │ └──────────────┘ │  │  │  │
+///     │                   │  └──────────────────┘  │  │  │
+///     │  ┌──────────────┐ │     ┌──────────┐       │  │  │
+///     └──┤ VetoCooldown │<┘     │ RageQuit │<──────┘  │  │
+///        │     [EXE]    │<──────┤   [SUB]  │<─────────┘  │
+///        └──────┬───────┘       └──────────┘             │
+///               └────────────────────────────────────────┘
+///
+///     SUB - Allows proposals submission while the state is active.
+///     EXE - Allows scheduling proposals for execution while the state is active.
 library DualGovernanceStateTransitions {
     using DualGovernanceConfig for DualGovernanceConfig.Context;