op-alloy

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 its crates as a dependency and take your first steps.

Building with op-alloy

Walk through types and functionality available in different op-alloy crates.

Contributing

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

op-alloy follows and expands the OP Stack standards set in the specs. The contributing guide breaks down how the specs integrate with op-alloy and how to contribute to op-alloy.

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 consists of a number of crates that provide a range of functionality essential for interfacing with any OP Stack chain.

The most succinct way to work with op-alloy is to add the op-alloy crate with the full feature flag from the command-line using Cargo.

cargo add op-alloy --features full

Alternatively, you can add the following to your Cargo.toml file.

op-alloy = { version = "0.5", features = ["full"] }

For more fine-grained control over the features you wish to include, you can add the individual crates to your Cargo.toml file, or use the op-alloy crate with the features you need.

After op-alloy is added as a dependency, crates re-exported by op-alloy are now available.

#![allow(unused)]
fn main() {
use op_alloy::{
   genesis::{RollupConfig, SystemConfig},
   consensus::OpBlock,
   protocol::BlockInfo,
   network::Optimism,
   provider::ext::engine::OpEngineApi,
   rpc_types::OpTransactionReceipt,
   rpc_jsonrpsee::traits::RollupNode,
   rpc_types_engine::OpAttributesWithParent,
};
}

Features

The op-alloy defines many feature flags including the following.

Default

  • std
  • k256
  • serde

Full enables the most commonly used crates.

  • full

The k256 feature flag enables the k256 feature on the op-alloy-consensus crate.

  • k256

Arbitrary enables arbitrary features on crates, deriving the Arbitrary trait on types.

  • arbitrary

Serde derives serde's Serialize and Deserialize traits on types.

  • serde

Additionally, individual crates can be enabled using their shorthand names. For example, the consensus feature flag provides the op-alloy-consensus re-export so op-alloy-consensus types can be used from op-alloy through op_alloy::consensus::InsertTypeHere.

Crates

no_std

As noted above, the following crates are no_std compatible.

To add no_std support to a crate, ensure the check_no_std script is updated to include this crate once no_std compatible.

Building

This section offers in-depth documentation into the various op-alloy crates. Some of the primary crates and their types are listed below.

[RollupConfig][rollup-config] and [SystemConfig][system-config] types.

Consensus

op-alloy-consensus crate

The op-alloy-consensus crate provides an Optimism consensus interface. It contains constants, types, and functions for implementing Optimism EL consensus and communication. This includes an extended OpTxEnvelope type with deposit transactions, and receipts containing OP Stack specific fields (deposit_nonce + deposit_receipt_version).

In general a type belongs in this crate if it exists in the alloy-consensus crate, but was modified from the base Ethereum protocol in the OP Stack. For consensus types that are not modified by the OP Stack, the alloy-consensus types should be used instead.

Block

op-alloy-consensus exports an Optimism block type, OpBlock.

This type simply re-uses the alloy-consensus block type, with OpTxEnvelope as the type of transactions in the block.

Transactions

Optimism extends the Ethereum EIP-2718 transaction envelope to include a deposit variant.

OpTxEnvelope

The OpTxEnvelope type is based on 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.

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.

RPC Engine Types

op-alloy-rpc-types-engine crate

The op-alloy-rpc-types-engine crate provides Optimism types for interfacing with the Engine API in the OP Stack.

Optimism defines a custom payload attributes type called OpPayloadAttributes. OpPayloadAttributes extends alloy's PayloadAttributes with a few fields: transactions, a flag for enabling the tx pool, the gas limit, and EIP 1559 parameters.

Optimism also returns a custom type for the engine_getPayload request for both V3 and V4 payload envelopes. These are the OpExecutionPayloadEnvelopeV3 and OpExecutionPayloadEnvelopeV4 types, which both wrap payload envelope types from alloy-rpc-types-engine.

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 a few dependencies:

Optional

Pull Request Process

  1. Create an issue for any significant changes. Trivial changes may skip this step.
  2. Once the 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. Be sure to update any documentation that has gone stale as a result of the change, in the README files, the book, and in rustdoc comments.
  4. Once your PR is approved by a maintainer, you may merge your pull request yourself if you have permissions to do so. Otherwise, the maintainer who approves your pull request will add it to the merge queue.

Working with OP Stack Specs

The OP Stack is a set of standardized open-source specifications that powers Optimism, developed by the Optimism Collective.

op-alloy is a rust implementation of core OP Stack types, transports, middleware and more. Not all types and implementation details in op-alloy are present in the OP Stack specs, and on the flipside, not all specifications are implemented by op-alloy. That said, op-alloy is entirely based off of the specs, and new functionality or core modifications to op-alloy must be reflected in the specs.

As such, the first step for introducing changes to the OP Stack is to open a pr in the specs repository. These changes should target a protocol upgrade so that all implementations of the OP Stack are able to synchronize and implement the changes.

Once changes are merged in the OP Stack specs repo, they may be added to op-alloy in a backwards-compatible way such that pre-upgrade functionality persists. The primary way to enable backwards-compatibility is by using timestamp-based activation for protocol upgrades.

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.