Superchain Configuration

Table of Contents

• Overview
• Configuration Data Structure
  • SuperchainDefinition
  • Hardforks
  • SuperchainL1
• Invariants
  • iSUPC-001: The Guardian and Pause Deputy must be able to trigger the Pause Mechanism
    • Impact
  • iSUPC-002: The Guardian must be able to reset or undo the Pause Mechanism
    • Impact
• Function Specification
  • initialize
  • upgrade
  • guardian
  • pauseExpiry
  • pause
  • unpause
  • extend
  • pausable
  • paused
  • expiration

Overview

The SuperchainConfig contract is used to manage global configuration values for multiple OP Chains within a single Superchain network.

Configuration Data Structure

The SuperchainDefinition type represents the configuration for a Superchain target, containing information about L1 contract addresses and network parameters.

SuperchainDefinition

SuperchainDefinition {
    Name                   string
    ProtocolVersionsAddr   address
    SuperchainConfigAddr   address
    OPContractsManagerAddr address
    Hardforks              Hardforks
    L1                     SuperchainL1
}

Fields:

• Name: The name of the superchain (e.g., "mainnet", "sepolia")
• ProtocolVersionsAddr: Address of the ProtocolVersions contract on L1
• SuperchainConfigAddr: Address of the SuperchainConfig contract on L1
• OPContractsManagerAddr: Address of the OP Contracts Manager on L1
• Hardforks: Hardfork activation configuration for the superchain
• L1: L1 chain information including chain ID, RPC endpoint, and explorer URL

Hardforks

The Hardforks type contains optional activation timestamps for each network upgrade.

Hardforks {
    CanyonTime             uint64
    DeltaTime              uint64
    EcotoneTime            uint64
    FjordTime              uint64
    GraniteTime            uint64
    HoloceneTime           uint64
    IsthmusTime            uint64
    InteropTime            uint64
}

Fields:

• CanyonTime: Activation timestamp for the Canyon upgrade
• DeltaTime: Activation timestamp for the Delta upgrade
• EcotoneTime: Activation timestamp for the Ecotone upgrade
• FjordTime: Activation timestamp for the Fjord upgrade
• GraniteTime: Activation timestamp for the Granite upgrade
• HoloceneTime: Activation timestamp for the Holocene upgrade
• IsthmusTime: Activation timestamp for the Isthmus upgrade
• InteropTime: Activation timestamp for the Interop upgrade

SuperchainL1

The SuperchainL1 type contains L1 chain information for the superchain.

SuperchainL1 {
    ChainID   uint64
    PublicRPC string
    Explorer  string
}

Fields:

• ChainID: The chain ID of the L1 network (e.g. 1 for Ethereum mainnet, 11155111 for Sepolia)
• PublicRPC: Public RPC endpoint URL for the L1 network
• Explorer: Block explorer URL for the L1 network

Invariants

iSUPC-001: The Guardian and Pause Deputy must be able to trigger the Pause Mechanism

We require that the SuperchainConfig is constructed such that both the Guardian and the Pause Deputy must be able to trigger the Pause Mechanism at any time.

Impact

Severity: High

Existing recovery runbooks would not function as expected if the SuperchainConfig prevented one of these actors from triggering the pause as needed.

iSUPC-002: The Guardian must be able to reset or undo the Pause Mechanism

We require that the SuperchainConfig is constructed such that the Guardian must be able to unpause or extend the Pause Mechanism at any time.

Impact

Severity: Medium

If the Pause Mechanism cannot be reset then it cannot be used again without intervention from the Proxy Admin Owner. We consider this to be a Medium severity issue because the Proxy Admin Owner will have several months to coordinate such a fix assuming that iSUPC-001 holds.

Function Specification

initialize

• MUST only be triggerable by the ProxyAdmin or its owner.
• MUST only be triggerable once.
• MUST set the value of the Guardian role.
• MUST emit a ConfigUpdate event with the Guardian address.

upgrade

• MUST only be triggerable by the ProxyAdmin or its owner.
• MUST migrate the guardian from old storage to new storage.
• MUST clear old storage slots.
• MUST maintain contract version information.

guardian

Returns the address of the current Guardian.

pauseExpiry

Returns the duration after which a pause expires, which is a hardcoded constant of 7,884,000 seconds (approximately 3 months).

pause

Allows the Guardian to trigger the Pause Mechanism. pause takes an address Pause Identifier as an input. This identifier determines which systems or chains are affected by the pause.

• MUST revert if called by an address other than the Guardian.
• MUST revert if the pause timestamp for the given identifier is non-zero (already paused).
• MUST set the pause timestamp for the given identifier to the current block timestamp.
• MUST emit a Paused event with the identifier.

unpause

Allows the Guardian to explicitly unpause the system for a given Pause Identifier rather than waiting for the pause to expire. Unpausing a specific identifier does NOT unpause the global pause (zero address identifier). If the global pause is active, all systems will remain paused even if their specific identifiers are unpaused.

• MUST revert if called by an address other than the Guardian.
• MUST set the pause timestamp for the given identifier to 0, representing "not paused".
• MUST emit an Unpaused event with the identifier.
• Will not revert if the system is not already paused for the given identifier.

extend

Allows the Guardian to extend an active pause by resetting the pause timestamp to the current block timestamp, effectively restarting the expiry timer.

• MUST revert if called by an address other than the Guardian.
• MUST revert if the pause timestamp for the given identifier is zero (not currently paused).
• MUST set the pause timestamp for the given identifier to the current block timestamp.
• MUST emit a Paused event with the identifier.

pausable

Allows any user to check if the Pause Mechanism can be triggered for a specific Pause Identifier. The pausable status of a specific identifier is independent of the pausable status of the global pause (zero address identifier).

• MUST return true if the pause timestamp for the given identifier is 0 (not currently paused).
• MUST return false if the pause timestamp for the given identifier is non-zero (currently paused).

paused

Allows any user to check if the system is currently paused for a specific Pause Identifier.

• MUST return true if the pause timestamp for the given identifier is non-zero AND not expired (current time < pause timestamp + expiry duration).
• MUST return false otherwise.
• When called without parameters, MUST check the pause status for the global identifier (address(0)).

expiration

Returns the timestamp at which the pause for a given Pause Identifier will expire. This function only returns the expiration for the specific identifier provided.

• MUST return the pause timestamp plus the configured expiry duration if the pause timestamp is non-zero.
• MUST return 0 if the pause timestamp is 0 (system is not paused) for the given identifier.