alloy_eips/
eip2718.rs

1//! [EIP-2718] traits.
2//!
3//! [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
4
5use crate::alloc::vec::Vec;
6use alloy_primitives::{keccak256, Bytes, Sealable, Sealed, B256};
7use alloy_rlp::{Buf, BufMut, Header, EMPTY_STRING_CODE};
8use auto_impl::auto_impl;
9use core::fmt;
10
11// https://eips.ethereum.org/EIPS/eip-2718#transactiontype-only-goes-up-to-0x7f
12const TX_TYPE_BYTE_MAX: u8 = 0x7f;
13
14/// Identifier for legacy transaction, however a legacy tx is technically not
15/// typed.
16pub const LEGACY_TX_TYPE_ID: u8 = 0;
17
18/// Identifier for an EIP2930 transaction.
19pub const EIP2930_TX_TYPE_ID: u8 = 1;
20
21/// Identifier for an EIP1559 transaction.
22pub const EIP1559_TX_TYPE_ID: u8 = 2;
23
24/// Identifier for an EIP4844 transaction.
25pub const EIP4844_TX_TYPE_ID: u8 = 3;
26
27/// Identifier for an EIP7702 transaction.
28pub const EIP7702_TX_TYPE_ID: u8 = 4;
29
30/// [EIP-2718] decoding errors.
31///
32/// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
33#[derive(Clone, Copy, Debug)]
34#[non_exhaustive] // NB: non-exhaustive allows us to add a Custom variant later
35pub enum Eip2718Error {
36    /// Rlp error from [`alloy_rlp`].
37    RlpError(alloy_rlp::Error),
38    /// Got an unexpected type flag while decoding.
39    UnexpectedType(u8),
40}
41
42/// Result type for [EIP-2718] decoding.
43pub type Eip2718Result<T, E = Eip2718Error> = core::result::Result<T, E>;
44
45impl fmt::Display for Eip2718Error {
46    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47        match self {
48            Self::RlpError(err) => write!(f, "{err}"),
49            Self::UnexpectedType(t) => write!(f, "Unexpected type flag. Got {t}."),
50        }
51    }
52}
53
54impl From<alloy_rlp::Error> for Eip2718Error {
55    fn from(err: alloy_rlp::Error) -> Self {
56        Self::RlpError(err)
57    }
58}
59
60impl From<Eip2718Error> for alloy_rlp::Error {
61    fn from(err: Eip2718Error) -> Self {
62        match err {
63            Eip2718Error::RlpError(err) => err,
64            Eip2718Error::UnexpectedType(_) => Self::Custom("Unexpected type flag"),
65        }
66    }
67}
68
69impl core::error::Error for Eip2718Error {}
70
71/// Decoding trait for [EIP-2718] envelopes. These envelopes wrap a transaction
72/// or a receipt with a type flag.
73///
74/// Users should rarely import this trait, and should instead prefer letting the
75/// alloy `Provider` methods handle encoding
76///
77/// ## Implementing
78///
79/// Implement this trait when you need to make custom TransactionEnvelope
80/// and ReceiptEnvelope types for your network. These types should be enums
81/// over the accepted transaction types.
82///
83/// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
84pub trait Decodable2718: Sized {
85    /// Extract the type byte from the buffer, if any. The type byte is the
86    /// first byte, provided that first byte is 0x7f or lower.
87    fn extract_type_byte(buf: &mut &[u8]) -> Option<u8> {
88        buf.first().copied().filter(|b| *b <= TX_TYPE_BYTE_MAX)
89    }
90
91    /// Decode the appropriate variant, based on the type flag.
92    ///
93    /// This function is invoked by [`Self::decode_2718`] with the type byte,
94    /// and the tail of the buffer.
95    ///
96    /// ## Implementing
97    ///
98    /// This should be a simple match block that invokes an inner type's
99    /// specific decoder.
100    fn typed_decode(ty: u8, buf: &mut &[u8]) -> Eip2718Result<Self>;
101
102    /// Decode the default variant.
103    ///
104    /// ## Implementing
105    ///
106    /// This function is invoked by [`Self::decode_2718`] when no type byte can
107    /// be extracted. It should be a simple wrapper around the default type's
108    /// decoder.
109    fn fallback_decode(buf: &mut &[u8]) -> Eip2718Result<Self>;
110
111    /// Decode the transaction according to [EIP-2718] rules. First a 1-byte
112    /// type flag in the range 0x0-0x7f, then the body of the transaction.
113    ///
114    /// [EIP-2718] inner encodings are unspecified, and produce an opaque
115    /// bytestring.
116    ///
117    /// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
118    fn decode_2718(buf: &mut &[u8]) -> Eip2718Result<Self> {
119        Self::extract_type_byte(buf)
120            .map(|ty| {
121                buf.advance(1);
122                Self::typed_decode(ty, buf)
123            })
124            .unwrap_or_else(|| Self::fallback_decode(buf))
125    }
126
127    /// Decode a transaction according to [EIP-2718], ensuring no trailing bytes.
128    ///
129    /// This method decodes a single transaction from the entire buffer and ensures that the
130    /// buffer is completely consumed. If there are any trailing bytes after the transaction
131    /// data, an error is returned.
132    ///
133    /// This is different from [`decode_2718`](Self::decode_2718) which allows trailing bytes
134    /// in the buffer. This method is useful when you need to ensure that the input contains
135    /// exactly one transaction and nothing else.
136    ///
137    /// # Errors
138    ///
139    /// Returns an error if:
140    /// - The transaction data is invalid
141    /// - There are trailing bytes after the transaction
142    ///
143    /// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
144    fn decode_2718_exact(bytes: &[u8]) -> Eip2718Result<Self> {
145        let mut buf = bytes;
146        let tx = Self::decode_2718(&mut buf)?;
147        if !buf.is_empty() {
148            return Err(Eip2718Error::RlpError(alloy_rlp::Error::UnexpectedLength));
149        }
150        Ok(tx)
151    }
152
153    /// Decode an [EIP-2718] transaction in the network format. The network
154    /// format is used ONLY by the Ethereum p2p protocol. Do not call this
155    /// method unless you are building a p2p protocol client.
156    ///
157    /// The network encoding is the RLP encoding of the eip2718-encoded
158    /// envelope.
159    ///
160    /// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
161    fn network_decode(buf: &mut &[u8]) -> Eip2718Result<Self> {
162        // Keep the original buffer around by copying it.
163        let mut h_decode = *buf;
164        let h = Header::decode(&mut h_decode)?;
165
166        // If it's a list, we need to fallback to the legacy decoding.
167        if h.list {
168            return Self::fallback_decode(buf);
169        }
170        *buf = h_decode;
171
172        let remaining_len = buf.len();
173        if remaining_len == 0 || remaining_len < h.payload_length {
174            return Err(alloy_rlp::Error::InputTooShort.into());
175        }
176
177        let ty = buf.get_u8();
178        let tx = Self::typed_decode(ty, buf)?;
179
180        let bytes_consumed = remaining_len - buf.len();
181        // because Header::decode works for single bytes (including the tx type), returning a
182        // string Header with payload_length of 1, we need to make sure this check is only
183        // performed for transactions with a string header
184        if bytes_consumed != h.payload_length && h_decode[0] > EMPTY_STRING_CODE {
185            return Err(alloy_rlp::Error::UnexpectedLength.into());
186        }
187
188        Ok(tx)
189    }
190}
191
192impl<T: Decodable2718 + Sealable> Decodable2718 for Sealed<T> {
193    fn extract_type_byte(buf: &mut &[u8]) -> Option<u8> {
194        T::extract_type_byte(buf)
195    }
196
197    fn typed_decode(ty: u8, buf: &mut &[u8]) -> Eip2718Result<Self> {
198        T::typed_decode(ty, buf).map(Self::new)
199    }
200
201    fn fallback_decode(buf: &mut &[u8]) -> Eip2718Result<Self> {
202        T::fallback_decode(buf).map(Self::new)
203    }
204
205    fn decode_2718(buf: &mut &[u8]) -> Eip2718Result<Self> {
206        T::decode_2718(buf).map(Self::new)
207    }
208
209    fn network_decode(buf: &mut &[u8]) -> Eip2718Result<Self> {
210        T::network_decode(buf).map(Self::new)
211    }
212}
213
214/// Encoding trait for [EIP-2718] envelopes.
215///
216/// These envelopes wrap a transaction or a receipt with a type flag. [EIP-2718] encodings are used
217/// by the `eth_sendRawTransaction` RPC call, the Ethereum block header's tries, and the
218/// peer-to-peer protocol.
219///
220/// Users should rarely import this trait, and should instead prefer letting the
221/// alloy `Provider` methods handle encoding
222///
223/// ## Implementing
224///
225/// Implement this trait when you need to make custom TransactionEnvelope
226/// and ReceiptEnvelope types for your network. These types should be enums
227/// over the accepted transaction types.
228///
229/// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
230#[auto_impl(&)]
231pub trait Encodable2718: Typed2718 + Sized + Send + Sync {
232    /// Return the type flag (if any).
233    ///
234    /// This should return `None` for the default (legacy) variant of the
235    /// envelope.
236    fn type_flag(&self) -> Option<u8> {
237        match self.ty() {
238            LEGACY_TX_TYPE_ID => None,
239            ty => Some(ty),
240        }
241    }
242
243    /// The length of the 2718 encoded envelope. This is the length of the type
244    /// flag + the length of the inner encoding.
245    fn encode_2718_len(&self) -> usize;
246
247    /// Encode the transaction according to [EIP-2718] rules. First a 1-byte
248    /// type flag in the range 0x0-0x7f, then the body of the transaction.
249    ///
250    /// [EIP-2718] inner encodings are unspecified, and produce an opaque
251    /// bytestring.
252    ///
253    /// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
254    fn encode_2718(&self, out: &mut dyn BufMut);
255
256    /// Encode the transaction according to [EIP-2718] rules. First a 1-byte
257    /// type flag in the range 0x0-0x7f, then the body of the transaction.
258    ///
259    /// This is a convenience method for encoding into a vec, and returning the
260    /// vec.
261    fn encoded_2718(&self) -> Vec<u8> {
262        let mut out = Vec::with_capacity(self.encode_2718_len());
263        self.encode_2718(&mut out);
264        out
265    }
266
267    /// Compute the hash as committed to in the MPT trie. This hash is used
268    /// ONLY by the Ethereum merkle-patricia trie and associated proofs. Do not
269    /// call this method unless you are building a full or light client.
270    ///
271    /// The trie hash is the keccak256 hash of the 2718-encoded envelope.
272    fn trie_hash(&self) -> B256 {
273        keccak256(self.encoded_2718())
274    }
275
276    /// Seal the encodable, by encoding and hashing it.
277    #[auto_impl(keep_default_for(&))]
278    fn seal(self) -> Sealed<Self> {
279        let hash = self.trie_hash();
280        Sealed::new_unchecked(self, hash)
281    }
282
283    /// A convenience function that encodes the value in the 2718 format and wraps it in a
284    /// [`WithEncoded`] wrapper.
285    ///
286    /// See also [`WithEncoded::from_2718_encodable`].
287    #[auto_impl(keep_default_for(&))]
288    fn into_encoded(self) -> WithEncoded<Self> {
289        WithEncoded::from_2718_encodable(self)
290    }
291
292    /// The length of the 2718 encoded envelope in network format. This is the
293    /// length of the header + the length of the type flag and inner encoding.
294    fn network_len(&self) -> usize {
295        let mut payload_length = self.encode_2718_len();
296        if !self.is_legacy() {
297            payload_length += Header { list: false, payload_length }.length();
298        }
299
300        payload_length
301    }
302
303    /// Encode in the network format. The network format is used ONLY by the
304    /// Ethereum p2p protocol. Do not call this method unless you are building
305    /// a p2p protocol client.
306    ///
307    /// The network encoding is the RLP encoding of the eip2718-encoded
308    /// envelope.
309    fn network_encode(&self, out: &mut dyn BufMut) {
310        if !self.is_legacy() {
311            Header { list: false, payload_length: self.encode_2718_len() }.encode(out);
312        }
313
314        self.encode_2718(out);
315    }
316}
317
318impl<T: Encodable2718> Encodable2718 for Sealed<T> {
319    fn encode_2718_len(&self) -> usize {
320        self.inner().encode_2718_len()
321    }
322
323    fn encode_2718(&self, out: &mut dyn alloy_rlp::BufMut) {
324        self.inner().encode_2718(out);
325    }
326
327    fn trie_hash(&self) -> B256 {
328        self.hash()
329    }
330}
331
332/// An [EIP-2718] envelope, blanket implemented for types that impl [`Encodable2718`] and
333/// [`Decodable2718`].
334///
335/// This envelope is a wrapper around a transaction, or a receipt, or any other type that is
336/// differentiated by an EIP-2718 transaction type.
337///
338/// [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
339pub trait Eip2718Envelope: Decodable2718 + Encodable2718 {}
340impl<T> Eip2718Envelope for T where T: Decodable2718 + Encodable2718 {}
341
342/// A trait that helps to determine the type of the transaction.
343#[auto_impl::auto_impl(&)]
344pub trait Typed2718 {
345    /// Returns the EIP-2718 type flag.
346    fn ty(&self) -> u8;
347
348    /// Returns true if the type matches the given type.
349    fn is_type(&self, ty: u8) -> bool {
350        self.ty() == ty
351    }
352
353    /// Returns true if the type is a legacy transaction.
354    fn is_legacy(&self) -> bool {
355        self.ty() == LEGACY_TX_TYPE_ID
356    }
357
358    /// Returns true if the type is an EIP-2930 transaction.
359    fn is_eip2930(&self) -> bool {
360        self.ty() == EIP2930_TX_TYPE_ID
361    }
362
363    /// Returns true if the type is an EIP-1559 transaction.
364    fn is_eip1559(&self) -> bool {
365        self.ty() == EIP1559_TX_TYPE_ID
366    }
367
368    /// Returns true if the type is an EIP-4844 transaction.
369    fn is_eip4844(&self) -> bool {
370        self.ty() == EIP4844_TX_TYPE_ID
371    }
372
373    /// Returns true if the type is an EIP-7702 transaction.
374    fn is_eip7702(&self) -> bool {
375        self.ty() == EIP7702_TX_TYPE_ID
376    }
377}
378
379impl<T: Typed2718> Typed2718 for Sealed<T> {
380    fn ty(&self) -> u8 {
381        self.inner().ty()
382    }
383}
384
385#[cfg(feature = "serde")]
386impl<T: Typed2718> Typed2718 for alloy_serde::WithOtherFields<T> {
387    #[inline]
388    fn ty(&self) -> u8 {
389        self.inner.ty()
390    }
391}
392
393/// Generic wrapper with encoded Bytes, such as transaction data.
394#[derive(Debug, Clone, PartialEq, Eq)]
395pub struct WithEncoded<T>(Bytes, pub T);
396
397impl<T> From<(Bytes, T)> for WithEncoded<T> {
398    fn from(value: (Bytes, T)) -> Self {
399        Self(value.0, value.1)
400    }
401}
402
403impl<T> WithEncoded<T> {
404    /// Wraps the value with the bytes.
405    pub const fn new(bytes: Bytes, value: T) -> Self {
406        Self(bytes, value)
407    }
408
409    /// Get the encoded bytes
410    pub const fn encoded_bytes(&self) -> &Bytes {
411        &self.0
412    }
413
414    /// Returns ownership of the encoded bytes.
415    pub fn into_encoded_bytes(self) -> Bytes {
416        self.0
417    }
418
419    /// Get the underlying value
420    pub const fn value(&self) -> &T {
421        &self.1
422    }
423
424    /// Returns ownership of the underlying value.
425    pub fn into_value(self) -> T {
426        self.1
427    }
428
429    /// Transform the value
430    pub fn transform<F: From<T>>(self) -> WithEncoded<F> {
431        WithEncoded(self.0, self.1.into())
432    }
433
434    /// Split the wrapper into [`Bytes`] and value tuple
435    pub fn split(self) -> (Bytes, T) {
436        (self.0, self.1)
437    }
438
439    /// Maps the inner value to a new value using the given function.
440    pub fn map<U, F: FnOnce(T) -> U>(self, op: F) -> WithEncoded<U> {
441        WithEncoded(self.0, op(self.1))
442    }
443}
444
445impl<T: Encodable2718> WithEncoded<T> {
446    /// Wraps the value with the [`Encodable2718::encoded_2718`] bytes.
447    pub fn from_2718_encodable(value: T) -> Self {
448        Self(value.encoded_2718().into(), value)
449    }
450}
451
452impl<T> WithEncoded<Option<T>> {
453    /// returns `None` if the inner value is `None`, otherwise returns `Some(WithEncoded<T>)`.
454    pub fn transpose(self) -> Option<WithEncoded<T>> {
455        self.1.map(|v| WithEncoded(self.0, v))
456    }
457}
458
459impl<L: Encodable2718, R: Encodable2718> Encodable2718 for either::Either<L, R> {
460    fn encode_2718_len(&self) -> usize {
461        match self {
462            Self::Left(l) => l.encode_2718_len(),
463            Self::Right(r) => r.encode_2718_len(),
464        }
465    }
466
467    fn encode_2718(&self, out: &mut dyn BufMut) {
468        match self {
469            Self::Left(l) => l.encode_2718(out),
470            Self::Right(r) => r.encode_2718(out),
471        }
472    }
473}
474
475impl<L: Typed2718, R: Typed2718> Typed2718 for either::Either<L, R> {
476    fn ty(&self) -> u8 {
477        match self {
478            Self::Left(l) => l.ty(),
479            Self::Right(r) => r.ty(),
480        }
481    }
482}
483
484/// Trait for checking if a transaction envelope supports a given EIP-2718 type ID.
485pub trait IsTyped2718 {
486    /// Returns true if the given type ID corresponds to a supported typed transaction.
487    fn is_type(type_id: u8) -> bool;
488}
489
490impl<L, R> IsTyped2718 for either::Either<L, R>
491where
492    L: IsTyped2718,
493    R: IsTyped2718,
494{
495    fn is_type(type_id: u8) -> bool {
496        L::is_type(type_id) || R::is_type(type_id)
497    }
498}
499
500impl<L, R> Decodable2718 for either::Either<L, R>
501where
502    L: Decodable2718 + IsTyped2718,
503    R: Decodable2718,
504{
505    fn typed_decode(ty: u8, buf: &mut &[u8]) -> Eip2718Result<Self> {
506        if L::is_type(ty) {
507            let envelope = L::typed_decode(ty, buf)?;
508            Ok(Self::Left(envelope))
509        } else {
510            let other = R::typed_decode(ty, buf)?;
511            Ok(Self::Right(other))
512        }
513    }
514    fn fallback_decode(buf: &mut &[u8]) -> Eip2718Result<Self> {
515        if buf.is_empty() {
516            return Err(Eip2718Error::RlpError(alloy_rlp::Error::InputTooShort));
517        }
518        L::fallback_decode(buf).map(Self::Left)
519    }
520}
alloy_eips/eip2718.rs

alloy_eips/
eip2718.rs
