op-alloy Book

Welcome to the hands-on guide for getting started with op-alloy!

op-alloy connects applications to the OP Stack, leveraging high performance types, traits, and middleware from alloy.

📖 Development Status

op-alloy is in active development, and is not yet ready for use in production. During development, this book will evolve quickly and may contain inaccuracies.

Please open an issue if you find any errors or have any suggestions for improvements, and also feel free to contribute to the project!

Sections

Getting Started

To get started with op-alloy, add op-alloy crates as a dependency and take your first steps.

Building with op-alloy

A walkthrough of building with op-alloy.

Examples

This section will give you practical examples of how Alloy can be used in your codebase.

Contributing

Contributors are welcome! It is built and maintained by Alloy contributors, members of OP Labs, and the broader open source community.

Please see the contributing guide to get involved.

Licensing

op-alloy is licensed under the combined Apache 2.0 and MIT License, along with a SNAPPY license for snappy encoding use.

Installation

[op-alloy][op-alloy] consists of a number of crates that provide a range of functionality essential for interfacing with any OP Stack chain.

Crates

TODO

no_std

TODO

Building

This section offers in-depth documentation into the various op-alloy crates.

Genesis

Rollup Configs

Rollup configurations are a consensus construct used to configure an Optimism Consensus client. When an OP Stack chain is deployed into production or consensus nodes are configured to sync the chain, certain consensus parameters can be configured. These parameters are defined in the OP Stack specs.

Consensus parameters are consumed by OP Stack software through the RollupConfig type defined in the op-alloy-genesis crate.

RollupConfig Type

The RollupConfig type is defined in op-alloy-genesis.

A predefined rollup config can be loaded from a given L2 chain id using the rollup_config_from_chain_id method. An example is shown below.

#![allow(unused)]
fn main() {
use op_alloy_genesis::{OP_MAINNET_CONFIG, rollup_config_from_chain_id};

let op_mainnet_config = rollup_config_from_chain_id(10).expect("infallible");
assert_eq!(OP_MAINNET_CONFIG, op_mainnet_config);
}

The OP_MAINNET_CONFIG is one of the predefined rollup configs exported by the op-alloy-genesis crate. Other predefined configs include the following.

  • OP_MAINNET_CONFIG
  • OP_SEPOLIA_CONFIG
  • BASE_MAINNET_CONFIG
  • BASE_SEPOLIA_CONFIG

System Config

The system configuration is a set of configurable chain parameters defined in a contract on L1. These parameters can be changed through the system config contract, emitting events that are picked up by the rollup node derivation process. To dive deeper into the System Config, visit the OP Stack Specifications.

SystemConfig Type

The SystemConfig type is defined in op-alloy-genesis.

Parameters defined in the SystemConfig are expected to be updated through L1 receipts, using the update_with_receipts method.

Holocene Updates

The Holocene Hardfork introduced an update to the SystemConfig type, adding EIP-1559 parameters to the config.

The SystemConfig type in op-alloy-genesis provides a method called eip_1559_params that returns the EIP-1559 parameters encoded as a B64.

Consensus

Transactions

The op-alloy-consensus crate contains types for Optimism EL consensus and communication. Most notably, Optimism extends the Ethereum EIP-2718 transaction envelope to include a deposit variant.

This doc breaks down transaction and other types defined in the op-alloy-consensus crate.

OpTxEnvelope

The OpTxEnvelope type is based on [Alloy][alloy]'s TxEnvelope type.

Optimism modifies the TxEnvelope to the following.

  • Legacy
  • EIP-2930
  • EIP-1559
  • EIP-7702
  • Deposit

Deposit is a custom transaction type that is either an L1 attributes deposit transaction or a user-submitted deposit transaction. Read more about deposit transactions in the specs.

Transaction Types (OpTxType)

The OpTxType enumerates the transaction types using their byte identifier, represents as a u8 in rust.

OpBlock

op-alloy-consensus exports an Optimism block type.

Receipt Types

Just like op-alloy-consensus defines transaction types, it also defines associated receipt types.

OpReceiptEnvelope defines an Eip-2718 receipt envelope type modified for the OP Stack. It contains the following variants - mapping directly to the OpTxEnvelope variants defined above.

  • Legacy
  • EIP-2930
  • EIP-1559
  • EIP-7702
  • Deposit

There is also an OpDepositReceipt type, extending the alloy receipt type with a deposit nonce and deposit receipt version.

Hardforks

Aside from transactions and receipts, op-alloy-consensus exports one other core primitive called Hardforks.

Hardforks provides hardfork transaction constructors - that is, it provides methods that return upgrade transactions for each hardfork. Some of these are the following.

Examples

Examples for working with op-alloy-* crates.

TODO: document op-alloy crate use and using it with re-exports.

Contributing

Thank you for wanting to contribute! Before contributing to this repository, please read through this document and discuss the change you wish to make via issue.

Dependencies

Before working with this repository locally, you'll need to install several dependencies:

Optional

Pull Request Process

  1. Before anything, create an issue to discuss the change you're wanting to make, if it is significant or changes functionality. Feel free to skip this step for trivial changes.
  2. Once your change is implemented, ensure that all checks are passing before creating a PR. The full CI pipeline can be run locally via the Justfiles in the repository.
  3. Make sure to update any documentation that has gone stale as a result of the change, in the README files, the [book][book], and in rustdoc comments.
  4. Once you have sign-off from a maintainer, you may merge your pull request yourself if you have permissions to do so. If not, the maintainer who approves your pull request will add it to the merge queue.

Licensing

op-alloy is dually licensed under the Apache 2.0 and the MIT license.

The SNAPPY license is added for the use of snap in op-alloy-rpc-types-engine.

Glossary

This document contains definitions for terms used throughout the op-alloy book.