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:
- Just for our command-runner scripts.
- The Rust toolchain.
Optional
Pull Request Process
- 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.
- 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
Justfile
s in the repository. - 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. - 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.