alloy-rs · mattsse · Jul 16, 2026 · Jul 16, 2026
@@ -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).
@@ -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`)

@@ -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).
@@ -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' },
       ]
     },
     {