Smart Contract overview

The OP Stack’s onchain logic lives in two groups of smart contracts: the Layer 1 contracts deployed to Ethereum, and the Layer 2 predeploys that exist in every OP Stack chain’s genesis state. This page explains what each group is for and routes you to the canonical definition of each contract. It does not restate interfaces, parameters, or per-release versions:

• Behavior is defined in the OP Stack specifications.
• Source code lives in packages/contracts-bedrock in the monorepo, with generated interface documentation at devdocs.optimism.io.
• Deployed addresses are on the OP Mainnet addresses page, sourced from the superchain-registry.

​

Layer 1 contracts

The L1 contracts hold the chain’s bridge liquidity, accept deposits, verify withdrawals, store the chain’s configuration, and adjudicate output proposals through the fault proof system. The Optimism Overview specification includes an architecture diagram showing how they connect.

​

Bridging and messaging

Deposits enter the chain and withdrawals leave it through a layered stack: the OptimismPortal is the low-level deposit and withdrawal contract, the L1CrossDomainMessenger adds replayable message passing on top of it, and the token bridges sit on top of the messenger. Messages sent directly to the OptimismPortal are not replayable, so users and app developers should prefer the messenger or bridge interfaces.

​

Chain configuration

​

Proposals and fault proofs

Claims about the L2 state are proposed and challenged permissionlessly through dispute games rather than trusted output submission. See the fault proofs explainer for how the system works end to end.

​

Legacy and deprecated contracts

• AddressManager is a legacy name-to-address registry from the pre-Bedrock system. It survives only because the L1CrossDomainMessenger still sits behind a legacy ResolvedDelegateProxy that resolves through it.
• L2OutputOracle was the trusted output proposal contract before fault proofs. It is deprecated: output proposals are made through the DisputeGameFactory instead, per the L2 output root proposals specification.
• ProtocolVersions signaled recommended and required protocol versions to node operators. The contract has been removed from the OP Stack contracts; the versioning scheme it exposed remains documented in the Superchain Upgrades specification.

​

Upgrading the contracts

L1 contracts are upgraded through the OP Contracts Manager (OPCM), which deploys and upgrades the L1 contracts as a versioned set. The superchain-ops workflow drives OPCM under the hood and is the path for chains that require Security Council signing; other chains can call OPCM directly. op-deployer remains the tool for initial deployments, but its upgrade command is deprecated in favor of OPCM; see the deprecation notice. L2 predeploys are upgraded through the L2 Contract Manager (L2CM), introduced in Upgrade 19. At a network upgrade, the consensus layer emits a network upgrade transaction that has the L2 ProxyAdmin delegatecall the L2ContractsManager contract, which updates every predeploy implementation in a single atomic transaction, replacing the older practice of per-contract multisig transactions. See the L2 Contract Manager feature page and the L2 Upgrades specification.

​

Contract releases

Contracts are released as tagged monorepo releases named op-contracts/vX.Y.Z, following the documented versioning policy. This page does not track releases; use these sources instead:

• The op-contracts release history lists every release with its notes, generated from the GitHub releases.
• The superchain-registry standard versions files record the exact contract versions and implementation addresses that make up each standard release.
• The network upgrades registry maps each hardfork to its governance approval and required component versions.

​

Layer 2 contracts (predeploys)

Predeploys are contracts placed at fixed, well-known addresses in the genesis state of every OP Stack chain. Unlike precompiles they are ordinary EVM contracts, which keeps them portable across client implementations and visible to standard tooling. Most live in the 0x4200000000000000000000000000000000000xxx address namespace and sit behind proxies owned by the L2 ProxyAdmin. The Predeploys specification is the canonical list: it maintains the full table of predeploy addresses, the upgrade each was introduced in, deprecation status, and whether each is proxied, along with the normative definition of each contract.

​

Bridging predeploys

The L2 side mirrors the L1 bridging stack. The L2CrossDomainMessenger is the recommended high-level messaging interface, the L2ToL1MessagePasser records withdrawal messages whose inclusion is later proven on L1, and the L2StandardBridge and L2ERC721Bridge pair with their L1 counterparts. The OptimismMintableERC20Factory and OptimismMintableERC721Factory permissionlessly create the L2 token contracts that the bridges mint and burn.

​

Fee and system predeploys

• The GasPriceOracle exposes the parameters and helper functions for estimating the data availability portion of the transaction fee. The exact fee formula changes across upgrades and is defined in the spec, not here; see transaction fees for the explanation.
• The L1Block predeploy exposes information about the latest known L1 block, written by the protocol through a system deposit transaction.
• The fee vaults (SequencerFeeVault, BaseFeeVault, L1FeeVault, and, since the Isthmus upgrade, the OperatorFeeVault) collect the components of the transaction fee for withdrawal to configured recipients. See fee vaults for operational details.
• The ProxyAdmin owns the proxies of the other predeploys and controls their upgrades.
• The BeaconBlockRoot contract (EIP-4788) exposes L1 beacon block roots, available since the Ecotone upgrade.
• WETH9 is the standard Wrapped Ether contract at a deterministic address.

​

GovernanceToken

The GovernanceToken is the OP token used in Optimism governance, supporting voting and delegation. It is owned by a MintManager contract that enforces the token inflation schedule. See the governance resources for how the token is used.

​

EAS (Ethereum Attestation Service)

The EAS and SchemaRegistry predeploys implement the Ethereum Attestation Service protocol, an open-source public good for issuing and managing onchain attestations. You can interact with EAS through the EAS Scan UI, the EAS SDK, or directly onchain, and index attestations with the EAS API or the open source indexer. See attestations for how attestations are used in Optimism governance.

​

Deprecated predeploys

The LegacyMessagePasser, DeployerWhitelist, LegacyERC20ETH, and L1BlockNumber contracts remain in state for backwards compatibility with the pre-Bedrock system but are deprecated and unused. Their addresses and history are in the Predeploys specification.

​

Next steps

• Read the Optimism Overview specification for the architecture diagrams connecting these contracts.
• Browse the contract source and the generated contract reference.
• Look up contract addresses on OP Mainnet.
• Learn how the fault proof system uses the dispute contracts.