1use std::{
2 collections::{HashMap, HashSet},
3 sync::Arc,
4};
5
6use thiserror::Error;
7use tokio::sync::{mpsc::UnboundedReceiver, watch};
8use tycho_client::feed::{synchronizer::Snapshot, BlockHeader, FeedMessage};
9use tycho_common::{
10 models::{
11 blockchain::{Block, BlockAggregatedChanges, DCIUpdate, PendingBlock},
12 protocol::{ComponentBalance, ProtocolComponent, ProtocolComponentStateDelta},
13 Chain,
14 },
15 traits::TxDeltaIndexer,
16 Bytes,
17};
18
19use crate::{
20 evm::decoder::{StreamDecodeError, TychoStreamDecoder},
21 protocol::models::Update,
22};
23
24pub struct PendingUpdate {
30 pub label: String,
31 pub update: Update,
32}
33
34#[derive(Debug, Error)]
35pub enum PendingError {
36 #[error("parent block {needed} not yet confirmed (current: {current})")]
40 ParentNotYetConfirmed { needed: u64, current: u64 },
41 #[error("decoder error: {0}")]
42 Decoder(#[from] StreamDecodeError),
43 #[error("indexer error for extractor '{extractor}': {message}")]
44 Indexer { extractor: String, message: String },
45}
46
47pub struct PendingBlockProcessor {
82 indexers: HashMap<String, Box<dyn TxDeltaIndexer>>,
83 decoder: Arc<TychoStreamDecoder<BlockHeader>>,
84 chain: Chain,
85 current_confirmed_block: u64,
87 confirmed_block_tx: watch::Sender<u64>,
89 block_rx: UnboundedReceiver<FeedMessage<BlockHeader>>,
91}
92
93impl PendingBlockProcessor {
94 pub(crate) fn new(
95 indexers: HashMap<String, Box<dyn TxDeltaIndexer>>,
96 decoder: Arc<TychoStreamDecoder<BlockHeader>>,
97 chain: Chain,
98 block_rx: UnboundedReceiver<FeedMessage<BlockHeader>>,
99 ) -> Self {
100 let (confirmed_block_tx, _) = watch::channel(0u64);
101 Self { indexers, decoder, chain, current_confirmed_block: 0, confirmed_block_tx, block_rx }
102 }
103
104 pub fn subscribe_confirmed_block(&self) -> watch::Receiver<u64> {
110 self.confirmed_block_tx.subscribe()
111 }
112
113 pub fn current_confirmed_block(&self) -> u64 {
115 self.current_confirmed_block
116 }
117
118 pub fn advance(&mut self, msg: &FeedMessage<BlockHeader>) -> Result<(), PendingError> {
124 self.advance_inner(msg)
125 }
126
127 pub async fn generate_pending_update(
145 &mut self,
146 pending: &PendingBlock,
147 label: String,
148 ) -> Result<PendingUpdate, PendingError> {
149 while let Ok(msg) = self.block_rx.try_recv() {
151 self.advance_inner(&msg)?;
152 }
153
154 let target_block = pending.block();
155 let parent = target_block.number.saturating_sub(1);
156 if self.current_confirmed_block < parent {
157 return Err(PendingError::ParentNotYetConfirmed {
158 needed: parent,
159 current: self.current_confirmed_block,
160 });
161 }
162 let target_header = BlockHeader::from(target_block);
163
164 let mut pending_deltas: HashMap<String, BlockAggregatedChanges> = HashMap::new();
165 for (protocol_system, indexer) in &self.indexers {
166 let changes = indexer.generate_deltas(pending);
167 pending_deltas.insert(protocol_system.clone(), changes);
168 }
169
170 let update = self
171 .decoder
172 .apply_deltas_ephemeral(&pending_deltas, target_header)
173 .await?;
174 Ok(PendingUpdate { label, update })
175 }
176
177 fn advance_inner(&mut self, msg: &FeedMessage<BlockHeader>) -> Result<(), PendingError> {
178 let msg_block = msg
179 .state_msgs
180 .values()
181 .map(|s| s.header.number)
182 .max()
183 .unwrap_or(0);
184
185 for (extractor, state_msg) in &msg.state_msgs {
186 let Some(indexer) = self.indexers.get_mut(extractor) else {
187 continue;
188 };
189
190 if !state_msg.snapshots.states.is_empty() {
191 let block_changes = snapshot_to_block_changes(
192 extractor,
193 &state_msg.snapshots,
194 &state_msg.header,
195 self.chain,
196 )?;
197 indexer
198 .apply_block(&block_changes)
199 .map_err(|e| PendingError::Indexer {
200 extractor: extractor.clone(),
201 message: format!("{e:#}"),
202 })?;
203 }
204
205 if let Some(deltas) = &state_msg.deltas {
206 indexer
207 .apply_block(deltas)
208 .map_err(|e| PendingError::Indexer {
209 extractor: extractor.clone(),
210 message: format!("{e:#}"),
211 })?;
212 }
213 }
214
215 if msg_block > self.current_confirmed_block {
216 self.current_confirmed_block = msg_block;
217 #[expect(
218 clippy::let_underscore_must_use,
219 reason = "the confirmed-block receivers are optional; having none is normal"
220 )]
221 let _ = self.confirmed_block_tx.send(msg_block);
222 }
223 Ok(())
224 }
225}
226
227fn snapshot_to_block_changes(
233 extractor: &str,
234 snapshot: &Snapshot,
235 header: &BlockHeader,
236 chain: Chain,
237) -> Result<BlockAggregatedChanges, PendingError> {
238 let ts = i64::try_from(header.timestamp)
239 .ok()
240 .and_then(|secs| chrono::DateTime::from_timestamp(secs, 0))
241 .ok_or_else(|| PendingError::Indexer {
242 extractor: extractor.to_string(),
243 message: format!(
244 "block {} has an invalid timestamp {}",
245 header.number, header.timestamp
246 ),
247 })?
248 .naive_utc();
249 let block = Block {
250 number: header.number,
251 chain,
252 hash: header.hash.clone(),
253 parent_hash: header.parent_hash.clone(),
254 ts,
255 };
256
257 let mut new_protocol_components: HashMap<String, ProtocolComponent> = HashMap::new();
258 let mut state_deltas: HashMap<String, ProtocolComponentStateDelta> = HashMap::new();
259 let mut component_balances: HashMap<String, HashMap<Bytes, ComponentBalance>> = HashMap::new();
260 let mut dci_update = DCIUpdate::default();
261
262 for (id, comp_with_state) in &snapshot.states {
263 new_protocol_components.insert(id.clone(), comp_with_state.component.clone());
264
265 for (entrypoint, trace) in &comp_with_state.entrypoints {
266 let ep_id = entrypoint
267 .entry_point
268 .external_id
269 .clone();
270 dci_update
271 .new_entrypoints
272 .entry(id.clone())
273 .or_default()
274 .insert(entrypoint.entry_point.clone());
275 dci_update
276 .new_entrypoint_params
277 .entry(ep_id.clone())
278 .or_default()
279 .insert((entrypoint.params.clone(), id.clone()));
280 dci_update
281 .trace_results
282 .entry(ep_id)
283 .or_default()
284 .merge(trace.clone());
285 }
286
287 state_deltas.insert(
288 id.clone(),
289 ProtocolComponentStateDelta {
290 component_id: id.clone(),
291 updated_attributes: comp_with_state.state.attributes.clone(),
292 deleted_attributes: HashSet::new(),
293 created_attributes: HashSet::new(),
294 },
295 );
296
297 let token_balances: HashMap<Bytes, ComponentBalance> = comp_with_state
298 .state
299 .balances
300 .iter()
301 .map(|(token, balance)| {
302 (
303 token.clone(),
304 ComponentBalance {
305 token: token.clone(),
306 balance: balance.clone(),
307 balance_float: 0.0,
308 modify_tx: Bytes::default(),
309 component_id: id.clone(),
310 },
311 )
312 })
313 .collect();
314 component_balances.insert(id.clone(), token_balances);
315 }
316
317 Ok(BlockAggregatedChanges {
318 extractor: extractor.to_string(),
319 chain,
320 block,
321 finalized_block_height: header.number,
322 new_protocol_components,
323 state_deltas,
324 component_balances,
325 dci_update,
326 ..Default::default()
327 })
328}
329
330#[cfg(test)]
331mod tests {
332 use std::sync::Mutex;
333
334 use tycho_common::models::blockchain::{Block, PendingBlock};
335
336 use super::*;
337
338 struct RecordingIndexer {
340 seen: Arc<Mutex<Vec<Block>>>,
341 }
342
343 impl TxDeltaIndexer for RecordingIndexer {
344 fn apply_block(&mut self, _block: &BlockAggregatedChanges) -> anyhow::Result<()> {
345 Ok(())
346 }
347
348 fn generate_deltas(&self, pending: &PendingBlock) -> BlockAggregatedChanges {
349 self.seen
350 .lock()
351 .unwrap()
352 .push(pending.block().clone());
353 BlockAggregatedChanges::default()
354 }
355 }
356
357 fn target_block(number: u64, timestamp: i64) -> Block {
358 Block {
359 number,
360 chain: Chain::Ethereum,
361 hash: Bytes::from([1u8; 32]),
362 parent_hash: Bytes::from([2u8; 32]),
363 ts: chrono::DateTime::from_timestamp(timestamp, 0)
364 .unwrap()
365 .naive_utc(),
366 }
367 }
368
369 fn processor(seen: Arc<Mutex<Vec<Block>>>) -> PendingBlockProcessor {
370 let indexers: HashMap<String, Box<dyn TxDeltaIndexer>> =
371 HashMap::from([("fluid".to_string(), Box::new(RecordingIndexer { seen }) as _)]);
372 let (_tx, rx) = tokio::sync::mpsc::unbounded_channel();
373 PendingBlockProcessor::new(
374 indexers,
375 Arc::new(TychoStreamDecoder::<BlockHeader>::new(Chain::Ethereum)),
376 Chain::Ethereum,
377 rx,
378 )
379 }
380
381 #[test]
382 fn test_snapshot_entrypoints_land_in_dci_update() {
383 use tycho_client::feed::synchronizer::ComponentWithState;
384 use tycho_common::models::{
385 blockchain::{
386 EntryPoint, EntryPointWithTracingParams, RPCTracerParams, TracingParams,
387 TracingResult,
388 },
389 protocol::ProtocolComponentState,
390 };
391
392 let component_id = "0xpool".to_string();
393 let entry_point = EntryPoint {
394 external_id: "0xpool:get_virtual_price()".to_string(),
395 target: Bytes::from([0xaa; 20]),
396 signature: "get_virtual_price()".to_string(),
397 };
398 let params =
399 TracingParams::RPCTracer(RPCTracerParams::new(None, Bytes::from([0x12, 0x34])));
400 let oracle = Bytes::from([0xbb; 20]);
401 let trace = TracingResult::new(
402 HashSet::new(),
403 HashMap::from([(oracle.clone(), HashSet::from([Bytes::from([0u8; 32])]))]),
404 );
405 let snapshot = Snapshot {
406 states: HashMap::from([(
407 component_id.clone(),
408 ComponentWithState {
409 state: ProtocolComponentState::new(
410 &component_id,
411 HashMap::new(),
412 HashMap::new(),
413 ),
414 component: ProtocolComponent::default(),
415 component_tvl: None,
416 entrypoints: vec![(
417 EntryPointWithTracingParams::new(entry_point.clone(), params.clone()),
418 trace,
419 )],
420 },
421 )]),
422 vm_storage: HashMap::new(),
423 };
424 let header = BlockHeader { number: 7, ..Default::default() };
425
426 let changes =
427 snapshot_to_block_changes("vm:curve", &snapshot, &header, Chain::Ethereum).unwrap();
428
429 let dci = &changes.dci_update;
430 assert_eq!(dci.new_entrypoints[&component_id], HashSet::from([entry_point.clone()]));
431 assert_eq!(
432 dci.new_entrypoint_params[&entry_point.external_id],
433 HashSet::from([(params, component_id)])
434 );
435 assert!(dci.trace_results[&entry_point.external_id]
436 .accessed_slots
437 .contains_key(&oracle));
438 }
439
440 #[tokio::test]
441 async fn test_indexer_receives_the_callers_target_block() {
442 let seen = Arc::new(Mutex::new(Vec::new()));
443 let mut pending_processor = processor(seen.clone());
444 let block = target_block(1, 1_759_842_947);
446
447 pending_processor
448 .generate_pending_update(
449 &PendingBlock::new(block.clone(), vec![], HashMap::new()),
450 "bundle-1".to_string(),
451 )
452 .await
453 .expect("pending update failed");
454
455 let seen = seen.lock().unwrap();
456 assert_eq!(
457 seen.as_slice(),
458 [block],
459 "The indexer must be handed the caller's block, not one derived from the parent."
460 );
461 }
462
463 fn confirmed_at(number: u64) -> FeedMessage<BlockHeader> {
465 FeedMessage {
466 state_msgs: HashMap::from([(
467 "fluid".to_string(),
468 tycho_client::feed::synchronizer::StateSyncMessage {
469 header: BlockHeader { number, ..Default::default() },
470 ..Default::default()
471 },
472 )]),
473 sync_states: HashMap::new(),
474 }
475 }
476
477 #[tokio::test]
480 async fn test_stamped_header_comes_from_the_pending_block() {
481 let seen = Arc::new(Mutex::new(Vec::new()));
482 let mut pending_processor = processor(seen);
483 pending_processor
484 .advance(&confirmed_at(5))
485 .expect("advance failed");
486
487 let update = pending_processor
488 .generate_pending_update(
489 &PendingBlock::new(target_block(3, 1_759_842_947), vec![], HashMap::new()),
490 "bundle-1".to_string(),
491 )
492 .await
493 .expect("pending update failed");
494
495 assert_eq!(
496 update.update.block_number, 3,
497 "The update must be stamped with the pending block, not the confirmed tip."
498 );
499 }
500
501 #[tokio::test]
502 async fn test_parent_guard_reads_the_pending_blocks_number() {
503 let seen = Arc::new(Mutex::new(Vec::new()));
504 let mut pending_processor = processor(seen.clone());
505 let block = target_block(23_526_115, 1_759_842_947);
506
507 let result = pending_processor
508 .generate_pending_update(
509 &PendingBlock::new(block, vec![], HashMap::new()),
510 "bundle-1".to_string(),
511 )
512 .await;
513
514 match result {
515 Err(PendingError::ParentNotYetConfirmed { needed, current }) => {
516 assert_eq!(needed, 23_526_114);
517 assert_eq!(current, 0);
518 }
519 Err(other) => panic!("expected ParentNotYetConfirmed, got {other:?}"),
520 Ok(_) => panic!("expected ParentNotYetConfirmed, got a successful update"),
521 }
522 assert!(
523 seen.lock().unwrap().is_empty(),
524 "No indexer should run when the parent is not confirmed."
525 );
526 }
527}