evm_fork_cache_hypersync/
query_plan.rs1use std::collections::BTreeMap;
2
3use evm_fork_cache_event_protocol::v1::{ApplyDesiredState, portable_interest};
4use hypersync_client::net_types::{BlockField, LogField, LogFilter, Query};
5
6pub const MAX_BLOCKS_PER_QUERY: usize = 1_000;
8pub const MAX_LOGS_PER_QUERY: usize = 5_000;
10pub const MAX_COMPILED_LOG_FILTERS: usize = 4_096;
12
13type CanonicalLogFilter = (Vec<Vec<u8>>, Vec<Vec<Vec<u8>>>);
14
15pub 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#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
193#[non_exhaustive]
194pub enum QueryPlanError {
195 #[error("invalid query range {from_block}..{to_block_excl}")]
197 InvalidRange {
198 from_block: u64,
200 to_block_excl: u64,
202 },
203 #[error("owner `{owner_id}` has an invalid log filter: {message}")]
205 InvalidLogFilter {
206 owner_id: String,
208 message: String,
210 },
211 #[error("owner `{owner_id}` supplied {positions} topic positions; at most 4 are supported")]
213 TooManyTopicPositions {
214 owner_id: String,
216 positions: usize,
218 },
219 #[error("desired state exceeds the provider limit of {limit} distinct log filters")]
221 TooManyCompiledLogFilters {
222 limit: usize,
224 },
225}