1use std::pin::Pin;
2
3use async_trait::async_trait;
4use evm_fork_cache_event_protocol::{
5 MAX_MESSAGE_SIZE_BYTES,
6 v1::{ApplyDesiredState, Barrier, BlockRef, Cursor, Delivery, Reorg, delivery},
7};
8use futures::Stream;
9use hypersync_client::{
10 format::Hash,
11 net_types::{BlockField, Query, RollbackGuard},
12};
13use prost::Message;
14
15use crate::{
16 CanonicalError, CanonicalTracker, NormalizeError, QueryPlanError, ReorgDelta, SourcePage,
17 SourcePageError,
18 normalize::{block_ref, encode_source_checkpoint, normalize_page_at},
19 page_validation::validate_source_page,
20 query_plan::{MAX_BLOCKS_PER_QUERY, MAX_LOGS_PER_QUERY, compile_query_with_limits},
21};
22
23pub const MAX_DELIVERY_SIZE_BYTES: usize = MAX_MESSAGE_SIZE_BYTES - 64 * 1024;
25pub const MAX_BLOCKS_PER_RESPONSE: usize = MAX_BLOCKS_PER_QUERY * 2;
27pub const MAX_LOGS_PER_RESPONSE: usize = MAX_LOGS_PER_QUERY * 2;
29pub const MAX_DYNAMIC_BYTES_PER_RESPONSE: usize = 16 * 1024 * 1024;
31
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40#[non_exhaustive]
41pub struct SourceResponseLimits {
42 max_blocks: usize,
43 max_logs: usize,
44 max_dynamic_bytes: usize,
45}
46
47impl SourceResponseLimits {
48 pub fn new(
54 max_blocks: usize,
55 max_logs: usize,
56 max_dynamic_bytes: usize,
57 ) -> Result<Self, SourceError> {
58 if max_blocks == 0 {
59 return Err(SourceError::InvalidResponseLimit { resource: "blocks" });
60 }
61 if max_logs == 0 {
62 return Err(SourceError::InvalidResponseLimit { resource: "logs" });
63 }
64 if max_dynamic_bytes == 0 {
65 return Err(SourceError::InvalidResponseLimit {
66 resource: "dynamic bytes",
67 });
68 }
69 Ok(Self {
70 max_blocks,
71 max_logs,
72 max_dynamic_bytes,
73 })
74 }
75
76 pub const fn max_blocks(&self) -> usize {
78 self.max_blocks
79 }
80
81 pub const fn max_logs(&self) -> usize {
83 self.max_logs
84 }
85
86 pub const fn max_dynamic_bytes(&self) -> usize {
88 self.max_dynamic_bytes
89 }
90}
91
92impl Default for SourceResponseLimits {
93 fn default() -> Self {
94 Self {
95 max_blocks: MAX_BLOCKS_PER_RESPONSE,
96 max_logs: MAX_LOGS_PER_RESPONSE,
97 max_dynamic_bytes: MAX_DYNAMIC_BYTES_PER_RESPONSE,
98 }
99 }
100}
101
102pub type ChainHeightStream = Pin<Box<dyn Stream<Item = u64> + Send + 'static>>;
104
105#[async_trait]
107pub trait ChainDataSource: Send + Sync {
108 async fn height(&self) -> Result<u64, SourceError>;
117
118 async fn query(&self, query: Query) -> Result<SourcePage, SourceError>;
125
126 fn height_stream(&self) -> Option<ChainHeightStream> {
129 None
130 }
131}
132
133pub struct SourceEngine<S> {
135 source: S,
136 desired_state: ApplyDesiredState,
137 committed_next_block: u64,
138 committed_sequence: u64,
139 activation_block: u64,
140 owner_backfill_activation_block: Option<u64>,
141 coverage_head: Option<BlockRef>,
142 canonical: CanonicalTracker,
143 previous_guard: Option<RollbackGuard>,
144 max_delivery_bytes: usize,
145 response_limits: SourceResponseLimits,
146 pending: Option<PendingDelivery>,
147 queued: Option<PendingDelivery>,
148}
149
150struct PendingDelivery {
151 delivery: Delivery,
152 rollback_guard: Option<RollbackGuard>,
153 advances_source: bool,
154}
155
156#[derive(Clone, Debug)]
158#[non_exhaustive]
159pub struct SourceResume {
160 pub next_block: u64,
162 pub sequence: u64,
164 pub activation_block: u64,
166 pub owner_backfill_activation_block: Option<u64>,
168 pub canonical_blocks: Vec<BlockRef>,
170 pub provider_checkpoint: Option<RollbackGuard>,
172 pub coverage_head: Option<BlockRef>,
174}
175
176impl SourceResume {
177 pub fn new(next_block: u64, sequence: u64, activation_block: u64) -> Self {
179 Self {
180 next_block,
181 sequence,
182 activation_block,
183 owner_backfill_activation_block: Some(activation_block),
184 canonical_blocks: Vec::new(),
185 provider_checkpoint: None,
186 coverage_head: None,
187 }
188 }
189
190 pub fn with_canonical_blocks(mut self, canonical_blocks: Vec<BlockRef>) -> Self {
192 self.canonical_blocks = canonical_blocks;
193 self
194 }
195
196 pub fn with_provider_checkpoint(mut self, provider_checkpoint: Option<RollbackGuard>) -> Self {
198 self.provider_checkpoint = provider_checkpoint;
199 self
200 }
201
202 pub fn with_coverage_head(mut self, coverage_head: Option<BlockRef>) -> Self {
204 self.coverage_head = coverage_head;
205 self
206 }
207}
208
209impl<S> SourceEngine<S>
210where
211 S: ChainDataSource,
212{
213 pub fn new(
215 source: S,
216 desired_state: ApplyDesiredState,
217 committed_next_block: u64,
218 activation_block: u64,
219 reorg_depth: usize,
220 ) -> Self {
221 Self {
222 source,
223 desired_state,
224 committed_next_block,
225 committed_sequence: 0,
226 activation_block,
227 owner_backfill_activation_block: Some(activation_block),
228 coverage_head: None,
229 canonical: CanonicalTracker::new(reorg_depth),
230 previous_guard: None,
231 max_delivery_bytes: MAX_DELIVERY_SIZE_BYTES,
232 response_limits: SourceResponseLimits::default(),
233 pending: None,
234 queued: None,
235 }
236 }
237
238 pub fn restore(
247 source: S,
248 desired_state: ApplyDesiredState,
249 resume: SourceResume,
250 reorg_depth: usize,
251 ) -> Result<Self, SourceEngineError> {
252 let mut canonical = CanonicalTracker::new(reorg_depth);
253 if !resume.canonical_blocks.is_empty() {
254 canonical.apply_blocks(resume.canonical_blocks)?;
255 }
256 let previous_guard =
257 validate_resume_state(&canonical, resume.next_block, resume.provider_checkpoint)?;
258 validate_coverage_state(&canonical, resume.next_block, resume.coverage_head.as_ref())?;
259 Ok(Self {
260 source,
261 desired_state,
262 committed_next_block: resume.next_block,
263 committed_sequence: resume.sequence,
264 activation_block: resume.activation_block,
265 owner_backfill_activation_block: resume.owner_backfill_activation_block,
266 coverage_head: resume.coverage_head,
267 canonical,
268 previous_guard,
269 max_delivery_bytes: MAX_DELIVERY_SIZE_BYTES,
270 response_limits: SourceResponseLimits::default(),
271 pending: None,
272 queued: None,
273 })
274 }
275
276 pub fn with_max_delivery_bytes(
283 mut self,
284 max_delivery_bytes: usize,
285 ) -> Result<Self, SourceEngineError> {
286 if max_delivery_bytes == 0 || max_delivery_bytes > MAX_DELIVERY_SIZE_BYTES {
287 return Err(SourceEngineError::InvalidDeliverySizeLimit {
288 requested: max_delivery_bytes,
289 maximum: MAX_DELIVERY_SIZE_BYTES,
290 });
291 }
292 self.max_delivery_bytes = max_delivery_bytes;
293 Ok(self)
294 }
295
296 pub fn with_response_limits(mut self, response_limits: SourceResponseLimits) -> Self {
298 self.response_limits = response_limits;
299 self
300 }
301
302 pub async fn next_batch(
311 &mut self,
312 to_block_excl: u64,
313 ) -> Result<Option<Delivery>, SourceEngineError> {
314 if let Some(pending) = &self.pending {
315 return Ok(Some(pending.delivery.clone()));
316 }
317 if self.committed_next_block >= to_block_excl {
318 return Ok(None);
319 }
320 let sequence = self
321 .committed_sequence
322 .checked_add(1)
323 .ok_or(SourceEngineError::SequenceExhausted)?;
324
325 let mut query_limits = QueryLimits::for_range(self.committed_next_block, to_block_excl);
326 let mut initial_anchor = None;
327 let (mut delivery, rollback_guard, canonical, reorg) = loop {
328 let page = self
329 .query_page(self.committed_next_block, to_block_excl, query_limits)
330 .await?;
331 if initial_anchor.is_none() {
332 initial_anchor = self.query_canonical_anchor(&page).await?;
333 }
334 let prepared = if self.rollback_detected(&page) {
335 self.recover_rollback(to_block_excl, sequence, query_limits)
336 .await?
337 } else {
338 self.prepare_batch(page, sequence, initial_anchor.as_ref())?
339 };
340 let encoded_len = prepared.0.encoded_len();
341 if encoded_len <= self.max_delivery_bytes {
342 break prepared;
343 }
344 if !query_limits.shrink() {
345 return Err(SourceEngineError::DeliveryTooLarge {
346 encoded_len,
347 limit: self.max_delivery_bytes,
348 });
349 }
350 };
351 if let Some(reorg) = reorg {
352 if reorg.old_tip.number < self.activation_block
360 && !global_backfill_contains(&self.desired_state, reorg.old_tip.number)
361 {
362 return Err(SourceEngineError::OwnerCatchupReorg {
363 activation_block: self.activation_block,
364 common_ancestor: reorg.common_ancestor.number,
365 old_tip: reorg.old_tip.number,
366 new_tip: reorg.new_tip.number,
367 });
368 }
369 let replacement_sequence = sequence
370 .checked_add(1)
371 .ok_or(SourceEngineError::SequenceExhausted)?;
372 set_delivery_sequence(&mut delivery, replacement_sequence)?;
373 let control = self.reorg_delivery(sequence, reorg)?;
374 let encoded_len = control.encoded_len();
375 if encoded_len > self.max_delivery_bytes {
376 return Err(SourceEngineError::DeliveryTooLarge {
377 encoded_len,
378 limit: self.max_delivery_bytes,
379 });
380 }
381 self.canonical = canonical;
382 self.queued = Some(PendingDelivery {
383 delivery,
384 rollback_guard,
385 advances_source: true,
386 });
387 self.pending = Some(PendingDelivery {
388 delivery: control.clone(),
389 rollback_guard: self.previous_guard.clone(),
390 advances_source: false,
391 });
392 Ok(Some(control))
393 } else {
394 self.canonical = canonical;
395 self.pending = Some(PendingDelivery {
396 delivery: delivery.clone(),
397 rollback_guard,
398 advances_source: true,
399 });
400 Ok(Some(delivery))
401 }
402 }
403
404 pub fn acknowledge(&mut self, delivery_token: &[u8]) -> Result<(), SourceEngineError> {
413 let pending = self
414 .pending
415 .as_ref()
416 .ok_or(SourceEngineError::NoPendingDelivery)?;
417 if pending.delivery.delivery_token != delivery_token {
418 return Err(SourceEngineError::DeliveryTokenMismatch);
419 }
420 let cursor = pending
421 .delivery
422 .cursor
423 .as_ref()
424 .ok_or(SourceEngineError::MissingCursor)?;
425 let committed_next_block = cursor.next_block;
426 let committed_sequence = pending.delivery.sequence;
427 let advances_source = pending.advances_source;
428 let rollback_guard = pending.rollback_guard.clone();
429 let coverage_head = cursor.canonical_head.clone();
430 if advances_source {
431 self.committed_next_block = committed_next_block;
432 self.previous_guard = rollback_guard;
433 }
434 self.committed_sequence = committed_sequence;
435 self.coverage_head = coverage_head;
436 self.pending = self.queued.take();
437 Ok(())
438 }
439
440 pub fn committed_next_block(&self) -> u64 {
442 self.committed_next_block
443 }
444
445 pub fn activation_cursor(&self) -> Result<Cursor, SourceEngineError> {
453 Ok(Cursor {
454 chain_id: self.desired_state.chain_id,
455 query_revision: self.desired_state.new_revision,
456 next_block: self.committed_next_block,
457 canonical_head: self.coverage_head.clone(),
458 batch_sequence: self.committed_sequence,
459 provider_checkpoint: encode_source_checkpoint(
460 self.previous_guard.as_ref(),
461 self.activation_block,
462 self.canonical.blocks(),
463 )?,
464 owner_backfill_activation_block: self.owner_backfill_activation_block,
465 })
466 }
467
468 pub fn committed_sequence(&self) -> u64 {
470 self.committed_sequence
471 }
472
473 pub fn acknowledge_external_control(&mut self, sequence: u64) -> Result<(), SourceEngineError> {
482 if self.pending.is_some() {
483 return Err(SourceEngineError::PendingDelivery);
484 }
485 if sequence < self.committed_sequence {
486 return Err(SourceEngineError::SequenceRegression {
487 committed: self.committed_sequence,
488 received: sequence,
489 });
490 }
491 self.committed_sequence = sequence;
492 Ok(())
493 }
494
495 pub fn synchronize_committed_cursor(
505 &mut self,
506 resume: SourceResume,
507 ) -> Result<(), SourceEngineError> {
508 if self.pending.is_some() {
509 return Err(SourceEngineError::PendingDelivery);
510 }
511 if resume.sequence < self.committed_sequence {
512 return Err(SourceEngineError::SequenceRegression {
513 committed: self.committed_sequence,
514 received: resume.sequence,
515 });
516 }
517 let mut canonical = self.canonical.clone();
518 canonical.restore_blocks(resume.canonical_blocks)?;
519 let previous_guard =
520 validate_resume_state(&canonical, resume.next_block, resume.provider_checkpoint)?;
521 validate_coverage_state(&canonical, resume.next_block, resume.coverage_head.as_ref())?;
522 self.canonical = canonical;
523 self.committed_next_block = resume.next_block;
524 self.committed_sequence = resume.sequence;
525 self.activation_block = resume.activation_block;
526 self.previous_guard = previous_guard;
527 self.coverage_head = resume.coverage_head;
528 self.owner_backfill_activation_block = resume.owner_backfill_activation_block;
529 Ok(())
530 }
531
532 pub fn activation_block(&self) -> u64 {
534 self.activation_block
535 }
536
537 pub fn source(&self) -> &S {
539 &self.source
540 }
541
542 async fn query_page(
543 &self,
544 from_block: u64,
545 to_block_excl: u64,
546 limits: QueryLimits,
547 ) -> Result<SourcePage, SourceEngineError> {
548 let query = compile_query_with_limits(
549 &self.desired_state,
550 from_block,
551 Some(to_block_excl),
552 limits.max_blocks,
553 limits.max_logs,
554 )?;
555 let page = self.source.query(query).await?;
556 validate_response_counts(&page, self.response_limits)?;
557 if page.next_block <= from_block {
558 return Err(SourceEngineError::NoProgress {
559 from_block,
560 next_block: page.next_block,
561 });
562 }
563 validate_source_page(&page, from_block, to_block_excl)?;
564 Ok(page)
565 }
566
567 async fn query_canonical_anchor(
568 &self,
569 page: &SourcePage,
570 ) -> Result<Option<BlockRef>, SourceEngineError> {
571 if !self.canonical.is_empty() {
572 return Ok(None);
573 }
574 let Some(guard) = page.rollback_guard.as_ref() else {
575 return Ok(None);
576 };
577 let Some(anchor_number) = guard.first_block_number.checked_sub(1) else {
578 return Ok(None);
579 };
580 let anchor_end = anchor_number
581 .checked_add(1)
582 .ok_or(SourceEngineError::BlockNumberOverflow)?;
583 let mut query = Query::new()
584 .from_block(anchor_number)
585 .to_block_excl(anchor_end)
586 .include_all_blocks()
587 .select_block_fields([
588 BlockField::Number,
589 BlockField::Hash,
590 BlockField::ParentHash,
591 BlockField::Timestamp,
592 ]);
593 query.max_num_blocks = Some(1);
594 query.max_num_logs = Some(1);
595 let anchor_page = self.source.query(query).await?;
596 validate_response_counts(&anchor_page, self.response_limits)?;
597 if anchor_page.next_block <= anchor_number {
598 return Err(SourceEngineError::NoProgress {
599 from_block: anchor_number,
600 next_block: anchor_page.next_block,
601 });
602 }
603 validate_source_page(&anchor_page, anchor_number, anchor_end)?;
604 let anchor = block_ref(
605 anchor_page
606 .blocks
607 .first()
608 .expect("validated one-block anchor page"),
609 )?;
610 if anchor.hash.as_slice() != guard.first_parent_hash.as_ref() {
611 return Err(CanonicalError::UnknownParent {
612 number: guard.first_block_number,
613 parent_hash: guard.first_parent_hash.as_ref().to_vec(),
614 }
615 .into());
616 }
617 Ok(Some(anchor))
618 }
619
620 fn rollback_detected(&self, page: &SourcePage) -> bool {
621 match (&self.previous_guard, &page.rollback_guard) {
622 (Some(previous), Some(current)) => {
623 current.first_block_number <= previous.block_number.saturating_add(1)
624 && current.first_parent_hash != previous.hash
625 }
626 _ => false,
627 }
628 }
629
630 async fn recover_rollback(
631 &self,
632 to_block_excl: u64,
633 sequence: u64,
634 limits: QueryLimits,
635 ) -> Result<PreparedPage, SourceEngineError> {
636 let previous = self
637 .previous_guard
638 .as_ref()
639 .ok_or(SourceEngineError::MissingRollbackGuard)?;
640 let oldest = self
641 .canonical
642 .blocks()
643 .next()
644 .map(|block| block.number)
645 .ok_or(CanonicalError::HistoryExhausted {
646 required_block: previous.block_number,
647 })?;
648 let newest = self
649 .canonical
650 .tip()
651 .map(|block| block.number.min(previous.block_number))
652 .ok_or(CanonicalError::HistoryExhausted {
653 required_block: previous.block_number,
654 })?;
655
656 let mut low = oldest;
661 let mut high = newest;
662 let mut common_ancestor = None;
663 while low <= high {
664 let candidate = low + (high - low) / 2;
665 let observed = self.query_canonical_block(candidate).await?;
666 let expected = self
667 .canonical
668 .block(candidate)
669 .expect("binary probe stays inside retained canonical history");
670 if observed.hash == expected.hash {
671 if observed != *expected {
672 return Err(
673 CanonicalError::ConflictingBlockMetadata { number: candidate }.into(),
674 );
675 }
676 common_ancestor = Some(candidate);
677 let Some(next) = candidate.checked_add(1) else {
678 break;
679 };
680 low = next;
681 } else if candidate == 0 {
682 break;
683 } else {
684 high = candidate - 1;
685 }
686 }
687 let common_ancestor = common_ancestor.ok_or(CanonicalError::HistoryExhausted {
688 required_block: oldest.saturating_sub(1),
689 })?;
690 let replacement_start = common_ancestor
691 .checked_add(1)
692 .ok_or(SourceEngineError::BlockNumberOverflow)?;
693 let page = self
694 .query_page(replacement_start, to_block_excl, limits)
695 .await?;
696 self.prepare_batch(page, sequence, None)
697 }
698
699 async fn query_canonical_block(&self, number: u64) -> Result<BlockRef, SourceEngineError> {
700 let end = number
701 .checked_add(1)
702 .ok_or(SourceEngineError::BlockNumberOverflow)?;
703 let mut query = Query::new()
704 .from_block(number)
705 .to_block_excl(end)
706 .include_all_blocks()
707 .select_block_fields([
708 BlockField::Number,
709 BlockField::Hash,
710 BlockField::ParentHash,
711 BlockField::Timestamp,
712 ]);
713 query.max_num_blocks = Some(1);
714 query.max_num_logs = Some(1);
715 let page = self.source.query(query).await?;
716 validate_response_counts(&page, self.response_limits)?;
717 if page.next_block <= number {
718 return Err(SourceEngineError::NoProgress {
719 from_block: number,
720 next_block: page.next_block,
721 });
722 }
723 validate_source_page(&page, number, end)?;
724 block_ref(page.blocks.first().expect("validated single-block page")).map_err(Into::into)
725 }
726
727 fn prepare_batch(
728 &self,
729 page: SourcePage,
730 sequence: u64,
731 initial_anchor: Option<&BlockRef>,
732 ) -> Result<PreparedPage, SourceEngineError> {
733 let rollback_guard = page.rollback_guard.clone();
734 let page_blocks = page
735 .blocks
736 .iter()
737 .map(block_ref)
738 .collect::<Result<Vec<_>, _>>()?;
739 let crosses_untracked_coverage_boundary =
746 self.coverage_head.as_ref().is_some_and(|coverage| {
747 self.canonical.is_empty() || self.committed_next_block <= coverage.number
748 });
749 if initial_anchor.is_some() || crosses_untracked_coverage_boundary {
750 validate_coverage_boundary(self.coverage_head.as_ref(), &page_blocks, initial_anchor)?;
751 }
752 let mut delivery =
753 normalize_page_at(&self.desired_state, sequence, page, self.activation_block)?;
754 let mut canonical = self.canonical.clone();
755 if canonical.is_empty()
756 && let Some(anchor) = initial_anchor
757 {
758 canonical.apply_blocks([anchor.clone()])?;
759 }
760 let reorg = canonical.apply_blocks(page_blocks)?;
761 delivery
762 .cursor
763 .as_mut()
764 .ok_or(SourceEngineError::MissingCursor)?
765 .provider_checkpoint = encode_source_checkpoint(
766 rollback_guard.as_ref(),
767 self.activation_block,
768 canonical.blocks(),
769 )?;
770 let cursor = delivery
771 .cursor
772 .as_mut()
773 .expect("delivery cursor was validated above");
774 cursor.owner_backfill_activation_block = self.owner_backfill_activation_block;
775 if cursor.canonical_head.is_none() {
776 cursor.canonical_head = self.coverage_head.clone();
777 }
778 if matches!(
779 delivery.payload.as_ref(),
780 Some(delivery::Payload::Data(data)) if data.records.is_empty()
781 ) {
782 let progress_block = delivery
783 .cursor
784 .as_ref()
785 .and_then(|cursor| cursor.canonical_head.clone())
786 .filter(|head| self.coverage_head.as_ref() != Some(head));
787 delivery.payload = Some(delivery::Payload::Barrier(Barrier {
788 id: format!(
789 "source-progress:{}:{}",
790 self.desired_state.new_revision,
791 delivery
792 .cursor
793 .as_ref()
794 .expect("validated cursor")
795 .next_block
796 )
797 .into_bytes(),
798 block: progress_block.clone(),
799 }));
800 delivery.checkpoint_neutral = progress_block.is_none();
801 }
802 Ok((delivery, rollback_guard, canonical, reorg))
803 }
804
805 fn reorg_delivery(
806 &self,
807 sequence: u64,
808 reorg: ReorgDelta,
809 ) -> Result<Delivery, SourceEngineError> {
810 let next_block = reorg
811 .common_ancestor
812 .number
813 .checked_add(1)
814 .ok_or(SourceEngineError::BlockNumberOverflow)?;
815 let rollback_guard = rollback_guard_at(&reorg.common_ancestor)?;
816 let canonical_prefix: Vec<_> = self
817 .canonical
818 .blocks()
819 .take_while(|block| block.number <= reorg.common_ancestor.number)
820 .collect();
821 Ok(Delivery {
822 session_id: self.desired_state.session_id.clone(),
823 sequence,
824 query_revision: self.desired_state.new_revision,
825 delivery_token: sequence.to_be_bytes().to_vec(),
826 cursor: Some(Cursor {
827 chain_id: self.desired_state.chain_id,
828 query_revision: self.desired_state.new_revision,
829 next_block,
830 canonical_head: Some(reorg.common_ancestor.clone()),
831 batch_sequence: sequence,
832 provider_checkpoint: encode_source_checkpoint(
833 Some(&rollback_guard),
834 self.activation_block,
835 canonical_prefix.into_iter(),
836 )?,
837 owner_backfill_activation_block: self.owner_backfill_activation_block,
838 }),
839 payload: Some(delivery::Payload::Reorg(Reorg {
840 common_ancestor: Some(reorg.common_ancestor),
841 old_tip: Some(reorg.old_tip),
842 new_tip: Some(reorg.new_tip),
843 })),
844 checkpoint_neutral: false,
845 })
846 }
847}
848
849fn global_backfill_contains(desired_state: &ApplyDesiredState, block_number: u64) -> bool {
850 desired_state.owners.iter().any(|owner| {
851 owner.canonical
852 && owner.backfill.as_ref().is_some_and(|backfill| {
853 block_number >= backfill.from_block
854 && backfill.to_block_excl.is_none_or(|end| block_number < end)
855 })
856 })
857}
858
859fn validate_coverage_state(
860 canonical: &CanonicalTracker,
861 next_block: u64,
862 coverage_head: Option<&BlockRef>,
863) -> Result<(), SourceEngineError> {
864 let Some(coverage_head) = coverage_head else {
865 return Ok(());
866 };
867 let mut validator = CanonicalTracker::new(1);
868 validator.apply_blocks([coverage_head.clone()])?;
869 let coverage_successor = coverage_head
870 .number
871 .checked_add(1)
872 .ok_or(SourceEngineError::BlockNumberOverflow)?;
873 if next_block > coverage_successor {
874 return Err(SourceEngineError::CoverageCursorMismatch {
875 coverage_successor,
876 received: next_block,
877 });
878 }
879 if let Some(scanned) = canonical.block(coverage_head.number)
880 && scanned != coverage_head
881 {
882 return Err(SourceEngineError::CoverageBoundaryConflict {
883 number: coverage_head.number,
884 });
885 }
886 Ok(())
887}
888
889fn validate_coverage_boundary(
890 coverage_head: Option<&BlockRef>,
891 page_blocks: &[BlockRef],
892 initial_anchor: Option<&BlockRef>,
893) -> Result<(), SourceEngineError> {
894 let Some(coverage_head) = coverage_head else {
895 return Ok(());
896 };
897 if let Some(observed) = page_blocks
898 .iter()
899 .find(|block| block.number == coverage_head.number)
900 .or_else(|| initial_anchor.filter(|block| block.number == coverage_head.number))
901 && observed != coverage_head
902 {
903 return Err(SourceEngineError::CoverageBoundaryConflict {
904 number: coverage_head.number,
905 });
906 }
907 if let Some(first) = page_blocks.first()
908 && first.number == coverage_head.number.saturating_add(1)
909 && first.parent_hash != coverage_head.hash
910 {
911 return Err(SourceEngineError::CoverageBoundaryConflict {
912 number: coverage_head.number,
913 });
914 }
915 Ok(())
916}
917
918pub(crate) fn validate_response_counts(
919 page: &SourcePage,
920 limits: SourceResponseLimits,
921) -> Result<(), SourceEngineError> {
922 if page.blocks.len() > limits.max_blocks {
923 return Err(SourceEngineError::ResponseLimitExceeded {
924 resource: "blocks",
925 observed: page.blocks.len(),
926 limit: limits.max_blocks,
927 });
928 }
929 if page.logs.len() > limits.max_logs {
930 return Err(SourceEngineError::ResponseLimitExceeded {
931 resource: "logs",
932 observed: page.logs.len(),
933 limit: limits.max_logs,
934 });
935 }
936 validate_response_dynamic_bytes(page, limits.max_dynamic_bytes)?;
937 Ok(())
938}
939
940fn validate_response_dynamic_bytes(
941 page: &SourcePage,
942 limit: usize,
943) -> Result<(), SourceEngineError> {
944 let mut observed = std::mem::size_of::<hypersync_client::simple_types::Block>()
948 .saturating_mul(page.blocks.capacity())
949 .saturating_add(
950 std::mem::size_of::<hypersync_client::simple_types::Log>()
951 .saturating_mul(page.logs.capacity()),
952 );
953 check_dynamic_bytes(observed, limit)?;
954
955 macro_rules! add_bytes {
956 ($value:expr) => {
957 if let Some(value) = $value.as_ref() {
958 observed = observed.saturating_add(value.as_ref().len());
959 check_dynamic_bytes(observed, limit)?;
960 }
961 };
962 }
963
964 for block in &page.blocks {
965 add_bytes!(block.hash);
966 add_bytes!(block.parent_hash);
967 add_bytes!(block.nonce);
968 add_bytes!(block.sha3_uncles);
969 add_bytes!(block.logs_bloom);
970 add_bytes!(block.transactions_root);
971 add_bytes!(block.state_root);
972 add_bytes!(block.receipts_root);
973 add_bytes!(block.miner);
974 add_bytes!(block.difficulty);
975 add_bytes!(block.total_difficulty);
976 add_bytes!(block.extra_data);
977 add_bytes!(block.size);
978 add_bytes!(block.gas_limit);
979 add_bytes!(block.gas_used);
980 add_bytes!(block.timestamp);
981 add_bytes!(block.base_fee_per_gas);
982 add_bytes!(block.blob_gas_used);
983 add_bytes!(block.excess_blob_gas);
984 add_bytes!(block.parent_beacon_block_root);
985 add_bytes!(block.withdrawals_root);
986 add_bytes!(block.send_count);
987 add_bytes!(block.send_root);
988 add_bytes!(block.mix_hash);
989 if let Some(uncles) = &block.uncles {
990 observed = observed
991 .saturating_add(std::mem::size_of::<Hash>().saturating_mul(uncles.capacity()));
992 check_dynamic_bytes(observed, limit)?;
993 for uncle in uncles {
994 observed = observed.saturating_add(uncle.as_ref().len());
995 check_dynamic_bytes(observed, limit)?;
996 }
997 }
998 if let Some(withdrawals) = &block.withdrawals {
999 observed = observed.saturating_add(
1000 std::mem::size_of::<hypersync_client::format::Withdrawal>()
1001 .saturating_mul(withdrawals.capacity()),
1002 );
1003 check_dynamic_bytes(observed, limit)?;
1004 for withdrawal in withdrawals {
1005 add_bytes!(withdrawal.index);
1006 add_bytes!(withdrawal.validator_index);
1007 add_bytes!(withdrawal.address);
1008 add_bytes!(withdrawal.amount);
1009 }
1010 }
1011 }
1012 for log in &page.logs {
1013 add_bytes!(log.transaction_hash);
1014 add_bytes!(log.block_hash);
1015 add_bytes!(log.address);
1016 add_bytes!(log.data);
1017 for topic in &log.topics {
1018 add_bytes!(topic);
1019 }
1020 }
1021 if let Some(guard) = &page.rollback_guard {
1022 observed = observed
1023 .saturating_add(guard.hash.as_ref().len())
1024 .saturating_add(guard.first_parent_hash.as_ref().len());
1025 check_dynamic_bytes(observed, limit)?;
1026 }
1027 Ok(())
1028}
1029
1030fn check_dynamic_bytes(observed: usize, limit: usize) -> Result<(), SourceEngineError> {
1031 if observed > limit {
1032 return Err(SourceEngineError::ResponseLimitExceeded {
1033 resource: "dynamic bytes",
1034 observed,
1035 limit,
1036 });
1037 }
1038 Ok(())
1039}
1040
1041fn rollback_guard_at(block: &BlockRef) -> Result<RollbackGuard, SourceEngineError> {
1042 let hash: [u8; 32] =
1043 block
1044 .hash
1045 .as_slice()
1046 .try_into()
1047 .map_err(|_| CanonicalError::InvalidHashWidth {
1048 field: "hash",
1049 width: block.hash.len(),
1050 })?;
1051 let parent_hash: [u8; 32] =
1052 block
1053 .parent_hash
1054 .as_slice()
1055 .try_into()
1056 .map_err(|_| CanonicalError::InvalidHashWidth {
1057 field: "parent_hash",
1058 width: block.parent_hash.len(),
1059 })?;
1060 Ok(RollbackGuard {
1061 block_number: block.number,
1062 timestamp: i64::try_from(block.timestamp)
1063 .map_err(|_| SourceEngineError::BlockTimestampOverflow(block.timestamp))?,
1064 hash: Hash::from(hash),
1065 first_block_number: block.number,
1066 first_parent_hash: Hash::from(parent_hash),
1067 })
1068}
1069
1070fn validate_resume_state(
1071 canonical: &CanonicalTracker,
1072 next_block: u64,
1073 provider_checkpoint: Option<RollbackGuard>,
1074) -> Result<Option<RollbackGuard>, SourceEngineError> {
1075 if provider_checkpoint
1076 .as_ref()
1077 .is_some_and(|guard| guard.first_block_number > guard.block_number)
1078 {
1079 return Err(SourceEngineError::ResumeGuardMismatch("first_block_number"));
1080 }
1081 let Some(tip) = canonical.tip() else {
1082 if let Some(guard) = provider_checkpoint {
1083 if guard.timestamp < 0 {
1084 return Err(SourceEngineError::ResumeGuardMismatch("timestamp"));
1085 }
1086 let expected = guard
1087 .block_number
1088 .checked_add(1)
1089 .ok_or(SourceEngineError::BlockNumberOverflow)?;
1090 if next_block != expected {
1091 return Err(SourceEngineError::ResumeCursorMismatch {
1092 expected,
1093 received: next_block,
1094 });
1095 }
1096 return Ok(Some(guard));
1097 }
1098 return Ok(None);
1099 };
1100
1101 let expected = tip
1102 .number
1103 .checked_add(1)
1104 .ok_or(SourceEngineError::BlockNumberOverflow)?;
1105 if next_block != expected {
1106 return Err(SourceEngineError::ResumeCursorMismatch {
1107 expected,
1108 received: next_block,
1109 });
1110 }
1111 let Some(guard) = provider_checkpoint else {
1112 return rollback_guard_at(tip).map(Some);
1113 };
1114 if guard.block_number != tip.number {
1115 return Err(SourceEngineError::ResumeGuardMismatch("block_number"));
1116 }
1117 if guard.hash.as_ref() != tip.hash {
1118 return Err(SourceEngineError::ResumeGuardMismatch("hash"));
1119 }
1120 let timestamp = i64::try_from(tip.timestamp)
1121 .map_err(|_| SourceEngineError::BlockTimestampOverflow(tip.timestamp))?;
1122 if guard.timestamp != timestamp {
1123 return Err(SourceEngineError::ResumeGuardMismatch("timestamp"));
1124 }
1125 Ok(Some(guard))
1126}
1127
1128type PreparedPage = (
1129 Delivery,
1130 Option<RollbackGuard>,
1131 CanonicalTracker,
1132 Option<ReorgDelta>,
1133);
1134
1135#[derive(Clone, Copy)]
1136struct QueryLimits {
1137 max_blocks: usize,
1138 max_logs: usize,
1139}
1140
1141impl QueryLimits {
1142 fn for_range(from_block: u64, to_block_excl: u64) -> Self {
1143 let span = to_block_excl.saturating_sub(from_block);
1144 let max_blocks = usize::try_from(span)
1145 .unwrap_or(MAX_BLOCKS_PER_QUERY)
1146 .clamp(1, MAX_BLOCKS_PER_QUERY);
1147 Self {
1148 max_blocks,
1149 max_logs: MAX_LOGS_PER_QUERY,
1150 }
1151 }
1152
1153 fn shrink(&mut self) -> bool {
1154 if self.max_blocks == 1 && self.max_logs == 1 {
1155 return false;
1156 }
1157 self.max_blocks = self.max_blocks.div_ceil(2).max(1);
1158 self.max_logs = self.max_logs.div_ceil(2).max(1);
1159 true
1160 }
1161}
1162
1163fn set_delivery_sequence(delivery: &mut Delivery, sequence: u64) -> Result<(), SourceEngineError> {
1164 delivery.sequence = sequence;
1165 delivery.delivery_token = sequence.to_be_bytes().to_vec();
1166 delivery
1167 .cursor
1168 .as_mut()
1169 .ok_or(SourceEngineError::MissingCursor)?
1170 .batch_sequence = sequence;
1171 Ok(())
1172}
1173
1174#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
1176#[non_exhaustive]
1177pub enum SourceError {
1178 #[error("chain data source request failed: {0}")]
1184 Request(String),
1185 #[error("chain data source archive height is unavailable")]
1187 UnavailableHeight,
1188 #[error("chain data source request timed out after {millis}ms")]
1190 RequestTimeout {
1191 millis: u128,
1193 },
1194 #[error("chain data source request timeout must be greater than zero")]
1196 InvalidRequestTimeout,
1197 #[error("managed source resident-session limit must be greater than zero")]
1199 InvalidSessionLimit,
1200 #[error("managed source reorg depth must be greater than zero")]
1202 InvalidReorgDepth,
1203 #[error("source delivery size limit {requested} must be within 1..={maximum} bytes")]
1205 InvalidDeliverySizeLimit {
1206 requested: usize,
1208 maximum: usize,
1210 },
1211 #[error("source response limit for {resource} must be greater than zero")]
1213 InvalidResponseLimit {
1214 resource: &'static str,
1216 },
1217}
1218
1219impl SourceError {
1220 pub fn request(message: impl Into<String>) -> Self {
1226 Self::Request(message.into())
1227 }
1228
1229 pub const fn unavailable_height() -> Self {
1231 Self::UnavailableHeight
1232 }
1233
1234 pub fn request_timeout(timeout: std::time::Duration) -> Self {
1236 Self::RequestTimeout {
1237 millis: timeout.as_millis(),
1238 }
1239 }
1240}
1241
1242#[derive(Debug, thiserror::Error)]
1244#[non_exhaustive]
1245pub enum SourceEngineError {
1246 #[error(transparent)]
1248 QueryPlan(#[from] QueryPlanError),
1249 #[error(transparent)]
1251 Source(#[from] SourceError),
1252 #[error(transparent)]
1254 Normalize(#[from] NormalizeError),
1255 #[error(transparent)]
1257 InvalidPage(#[from] SourcePageError),
1258 #[error(transparent)]
1260 Canonical(#[from] CanonicalError),
1261 #[error("source page made no progress from {from_block}: next_block={next_block}")]
1263 NoProgress {
1264 from_block: u64,
1266 next_block: u64,
1268 },
1269 #[error("no delivery is awaiting acknowledgement")]
1271 NoPendingDelivery,
1272 #[error("delivery token does not match the in-flight batch")]
1274 DeliveryTokenMismatch,
1275 #[error("delivered batch is missing its cursor")]
1277 MissingCursor,
1278 #[error("rollback recovery is missing its previous continuity guard")]
1280 MissingRollbackGuard,
1281 #[error(
1283 "owner catch-up fork before activation block {activation_block} cannot be emitted as a global reorg (common ancestor {common_ancestor}, old tip {old_tip}, new tip {new_tip})"
1284 )]
1285 OwnerCatchupReorg {
1286 activation_block: u64,
1288 common_ancestor: u64,
1290 old_tip: u64,
1292 new_tip: u64,
1294 },
1295 #[error("cannot acknowledge an external control while a source delivery is pending")]
1297 PendingDelivery,
1298 #[error("delivery sequence regressed from {committed} to {received}")]
1300 SequenceRegression {
1301 committed: u64,
1303 received: u64,
1305 },
1306 #[error("resume cursor is {received}, expected canonical successor {expected}")]
1308 ResumeCursorMismatch {
1309 expected: u64,
1311 received: u64,
1313 },
1314 #[error("resume provider guard conflicts with canonical `{0}`")]
1316 ResumeGuardMismatch(&'static str),
1317 #[error(
1319 "resume scan cursor is {received}, beyond preserved coverage successor {coverage_successor}"
1320 )]
1321 CoverageCursorMismatch {
1322 coverage_successor: u64,
1324 received: u64,
1326 },
1327 #[error("rescanned canonical identity conflicts with preserved coverage at block {number}")]
1329 CoverageBoundaryConflict {
1330 number: u64,
1332 },
1333 #[error("delivery sequence is exhausted")]
1335 SequenceExhausted,
1336 #[error("canonical block number cannot advance beyond u64::MAX")]
1338 BlockNumberOverflow,
1339 #[error("canonical block timestamp {0} does not fit in i64")]
1341 BlockTimestampOverflow(u64),
1342 #[error("delivery size limit {requested} must be within 1..={maximum} bytes")]
1344 InvalidDeliverySizeLimit {
1345 requested: usize,
1347 maximum: usize,
1349 },
1350 #[error("encoded delivery is {encoded_len} bytes, exceeding the {limit}-byte limit")]
1352 DeliveryTooLarge {
1353 encoded_len: usize,
1355 limit: usize,
1357 },
1358 #[error(
1360 "provider response contains {observed} {resource}, exceeding the hard limit of {limit}"
1361 )]
1362 ResponseLimitExceeded {
1363 resource: &'static str,
1365 observed: usize,
1367 limit: usize,
1369 },
1370}