From 5ddd056bde12d2b25bbe02455af22aea4ee203b6 Mon Sep 17 00:00:00 2001 From: refcell Date: Mon, 4 Nov 2024 09:36:51 -0500 Subject: [PATCH 1/2] fix(book): installation docs --- book/src/links.md | 13 ++++++ book/src/starting/installation.md | 77 ++++++++++++++++++++++++++++++- 2 files changed, 88 insertions(+), 2 deletions(-) diff --git a/book/src/links.md b/book/src/links.md index 7155a0a9..fcc2c8a2 100644 --- a/book/src/links.md +++ b/book/src/links.md @@ -1,3 +1,16 @@ + + +[op-alloy-crate]: https://crates.io/crates/op-alloy + +[op-alloy-consensus]: https://crates.io/crates/op-alloy-consensus +[op-alloy-genesis]: https://crates.io/crates/op-alloy-genesis +[op-alloy-network]: https://crates.io/crates/op-alloy-network +[op-alloy-protocol]: https://crates.io/crates/op-alloy-protocol +[op-alloy-provider]: https://crates.io/crates/op-alloy-provider +[op-alloy-rpc-jsonrpsee]: https://crates.io/crates/op-alloy-rpc-jsonrpsee +[op-alloy-rpc-types-engine]: https://crates.io/crates/op-alloy-rpc-types-engine +[op-alloy-rpc-types]: https://crates.io/crates/op-alloy-rpc-types + [op-stack]: https://github.com/ethereum-optimism/optimism diff --git a/book/src/starting/installation.md b/book/src/starting/installation.md index 5796b845..ec69f348 100644 --- a/book/src/starting/installation.md +++ b/book/src/starting/installation.md @@ -3,12 +3,85 @@ [op-alloy][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`][op-alloy-crate] crate +with the `full` feature flag from the command-line using Cargo. + +```bash +cargo add op-alloy --features full +``` + +Alternatively, you can add the following to your `Cargo.toml` file. + +```bash +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. + +```rust +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`][op-alloy-crate] defines many [feature flags][op-alloy-ff] 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 -TODO +- [`op-alloy-network`][op-alloy-network] +- [`op-alloy-genesis`][op-alloy-genesis] (supports `no_std`) +- [`op-alloy-protocol`][op-alloy-protocol] (supports `no_std`) +- [`op-alloy-provider`][op-alloy-provider] +- [`op-alloy-consensus`][op-alloy-consensus] (supports `no_std`) +- [`op-alloy-rpc-jsonrpsee`][op-alloy-rpc-jsonrpsee] +- [`op-alloy-rpc-types`][op-alloy-rpc-types] (supports `no_std`) +- [`op-alloy-rpc-types-engine`][op-alloy-rpc-types-engine] (supports `no_std`) ## `no_std` -TODO +As noted above, the following crates are `no_std` compatible. + +- [`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] + +To add `no_std` support to a crate, ensure the [check_no_std][check-no-std] +script is updated to include this crate once `no_std` compatible. + {{#include ./links.md}} From e239f6ebf26b0b5f0686e9a9e7956fe59f2c7b36 Mon Sep 17 00:00:00 2001 From: refcell Date: Mon, 4 Nov 2024 10:59:16 -0500 Subject: [PATCH 2/2] chore(book): rework consensus docs --- book/src/SUMMARY.md | 3 +- .../transactions.md => consensus.md} | 43 ++++++++++++++----- book/src/building/consensus/README.md | 1 - 3 files changed, 33 insertions(+), 14 deletions(-) rename book/src/building/{consensus/transactions.md => consensus.md} (68%) delete mode 100644 book/src/building/consensus/README.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 6cf98d1c..745e5a51 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -6,8 +6,7 @@ - [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) + - [Consensus](./building/consensus.md) - [Examples](./examples/README.md) - [Contributing](./CONTRIBUTING.md) - [Licensing](./LICENSE.md) diff --git a/book/src/building/consensus/transactions.md b/book/src/building/consensus.md similarity index 68% rename from book/src/building/consensus/transactions.md rename to book/src/building/consensus.md index b073a4a9..ad6640d7 100644 --- a/book/src/building/consensus/transactions.md +++ b/book/src/building/consensus.md @@ -1,13 +1,33 @@ -# Transactions +# Consensus -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. +op-alloy-consensus crate -This doc breaks down transaction and other types defined in the -[`op-alloy-consensus`][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][deposit], and receipts containing OP Stack +specific fields (`deposit_nonce` + `deposit_receipt_version`). -## [`OpTxEnvelope`][envelope] +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`][consensus] exports an Optimism block type, [`OpBlock`][block]. + +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][2718] transaction envelope to include a +deposit variant. + +### [`OpTxEnvelope`][envelope] The [`OpTxEnvelope`][envelope] type is based on [Alloy][alloy]'s [`TxEnvelope`][tx-envelope] type. @@ -23,14 +43,11 @@ 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]) +### 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 @@ -50,6 +67,7 @@ directly to the `OpTxEnvelope` variants defined above. 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 @@ -63,6 +81,9 @@ are the following. - [`Hardforks::fjord_txs()`][fjord] + + +[deposit]: https://specs.optimism.io/protocol/deposits.html [alloy]: https://github.com/alloy-rs/alloy [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 diff --git a/book/src/building/consensus/README.md b/book/src/building/consensus/README.md deleted file mode 100644 index 5cfc2c95..00000000 --- a/book/src/building/consensus/README.md +++ /dev/null @@ -1 +0,0 @@ -# Consensus