or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdl1-messaging-bridging.mdl1-rollup-management.mdl2-messaging-bridging.mdl2-system-contracts.mdstandards-interfaces.mdtypescript-utilities.mdutility-libraries.md
tile.json

tessl/npm-eth-optimism--contracts

Smart contracts for Optimism Layer 2 scaling solution including L1/L2 messaging, bridging, rollup management, and predeploy contracts

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@eth-optimism/contracts@0.6.x

To install, run

npx @tessl/cli install tessl/npm-eth-optimism--contracts@0.6.0

index.mddocs/

Optimism Contracts

The @eth-optimism/contracts package provides the complete smart contract infrastructure for the Optimism Layer 2 scaling solution. It includes contracts for both Layer 1 (Ethereum mainnet) and Layer 2 (Optimism), implementing cross-domain messaging, asset bridging, rollup management, fraud proofs, and governance mechanisms using the Optimistic Rollup architecture.

Package Information

  • Package Name: @eth-optimism/contracts
  • Package Type: npm
  • Language: Solidity (with TypeScript utilities)
  • Installation: npm install @eth-optimism/contracts
  • Version: 0.6.0
  • License: MIT

Core Imports

TypeScript utilities for contract interaction:

import { 
  getContractDefinition, 
  getContractInterface, 
  getContractFactory,
  predeploys 
} from "@eth-optimism/contracts";

For CommonJS:

const { 
  getContractDefinition, 
  getContractInterface, 
  getContractFactory,
  predeploys 
} = require("@eth-optimism/contracts");

Solidity contract imports:

import { L1CrossDomainMessenger } from "@eth-optimism/contracts/L1/messaging/L1CrossDomainMessenger.sol";
import { L2CrossDomainMessenger } from "@eth-optimism/contracts/L2/messaging/L2CrossDomainMessenger.sol";
import { L1StandardBridge } from "@eth-optimism/contracts/L1/messaging/L1StandardBridge.sol";
import { IL2StandardERC20 } from "@eth-optimism/contracts/standards/IL2StandardERC20.sol";

Basic Usage

import { getContractFactory, predeploys, getContractInterface } from "@eth-optimism/contracts";
import { ethers } from "ethers";

// Get contract factory for deployment
const l1MessengerFactory = getContractFactory("L1CrossDomainMessenger", signer);

// Get contract interface for encoding calls
const l2MessengerInterface = getContractInterface("L2CrossDomainMessenger");

// Access predeploy addresses
const l2MessengerAddress = predeploys.L2CrossDomainMessenger;
const l2BridgeAddress = predeploys.L2StandardBridge;

// Connect to deployed contracts
const l2Messenger = new ethers.Contract(
  l2MessengerAddress,
  l2MessengerInterface,
  provider
);

// Send cross-domain message
await l2Messenger.sendMessage(
  targetAddress,
  messageData,
  gasLimit
);

Architecture

The Optimism contracts system is organized into several key architectural layers:

  • Layer 1 Contracts: Deployed on Ethereum mainnet, handle rollup data availability, fraud proofs, and L1↔L2 messaging
  • Layer 2 Contracts: Deployed on Optimism L2, provide system functionality and predeploy services
  • Cross-Domain Messaging: Enables secure communication between L1 and L2 with proof verification
  • Bridge System: Handles ETH and ERC20 token transfers between layers with deposit/withdrawal flows
  • Rollup Management: Manages transaction batching, state commitments, and fraud proof verification
  • Utility Libraries: Shared functionality for encoding, cryptography, data structures, and address resolution

Capabilities

TypeScript Contract Utilities

Core utilities for interacting with Optimism smart contracts, including contract factories, interfaces, predeploy addresses, and deployment configuration.

function getContractDefinition(name: string): any;
function getContractInterface(name: string): ethers.utils.Interface;
function getContractFactory(name: string, signer?: ethers.Signer): ethers.ContractFactory;
function getDeployedContractDefinition(name: string, network: string): {
  address: string;
  abi: any;
};

const predeploys: {
  OVM_L2ToL1MessagePasser: string;
  L2CrossDomainMessenger: string;
  L2StandardBridge: string;
  OVM_GasPriceOracle: string;
  // ... additional predeploy addresses
};

TypeScript Utilities

Layer 1 Messaging & Bridging

L1 contracts that handle cross-domain messaging and asset bridging, enabling communication and token transfers between Ethereum mainnet and Optimism L2.

contract L1CrossDomainMessenger {
  function sendMessage(address _target, bytes calldata _message, uint32 _gasLimit) external;
  function relayMessage(
    address _target,
    address _sender, 
    bytes memory _message,
    uint256 _messageNonce,
    L2MessageInclusionProof memory _proof
  ) external;
  function xDomainMessageSender() external view returns (address);
}

contract L1StandardBridge {
  function depositETH(uint32 _l2Gas, bytes calldata _data) external payable;
  function depositETHTo(address _to, uint32 _l2Gas, bytes calldata _data) external payable;
  function depositERC20(
    address _l1Token,
    address _l2Token, 
    uint256 _amount,
    uint32 _l2Gas,
    bytes calldata _data
  ) external;
  function depositERC20To(
    address _l1Token,
    address _l2Token,
    address _to,
    uint256 _amount,
    uint32 _l2Gas,
    bytes calldata _data
  ) external;
  function finalizeETHWithdrawal(
    address _from,
    address _to,
    uint256 _amount,
    bytes calldata _data
  ) external;
  function finalizeERC20Withdrawal(
    address _l1Token,
    address _l2Token,
    address _from,
    address _to,
    uint256 _amount,
    bytes calldata _data
  ) external;
}

Layer 1 Messaging & Bridging

Layer 1 Rollup Management

L1 contracts responsible for managing the Optimistic Rollup, including transaction ordering, state commitments, and fraud proof verification.

contract CanonicalTransactionChain {
  function enqueue(address _target, uint256 _gasLimit, bytes memory _data) external;
  function appendQueueBatch(uint256 _numQueuedTransactions) external;
  function appendSequencerBatch() external;
}

contract StateCommitmentChain {
  function appendStateBatch(
    bytes32[] memory _batch,
    uint256 _shouldStartAtElement
  ) external;
  function verifyStateCommitment(
    bytes32 _element,
    ChainBatchHeader memory _batchHeader,
    ChainInclusionProof memory _proof
  ) external view returns (bool);
}

Layer 1 Rollup Management

Layer 2 Messaging & Bridging

L2 contracts that provide the Layer 2 side of cross-domain messaging and bridging functionality, including message relaying and token withdrawals.

contract L2CrossDomainMessenger {
  function sendMessage(address _target, bytes calldata _message, uint32 _gasLimit) external;
  function relayMessage(
    address _target,
    address _sender,
    bytes memory _message, 
    uint256 _messageNonce
  ) external;
}

contract L2StandardBridge {
  function withdraw(
    address _l2Token,
    uint256 _amount,
    uint32 _l1Gas,
    bytes calldata _data
  ) external;
  function finalizeDeposit(
    address _l1Token,
    address _l2Token,
    address _from,
    address _to,
    uint256 _amount,
    bytes calldata _data
  ) external;
}

Layer 2 Messaging & Bridging

Layer 2 System Contracts

Predeploy contracts that provide essential L2 system functionality including gas pricing, fee collection, and L1 block information.

contract OVM_GasPriceOracle {
  function gasPrice() external view returns (uint256);
  function getL1Fee(bytes memory _data) external view returns (uint256);
  function l1BaseFee() external view returns (uint256);
  function overhead() external view returns (uint256);
  function scalar() external view returns (uint256);
}

contract OVM_L2ToL1MessagePasser {
  function passMessageToL1(bytes memory _message) external;
}

contract OVM_SequencerFeeVault {
  function withdraw() external;
}

Layer 2 System Contracts

Utility Libraries

Comprehensive library contracts providing shared functionality for encoding, cryptography, data structures, address resolution, and Ethereum standards.

library Lib_CrossDomainUtils {
  function encodeXDomainCalldata(
    address _target,
    address _sender,
    bytes memory _message,
    uint256 _messageNonce
  ) internal pure returns (bytes memory);
}

library Lib_MerkleTree {
  function verify(
    bytes32 _root,
    bytes32 _leaf,
    uint256 _index,
    bytes32[] memory _siblings,
    uint256 _totalLeaves
  ) internal pure returns (bool);
}

contract Lib_AddressManager {
  function setAddress(string memory _name, address _address) external;
  function getAddress(string memory _name) external view returns (address);
}

Utility Libraries

Standards & Interfaces

Standard contracts and interfaces that define the common patterns and APIs used throughout the Optimism ecosystem.

interface ICrossDomainMessenger {
  function sendMessage(address _target, bytes calldata _message, uint32 _gasLimit) external;
  function xDomainMessageSender() external view returns (address);
}

contract L2StandardERC20 {
  function mint(address _to, uint256 _amount) external;
  function burn(address _from, uint256 _amount) external;
  // Standard ERC20 functions...
}

library AddressAliasHelper {
  function applyL1ToL2Alias(address l1Address) internal pure returns (address l2Address);
  function undoL1ToL2Alias(address l2Address) internal pure returns (address l1Address);
}

Standards & Interfaces

Common Types

interface L2MessageInclusionProof {
  stateRoot: string;
  stateRootBatchHeader: ChainBatchHeader;
  stateRootProof: ChainInclusionProof;
  stateTrieWitness: string;
  storageTrieWitness: string;
}

interface ChainBatchHeader {
  batchIndex: BigNumber;
  batchRoot: string;
  batchSize: BigNumber;
  prevTotalElements: BigNumber;
  extraData: string;
}

interface ChainInclusionProof {
  index: BigNumber;
  siblings: string[];
}

interface DeployConfig {
  l1BlockTimeSeconds: number;
  l2BlockGasLimit: number;
  l2ChainId: number;
  ctcL2GasDiscountDivisor: number;
  ctcEnqueueGasCost: number;
  sccFaultProofWindowSeconds: number;
  // ... additional configuration options
}

Contract File Paths

The package exports Solidity contracts organized in the following directory structure:

  • L1 Contracts: L1/messaging/, L1/rollup/, L1/verification/, L1/deployment/
  • L2 Contracts: L2/messaging/, L2/predeploys/
  • Libraries: libraries/bridge/, libraries/codec/, libraries/utils/, libraries/resolver/, libraries/rlp/, libraries/trie/, libraries/constants/
  • Standards: standards/
  • ChugSplash: chugsplash/ (upgrade system contracts)

Each capability section provides detailed documentation of the contracts in these directories.