alloy-rs · refcell · Nov 1, 2024 · Oct 31, 2024 · Oct 31, 2024 · Oct 31, 2024
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 <a href="https://github.com/alloy-rs/op-alloy/blob/main/LICENSE-MIT"><img src="https://img.shields.io/badge/License-MIT-d1d1f6.svg?label=license&labelColor=2a2f35" alt="License"></a>
 <a href="https://alloy-rs.github.io/op-alloy"><img src="https://img.shields.io/badge/Contributor%20Book-854a15?logo=mdBook&labelColor=2a2f35" alt="Book"></a>
 
-Transports, Middleware, and Networks for Optimism built with [Alloy][alloy].
+Built on [Alloy][alloy], op-alloy connects applications to the OP Stack.
 
 
 ## Usage
@@ -50,12 +50,11 @@ op-alloy is intended to be `no_std` compatible, initially for use in [kona][kona
 The following crates support `no_std`.
 Notice, provider crates do not support `no_std` compatibility.
 
-- `op-alloy-consensus`
-- `op-alloy-genesis`
-- `op-alloy-protocol`
-- `op-alloy-genesis`
-- `op-alloy-rpc-types`
-- `op-alloy-rpc-types-engine`
+- [`op-alloy-consensus`][op-alloy-consensus]
+- [`op-alloy-genesis`][op-alloy-genesis]
+- [`op-alloy-protocol`][op-alloy-protocol]
+- [`op-alloy-rpc-types-engine`][op-alloy-rpc-types-engine]
+- [`op-alloy-rpc-types`][op-alloy-rpc-types]
 
 If you would like to add no_std support to a crate,
 please make sure to update [scripts/check_no_std.sh][check-no-std].

diff --git a/book/src/CONTRIBUTING.md b/book/src/CONTRIBUTING.md
@@ -7,10 +7,8 @@ discuss the change you wish to make via issue.
 
 Before working with this repository locally, you'll need to install several dependencies:
 
-- [Docker](https://www.docker.com/) for cross-compilation.
-- [just](https://github.com/casey/just) for our command-runner scripts.
-- The [Rust toolchain](https://rustup.rs/)
-- The [Golang toolchain](https://go.dev/dl/)
+- [Just](https://github.com/casey/just) for our command-runner scripts.
+- [The Rust toolchain](https://rustup.rs/).
 
 **Optional**
 

diff --git a/book/src/LICENSE.md b/book/src/LICENSE.md
@@ -0,0 +1,10 @@
+# Licensing
+
+op-alloy is dually licensed under the [Apache 2.0][apache] and the [MIT][mit] license.
+
+The [SNAPPY license][snappy] is added for the use of [snap][snap] in `op-alloy-rpc-types-engine`.
+
+[snap]: https://github.com/BurntSushi/rust-snappy
+[snappy]: https://github.com/alloy-rs/op-alloy/blob/main/SNAPPY-LICENSE
+[apache]: https://github.com/alloy-rs/op-alloy/blob/main/LICENSE-APACHE
+[mit]: https://github.com/alloy-rs/op-alloy/blob/main/LICENSE-MIT
@@ -1,5 +1,14 @@
 # Summary
 
 - [Introduction](./intro.md)
-- [Glossary](./glossary.md)
+- [Getting Started](./starting/installation.md)
+- [Building](./building/README.md)
+  - [Genesis](./building/genesis/README.md)
+    - [Rollup Config](./building/genesis/rollup-config.md)
+    - [System Config](./building/genesis/system-config.md)
+  - [Consensus](./building/consensus/README.md)
+    - [Transactions](./building/consensus/transactions.md)
+- [Examples](./examples/README.md)
 - [Contributing](./CONTRIBUTING.md)
+- [Licensing](./LICENSE.md)
+- [Glossary](./glossary.md)
diff --git a/book/src/building/README.md b/book/src/building/README.md
@@ -0,0 +1,3 @@
+# Building
+
+This section offers in-depth documentation into the various `op-alloy` crates.
@@ -0,0 +1,77 @@
+# Transactions
+
+The [`op-alloy-consensus`][consensus] crate contains types for Optimism EL
+consensus and communication. Most notably, Optimism extends the Ethereum
+[EIP-2718][2718] transaction envelope to include a deposit variant.
+
+This doc breaks down transaction and other types defined in the
+[`op-alloy-consensus`][consensus] crate.
+
+## [`OpTxEnvelope`][envelope]
+
+The [`OpTxEnvelope`][envelope] type is based on [Alloy][alloy]'s
+[`TxEnvelope`][tx-envelope] 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][specs].
+
+## Transaction Types ([`OpTxType`][ty])
+
+The [`OpTxType`][ty] enumerates the transaction types using their byte identifier,
+represents as a `u8` in rust.
+
+## [`OpBlock`][block]
+
+[`op-alloy-consensus`][consensus] exports an Optimism block type.
+
+## Receipt Types
+
+Just like [`op-alloy-consensus`][consensus] defines transaction types,
+it also defines associated receipt types.
+
+[`OpReceiptEnvelope`][ore] defines an [Eip-2718][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`][odr] type, extending the alloy receipt
+type with a deposit nonce and deposit receipt version.
+
+## Hardforks
+
+Aside from transactions and receipts, [`op-alloy-consensus`][consensus] exports
+one other core primitive called [`Hardforks`][hardforks].
+
+Hardforks provides hardfork transaction constructors - that is, it provides
+methods that return upgrade transactions for each hardfork. Some of these
+are the following.
+
+- [`Hardforks::ecotone_txs()`][ecotone]
+- [`Hardforks::fjord_txs()`][fjord]
+
+
+[fjord]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/hardforks/struct.Hardforks.html#method.fjord_txs
+[ecotone]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/hardforks/struct.Hardforks.html#method.ecotone_txs
+[hardforks]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/hardforks/struct.Hardforks.html
+[odr]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/struct.OpDepositReceipt.html
+[ore]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/enum.OpReceiptEnvelope.html
+[block]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/type.OpBlock.html
+[ty]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/enum.OpTxType.html
+[specs]: https://specs.optimism.io/protocol/deposits.html
+[tx-envelope]: https://docs.rs/alloy-consensus/latest/alloy_consensus/transaction/enum.TxEnvelope.html
+[envelope]: https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/enum.OpTxEnvelope.html
+[2718]: https://eips.ethereum.org/EIPS/eip-2718
+[consensus]: https://crates.io/crates/op-alloy-consensus
diff --git a/book/src/building/genesis/rollup-config.md b/book/src/building/genesis/rollup-config.md
@@ -0,0 +1,38 @@
+# 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][config].
+
+Consensus parameters are consumed by OP Stack software through the `RollupConfig` type defined in the
+[`op-alloy-genesis`][genesis] crate.
+
+## `RollupConfig` Type
+
+The [`RollupConfig`][rc] type is defined in [`op-alloy-genesis`][genesis].
+
+A predefined rollup config can be loaded from a given L2 chain id using
+the [`rollup_config_from_chain_id`][rcid] method. An example is shown below.
+
+```rust
+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`][genesis] crate. Other predefined configs include
+the following.
+
+- `OP_MAINNET_CONFIG`
+- `OP_SEPOLIA_CONFIG`
+- `BASE_MAINNET_CONFIG`
+- `BASE_SEPOLIA_CONFIG`
+
+<!-- Links -->
+
+[rcid]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/rollup/fn.rollup_config_from_chain_id.html
+[rc]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/rollup/struct.RollupConfig.html
+[genesis]: https://crates.io/crates/op-alloy-genesis
+[config]: https://specs.optimism.io/protocol/configurability.html
diff --git a/book/src/building/genesis/system-config.md b/book/src/building/genesis/system-config.md
@@ -0,0 +1,32 @@
+# 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][derivation]. To dive deeper
+into the System Config, visit the [OP Stack Specifications][specs].
+
+## `SystemConfig` Type
+
+The [`SystemConfig`][sc] type is defined in [`op-alloy-genesis`][genesis].
+
+Parameters defined in the [`SystemConfig`][sc] are expected to be updated
+through L1 receipts, using the [`update_with_receipts`][update] method.
+
+## Holocene Updates
+
+The [Holocene Hardfork][holocene] introduced an update to the [`SystemConfig`][sc]
+type, adding EIP-1559 parameters to the config.
+
+The [`SystemConfig`][sc] type in [`op-alloy-genesis`][genesis] provides a method
+called [`eip_1559_params`][eip] that returns the EIP-1559 parameters encoded as
+a [`B64`][b64].
+
+[holocene]: https://specs.optimism.io/protocol/holocene/overview.html
+[b64]: https://docs.rs/alloy-primitives/latest/alloy_primitives/aliases/type.B64.html
+[eip]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/system/struct.SystemConfig.html#method.eip_1559_params
+[update]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/system/struct.SystemConfig.html#method.update_with_receipts
+[sc]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/system/struct.SystemConfig.html
+[specs]: https://specs.optimism.io/protocol/system-config.html#system-config
+[derivation]: https://specs.optimism.io/protocol/derivation.html
+[genesis]: https://crates.io/crates/op-alloy-genesis
diff --git a/book/src/examples/README.md b/book/src/examples/README.md
@@ -0,0 +1,5 @@
+# Examples
+
+Examples for working with `op-alloy-*` crates.
+
+TODO: document `op-alloy` crate use and using it with re-exports.
diff --git a/book/src/examples/genesis/loading-a-rollup-config.md b/book/src/examples/genesis/loading-a-rollup-config.md
diff --git a/book/src/intro.md b/book/src/intro.md
@@ -1,27 +1,45 @@
 # op-alloy Book
 
-_Documentation for op-alloy._
-
 <a href="https://github.com/alloy-rs/op-alloy"><img src="https://img.shields.io/badge/GitHub%20Repo-op-alloy-green?logo=github"></a>
 
-> 📖 `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.
+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][alloy].
+
+> 📖 Development Status
 >
-> Please [open an issue][new-issue] if you find any errors or have any suggestions for improvements, and also feel free to [contribute][contributing] to the project!
+> `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][new-issue] if you find any errors or have any suggestions for
+> improvements, and also feel free to [contribute][contributing] to the project!
 
-## Introduction
+## Sections
 
-op-alloy is a collection of types, middleware, and networks for Optimism built on top of [alloy][alloy].
+### [Getting Started](./starting/installation.md)
 
-It is built and maintained by Alloy contributors, members of [OP Labs][op-labs], and the broader
-open source community. op-alloy is licensed under the combined Apache 2.0 and MIT License, along
-with a SNAPPY license for snappy encoding use.
+To get started with op-alloy, add op-alloy crates as a dependency and take your first steps.
+
+### [Building with op-alloy](./building/README.md)
 
-## Development Status
+A walkthrough of building with op-alloy.
 
-**op-alloy is currently in active development, and is not yet ready for use in production.**
+### [Examples](./examples/README.md)
 
-## Contributing
+This section will give you practical examples of how Alloy can be used in your codebase.
+
+### [Contributing](./CONTRIBUTING.md)
+
+Contributors are welcome! It is built and maintained by Alloy contributors,
+members of [OP Labs][op-labs], and the broader open source community.
+
+Please see the [contributing guide][contributing] to get involved.
+
+### [Licensing](./LICENSE.md)
+
+op-alloy is licensed under the combined Apache 2.0 and MIT License, along
+with a SNAPPY license for snappy encoding use.
 
-Contributors are welcome! Please see the [contributing guide][contributing] for more information.
 
 {{#include ./links.md}}
diff --git a/book/src/starting/installation.md b/book/src/starting/installation.md
@@ -0,0 +1,12 @@
+# 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