Skip to main content

evm_fork_cache_hypersync/
query_plan.rs

1use std::collections::BTreeMap;
2
3use evm_fork_cache_event_protocol::v1::{ApplyDesiredState, portable_interest};
4use hypersync_client::net_types::{BlockField, LogField, LogFilter, Query};
5
6/// Bound one provider response so catch-up remains resumable and deliverable over gRPC.
7pub const MAX_BLOCKS_PER_QUERY: usize = 1_000;
8/// Bound high-density log responses rather than relying only on a block span.
9pub const MAX_LOGS_PER_QUERY: usize = 5_000;
10/// Maximum number of distinct provider-side log filters compiled for one revision.
11pub const MAX_COMPILED_LOG_FILTERS: usize = 4_096;
12
13type CanonicalLogFilter = (Vec<Vec<u8>>, Vec<Vec<Vec<u8>>>);
14
15/// Compile one committed desired state into a bounded HyperSync query.
16///
17/// # Errors
18///
19/// Returns [`QueryPlanError`] for an empty/backward range, invalid address or
20/// topic widths, more than four topic positions, too many distinct compiled
21/// filters, or a filter rejected by the HyperSync query builder.
22pub fn compile_query(
23    desired_state: &ApplyDesiredState,
24    from_block: u64,
25    to_block_excl: Option<u64>,
26) -> Result<Query, QueryPlanError> {
27    compile_query_with_limits(
28        desired_state,
29        from_block,
30        to_block_excl,
31        MAX_BLOCKS_PER_QUERY,
32        MAX_LOGS_PER_QUERY,
33    )
34}
35
36pub(crate) fn compile_query_with_limits(
37    desired_state: &ApplyDesiredState,
38    from_block: u64,
39    to_block_excl: Option<u64>,
40    max_blocks: usize,
41    max_logs: usize,
42) -> Result<Query, QueryPlanError> {
43    if let Some(to_block_excl) = to_block_excl
44        && to_block_excl <= from_block
45    {
46        return Err(QueryPlanError::InvalidRange {
47            from_block,
48            to_block_excl,
49        });
50    }
51    let mut canonical_filters = BTreeMap::new();
52    let mut filter_limit_exceeded = false;
53    let mut match_all = false;
54    let mut explicit_headers = false;
55
56    for owner in &desired_state.owners {
57        for interest in &owner.interests {
58            match interest.kind.as_ref() {
59                Some(portable_interest::Kind::Log(log)) => {
60                    if log.topics.len() > 4 {
61                        return Err(QueryPlanError::TooManyTopicPositions {
62                            owner_id: owner.owner_id.clone(),
63                            positions: log.topics.len(),
64                        });
65                    }
66                    validate_log_filter(&owner.owner_id, &log.addresses, &log.topics)?;
67                    let key = canonical_log_filter(log.addresses.clone(), &log.topics);
68                    if key.0.is_empty() && key.1.is_empty() {
69                        match_all = true;
70                        canonical_filters.clear();
71                        canonical_filters.insert(key, owner.owner_id.clone());
72                    } else if !match_all && !canonical_filters.contains_key(&key) {
73                        if canonical_filters.len() == MAX_COMPILED_LOG_FILTERS {
74                            filter_limit_exceeded = true;
75                        } else {
76                            canonical_filters.insert(key, owner.owner_id.clone());
77                        }
78                    }
79                }
80                Some(portable_interest::Kind::Block(_)) => explicit_headers = true,
81                None => {}
82            }
83        }
84    }
85
86    if filter_limit_exceeded && !match_all {
87        return Err(QueryPlanError::TooManyCompiledLogFilters {
88            limit: MAX_COMPILED_LOG_FILTERS,
89        });
90    }
91    let filters = canonical_filters
92        .into_iter()
93        .map(|((addresses, topics), owner_id)| {
94            let mut filter = LogFilter::all();
95            if !addresses.is_empty() {
96                filter = filter.and_address(addresses).map_err(|error| {
97                    QueryPlanError::InvalidLogFilter {
98                        owner_id: owner_id.clone(),
99                        message: error.to_string(),
100                    }
101                })?;
102            }
103            for (index, values) in topics.into_iter().enumerate() {
104                if values.is_empty() {
105                    continue;
106                }
107                let result = match index {
108                    0 => filter.and_topic0(values),
109                    1 => filter.and_topic1(values),
110                    2 => filter.and_topic2(values),
111                    3 => filter.and_topic3(values),
112                    _ => unreachable!("canonicalized topics are bounded above"),
113                };
114                filter = result.map_err(|error| QueryPlanError::InvalidLogFilter {
115                    owner_id: owner_id.clone(),
116                    message: error.to_string(),
117                })?;
118            }
119            Ok(filter)
120        })
121        .collect::<Result<Vec<_>, QueryPlanError>>()?;
122
123    let mut query = Query::new()
124        .from_block(from_block)
125        .include_all_blocks()
126        .select_log_fields(LogField::all());
127    query.max_num_blocks = Some(max_blocks.max(1));
128    query.max_num_logs = Some(max_logs.max(1));
129    if let Some(to_block_excl) = to_block_excl {
130        query = query.to_block_excl(to_block_excl);
131    }
132    query.logs = filters.into_iter().map(Into::into).collect();
133    query = if explicit_headers {
134        query.select_block_fields(BlockField::all())
135    } else {
136        query.select_block_fields([
137            BlockField::Number,
138            BlockField::Hash,
139            BlockField::ParentHash,
140            BlockField::Timestamp,
141        ])
142    };
143    Ok(query)
144}
145
146fn validate_log_filter(
147    owner_id: &str,
148    addresses: &[Vec<u8>],
149    topics: &[evm_fork_cache_event_protocol::v1::TopicValues],
150) -> Result<(), QueryPlanError> {
151    if let Some(address) = addresses.iter().find(|address| address.len() != 20) {
152        return Err(QueryPlanError::InvalidLogFilter {
153            owner_id: owner_id.to_owned(),
154            message: format!("address must be 20 bytes, got {}", address.len()),
155        });
156    }
157    if let Some(topic) = topics
158        .iter()
159        .flat_map(|position| &position.values)
160        .find(|topic| topic.len() != 32)
161    {
162        return Err(QueryPlanError::InvalidLogFilter {
163            owner_id: owner_id.to_owned(),
164            message: format!("topic must be 32 bytes, got {}", topic.len()),
165        });
166    }
167    Ok(())
168}
169
170fn canonical_log_filter(
171    mut addresses: Vec<Vec<u8>>,
172    topics: &[evm_fork_cache_event_protocol::v1::TopicValues],
173) -> CanonicalLogFilter {
174    addresses.sort();
175    addresses.dedup();
176    let mut topics: Vec<Vec<Vec<u8>>> = topics
177        .iter()
178        .map(|values| {
179            let mut values = values.values.clone();
180            values.sort();
181            values.dedup();
182            values
183        })
184        .collect();
185    while topics.last().is_some_and(Vec::is_empty) {
186        topics.pop();
187    }
188    (addresses, topics)
189}
190
191/// Failure compiling portable interests into a HyperSync query.
192#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
193#[non_exhaustive]
194pub enum QueryPlanError {
195    /// A bounded range was empty or moved backwards.
196    #[error("invalid query range {from_block}..{to_block_excl}")]
197    InvalidRange {
198        /// Inclusive query start.
199        from_block: u64,
200        /// Exclusive query end.
201        to_block_excl: u64,
202    },
203    /// A portable address or topic had an invalid byte width.
204    #[error("owner `{owner_id}` has an invalid log filter: {message}")]
205    InvalidLogFilter {
206        /// Owner that supplied the filter.
207        owner_id: String,
208        /// Conversion failure.
209        message: String,
210    },
211    /// HyperSync supports at most four indexed topic positions.
212    #[error("owner `{owner_id}` supplied {positions} topic positions; at most 4 are supported")]
213    TooManyTopicPositions {
214        /// Owner that supplied the filter.
215        owner_id: String,
216        /// Number of supplied positions.
217        positions: usize,
218    },
219    /// The desired state expands to more distinct provider filters than allowed.
220    #[error("desired state exceeds the provider limit of {limit} distinct log filters")]
221    TooManyCompiledLogFilters {
222        /// Maximum distinct filters accepted by this adapter.
223        limit: usize,
224    },
225}