Skip to main content

evm_fork_cache_hypersync/
normalize.rs

1use std::collections::HashMap;
2
3use alloy_consensus::Header as ConsensusHeader;
4use alloy_primitives::{Address as AlloyAddress, B64, B256, Bloom, Bytes, U256};
5use alloy_rlp::Encodable;
6use evm_fork_cache_event_protocol::v1::{
7    ApplyDesiredState, BlockHeaderEvent, BlockProgressEvent, BlockRef, ChainEvent, Cursor,
8    DataPayload, Delivery, DeliveryScope, EventRecord, LogEvent, PortableInterest, chain_event,
9    delivery, portable_interest,
10};
11use hypersync_client::{
12    format::{Hash, Quantity},
13    net_types::RollbackGuard,
14    simple_types::{Block, Log},
15};
16
17const SOURCE_CHECKPOINT_MAGIC: &[u8; 8] = b"EFCHSCP2";
18const ENCODED_BLOCK_REF_LEN: usize = 80;
19
20#[derive(Clone, Default)]
21pub(crate) struct DecodedSourceCheckpoint {
22    pub rollback_guard: Option<RollbackGuard>,
23    pub activation_block: Option<u64>,
24    pub canonical_blocks: Vec<BlockRef>,
25}
26
27/// Provider-neutral page returned by a chain data source.
28#[derive(Clone, Debug, Default)]
29#[non_exhaustive]
30pub struct SourcePage {
31    /// Height available in the source archive when the query ran.
32    pub archive_height: Option<u64>,
33    /// Exclusive block cursor for the next page.
34    pub next_block: u64,
35    /// Blocks returned for the covered range.
36    pub blocks: Vec<Block>,
37    /// Logs returned for the covered range.
38    pub logs: Vec<Log>,
39    /// HyperSync continuity metadata for this page.
40    pub rollback_guard: Option<RollbackGuard>,
41}
42
43impl SourcePage {
44    /// Create a page with no archive-height or provider-checkpoint metadata.
45    pub fn new(next_block: u64, blocks: Vec<Block>, logs: Vec<Log>) -> Self {
46        Self {
47            archive_height: None,
48            next_block,
49            blocks,
50            logs,
51            rollback_guard: None,
52        }
53    }
54
55    /// Attach the source's latest-height observation from the same response.
56    pub fn with_archive_height(mut self, archive_height: Option<u64>) -> Self {
57        self.archive_height = archive_height;
58        self
59    }
60
61    /// Attach provider-native continuity metadata from the same response.
62    pub fn with_rollback_guard(mut self, rollback_guard: Option<RollbackGuard>) -> Self {
63        self.rollback_guard = rollback_guard;
64        self
65    }
66}
67
68/// Normalize an already-admitted provider page into one ordered wire delivery.
69///
70/// # Integrity boundary
71///
72/// This low-level helper deliberately does **not** validate the requested range,
73/// canonical continuity, duplicate identities, or hard response limits. It is
74/// exposed for deterministic tooling and benchmarks whose fixtures are already
75/// trusted. Production adapters must route untrusted provider data through
76/// [`crate::SourceEngine`], which performs hard admission and structural
77/// validation before calling the same normalization implementation.
78///
79/// # Errors
80///
81/// Returns [`NormalizeError`] when required block/log fields are missing,
82/// malformed, overflow their protocol representation, cannot be encoded into a
83/// valid delivery/cursor, or when a complete reconstructed header does not
84/// reproduce the provider's block hash.
85pub fn normalize_page_unchecked(
86    desired_state: &ApplyDesiredState,
87    sequence: u64,
88    page: SourcePage,
89) -> Result<Delivery, NormalizeError> {
90    normalize_page_at(desired_state, sequence, page, 0)
91}
92
93pub(crate) fn normalize_page_at(
94    desired_state: &ApplyDesiredState,
95    sequence: u64,
96    mut page: SourcePage,
97    activation_block: u64,
98) -> Result<Delivery, NormalizeError> {
99    page.blocks.sort_by_key(|block| block.number);
100    page.logs.sort_by_key(|log| {
101        (
102            log.block_number.map(u64::from),
103            log.transaction_index.map(u64::from),
104            log.log_index.map(u64::from),
105        )
106    });
107
108    let mut events = Vec::with_capacity(page.blocks.len() + page.logs.len());
109    let mut block_timestamps = HashMap::with_capacity(page.blocks.len());
110    for block in &page.blocks {
111        let block_ref = block_ref(block)?;
112        let block_number = block_ref.number;
113        block_timestamps.insert(block_number, block_ref.timestamp);
114        if has_active_block_interest(desired_state, block_number, activation_block) {
115            events.push((
116                block_number,
117                0_u8,
118                0_u64,
119                0_u64,
120                ChainEvent {
121                    event: Some(chain_event::Event::BlockHeader(BlockHeaderEvent {
122                        block: Some(block_ref.clone()),
123                        consensus_header_rlp: encode_consensus_header(block)?,
124                        total_difficulty: block
125                            .total_difficulty
126                            .as_ref()
127                            .map_or_else(Vec::new, |value| value.as_ref().to_vec()),
128                        size: block
129                            .size
130                            .as_ref()
131                            .map_or_else(Vec::new, |value| value.as_ref().to_vec()),
132                    })),
133                },
134                delivery_scope(desired_state, block_number, activation_block),
135            ));
136        }
137        if block_number >= activation_block || global_backfill_active(desired_state, block_number) {
138            events.push((
139                block_number,
140                2_u8,
141                0_u64,
142                0_u64,
143                ChainEvent {
144                    event: Some(chain_event::Event::BlockProgress(BlockProgressEvent {
145                        block: Some(block_ref),
146                    })),
147                },
148                DeliveryScope::CanonicalProgress,
149            ));
150        }
151    }
152
153    for log in page.logs {
154        let block_number = required_u64(log.block_number, "log.block_number")?;
155        let transaction_index = required_u64(log.transaction_index, "log.transaction_index")?;
156        let log_index = required_u64(log.log_index, "log.log_index")?;
157        let address = required_fixed::<20, _>(log.address.as_ref(), "log.address")?.to_vec();
158        let block_hash =
159            required_fixed::<32, _>(log.block_hash.as_ref(), "log.block_hash")?.to_vec();
160        let transaction_hash =
161            required_fixed::<32, _>(log.transaction_hash.as_ref(), "log.transaction_hash")?
162                .to_vec();
163        let data = required_bytes(log.data.as_ref(), "log.data")?;
164        let removed = log
165            .removed
166            .ok_or(NormalizeError::MissingField("log.removed"))?;
167        let topics = normalize_topics(&log.topics)?;
168        let block_timestamp = block_timestamps
169            .get(&block_number)
170            .copied()
171            .ok_or(NormalizeError::LogWithoutBlock { block_number })?;
172        events.push((
173            block_number,
174            1_u8,
175            transaction_index,
176            log_index,
177            ChainEvent {
178                event: Some(chain_event::Event::Log(LogEvent {
179                    address,
180                    topics,
181                    data,
182                    block_number,
183                    block_hash,
184                    transaction_hash,
185                    transaction_index,
186                    log_index,
187                    block_timestamp,
188                    removed,
189                })),
190            },
191            delivery_scope(desired_state, block_number, activation_block),
192        ));
193    }
194    events.sort_by_key(|(block, kind, transaction, log, _, _)| (*block, *kind, *transaction, *log));
195
196    // `next_block` and the provider checkpoint describe this source's scan
197    // position. They may advance during an owner-specific historical catch-up.
198    // Global canonical coverage is narrower: only blocks at or beyond this
199    // revision's activation boundary are visible to the canonical audience.
200    let canonical_head = page
201        .blocks
202        .iter()
203        .rev()
204        .find(|block| {
205            block.number.is_some_and(|number| {
206                number >= activation_block || global_backfill_active(desired_state, number)
207            })
208        })
209        .map(block_ref)
210        .transpose()?;
211    let provider_checkpoint = page
212        .rollback_guard
213        .as_ref()
214        .map_or_else(Vec::new, encode_rollback_guard);
215    let mut records: Vec<EventRecord> = events
216        .into_iter()
217        .filter_map(|(_, _, _, _, event, scope)| {
218            let (canonical_audience, owner_ids) =
219                event_audience(desired_state, &event, activation_block);
220            (canonical_audience || !owner_ids.is_empty()).then_some(EventRecord {
221                event: Some(event),
222                canonical_audience,
223                owner_ids,
224                scope: scope.into(),
225            })
226        })
227        .collect();
228    if let Some(head) = canonical_head.as_ref()
229        && !records.is_empty()
230        && !records.iter().any(|record| {
231            record.canonical_audience
232                && record
233                    .event
234                    .as_ref()
235                    .and_then(|event| event.event.as_ref())
236                    .and_then(|event| match event {
237                        chain_event::Event::BlockHeader(header) => header.block.as_ref(),
238                        chain_event::Event::BlockProgress(progress) => progress.block.as_ref(),
239                        chain_event::Event::Log(_) => None,
240                    })
241                    .is_some_and(|block| block == head)
242        })
243    {
244        records.push(EventRecord {
245            event: Some(ChainEvent {
246                event: Some(chain_event::Event::BlockProgress(BlockProgressEvent {
247                    block: Some(head.clone()),
248                })),
249            }),
250            canonical_audience: true,
251            owner_ids: Vec::new(),
252            scope: DeliveryScope::CanonicalProgress.into(),
253        });
254    }
255
256    Ok(Delivery {
257        session_id: desired_state.session_id.clone(),
258        sequence,
259        query_revision: desired_state.new_revision,
260        delivery_token: sequence.to_be_bytes().to_vec(),
261        cursor: Some(Cursor {
262            chain_id: desired_state.chain_id,
263            query_revision: desired_state.new_revision,
264            next_block: page.next_block,
265            canonical_head,
266            batch_sequence: sequence,
267            provider_checkpoint,
268            owner_backfill_activation_block: Some(activation_block),
269        }),
270        payload: Some(delivery::Payload::Data(DataPayload { records })),
271        checkpoint_neutral: false,
272    })
273}
274
275fn delivery_scope(
276    desired_state: &ApplyDesiredState,
277    block_number: u64,
278    activation_block: u64,
279) -> DeliveryScope {
280    if block_number >= activation_block || global_backfill_active(desired_state, block_number) {
281        DeliveryScope::CanonicalProgress
282    } else {
283        DeliveryScope::OwnerCatchup
284    }
285}
286
287fn has_active_block_interest(
288    desired_state: &ApplyDesiredState,
289    block_number: u64,
290    activation_block: u64,
291) -> bool {
292    let global_backfill = global_backfill_active(desired_state, block_number);
293    desired_state.owners.iter().any(|owner| {
294        let active = global_backfill
295            || block_number >= activation_block
296            || owner.backfill.as_ref().is_some_and(|backfill| {
297                block_number >= backfill.from_block
298                    && backfill.to_block_excl.is_none_or(|end| block_number < end)
299            });
300        active
301            && owner.interests.iter().any(|interest| {
302                matches!(
303                    interest.kind.as_ref(),
304                    Some(portable_interest::Kind::Block(_))
305                )
306            })
307    })
308}
309
310fn event_audience(
311    desired_state: &ApplyDesiredState,
312    event: &ChainEvent,
313    activation_block: u64,
314) -> (bool, Vec<String>) {
315    let mut canonical = false;
316    let mut owners = Vec::new();
317    let block_number = event_block_number(event);
318    let canonical_phase = block_number >= activation_block;
319    let global_backfill = global_backfill_active(desired_state, block_number);
320    if matches!(
321        event.event.as_ref(),
322        Some(chain_event::Event::BlockProgress(_))
323    ) && (canonical_phase || global_backfill)
324    {
325        return (true, Vec::new());
326    }
327    for owner in &desired_state.owners {
328        let active = global_backfill
329            || canonical_phase
330            || owner.backfill.as_ref().is_some_and(|backfill| {
331                block_number >= backfill.from_block
332                    && backfill.to_block_excl.is_none_or(|end| block_number < end)
333            });
334        if !active {
335            continue;
336        }
337        if owner
338            .interests
339            .iter()
340            .any(|interest| interest_matches_event(interest, event))
341        {
342            if global_backfill || (owner.canonical && canonical_phase) {
343                canonical = true;
344            } else {
345                owners.push(owner.owner_id.clone());
346            }
347        }
348    }
349    owners.sort();
350    owners.dedup();
351    if canonical {
352        owners.clear();
353    }
354    (canonical, owners)
355}
356
357fn global_backfill_active(desired_state: &ApplyDesiredState, block_number: u64) -> bool {
358    desired_state.owners.iter().any(|owner| {
359        owner.canonical
360            && owner.backfill.as_ref().is_some_and(|backfill| {
361                block_number >= backfill.from_block
362                    && backfill.to_block_excl.is_none_or(|end| block_number < end)
363            })
364    })
365}
366
367fn event_block_number(event: &ChainEvent) -> u64 {
368    match event.event.as_ref() {
369        Some(chain_event::Event::Log(log)) => log.block_number,
370        Some(chain_event::Event::BlockHeader(header)) => {
371            header.block.as_ref().map_or(0, |block| block.number)
372        }
373        Some(chain_event::Event::BlockProgress(progress)) => {
374            progress.block.as_ref().map_or(0, |block| block.number)
375        }
376        None => 0,
377    }
378}
379
380fn interest_matches_event(interest: &PortableInterest, event: &ChainEvent) -> bool {
381    match (&interest.kind, &event.event) {
382        (Some(portable_interest::Kind::Block(_)), Some(chain_event::Event::BlockHeader(_))) => true,
383        (Some(portable_interest::Kind::Log(interest)), Some(chain_event::Event::Log(log))) => {
384            (interest.addresses.is_empty() || interest.addresses.contains(&log.address))
385                && interest.topics.iter().enumerate().all(|(index, accepted)| {
386                    accepted.values.is_empty()
387                        || log
388                            .topics
389                            .get(index)
390                            .is_some_and(|topic| accepted.values.contains(topic))
391                })
392        }
393        _ => false,
394    }
395}
396
397pub(crate) fn encode_rollback_guard(guard: &RollbackGuard) -> Vec<u8> {
398    let mut encoded = Vec::with_capacity(88);
399    encoded.extend_from_slice(&guard.block_number.to_be_bytes());
400    encoded.extend_from_slice(guard.hash.as_ref());
401    encoded.extend_from_slice(&guard.timestamp.to_be_bytes());
402    encoded.extend_from_slice(&guard.first_block_number.to_be_bytes());
403    encoded.extend_from_slice(guard.first_parent_hash.as_ref());
404    encoded
405}
406
407pub(crate) fn decode_rollback_guard(
408    encoded: &[u8],
409) -> Result<Option<RollbackGuard>, NormalizeError> {
410    if encoded.is_empty() {
411        return Ok(None);
412    }
413    if encoded.len() != 88 {
414        return Err(NormalizeError::CheckpointWidth(encoded.len()));
415    }
416    let block_number = u64::from_be_bytes(encoded[0..8].try_into().expect("fixed slice"));
417    let hash = Hash::from(<[u8; 32]>::try_from(&encoded[8..40]).expect("fixed slice"));
418    let timestamp = i64::from_be_bytes(encoded[40..48].try_into().expect("fixed slice"));
419    let first_block_number = u64::from_be_bytes(encoded[48..56].try_into().expect("fixed slice"));
420    let first_parent_hash =
421        Hash::from(<[u8; 32]>::try_from(&encoded[56..88]).expect("fixed slice"));
422    Ok(Some(RollbackGuard {
423        block_number,
424        timestamp,
425        hash,
426        first_block_number,
427        first_parent_hash,
428    }))
429}
430
431pub(crate) fn encode_source_checkpoint<'a>(
432    guard: Option<&RollbackGuard>,
433    activation_block: u64,
434    blocks: impl ExactSizeIterator<Item = &'a BlockRef>,
435) -> Result<Vec<u8>, NormalizeError> {
436    let block_count = u32::try_from(blocks.len())
437        .map_err(|_| NormalizeError::InvalidCheckpoint("canonical history is too large"))?;
438    let mut encoded = Vec::with_capacity(
439        SOURCE_CHECKPOINT_MAGIC.len()
440            + 1
441            + usize::from(guard.is_some()) * 88
442            + 8
443            + 4
444            + block_count as usize * ENCODED_BLOCK_REF_LEN,
445    );
446    encoded.extend_from_slice(SOURCE_CHECKPOINT_MAGIC);
447    encoded.push(u8::from(guard.is_some()));
448    if let Some(guard) = guard {
449        encoded.extend_from_slice(&encode_rollback_guard(guard));
450    }
451    encoded.extend_from_slice(&activation_block.to_be_bytes());
452    encoded.extend_from_slice(&block_count.to_be_bytes());
453    for block in blocks {
454        if block.hash.len() != 32 || block.parent_hash.len() != 32 {
455            return Err(NormalizeError::InvalidCheckpoint(
456                "canonical history contains an invalid hash width",
457            ));
458        }
459        encoded.extend_from_slice(&block.number.to_be_bytes());
460        encoded.extend_from_slice(&block.hash);
461        encoded.extend_from_slice(&block.parent_hash);
462        encoded.extend_from_slice(&block.timestamp.to_be_bytes());
463    }
464    Ok(encoded)
465}
466
467pub(crate) fn decode_source_checkpoint(
468    encoded: &[u8],
469) -> Result<DecodedSourceCheckpoint, NormalizeError> {
470    if encoded.is_empty() {
471        return Ok(DecodedSourceCheckpoint::default());
472    }
473    if encoded.len() == 88 {
474        return Ok(DecodedSourceCheckpoint {
475            rollback_guard: decode_rollback_guard(encoded)?,
476            ..DecodedSourceCheckpoint::default()
477        });
478    }
479    if encoded.len() < SOURCE_CHECKPOINT_MAGIC.len() + 1 + 4
480        || &encoded[..SOURCE_CHECKPOINT_MAGIC.len()] != SOURCE_CHECKPOINT_MAGIC
481    {
482        return Err(NormalizeError::InvalidCheckpoint(
483            "unknown checkpoint encoding",
484        ));
485    }
486    let mut offset = SOURCE_CHECKPOINT_MAGIC.len();
487    let guard = match encoded[offset] {
488        0 => {
489            offset += 1;
490            None
491        }
492        1 => {
493            offset += 1;
494            let end = offset.saturating_add(88);
495            let guard = encoded
496                .get(offset..end)
497                .ok_or(NormalizeError::InvalidCheckpoint(
498                    "truncated rollback guard",
499                ))?;
500            offset = end;
501            decode_rollback_guard(guard)?
502        }
503        _ => {
504            return Err(NormalizeError::InvalidCheckpoint(
505                "invalid rollback-guard tag",
506            ));
507        }
508    };
509    let activation_block = read_u64(encoded, &mut offset)?;
510    let count_end = offset.saturating_add(4);
511    let count = u32::from_be_bytes(
512        encoded
513            .get(offset..count_end)
514            .ok_or(NormalizeError::InvalidCheckpoint(
515                "missing canonical-history count",
516            ))?
517            .try_into()
518            .map_err(|_| NormalizeError::InvalidCheckpoint("invalid history count"))?,
519    ) as usize;
520    offset = count_end;
521    let expected = offset.saturating_add(count.saturating_mul(ENCODED_BLOCK_REF_LEN));
522    if encoded.len() != expected {
523        return Err(NormalizeError::InvalidCheckpoint(
524            "canonical-history length does not match its count",
525        ));
526    }
527    let mut blocks = Vec::with_capacity(count);
528    for _ in 0..count {
529        let number = read_u64(encoded, &mut offset)?;
530        let hash = read_fixed(encoded, &mut offset, 32)?.to_vec();
531        let parent_hash = read_fixed(encoded, &mut offset, 32)?.to_vec();
532        let timestamp = read_u64(encoded, &mut offset)?;
533        blocks.push(BlockRef {
534            number,
535            hash,
536            parent_hash,
537            timestamp,
538        });
539    }
540    Ok(DecodedSourceCheckpoint {
541        rollback_guard: guard,
542        activation_block: Some(activation_block),
543        canonical_blocks: blocks,
544    })
545}
546
547fn read_u64(encoded: &[u8], offset: &mut usize) -> Result<u64, NormalizeError> {
548    Ok(u64::from_be_bytes(
549        read_fixed(encoded, offset, 8)?
550            .try_into()
551            .map_err(|_| NormalizeError::InvalidCheckpoint("invalid integer width"))?,
552    ))
553}
554
555fn read_fixed<'a>(
556    encoded: &'a [u8],
557    offset: &mut usize,
558    width: usize,
559) -> Result<&'a [u8], NormalizeError> {
560    let end = offset.saturating_add(width);
561    let bytes = encoded
562        .get(*offset..end)
563        .ok_or(NormalizeError::InvalidCheckpoint("truncated checkpoint"))?;
564    *offset = end;
565    Ok(bytes)
566}
567
568pub(crate) fn block_ref(block: &Block) -> Result<BlockRef, NormalizeError> {
569    Ok(BlockRef {
570        number: block
571            .number
572            .ok_or(NormalizeError::MissingField("block.number"))?,
573        hash: required_fixed::<32, _>(block.hash.as_ref(), "block.hash")?.to_vec(),
574        parent_hash: required_fixed::<32, _>(block.parent_hash.as_ref(), "block.parent_hash")?
575            .to_vec(),
576        timestamp: block
577            .timestamp
578            .as_ref()
579            .map(quantity_to_u64)
580            .transpose()?
581            .ok_or(NormalizeError::MissingField("block.timestamp"))?,
582    })
583}
584
585fn normalize_topics(
586    topics: &[Option<hypersync_client::format::LogArgument>],
587) -> Result<Vec<Vec<u8>>, NormalizeError> {
588    let mut normalized = Vec::with_capacity(topics.len());
589    let mut saw_missing = false;
590    for topic in topics {
591        match topic.as_ref() {
592            Some(_) if saw_missing => return Err(NormalizeError::NonContiguousLogTopics),
593            Some(topic) => {
594                normalized.push(required_fixed::<32, _>(Some(topic), "log.topic")?.to_vec())
595            }
596            None => saw_missing = true,
597        }
598    }
599    Ok(normalized)
600}
601
602fn encode_consensus_header(block: &Block) -> Result<Vec<u8>, NormalizeError> {
603    let extra_data = block
604        .extra_data
605        .as_ref()
606        .ok_or(NormalizeError::MissingField("block.extra_data"))?
607        .as_ref();
608    if extra_data.len() > 32 {
609        return Err(NormalizeError::InvalidField(
610            "block.extra_data exceeds 32 bytes",
611        ));
612    }
613    let header = ConsensusHeader {
614        parent_hash: B256::from(required_fixed(
615            block.parent_hash.as_ref(),
616            "block.parent_hash",
617        )?),
618        ommers_hash: B256::from(required_fixed(
619            block.sha3_uncles.as_ref(),
620            "block.sha3_uncles",
621        )?),
622        beneficiary: AlloyAddress::from(required_fixed(block.miner.as_ref(), "block.miner")?),
623        state_root: B256::from(required_fixed(
624            block.state_root.as_ref(),
625            "block.state_root",
626        )?),
627        transactions_root: B256::from(required_fixed(
628            block.transactions_root.as_ref(),
629            "block.transactions_root",
630        )?),
631        receipts_root: B256::from(required_fixed(
632            block.receipts_root.as_ref(),
633            "block.receipts_root",
634        )?),
635        logs_bloom: Bloom::from(required_fixed(
636            block.logs_bloom.as_ref(),
637            "block.logs_bloom",
638        )?),
639        difficulty: quantity_to_u256(
640            block
641                .difficulty
642                .as_ref()
643                .ok_or(NormalizeError::MissingField("block.difficulty"))?,
644            "block.difficulty",
645        )?,
646        number: block
647            .number
648            .ok_or(NormalizeError::MissingField("block.number"))?,
649        gas_limit: required_quantity_u64(block.gas_limit.as_ref(), "block.gas_limit")?,
650        gas_used: required_quantity_u64(block.gas_used.as_ref(), "block.gas_used")?,
651        timestamp: required_quantity_u64(block.timestamp.as_ref(), "block.timestamp")?,
652        extra_data: Bytes::copy_from_slice(extra_data),
653        mix_hash: B256::from(required_fixed(block.mix_hash.as_ref(), "block.mix_hash")?),
654        nonce: B64::from(required_fixed(block.nonce.as_ref(), "block.nonce")?),
655        base_fee_per_gas: optional_quantity_u64(
656            block.base_fee_per_gas.as_ref(),
657            "block.base_fee_per_gas",
658        )?,
659        withdrawals_root: optional_b256(block.withdrawals_root.as_ref(), "block.withdrawals_root")?,
660        blob_gas_used: optional_quantity_u64(block.blob_gas_used.as_ref(), "block.blob_gas_used")?,
661        excess_blob_gas: optional_quantity_u64(
662            block.excess_blob_gas.as_ref(),
663            "block.excess_blob_gas",
664        )?,
665        parent_beacon_block_root: optional_b256(
666            block.parent_beacon_block_root.as_ref(),
667            "block.parent_beacon_block_root",
668        )?,
669        requests_hash: None,
670    };
671    let expected_hash = B256::from(required_fixed(block.hash.as_ref(), "block.hash")?);
672    let actual_hash = header.hash_slow();
673    if actual_hash != expected_hash {
674        return Err(NormalizeError::HeaderHashMismatch {
675            expected: expected_hash.as_slice().to_vec(),
676            actual: actual_hash.as_slice().to_vec(),
677        });
678    }
679    let mut encoded = Vec::new();
680    header.encode(&mut encoded);
681    Ok(encoded)
682}
683
684fn required_fixed<const N: usize, T: AsRef<[u8]>>(
685    value: Option<&T>,
686    field: &'static str,
687) -> Result<[u8; N], NormalizeError> {
688    let bytes = value.ok_or(NormalizeError::MissingField(field))?.as_ref();
689    bytes.try_into().map_err(|_| NormalizeError::InvalidWidth {
690        field,
691        expected: N,
692        received: bytes.len(),
693    })
694}
695
696fn optional_b256<T: AsRef<[u8]>>(
697    value: Option<&T>,
698    field: &'static str,
699) -> Result<Option<B256>, NormalizeError> {
700    value
701        .map(|value| required_fixed(Some(value), field).map(B256::from))
702        .transpose()
703}
704
705fn required_quantity_u64(
706    value: Option<&Quantity>,
707    field: &'static str,
708) -> Result<u64, NormalizeError> {
709    value
710        .ok_or(NormalizeError::MissingField(field))
711        .and_then(|value| quantity_to_u64_field(value, field))
712}
713
714fn optional_quantity_u64(
715    value: Option<&Quantity>,
716    field: &'static str,
717) -> Result<Option<u64>, NormalizeError> {
718    value
719        .map(|value| quantity_to_u64_field(value, field))
720        .transpose()
721}
722
723fn quantity_to_u64_field(value: &Quantity, field: &'static str) -> Result<u64, NormalizeError> {
724    let bytes = value.as_ref();
725    if bytes.len() > 8 {
726        return Err(NormalizeError::QuantityOverflow(field));
727    }
728    let mut buffer = [0_u8; 8];
729    buffer[8 - bytes.len()..].copy_from_slice(bytes);
730    Ok(u64::from_be_bytes(buffer))
731}
732
733fn quantity_to_u256(value: &Quantity, field: &'static str) -> Result<U256, NormalizeError> {
734    let bytes = value.as_ref();
735    if bytes.len() > 32 {
736        return Err(NormalizeError::QuantityOverflow(field));
737    }
738    Ok(U256::from_be_slice(bytes))
739}
740
741fn required_bytes<T: AsRef<[u8]>>(
742    value: Option<&T>,
743    field: &'static str,
744) -> Result<Vec<u8>, NormalizeError> {
745    value
746        .map(|value| value.as_ref().to_vec())
747        .ok_or(NormalizeError::MissingField(field))
748}
749
750fn required_u64<T: Into<u64>>(
751    value: Option<T>,
752    field: &'static str,
753) -> Result<u64, NormalizeError> {
754    value
755        .map(Into::into)
756        .ok_or(NormalizeError::MissingField(field))
757}
758
759fn quantity_to_u64(value: &Quantity) -> Result<u64, NormalizeError> {
760    let bytes = value.as_ref();
761    if bytes.len() > 8 {
762        return Err(NormalizeError::QuantityOverflow("block.timestamp"));
763    }
764    let mut buffer = [0_u8; 8];
765    buffer[8 - bytes.len()..].copy_from_slice(bytes);
766    Ok(u64::from_be_bytes(buffer))
767}
768
769/// Source data could not be represented by the event protocol.
770#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
771#[non_exhaustive]
772pub enum NormalizeError {
773    /// A field required for canonical identity or runtime input was absent.
774    #[error("source response is missing required field `{0}`")]
775    MissingField(&'static str),
776    /// A log was returned without its canonical block and timestamp.
777    #[error("source log at block {block_number} has no corresponding block")]
778    LogWithoutBlock {
779        /// Orphaned log block number.
780        block_number: u64,
781    },
782    /// A later indexed topic was present after an earlier position was absent.
783    #[error("source log topics are not a contiguous prefix")]
784    NonContiguousLogTopics,
785    /// A fixed-width consensus field had the wrong encoded size.
786    #[error("source field `{field}` must be {expected} bytes, got {received}")]
787    InvalidWidth {
788        /// Field name.
789        field: &'static str,
790        /// Consensus width.
791        expected: usize,
792        /// Provider width.
793        received: usize,
794    },
795    /// A consensus field violated a structural invariant.
796    #[error("invalid source field: {0}")]
797    InvalidField(&'static str),
798    /// A numeric source value did not fit the protocol's fixed width.
799    #[error("source quantity `{0}` does not fit in u64")]
800    QuantityOverflow(&'static str),
801    /// An opaque HyperSync checkpoint had an unexpected encoded width.
802    #[error("HyperSync checkpoint must be 88 bytes, got {0}")]
803    CheckpointWidth(usize),
804    /// An opaque source checkpoint was corrupt or from an unknown format.
805    #[error("invalid HyperSync source checkpoint: {0}")]
806    InvalidCheckpoint(&'static str),
807    /// Reconstructed consensus fields did not reproduce the provider's block hash.
808    #[error("reconstructed header hash {actual:?} does not match provider hash {expected:?}")]
809    HeaderHashMismatch {
810        /// Hash returned by the provider.
811        expected: Vec<u8>,
812        /// Hash computed from the reconstructed RLP.
813        actual: Vec<u8>,
814    },
815}