Skip to main content

evm_fork_cache_hypersync/
page_validation.rs

1use std::collections::{HashMap, HashSet};
2
3use hypersync_client::simple_types::Log;
4
5use crate::SourcePage;
6
7/// Validate the provider page against the exact bounded query that produced it.
8pub(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/// A provider page violated the bounded, contiguous source contract.
264#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
265#[non_exhaustive]
266pub enum SourcePageError {
267    /// The provider advanced beyond the requested exclusive target.
268    #[error("source cursor {next_block} exceeds requested target {to_block_excl}")]
269    CursorBeyondTarget {
270        /// Returned exclusive cursor.
271        next_block: u64,
272        /// Requested exclusive target.
273        to_block_excl: u64,
274    },
275    /// The provider's advertised archive height cannot contain the returned page.
276    #[error("archive height {archive_height} is behind returned cursor {next_block}")]
277    ArchiveBehindCursor {
278        /// Provider archive height.
279        archive_height: u64,
280        /// Returned exclusive cursor.
281        next_block: u64,
282    },
283    /// A required canonical or log identity field was absent.
284    #[error("source page is missing required field `{0}`")]
285    MissingField(&'static str),
286    /// A fixed-width identity field had the wrong size.
287    #[error("source field `{field}` must be {expected} bytes, got {received}")]
288    InvalidWidth {
289        /// Field name.
290        field: &'static str,
291        /// Required width.
292        expected: usize,
293        /// Returned width.
294        received: usize,
295    },
296    /// A block number did not immediately follow the previous returned block.
297    #[error("source block range is not contiguous: expected {expected}, received {received}")]
298    NonContiguousBlock {
299        /// Required number.
300        expected: u64,
301        /// Returned number.
302        received: u64,
303    },
304    /// Adjacent returned blocks did not form one chain.
305    #[error("block {number} does not reference the preceding returned block")]
306    ParentHashMismatch {
307        /// Invalid block number.
308        number: u64,
309    },
310    /// The returned exclusive cursor did not match complete header coverage.
311    #[error("source header coverage ends at {expected_next_block}, but cursor is {next_block}")]
312    IncompleteBlockRange {
313        /// Cursor implied by the returned headers.
314        expected_next_block: u64,
315        /// Provider cursor.
316        next_block: u64,
317    },
318    /// A rollback guard was present without any returned block range to guard.
319    #[error("source rollback guard is present without returned blocks")]
320    MissingRollbackGuardRange,
321    /// The rollback guard did not start at the first returned block.
322    #[error("rollback guard starts at {received}, expected {expected}")]
323    RollbackGuardStartMismatch {
324        /// First returned block.
325        expected: u64,
326        /// Guard start.
327        received: u64,
328    },
329    /// The rollback guard did not end at the final returned block.
330    #[error("rollback guard ends at {received}, expected {expected}")]
331    RollbackGuardTipMismatch {
332        /// Last returned block.
333        expected: u64,
334        /// Guard tip.
335        received: u64,
336    },
337    /// The rollback guard did not preserve the first returned block's parent.
338    #[error("rollback guard parent does not match the first returned block {number}")]
339    RollbackGuardParentMismatch {
340        /// First returned block.
341        number: u64,
342    },
343    /// The rollback guard tip hash did not match the final returned block.
344    #[error("rollback guard hash does not match the final returned block {number}")]
345    RollbackGuardHashMismatch {
346        /// Final returned block.
347        number: u64,
348    },
349    /// The rollback guard timestamp did not match the final returned block.
350    #[error("rollback guard timestamp does not match the final returned block {number}")]
351    RollbackGuardTimestampMismatch {
352        /// Final returned block.
353        number: u64,
354    },
355    /// A block timestamp could not be represented by HyperSync's signed guard.
356    #[error("block {number} timestamp does not fit the rollback guard")]
357    RollbackGuardTimestampOutOfRange {
358        /// Final returned block.
359        number: u64,
360    },
361    /// A log was outside the page's proven canonical range.
362    #[error("log block {block_number} is outside page {from_block}..{next_block}")]
363    LogOutsidePage {
364        /// Log block.
365        block_number: u64,
366        /// Query start.
367        from_block: u64,
368        /// Page cursor.
369        next_block: u64,
370    },
371    /// A log did not have a corresponding returned header.
372    #[error("log block {block_number} has no corresponding header")]
373    LogWithoutBlock {
374        /// Log block.
375        block_number: u64,
376    },
377    /// A log claimed a hash other than its returned header.
378    #[error("log block hash does not match header at block {block_number}")]
379    LogBlockHashMismatch {
380        /// Log block.
381        block_number: u64,
382    },
383    /// A historical row claimed removal while matching the page's current canonical header.
384    #[error("removed log at block {block_number} contradicts the canonical historical page")]
385    RemovedLogInCanonicalPage {
386        /// Contradictory log block.
387        block_number: u64,
388    },
389    /// A stable log identity occurred more than once in the page.
390    #[error("source page contains duplicate log identity at log index {log_index}")]
391    DuplicateLog {
392        /// Duplicate log index.
393        log_index: u64,
394    },
395    /// Logs disagree on transaction hash/index identity within one block.
396    #[error("source logs conflict on transaction identity in block {block_number}")]
397    TransactionIdentityConflict {
398        /// Block containing the contradictory transaction identity.
399        block_number: u64,
400    },
401    /// An EVM log contained more than four indexed topics.
402    #[error("source log contains {received} topics; EVM logs support at most 4")]
403    TooManyLogTopics {
404        /// Returned topic count.
405        received: usize,
406    },
407    /// A later topic was present after an earlier topic position was absent.
408    #[error("source log topics are not a contiguous prefix")]
409    NonContiguousLogTopics,
410    /// A source quantity could not fit the protocol's fixed width.
411    #[error("source quantity `{0}` does not fit in u64")]
412    QuantityOverflow(&'static str),
413    /// Header iteration could not represent the following block.
414    #[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}