docs: improve transaction trait documentation (#103)

* docs: improve transaction trait documentation

Adds comprehensive documentation for transaction-related traits to help
users understand how consensus transactions are converted for EVM execution.

Key improvements:
- Enhanced module-level docs explaining the trait system's purpose
- Added detailed trait documentation with examples for IntoTxEnv,
  FromRecoveredTx, FromTxWithEncoded, and ExecutableTx
- Clarified the transaction flow from consensus types to EVM execution
- Added context to BlockExecutor methods explaining ExecutableTx usage
- Fixed all documentation links to use proper Rust doc syntax
- Updated references from TransactionSigned to EthereumTxEnvelope

This makes it much clearer how recovered consensus transactions can be
seamlessly converted into the transaction type that the EVM operates on.

Closes #97

* fmt

* docs

* docs

Author: mattsse

crates/evm/src/block/mod.rs

@@ -34,6 +34,21 @@ pub struct BlockExecutionResult<T> {
 }
 
 /// Helper trait to encapsulate requirements for a type to be used as input for [`BlockExecutor`].
+///
+/// This trait combines the requirements for a transaction to be executable by a block executor:
+/// - Must be convertible to the EVM's transaction environment via [`IntoTxEnv`]
+/// - Must provide access to the transaction and signer via [`RecoveredTx`]
+/// - Must be [`Copy`] for efficient handling during block execution (the expectation here is that
+///   this always passed as & reference)
+///
+/// This trait is automatically implemented for any type that meets these requirements.
+/// Common implementations include:
+/// - [`Recovered<T>`](alloy_consensus::transaction::Recovered) where `T` is a transaction type
+/// - [`WithEncoded<Recovered<T>>`](alloy_eips::eip2718::WithEncoded) for transactions with encoded
+///   bytes
+///
+/// The trait ensures that the block executor can both execute the transaction in the EVM
+/// and access the original transaction data for receipt generation.
 pub trait ExecutableTx<E: BlockExecutor + ?Sized>:
     IntoTxEnv<<E::Evm as Evm>::Tx> + RecoveredTx<E::Transaction> + Copy
 {
@@ -73,17 +88,61 @@ impl CommitChanges {
 /// relevant information about the block execution.
 pub trait BlockExecutor {
     /// Input transaction type.
+    ///
+    /// This represents the consensus transaction type that the block executor operates on.
+    /// It's typically a type from the consensus layer (e.g.,
+    /// [`EthereumTxEnvelope`](alloy_consensus::EthereumTxEnvelope)) that contains
+    /// the raw transaction data, signature, and other consensus-level information.
+    ///
+    /// This type is used in several contexts:
+    /// - As the generic parameter for [`RecoveredTx<T>`](crate::RecoveredTx) in [`ExecutableTx`]
+    /// - As the generic parameter for [`FromRecoveredTx<T>`](crate::FromRecoveredTx) and
+    ///   [`FromTxWithEncoded<T>`](crate::FromTxWithEncoded) in the EVM constraint
+    /// - To generate receipts after transaction execution
+    ///
+    /// The transaction flow is:
+    /// 1. `Self::Transaction` (consensus tx) →
+    ///    [`Recovered<Self::Transaction>`](alloy_consensus::transaction::Recovered) (with sender)
+    /// 2. [`Recovered<Self::Transaction>`](alloy_consensus::transaction::Recovered) →
+    ///    [`TxEnv`](revm::context::TxEnv) (via [`FromRecoveredTx`])
+    /// 3. [`TxEnv`](revm::context::TxEnv) → EVM execution → [`ExecutionResult`]
+    /// 4. [`ExecutionResult`] + `Self::Transaction` → `Self::Receipt`
+    ///
+    /// Common examples:
+    /// - [`EthereumTxEnvelope`](alloy_consensus::EthereumTxEnvelope) for all Ethereum transaction
+    ///   variants
+    /// - `OpTxEnvelope` for opstack transaction variants
     type Transaction;
     /// Receipt type this executor produces.
     type Receipt;
     /// EVM used by the executor.
+    ///
+    /// The EVM's transaction type (`Evm::Tx`) must be able to be constructed from both:
+    /// - [`FromRecoveredTx<Self::Transaction>`](crate::FromRecoveredTx) - for transactions with
+    ///   recovered senders
+    /// - [`FromTxWithEncoded<Self::Transaction>`](crate::FromTxWithEncoded) - for transactions with
+    ///   encoded bytes
+    ///
+    /// This constraint ensures that the block executor can convert consensus transactions
+    /// into the EVM's transaction format for execution.
     type Evm: Evm<Tx: FromRecoveredTx<Self::Transaction> + FromTxWithEncoded<Self::Transaction>>;
 
     /// Applies any necessary changes before executing the block's transactions.
     fn apply_pre_execution_changes(&mut self) -> Result<(), BlockExecutionError>;
 
     /// Executes a single transaction and applies execution result to internal state.
     ///
+    /// This method accepts any type implementing [`ExecutableTx`], which ensures the transaction:
+    /// - Can be converted to the EVM's transaction environment for execution
+    /// - Provides access to the original transaction and signer for receipt generation
+    ///
+    /// Common input types include:
+    /// - `&Recovered<Transaction>` - A transaction with its recovered sender
+    /// - `&WithEncoded<Recovered<Transaction>>` - A transaction with sender and encoded bytes
+    ///
+    /// The transaction is executed in the EVM, state changes are committed, and a receipt
+    /// is generated internally.
+    ///
     /// Returns the gas used by the transaction.
     fn execute_transaction(
         &mut self,
@@ -94,6 +153,14 @@ pub trait BlockExecutor {
 
     /// Executes a single transaction and applies execution result to internal state. Invokes the
     /// given closure with an internal [`ExecutionResult`] produced by the EVM.
+    ///
+    /// This method is similar to [`execute_transaction`](Self::execute_transaction) but provides
+    /// access to the raw execution result before it's converted to a receipt. This is useful for:
+    /// - Custom logging or metrics collection
+    /// - Debugging transaction execution
+    /// - Extracting additional information from the execution result
+    ///
+    /// The transaction is always committed after the closure is invoked.
     fn execute_transaction_with_result_closure(
         &mut self,
         tx: impl ExecutableTx<Self>,
@@ -110,7 +177,22 @@ pub trait BlockExecutor {
     /// given closure with an internal [`ExecutionResult`] produced by the EVM, and commits the
     /// transaction to the state on [`CommitChanges::Yes`].
     ///
-    /// Returns [`None`] if transaction was skipped via [`CommitChanges::No`].
+    /// This is the most flexible transaction execution method, allowing conditional commitment
+    /// based on the execution result. The closure receives the execution result and returns
+    /// whether to commit the changes to state.
+    ///
+    /// Use cases:
+    /// - Conditional execution based on transaction outcome
+    /// - Simulating transactions without committing
+    /// - Custom validation logic before committing
+    ///
+    /// The [`ExecutableTx`] constraint ensures that:
+    /// 1. The transaction can be converted to `TxEnv` via [`IntoTxEnv`] for EVM execution
+    /// 2. The original transaction and signer can be accessed via [`RecoveredTx`] for receipt
+    ///    generation
+    ///
+    /// Returns [`None`] if commiting changes from the transaction should be skipped via
+    /// [`CommitChanges::No`], otherwise returns the gas used by the transaction.
     fn execute_transaction_with_commit_condition(
         &mut self,
         tx: impl ExecutableTx<Self>,
@@ -153,6 +235,26 @@ pub trait BlockExecutor {
     fn evm(&self) -> &Self::Evm;
 
     /// Executes all transactions in a block, applying pre and post execution changes.
+    ///
+    /// This is a convenience method that orchestrates the complete block execution flow:
+    /// 1. Applies pre-execution changes (system calls, irregular state transitions)
+    /// 2. Executes all transactions in order
+    /// 3. Applies post-execution changes (block rewards, system calls)
+    ///
+    /// Each transaction in the iterator must implement [`ExecutableTx`], ensuring it can be:
+    /// - Converted to the EVM's transaction format for execution
+    /// - Used to generate receipts with access to the original transaction data
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// let recovered_txs: Vec<Recovered<Transaction>> = block.transactions
+    ///     .iter()
+    ///     .map(|tx| tx.recover_signer())
+    ///     .collect::<Result<_, _>>()?;
+    ///
+    /// let result = executor.execute_block(recovered_txs.iter())?;
+    /// ```
     fn execute_block(
         mut self,
         transactions: impl IntoIterator<Item = impl ExecutableTx<Self>>,
@@ -221,6 +323,10 @@ pub trait BlockExecutorFactory: 'static {
     type ExecutionCtx<'a>: Clone;
 
     /// Transaction type used by the executor, see [`BlockExecutor::Transaction`].
+    ///
+    /// This should be the same consensus transaction type that the block executor operates on.
+    /// It represents the transaction format from your consensus layer that needs to be
+    /// executed by the EVM.
     type Transaction;
 
     /// Receipt type produced by the executor, see [`BlockExecutor::Receipt`].

crates/evm/src/evm.rs

@@ -28,9 +28,20 @@ pub trait Evm {
     type DB;
     /// The transaction object that the EVM will execute.
     ///
-    /// Implementations are expected to rely on a single entrypoint for transaction execution such
-    /// as [`revm::context::TxEnv`]. The actual set of valid inputs is not limited by allowing to
-    /// provide any [`IntoTxEnv`] implementation for [`Evm::transact`] method.
+    /// This type represents the transaction environment that the EVM operates on internally.
+    /// Typically this is [`revm::context::TxEnv`], which contains all necessary transaction
+    /// data like sender, gas limits, value, and calldata.
+    ///
+    /// The EVM accepts flexible transaction inputs through the [`IntoTxEnv`] trait. This means
+    /// that while the EVM internally works with `Self::Tx` (usually `TxEnv`), users can pass
+    /// various transaction formats to [`Evm::transact`], including:
+    /// - Direct [`TxEnv`](revm::context::TxEnv) instances
+    /// - [`Recovered<T>`](alloy_consensus::transaction::Recovered) where `T` implements
+    ///   [`crate::FromRecoveredTx`]
+    /// - [`WithEncoded<Recovered<T>>`](alloy_eips::eip2718::WithEncoded) where `T` implements
+    ///   [`crate::FromTxWithEncoded`]
+    ///
+    /// This design allows the EVM to accept recovered consensus transactions seamlessly.
     type Tx: IntoTxEnv<Self::Tx>;
     /// Error type returned by EVM. Contains either errors related to invalid transactions or
     /// internal irrecoverable execution errors.
@@ -59,8 +70,17 @@ pub trait Evm {
         tx: Self::Tx,
     ) -> Result<ResultAndState<Self::HaltReason>, Self::Error>;
 
-    /// Same as [`Evm::transact_raw`], but takes a [`IntoTxEnv`] implementation, thus allowing to
-    /// support transacting with an external type.
+    /// Same as [`Evm::transact_raw`], but takes any type implementing [`IntoTxEnv`].
+    ///
+    /// This is the primary method for executing transactions. It accepts flexible input types
+    /// that can be converted to the EVM's transaction environment, including:
+    /// - [`TxEnv`](revm::context::TxEnv) - Direct transaction environment
+    /// - [`Recovered<T>`](alloy_consensus::transaction::Recovered) - Consensus transaction with
+    ///   recovered sender
+    /// - [`WithEncoded<Recovered<T>>`](alloy_eips::eip2718::WithEncoded) - Transaction with sender
+    ///   and encoded bytes
+    ///
+    /// The conversion happens automatically through the [`IntoTxEnv`] trait.
     fn transact(
         &mut self,
         tx: impl IntoTxEnv<Self::Tx>,

crates/evm/src/tx.rs

@@ -1,4 +1,8 @@
-//! Abstraction of an executable transaction.
+//! Transaction abstractions for EVM execution.
+//!
+//! This module provides traits and implementations for converting various transaction formats
+//! into a unified transaction environment ([`TxEnv`]) that the EVM can execute. The main purpose
+//! of these traits is to enable flexible transaction input while maintaining type safety.
 
 use alloy_consensus::{
     crypto::secp256k1, transaction::Recovered, EthereumTxEnvelope, TxEip1559, TxEip2930, TxEip4844,
@@ -13,6 +17,26 @@ use alloy_primitives::{Address, Bytes, TxKind};
 use revm::{context::TxEnv, context_interface::either::Either};
 
 /// Trait marking types that can be converted into a transaction environment.
+///
+/// This is the primary trait that enables flexible transaction input for the EVM. The EVM's
+/// associated type `Evm::Tx` must implement this trait, and the `transact` method accepts
+/// any type implementing [`IntoTxEnv<Evm::Tx>`](IntoTxEnv).
+///
+/// # Example
+///
+/// ```ignore
+/// // Direct TxEnv usage
+/// let tx_env = TxEnv { caller: address, gas_limit: 100_000, ... };
+/// evm.transact(tx_env)?;
+///
+/// // Using a recovered transaction
+/// let recovered = tx.recover_signer()?;
+/// evm.transact(recovered)?;
+///
+/// // Using a transaction with encoded bytes
+/// let with_encoded = WithEncoded::new(recovered, encoded_bytes);
+/// evm.transact(with_encoded)?;
+/// ```
 pub trait IntoTxEnv<TxEnv> {
     /// Converts `self` into [`TxEnv`].
     fn into_tx_env(self) -> TxEnv;
@@ -34,9 +58,33 @@ where
     }
 }
 
-/// Helper user-facing trait to allow implementing [`IntoTxEnv`] on instances of [`Recovered`].
+/// Helper trait for building a transaction environment from a recovered transaction.
+///
+/// This trait enables the conversion of consensus transaction types (which have been recovered
+/// with their sender address) into the EVM's transaction environment. It's automatically used
+/// when a [`Recovered<T>`] type is passed to the EVM's `transact` method.
+///
+/// The expectation is that any recovered consensus transaction can be converted into the
+/// transaction type that the EVM operates on (typically [`TxEnv`]).
+///
+/// # Implementation
+///
+/// This trait is implemented for all standard Ethereum transaction types ([`TxLegacy`],
+/// [`TxEip2930`], [`TxEip1559`], [`TxEip4844`], [`TxEip7702`]) and transaction envelopes
+/// ([`EthereumTxEnvelope`]).
+///
+/// # Example
+///
+/// ```ignore
+/// // Recover the signer from a transaction
+/// let recovered = tx.recover_signer()?;
+///
+/// // The recovered transaction can now be used with the EVM
+/// // This works because Recovered<T> implements IntoTxEnv when T implements FromRecoveredTx
+/// evm.transact(recovered)?;
+/// ```
 pub trait FromRecoveredTx<Tx> {
-    /// Builds a `TxEnv` from a transaction and a sender address.
+    /// Builds a [`TxEnv`] from a transaction and a sender address.
     fn from_recovered_tx(tx: &Tx, sender: Address) -> Self;
 }
 
@@ -237,9 +285,9 @@ impl FromTxWithEncoded<TxEip7702> for TxEnv {
     }
 }
 
-/// Helper trait to abstract over different `Recovered<T>` implementations.
+/// Helper trait to abstract over different [`Recovered<T>`] implementations.
 ///
-/// Implemented for `Recovered<T>`, `Recovered<&T>`, `&Recovered<T>`, `&Recovered<&T>`
+/// Implemented for [`Recovered<T>`], `Recovered<&T>`, `&Recovered<T>`, `&Recovered<&T>`
 #[auto_impl::auto_impl(&)]
 pub trait RecoveredTx<T> {
     /// Returns the transaction.
@@ -279,10 +327,38 @@ impl<Tx, T: RecoveredTx<Tx>> RecoveredTx<Tx> for WithEncoded<T> {
     }
 }
 
-/// Helper user-facing trait to allow implementing [`IntoTxEnv`] on instances of [`WithEncoded`].
-/// This allows creating transaction environments directly from EIP-2718 encoded bytes.
+/// Helper trait for building a transaction environment from a transaction with its encoded form.
+///
+/// This trait enables the conversion of consensus transaction types along with their EIP-2718
+/// encoded bytes into the EVM's transaction environment. It's automatically used when a
+/// [`WithEncoded<Recovered<T>>`](WithEncoded) type is passed to the EVM's `transact` method.
+///
+/// The main purpose of this trait is to allow preserving the original encoded transaction data
+/// alongside the parsed transaction, which can be useful for:
+/// - Signature verification
+/// - Transaction hash computation
+/// - Re-encoding for network propagation
+/// - Optimism transaction handling (which requires encoded data, for Data availability costs).
+///
+/// # Implementation
+///
+/// Most implementations simply delegate to [`FromRecoveredTx`], ignoring the encoded bytes.
+/// However, specialized implementations (like Optimism's `OpTransaction`) may use the encoded
+/// data for additional functionality.
+///
+/// # Example
+///
+/// ```ignore
+/// // Create a transaction with its encoded form
+/// let encoded_bytes = tx.encoded_2718();
+/// let recovered = tx.recover_signer()?;
+/// let with_encoded = WithEncoded::new(recovered, encoded_bytes);
+///
+/// // The transaction with encoded data can be used with the EVM
+/// evm.transact(with_encoded)?;
+/// ```
 pub trait FromTxWithEncoded<Tx> {
-    /// Builds a `TxEnv` from a transaction, its sender, and encoded transaction bytes.
+    /// Builds a [`TxEnv`] from a transaction, its sender, and encoded transaction bytes.
     fn from_encoded_tx(tx: &Tx, sender: Address, encoded: Bytes) -> Self;
 }