Skip to main content

tycho_common/
storage.rs

1//! Storage traits used by Tycho
2use std::{
3    collections::{HashMap, HashSet},
4    fmt::Display,
5};
6
7use async_trait::async_trait;
8use chrono::NaiveDateTime;
9use thiserror::Error;
10
11use crate::{
12    dto,
13    models::{
14        blockchain::{
15            Block, EntryPoint, EntryPointWithTracingParams, TracedEntryPoint, TracedEntryPoints,
16            TracingParams, TracingResult, Transaction,
17        },
18        contract::{Account, AccountBalance, AccountDelta},
19        protocol::{
20            ComponentBalance, ComponentPause, PauseRecord, ProtocolComponent,
21            ProtocolComponentState, ProtocolComponentStateDelta, QualityRange, UnpauseRecord,
22        },
23        token::Token,
24        Address, BlockHash, Chain, ComponentId, ContractId, EntryPointId, ExtractionState,
25        PaginationParams, ProtocolSystem, ProtocolType, StoreKey, TxHash,
26    },
27    Bytes,
28};
29
30/// Identifies a block in storage.
31#[derive(Debug, Clone, PartialEq, Hash, Eq)]
32pub enum BlockIdentifier {
33    /// Identifies the block by its position on a specified chain.
34    ///
35    /// This form of identification has potential risks as it may become
36    /// ambiguous in certain situations. For example, if the block has not been
37    /// finalised, there exists a possibility of forks occurring. As a result,
38    /// the same number could refer to different blocks on different forks.
39    Number((Chain, i64)),
40
41    /// Identifies a block by its hash.
42    ///
43    /// The hash should be unique across multiple chains. Preferred method if
44    /// the block is very recent.
45    Hash(BlockHash),
46
47    /// Latest stored block for the target chain
48    ///
49    /// Returns the block with the highest block number on the target chain.
50    Latest(Chain),
51}
52
53impl Display for BlockIdentifier {
54    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
55        write!(f, "{self:?}")
56    }
57}
58
59#[derive(Error, Debug, PartialEq, Clone)]
60pub enum StorageError {
61    #[error("Could not find {0} with id `{1}`!")]
62    NotFound(String, String),
63    #[error("The entity {0} with id {1} was already present!")]
64    DuplicateEntry(String, String),
65    #[error("Could not find related {0} for {1} with id `{2}`!")]
66    NoRelatedEntity(String, String, String),
67    #[error("DecodeError: {0}")]
68    DecodeError(String),
69    #[error("Unexpected storage error: {0}")]
70    Unexpected(String),
71    #[error("Currently unsupported operation: {0}")]
72    Unsupported(String),
73    #[error("Write cache unexpectedly dropped notification channel!")]
74    WriteCacheGoneAway(),
75    #[error("Invalid block range encountered")]
76    InvalidBlockRange(),
77}
78
79/// Storage methods for chain specific objects.
80///
81/// This trait abstracts the specific implementation details of a blockchain's
82/// entities, allowing the user to add and retrieve blocks and transactions in a
83/// generic way.
84///
85/// For traceability protocol components and contracts changes are linked to
86/// blocks of their respective chain if applicable. This means while indexing we
87/// need to keep a lightweight and cross chain compatible representation of
88/// blocks and transactions in storage.
89///
90/// It's defined generically over two associated types:
91///
92/// * `Block`: represents a block in the blockchain.
93/// * `Transaction`: represents a transaction within a block.
94#[async_trait]
95pub trait ChainGateway {
96    /// Upserts a new block to the blockchain's storage.
97    ///
98    /// Ignores any existing tx, if the new entry has different attributes
99    /// no error is raised and the old entry is kept.
100    ///
101    /// # Parameters
102    /// - `new`: An instance of `Self::Block`, representing the new block to be stored.
103    ///
104    /// # Returns
105    /// - Empty ok result indicates success. Failure might occur if the block is already present.
106    async fn upsert_block(&self, new: &[Block]) -> Result<(), StorageError>;
107    /// Retrieves a block from storage.
108    ///
109    /// # Parameters
110    /// - `id`: Block's unique identifier of type `BlockIdentifier`.
111    ///
112    /// # Returns
113    /// - An Ok result containing the block. Might fail if the block does not exist yet.
114    async fn get_block(&self, id: &BlockIdentifier) -> Result<Block, StorageError>;
115    /// Upserts a transaction to storage.
116    ///
117    /// Ignores any existing tx, if the new entry has different attributes
118    /// no error is raised and the old entry is kept.
119    ///
120    /// # Parameters
121    /// - `new`: An instance of `Self::Transaction`, representing the new transaction to be stored.
122    ///
123    /// # Returns
124    /// - Empty ok result indicates success. Failure might occur if the
125    /// corresponding block does not exists yet, or if the transaction already
126    /// exists.
127    async fn upsert_tx(&self, new: &[Transaction]) -> Result<(), StorageError>;
128
129    /// Tries to retrieve a transaction from the blockchain's storage using its
130    /// hash.
131    ///
132    /// # Parameters
133    /// - `hash`: The byte slice representing the hash of the transaction to be retrieved.
134    ///
135    /// # Returns
136    /// - An Ok result containing the transaction. Might fail if the transaction does not exist yet.
137    async fn get_tx(&self, hash: &TxHash) -> Result<Transaction, StorageError>;
138
139    /// Reverts the blockchain storage to a previous version.
140    ///
141    /// Reverting state signifies deleting database history. Only the main branch will be kept.
142    ///
143    /// Blocks that are greater than the provided block (`to`) are deleted and any versioned rows
144    /// which were invalidated in the deleted blocks are updated to be valid again.
145    ///
146    /// # Parameters
147    /// - `to` The version to revert to. Given a block uses VersionKind::Last behaviour.
148    /// - `db` The database gateway.
149    ///
150    /// # Returns
151    /// - An Ok if the revert is successful, or a `StorageError` if not.
152    async fn revert_state(&self, to: &BlockIdentifier) -> Result<(), StorageError>;
153}
154
155/// Store and retrieve state of Extractors.
156///
157/// Sometimes extractors may wish to persist their state across restart. E.g.
158/// substreams based extractors need to store the cursor, so they can continue
159/// processing where they left off.
160///
161/// Extractors are uniquely identified by a name and the respective chain which
162/// they are indexing.
163#[async_trait]
164pub trait ExtractionStateGateway {
165    /// Retrieves the state of an extractor instance from a storage.
166    ///
167    /// # Parameters
168    /// - `name` A unique name for the extractor instance.
169    /// - `chain` The chain this extractor is indexing.
170    ///
171    /// # Returns
172    /// Ok if the corrsponding state was retrieved successfully, Err in
173    /// case the state was not found.
174    async fn get_state(&self, name: &str, chain: &Chain) -> Result<ExtractionState, StorageError>;
175
176    /// Saves the state of an extractor instance to a storage.
177    ///
178    /// Creates an entry if not present yet, or updates an already existing
179    /// entry.
180    ///
181    /// # Parameters
182    /// - `state` The state of the extractor that needs to be saved.
183    ///
184    /// # Returns
185    /// Ok, if state was stored successfully, Err if the state is not valid.
186    async fn save_state(&self, state: &ExtractionState) -> Result<(), StorageError>;
187}
188
189/// Point in time as either block or timestamp. If a block is chosen it
190/// timestamp attribute is used.
191#[derive(Debug, Clone, PartialEq, Hash, Eq)]
192pub enum BlockOrTimestamp {
193    Block(BlockIdentifier),
194    Timestamp(NaiveDateTime),
195}
196
197#[expect(deprecated, reason = "reads the deprecated chain field of BlockParam")]
198impl TryFrom<&dto::VersionParam> for BlockOrTimestamp {
199    type Error = anyhow::Error;
200
201    fn try_from(version: &dto::VersionParam) -> Result<Self, Self::Error> {
202        match (&version.timestamp, &version.block) {
203            (_, Some(block)) => {
204                // If a full block is provided, we prioritize hash over number and chain
205                let block_identifier = match (&block.hash, &block.chain, &block.number) {
206                    (Some(hash), _, _) => BlockIdentifier::Hash(hash.clone()),
207                    (_, Some(chain), Some(number)) => {
208                        BlockIdentifier::Number((Chain::from(*chain), *number))
209                    }
210                    _ => {
211                        return Err(anyhow::format_err!("Insufficient block information".to_owned()))
212                    }
213                };
214                Ok(BlockOrTimestamp::Block(block_identifier))
215            }
216            (Some(timestamp), None) => Ok(BlockOrTimestamp::Timestamp(*timestamp)),
217            (None, None) => {
218                Err(anyhow::format_err!("Missing timestamp or block identifier".to_owned()))
219            }
220        }
221    }
222}
223
224/// References certain states within a single block.
225///
226/// **Note:** Not all methods that take a version will support all version kinds,
227/// the versions here are included for completeness and to document the
228/// retrieval behaviour that is possible with the storage layout. Please refer
229/// to the individual implementation for information about which version kinds
230/// it supports.
231#[derive(Debug, Clone, Default)]
232pub enum VersionKind {
233    /// Represents the final state within a specific block. Essentially, it
234    /// retrieves the state subsequent to the execution of the last transaction
235    /// executed in that block.
236    #[default]
237    Last,
238    /// Represents the initial state of a specific block. In other words,
239    /// it is the state before any transaction has been executed within that block.
240    First,
241    /// Represents a specific transactions indexed position within a block.
242    /// It includes the state after executing the transaction at that index.
243    Index(i64),
244}
245
246/// A version desribes the state of the DB at a exact point in time.
247/// See the module level docs for more information on how versioning works.
248#[derive(Debug, Clone)]
249pub struct Version(pub BlockOrTimestamp, pub VersionKind);
250
251impl Version {
252    pub fn from_block_number(chain: Chain, number: i64) -> Self {
253        Self(BlockOrTimestamp::Block(BlockIdentifier::Number((chain, number))), VersionKind::Last)
254    }
255    pub fn from_ts(ts: NaiveDateTime) -> Self {
256        Self(BlockOrTimestamp::Timestamp(ts), VersionKind::Last)
257    }
258}
259
260// Helper type to retrieve entities with their total retrievable count.
261#[derive(Debug)]
262pub struct WithTotal<T> {
263    pub entity: T,
264    pub total: Option<i64>,
265}
266
267/// Store and retrieve protocol related structs.
268///
269/// This trait defines how to retrieve protocol components, state as well as
270/// tokens from storage.
271#[async_trait]
272pub trait ProtocolGateway {
273    /// Retrieve ProtocolComponent from the db
274    ///
275    /// # Parameters
276    /// - `chain` The chain of the component
277    /// - `system` Allows to optionally filter by system.
278    /// - `ids` Allows to optionally filter by id.
279    /// - `min_tvl` Allows to optionally filter by min tvl.
280    /// - `pagination_params` Optional pagination parameters to control the number of results.
281    ///
282    /// # Returns
283    /// Ok, if found else Err
284    async fn get_protocol_components(
285        &self,
286        chain: &Chain,
287        system: Option<String>,
288        ids: Option<&[&str]>,
289        min_tvl: Option<f64>,
290        pagination_params: Option<&PaginationParams>,
291    ) -> Result<WithTotal<Vec<ProtocolComponent>>, StorageError>;
292
293    /// Retrieves owners of tokens
294    ///
295    /// Queries for owners (protocol components) of tokens that have a certain minimum
296    /// balance and returns a maximum aggregate of those in case there are multiple
297    /// owners.
298    ///
299    /// # Parameters
300    /// - `chain` The chain of the component
301    /// - `tokens` The tokens to query for, any component with at least one of these tokens is
302    ///   returned.
303    /// - `min_balance` A minimum balance we expect the component to have on any of the tokens
304    ///   mentioned in `tokens`.
305    async fn get_token_owners(
306        &self,
307        chain: &Chain,
308        tokens: &[Address],
309        min_balance: Option<f64>,
310    ) -> Result<HashMap<Address, (ComponentId, Bytes)>, StorageError>;
311
312    async fn add_protocol_components(&self, new: &[ProtocolComponent]) -> Result<(), StorageError>;
313
314    async fn delete_protocol_components(
315        &self,
316        to_delete: &[ProtocolComponent],
317        block_ts: NaiveDateTime,
318    ) -> Result<(), StorageError>;
319
320    /// Stores new found ProtocolTypes.
321    ///
322    /// # Parameters
323    /// - `new_protocol_types`  The new protocol types.
324    ///
325    /// # Returns
326    /// Ok if stored successfully.
327    async fn add_protocol_types(
328        &self,
329        new_protocol_types: &[ProtocolType],
330    ) -> Result<(), StorageError>;
331
332    /// Retrieve protocol component states
333    ///
334    /// This resource is versioned, the version can be specified by either block
335    /// or timestamp, for off-chain components, a block version will error.
336    ///
337    /// As the state is retained on a transaction basis on blockchain systems, a
338    /// single version may relate to more than one state. In these cases a
339    /// versioned result is returned, if requesting `Version:All` with the
340    /// latest entry being the state at the end of the block and the first entry
341    /// represents the first change to the state within the block.
342    ///
343    /// # Parameters
344    /// - `chain` The chain of the component
345    /// - `at` The version at which the state is valid at.
346    /// - `system` The protocol system this component belongs to
347    /// - `ids` The external ids of the components e.g. addresses, or the pairs
348    /// - `retrieve_balances` Whether to retrieve the balances for the components.
349    /// - `pagination_params` Optional pagination parameters to control the number of results.
350    async fn get_protocol_states(
351        &self,
352        chain: &Chain,
353        at: Option<Version>,
354        system: Option<String>,
355        ids: Option<&[&str]>,
356        retrieve_balances: bool,
357        pagination_params: Option<&PaginationParams>,
358    ) -> Result<WithTotal<Vec<ProtocolComponentState>>, StorageError>;
359
360    async fn update_protocol_states(
361        &self,
362        new: &[(TxHash, ProtocolComponentStateDelta)],
363    ) -> Result<(), StorageError>;
364
365    /// Retrieves a tokens from storage
366    ///
367    /// # Parameters
368    /// - `chain` The chain this token is implemented on.
369    /// - `address` The address for the token within the chain.
370    /// - `quality` The quality of the token.
371    /// - `traded_n_days_ago` The number of days ago the token was traded.
372    /// - `pagination_params` Optional pagination parameters to control the number of results.
373    ///
374    /// # Returns
375    /// Ok if the results could be retrieved from the storage, else errors.
376    async fn get_tokens(
377        &self,
378        chain: Chain,
379        address: Option<&[&Address]>,
380        quality: QualityRange,
381        traded_n_days_ago: Option<NaiveDateTime>,
382        pagination_params: Option<&PaginationParams>,
383    ) -> Result<WithTotal<Vec<Token>>, StorageError>;
384
385    /// Saves multiple component balances to storage.
386    ///
387    /// # Parameters
388    /// - `component_balances` The component balances to insert.
389    ///
390    /// # Return
391    /// Ok if all component balances could be inserted, Err if at least one token failed to
392    /// insert.
393    async fn add_component_balances(
394        &self,
395        component_balances: &[ComponentBalance],
396    ) -> Result<(), StorageError>;
397
398    /// Saves multiple tokens to storage.
399    ///
400    /// Inserts token into storage. Tokens and their properties are assumed to
401    /// be immutable.
402    ///
403    /// # Parameters
404    /// - `tokens` The tokens to insert.
405    ///
406    /// # Return
407    /// Ok if all tokens could be inserted, Err if at least one token failed to
408    /// insert.
409    async fn add_tokens(&self, tokens: &[Token]) -> Result<(), StorageError>;
410
411    /// Updates multiple tokens in storage.
412    ///
413    /// Updates token in storage. Will warn if one of the tokens does not exist in the
414    /// database. Currently assumes that token addresses are unique across chains.
415    ///
416    /// # Parameters
417    /// - `tokens` The tokens to update.
418    ///
419    /// # Return
420    /// Ok if all tokens could be inserted, Err if at least one token failed to
421    /// insert.
422    async fn update_tokens(&self, tokens: &[Token]) -> Result<(), StorageError>;
423
424    /// Retrieve protocol state changes
425    ///
426    /// Fetches all state changes that occurred for the given chain
427    ///
428    /// # Parameters
429    /// - `chain` The chain of the component
430    /// - `start_version` The version at which to start looking for changes at.
431    /// - `end_version` The version at which to stop looking for changes.
432    ///
433    /// # Return
434    /// A list of ProtocolStateDeltas containing all state changes, Err if no changes were found.
435    async fn get_protocol_states_delta(
436        &self,
437        chain: &Chain,
438        start_version: Option<&BlockOrTimestamp>,
439        end_version: &BlockOrTimestamp,
440    ) -> Result<Vec<ProtocolComponentStateDelta>, StorageError>;
441
442    /// Retrieve protocol component balance changes
443    ///
444    /// Fetches all balance changes that occurred for the given protocol system
445    ///
446    /// # Parameters
447    /// - `chain` The chain of the component
448    /// - `start_version` The version at which to start looking for changes at.
449    /// - `target_version` The version at which to stop looking for changes.
450    ///
451    /// # Return
452    /// A vec containing ComponentBalance objects for changed components.
453    async fn get_balance_deltas(
454        &self,
455        chain: &Chain,
456        start_version: Option<&BlockOrTimestamp>,
457        target_version: &BlockOrTimestamp,
458    ) -> Result<Vec<ComponentBalance>, StorageError>;
459
460    async fn get_component_balances(
461        &self,
462        chain: &Chain,
463        ids: Option<&[&str]>,
464        version: Option<&Version>,
465    ) -> Result<HashMap<String, HashMap<Bytes, ComponentBalance>>, StorageError>;
466
467    async fn get_token_prices(&self, chain: &Chain) -> Result<HashMap<Bytes, f64>, StorageError>;
468
469    async fn upsert_component_tvl(
470        &self,
471        chain: &Chain,
472        tvl_values: &HashMap<String, f64>,
473    ) -> Result<(), StorageError>;
474
475    /// Retrieve a list of actively supported protocol systems
476    ///
477    /// Fetches the list of protocol systems supported by the Tycho indexing service.
478    ///
479    /// # Parameters
480    /// - `chain` The chain for which to retrieve supported protocol systems.
481    /// - `pagination_params` Optional pagination parameters to control the number of results.
482    ///
483    /// # Return
484    /// A paginated list of supported protocol systems, along with the total count.
485    async fn get_protocol_systems(
486        &self,
487        chain: &Chain,
488        pagination_params: Option<&PaginationParams>,
489    ) -> Result<WithTotal<Vec<String>>, StorageError>;
490
491    /// Retrieve the components total value locked (TVL).
492    ///
493    /// # Parameters
494    /// - `chain` The chain for which to retrieve the total value locked
495    /// - `system` The protocol system for which to retrieve the total value locked
496    /// - `ids` The ids of the components to retrieve the total value locked for
497    /// - `pagination_params` Optional pagination parameters to control the number of results.
498    ///
499    /// # Return
500    /// A result with a map of component ids to their TVL. Err if storage access failed.
501    async fn get_component_tvls(
502        &self,
503        chain: &Chain,
504        system: Option<String>,
505        ids: Option<&[&str]>,
506        pagination_params: Option<&PaginationParams>,
507    ) -> Result<WithTotal<HashMap<String, f64>>, StorageError>;
508}
509
510/// Store and retrieve admin pauses of protocol components.
511#[async_trait]
512pub trait ComponentPauseGateway {
513    /// Records admin pauses of components.
514    ///
515    /// A component that is already paused keeps its existing pause and audit details. A
516    /// component can be paused before it is indexed. The call records every pause or none, so a
517    /// failed call can be retried as a whole.
518    ///
519    /// # Parameters
520    /// - `chain` The chain of the components.
521    /// - `system` The protocol system the components belong to.
522    /// - `pauses` The pauses to record. A repeated id keeps its first pause.
523    ///
524    /// # Returns
525    /// The ids of the components this call paused. Err if the protocol system is unknown or
526    /// storage access failed.
527    async fn pause_components(
528        &self,
529        chain: &Chain,
530        system: &str,
531        pauses: &[PauseRecord],
532    ) -> Result<Vec<ComponentId>, StorageError>;
533
534    /// Ends admin pauses of components.
535    ///
536    /// Ended pauses stay stored as history. Ids that are not paused are ignored.
537    ///
538    /// # Parameters
539    /// - `chain` The chain of the components.
540    /// - `component_ids` The external ids of the components to unpause.
541    /// - `unpause` Who ended the pauses and why, stored on every pause this call ends.
542    ///
543    /// # Returns
544    /// The ids of the components whose pause this call ended. Err if storage access failed.
545    async fn unpause_components(
546        &self,
547        chain: &Chain,
548        component_ids: &[&str],
549        unpause: &UnpauseRecord,
550    ) -> Result<Vec<ComponentId>, StorageError>;
551
552    /// Reads the admin pauses that are in effect.
553    ///
554    /// # Parameters
555    /// - `chain` The chain to read pauses for.
556    ///
557    /// # Returns
558    /// Every pause in effect on the chain, across all protocol systems. Err if storage access
559    /// failed.
560    async fn get_component_pauses(
561        &self,
562        chain: &Chain,
563    ) -> Result<Vec<ComponentPause>, StorageError>;
564}
565
566/// Filters for entry points queries in the database.
567// Shalow but can be used to add more filters without breaking backwards compatibility in the future
568#[derive(Debug, Clone)]
569pub struct EntryPointFilter {
570    pub protocol_system: ProtocolSystem,
571    pub component_ids: Option<Vec<ComponentId>>,
572}
573
574impl EntryPointFilter {
575    pub fn new(protocol: ProtocolSystem) -> Self {
576        Self { protocol_system: protocol, component_ids: None }
577    }
578
579    pub fn with_component_ids(mut self, component_ids: Vec<ComponentId>) -> Self {
580        self.component_ids = Some(component_ids);
581        self
582    }
583}
584
585// Trait for entry point gateway operations.
586#[async_trait]
587pub trait EntryPointGateway {
588    /// Inserts a list of entry points into the database.
589    ///
590    /// # Arguments
591    /// * `entry_points` - The map of component ids to their entry points to insert.
592    ///
593    /// Note: This function ignores conflicts on inserts.
594    async fn insert_entry_points(
595        &self,
596        entry_points: &HashMap<ComponentId, HashSet<EntryPoint>>,
597    ) -> Result<(), StorageError>;
598
599    /// Inserts a list of entry points with their tracing params into the database.
600    ///
601    /// # Arguments
602    /// * `entry_points_params` - The map of entry points to their tracing params to insert and
603    ///   component id for the component linked to the params.
604    ///
605    /// Note: This function ignores conflicts on inserts.
606    async fn insert_entry_point_tracing_params(
607        &self,
608        entry_points_params: &HashMap<EntryPointId, HashSet<(TracingParams, ComponentId)>>,
609    ) -> Result<(), StorageError>;
610
611    /// Retrieves a map of component ids to a set of entry points from the database.
612    ///
613    /// # Arguments
614    /// * `filter` - The EntryPointFilter to apply to the query.
615    /// * `pagination_params` - The pagination parameters to apply to the query, if None, all
616    ///   results are returned.
617    ///
618    /// # Returns
619    /// A map of component ids to a set of entry points.
620    async fn get_entry_points(
621        &self,
622        filter: EntryPointFilter,
623        pagination_params: Option<&PaginationParams>,
624    ) -> Result<WithTotal<HashMap<ComponentId, HashSet<EntryPoint>>>, StorageError>;
625
626    /// Retrieves a map of component ids to a set of entry points with their tracing data from the
627    /// database.
628    ///
629    /// # Arguments
630    /// * `filter` - The EntryPointFilter to apply to the query.
631    /// * `pagination_params` - The pagination parameters to apply to the query, if None, all
632    ///   results are returned.
633    ///
634    /// # Returns
635    /// A map of component ids to a set of entry points with their tracing params.
636    async fn get_entry_points_tracing_params(
637        &self,
638        filter: EntryPointFilter,
639        pagination_params: Option<&PaginationParams>,
640    ) -> Result<WithTotal<HashMap<ComponentId, HashSet<EntryPointWithTracingParams>>>, StorageError>;
641
642    /// Upserts a list of traced entry points into the database. Updates the result if it already
643    /// exists for the same entry point and tracing params.
644    ///
645    /// # Arguments
646    /// * `traced_entry_points` - The list of traced entry points to upsert.
647    async fn upsert_traced_entry_points(
648        &self,
649        traced_entry_points: &[TracedEntryPoint],
650    ) -> Result<(), StorageError>;
651
652    /// Retrieves all tracing results for a set of entry points from the database.
653    ///
654    /// # Arguments
655    /// * `entry_points` - The set of entry points to retrieve tracing results for.
656    ///
657    /// # Returns
658    /// A map of entry point ids to a map of tracing params to tracing results.
659    async fn get_traced_entry_points(
660        &self,
661        entry_points: &HashSet<EntryPointId>,
662    ) -> Result<HashMap<EntryPointId, HashMap<TracingParams, TracingResult>>, StorageError>;
663
664    /// Retrieves the traced entry points of a set of components from the database.
665    ///
666    /// # Arguments
667    /// * `filter` - The EntryPointFilter to apply to the query.
668    /// * `pagination_params` - The pagination parameters to apply to the query, if None, all
669    ///   results are returned.
670    ///
671    /// # Returns
672    /// A map of component ids to the entry points with the tracing params linked to the
673    /// component, and their tracing results. Params without a tracing result are not included.
674    async fn get_traced_entry_points_by_component(
675        &self,
676        filter: EntryPointFilter,
677        pagination_params: Option<&PaginationParams>,
678    ) -> Result<WithTotal<TracedEntryPoints>, StorageError>;
679}
680
681/// Manage contracts and their state in storage.
682///
683/// Specifies how to retrieve, add and update contracts in storage.
684#[async_trait]
685pub trait ContractStateGateway {
686    /// Get a contracts state from storage
687    ///
688    /// This method retrieves a single contract from the database.
689    ///
690    /// # Parameters
691    /// - `id` The identifier for the contract.
692    /// - `version` Version at which to retrieve state for. None retrieves the latest state.
693    /// - `include_slots`: Flag to determine whether to include slot changes. If set to `true`, it
694    ///   includes storage slot.
695    async fn get_contract(
696        &self,
697        id: &ContractId,
698        version: Option<&Version>,
699        include_slots: bool,
700    ) -> Result<Account, StorageError>;
701
702    /// Get multiple contracts' states from storage.
703    ///
704    /// This method retrieves balance and code, and optionally storage, of
705    /// multiple contracts in a chain. It can optionally filter by given
706    /// addresses and retrieve state for specific versions.
707    ///
708    /// # Parameters:
709    /// - `chain`: The blockchain where the contracts reside.
710    /// - `addresses`: Filter for specific addresses. If set to `None`, it retrieves all indexed
711    ///   contracts in the chain.
712    /// - `version`: Version at which to retrieve state for. If set to `None`, it retrieves the
713    ///   latest state.
714    /// - `include_slots`: Flag to determine whether to include slot changes. If set to `true`, it
715    ///   includes storage slot.
716    /// - `pagination_params`: Optional pagination parameters to control the number of results.
717    ///
718    /// # Returns:
719    /// A `Result` with a list of contract states if the operation is
720    /// successful, or a `StorageError` if the operation fails.
721    async fn get_contracts(
722        &self,
723        chain: &Chain,
724        addresses: Option<&[Address]>,
725        version: Option<&Version>,
726        include_slots: bool,
727        pagination_params: Option<&PaginationParams>,
728    ) -> Result<WithTotal<Vec<Account>>, StorageError>;
729
730    /// Inserts a new contract into the database.
731    ///
732    /// Inserts only the static values of the contract. To insert the contract slots, balance and
733    /// code please use the `update_contracts` method.
734    ///
735    /// # Arguments
736    /// - `new`: A reference to the new contract state to be inserted.
737    ///
738    /// # Returns
739    /// - A Result with Ok if the operation was successful, and an Err containing `StorageError` if
740    ///   there was an issue inserting the contract into the database. E.g. if the contract already
741    ///   existed.
742    async fn insert_contract(&self, new: &Account) -> Result<(), StorageError>;
743
744    /// Update multiple contracts
745    ///
746    /// Given contract deltas, this method will batch all updates to contracts across a single
747    /// chain.
748    ///
749    /// As changes are versioned by transaction, each changeset needs to be associated with a
750    /// transaction hash. All references transaction are assumed to be already persisted.
751    ///
752    /// # Arguments
753    ///
754    /// - `new`: A reference to a slice of tuples where each tuple has a transaction hash (`TxHash`)
755    ///   and a reference to the state delta (`&Self::Delta`) for that transaction.
756    ///
757    /// # Returns
758    ///
759    /// A Result with `Ok` if the operation was successful, and an `Err` containing
760    /// `StorageError` if there was an issue updating the contracts in the database. E.g. if a
761    /// transaction can't be located by it's reference or accounts refer to a different chain then
762    /// the one specified.
763    async fn update_contracts(&self, new: &[(TxHash, AccountDelta)]) -> Result<(), StorageError>;
764
765    /// Mark a contract as deleted
766    ///
767    /// Issues a soft delete of the contract.
768    ///
769    /// # Parameters
770    /// - `id` The identifier for the contract.
771    /// - `at_tx` The transaction hash which deleted the contract. This transaction is assumed to be
772    ///   in storage already. None retrieves the latest state.
773    ///
774    /// # Returns
775    /// Ok if the deletion was successful, might Err if:
776    ///  - Contract is not present in storage.
777    ///  - Deletion transaction is not present in storage.
778    ///  - Contract was already deleted.
779    async fn delete_contract(&self, id: &ContractId, at_tx: &TxHash) -> Result<(), StorageError>;
780
781    /// Retrieve a account delta between two versions.
782    ///
783    /// Given start version V1 and end version V2, this method will return the
784    /// changes necessary to move from V1 to V2. So if V1 < V2, it will contain
785    /// the changes of all accounts that changed between the two versions with the
786    /// values corresponding to V2. If V2 < V1 then it will contain all the
787    /// slots that changed between the two versions with the values corresponding to V1.
788    ///
789    /// This method is mainly meant to handle reverts, but can also be used to create delta changes
790    /// between two historical version thus providing the basis for creating a backtestable stream
791    /// of messages.
792    ///
793    /// # Parameters
794    ///
795    /// - `chain` The chain for which to generate the delta changes.
796    /// - `start_version` The deltas start version, given a block uses VersionKind::Last behaviour.
797    ///   If None the latest version is assumed.
798    /// - `end_version` The deltas end version, given a block uses VersionKind::Last behaviour.
799    ///
800    /// # Note
801    ///
802    /// A choice to utilize `BlockOrTimestamp` has been made intentionally in
803    /// this scenario as passing a `Version` by user isn't quite logical.
804    /// Support for deltas is limited to the states at the start or end of
805    /// blocks because blockchain reorganization at the transaction level is not
806    /// common.
807    ///
808    /// The decision to use either the beginning or end state of a block is
809    /// automatically determined by the underlying logic. For example, if we are
810    /// tracing back, `VersionKind::First` retrieval mode will be used.
811    /// Conversely, if we're progressing forward, we would apply the
812    /// `VersionKind::Last` semantics.
813    ///
814    /// # Returns
815    /// A map containing the necessary changes to update a state from start_version to end_version.
816    /// Errors if:
817    ///     - The versions can't be located in storage.
818    ///     - There was an error with the database
819    async fn get_accounts_delta(
820        &self,
821        chain: &Chain,
822        start_version: Option<&BlockOrTimestamp>,
823        end_version: &BlockOrTimestamp,
824    ) -> Result<Vec<AccountDelta>, StorageError>;
825
826    /// Saves multiple account balances to storage.
827    ///
828    /// # Parameters
829    /// - `account_balances` The account balances to insert.
830    ///
831    /// # Return
832    /// Ok if all account balances could be inserted, Err if at least one token failed to insert.
833    async fn add_account_balances(
834        &self,
835        account_balances: &[AccountBalance],
836    ) -> Result<(), StorageError>;
837
838    /// Retrieve account balances
839    ///
840    /// # Parameters
841    /// - `chain` The chain of the account balances
842    /// - `accounts` The accounts to query for. If set to `None`, it retrieves balances for all
843    ///   indexed
844    ///  accounts in the chain.
845    /// - `version` Version at which to retrieve balances for. If set to `None`, it retrieves the
846    ///   latest balances.
847    async fn get_account_balances(
848        &self,
849        chain: &Chain,
850        accounts: Option<&[Address]>,
851        version: Option<&Version>,
852    ) -> Result<HashMap<Address, HashMap<Address, AccountBalance>>, StorageError>;
853}
854
855pub trait Gateway:
856    ChainGateway
857    + ContractStateGateway
858    + ExtractionStateGateway
859    + ProtocolGateway
860    + ContractStateGateway
861    + EntryPointGateway
862    + Send
863    + Sync
864{
865}
866
867/// When a value was written: the timestamp of the writing block.
868///
869/// This is the unit of the database's `valid_from`, so the cache orders writes the way the
870/// database versions them. Block timestamps are unique per chain: the extractor adds a
871/// microsecond to a block that shares its second with the previous block. A block header supplies
872/// the timestamp; a snapshot row takes it from its `valid_from`.
873#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
874pub struct WriteTimestamp(NaiveDateTime);
875
876impl WriteTimestamp {
877    pub fn new(block_ts: NaiveDateTime) -> Self {
878        Self(block_ts)
879    }
880
881    pub fn block_ts(&self) -> NaiveDateTime {
882        self.0
883    }
884}
885
886impl From<&Block> for WriteTimestamp {
887    fn from(block: &Block) -> Self {
888        Self::new(block.ts)
889    }
890}
891
892/// Write timestamps of one account's values, one per database row.
893#[derive(Debug, Clone, PartialEq)]
894pub struct AccountWriteTimestamps {
895    pub slots: HashMap<StoreKey, WriteTimestamp>,
896    pub native_balance: WriteTimestamp,
897    pub code: WriteTimestamp,
898    pub token_balances: HashMap<Address, WriteTimestamp>,
899}
900
901impl AccountWriteTimestamps {
902    /// One timestamp for every value of `account`.
903    pub fn uniform(account: &Account, at: WriteTimestamp) -> Self {
904        Self {
905            slots: account
906                .slots
907                .keys()
908                .map(|key| (key.clone(), at))
909                .collect(),
910            native_balance: at,
911            code: at,
912            token_balances: account
913                .token_balances
914                .keys()
915                .map(|token| (token.clone(), at))
916                .collect(),
917        }
918    }
919}
920
921/// One account's live state and the write timestamp of every value: the row's `valid_from`.
922#[derive(Debug, Clone, PartialEq)]
923pub struct AccountSnapshot {
924    pub account: Account,
925    pub written_at: AccountWriteTimestamps,
926}
927
928/// One component's live state, timestamped with the newest `valid_from` among its rows or, for a
929/// component without rows, its `created_at`.
930#[derive(Debug, Clone, PartialEq)]
931pub struct ComponentSnapshot {
932    pub system: ProtocolSystem,
933    pub state: ProtocolComponentState,
934    pub updated_at: WriteTimestamp,
935}
936
937/// All live contracts and components of one chain, read from one database snapshot.
938#[derive(Debug, Clone, PartialEq)]
939pub struct StateSnapshot {
940    pub accounts: Vec<AccountSnapshot>,
941    pub components: Vec<ComponentSnapshot>,
942}
943
944/// Reads all live contracts and components of a chain from one database snapshot.
945#[async_trait]
946pub trait StateSnapshotGateway {
947    /// All live accounts and components of `chain`, every value timestamped with the block
948    /// that wrote its row.
949    ///
950    /// Implementations must read everything from one database snapshot: a row committed after
951    /// the read starts is invisible to every part of the result. In SQL terms, a read-only
952    /// `REPEATABLE READ` transaction or stricter.
953    async fn state_snapshot(&self, chain: &Chain) -> Result<StateSnapshot, StorageError>;
954}