Skip to main content

tycho_simulation/evm/
pending.rs

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
24/// An ephemeral [`Update`] tagged with a caller-supplied label.
25///
26/// The label is an opaque string chosen by the caller to distinguish parallel bundle evaluations
27/// (e.g. bundle ID, strategy name). It is separate from `update.block_number`,
28/// which carries the target block the bundle was evaluated against.
29pub struct PendingUpdate {
30    pub label: String,
31    pub update: Update,
32}
33
34#[derive(Debug, Error)]
35pub enum PendingError {
36    /// Returned when the parent of `pending.block()` has not been confirmed. Use
37    /// [`subscribe_confirmed_block`](PendingBlockProcessor::subscribe_confirmed_block) to wait
38    /// for the right block before calling.
39    #[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
47/// Wires one or more [`TxDeltaIndexer`]s to an existing [`TychoStreamDecoder`], enabling
48/// ephemeral simulation of candidate transaction bundles against the correct parent state
49/// for a specific target block.
50///
51/// # Block targeting
52///
53/// Call [`subscribe_confirmed_block`](Self::subscribe_confirmed_block) to obtain a
54/// [`watch::Receiver<u64>`] that fires on every confirmed block. Use it to wait for the
55/// right parent before submitting a bundle:
56///
57/// ```no_run
58/// # async fn example(
59/// #     mut processor: tycho_simulation::evm::pending::PendingBlockProcessor,
60/// #     pending_block: &tycho_common::models::blockchain::PendingBlock,
61/// # ) {
62/// processor
63///     .subscribe_confirmed_block()
64///     .wait_for(|&n| n >= pending_block.block().number - 1)
65///     .await
66///     .expect("stream closed");
67/// let update = processor
68///     .generate_pending_update(pending_block, "bundle-1".to_string())
69///     .await
70///     .expect("pending update failed");
71/// # }
72/// ```
73///
74/// # Concurrency
75///
76/// `PendingBlockProcessor` is intentionally **not** wrapped in a `Mutex` at construction
77/// time. The confirmed stream forwards blocks via an unbounded channel — it never blocks
78/// waiting for the consumer. Multiple callers can each hold a watch receiver and
79/// independently decide when to acquire whatever external lock they use around
80/// `generate_pending_update`.
81pub struct PendingBlockProcessor {
82    indexers: HashMap<String, Box<dyn TxDeltaIndexer>>,
83    decoder: Arc<TychoStreamDecoder<BlockHeader>>,
84    chain: Chain,
85    /// Block number of the most recently confirmed block applied to `indexers`.
86    current_confirmed_block: u64,
87    /// Notified on every `advance_inner` call; drives `subscribe_confirmed_block`.
88    confirmed_block_tx: watch::Sender<u64>,
89    /// Confirmed blocks forwarded by the stream pipeline.
90    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    /// Returns a receiver that is notified with the latest confirmed block number every time
105    /// a new block is applied.
106    ///
107    /// Typical usage: `.wait_for(|&n| n >= target_block - 1).await` before calling
108    /// [`generate_pending_update`](Self::generate_pending_update).
109    pub fn subscribe_confirmed_block(&self) -> watch::Receiver<u64> {
110        self.confirmed_block_tx.subscribe()
111    }
112
113    /// Returns the block number of the last confirmed block applied to the indexers.
114    pub fn current_confirmed_block(&self) -> u64 {
115        self.current_confirmed_block
116    }
117
118    /// Advances each registered indexer by applying one confirmed block.
119    ///
120    /// Only needed when using the processor standalone (without
121    /// [`ProtocolStreamBuilder::build_with_pending`](crate::evm::stream::ProtocolStreamBuilder::build_with_pending)).
122    /// When using `build_with_pending`, confirmed blocks are forwarded automatically.
123    pub fn advance(&mut self, msg: &FeedMessage<BlockHeader>) -> Result<(), PendingError> {
124        self.advance_inner(msg)
125    }
126
127    /// Simulates `pending` against the confirmed parent of `pending.block()`.
128    ///
129    /// Drains any confirmed blocks that have arrived since the last call, then immediately
130    /// checks whether `pending.block().number - 1` is available. If not, returns
131    /// [`PendingError::ParentNotYetConfirmed`] — **no blocking**. Use
132    /// [`subscribe_confirmed_block`](Self::subscribe_confirmed_block) to wait for the right
133    /// block before calling.
134    ///
135    /// Neither the indexers' internal state nor the decoder's confirmed pool states are
136    /// mutated. Calling this twice with the same arguments returns identical results.
137    ///
138    /// # Parameters
139    /// * `pending` — the in-flight block: the block being built, the candidate bundle in execution
140    ///   order (failed transactions are skipped), and post-execution account state for the accounts
141    ///   it touched. The returned deltas use this block's number and timestamp.
142    /// * `label` — opaque caller-supplied tag stamped onto the returned [`PendingUpdate`]. Use it
143    ///   to associate the result with a specific bundle or evaluation context.
144    pub async fn generate_pending_update(
145        &mut self,
146        pending: &PendingBlock,
147        label: String,
148    ) -> Result<PendingUpdate, PendingError> {
149        // Drain any confirmed blocks that have arrived since our last call.
150        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
227/// Converts a startup snapshot into a `BlockAggregatedChanges` suitable for
228/// [`TxDeltaIndexer::apply_block`].
229///
230/// Each component's traced entrypoints are folded into `dci_update`, so an indexer sees the
231/// contracts a component reads through DCI the same way it does on the delta path.
232fn 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    /// Records the block it was handed, so a test can assert what the processor passed down.
339    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        // Parent is block 0, which the processor considers confirmed from the start.
445        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    /// A confirmed block carrying no snapshots or deltas: it only advances the tip.
464    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    /// The header stamped onto every delta must come from the pending block too, not from the
478    /// confirmed tip. Priced against a tip of 5, a target of 3 tells the two apart.
479    #[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}