Skip to content

Commit

Permalink
Merge pull request #246 from lidofinance/docs/specification
Browse files Browse the repository at this point in the history 
Additions and Updates to Specification and NatSpec
  • Loading branch information
@Psirex
Psirex authored Dec 25, 2024
2 parents 04a82d7 + 16e12c9 commit 833e083
Show file tree
Hide file tree
Showing 11 changed files with 1,949 additions and 429 deletions.
26 changes: 13 additions & 13 deletions contracts/DualGovernance.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -300,8 +300,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);
Expand All @@ -320,14 +320,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;
}
Expand Down Expand Up @@ -413,7 +413,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.
Expand All @@ -427,15 +427,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`).
Expand Down Expand Up @@ -537,20 +537,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;
Expand Down
38 changes: 26 additions & 12 deletions contracts/EmergencyProtectedTimelock.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,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;
Expand Down Expand Up @@ -135,7 +150,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();
Expand Down Expand Up @@ -309,7 +324,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.
Expand All @@ -322,12 +337,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.
Expand All @@ -341,14 +355,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();
Expand Down
14 changes: 7 additions & 7 deletions contracts/Escrow.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,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;
Expand Down Expand Up @@ -306,7 +306,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();
Expand Down Expand Up @@ -354,7 +354,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) {
Expand All @@ -377,8 +377,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:
Expand Down Expand Up @@ -569,7 +569,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) {
Expand Down Expand Up @@ -599,7 +599,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.
Expand Down
4 changes: 2 additions & 2 deletions contracts/ImmutableDualGovernanceConfigProvider.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,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;

Expand Down
4 changes: 2 additions & 2 deletions contracts/ResealManager.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,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;
}
Expand All @@ -41,7 +41,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.
Expand Down
4 changes: 2 additions & 2 deletions contracts/libraries/DualGovernanceConfig.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,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
Expand Down
20 changes: 19 additions & 1 deletion contracts/libraries/DualGovernanceStateTransitions.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,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;

Expand Down
Loading

0 comments on commit 833e083

Please sign in to comment.