alloy_eips/
eip7685.rs

1//! [EIP-7685]: General purpose execution layer requests
2//!
3//! [EIP-7685]: https://eips.ethereum.org/EIPS/eip-7685
4
5use alloc::vec::Vec;
6use alloy_primitives::{b256, Bytes, B256};
7use derive_more::{Deref, DerefMut, From, IntoIterator};
8
9/// The empty requests hash.
10///
11/// This is equivalent to `sha256("")`
12pub const EMPTY_REQUESTS_HASH: B256 =
13    b256!("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
14
15/// A container of EIP-7685 requests.
16///
17/// The container only holds the `requests` as defined by their respective EIPs. The first byte of
18/// each element is the `request_type` and the remaining bytes are the `request_data`.
19#[derive(Debug, Clone, PartialEq, Eq, Default, Hash, Deref, DerefMut, From, IntoIterator)]
20#[cfg_attr(any(test, feature = "arbitrary"), derive(arbitrary::Arbitrary))]
21#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
22pub struct Requests(Vec<Bytes>);
23
24impl Requests {
25    /// Construct a new [`Requests`] container with the given capacity.
26    pub fn with_capacity(capacity: usize) -> Self {
27        Self(Vec::with_capacity(capacity))
28    }
29
30    /// Construct a new [`Requests`] container.
31    ///
32    /// This function assumes that the request type byte is already included as the
33    /// first byte in the provided `Bytes` blob.
34    pub const fn new(requests: Vec<Bytes>) -> Self {
35        Self(requests)
36    }
37
38    /// Add a new request into the container.
39    pub fn push_request(&mut self, request: Bytes) {
40        // Omit empty requests.
41        if request.len() == 1 {
42            return;
43        }
44        self.0.push(request);
45    }
46
47    /// Adds a new request with the given request type into the container.
48    pub fn push_request_with_type(
49        &mut self,
50        request_type: u8,
51        request: impl IntoIterator<Item = u8>,
52    ) {
53        let mut request = request.into_iter().peekable();
54        // Omit empty requests.
55        if request.peek().is_none() {
56            return;
57        }
58        self.0.push(core::iter::once(request_type).chain(request).collect());
59    }
60
61    /// Consumes [`Requests`] and returns the inner raw opaque requests.
62    ///
63    /// # Note
64    ///
65    /// These requests include the `request_type` as the first byte in each
66    /// `Bytes` element, followed by the `requests_data`.
67    pub fn take(self) -> Vec<Bytes> {
68        self.0
69    }
70
71    /// Get an iterator over the requests.
72    pub fn iter(&self) -> core::slice::Iter<'_, Bytes> {
73        self.0.iter()
74    }
75
76    /// Calculate the requests hash as defined in EIP-7685 for the requests.
77    ///
78    /// The requests hash is defined as
79    ///
80    /// ```text
81    /// sha256(sha256(requests_0) ++ sha256(requests_1) ++ ...)
82    /// ```
83    ///
84    /// Each request in the container is expected to already have the `request_type` prepended
85    /// to its corresponding `requests_data`. This function directly calculates the hash based
86    /// on the combined `request_type` and `requests_data`.
87    ///
88    /// Empty requests are omitted from the hash calculation.
89    /// Requests are sorted by their `request_type` before hashing, see also [Ordering](https://eips.ethereum.org/EIPS/eip-7685#ordering)
90    #[cfg(feature = "sha2")]
91    pub fn requests_hash(&self) -> B256 {
92        use sha2::{Digest, Sha256};
93        let mut hash = Sha256::new();
94
95        let mut requests: Vec<_> = self.0.iter().filter(|req| !req.is_empty()).collect();
96        requests.sort_unstable_by_key(|req| {
97            // SAFETY: only includes non-empty requests
98            req[0]
99        });
100
101        for req in requests {
102            let mut req_hash = Sha256::new();
103            req_hash.update(req);
104            hash.update(req_hash.finalize());
105        }
106        B256::new(hash.finalize().into())
107    }
108
109    /// Extend this container with requests from another container.
110    pub fn extend(&mut self, other: Self) {
111        self.0.extend(other.take());
112    }
113}
114
115/// A list of requests or a precomputed requests hash.
116///
117/// For testing purposes, the `Hash` variant stores a precomputed requests hash. This can be useful
118/// when the exact contents of the requests are unnecessary, and only a consistent hash value is
119/// needed to simulate the presence of requests without holding actual data.
120#[derive(Debug, Clone, PartialEq, Eq, Hash, derive_more::From)]
121#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
122pub enum RequestsOrHash {
123    /// Stores a list of requests, allowing for dynamic requests hash calculation.
124    Requests(Requests),
125    /// Stores a precomputed requests hash, used primarily for testing or mocking because the
126    /// header only contains the hash.
127    Hash(B256),
128}
129
130impl RequestsOrHash {
131    /// Returns the requests hash for the enum instance.
132    ///
133    /// - If the instance contains a list of requests, this function calculates the hash using
134    ///   `requests_hash` of the [`Requests`] struct.
135    /// - If it contains a precomputed hash, it returns that hash directly.
136    #[cfg(feature = "sha2")]
137    pub fn requests_hash(&self) -> B256 {
138        match self {
139            Self::Requests(requests) => requests.requests_hash(),
140            Self::Hash(precomputed_hash) => *precomputed_hash,
141        }
142    }
143
144    /// Returns an instance with the [`EMPTY_REQUESTS_HASH`].
145    pub const fn empty() -> Self {
146        Self::Hash(EMPTY_REQUESTS_HASH)
147    }
148
149    /// Returns the requests, if any.
150    pub const fn requests(&self) -> Option<&Requests> {
151        match self {
152            Self::Requests(requests) => Some(requests),
153            Self::Hash(_) => None,
154        }
155    }
156}
157
158impl Default for RequestsOrHash {
159    fn default() -> Self {
160        Self::Requests(Requests::default())
161    }
162}
163
164#[cfg(test)]
165mod tests {
166    use super::*;
167
168    #[test]
169    fn test_extend() {
170        // Test extending a Requests container with another Requests container
171        let mut reqs1 = Requests::new(vec![Bytes::from(vec![0x01, 0x02])]);
172        let reqs2 =
173            Requests::new(vec![Bytes::from(vec![0x03, 0x04]), Bytes::from(vec![0x05, 0x06])]);
174
175        // Extend reqs1 with reqs2
176        reqs1.extend(reqs2);
177
178        // Ensure the requests are correctly combined
179        assert_eq!(reqs1.0.len(), 3);
180        assert_eq!(
181            reqs1.0,
182            vec![
183                Bytes::from(vec![0x01, 0x02]),
184                Bytes::from(vec![0x03, 0x04]),
185                Bytes::from(vec![0x05, 0x06])
186            ]
187        );
188    }
189
190    #[test]
191    #[cfg(feature = "sha2")]
192    fn test_consistent_requests_hash() {
193        // We test that the empty requests hash is consistent with the EIP-7685 definition.
194        assert_eq!(Requests::default().requests_hash(), EMPTY_REQUESTS_HASH);
195
196        // Test to hash a non-empty vector of requests.
197        assert_eq!(
198            Requests(vec![
199                Bytes::from(vec![0x00, 0x0a, 0x0b, 0x0c]),
200                Bytes::from(vec![0x01, 0x0d, 0x0e, 0x0f])
201            ])
202            .requests_hash(),
203            b256!("be3a57667b9bb9e0275019c0faf0f415fdc8385a408fd03e13a5c50615e3530c"),
204        );
205    }
206}
alloy_eips/eip7685.rs

alloy_eips/
eip7685.rs
