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, ProtocolComponent, ProtocolComponentState,
21            ProtocolComponentStateDelta, QualityRange,
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/// Filters for entry points queries in the database.
511// Shalow but can be used to add more filters without breaking backwards compatibility in the future
512#[derive(Debug, Clone)]
513pub struct EntryPointFilter {
514    pub protocol_system: ProtocolSystem,
515    pub component_ids: Option<Vec<ComponentId>>,
516}
517
518impl EntryPointFilter {
519    pub fn new(protocol: ProtocolSystem) -> Self {
520        Self { protocol_system: protocol, component_ids: None }
521    }
522
523    pub fn with_component_ids(mut self, component_ids: Vec<ComponentId>) -> Self {
524        self.component_ids = Some(component_ids);
525        self
526    }
527}
528
529// Trait for entry point gateway operations.
530#[async_trait]
531pub trait EntryPointGateway {
532    /// Inserts a list of entry points into the database.
533    ///
534    /// # Arguments
535    /// * `entry_points` - The map of component ids to their entry points to insert.
536    ///
537    /// Note: This function ignores conflicts on inserts.
538    async fn insert_entry_points(
539        &self,
540        entry_points: &HashMap<ComponentId, HashSet<EntryPoint>>,
541    ) -> Result<(), StorageError>;
542
543    /// Inserts a list of entry points with their tracing params into the database.
544    ///
545    /// # Arguments
546    /// * `entry_points_params` - The map of entry points to their tracing params to insert and
547    ///   component id for the component linked to the params.
548    ///
549    /// Note: This function ignores conflicts on inserts.
550    async fn insert_entry_point_tracing_params(
551        &self,
552        entry_points_params: &HashMap<EntryPointId, HashSet<(TracingParams, ComponentId)>>,
553    ) -> Result<(), StorageError>;
554
555    /// Retrieves a map of component ids to a set of entry points from the database.
556    ///
557    /// # Arguments
558    /// * `filter` - The EntryPointFilter to apply to the query.
559    /// * `pagination_params` - The pagination parameters to apply to the query, if None, all
560    ///   results are returned.
561    ///
562    /// # Returns
563    /// A map of component ids to a set of entry points.
564    async fn get_entry_points(
565        &self,
566        filter: EntryPointFilter,
567        pagination_params: Option<&PaginationParams>,
568    ) -> Result<WithTotal<HashMap<ComponentId, HashSet<EntryPoint>>>, StorageError>;
569
570    /// Retrieves a map of component ids to a set of entry points with their tracing data from the
571    /// database.
572    ///
573    /// # Arguments
574    /// * `filter` - The EntryPointFilter to apply to the query.
575    /// * `pagination_params` - The pagination parameters to apply to the query, if None, all
576    ///   results are returned.
577    ///
578    /// # Returns
579    /// A map of component ids to a set of entry points with their tracing params.
580    async fn get_entry_points_tracing_params(
581        &self,
582        filter: EntryPointFilter,
583        pagination_params: Option<&PaginationParams>,
584    ) -> Result<WithTotal<HashMap<ComponentId, HashSet<EntryPointWithTracingParams>>>, StorageError>;
585
586    /// Upserts a list of traced entry points into the database. Updates the result if it already
587    /// exists for the same entry point and tracing params.
588    ///
589    /// # Arguments
590    /// * `traced_entry_points` - The list of traced entry points to upsert.
591    async fn upsert_traced_entry_points(
592        &self,
593        traced_entry_points: &[TracedEntryPoint],
594    ) -> Result<(), StorageError>;
595
596    /// Retrieves all tracing results for a set of entry points from the database.
597    ///
598    /// # Arguments
599    /// * `entry_points` - The set of entry points to retrieve tracing results for.
600    ///
601    /// # Returns
602    /// A map of entry point ids to a map of tracing params to tracing results.
603    async fn get_traced_entry_points(
604        &self,
605        entry_points: &HashSet<EntryPointId>,
606    ) -> Result<HashMap<EntryPointId, HashMap<TracingParams, TracingResult>>, StorageError>;
607
608    /// Retrieves the traced entry points of a set of components from the database.
609    ///
610    /// # Arguments
611    /// * `filter` - The EntryPointFilter to apply to the query.
612    /// * `pagination_params` - The pagination parameters to apply to the query, if None, all
613    ///   results are returned.
614    ///
615    /// # Returns
616    /// A map of component ids to the entry points with the tracing params linked to the
617    /// component, and their tracing results. Params without a tracing result are not included.
618    async fn get_traced_entry_points_by_component(
619        &self,
620        filter: EntryPointFilter,
621        pagination_params: Option<&PaginationParams>,
622    ) -> Result<WithTotal<TracedEntryPoints>, StorageError>;
623}
624
625/// Manage contracts and their state in storage.
626///
627/// Specifies how to retrieve, add and update contracts in storage.
628#[async_trait]
629pub trait ContractStateGateway {
630    /// Get a contracts state from storage
631    ///
632    /// This method retrieves a single contract from the database.
633    ///
634    /// # Parameters
635    /// - `id` The identifier for the contract.
636    /// - `version` Version at which to retrieve state for. None retrieves the latest state.
637    /// - `include_slots`: Flag to determine whether to include slot changes. If set to `true`, it
638    ///   includes storage slot.
639    async fn get_contract(
640        &self,
641        id: &ContractId,
642        version: Option<&Version>,
643        include_slots: bool,
644    ) -> Result<Account, StorageError>;
645
646    /// Get multiple contracts' states from storage.
647    ///
648    /// This method retrieves balance and code, and optionally storage, of
649    /// multiple contracts in a chain. It can optionally filter by given
650    /// addresses and retrieve state for specific versions.
651    ///
652    /// # Parameters:
653    /// - `chain`: The blockchain where the contracts reside.
654    /// - `addresses`: Filter for specific addresses. If set to `None`, it retrieves all indexed
655    ///   contracts in the chain.
656    /// - `version`: Version at which to retrieve state for. If set to `None`, it retrieves the
657    ///   latest state.
658    /// - `include_slots`: Flag to determine whether to include slot changes. If set to `true`, it
659    ///   includes storage slot.
660    /// - `pagination_params`: Optional pagination parameters to control the number of results.
661    ///
662    /// # Returns:
663    /// A `Result` with a list of contract states if the operation is
664    /// successful, or a `StorageError` if the operation fails.
665    async fn get_contracts(
666        &self,
667        chain: &Chain,
668        addresses: Option<&[Address]>,
669        version: Option<&Version>,
670        include_slots: bool,
671        pagination_params: Option<&PaginationParams>,
672    ) -> Result<WithTotal<Vec<Account>>, StorageError>;
673
674    /// Inserts a new contract into the database.
675    ///
676    /// Inserts only the static values of the contract. To insert the contract slots, balance and
677    /// code please use the `update_contracts` method.
678    ///
679    /// # Arguments
680    /// - `new`: A reference to the new contract state to be inserted.
681    ///
682    /// # Returns
683    /// - A Result with Ok if the operation was successful, and an Err containing `StorageError` if
684    ///   there was an issue inserting the contract into the database. E.g. if the contract already
685    ///   existed.
686    async fn insert_contract(&self, new: &Account) -> Result<(), StorageError>;
687
688    /// Update multiple contracts
689    ///
690    /// Given contract deltas, this method will batch all updates to contracts across a single
691    /// chain.
692    ///
693    /// As changes are versioned by transaction, each changeset needs to be associated with a
694    /// transaction hash. All references transaction are assumed to be already persisted.
695    ///
696    /// # Arguments
697    ///
698    /// - `new`: A reference to a slice of tuples where each tuple has a transaction hash (`TxHash`)
699    ///   and a reference to the state delta (`&Self::Delta`) for that transaction.
700    ///
701    /// # Returns
702    ///
703    /// A Result with `Ok` if the operation was successful, and an `Err` containing
704    /// `StorageError` if there was an issue updating the contracts in the database. E.g. if a
705    /// transaction can't be located by it's reference or accounts refer to a different chain then
706    /// the one specified.
707    async fn update_contracts(&self, new: &[(TxHash, AccountDelta)]) -> Result<(), StorageError>;
708
709    /// Mark a contract as deleted
710    ///
711    /// Issues a soft delete of the contract.
712    ///
713    /// # Parameters
714    /// - `id` The identifier for the contract.
715    /// - `at_tx` The transaction hash which deleted the contract. This transaction is assumed to be
716    ///   in storage already. None retrieves the latest state.
717    ///
718    /// # Returns
719    /// Ok if the deletion was successful, might Err if:
720    ///  - Contract is not present in storage.
721    ///  - Deletion transaction is not present in storage.
722    ///  - Contract was already deleted.
723    async fn delete_contract(&self, id: &ContractId, at_tx: &TxHash) -> Result<(), StorageError>;
724
725    /// Retrieve a account delta between two versions.
726    ///
727    /// Given start version V1 and end version V2, this method will return the
728    /// changes necessary to move from V1 to V2. So if V1 < V2, it will contain
729    /// the changes of all accounts that changed between the two versions with the
730    /// values corresponding to V2. If V2 < V1 then it will contain all the
731    /// slots that changed between the two versions with the values corresponding to V1.
732    ///
733    /// This method is mainly meant to handle reverts, but can also be used to create delta changes
734    /// between two historical version thus providing the basis for creating a backtestable stream
735    /// of messages.
736    ///
737    /// # Parameters
738    ///
739    /// - `chain` The chain for which to generate the delta changes.
740    /// - `start_version` The deltas start version, given a block uses VersionKind::Last behaviour.
741    ///   If None the latest version is assumed.
742    /// - `end_version` The deltas end version, given a block uses VersionKind::Last behaviour.
743    ///
744    /// # Note
745    ///
746    /// A choice to utilize `BlockOrTimestamp` has been made intentionally in
747    /// this scenario as passing a `Version` by user isn't quite logical.
748    /// Support for deltas is limited to the states at the start or end of
749    /// blocks because blockchain reorganization at the transaction level is not
750    /// common.
751    ///
752    /// The decision to use either the beginning or end state of a block is
753    /// automatically determined by the underlying logic. For example, if we are
754    /// tracing back, `VersionKind::First` retrieval mode will be used.
755    /// Conversely, if we're progressing forward, we would apply the
756    /// `VersionKind::Last` semantics.
757    ///
758    /// # Returns
759    /// A map containing the necessary changes to update a state from start_version to end_version.
760    /// Errors if:
761    ///     - The versions can't be located in storage.
762    ///     - There was an error with the database
763    async fn get_accounts_delta(
764        &self,
765        chain: &Chain,
766        start_version: Option<&BlockOrTimestamp>,
767        end_version: &BlockOrTimestamp,
768    ) -> Result<Vec<AccountDelta>, StorageError>;
769
770    /// Saves multiple account balances to storage.
771    ///
772    /// # Parameters
773    /// - `account_balances` The account balances to insert.
774    ///
775    /// # Return
776    /// Ok if all account balances could be inserted, Err if at least one token failed to insert.
777    async fn add_account_balances(
778        &self,
779        account_balances: &[AccountBalance],
780    ) -> Result<(), StorageError>;
781
782    /// Retrieve account balances
783    ///
784    /// # Parameters
785    /// - `chain` The chain of the account balances
786    /// - `accounts` The accounts to query for. If set to `None`, it retrieves balances for all
787    ///   indexed
788    ///  accounts in the chain.
789    /// - `version` Version at which to retrieve balances for. If set to `None`, it retrieves the
790    ///   latest balances.
791    async fn get_account_balances(
792        &self,
793        chain: &Chain,
794        accounts: Option<&[Address]>,
795        version: Option<&Version>,
796    ) -> Result<HashMap<Address, HashMap<Address, AccountBalance>>, StorageError>;
797}
798
799pub trait Gateway:
800    ChainGateway
801    + ContractStateGateway
802    + ExtractionStateGateway
803    + ProtocolGateway
804    + ContractStateGateway
805    + EntryPointGateway
806    + Send
807    + Sync
808{
809}
810
811/// When a value was written: the timestamp of the writing block.
812///
813/// This is the unit of the database's `valid_from`, so the cache orders writes the way the
814/// database versions them. Block timestamps are unique per chain: the extractor adds a
815/// microsecond to a block that shares its second with the previous block. A block header supplies
816/// the timestamp; a snapshot row takes it from its `valid_from`.
817#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
818pub struct WriteTimestamp(NaiveDateTime);
819
820impl WriteTimestamp {
821    pub fn new(block_ts: NaiveDateTime) -> Self {
822        Self(block_ts)
823    }
824
825    pub fn block_ts(&self) -> NaiveDateTime {
826        self.0
827    }
828}
829
830impl From<&Block> for WriteTimestamp {
831    fn from(block: &Block) -> Self {
832        Self::new(block.ts)
833    }
834}
835
836/// Write timestamps of one account's values, one per database row.
837#[derive(Debug, Clone, PartialEq)]
838pub struct AccountWriteTimestamps {
839    pub slots: HashMap<StoreKey, WriteTimestamp>,
840    pub native_balance: WriteTimestamp,
841    pub code: WriteTimestamp,
842    pub token_balances: HashMap<Address, WriteTimestamp>,
843}
844
845impl AccountWriteTimestamps {
846    /// One timestamp for every value of `account`.
847    pub fn uniform(account: &Account, at: WriteTimestamp) -> Self {
848        Self {
849            slots: account
850                .slots
851                .keys()
852                .map(|key| (key.clone(), at))
853                .collect(),
854            native_balance: at,
855            code: at,
856            token_balances: account
857                .token_balances
858                .keys()
859                .map(|token| (token.clone(), at))
860                .collect(),
861        }
862    }
863}
864
865/// One account's live state and the write timestamp of every value: the row's `valid_from`.
866#[derive(Debug, Clone, PartialEq)]
867pub struct AccountSnapshot {
868    pub account: Account,
869    pub written_at: AccountWriteTimestamps,
870}
871
872/// One component's live state, timestamped with the newest `valid_from` among its rows or, for a
873/// component without rows, its `created_at`.
874#[derive(Debug, Clone, PartialEq)]
875pub struct ComponentSnapshot {
876    pub system: ProtocolSystem,
877    pub state: ProtocolComponentState,
878    pub updated_at: WriteTimestamp,
879}
880
881/// All live contracts and components of one chain, read from one database snapshot.
882#[derive(Debug, Clone, PartialEq)]
883pub struct StateSnapshot {
884    pub accounts: Vec<AccountSnapshot>,
885    pub components: Vec<ComponentSnapshot>,
886}
887
888/// Reads all live contracts and components of a chain from one database snapshot.
889#[async_trait]
890pub trait StateSnapshotGateway {
891    /// All live accounts and components of `chain`, every value timestamped with the block
892    /// that wrote its row.
893    ///
894    /// Implementations must read everything from one database snapshot: a row committed after
895    /// the read starts is invisible to every part of the result. In SQL terms, a read-only
896    /// `REPEATABLE READ` transaction or stricter.
897    async fn state_snapshot(&self, chain: &Chain) -> Result<StateSnapshot, StorageError>;
898}