reth_era/ere/types/
execution.rs

1//! Execution layer specific types for `.ere` files
2//!
3//! Contains implementations for compressed execution layer data structures:
4//! - [`CompressedHeader`] - Block header
5//! - [`CompressedBody`] - Block body
6//! - [`CompressedSlimReceipts`] - Block receipts
7//! - [`TotalDifficulty`] - Block total difficulty
8//!
9//! These types use Snappy compression to match the specification.
10//!
11//! See also <https://github.com/eth-clients/e2store-format-specs/blob/main/formats/ere.md>
12
13use crate::{
14    common::{
15        compression::{snappy_compress, snappy_decompress, SnappyRlpCodec},
16        decode::DecodeCompressedRlp,
17    },
18    e2s::{error::E2sError, types::Entry},
19};
20use alloy_consensus::{Block, BlockBody, Eip658Value, Header, Receipt, ReceiptEnvelope, TxType};
21use alloy_primitives::{Log, B256, U256};
22use alloy_rlp::{Decodable, Encodable, RlpDecodable, RlpEncodable};
23use sha2::{Digest, Sha256};
24
25// ERE-specific constants
26/// `CompressedHeader` record type
27pub const COMPRESSED_HEADER: [u8; 2] = [0x03, 0x00];
28
29/// `CompressedBody` record type
30pub const COMPRESSED_BODY: [u8; 2] = [0x04, 0x00];
31
32/// `CompressedSlimReceipts` record type (0x0a00)
33/// Slim receipts exclude bloom filters to optimize storage.
34pub const COMPRESSED_SLIM_RECEIPTS: [u8; 2] = [0x0a, 0x00];
35
36/// `Proof` record type (0x0b00)
37/// Format: `snappyFramed(rlp([proof-type, ssz(proof-object)]))`
38pub const PROOF: [u8; 2] = [0x0b, 0x00];
39
40/// `TotalDifficulty` record type
41pub const TOTAL_DIFFICULTY: [u8; 2] = [0x06, 0x00];
42
43/// `Accumulator` record type
44pub const ACCUMULATOR: [u8; 2] = [0x07, 0x00];
45
46/// Maximum number of blocks in an `ERE` file, limited by accumulator size.
47pub const MAX_BLOCKS_PER_ERE: usize = crate::common::MAX_ENTRIES_PER_ERA as usize;
48
49/// Compressed block header using `snappyFramed(rlp(header))`
50#[derive(Debug, Clone)]
51pub struct CompressedHeader {
52    /// The compressed data
53    pub data: Vec<u8>,
54}
55
56impl CompressedHeader {
57    /// Create a new [`CompressedHeader`] from compressed data
58    pub const fn new(data: Vec<u8>) -> Self {
59        Self { data }
60    }
61
62    /// Create from RLP-encoded header by compressing it with Snappy framed encoding
63    pub fn from_rlp(rlp_data: &[u8]) -> Result<Self, E2sError> {
64        Ok(Self { data: snappy_compress(rlp_data)? })
65    }
66
67    /// Decompress to get the original RLP-encoded header
68    pub fn decompress(&self) -> Result<Vec<u8>, E2sError> {
69        snappy_decompress(&self.data)
70    }
71
72    /// Convert to an [`Entry`]
73    pub fn to_entry(&self) -> Entry {
74        Entry::new(COMPRESSED_HEADER, self.data.clone())
75    }
76
77    /// Create from an [`Entry`]
78    pub fn from_entry(entry: &Entry) -> Result<Self, E2sError> {
79        entry.ensure_type(COMPRESSED_HEADER, "CompressedHeader")?;
80        Ok(Self { data: entry.data.clone() })
81    }
82
83    /// Decode this compressed header into an `alloy_consensus::Header`
84    pub fn decode_header(&self) -> Result<Header, E2sError> {
85        self.decode()
86    }
87
88    /// Create a [`CompressedHeader`] from a header
89    pub fn from_header<H: Encodable>(header: &H) -> Result<Self, E2sError> {
90        let encoder = SnappyRlpCodec::new();
91        let compressed = encoder.encode(header)?;
92        Ok(Self::new(compressed))
93    }
94}
95
96impl DecodeCompressedRlp for CompressedHeader {
97    fn decode<T: Decodable>(&self) -> Result<T, E2sError> {
98        let decoder = SnappyRlpCodec::<T>::new();
99        decoder.decode(&self.data)
100    }
101}
102
103/// Compressed block body using `snappyFramed(rlp(body))`
104#[derive(Debug, Clone)]
105pub struct CompressedBody {
106    /// The compressed data
107    pub data: Vec<u8>,
108}
109
110impl CompressedBody {
111    /// Create a new [`CompressedBody`] from compressed data
112    pub const fn new(data: Vec<u8>) -> Self {
113        Self { data }
114    }
115
116    /// Create from RLP-encoded body by compressing it with Snappy framed encoding
117    pub fn from_rlp(rlp_data: &[u8]) -> Result<Self, E2sError> {
118        Ok(Self { data: snappy_compress(rlp_data)? })
119    }
120
121    /// Decompress to get the original RLP-encoded body
122    pub fn decompress(&self) -> Result<Vec<u8>, E2sError> {
123        snappy_decompress(&self.data)
124    }
125
126    /// Convert to an [`Entry`]
127    pub fn to_entry(&self) -> Entry {
128        Entry::new(COMPRESSED_BODY, self.data.clone())
129    }
130
131    /// Create from an [`Entry`]
132    pub fn from_entry(entry: &Entry) -> Result<Self, E2sError> {
133        entry.ensure_type(COMPRESSED_BODY, "CompressedBody")?;
134        Ok(Self { data: entry.data.clone() })
135    }
136
137    /// Decode this [`CompressedBody`] into an `alloy_consensus::BlockBody`
138    pub fn decode_body<T: Decodable, H: Decodable>(&self) -> Result<BlockBody<T, H>, E2sError> {
139        let decompressed = self.decompress()?;
140        Self::decode_body_from_decompressed(&decompressed)
141    }
142
143    /// Decode decompressed body data into an `alloy_consensus::BlockBody`
144    pub fn decode_body_from_decompressed<T: Decodable, H: Decodable>(
145        data: &[u8],
146    ) -> Result<BlockBody<T, H>, E2sError> {
147        alloy_rlp::decode_exact::<BlockBody<T, H>>(data)
148            .map_err(|e| E2sError::Rlp(format!("Failed to decode RLP data: {e}")))
149    }
150
151    /// Create a [`CompressedBody`] from a block body (e.g.  `alloy_consensus::BlockBody`)
152    pub fn from_body<B: Encodable>(body: &B) -> Result<Self, E2sError> {
153        let encoder = SnappyRlpCodec::new();
154        let compressed = encoder.encode(body)?;
155        Ok(Self::new(compressed))
156    }
157}
158
159impl DecodeCompressedRlp for CompressedBody {
160    fn decode<T: Decodable>(&self) -> Result<T, E2sError> {
161        let decoder = SnappyRlpCodec::<T>::new();
162        decoder.decode(&self.data)
163    }
164}
165
166/// Compressed slim receipts using `snappyFramed(rlp(...))`.
167///
168/// Slim receipts exclude bloom filters to optimize storage.
169/// Format: `snappyFramed(rlp([tx-type, post-state-or-status, cumulative-gas, logs]))`
170#[derive(Debug, Clone)]
171pub struct CompressedSlimReceipts {
172    /// The compressed data
173    pub data: Vec<u8>,
174}
175
176impl CompressedSlimReceipts {
177    /// Create a new [`CompressedSlimReceipts`] from compressed data
178    pub const fn new(data: Vec<u8>) -> Self {
179        Self { data }
180    }
181
182    /// Create from RLP-encoded slim receipts by compressing with Snappy framed encoding
183    pub fn from_rlp(rlp_data: &[u8]) -> Result<Self, E2sError> {
184        Ok(Self { data: snappy_compress(rlp_data)? })
185    }
186
187    /// Decompress to get the original RLP-encoded slim receipts
188    pub fn decompress(&self) -> Result<Vec<u8>, E2sError> {
189        snappy_decompress(&self.data)
190    }
191
192    /// Convert to an [`Entry`]
193    pub fn to_entry(&self) -> Entry {
194        Entry::new(COMPRESSED_SLIM_RECEIPTS, self.data.clone())
195    }
196
197    /// Create from an [`Entry`]
198    pub fn from_entry(entry: &Entry) -> Result<Self, E2sError> {
199        entry.ensure_type(COMPRESSED_SLIM_RECEIPTS, "CompressedSlimReceipts")?;
200        Ok(Self { data: entry.data.clone() })
201    }
202
203    /// Decode this [`CompressedSlimReceipts`] into the given type
204    pub fn decode<T: Decodable>(&self) -> Result<T, E2sError> {
205        let decoder = SnappyRlpCodec::<T>::new();
206        decoder.decode(&self.data)
207    }
208
209    /// Create [`CompressedSlimReceipts`] from an encodable type
210    pub fn from_encodable<T: Encodable>(data: &T) -> Result<Self, E2sError> {
211        let encoder = SnappyRlpCodec::<T>::new();
212        let compressed = encoder.encode(data)?;
213        Ok(Self::new(compressed))
214    }
215
216    /// Encode and compress a list of slim receipts
217    pub fn from_encodable_list<T: Encodable>(receipts: &[T]) -> Result<Self, E2sError> {
218        let mut rlp_data = Vec::new();
219        alloy_rlp::encode_list(receipts, &mut rlp_data);
220        Self::from_rlp(&rlp_data)
221    }
222
223    /// Compress a block's slim receipts.
224    ///
225    /// [`SlimReceipt`] is the canonical slim receipt: its RLP encoding is the 4-element list
226    /// `[tx-type, post-state-or-status, cumulative-gas, logs]`, with no bloom filter.
227    pub fn from_receipts(receipts: &[SlimReceipt]) -> Result<Self, E2sError> {
228        Self::from_encodable_list(receipts)
229    }
230
231    /// Decompress and decode this entry into a block's slim receipts.
232    pub fn decode_receipts(&self) -> Result<Vec<SlimReceipt>, E2sError> {
233        self.decode()
234    }
235}
236
237impl DecodeCompressedRlp for CompressedSlimReceipts {
238    fn decode<T: Decodable>(&self) -> Result<T, E2sError> {
239        let decoder = SnappyRlpCodec::<T>::new();
240        decoder.decode(&self.data)
241    }
242}
243
244/// A slim execution receipt as stored in an `ERE` file.
245///
246/// Per the spec, the slim form is the 4-element RLP list
247/// `[tx-type, post-state-or-status, cumulative-gas, logs]` with **no bloom filter** (the bloom is
248/// recomputable from the logs). This is a thin wrapper over alloy's field types: [`Eip658Value`]
249/// captures both the pre-Byzantium 32-byte post-state root and the post-Byzantium boolean status,
250/// so a single type decodes receipts across every fork.
251#[derive(Debug, Clone, PartialEq, Eq, RlpEncodable, RlpDecodable)]
252pub struct SlimReceipt {
253    /// Transaction type (EIP-2718).
254    pub tx_type: TxType,
255    /// Post-state root (pre-Byzantium) or success status (post-Byzantium).
256    pub status: Eip658Value,
257    /// Cumulative gas used in the block up to and including this transaction.
258    pub cumulative_gas_used: u64,
259    /// Logs emitted by the transaction.
260    pub logs: Vec<Log>,
261}
262
263impl From<SlimReceipt> for ReceiptEnvelope {
264    /// Restores the bloom that the slim form omits, recomputing it from the logs.
265    fn from(receipt: SlimReceipt) -> Self {
266        let SlimReceipt { tx_type, status, cumulative_gas_used, logs } = receipt;
267        let receipt = Receipt { status, cumulative_gas_used, logs };
268
269        Self::from_typed(tx_type, receipt.with_bloom())
270    }
271}
272
273/// Proof type discriminant used inside the Proof entry's RLP envelope.
274///
275/// Maps to specific Portal Network proof objects.
276#[derive(Debug, Clone, Copy, PartialEq, Eq)]
277#[repr(u8)]
278pub enum ProofType {
279    /// Pre-merge proof against the historical hashes accumulator
280    BlockProofHistoricalHashesAccumulator = 0,
281    /// Post-merge proof against historical roots
282    BlockProofHistoricalRoots = 1,
283    /// Capella-era proof against historical summaries
284    BlockProofHistoricalSummariesCapella = 2,
285    /// Deneb-era proof against historical summaries
286    BlockProofHistoricalSummariesDeneb = 3,
287}
288
289impl ProofType {
290    /// Convert from a raw byte value
291    pub const fn from_byte(value: u8) -> Option<Self> {
292        match value {
293            0 => Some(Self::BlockProofHistoricalHashesAccumulator),
294            1 => Some(Self::BlockProofHistoricalRoots),
295            2 => Some(Self::BlockProofHistoricalSummariesCapella),
296            3 => Some(Self::BlockProofHistoricalSummariesDeneb),
297            _ => None,
298        }
299    }
300
301    /// Convert to a raw byte value
302    pub const fn as_byte(self) -> u8 {
303        self as u8
304    }
305}
306
307/// A proof entry attesting to block validity against a trusted consensus layer header.
308///
309/// Format: `snappyFramed(rlp([proof-type, ssz(proof-object)]))`
310///
311/// Multiple proof types can coexist in the same file at fork boundaries.
312#[derive(Debug, Clone)]
313pub struct Proof {
314    /// The compressed data containing `rlp([proof-type, ssz(proof-object)])`
315    pub data: Vec<u8>,
316}
317
318impl Proof {
319    /// Create a new [`Proof`] from already-compressed data
320    pub const fn new(data: Vec<u8>) -> Self {
321        Self { data }
322    }
323
324    /// Encode a [`Proof`] from a proof type and raw SSZ-encoded proof object.
325    pub fn encode(proof_type: ProofType, ssz_proof: &[u8]) -> Result<Self, E2sError> {
326        // Build the list payload first so the RLP list header gets the exact length,
327        // regardless of how each item encodes.
328        let mut payload = Vec::new();
329        proof_type.as_byte().encode(&mut payload);
330        ssz_proof.encode(&mut payload);
331
332        let mut rlp_data = Vec::new();
333        alloy_rlp::Header { list: true, payload_length: payload.len() }.encode(&mut rlp_data);
334        rlp_data.extend_from_slice(&payload);
335
336        Ok(Self { data: snappy_compress(&rlp_data)? })
337    }
338
339    /// Decode the proof, returning `(proof_type, raw_ssz_proof_bytes)`.
340    pub fn decode(&self) -> Result<(ProofType, Vec<u8>), E2sError> {
341        let decompressed = snappy_decompress(&self.data)?;
342
343        let mut buf = decompressed.as_slice();
344        let header = alloy_rlp::Header::decode(&mut buf)
345            .map_err(|e| E2sError::Rlp(format!("Failed to decode proof RLP header: {e}")))?;
346        if !header.list {
347            return Err(E2sError::Rlp("Expected RLP list for Proof entry".to_string()));
348        }
349
350        // A proof is exactly the two-item list `[proof-type, ssz(proof-object)]`. Pin decoding to
351        // the list's own payload so nothing outside it slips through: bytes after the list end, or
352        // a third item inside it, both fail instead of being silently dropped.
353        if buf.len() != header.payload_length {
354            return Err(E2sError::Rlp(format!(
355                "Trailing bytes after Proof list: {} byte(s) beyond the list payload",
356                buf.len().saturating_sub(header.payload_length)
357            )));
358        }
359        let mut payload = &buf[..header.payload_length];
360
361        let proof_type_byte = u8::decode(&mut payload)
362            .map_err(|e| E2sError::Rlp(format!("Failed to decode proof type: {e}")))?;
363        let proof_type = ProofType::from_byte(proof_type_byte)
364            .ok_or_else(|| E2sError::Rlp(format!("Unknown proof type: {proof_type_byte}")))?;
365
366        let ssz_bytes = alloy_primitives::Bytes::decode(&mut payload)
367            .map_err(|e| E2sError::Rlp(format!("Failed to decode proof SSZ bytes: {e}")))?;
368
369        if !payload.is_empty() {
370            return Err(E2sError::Rlp("Unexpected extra items in Proof list".to_string()));
371        }
372
373        Ok((proof_type, ssz_bytes.to_vec()))
374    }
375
376    /// Convert to an [`Entry`]
377    pub fn to_entry(&self) -> Entry {
378        Entry::new(PROOF, self.data.clone())
379    }
380
381    /// Create from an [`Entry`]
382    pub fn from_entry(entry: &Entry) -> Result<Self, E2sError> {
383        entry.ensure_type(PROOF, "Proof")?;
384        Ok(Self { data: entry.data.clone() })
385    }
386}
387
388/// Total difficulty for a block
389#[derive(Debug, Clone)]
390pub struct TotalDifficulty {
391    /// The total difficulty as U256
392    pub value: U256,
393}
394
395impl TotalDifficulty {
396    /// Create a new [`TotalDifficulty`] from a U256 value
397    pub const fn new(value: U256) -> Self {
398        Self { value }
399    }
400
401    /// Convert to an [`Entry`]
402    pub fn to_entry(&self) -> Entry {
403        // ere spec: `total-difficulty = { type: 0x0600, data: SSZ uint256 }` (little-endian)
404        let data = self.value.to_le_bytes::<32>().to_vec();
405        Entry::new(TOTAL_DIFFICULTY, data)
406    }
407
408    /// Create from an [`Entry`]
409    pub fn from_entry(entry: &Entry) -> Result<Self, E2sError> {
410        entry.ensure_type(TOTAL_DIFFICULTY, "TotalDifficulty")?;
411
412        if entry.data.len() != 32 {
413            return Err(E2sError::Ssz(format!(
414                "Invalid data length for TotalDifficulty: expected 32, got {}",
415                entry.data.len()
416            )));
417        }
418
419        // ere spec: `total-difficulty = { type: 0x0600, data: SSZ uint256 }` (little-endian)
420        let value = U256::from_le_slice(&entry.data);
421
422        Ok(Self { value })
423    }
424}
425
426/// Accumulator is computed by constructing an SSZ list of header-records
427/// and calculating the `hash_tree_root`
428#[derive(Debug, Clone, PartialEq, Eq)]
429pub struct Accumulator {
430    /// The accumulator root hash
431    pub root: B256,
432}
433
434impl Accumulator {
435    /// Create a new [`Accumulator`] from a root hash
436    pub const fn new(root: B256) -> Self {
437        Self { root }
438    }
439
440    /// Convert to an [`Entry`]
441    pub fn to_entry(&self) -> Entry {
442        Entry::new(ACCUMULATOR, self.root.to_vec())
443    }
444
445    /// Create from an [`Entry`]
446    pub fn from_entry(entry: &Entry) -> Result<Self, E2sError> {
447        entry.ensure_type(ACCUMULATOR, "Accumulator")?;
448
449        if entry.data.len() != 32 {
450            return Err(E2sError::Ssz(format!(
451                "Invalid data length for Accumulator: expected 32, got {}",
452                entry.data.len()
453            )));
454        }
455
456        let mut root = [0u8; 32];
457        root.copy_from_slice(&entry.data);
458
459        Ok(Self { root: B256::from(root) })
460    }
461
462    /// Compute the accumulator from a list of header records.
463    ///
464    /// Implements `hash_tree_root(List[HeaderRecord, 8192])` per the spec:
465    /// - Each leaf is `sha256(block_hash || total_difficulty_le_bytes32)`
466    /// - Leaves are padded to `MAX_BLOCKS_PER_ERE` (8192) with zero hashes
467    /// - Binary Merkle tree is computed bottom-up
468    /// - Final root is `sha256(merkle_root || le_bytes32(actual_count))`
469    ///
470    /// Returns `Err` if `records` exceeds [`MAX_BLOCKS_PER_ERE`].
471    pub fn from_header_records(records: &[HeaderRecord]) -> Result<Self, E2sError> {
472        let capacity = MAX_BLOCKS_PER_ERE;
473
474        if records.len() > capacity {
475            return Err(E2sError::Ssz(format!(
476                "Too many header records: got {}, max {}",
477                records.len(),
478                capacity
479            )));
480        }
481
482        // Compute leaf hash for each header record
483        let mut leaves = Vec::with_capacity(capacity);
484        for record in records {
485            let mut data = [0u8; 64];
486            data[..32].copy_from_slice(record.block_hash.as_slice());
487            data[32..].copy_from_slice(&record.total_difficulty.to_le_bytes::<32>());
488            leaves.push(<[u8; 32]>::from(Sha256::digest(data)));
489        }
490
491        // Pad to capacity with zero hashes
492        leaves.resize(capacity, [0u8; 32]);
493
494        // Binary Merkle tree bottom-up (capacity is always a power of two)
495        while leaves.len() > 1 {
496            let mut next_level = Vec::with_capacity(leaves.len() / 2);
497            for pair in leaves.as_chunks::<2>().0 {
498                let mut data = [0u8; 64];
499                data[..32].copy_from_slice(&pair[0]);
500                data[32..].copy_from_slice(&pair[1]);
501                next_level.push(<[u8; 32]>::from(Sha256::digest(data)));
502            }
503            leaves = next_level;
504        }
505
506        let merkle_root = leaves[0];
507
508        // mix_in_length: sha256(merkle_root || le_bytes32(actual_length))
509        let mut mix = [0u8; 64];
510        mix[..32].copy_from_slice(&merkle_root);
511        let length = records.len() as u64;
512        mix[32..40].copy_from_slice(&length.to_le_bytes());
513        // remaining bytes stay zero (uint256 LE padding)
514
515        Ok(Self { root: B256::from(<[u8; 32]>::from(Sha256::digest(mix))) })
516    }
517}
518
519/// The minimal per-block commitment used to build the accumulator.
520///
521/// This is **not** a block header: it is the 64-byte leaf
522/// `{ block-hash: Bytes32, total-difficulty: Uint256 }` that
523/// [`Accumulator::from_header_records`] merkleizes as `hash_tree_root(List[HeaderRecord, 8192])`.
524/// The full header is stored separately as [`CompressedHeader`].
525///
526/// Only meaningful pre-merge, since `total-difficulty` stops advancing after the merge.
527#[derive(Debug, Clone)]
528pub struct HeaderRecord {
529    /// The canonical block hash, i.e. `keccak256(rlp(header))` — the hash *of* the full block
530    /// header, which serves as this leaf's identity in the accumulator.
531    pub block_hash: B256,
532    /// The **cumulative** total difficulty through this block (the running sum of every block's
533    /// difficulty up to and including it), not the header's own per-block `difficulty` field.
534    pub total_difficulty: U256,
535}
536
537/// A single block's components in an `ERE` file.
538///
539/// Only the header and body are mandatory; receipts, total difficulty, and the proof are optional,
540/// so subset profiles or post-merge blocks can omit them.
541/// [`component_count`](Self::component_count) reports how many are present, matching the file's
542/// `DynamicBlockIndex` `component-count`.
543///
544/// See also <https://github.com/eth-clients/e2store-format-specs/blob/main/formats/ere.md#specification>
545#[derive(Debug, Clone)]
546pub struct BlockTuple {
547    /// Compressed block header
548    pub header: CompressedHeader,
549
550    /// Compressed block body
551    pub body: CompressedBody,
552
553    /// Compressed slim receipts, omitted by the `noreceipts` profile
554    pub receipts: Option<CompressedSlimReceipts>,
555
556    /// Total difficulty, absent once it stops advancing after the merge
557    pub total_difficulty: Option<TotalDifficulty>,
558
559    /// Proof of block validity, omitted by the `noproofs` profile
560    pub proof: Option<Proof>,
561}
562
563impl BlockTuple {
564    /// Create a new [`BlockTuple`] with only the mandatory header and body.
565    ///
566    /// Attach the optional components with [`with_receipts`](Self::with_receipts),
567    /// [`with_total_difficulty`](Self::with_total_difficulty), and
568    /// [`with_proof`](Self::with_proof).
569    pub const fn new(header: CompressedHeader, body: CompressedBody) -> Self {
570        Self { header, body, receipts: None, total_difficulty: None, proof: None }
571    }
572
573    /// Attach compressed slim receipts.
574    pub fn with_receipts(mut self, receipts: CompressedSlimReceipts) -> Self {
575        self.receipts = Some(receipts);
576        self
577    }
578
579    /// Attach the total difficulty.
580    pub const fn with_total_difficulty(mut self, total_difficulty: TotalDifficulty) -> Self {
581        self.total_difficulty = Some(total_difficulty);
582        self
583    }
584
585    /// Attach a validity proof.
586    pub fn with_proof(mut self, proof: Proof) -> Self {
587        self.proof = Some(proof);
588        self
589    }
590
591    /// Number of index components this block contributes: the mandatory header and body plus each
592    /// optional component present. Always in the range 2-5, matching the file's `component-count`.
593    pub const fn component_count(&self) -> u64 {
594        2 + self.receipts.is_some() as u64 +
595            self.total_difficulty.is_some() as u64 +
596            self.proof.is_some() as u64
597    }
598
599    /// Convert to an `alloy_consensus::Block`
600    pub fn to_alloy_block<T: Decodable>(&self) -> Result<Block<T>, E2sError> {
601        let header: Header = self.header.decode()?;
602        let body: BlockBody<T> = self.body.decode()?;
603
604        Ok(Block::new(header, body))
605    }
606
607    /// Create from an `alloy_consensus::Block`, attaching the given receipts and total difficulty.
608    pub fn from_alloy_block<T: Encodable, R: Encodable>(
609        block: &Block<T>,
610        receipts: &R,
611        total_difficulty: U256,
612    ) -> Result<Self, E2sError> {
613        let header = CompressedHeader::from_header(&block.header)?;
614        let body = CompressedBody::from_body(&block.body)?;
615
616        let compressed_receipts = CompressedSlimReceipts::from_encodable(receipts)?;
617
618        let difficulty = TotalDifficulty::new(total_difficulty);
619
620        Ok(Self::new(header, body)
621            .with_receipts(compressed_receipts)
622            .with_total_difficulty(difficulty))
623    }
624}
625
626#[cfg(test)]
627mod tests {
628    use super::*;
629    use crate::test_utils::{create_header, create_test_receipt, create_test_receipts};
630    use alloy_eips::eip4895::Withdrawals;
631    use alloy_primitives::{Bytes, U256};
632    use reth_ethereum_primitives::{Receipt, TxType};
633
634    #[test]
635    fn test_header_conversion_roundtrip() {
636        let header = create_header();
637
638        let compressed_header = CompressedHeader::from_header(&header).unwrap();
639
640        let decoded_header = compressed_header.decode_header().unwrap();
641
642        assert_eq!(header.number, decoded_header.number);
643        assert_eq!(header.difficulty, decoded_header.difficulty);
644        assert_eq!(header.timestamp, decoded_header.timestamp);
645        assert_eq!(header.gas_used, decoded_header.gas_used);
646        assert_eq!(header.parent_hash, decoded_header.parent_hash);
647        assert_eq!(header.base_fee_per_gas, decoded_header.base_fee_per_gas);
648    }
649
650    #[test]
651    fn test_block_body_conversion() {
652        let block_body: BlockBody<Bytes> =
653            BlockBody { transactions: vec![], ommers: vec![], withdrawals: None };
654
655        let compressed_body = CompressedBody::from_body(&block_body).unwrap();
656
657        let decoded_body: BlockBody<Bytes> = compressed_body.decode_body().unwrap();
658
659        assert_eq!(decoded_body.transactions.len(), 0);
660        assert_eq!(decoded_body.ommers.len(), 0);
661        assert_eq!(decoded_body.withdrawals, None);
662    }
663
664    #[test]
665    fn test_total_difficulty_roundtrip() {
666        let value = U256::from(123456789u64);
667
668        let total_difficulty = TotalDifficulty::new(value);
669
670        let entry = total_difficulty.to_entry();
671
672        assert_eq!(entry.entry_type, TOTAL_DIFFICULTY);
673
674        let recovered = TotalDifficulty::from_entry(&entry).unwrap();
675
676        assert_eq!(recovered.value, value);
677    }
678
679    #[test]
680    fn test_total_difficulty_ssz_le_encoding() {
681        // Verify that total-difficulty is encoded as SSZ uint256 (little-endian).
682        // See https://github.com/eth-clients/e2store-format-specs/blob/main/formats/ere.md
683        let value = U256::from(1u64);
684        let td = TotalDifficulty::new(value);
685        let entry = td.to_entry();
686
687        // Little-endian: least significant byte first [1, 0, 0, ..., 0]
688        assert_eq!(entry.data[0], 1, "First byte must be 1 (little-endian)");
689        assert_eq!(entry.data[31], 0, "Last byte must be 0 (little-endian)");
690    }
691
692    #[test]
693    fn test_compression_roundtrip() {
694        let rlp_data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
695
696        // Test header compression/decompression
697        let compressed_header = CompressedHeader::from_rlp(&rlp_data).unwrap();
698        let decompressed = compressed_header.decompress().unwrap();
699        assert_eq!(decompressed, rlp_data);
700
701        // Test body compression/decompression
702        let compressed_body = CompressedBody::from_rlp(&rlp_data).unwrap();
703        let decompressed = compressed_body.decompress().unwrap();
704        assert_eq!(decompressed, rlp_data);
705
706        // Test receipts compression/decompression
707        let compressed_receipts = CompressedSlimReceipts::from_rlp(&rlp_data).unwrap();
708        let decompressed = compressed_receipts.decompress().unwrap();
709        assert_eq!(decompressed, rlp_data);
710    }
711
712    #[test]
713    fn test_block_tuple_with_data() {
714        // Create block with transactions and withdrawals
715        let header = create_header();
716
717        let transactions = vec![Bytes::from(vec![1, 2, 3, 4]), Bytes::from(vec![5, 6, 7, 8])];
718
719        let withdrawals = Some(Withdrawals(vec![]));
720
721        let block_body = BlockBody { transactions, ommers: vec![], withdrawals };
722
723        let block = Block::new(header, block_body);
724
725        let receipts: Vec<u8> = Vec::new();
726
727        let block_tuple =
728            BlockTuple::from_alloy_block(&block, &receipts, U256::from(123456u64)).unwrap();
729
730        // Convert back to Block
731        let decoded_block: Block<Bytes> = block_tuple.to_alloy_block().unwrap();
732
733        // Verify block components
734        assert_eq!(decoded_block.header.number, 100);
735        assert_eq!(decoded_block.body.transactions.len(), 2);
736        assert_eq!(decoded_block.body.transactions[0], Bytes::from(vec![1, 2, 3, 4]));
737        assert_eq!(decoded_block.body.transactions[1], Bytes::from(vec![5, 6, 7, 8]));
738        assert!(decoded_block.body.withdrawals.is_some());
739    }
740
741    #[test]
742    fn test_block_tuple_component_count() {
743        let base = BlockTuple::new(CompressedHeader::new(vec![1]), CompressedBody::new(vec![2]));
744        // Mandatory header + body only.
745        assert_eq!(base.component_count(), 2);
746
747        // Each optional component bumps the count, up to the 5-component maximum.
748        assert_eq!(
749            base.clone().with_receipts(CompressedSlimReceipts::new(vec![3])).component_count(),
750            3
751        );
752        let full = base
753            .with_receipts(CompressedSlimReceipts::new(vec![3]))
754            .with_total_difficulty(TotalDifficulty::new(U256::from(1u64)))
755            .with_proof(Proof::new(vec![4]));
756        assert_eq!(full.component_count(), 5);
757        assert!(full.receipts.is_some() && full.total_difficulty.is_some() && full.proof.is_some());
758    }
759
760    #[test]
761    fn test_single_receipt_compression_roundtrip() {
762        let test_receipt = create_test_receipt(TxType::Eip1559, true, 21000, 2);
763
764        // Compress the receipt
765        let compressed_receipts = CompressedSlimReceipts::from_encodable(&test_receipt)
766            .expect("Failed to compress receipt");
767
768        // Verify compression
769        assert!(!compressed_receipts.data.is_empty());
770
771        // Decode the compressed receipt back
772        let decoded_receipt: Receipt =
773            compressed_receipts.decode().expect("Failed to decode compressed receipt");
774
775        // Verify that the decoded receipt matches the original
776        assert_eq!(decoded_receipt.tx_type, test_receipt.tx_type);
777        assert_eq!(decoded_receipt.success, test_receipt.success);
778        assert_eq!(decoded_receipt.cumulative_gas_used, test_receipt.cumulative_gas_used);
779        assert_eq!(decoded_receipt.logs.len(), test_receipt.logs.len());
780
781        // Verify each log
782        for (original_log, decoded_log) in test_receipt.logs.iter().zip(decoded_receipt.logs.iter())
783        {
784            assert_eq!(decoded_log.address, original_log.address);
785            assert_eq!(decoded_log.data.topics(), original_log.data.topics());
786        }
787    }
788
789    #[test]
790    fn test_slim_receipt_matches_spec_rlp() {
791        // Spec: CompressedSlimReceipts.data = snappyFramed(rlp([tx-type, status, cumulative-gas,
792        // logs])), with no bloom filter. Prove the inner RLP of `EthereumReceipt` is exactly that
793        // 4-element list, byte for byte.
794        let receipt = create_test_receipt(TxType::Eip1559, true, 21000, 2);
795
796        let compressed = CompressedSlimReceipts::from_encodable(&receipt).unwrap();
797        let actual_rlp = compressed.decompress().unwrap();
798
799        // Hand-build rlp([tx-type, status, cumulative-gas, logs]) in spec field order.
800        let mut fields = Vec::new();
801        (receipt.tx_type as u8).encode(&mut fields);
802        receipt.success.encode(&mut fields);
803        receipt.cumulative_gas_used.encode(&mut fields);
804        receipt.logs.encode(&mut fields);
805        let mut expected = Vec::new();
806        alloy_rlp::Header { list: true, payload_length: fields.len() }.encode(&mut expected);
807        expected.extend_from_slice(&fields);
808
809        assert_eq!(
810            actual_rlp, expected,
811            "slim receipt RLP must be the 4-element list [tx-type, status, cumulative-gas, logs]"
812        );
813    }
814
815    #[test]
816    fn test_slim_receipts_typed_helpers() {
817        // Cover both status variants: post-Byzantium boolean status and a pre-Byzantium 32-byte
818        // post-state root, proving a single `SlimReceipt` type round-trips across forks.
819        let receipts = vec![
820            SlimReceipt {
821                tx_type: TxType::Eip1559,
822                status: Eip658Value::Eip658(true),
823                cumulative_gas_used: 21000,
824                logs: vec![],
825            },
826            SlimReceipt {
827                tx_type: TxType::Legacy,
828                status: Eip658Value::PostState(B256::repeat_byte(0xab)),
829                cumulative_gas_used: 42000,
830                logs: vec![],
831            },
832        ];
833
834        let compressed = CompressedSlimReceipts::from_receipts(&receipts).unwrap();
835        let decoded = compressed.decode_receipts().unwrap();
836
837        assert_eq!(decoded, receipts);
838    }
839
840    #[test]
841    fn test_accumulator_from_header_records_known_vectors() {
842        // Known-answer vectors computed from the SSZ spec:
843        //   hash_tree_root(List[HeaderRecord, 8192])
844        let expected_empty: B256 =
845            "4a8c3a07c8d23adc5bac61157555c3c784d53d9bc110c1370809bd23cd93777d".parse().unwrap();
846        let expected_single_zero: B256 =
847            "81fd641249670887a731386e756a7a1538dc781b1b0bf016889045d350812817".parse().unwrap();
848        let expected_single_nonzero: B256 =
849            "ada35c48d81117f4fd588554cd4c4752356336e84cb41106dea1ceb4cfac8799".parse().unwrap();
850
851        // Empty list
852        let acc_empty = Accumulator::from_header_records(&[]).unwrap();
853        assert_eq!(acc_empty.root, expected_empty);
854
855        // Single record with zero values
856        let records = vec![HeaderRecord { block_hash: B256::ZERO, total_difficulty: U256::ZERO }];
857        let acc = Accumulator::from_header_records(&records).unwrap();
858        assert_eq!(acc.root, expected_single_zero);
859
860        // Single record with non-zero values
861        let records2 = vec![HeaderRecord {
862            block_hash: B256::from([1u8; 32]),
863            total_difficulty: U256::from(100u64),
864        }];
865        let acc2 = Accumulator::from_header_records(&records2).unwrap();
866        assert_eq!(acc2.root, expected_single_nonzero);
867    }
868
869    #[test]
870    fn test_accumulator_rejects_oversized_input() {
871        let records = vec![
872            HeaderRecord { block_hash: B256::ZERO, total_difficulty: U256::ZERO };
873            MAX_BLOCKS_PER_ERE + 1
874        ];
875        assert!(Accumulator::from_header_records(&records).is_err());
876    }
877
878    #[test]
879    fn test_proof_type_byte_roundtrip() {
880        for ty in [
881            ProofType::BlockProofHistoricalHashesAccumulator,
882            ProofType::BlockProofHistoricalRoots,
883            ProofType::BlockProofHistoricalSummariesCapella,
884            ProofType::BlockProofHistoricalSummariesDeneb,
885        ] {
886            assert_eq!(ProofType::from_byte(ty.as_byte()), Some(ty));
887        }
888        assert_eq!(ProofType::from_byte(4), None);
889    }
890
891    #[test]
892    fn test_proof_roundtrip() {
893        let ssz_proof = vec![0xab; 64];
894        let proof = Proof::encode(ProofType::BlockProofHistoricalRoots, &ssz_proof).unwrap();
895
896        // Roundtrip through an Entry
897        let entry = proof.to_entry();
898        assert_eq!(entry.entry_type, PROOF);
899        let recovered = Proof::from_entry(&entry).unwrap();
900
901        let (proof_type, ssz_bytes) = recovered.decode().unwrap();
902        assert_eq!(proof_type, ProofType::BlockProofHistoricalRoots);
903        assert_eq!(ssz_bytes, ssz_proof);
904    }
905
906    #[test]
907    fn test_from_entry_rejects_wrong_type() {
908        let entry = Entry::new(COMPRESSED_BODY, vec![1, 2, 3]);
909        assert!(CompressedHeader::from_entry(&entry).is_err());
910    }
911
912    #[test]
913    fn test_decode_rejects_trailing_bytes() {
914        // A record is exactly `snappyFramed(rlp(...))`; an extra byte after the RLP value
915        // must be rejected, not silently ignored.
916        let mut rlp = Vec::new();
917        7u64.encode(&mut rlp);
918        rlp.push(0xff);
919        let compressed = CompressedHeader::from_rlp(&rlp).unwrap();
920        assert!(compressed.decode::<u64>().is_err());
921    }
922
923    #[test]
924    fn test_proof_decode_rejects_trailing_bytes() {
925        let valid = Proof::encode(ProofType::BlockProofHistoricalRoots, &[1, 2, 3]).unwrap();
926        let mut raw = snappy_decompress(&valid.data).unwrap();
927        raw.push(0xff); // byte beyond the RLP list
928        let tampered = Proof::new(snappy_compress(&raw).unwrap());
929        assert!(tampered.decode().is_err());
930    }
931
932    #[test]
933    fn test_proof_decode_rejects_extra_list_item() {
934        // Build rlp([proof-type, ssz, extra]) — a third item must be rejected.
935        let mut payload = Vec::new();
936        0u8.encode(&mut payload);
937        alloy_primitives::Bytes::from(vec![1, 2, 3]).encode(&mut payload);
938        99u8.encode(&mut payload);
939        let mut rlp = Vec::new();
940        alloy_rlp::Header { list: true, payload_length: payload.len() }.encode(&mut rlp);
941        rlp.extend_from_slice(&payload);
942        let proof = Proof::new(snappy_compress(&rlp).unwrap());
943        assert!(proof.decode().is_err());
944    }
945
946    #[test]
947    fn test_receipt_list_compression() {
948        let receipts = create_test_receipts();
949
950        // Compress the list of receipts
951        let compressed_receipts = CompressedSlimReceipts::from_encodable_list(&receipts)
952            .expect("Failed to compress receipt list");
953
954        // Decode the compressed receipts back. ERE always stores slim receipts (no bloom), so the
955        // bare `Receipt` (`alloy_consensus::EthereumReceipt`) is the canonical decode target.
956        let decoded_receipts: Vec<Receipt> =
957            compressed_receipts.decode().expect("Failed to decode compressed receipt list");
958
959        // Verify that the decoded receipts match the original
960        assert_eq!(decoded_receipts.len(), receipts.len());
961
962        for (original, decoded) in receipts.iter().zip(decoded_receipts.iter()) {
963            assert_eq!(decoded.tx_type, original.tx_type);
964            assert_eq!(decoded.success, original.success);
965            assert_eq!(decoded.cumulative_gas_used, original.cumulative_gas_used);
966            assert_eq!(decoded.logs.len(), original.logs.len());
967
968            for (original_log, decoded_log) in original.logs.iter().zip(decoded.logs.iter()) {
969                assert_eq!(decoded_log.address, original_log.address);
970                assert_eq!(decoded_log.data.topics(), original_log.data.topics());
971            }
972        }
973    }
974}
reth_era/ere/types/execution.rs

reth_era/ere/types/
execution.rs
