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
24#[cfg(feature = "ssz")]
25impl ssz::Encode for Requests {
26    fn is_ssz_fixed_len() -> bool {
27        <Vec<Bytes> as ssz::Encode>::is_ssz_fixed_len()
28    }
29
30    fn ssz_fixed_len() -> usize {
31        <Vec<Bytes> as ssz::Encode>::ssz_fixed_len()
32    }
33
34    fn ssz_bytes_len(&self) -> usize {
35        self.0.ssz_bytes_len()
36    }
37
38    fn ssz_append(&self, buf: &mut Vec<u8>) {
39        self.0.ssz_append(buf);
40    }
41}
42
43#[cfg(feature = "ssz")]
44impl ssz::Decode for Requests {
45    fn is_ssz_fixed_len() -> bool {
46        <Vec<Bytes> as ssz::Decode>::is_ssz_fixed_len()
47    }
48
49    fn ssz_fixed_len() -> usize {
50        <Vec<Bytes> as ssz::Decode>::ssz_fixed_len()
51    }
52
53    fn from_ssz_bytes(bytes: &[u8]) -> Result<Self, ssz::DecodeError> {
54        <Vec<Bytes> as ssz::Decode>::from_ssz_bytes(bytes).map(Self)
55    }
56}
57
58impl Requests {
59    /// Create a new [`Requests`] container from an iterator of items convertible to [`Bytes`].
60    pub fn from_requests<T: Into<Bytes>>(requests: impl IntoIterator<Item = T>) -> Self {
61        Self(requests.into_iter().map(Into::into).collect())
62    }
63    /// Construct a new [`Requests`] container with the given capacity.
64    pub fn with_capacity(capacity: usize) -> Self {
65        Self(Vec::with_capacity(capacity))
66    }
67
68    /// Construct a new [`Requests`] container.
69    ///
70    /// This function assumes that the request type byte is already included as the
71    /// first byte in the provided `Bytes` blob.
72    pub const fn new(requests: Vec<Bytes>) -> Self {
73        Self(requests)
74    }
75
76    /// Add a new request into the container.
77    pub fn push_request(&mut self, request: Bytes) {
78        // Omit empty requests.
79        if request.len() == 1 {
80            return;
81        }
82        self.0.push(request);
83    }
84
85    /// Adds a new request with the given request type into the container.
86    pub fn push_request_with_type(
87        &mut self,
88        request_type: u8,
89        request: impl IntoIterator<Item = u8>,
90    ) {
91        let mut request = request.into_iter().peekable();
92        // Omit empty requests.
93        if request.peek().is_none() {
94            return;
95        }
96        self.0.push(core::iter::once(request_type).chain(request).collect());
97    }
98
99    /// Consumes [`Requests`] and returns the inner raw opaque requests.
100    ///
101    /// # Note
102    ///
103    /// These requests include the `request_type` as the first byte in each
104    /// `Bytes` element, followed by the `requests_data`.
105    pub fn take(self) -> Vec<Bytes> {
106        self.0
107    }
108
109    /// Get an iterator over the requests.
110    pub fn iter(&self) -> core::slice::Iter<'_, Bytes> {
111        self.0.iter()
112    }
113
114    /// Calculate the requests hash as defined in EIP-7685 for the requests.
115    ///
116    /// The requests hash is defined as
117    ///
118    /// ```text
119    /// sha256(sha256(requests_0) ++ sha256(requests_1) ++ ...)
120    /// ```
121    ///
122    /// Each request in the container is expected to already have the `request_type` prepended
123    /// to its corresponding `requests_data`. This function directly calculates the hash based
124    /// on the combined `request_type` and `requests_data`.
125    ///
126    /// Empty requests are omitted from the hash calculation.
127    /// Requests are sorted by their `request_type` before hashing, see also [Ordering](https://eips.ethereum.org/EIPS/eip-7685#ordering)
128    #[cfg(feature = "sha2")]
129    pub fn requests_hash(&self) -> B256 {
130        use sha2::{Digest, Sha256};
131        let mut hash = Sha256::new();
132
133        let mut requests: Vec<_> = self
134            .0
135            .iter()
136            .filter(|req| {
137                // filter out all requests that are empty or only have the type byte
138                // <type-id> <data>
139                req.len() > 1
140            })
141            .collect();
142
143        // requests should only contain unique types: `id [r1,r2,..]`
144        requests.sort_unstable_by_key(|req| {
145            // SAFETY: only includes non-empty requests
146            req[0]
147        });
148
149        for req in requests {
150            let mut req_hash = Sha256::new();
151            req_hash.update(req);
152            hash.update(req_hash.finalize());
153        }
154        B256::new(hash.finalize().into())
155    }
156
157    /// Extend this container with requests from another container.
158    pub fn extend(&mut self, other: Self) {
159        self.0.extend(other.take());
160    }
161}
162
163/// A list of requests or a precomputed requests hash.
164///
165/// For testing purposes, the `Hash` variant stores a precomputed requests hash. This can be useful
166/// when the exact contents of the requests are unnecessary, and only a consistent hash value is
167/// needed to simulate the presence of requests without holding actual data.
168#[derive(Debug, Clone, PartialEq, Eq, Hash, derive_more::From)]
169#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
170#[cfg_attr(feature = "serde", serde(untagged))]
171#[cfg_attr(any(test, feature = "arbitrary"), derive(arbitrary::Arbitrary))]
172pub enum RequestsOrHash {
173    /// Stores a list of requests, allowing for dynamic requests hash calculation.
174    Requests(Requests),
175    /// Stores a precomputed requests hash, used primarily for testing or mocking because the
176    /// header only contains the hash.
177    Hash(B256),
178}
179
180impl RequestsOrHash {
181    /// Returns the requests hash for the enum instance.
182    ///
183    /// - If the instance contains a list of requests, this function calculates the hash using
184    ///   `requests_hash` of the [`Requests`] struct.
185    /// - If it contains a precomputed hash, it returns that hash directly.
186    #[cfg(feature = "sha2")]
187    pub fn requests_hash(&self) -> B256 {
188        match self {
189            Self::Requests(requests) => requests.requests_hash(),
190            Self::Hash(precomputed_hash) => *precomputed_hash,
191        }
192    }
193
194    /// Returns an instance with the [`EMPTY_REQUESTS_HASH`].
195    pub const fn empty() -> Self {
196        Self::Hash(EMPTY_REQUESTS_HASH)
197    }
198
199    /// Returns the requests, if any.
200    pub const fn requests(&self) -> Option<&Requests> {
201        match self {
202            Self::Requests(requests) => Some(requests),
203            Self::Hash(_) => None,
204        }
205    }
206
207    /// Returns `true` if the variant is a list of requests.
208    pub const fn is_requests(&self) -> bool {
209        matches!(self, Self::Requests(_))
210    }
211
212    /// Returns `true` if the variant is a precomputed hash.
213    pub const fn is_hash(&self) -> bool {
214        matches!(self, Self::Hash(_))
215    }
216}
217
218impl Default for RequestsOrHash {
219    fn default() -> Self {
220        Self::Requests(Requests::default())
221    }
222}
223
224impl From<Vec<Bytes>> for RequestsOrHash {
225    fn from(requests: Vec<Bytes>) -> Self {
226        Self::Requests(requests.into())
227    }
228}
229
230#[cfg(test)]
231mod tests {
232    use super::*;
233
234    #[test]
235    fn test_extend() {
236        // Test extending a Requests container with another Requests container
237        let mut reqs1 = Requests::new(vec![Bytes::from(vec![0x01, 0x02])]);
238        let reqs2 =
239            Requests::new(vec![Bytes::from(vec![0x03, 0x04]), Bytes::from(vec![0x05, 0x06])]);
240
241        // Extend reqs1 with reqs2
242        reqs1.extend(reqs2);
243
244        // Ensure the requests are correctly combined
245        assert_eq!(reqs1.0.len(), 3);
246        assert_eq!(
247            reqs1.0,
248            vec![
249                Bytes::from(vec![0x01, 0x02]),
250                Bytes::from(vec![0x03, 0x04]),
251                Bytes::from(vec![0x05, 0x06])
252            ]
253        );
254    }
255
256    #[test]
257    #[cfg(feature = "sha2")]
258    fn test_consistent_requests_hash() {
259        // We test that the empty requests hash is consistent with the EIP-7685 definition.
260        assert_eq!(Requests::default().requests_hash(), EMPTY_REQUESTS_HASH);
261
262        // Test to hash a non-empty vector of requests.
263        assert_eq!(
264            Requests(vec![
265                Bytes::from(vec![0x00, 0x0a, 0x0b, 0x0c]),
266                Bytes::from(vec![0x01, 0x0d, 0x0e, 0x0f])
267            ])
268            .requests_hash(),
269            b256!("be3a57667b9bb9e0275019c0faf0f415fdc8385a408fd03e13a5c50615e3530c"),
270        );
271    }
272}
alloy_eips/eip7685.rs

alloy_eips/
eip7685.rs
