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#[derive(Clone, Debug, Default)]
29#[non_exhaustive]
30pub struct SourcePage {
31 pub archive_height: Option<u64>,
33 pub next_block: u64,
35 pub blocks: Vec<Block>,
37 pub logs: Vec<Log>,
39 pub rollback_guard: Option<RollbackGuard>,
41}
42
43impl SourcePage {
44 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 pub fn with_archive_height(mut self, archive_height: Option<u64>) -> Self {
57 self.archive_height = archive_height;
58 self
59 }
60
61 pub fn with_rollback_guard(mut self, rollback_guard: Option<RollbackGuard>) -> Self {
63 self.rollback_guard = rollback_guard;
64 self
65 }
66}
67
68pub 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 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#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
771#[non_exhaustive]
772pub enum NormalizeError {
773 #[error("source response is missing required field `{0}`")]
775 MissingField(&'static str),
776 #[error("source log at block {block_number} has no corresponding block")]
778 LogWithoutBlock {
779 block_number: u64,
781 },
782 #[error("source log topics are not a contiguous prefix")]
784 NonContiguousLogTopics,
785 #[error("source field `{field}` must be {expected} bytes, got {received}")]
787 InvalidWidth {
788 field: &'static str,
790 expected: usize,
792 received: usize,
794 },
795 #[error("invalid source field: {0}")]
797 InvalidField(&'static str),
798 #[error("source quantity `{0}` does not fit in u64")]
800 QuantityOverflow(&'static str),
801 #[error("HyperSync checkpoint must be 88 bytes, got {0}")]
803 CheckpointWidth(usize),
804 #[error("invalid HyperSync source checkpoint: {0}")]
806 InvalidCheckpoint(&'static str),
807 #[error("reconstructed header hash {actual:?} does not match provider hash {expected:?}")]
809 HeaderHashMismatch {
810 expected: Vec<u8>,
812 actual: Vec<u8>,
814 },
815}