Skip to content

Commit

Permalink
Update the NatSpec comments format in the EmergencyProtectedTimelock
Browse files Browse the repository at this point in the history
  • Loading branch information
@Psirex
Psirex committed Jul 7, 2024
1 parent e92a3e4 commit cca2785
Showing 1 changed file with 80 additions and 108 deletions.
188 changes: 80 additions & 108 deletions contracts/EmergencyProtectedTimelock.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,11 @@ import {EmergencyProtection, EmergencyState} from "./libraries/EmergencyProtecti

import {ConfigurationProvider} from "./ConfigurationProvider.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.
*/
/// @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.
contract EmergencyProtectedTimelock is ITimelock, ConfigurationProvider {
using Proposals for Proposals.State;
using EmergencyProtection for EmergencyProtection.State;
Expand All @@ -35,93 +33,83 @@ contract EmergencyProtectedTimelock is ITimelock, ConfigurationProvider {

constructor(address config) ConfigurationProvider(config) {}

/**
* @dev Submits a new proposal to execute a series of calls through an executor.
* Only the governance contract can call this function.
* @param executor The address of the executor contract that will execute the calls.
* @param calls An array of `ExecutorCall` structs representing the calls to be executed.
* @return newProposalId The ID of the newly created proposal.
*/
// ---
// Main Timelock Functionality
// ---

/// @dev Submits a new proposal to execute a series of calls through an executor.
/// Only the governance contract can call this function.
/// @param executor The address of the executor contract that will execute the calls.
/// @param calls An array of `ExecutorCall` structs representing the calls to be executed.
/// @return newProposalId The ID of the newly created proposal.
function submit(address executor, ExecutorCall[] calldata calls) external returns (uint256 newProposalId) {
_checkGovernance(msg.sender);
newProposalId = _proposals.submit(executor, calls);
}

/**
* @dev Schedules a proposal for execution after a specified delay.
* Only the governance contract can call this function.
* @param proposalId The ID of the proposal to be scheduled.
*/
/// @dev Schedules a proposal for execution after a specified delay.
/// Only the governance contract can call this function.
/// @param proposalId The ID of the proposal to be scheduled.
function schedule(uint256 proposalId) external {
_checkGovernance(msg.sender);
_proposals.schedule(proposalId, CONFIG.AFTER_SUBMIT_DELAY());
}

/**
* @dev Executes a scheduled proposal.
* Checks if emergency mode is active and prevents execution if it is.
* @param proposalId The ID of the proposal to be executed.
*/
/// @dev Executes a scheduled proposal.
/// Checks if emergency mode is active and prevents execution if it is.
/// @param proposalId The ID of the proposal to be executed.
function execute(uint256 proposalId) external {
_emergencyProtection.checkEmergencyModeActive(false);
_proposals.execute(proposalId, CONFIG.AFTER_SCHEDULE_DELAY());
}

/**
* @dev Cancels all non-executed proposals.
* Only the governance contract can call this function.
*/
/// @dev Cancels all non-executed proposals.
/// Only the governance contract can call this function.
function cancelAllNonExecutedProposals() external {
_checkGovernance(msg.sender);
_proposals.cancelAll();
}

/**
* @dev Transfers ownership of the executor contract to a new owner.
* Only the admin executor can call this function.
* @param executor The address of the executor contract.
* @param owner The address of the new owner.
*/
/// @dev Transfers ownership of the executor contract to a new owner.
/// Only the admin executor can call this function.
/// @param executor The address of the executor contract.
/// @param owner The address of the new owner.
function transferExecutorOwnership(address executor, address owner) external {
_checkAdminExecutor(msg.sender);
IOwnable(executor).transferOwnership(owner);
}

/**
* @dev Sets a new governance contract address.
* Only the admin executor can call this function.
* @param newGovernance The address of the new governance contract.
*/
/// @dev Sets a new governance contract address.
/// Only the admin executor can call this function.
/// @param newGovernance The address of the new governance contract.
function setGovernance(address newGovernance) external {
_checkAdminExecutor(msg.sender);
_setGovernance(newGovernance);
}

/**
* @dev Activates the emergency mode.
* Only the activation committee can call this function.
*/
// ---
// Emergency Protection Functionality
// ---

/// @dev Activates the emergency mode.
/// Only the activation committee can call this function.
function activateEmergencyMode() external {
_emergencyProtection.checkActivationCommittee(msg.sender);
_emergencyProtection.checkEmergencyModeActive(false);
_emergencyProtection.activate();
}

/**
* @dev Executes a proposal during emergency mode.
* Checks if emergency mode is active and if the caller is part of the execution committee.
* @param proposalId The ID of the proposal to be executed.
*/
/// @dev Executes a proposal during emergency mode.
/// Checks if emergency mode is active and if the caller is part of the execution committee.
/// @param proposalId The ID of the proposal to be executed.
function emergencyExecute(uint256 proposalId) external {
_emergencyProtection.checkEmergencyModeActive(true);
_emergencyProtection.checkExecutionCommittee(msg.sender);
_proposals.execute(proposalId, /* afterScheduleDelay */ Duration.wrap(0));
}

/**
* @dev Deactivates the emergency mode.
* If the emergency mode has not passed, only the admin executor can call this function.
*/
/// @dev Deactivates the emergency mode.
/// If the emergency mode has not passed, only the admin executor can call this function.
function deactivateEmergencyMode() external {
_emergencyProtection.checkEmergencyModeActive(true);
if (!_emergencyProtection.isEmergencyModePassed()) {
Expand All @@ -131,10 +119,8 @@ contract EmergencyProtectedTimelock is ITimelock, ConfigurationProvider {
_proposals.cancelAll();
}

/**
* @dev Resets the system after entering the emergency mode.
* Only the execution committee can call this function.
*/
/// @dev Resets the system after entering the emergency mode.
/// Only the execution committee can call this function.
function emergencyReset() external {
_emergencyProtection.checkEmergencyModeActive(true);
_emergencyProtection.checkExecutionCommittee(msg.sender);
Expand All @@ -143,14 +129,12 @@ contract EmergencyProtectedTimelock is ITimelock, ConfigurationProvider {
_proposals.cancelAll();
}

/**
* @dev Sets the parameters for the emergency protection functionality.
* Only the admin executor can call this function.
* @param activator The address of the activation committee.
* @param enactor The address of the execution committee.
* @param protectionDuration The duration of the protection period.
* @param emergencyModeDuration The duration of the emergency mode.
*/
/// @dev Sets the parameters for the emergency protection functionality.
/// Only the admin executor can call this function.
/// @param activator The address of the activation committee.
/// @param enactor The address of the execution committee.
/// @param protectionDuration The duration of the protection period.
/// @param emergencyModeDuration The duration of the emergency mode.
function setEmergencyProtection(
address activator,
address enactor,
Expand All @@ -161,79 +145,69 @@ contract EmergencyProtectedTimelock is ITimelock, ConfigurationProvider {
_emergencyProtection.setup(activator, enactor, protectionDuration, emergencyModeDuration);
}

/**
* @dev Checks if the emergency protection functionality is enabled.
* @return A boolean indicating if the emergency protection is enabled.
*/
/// @dev Checks if the emergency protection functionality is enabled.
/// @return A boolean indicating if the emergency protection is enabled.
function isEmergencyProtectionEnabled() external view returns (bool) {
return _emergencyProtection.isEmergencyProtectionEnabled();
}

/**
* @dev Retrieves the current emergency state.
* @return res The EmergencyState struct containing the current emergency state.
*/
/// @dev Retrieves the current emergency state.
/// @return res The EmergencyState struct containing the current emergency state.
function getEmergencyState() external view returns (EmergencyState memory res) {
res = _emergencyProtection.getEmergencyState();
}

/**
* @dev Retrieves the address of the current governance contract.
* @return The address of the current governance contract.
*/
// ---
// Timelock View Methods
// ---

/// @dev Retrieves the address of the current governance contract.
/// @return The address of the current governance contract.
function getGovernance() external view returns (address) {
return _governance;
}

/**
* @dev Retrieves the details of a proposal.
* @param proposalId The ID of the proposal.
* @return proposal The Proposal struct containing the details of the proposal.
*/
/// @dev Retrieves the details of a proposal.
/// @param proposalId The ID of the proposal.
/// @return proposal The Proposal struct containing the details of the proposal.
function getProposal(uint256 proposalId) external view returns (Proposal memory proposal) {
proposal = _proposals.get(proposalId);
}

/**
* @dev Retrieves the total number of proposals.
* @return count The total number of proposals.
*/
/// @dev Retrieves the total number of proposals.
/// @return count The total number of proposals.
function getProposalsCount() external view returns (uint256 count) {
count = _proposals.count();
}

/**
* @dev Retrieves the submission time of a proposal.
* @param proposalId The ID of the proposal.
* @return submittedAt The submission time of the proposal.
*/
/// @dev Retrieves the submission time of a proposal.
/// @param proposalId The ID of the proposal.
/// @return submittedAt The submission time of the proposal.
function getProposalSubmissionTime(uint256 proposalId) external view returns (Timestamp submittedAt) {
submittedAt = _proposals.getProposalSubmissionTime(proposalId);
}

/**
* @dev Checks if a proposal can be executed.
* @param proposalId The ID of the proposal.
* @return A boolean indicating if the proposal can be executed.
*/
/// @dev Checks if a proposal can be executed.
/// @param proposalId The ID of the proposal.
/// @return A boolean indicating if the proposal can be executed.
function canExecute(uint256 proposalId) external view returns (bool) {
return !_emergencyProtection.isEmergencyModeActivated()
&& _proposals.canExecute(proposalId, CONFIG.AFTER_SCHEDULE_DELAY());
}

/**
* @dev Checks if a proposal can be scheduled.
* @param proposalId The ID of the proposal.
* @return A boolean indicating if the proposal can be scheduled.
*/
/// @dev Checks if a proposal can be scheduled.
/// @param proposalId The ID of the proposal.
/// @return A boolean indicating if the proposal can be scheduled.
function canSchedule(uint256 proposalId) external view returns (bool) {
return _proposals.canSchedule(proposalId, CONFIG.AFTER_SUBMIT_DELAY());
}

/**
* @dev Internal function to set the governance contract address.
* @param newGovernance The address of the new governance contract.
*/
// ---
// Internal Methods
// ---

/// @dev Internal function to set the governance contract address.
/// @param newGovernance The address of the new governance contract.
function _setGovernance(address newGovernance) internal {
address prevGovernance = _governance;
if (newGovernance == prevGovernance || newGovernance == address(0)) {
Expand All @@ -243,10 +217,8 @@ contract EmergencyProtectedTimelock is ITimelock, ConfigurationProvider {
emit GovernanceSet(newGovernance);
}

/**
* @dev Internal function to check if the caller is the governance contract.
* @param account The address to check.
*/
/// @dev Internal function to check if the caller is the governance contract.
/// @param account The address to check.
function _checkGovernance(address account) internal view {
if (_governance != account) {
revert NotGovernance(account, _governance);
Expand Down

0 comments on commit cca2785

Please sign in to comment.