chore(book): Consensus Docs

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)

book/src/building/consensus/transactions.md → 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.
+<a href="https://crates.io/crates/op-alloy-consensus"><img src="https://img.shields.io/crates/v/op-alloy-consensus.svg" alt="op-alloy-consensus crate"></a>
 
-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]
 
 
+<!-- Links -->
+
+[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

book/src/links.md

@@ -1,3 +1,16 @@
+<!-- op-alloy -->
+
+[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
+
 <!-- External -->
 
 [op-stack]: https://github.com/ethereum-optimism/optimism

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}}