chore(sdk): SignedTransaction abstraction

crates/primitives-traits/Cargo.toml

@@ -65,3 +65,4 @@ arbitrary = [
     "dep:proptest-arbitrary-interop",
 ]
 serde-bincode-compat = ["serde_with", "alloy-consensus/serde-bincode-compat"]
+optimism = []

crates/primitives-traits/src/lib.rs

@@ -20,6 +20,12 @@ pub use constants::gas_units::{format_gas, format_gas_throughput};
 pub mod account;
 pub use account::{Account, Bytecode};
 
+pub mod signed_tx;
+pub use signed_tx::SignedTransaction;
+
+pub mod signature;
+pub use signature::Signature;
+
 mod integer_list;
 pub use integer_list::{IntegerList, IntegerListError};
 

crates/primitives-traits/src/signature.rs

@@ -0,0 +1,33 @@
+//! Signature abstraction
+
+use alloy_primitives::{Parity, U256};
+
+/// A signature.
+pub trait Signature: Sized + Send + Sync {
+    /// Decodes RLP-encoded signature, w.r.t. chain ID.
+    fn decode_with_eip155_chain_id(buf: &mut &[u8]) -> alloy_rlp::Result<(Self, Option<u64>)>;
+}
+
+impl Signature for alloy_primitives::Signature {
+    fn decode_with_eip155_chain_id(buf: &mut &[u8]) -> alloy_rlp::Result<(Self, Option<u64>)> {
+        let v: Parity = alloy_rlp::Decodable::decode(buf)?;
+        let r: U256 = alloy_rlp::Decodable::decode(buf)?;
+        let s: U256 = alloy_rlp::Decodable::decode(buf)?;
+
+        #[cfg(not(feature = "optimism"))]
+        if matches!(v, Parity::Parity(_)) {
+            return Err(alloy_rlp::Error::Custom("invalid parity for legacy transaction"));
+        }
+
+        #[cfg(feature = "optimism")]
+        // pre bedrock system transactions were sent from the zero address as legacy
+        // transactions with an empty signature
+        //
+        // NOTE: this is very hacky and only relevant for op-mainnet pre bedrock
+        if matches!(v, Parity::Parity(false)) && r.is_zero() && s.is_zero() {
+            return Ok((Self::new(r, s, Parity::Parity(false)), None))
+        }
+
+        Ok((Self::new(r, s, v), v.chain_id()))
+    }
+}

crates/primitives-traits/src/signed_tx.rs

@@ -0,0 +1,138 @@
+//! API of a signed transaction, w.r.t. network stack.
+
+use alloc::fmt;
+use core::hash::Hash;
+
+use alloy_consensus::{SignableTransaction, TxLegacy};
+use alloy_eips::eip2718::{Decodable2718, Encodable2718};
+use alloy_primitives::{keccak256, Address, TxHash, B256};
+
+use crate::Signature;
+
+/// A signed transaction.
+pub trait SignedTransaction:
+    fmt::Debug
+    + Clone
+    + PartialEq
+    + Eq
+    + Hash
+    + Send
+    + Sync
+    + serde::Serialize
+    + for<'a> serde::Deserialize<'a>
+    + alloy_rlp::Encodable
+    + alloy_rlp::Decodable
+    + Encodable2718
+    + Decodable2718
+{
+    /// Transaction type that is signed.
+    type Transaction: SignableTransaction<Self::Signature>;
+
+    /// Signature type that results from signing transaction.
+    type Signature: Signature;
+
+    /// Returns reference to transaction hash.
+    fn tx_hash(&self) -> &TxHash;
+
+    /// Returns reference to transaction.
+    fn transaction(&self) -> &Self::Transaction;
+
+    /// Returns reference to signature.
+    fn signature(&self) -> &Self::Signature;
+
+    /// Recover signer from signature and hash.
+    ///
+    /// Returns `None` if the transaction's signature is invalid following [EIP-2](https://eips.ethereum.org/EIPS/eip-2), see also `reth_primitives::transaction::recover_signer`.
+    ///
+    /// Note:
+    ///
+    /// This can fail for some early ethereum mainnet transactions pre EIP-2, use
+    /// [`Self::recover_signer_unchecked`] if you want to recover the signer without ensuring that
+    /// the signature has a low `s` value.
+    fn recover_signer(&self) -> Option<Address>;
+
+    /// Recover signer from signature and hash _without ensuring that the signature has a low `s`
+    /// value_.
+    ///
+    /// Returns `None` if the transaction's signature is invalid, see also
+    /// `reth_primitives::transaction::recover_signer_unchecked`.
+    fn recover_signer_unchecked(&self) -> Option<Address>;
+
+    /// Output the length of the `encode_inner(out`, true). Note to assume that `with_header` is
+    /// only `true`.
+    fn payload_len_inner(&self) -> usize;
+
+    /// Returns the length without an RLP header - this is used for eth/68 sizes.
+    fn length_without_header(&self) -> usize;
+
+    /// Decodes legacy transaction from the data buffer.
+    ///
+    /// This should be used _only_ be used in general transaction decoding methods, which have
+    /// already ensured that the input is a legacy transaction with the following format:
+    /// `rlp(legacy_tx)`
+    ///
+    /// Legacy transactions are encoded as lists, so the input should start with a RLP list header.
+    ///
+    /// This expects `rlp(legacy_tx)`
+    // TODO: make buf advancement semantics consistent with `decode_enveloped_typed_transaction`,
+    // so decoding methods do not need to manually advance the buffer
+    fn decode_rlp_legacy_transaction(data: &mut &[u8]) -> alloy_rlp::Result<Self>;
+
+    /// Decodes legacy transaction from the data buffer into a tuple.
+    ///
+    /// This expects `rlp(legacy_tx)`
+    ///
+    /// Refer to the docs for [`Self::decode_rlp_legacy_transaction`] for details on the exact
+    /// format expected.
+    fn decode_rlp_legacy_transaction_tuple(
+        data: &mut &[u8],
+    ) -> alloy_rlp::Result<(TxLegacy, TxHash, Self::Signature)> {
+        // keep this around, so we can use it to calculate the hash
+        let original_encoding = *data;
+
+        let header = alloy_rlp::Header::decode(data)?;
+        let remaining_len = data.len();
+
+        let transaction_payload_len = header.payload_length;
+
+        if transaction_payload_len > remaining_len {
+            return Err(alloy_rlp::Error::InputTooShort)
+        }
+
+        let mut transaction = TxLegacy {
+            nonce: alloy_rlp::Decodable::decode(data)?,
+            gas_price: alloy_rlp::Decodable::decode(data)?,
+            gas_limit: alloy_rlp::Decodable::decode(data)?,
+            to: alloy_rlp::Decodable::decode(data)?,
+            value: alloy_rlp::Decodable::decode(data)?,
+            input: alloy_rlp::Decodable::decode(data)?,
+            chain_id: None,
+        };
+        let (signature, extracted_id) = Self::Signature::decode_with_eip155_chain_id(data)?;
+        transaction.chain_id = extracted_id;
+
+        // check the new length, compared to the original length and the header length
+        let decoded = remaining_len - data.len();
+        if decoded != transaction_payload_len {
+            return Err(alloy_rlp::Error::UnexpectedLength)
+        }
+
+        let tx_length = header.payload_length + header.length();
+        let hash = keccak256(&original_encoding[..tx_length]);
+        Ok((transaction, hash, signature))
+    }
+
+    /// Create a new signed transaction from a transaction and its signature.
+    ///
+    /// This will also calculate the transaction hash using its encoding.
+    fn from_transaction_and_signature(
+        transaction: Self::Transaction,
+        signature: Self::Signature,
+    ) -> Self;
+
+    /// Calculate transaction hash, eip2728 transaction does not contain rlp header and start with
+    /// tx type.
+    fn recalculate_hash(&self) -> B256 {
+        keccak256(self.encoded_2718())
+    }
+}

crates/primitives/src/traits/mod.rs

@@ -1,7 +1,9 @@
 //! Abstractions of primitive data types
 
 pub mod block;
+pub mod transaction;
 
 pub use block::{body::BlockBody, Block};
+pub use transaction::signed::SignedTransaction;
 
 pub use alloy_consensus::BlockHeader;

crates/primitives/src/transaction/mod.rs

@@ -15,8 +15,8 @@ use core::mem;
 use derive_more::{AsRef, Deref};
 use once_cell::sync::Lazy;
 use rayon::prelude::{IntoParallelIterator, ParallelIterator};
+use reth_primitives_traits::Signature as _;
 use serde::{Deserialize, Serialize};
-use signature::{decode_with_eip155_chain_id, with_eip155_parity};
 
 pub use error::{
     InvalidTransactionError, TransactionConversionError, TryFromRecoveredTransactionError,
@@ -31,7 +31,8 @@ pub use sidecar::{BlobTransaction, BlobTransactionSidecar};
 
 pub use compat::FillTxEnv;
 pub use signature::{
-    extract_chain_id, legacy_parity, recover_signer, recover_signer_unchecked, Signature,
+    extract_chain_id, legacy_parity, recover_signer, recover_signer_unchecked, with_eip155_parity,
+    Signature,
 };
 pub use tx_type::{
     TxType, EIP1559_TX_TYPE_ID, EIP2930_TX_TYPE_ID, EIP4844_TX_TYPE_ID, EIP7702_TX_TYPE_ID,
@@ -1251,7 +1252,7 @@ impl TransactionSigned {
             input: Decodable::decode(data)?,
             chain_id: None,
         };
-        let (signature, extracted_id) = decode_with_eip155_chain_id(data)?;
+        let (signature, extracted_id) = Signature::decode_with_eip155_chain_id(data)?;
         transaction.chain_id = extracted_id;
 
         // check the new length, compared to the original length and the header length

crates/primitives/src/transaction/signature.rs

@@ -1,6 +1,6 @@
 use crate::transaction::util::secp256k1;
 use alloy_primitives::{Address, Parity, B256, U256};
-use alloy_rlp::{Decodable, Error as RlpError};
+use alloy_rlp::Error as RlpError;
 
 pub use alloy_primitives::Signature;
 
@@ -16,30 +16,6 @@ const SECP256K1N_HALF: U256 = U256::from_be_bytes([
     0x5D, 0x57, 0x6E, 0x73, 0x57, 0xA4, 0x50, 0x1D, 0xDF, 0xE9, 0x2F, 0x46, 0x68, 0x1B, 0x20, 0xA0,
 ]);
 
-pub(crate) fn decode_with_eip155_chain_id(
-    buf: &mut &[u8],
-) -> alloy_rlp::Result<(Signature, Option<u64>)> {
-    let v: Parity = Decodable::decode(buf)?;
-    let r: U256 = Decodable::decode(buf)?;
-    let s: U256 = Decodable::decode(buf)?;
-
-    #[cfg(not(feature = "optimism"))]
-    if matches!(v, Parity::Parity(_)) {
-        return Err(alloy_rlp::Error::Custom("invalid parity for legacy transaction"));
-    }
-
-    #[cfg(feature = "optimism")]
-    // pre bedrock system transactions were sent from the zero address as legacy
-    // transactions with an empty signature
-    //
-    // NOTE: this is very hacky and only relevant for op-mainnet pre bedrock
-    if matches!(v, Parity::Parity(false)) && r.is_zero() && s.is_zero() {
-        return Ok((Signature::new(r, s, Parity::Parity(false)), None))
-    }
-
-    Ok((Signature::new(r, s, v), v.chain_id()))
-}
-
 /// Recover signer from message hash, _without ensuring that the signature has a low `s`
 /// value_.
 ///
@@ -90,7 +66,7 @@ pub fn legacy_parity(signature: &Signature, chain_id: Option<u64>) -> Parity {
 }
 
 /// Returns a signature with the given chain ID applied to the `v` value.
-pub(crate) fn with_eip155_parity(signature: &Signature, chain_id: Option<u64>) -> Signature {
+pub fn with_eip155_parity(signature: &Signature, chain_id: Option<u64>) -> Signature {
     Signature::new(signature.r(), signature.s(), legacy_parity(signature, chain_id))
 }