docs: cover protocol types and PeerDAS (#181)

## Summary

- map primitives, consensus, EIP, network, RPC, genesis, trie, and serde
types to their intended boundaries
- explain how RPC responses embed consensus values and which conversions
preserve or discard metadata
- document network-associated types, chain-specific implementations,
persistence choices, and constrained builds
- add EIP-7594 PeerDAS sidecar coverage to the transaction guide and
navigation

## Why

The site documents primitives and provider calls but does not explain
the protocol and data-model crates that make up much of Alloy. Users
must infer when to use consensus versus RPC types, how Network changes
associated types, and where genesis, trie, and serialization helpers
fit. The examples include EIP-7594, but the transaction guide omits it.

## Impact

Infrastructure and library authors get a boundary-oriented type map
instead of a crate-name inventory. Application developers can convert
RPC responses without JSON round trips and select the correct network
representation. PeerDAS users can find the existing runnable flow and
its node, fork, and KZG requirements.

Author: mattsse

vocs/docs/pages/reference/protocol-and-rpc-types.md

@@ -0,0 +1,128 @@
+---
+title: Protocol and RPC Types
+description: Choose Alloy primitives, consensus envelopes, EIP helpers, RPC responses, genesis, trie, and serialization types
+---
+
+# Protocol and RPC types
+
+Alloy models the same chain data at several boundaries. Choosing the type that belongs to the
+boundary avoids manual conversion and preserves network-specific fields.
+
+| Boundary | Primary crates or modules | Examples |
+| --- | --- | --- |
+| Values and ABI | `alloy-primitives`, `alloy-sol-types`, `alloy-dyn-abi`, `alloy-json-abi` | address, `U256`, bytes, Solidity bindings |
+| Execution consensus | `alloy-consensus` | transaction envelopes, blocks, receipts, headers |
+| Protocol extensions | `alloy-eips` | block identifiers and implemented EIP data structures |
+| Network behavior | `alloy-network`, `alloy-network-primitives` | associated request, response, envelope, and receipt types |
+| JSON-RPC wire data | `alloy-rpc-types-*` | `TransactionRequest`, RPC block and receipt responses |
+| Chain configuration | `alloy-genesis` | execution genesis files and allocations |
+| State proofs | `alloy-trie` | trie roots, proofs, and prefix-sorted updates |
+| Representation helpers | `alloy-serde` | quantity, bytes, and compatibility serializers |
+
+The `alloy` meta-crate re-exports enabled families as `alloy::primitives`, `alloy::consensus`,
+`alloy::eips`, `alloy::network`, and `alloy::rpc::types`.
+
+## Primitives and ABI types
+
+Use primitives for chain-independent values: `Address`, `B256`, `Bytes`, fixed bytes, signed and
+unsigned integers, hashes, and maps. The `sol!` macro and Solidity type traits provide static ABI
+encoding, event and error decoding, and EIP-712 definitions. Dynamic ABI and JSON ABI types are for
+interfaces discovered at runtime.
+
+See [primitive types](/using-primitive-types/introduction), [`sol!`](/contract-interactions/using-sol!),
+and [static vs. dynamic ABI](/guides/static-dynamic-abi-in-alloy).
+
+## Consensus types
+
+Consensus types represent execution-layer objects independently of their JSON-RPC metadata:
+
+- signed and unsigned transaction variants and EIP-2718 envelopes;
+- headers and blocks;
+- receipts, logs, withdrawals, and blob sidecars;
+- recovered transactions that pair an envelope with its signer.
+
+Enable the `consensus` feature when using these through the meta-crate. Add `rlp`, `k256`, `kzg`, or
+`consensus-secp256k1` only when the operation needs that codec or cryptographic implementation.
+
+Use consensus types for database storage, networking, hashing, roots, signing payloads, and
+protocol-level transformations. Use the network's RPC types at the provider boundary.
+
+## RPC types wrap consensus data
+
+Ethereum RPC responses embed consensus values and add fields supplied by the node. For example, an
+RPC transaction includes block placement metadata while containing a recovered consensus envelope;
+an RPC receipt includes transaction and block metadata around the consensus receipt.
+
+Common conversion and access patterns include:
+
+- `block.into_consensus()` to discard RPC-only metadata and obtain a consensus block;
+- `transaction.into_recovered()` for the recovered consensus transaction;
+- `.inner` or `.into_inner()` on wrapper types;
+- `map_*` and `try_map_*` methods when replacing an embedded header or transaction type.
+
+See the runnable [consensus and RPC embedding example](/examples/providers/embed_consensus_rpc).
+Avoid re-serializing through JSON just to convert between these representations.
+
+## Network-associated types
+
+`Provider<N>` is generic over a `Network`. The network chooses the transaction type, envelope,
+receipt, header, request, and RPC response types used by provider methods. Ethereum is the default.
+
+Use:
+
+- `Ethereum` for Ethereum execution-layer responses;
+- a chain-specific implementation such as `op-alloy` for a supported ecosystem with extra
+  transaction or receipt variants;
+- `AnyNetwork` when consuming heterogeneous responses and the catch-all representation is
+  acceptable;
+- a custom `Network` implementation when a library owns a distinct typed protocol surface.
+
+Choosing `Ethereum` for a chain with extra transaction variants can fail deserialization. See
+[interacting with multiple networks](/guides/interacting-with-multiple-networks) and the
+[`AnyNetwork` example](/examples/advanced/any_network).
+
+## EIP modules
+
+`alloy-eips` collects protocol structures and behavior that are shared across consensus, provider,
+and RPC crates. Support for a type does not imply that the connected chain has activated that EIP.
+Fork activation and RPC availability remain network and node concerns.
+
+Examples include block identifiers and tags, typed envelope encodings, access lists,
+authorizations, blob sidecars, requests, and hardfork-related structures. Consult the
+[`alloy-eips` module list](https://docs.rs/alloy-eips/latest/alloy_eips/) for the exact release.
+
+## Genesis and trie data
+
+Use `alloy-genesis` for execution genesis configuration and account allocations. Genesis formats
+can contain client extensions, so preserve unknown or chain-specific fields when round-tripping a
+configuration.
+
+Use `alloy-trie` for Merkle-Patricia Trie roots and proofs. Trie APIs generally require keys and
+updates in the documented order; incorrect ordering can produce a different root rather than a
+helpful RPC error. Treat proof verification input as untrusted data and validate the expected root.
+
+These families are optional `genesis` and `trie` features on the meta-crate and are also available
+as direct dependencies for infrastructure libraries.
+
+## Serialization
+
+Ethereum JSON-RPC quantities, fixed bytes, byte strings, and nullability do not follow ordinary
+human-readable JSON conventions. Prefer the provided RPC and serde helper types over custom
+hex-string logic.
+
+Enable `serde` for serde implementations and helpers. Compatibility formats such as
+`serde-bincode-compat` are opt-in; use the documented compatibility wrapper rather than assuming a
+type's normal serde representation is stable for non-self-describing storage.
+
+For persistent data:
+
+1. Choose whether the stored form is consensus, RPC-enriched, or application-specific.
+2. Version the schema independently of the Rust type name.
+3. Test round trips across dependency upgrades.
+4. Do not use debug output as a data format.
+
+## Constrained and `no_std` users
+
+The network-facing meta-crate primarily targets `std`. Some core and protocol crates support
+`no_std` with default features disabled. Depend on the narrow crate directly, inspect its own
+feature list, and compile the exact target. See [feature flags](/reference/feature-flags).

vocs/docs/pages/transactions/introduction.mdx

@@ -30,6 +30,7 @@ Alloy supports building a transaction request for all types of transactions via
 - **EIP-2930 transactions:** Set the `access_list` field. This creates an access-list transaction.
 - **EIP-1559 transactions:** Set the `max_fee_per_gas` and `max_priority_fee_per_gas` fields. Omit the `gas_price` field.
 - **EIP-4844 transaction:** Use the `TransactionBuilder4844` to set blob specific fields using the `.with_blob_sidecar(..)` method.
+- **EIP-7594 sidecar:** Convert the pooled EIP-4844 sidecar to its PeerDAS cell-proof representation. This remains `TxType = 3`.
 - **EIP-7702 transaction:** Use the `TransactionBuilder7702` to set the authorization list using the `.with_authorization_list(..)` method.
 
 ### Legacy Transactions
@@ -75,7 +76,7 @@ Find the full example [here](/transactions/using-access-lists).
 
 ### EIP-1559 Transaction
 
-By default the builder attempts to construct an [EIP1559](https://eips.ethereum.org/EIPS/eip-1559) transaction (`TxType = 2`). You can make this explicit by specifiying the priority gas fields.
+By default the builder attempts to construct an [EIP1559](https://eips.ethereum.org/EIPS/eip-1559) transaction (`TxType = 2`). You can make this explicit by specifying the priority gas fields.
 
 ```rust showLineNumbers
 use alloy::{
@@ -95,7 +96,7 @@ Find the full example [here](/transactions/sending-an-EIP-1559-transaction).
 
 ### EIP-4844 Transaction
 
-EIP-4844 transactions (`TxType = 3`) are specific to Ethereum mainnet. One can build such transactions using the `TransactionBuilder4844` struct. This builder provides methods to set blob specific fields using the `.with_blob_sidecar(..)` method.
+EIP-4844 transactions (`TxType = 3`) are available on networks that have activated blob transactions. Build one using the `TransactionBuilder4844` trait, which provides `.with_blob_sidecar(..)` for blob-specific fields.
 
 ```rust showLineNumbers
 use alloy::{
@@ -114,6 +115,14 @@ let tx = TransactionRequest::default()
 
 Find the full example [here](/transactions/sending-an-EIP-4844-transaction).
 
+### EIP-7594 Blob Sidecar
+
+EIP-7594 changes the pooled blob sidecar representation for PeerDAS; it does not introduce a new
+transaction type. Build and fill an EIP-4844 transaction, then convert its sidecar before encoding
+and submitting it to a compatible node.
+
+Find the full example [here](/transactions/sending-an-EIP-7594-transaction).
+
 ### Example: EIP-7702 Transaction
 
 EIP-7702 transaction (`TxType = 4`)

vocs/docs/pages/transactions/sending-an-EIP-7594-transaction.md

@@ -0,0 +1,32 @@
+---
+title: Sending an EIP-7594 Blob Sidecar
+description: Convert and send an EIP-4844 blob transaction with an EIP-7594 PeerDAS cell-proof sidecar
+---
+
+# Sending an EIP-7594 blob sidecar
+
+[EIP-7594](https://eips.ethereum.org/EIPS/eip-7594) introduces PeerDAS cell proofs for blob data.
+It does not add a new execution-layer transaction type: the transaction remains an EIP-4844 blob
+transaction (`TxType = 3`), while its pooled sidecar uses the EIP-7594 representation.
+
+The workflow is:
+
+1. Build an EIP-4844 transaction and blob sidecar.
+2. Let the provider fill and sign the transaction.
+3. Convert the pooled EIP-4844 sidecar to `BlobTransactionSidecarEip7594` using the intended KZG
+   settings.
+4. Encode the envelope and submit it with `send_raw_transaction`.
+
+```rust
+// [!include ~/snippets/transactions/examples/send_eip7594_transaction.rs]
+```
+
+The connected node must support the fork and pooled transaction format. The runnable example starts
+Anvil with the Osaka hardfork; it requires a recent compatible Anvil binary and the
+`provider-anvil-node` feature.
+
+Use `EnvKzgSettings::Default` only when its environment-selected settings match the network. KZG
+setup and sidecar conversion errors should stop submission rather than falling back to a different
+format silently.
+
+For ordinary pre-PeerDAS blob transactions, use the [EIP-4844 guide](/transactions/sending-an-EIP-4844-transaction).

vocs/sidebar.ts

@@ -49,6 +49,7 @@ export const sidebar: Sidebar = [
       { text: 'Legacy Transaction', link: '/transactions/sending-a-legacy-transaction' },
       { text: 'EIP-1559 Transaction', link: '/transactions/sending-an-EIP-1559-transaction' },
       { text: 'EIP-4844 Transaction', link: '/transactions/sending-an-EIP-4844-transaction' },
+      { text: 'EIP-7594 Blob Sidecar', link: '/transactions/sending-an-EIP-7594-transaction' },
       { text: 'EIP-7702 Transaction', link: '/transactions/sending-an-EIP-7702-transaction' },
       { text: 'Using Access Lists', link: '/transactions/using-access-lists' },
     ]
@@ -76,6 +77,7 @@ export const sidebar: Sidebar = [
       text: 'Reference',
       items: [
         { text: 'Feature Flags', link: '/reference/feature-flags' },
+        { text: 'Protocol and RPC Types', link: '/reference/protocol-and-rpc-types' },
       ]
     },
     {