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}