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.
npm install @eth-optimism/contractsTypeScript 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";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
);The Optimism contracts system is organized into several key architectural layers:
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
};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;
}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);
}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;
}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;
}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);
}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);
}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
}The package exports Solidity contracts organized in the following directory structure:
L1/messaging/, L1/rollup/, L1/verification/, L1/deployment/L2/messaging/, L2/predeploys/libraries/bridge/, libraries/codec/, libraries/utils/, libraries/resolver/, libraries/rlp/, libraries/trie/, libraries/constants/standards/chugsplash/ (upgrade system contracts)Each capability section provides detailed documentation of the contracts in these directories.