A Developer's Guide to the Optimism Smart Contracts Package

The @eth-optimism/contracts npm package is a fundamental collection of Solidity smart contracts that power the Optimism ecosystem. This package contains the core logic for both Layer 1 (Ethereum mainnet) and Layer 2 (the Optimism network) components, enabling secure and efficient cross-chain communication and operations.

Whether you are building a new decentralized application, integrating cross-chain functionality, or simply exploring how Optimism's technology works under the hood, this package provides the essential building blocks. This guide will walk you through its structure, usage, and the key development workflows.

Core Package Structure and Purpose

The contracts within the package are distinctly categorized based on their intended deployment network. Contracts designated with EVM are meant for Ethereum mainnet (Layer 1), while those marked with OVM (Optimistic Virtual Machine) are designed for deployment on the Optimism network (Layer 2). Some utility contracts may be network-agnostic and lack a specific designation, meaning they can be used on either layer.

This separation is crucial for developers to understand, as it dictates how and where your dApp will interact with the Optimism stack. The L1 contracts typically handle cross-chain bridge logic and security, while the L2 contracts manage high-throughput, low-cost transactions.

Installing and Importing the Contracts

To start using these pre-audited contracts in your own Solidity project, you can easily install the package via npm or Yarn.

npm install @eth-optimism/contracts

Once installed, you can import specific contracts directly into your Solidity files. The import path is based on the contract's location within the package's contracts directory.

// Example: Importing the L1 Cross Domain Messenger contract
import { L1CrossDomainMessenger } from "@eth-optimism/contracts/L1/messaging/L1CrossDomainMessenger.sol";

This approach allows you to extend and compose your contracts with Optimism's battle-tested infrastructure, saving development time and reducing audit overhead.

Setting Up a Local Development Environment

To contribute to the package or test changes, you'll need to set up a local development environment.

Prerequisites:

Node.js (Version 14 or higher)
npm
Yarn

Initial Setup:

Clone the repository: git clone https://github.com/ethereum-optimism/optimism.git
Navigate to the contracts package: cd optimism/packages/contracts
Install the necessary dependencies: yarn install

Core Development Workflows

Running and Writing Tests

A comprehensive test suite is vital for ensuring the security and correctness of smart contracts. You can run the entire test suite or target specific test files.

Run all tests: yarn test
Run a specific test file: yarn test ./test/path/to/my/test.spec.ts

Measuring Test Coverage

To analyze how much of your codebase is covered by tests, you can generate a coverage report. This is an excellent practice for identifying untested logic paths.

yarn test:coverage

The command generates a detailed HTML report. Open ./coverage/index.html in your browser to visually explore the coverage results.

Compiling Contracts

Compile the contracts to ensure there are no syntax errors and to generate the latest artifacts using the build command:

yarn build

Deployment Guide

Deploying the full suite of Optimism contracts requires careful configuration and execution.

1. Environment Configuration

Before deploying, you must set critical environment variables. Copy the provided .env.example file to a new file named .env and fill in all the required values, such as private keys and RPC URLs for your target networks.

2. Deployment Configuration

Each deployment requires a config file. These TypeScript files, located in the deploy-config directory, define the parameters for your network (e.g., addresses of dependent contracts, gas price settings). It's best to start by duplicating and modifying an existing configuration like mainnet.ts.

3. Executing the Deployment

For a fresh deployment to a new network, use the following Hardhat command:

npx hardhat deploy --network <your-network-name>

For upgrading an existing system, you must use the --tags upgrade flag to ensure the correct migration scripts are run:

npx hardhat deploy --network <your-network-name> --tags upgrade

👉 Explore more strategies for secure contract upgrades

Important Security Note: The upgrade process involves temporarily transferring contract ownership to a dedicated manager contract. You will be prompted to verify all configuration details on-chain. Always double-check the provided addresses and values to prevent any malicious actions.

4. Verifying Contract Source Code

Contract source code is typically verified automatically during deployment on platforms like Etherscan and Sourcify. If automatic verification fails, you can manually verify your contracts with:

npx hardhat etherscan-verify --network <your-network-name>

5. Generating the L2 Genesis File

Optimism requires certain predeployed contracts (predeploys) to exist at fixed addresses on L2 at genesis. After deploying your L1 contracts, generate the necessary L2 genesis file with:

npx hardhat take-dump --network <your-network-name>

The generated genesis.json file can then be used to initialize your L2 geth node.

Useful Hardhat Management Tasks

Fee Withdrawal

The Sequencer Fee Wallet on L2 accumulates transaction fees. Any wallet can trigger a withdrawal of these fees to L1 once a predefined threshold is met. Use the built-in task to manage this:

npx hardhat withdraw-fees --help

Security and Bug Bounties

The security of the Optimism protocol is taken extremely seriously. The project maintains a detailed Security Policy for responsibly disclosing vulnerabilities.

Furthermore, a massive bug bounty program is hosted on Immunefi, offering rewards of up to $2,000,042 for critical vulnerabilities discovered in the protocol's smart contracts. This underscores the commitment to maintaining a robust and secure scaling solution for Ethereum.

Frequently Asked Questions

What is the difference between EVM and OVM contracts in the package?
EVM contracts are designed to be deployed on Ethereum Mainnet (Layer 1), handling bridge and security logic. OVM contracts are designed for the Optimism Layer 2 network, where they benefit from lower gas fees and faster transaction times, but operate under a slightly different virtual machine architecture.

How do I know which import path to use for a specific contract?
The import path directly mirrors the file structure within the package's contracts directory on GitHub. Find the contract file you need (e.g., L1/messaging/L1CrossDomainMessenger.sol) and use that path after the package name in your import statement.

Can I use these contracts to deploy my own independent Optimistic Rollup?
Yes, the @eth-optimism/contracts package provides the core smart contracts needed to deploy a custom Optimistic Rollup chain. However, this is a complex process that also requires configuring and running a full node software stack (like the Optimism Monorepo's op-node).

What should I do if I find a potential security vulnerability?
You should immediately refer to the project's official Security Policy on GitHub. Do not disclose the vulnerability publicly. Instead, follow the outlined procedure for private disclosure, which may involve contacting the team directly or submitting a report through the Immunefi platform to be eligible for the bounty.

Are the contracts audited?
Yes, the core Optimism contracts have undergone multiple professional audits from leading security firms in the blockchain space. Always check the official Optimism documentation or GitHub repository for the latest audit reports before using the contracts in production.

Is there a whitelist for mainnet deployments?
The whitelist has been removed from the Optimism mainnet. The functionality remains in the codebase for developers who are running their own independent networks and wish to use a permissioned allowist for certain actions.