1use std::collections::{HashMap, HashSet};
2
3use hypersync_client::simple_types::Log;
4
5use crate::SourcePage;
6
7pub(crate) fn validate_source_page(
9 page: &SourcePage,
10 from_block: u64,
11 to_block_excl: u64,
12) -> Result<(), SourcePageError> {
13 if page.next_block > to_block_excl {
14 return Err(SourcePageError::CursorBeyondTarget {
15 next_block: page.next_block,
16 to_block_excl,
17 });
18 }
19 if let Some(archive_height) = page.archive_height
20 && archive_height < page.next_block
21 {
22 return Err(SourcePageError::ArchiveBehindCursor {
23 archive_height,
24 next_block: page.next_block,
25 });
26 }
27
28 let mut expected_number = from_block;
29 let mut previous_hash: Option<&[u8]> = None;
30 let mut block_hashes = Vec::with_capacity(page.blocks.len());
31 for block in &page.blocks {
32 let number = block
33 .number
34 .ok_or(SourcePageError::MissingField("block.number"))?;
35 if number != expected_number {
36 return Err(SourcePageError::NonContiguousBlock {
37 expected: expected_number,
38 received: number,
39 });
40 }
41 let hash = required_width(block.hash.as_ref(), "block.hash", 32)?;
42 let parent_hash = required_width(block.parent_hash.as_ref(), "block.parent_hash", 32)?;
43 if let Some(previous_hash) = previous_hash
44 && parent_hash != previous_hash
45 {
46 return Err(SourcePageError::ParentHashMismatch { number });
47 }
48 let timestamp = block
49 .timestamp
50 .as_ref()
51 .ok_or(SourcePageError::MissingField("block.timestamp"))?;
52 if timestamp.as_ref().len() > 8 {
53 return Err(SourcePageError::QuantityOverflow("block.timestamp"));
54 }
55 block_hashes.push((number, hash.to_vec()));
56 previous_hash = Some(hash);
57 expected_number = expected_number
58 .checked_add(1)
59 .ok_or(SourcePageError::BlockNumberOverflow)?;
60 }
61 if expected_number != page.next_block {
62 return Err(SourcePageError::IncompleteBlockRange {
63 expected_next_block: expected_number,
64 next_block: page.next_block,
65 });
66 }
67 if let Some(guard) = &page.rollback_guard {
68 validate_rollback_guard(guard, &page.blocks)?;
69 }
70
71 let mut log_identities = HashSet::with_capacity(page.logs.len());
72 let mut transaction_indexes = HashMap::new();
73 let mut transaction_hashes = HashMap::new();
74 for log in &page.logs {
75 validate_log(log, from_block, page.next_block, &block_hashes)?;
76 let block_hash = required_width(log.block_hash.as_ref(), "log.block_hash", 32)?;
77 let transaction_hash =
78 required_width(log.transaction_hash.as_ref(), "log.transaction_hash", 32)?;
79 let transaction_index = log
80 .transaction_index
81 .map(u64::from)
82 .ok_or(SourcePageError::MissingField("log.transaction_index"))?;
83 let log_index = log
84 .log_index
85 .map(u64::from)
86 .ok_or(SourcePageError::MissingField("log.log_index"))?;
87 if !log_identities.insert((block_hash.to_vec(), log_index)) {
88 return Err(SourcePageError::DuplicateLog { log_index });
89 }
90 if transaction_indexes
91 .insert(
92 (block_hash.to_vec(), transaction_hash.to_vec()),
93 transaction_index,
94 )
95 .is_some_and(|known| known != transaction_index)
96 || transaction_hashes
97 .insert(
98 (block_hash.to_vec(), transaction_index),
99 transaction_hash.to_vec(),
100 )
101 .is_some_and(|known| known.as_slice() != transaction_hash)
102 {
103 return Err(SourcePageError::TransactionIdentityConflict {
104 block_number: log
105 .block_number
106 .map(u64::from)
107 .expect("validated log block number"),
108 });
109 }
110 }
111 Ok(())
112}
113
114fn validate_rollback_guard(
115 guard: &hypersync_client::net_types::RollbackGuard,
116 blocks: &[hypersync_client::simple_types::Block],
117) -> Result<(), SourcePageError> {
118 let first = blocks
119 .first()
120 .ok_or(SourcePageError::MissingRollbackGuardRange)?;
121 let last = blocks
122 .last()
123 .ok_or(SourcePageError::MissingRollbackGuardRange)?;
124 let first_number = first
125 .number
126 .ok_or(SourcePageError::MissingField("block.number"))?;
127 let last_number = last
128 .number
129 .ok_or(SourcePageError::MissingField("block.number"))?;
130 if guard.first_block_number != first_number {
131 return Err(SourcePageError::RollbackGuardStartMismatch {
132 expected: first_number,
133 received: guard.first_block_number,
134 });
135 }
136 if guard.block_number != last_number {
137 return Err(SourcePageError::RollbackGuardTipMismatch {
138 expected: last_number,
139 received: guard.block_number,
140 });
141 }
142 let first_parent = required_width(first.parent_hash.as_ref(), "block.parent_hash", 32)?;
143 if guard.first_parent_hash.as_ref() != first_parent {
144 return Err(SourcePageError::RollbackGuardParentMismatch {
145 number: first_number,
146 });
147 }
148 let last_hash = required_width(last.hash.as_ref(), "block.hash", 32)?;
149 if guard.hash.as_ref() != last_hash {
150 return Err(SourcePageError::RollbackGuardHashMismatch {
151 number: last_number,
152 });
153 }
154 let timestamp = quantity_u64(
155 last.timestamp
156 .as_ref()
157 .ok_or(SourcePageError::MissingField("block.timestamp"))?,
158 "block.timestamp",
159 )?;
160 let timestamp = i64::try_from(timestamp).map_err(|_| {
161 SourcePageError::RollbackGuardTimestampOutOfRange {
162 number: last_number,
163 }
164 })?;
165 if guard.timestamp != timestamp {
166 return Err(SourcePageError::RollbackGuardTimestampMismatch {
167 number: last_number,
168 });
169 }
170 Ok(())
171}
172
173fn validate_log(
174 log: &Log,
175 from_block: u64,
176 next_block: u64,
177 block_hashes: &[(u64, Vec<u8>)],
178) -> Result<(), SourcePageError> {
179 let block_number = log
180 .block_number
181 .map(u64::from)
182 .ok_or(SourcePageError::MissingField("log.block_number"))?;
183 if block_number < from_block || block_number >= next_block {
184 return Err(SourcePageError::LogOutsidePage {
185 block_number,
186 from_block,
187 next_block,
188 });
189 }
190 let block_hash = required_width(log.block_hash.as_ref(), "log.block_hash", 32)?;
191 let expected_hash = block_hashes
192 .get((block_number - from_block) as usize)
193 .filter(|(number, _)| *number == block_number)
194 .map(|(_, hash)| hash.as_slice())
195 .ok_or(SourcePageError::LogWithoutBlock { block_number })?;
196 if block_hash != expected_hash {
197 return Err(SourcePageError::LogBlockHashMismatch { block_number });
198 }
199 let removed = log
200 .removed
201 .ok_or(SourcePageError::MissingField("log.removed"))?;
202 if removed {
203 return Err(SourcePageError::RemovedLogInCanonicalPage { block_number });
204 }
205 required_width(log.address.as_ref(), "log.address", 20)?;
206 required_width(log.transaction_hash.as_ref(), "log.transaction_hash", 32)?;
207 log.data
208 .as_ref()
209 .ok_or(SourcePageError::MissingField("log.data"))?;
210 if log.topics.len() > 4 {
211 return Err(SourcePageError::TooManyLogTopics {
212 received: log.topics.len(),
213 });
214 }
215 let mut saw_missing_topic = false;
216 for topic in &log.topics {
217 match topic.as_ref() {
218 Some(_) if saw_missing_topic => {
219 return Err(SourcePageError::NonContiguousLogTopics);
220 }
221 Some(topic) => {
222 required_width(Some(topic), "log.topic", 32)?;
223 }
224 None => saw_missing_topic = true,
225 }
226 }
227 log.transaction_index
228 .ok_or(SourcePageError::MissingField("log.transaction_index"))?;
229 log.log_index
230 .ok_or(SourcePageError::MissingField("log.log_index"))?;
231 Ok(())
232}
233
234fn quantity_u64(
235 value: &hypersync_client::format::Quantity,
236 field: &'static str,
237) -> Result<u64, SourcePageError> {
238 let bytes = value.as_ref();
239 if bytes.len() > 8 {
240 return Err(SourcePageError::QuantityOverflow(field));
241 }
242 let mut buffer = [0_u8; 8];
243 buffer[8 - bytes.len()..].copy_from_slice(bytes);
244 Ok(u64::from_be_bytes(buffer))
245}
246
247fn required_width<'a, T: AsRef<[u8]>>(
248 value: Option<&'a T>,
249 field: &'static str,
250 expected: usize,
251) -> Result<&'a [u8], SourcePageError> {
252 let value = value.ok_or(SourcePageError::MissingField(field))?.as_ref();
253 if value.len() != expected {
254 return Err(SourcePageError::InvalidWidth {
255 field,
256 expected,
257 received: value.len(),
258 });
259 }
260 Ok(value)
261}
262
263#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
265#[non_exhaustive]
266pub enum SourcePageError {
267 #[error("source cursor {next_block} exceeds requested target {to_block_excl}")]
269 CursorBeyondTarget {
270 next_block: u64,
272 to_block_excl: u64,
274 },
275 #[error("archive height {archive_height} is behind returned cursor {next_block}")]
277 ArchiveBehindCursor {
278 archive_height: u64,
280 next_block: u64,
282 },
283 #[error("source page is missing required field `{0}`")]
285 MissingField(&'static str),
286 #[error("source field `{field}` must be {expected} bytes, got {received}")]
288 InvalidWidth {
289 field: &'static str,
291 expected: usize,
293 received: usize,
295 },
296 #[error("source block range is not contiguous: expected {expected}, received {received}")]
298 NonContiguousBlock {
299 expected: u64,
301 received: u64,
303 },
304 #[error("block {number} does not reference the preceding returned block")]
306 ParentHashMismatch {
307 number: u64,
309 },
310 #[error("source header coverage ends at {expected_next_block}, but cursor is {next_block}")]
312 IncompleteBlockRange {
313 expected_next_block: u64,
315 next_block: u64,
317 },
318 #[error("source rollback guard is present without returned blocks")]
320 MissingRollbackGuardRange,
321 #[error("rollback guard starts at {received}, expected {expected}")]
323 RollbackGuardStartMismatch {
324 expected: u64,
326 received: u64,
328 },
329 #[error("rollback guard ends at {received}, expected {expected}")]
331 RollbackGuardTipMismatch {
332 expected: u64,
334 received: u64,
336 },
337 #[error("rollback guard parent does not match the first returned block {number}")]
339 RollbackGuardParentMismatch {
340 number: u64,
342 },
343 #[error("rollback guard hash does not match the final returned block {number}")]
345 RollbackGuardHashMismatch {
346 number: u64,
348 },
349 #[error("rollback guard timestamp does not match the final returned block {number}")]
351 RollbackGuardTimestampMismatch {
352 number: u64,
354 },
355 #[error("block {number} timestamp does not fit the rollback guard")]
357 RollbackGuardTimestampOutOfRange {
358 number: u64,
360 },
361 #[error("log block {block_number} is outside page {from_block}..{next_block}")]
363 LogOutsidePage {
364 block_number: u64,
366 from_block: u64,
368 next_block: u64,
370 },
371 #[error("log block {block_number} has no corresponding header")]
373 LogWithoutBlock {
374 block_number: u64,
376 },
377 #[error("log block hash does not match header at block {block_number}")]
379 LogBlockHashMismatch {
380 block_number: u64,
382 },
383 #[error("removed log at block {block_number} contradicts the canonical historical page")]
385 RemovedLogInCanonicalPage {
386 block_number: u64,
388 },
389 #[error("source page contains duplicate log identity at log index {log_index}")]
391 DuplicateLog {
392 log_index: u64,
394 },
395 #[error("source logs conflict on transaction identity in block {block_number}")]
397 TransactionIdentityConflict {
398 block_number: u64,
400 },
401 #[error("source log contains {received} topics; EVM logs support at most 4")]
403 TooManyLogTopics {
404 received: usize,
406 },
407 #[error("source log topics are not a contiguous prefix")]
409 NonContiguousLogTopics,
410 #[error("source quantity `{0}` does not fit in u64")]
412 QuantityOverflow(&'static str),
413 #[error("source block number cannot advance beyond u64::MAX")]
415 BlockNumberOverflow,
416}
417
418#[cfg(test)]
419mod tests {
420 use hypersync_client::{
421 format::{Address, Data, Hash, Quantity},
422 simple_types::{Block, Log},
423 };
424
425 use super::*;
426
427 fn block() -> Block {
428 Block {
429 number: Some(100),
430 hash: Some(Hash::from([0x10; 32])),
431 parent_hash: Some(Hash::from([0x0f; 32])),
432 timestamp: Some(Quantity::from(100_u64)),
433 ..Default::default()
434 }
435 }
436
437 fn log(transaction_hash: u8, transaction_index: u64, log_index: u64) -> Log {
438 Log {
439 removed: Some(false),
440 log_index: Some(log_index.into()),
441 transaction_index: Some(transaction_index.into()),
442 transaction_hash: Some(Hash::from([transaction_hash; 32])),
443 block_hash: Some(Hash::from([0x10; 32])),
444 block_number: Some(100_u64.into()),
445 address: Some(Address::from([0x33; 20])),
446 data: Some(Data::from(Vec::new())),
447 ..Default::default()
448 }
449 }
450
451 fn page(logs: Vec<Log>) -> SourcePage {
452 SourcePage::new(101, vec![block()], logs).with_archive_height(Some(101))
453 }
454
455 #[test]
456 fn source_page_rejects_ambiguous_log_and_transaction_identities() {
457 assert!(matches!(
458 validate_source_page(&page(vec![log(0x20, 0, 0), log(0x20, 1, 1)]), 100, 101),
459 Err(SourcePageError::TransactionIdentityConflict { block_number: 100 })
460 ));
461 assert!(matches!(
462 validate_source_page(&page(vec![log(0x20, 0, 0), log(0x21, 0, 1)]), 100, 101),
463 Err(SourcePageError::TransactionIdentityConflict { block_number: 100 })
464 ));
465 assert!(matches!(
466 validate_source_page(&page(vec![log(0x20, 0, 0), log(0x21, 1, 0)]), 100, 101),
467 Err(SourcePageError::DuplicateLog { log_index: 0 })
468 ));
469 }
470
471 #[test]
472 fn source_page_rejects_removed_logs_from_a_canonical_page() {
473 let mut removed = log(0x20, 0, 0);
474 removed.removed = Some(true);
475 assert!(matches!(
476 validate_source_page(&page(vec![removed]), 100, 101),
477 Err(SourcePageError::RemovedLogInCanonicalPage { block_number: 100 })
478 ));
479 }
480}