System Config

Table of Contents

• Overview
• Definitions
  • Batch Inbox
  • Batcher Hash
  • Fee Scalars
    • Pre-Ecotone Parameters
    • Post-Ecotone Parameters
    • Post-Ecotone Scalar Encoding
  • Unsafe Block Signer
  • L2 Gas Limit
• Functionality
  • System Config Updates
• Function Specification
  • initialize
  • minimumGasLimit
  • maximumGasLimit
  • unsafeBlockSigner
  • l1CrossDomainMessenger
  • l1ERC721Bridge
  • l1StandardBridge
  • disputeGameFactory
  • optimismPortal
  • optimismMintableERC20Factory
  • getAddresses
  • batchInbox
  • startBlock
  • paused
  • superchainConfig
  • setUnsafeBlockSigner
  • setBatcherHash
  • setGasConfig
  • setGasConfigEcotone
  • setGasLimit
  • setEIP1559Params
  • setOperatorFeeScalars
  • resourceConfig

Overview

The SystemConfig is a contract on L1 that can emit rollup configuration changes as log events. The rollup block derivation process picks up on these log events and applies the changes. SystemConfig generally acts as the source of truth for configuration values within an OP Stack chain.

Definitions

Batch Inbox

The Batch Inbox is the address that Sequencer transaction batches are published to. Sequencers publish transactions to the Batch Inbox by setting it as the to address on a transaction containing batched L2 transactions either in calldata or as blobdata.

Batcher Hash

The Batcher Hash identifies the sender(s) whose transactions to the Batch Inbox will be recognized by the L2 clients for a given OP Chain.

The Batcher Hash is versioned by the first byte of the hash. The structure of the V0 Batcher Hash is a 32 byte hash defined as follows:

This can also be understood as:

bytes32(address(batcher))

Where batcher is the address of the account that sends transactions to the Batch Inbox. Put simply, the V0 hash identifies a single address whose transaction batches will be recognized by L2 clients. This hash is versioned so that it could, for instance, be repurposed to be a commitment to a list of permitted accounts or some other form of batcher identification.

Fee Scalars

The Fee Scalars are parameters used to calculate the L1 data fee for L2 transactions. These parameters are also known as Gas Price Oracle (GPO) parameters.

Pre-Ecotone Parameters

Before the Ecotone upgrade, these include:

• Scalar: A multiplier applied to the L1 base fee, interpreted as a big-endian uint256
• Overhead: A constant gas overhead, interpreted as a big-endian uint256

Post-Ecotone Parameters

After the Ecotone upgrade:

• The Scalar attribute encodes additional scalar information in a versioned encoding scheme
• The Overhead value is ignored and does not affect the L2 state-transition output

Post-Ecotone Scalar Encoding

The Scalar is encoded as big-endian uint256, interpreted as bytes32, and composed as follows:

• Byte 0: scalar-version byte
• Bytes [1, 32): depending on scalar-version:
  • Scalar-version 0:
    • Bytes [1, 28): padding, should be zero
    • Bytes [28, 32): big-endian uint32, encoding the L1-fee baseFeeScalar
    • This version implies the L1-fee blobBaseFeeScalar is set to 0
    • If there are non-zero bytes in the padding area, baseFeeScalar must be set to MaxUint32
  • Scalar-version 1:
    • Bytes [1, 24): padding, must be zero
    • Bytes [24, 28): big-endian uint32, encoding the blobBaseFeeScalar
    • Bytes [28, 32): big-endian uint32, encoding the baseFeeScalar

The baseFeeScalar corresponds to the share of the user-transaction (per byte) in the total regular L1 EVM gas usage consumed by the data-transaction of the batch-submitter. For blob transactions, this is the fixed intrinsic gas cost of the L1 transaction.

The blobBaseFeeScalar corresponds to the share of a user-transaction (per byte) in the total blobdata that is introduced by the data-transaction of the batch-submitter.

Unsafe Block Signer

The Unsafe Block Signer is an Ethereum address whose corresponding private key is used to sign "unsafe" blocks before they are published to L1. This signature allows nodes in the P2P network to recognize these blocks as the canonical unsafe blocks, preventing denial of service attacks on the P2P layer.

To ensure that its value can be fetched with a storage proof in a storage layout independent manner, it is stored at a special storage slot corresponding to keccak256("systemconfig.unsafeblocksigner").

Unlike other system config parameters, the Unsafe Block Signer only operates on blockchain policy and is not a consensus level parameter.

L2 Gas Limit

The L2 Gas Limit defines the maximum amount of gas that can be used in a single L2 block. This parameter ensures that L2 blocks remain of reasonable size to be processed and proven.

Changes to the L2 gas limit are fully applied in the first L2 block with the L1 origin that introduced the change, as opposed to the 1/1024 adjustments towards a target as seen in limit updates of L1 blocks.

The gas limit may not be set to a value larger than the maximum gas limit. This is to ensure that L2 blocks are fault provable and of reasonable size to be processed by the client software.

Functionality

System Config Updates

System config updates are signaled through the ConfigUpdate(uint256,uint8,bytes) event. The event structure includes:

• The first topic determines the version (unknown versions are critical derivation errors)
• The second topic determines the type of update (unknown types are critical derivation errors)
• The remaining event data encodes the configuration update

In version 0, the following update types are supported:

• Type 0: batcherHash overwrite, as bytes32 payload
• Type 1: Pre-Ecotone, overhead and scalar overwrite, as two packed uint256 entries. After Ecotone upgrade, overhead is ignored and scalar is interpreted as a versioned encoding that updates baseFeeScalar and blobBaseFeeScalar
• Type 2: gasLimit overwrite, as uint64 payload
• Type 3: unsafeBlockSigner overwrite, as address payload

Function Specification

initialize

• MUST only be triggerable once.
• MUST set the owner of the contract to the provided _owner address.
• MUST set the SuperchainConfig contract address.
• MUST set the batcher hash, gas config, gas limit, unsafe block signer, resource config, batch inbox, L1 contract addresses, and L2 chain ID.
• MUST set the start block to the current block number if it hasn't been set already.

minimumGasLimit

Returns the minimum L2 gas limit that can be safely set for the system to operate, calculated as the sum of the maximum resource limit and the system transaction maximum gas.

maximumGasLimit

Returns the maximum L2 gas limit that can be safely set for the system to operate.

unsafeBlockSigner

Returns the address of the Unsafe Block Signer.

l1CrossDomainMessenger

Returns the address of the L1CrossDomainMessenger contract.

l1ERC721Bridge

Returns the address of the L1ERC721Bridge contract.

l1StandardBridge

Returns the address of the L1StandardBridge contract.

disputeGameFactory

Returns the address of the DisputeGameFactory contract, derived from the OptimismPortal.

optimismPortal

Returns the address of the OptimismPortal contract.

optimismMintableERC20Factory

Returns the address of the OptimismMintableERC20Factory contract.

getAddresses

Returns a consolidated struct containing all the L1 contract addresses.

batchInbox

Returns the address of the Batch Inbox.

startBlock

Returns the block number at which the op-node can start searching for logs.

paused

This function integrates with the Pause Mechanism by using the chain's ETHLockbox address as the Pause Identifier. Returns the current pause state of the system by checking if the SuperchainConfig is paused for this chain's ETHLockbox.

• MUST return true if SuperchainConfig.paused(optimismPortal().ethLockbox()) returns true OR if SuperchainConfig.paused(address(0)) returns true.
• MUST return false otherwise.

superchainConfig

Returns the address of the SuperchainConfig contract that manages the pause state.

setUnsafeBlockSigner

Allows the owner to update the Unsafe Block Signer address.

• MUST revert if called by an address other than the owner.
• MUST update the unsafe block signer address.
• MUST emit a ConfigUpdate event with the UpdateType.UNSAFE_BLOCK_SIGNER type.

setBatcherHash

Allows the owner to update the Batcher Hash.

• MUST revert if called by an address other than the owner.
• MUST update the batcher hash.
• MUST emit a ConfigUpdate event with the UpdateType.BATCHER type.

setGasConfig

Allows the owner to update the gas configuration parameters (pre-Ecotone).

• MUST revert if called by an address other than the owner.
• MUST revert if the scalar exceeds the maximum allowed value.
• MUST update the overhead and scalar values.
• MUST emit a ConfigUpdate event with the UpdateType.FEE_SCALARS type.

setGasConfigEcotone

Allows the owner to update the gas configuration parameters (post-Ecotone).

• MUST revert if called by an address other than the owner.
• MUST update the basefeeScalar and blobbasefeeScalar values.
• MUST update the scalar value with the versioned encoding.
• MUST emit a ConfigUpdate event with the UpdateType.FEE_SCALARS type.

setGasLimit

Allows the owner to update the L2 Gas Limit.

• MUST revert if called by an address other than the owner.
• MUST revert if the gas limit is less than the minimum gas limit.
• MUST revert if the gas limit is greater than the maximum gas limit.
• MUST update the gas limit.
• MUST emit a ConfigUpdate event with the UpdateType.GAS_LIMIT type.

setEIP1559Params

Allows the owner to update the EIP-1559 parameters of the chain.

• MUST revert if called by an address other than the owner.
• MUST revert if the denominator is less than 1.
• MUST revert if the elasticity is less than 1.
• MUST update the eip1559Denominator and eip1559Elasticity values.
• MUST emit a ConfigUpdate event with the UpdateType.EIP_1559_PARAMS type.

setOperatorFeeScalars

Allows the owner to update the operator fee parameters.

• MUST revert if called by an address other than the owner.
• MUST update the operatorFeeScalar and operatorFeeConstant values.
• MUST emit a ConfigUpdate event with the UpdateType.OPERATOR_FEE_PARAMS type.

resourceConfig

Returns the current resource metering configuration.