ISecureUpgradeable

Git Source

Title: ISecureUpgradeable

Author: Quantillon Labs - Nicolas Bellengé - @chewbaccoin

Interface for the SecureUpgradeable base contract

Note: security-contact: team@quantillon.money

Functions

initialize

Initializes the secure upgradeable contract

Sets up the secure upgradeable with initial configuration and assigns roles to admin

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to initializer modifier

• oracle: No oracle dependencies

function initialize(address admin) external;

Parameters

setTimelock

Set the timelock contract

Configures the timelock contract for secure upgrade management

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function setTimelock(address _timelock) external;

Parameters

toggleSecureUpgrades

Toggle secure upgrades

Enables or disables the secure upgrade mechanism

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function toggleSecureUpgrades(bool enabled) external;

Parameters

proposeUpgrade

Propose an upgrade through the timelock

Initiates a secure upgrade proposal with timelock delay

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function proposeUpgrade(address newImplementation, string calldata description, uint256 customDelay) external;

Parameters

executeUpgrade

Execute an upgrade through the timelock

Executes a previously proposed upgrade after timelock delay

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function executeUpgrade(address newImplementation) external;

Parameters

emergencyUpgrade

Emergency upgrade (bypasses timelock, requires emergency mode)

Performs immediate upgrade in emergency situations

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function emergencyUpgrade(address newImplementation, string calldata description) external;

Parameters

isUpgradePending

Check if an upgrade is pending

Checks if there's a pending upgrade for the given implementation

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function isUpgradePending(address implementation) external view returns (bool isPending);

Parameters

Returns

getPendingUpgrade

Get pending upgrade details

Returns detailed information about a pending upgrade

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getPendingUpgrade(address implementation)
    external
    view
    returns (ITimelockUpgradeable.PendingUpgrade memory upgrade);

Parameters

Returns

canExecuteUpgrade

Check if an upgrade can be executed

Checks if the timelock delay has passed and upgrade can be executed

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function canExecuteUpgrade(address implementation) external view returns (bool canExecute);

Parameters

Returns

getUpgradeSecurityStatus

Get upgrade security status

Returns current security configuration for upgrades

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getUpgradeSecurityStatus()
    external
    view
    returns (address timelockAddress, bool secureUpgradesEnabled_, bool hasTimelock);

Returns

proposeEmergencyDisableSecureUpgrades

Propose emergency disable of secure upgrades (starts 24‑hour delay window).

Increments the emergency‑disable proposal id, resets approvals and sets a future timestamp after which the proposal can be applied.

Notes:

• security: Only callable by an authorized admin role in implementations.

• validation: Reverts if secure upgrades are already disabled.

• state-changes: Bumps proposal id, clears approval count and sets emergencyDisablePendingAt.

• events: Emits an event describing the newly created proposal and activation time.

• errors: Reverts with a protocol‑specific error if secure upgrades are not active.

• reentrancy: Not applicable – implementations should avoid external calls.

• access: Restricted to governance/admin roles.

• oracle: No oracle dependencies.

function proposeEmergencyDisableSecureUpgrades() external;

approveEmergencyDisableSecureUpgrades

Register an admin approval for the currently pending emergency‑disable proposal.

Records that the caller has approved the latest proposal and increases the approval count, enforcing one‑approval‑per‑admin semantics.

Notes:

• security: Only callable by an authorized admin role in implementations.

• validation: Reverts if there is no active proposal or caller already approved.

• state-changes: Marks the caller as having approved and increments approval count.

• events: Emits an event with updated approval count.

• errors: Reverts with protocol‑specific errors on missing proposal or duplicate approval.

• reentrancy: Not applicable – implementations should avoid external calls.

• access: Restricted to governance/admin roles.

• oracle: No oracle dependencies.

function approveEmergencyDisableSecureUpgrades() external;

applyEmergencyDisableSecureUpgrades

Apply pending emergency‑disable once quorum and delay are satisfied.

Disables secure upgrades permanently for the implementation once:

• the activation timestamp is reached, and
• the approval count is at least the quorum.

Notes:

• security: Only callable by an authorized admin role; enforces timelock and quorum.

• validation: Reverts on mismatched expectedProposalId, missing quorum or no pending proposal.

• state-changes: Clears pending state and sets secureUpgradesEnabled to false.

• events: Emits an event indicating secure upgrades have been disabled.

• errors: Reverts with protocol‑specific errors on invalid state or insufficient approvals.

• reentrancy: Not applicable – implementations should avoid external calls after state changes.

• access: Restricted to governance/admin roles.

• oracle: No oracle dependencies.

function applyEmergencyDisableSecureUpgrades(uint256 expectedProposalId) external;

Parameters

enableSecureUpgrades

Enable secure upgrades after emergency

Re-enables secure upgrade mechanism after emergency

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function enableSecureUpgrades() external;

emergencyDisablePendingAt

Timestamp when emergency disable can be applied for the current proposal.

Returns 0 when there is no active proposal.

Notes:

• security: View helper; no access restriction.

• validation: None.

• state-changes: None – view function only.

• events: None.

• errors: None.

• reentrancy: Not applicable – view function.

• access: Public.

• oracle: No oracle dependencies.

function emergencyDisablePendingAt() external view returns (uint256);

Returns

emergencyDisableProposalId

Returns the current emergency‑disable proposal id.

Value is 0 when no proposal has ever been created.

Notes:

• security: View helper; no access restriction.

• validation: None.

• state-changes: None – view function only.

• events: None.

• errors: None.

• reentrancy: Not applicable – view function.

• access: Public.

• oracle: No oracle dependencies.

function emergencyDisableProposalId() external view returns (uint256);

Returns

emergencyDisableApprovalCount

Returns the current number of admin approvals for the active proposal.

Counts how many distinct admin addresses have approved the latest proposal id.

Notes:

• security: View helper; no access restriction.

• validation: None.

• state-changes: None – view function only.

• events: None.

• errors: None.

• reentrancy: Not applicable – view function.

• access: Public.

• oracle: No oracle dependencies.

function emergencyDisableApprovalCount() external view returns (uint256);

Returns

emergencyDisableQuorum

Returns the number of approvals required to apply emergency disable.

Exposes the implementation’s quorum constant for off‑chain monitoring.

Notes:

• security: View helper; no access restriction.

• validation: None.

• state-changes: None – view function only.

• events: None.

• errors: None.

• reentrancy: Not applicable – view function.

• access: Public.

• oracle: No oracle dependencies.

function emergencyDisableQuorum() external view returns (uint256);

Returns

hasEmergencyDisableApproval

Returns whether a given approver address approved a specific proposal id.

MUST return false when approver is the zero address or proposalId is zero.

Notes:

• security: View helper; no access restriction.

• validation: Treats invalid inputs as “not approved”.

• state-changes: None – view function only.

• events: None.

• errors: None.

• reentrancy: Not applicable – view function.

• access: Public.

• oracle: No oracle dependencies.

function hasEmergencyDisableApproval(uint256 proposalId, address approver) external view returns (bool);

Parameters

Returns

timelock

Returns the timelock contract address

Returns the ITimelockUpgradeable contract instance

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function timelock() external view returns (ITimelockUpgradeable);

Returns

secureUpgradesEnabled

Returns whether secure upgrades are enabled

Indicates if the secure upgrade mechanism is active

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function secureUpgradesEnabled() external view returns (bool);

Returns

UPGRADER_ROLE

Returns the upgrader role identifier

Role that can perform upgrades

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function UPGRADER_ROLE() external view returns (bytes32);

Returns

hasRole

Checks if an account has a specific role

Returns true if the account has been granted the role

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function hasRole(bytes32 role, address account) external view returns (bool);

Parameters

Returns

getRoleAdmin

Gets the admin role for a given role

Returns the role that is the admin of the given role

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getRoleAdmin(bytes32 role) external view returns (bytes32);

Parameters

Returns

grantRole

Grants a role to an account

Can only be called by an account with the admin role

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function grantRole(bytes32 role, address account) external;

Parameters

revokeRole

Revokes a role from an account

Can only be called by an account with the admin role

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function revokeRole(bytes32 role, address account) external;

Parameters

renounceRole

Renounces a role from the caller

The caller gives up their own role

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function renounceRole(bytes32 role, address callerConfirmation) external;

Parameters

upgradeTo

Upgrades the contract to a new implementation

Can only be called by accounts with UPGRADER_ROLE

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function upgradeTo(address newImplementation) external;

Parameters

upgradeToAndCall

Upgrades the contract to a new implementation and calls a function

Can only be called by accounts with UPGRADER_ROLE

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function upgradeToAndCall(address newImplementation, bytes memory data) external payable;

Parameters