[replay] Refactored data store to a separate crate (#24436)

## Description 

This PR refactors data stores used by the replay tool into a separate
crate so that it can be more easily used by other clients, in
particular, the upcoming forking tool.

It's mostly about shuffling files around, with dependency updates and
some minor renamings. The exception here is that file cache directory is
has been renamed from `~/.replay_data_store` to `~/.sui_data_store`

While the forking tool likely will only need object retrieval, it seemed
to make sense to refactor all existing stores as perhaps they could be
of use to other clients (and forking tool can simply skip using the
stores/queries it does not need)

## Test plan 

Tested manually that the replay tool still builds and replays
transactions correctly (as does Sui CLI)

Author: awelc

Cargo.lock

@@ -110,6 +110,7 @@ members = [
   "crates/sui-cost",
   "crates/sui-data-ingestion",
   "crates/sui-data-ingestion-core",
+  "crates/sui-data-store",
   "crates/sui-deepbook-indexer",
   "crates/sui-default-config",
   "crates/sui-display",
@@ -693,6 +694,7 @@ sui-core = { path = "crates/sui-core" }
 sui-cost = { path = "crates/sui-cost" }
 sui-data-ingestion = { path = "crates/sui-data-ingestion" }
 sui-data-ingestion-core = { path = "crates/sui-data-ingestion-core" }
+sui-data-store = { path = "crates/sui-data-store" }
 sui-default-config = { path = "crates/sui-default-config" }
 sui-display = { path = "crates/sui-display" }
 sui-e2e-tests = { path = "crates/sui-e2e-tests" }

Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "sui-data-store"
+version = "0.1.0"
+authors = ["Mysten Labs <[email protected]>"]
+license = "Apache-2.0"
+publish = false
+edition = "2024"
+
+[dependencies]
+anyhow.workspace = true
+bcs.workspace = true
+chrono.workspace = true
+csv.workspace = true
+cynic.workspace = true
+fastcrypto.workspace = true
+lru.workspace = true
+reqwest = { workspace = true, features = ["json"] }
+serde.workspace = true
+sui-config.workspace = true
+sui-types.workspace = true
+tokio = { workspace = true, features = ["full"] }
+tracing.workspace = true
+
+[build-dependencies]
+cynic-codegen.workspace = true

crates/sui-data-store/Cargo.toml

@@ -0,0 +1,96 @@
+# sui-data-store
+
+Multi-tier caching data store for Sui blockchain data.
+
+This crate provides a flexible data store abstraction for retrieving and caching
+Sui blockchain data (transactions, epochs, objects). The stores are loosely modeled
+after the GraphQL schema in `crates/sui-indexer-alt-graphql/schema.graphql`.
+
+## Core Traits
+
+- `TransactionStore` - Retrieve transaction data and effects by digest
+- `EpochStore` - Retrieve epoch information and protocol configuration
+- `ObjectStore` - Retrieve objects by their keys with flexible version queries
+
+The read traits above have corresponding writer traits (`TransactionStoreWriter`,
+`EpochStoreWriter`, `ObjectStoreWriter`) for stores that support write-back caching.
+
+## Store Implementations
+
+| Store | Description | Read | Write |
+|-------|-------------|------|-------|
+| `DataStore` | Remote GraphQL-backed store (mainnet/testnet) | Yes | No |
+| `FileSystemStore` | Persistent local disk cache | Yes | Yes |
+| `InMemoryStore` | Unbounded in-memory cache | Yes | Yes |
+| `LruMemoryStore` | Bounded LRU cache | Yes | Yes |
+| `ReadThroughStore` | Composable two-tier caching pattern | Yes | Yes* |
+
+\* `ReadThroughStore` delegates writes to its secondary (backing) store.
+
+## Architecture
+
+The typical 3-tier cache composition: Memory → FileSystem → GraphQL
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Client Code                              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              ReadThroughStore<Memory, Inner>                    │
+│      Fast in-memory cache (LruMemoryStore or InMemoryStore)     │
+└─────────────────────────────────────────────────────────────────┘
+                              │ cache miss
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│           ReadThroughStore<FileSystem, Remote>                  │
+│         Persistent disk cache (FileSystemStore)                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │ cache miss
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    DataStore (GraphQL)                          │
+│              Remote data source (mainnet/testnet)               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Composition Examples
+
+Use `ReadThroughStore<Primary, Secondary>` to compose cache layers:
+
+```rust
+use sui_data_store::{Node, stores::{DataStore, LruMemoryStore, ReadThroughStore, FileSystemStore}};
+
+// Full 3-tier: Memory → FileSystem → GraphQL (typical production setup)
+let graphql = DataStore::new(Node::Mainnet);
+let disk = FileSystemStore::new(Node::Mainnet)?;
+let disk_with_remote = ReadThroughStore::new(disk, graphql);
+let memory = LruMemoryStore::new(Node::Mainnet);
+let store = ReadThroughStore::new(memory, disk_with_remote);
+
+// 2-tier: Memory + FileSystem (e.g., CI testing with pre-populated disk cache)
+let disk = FileSystemStore::new(Node::Mainnet)?;
+let memory = LruMemoryStore::new(Node::Mainnet);
+let store = ReadThroughStore::new(memory, disk);
+```
+
+## Version Queries
+
+The `ObjectStore` trait supports three query modes via `VersionQuery`:
+
+- `Version(v)` - Request object at exact version `v`
+- `RootVersion(v)` - Request object at version `<= v` (for dynamic field roots)
+- `AtCheckpoint(c)` - Request object as it existed at checkpoint `c`
+
+## Network Configuration
+
+Use the `Node` enum to configure which network to connect to:
+
+```rust
+use sui_data_store::Node;
+
+let mainnet = Node::Mainnet;
+let testnet = Node::Testnet;
+let custom = Node::Custom("https://my-rpc.example.com".to_string());
+```

crates/sui-data-store/README.md

@@ -4,12 +4,12 @@
 //! GQL Queries
 //! Interface to the rpc for the gql schema defined in `crates\sui-indexer-alt-graphql/schema.graphql`.
 //! Built in 3 modules: epoch_query, txn_query, object_query.
-//! No GQL type escapes this module. From here we return structures defined by the replay tool
+//! No GQL type escapes this module. From here we return structures defined in this crate
 //! or bcs encoded data of runtime structures.
 //!
 //! This module is private to the `DataStore` and packcaged in its own module for convenience.
 
-use crate::{DataStore, replay_interface::EpochData};
+use crate::{EpochData, stores::DataStore};
 use anyhow::{Context, Error, anyhow};
 use cynic::QueryBuilder;
 use fastcrypto::encoding::{Base64 as CryptoBase64, Encoding};
@@ -204,7 +204,7 @@ pub(crate) mod object_query {
     use sui_types::object::Object;
 
     use super::*;
-    use crate::replay_interface;
+    use crate::{ObjectKey as GqlObjectKey, VersionQuery};
 
     #[derive(cynic::Scalar, Debug, Clone)]
     #[cynic(graphql_type = "SuiAddress")]
@@ -236,10 +236,7 @@ pub(crate) mod object_query {
     }
 
     #[derive(cynic::QueryFragment)]
-    #[cynic(
-        graphql_type = "Object",
-        schema_module = "crate::data_stores::gql_queries::schema"
-    )]
+    #[cynic(graphql_type = "Object", schema_module = "crate::gql_queries::schema")]
     pub(crate) struct ObjectFragment {
         #[allow(dead_code)]
         pub address: SuiAddress,
@@ -253,7 +250,7 @@ pub(crate) mod object_query {
     const MAX_KEYS_SIZE: usize = 30;
 
     pub(crate) async fn query(
-        keys: &[replay_interface::ObjectKey],
+        keys: &[GqlObjectKey],
         data_store: &DataStore,
     ) -> Result<Vec<Option<(Object, u64)>>, Error> {
         let mut keys = keys
@@ -306,20 +303,20 @@ pub(crate) mod object_query {
         Ok(objects)
     }
 
-    impl From<replay_interface::ObjectKey> for ObjectKey {
-        fn from(key: replay_interface::ObjectKey) -> Self {
+    impl From<GqlObjectKey> for ObjectKey {
+        fn from(key: GqlObjectKey) -> Self {
             ObjectKey {
                 address: SuiAddress(key.object_id.to_string()),
                 version: match key.version_query {
-                    replay_interface::VersionQuery::Version(v) => Some(v),
+                    VersionQuery::Version(v) => Some(v),
                     _ => None,
                 },
                 root_version: match key.version_query {
-                    replay_interface::VersionQuery::RootVersion(v) => Some(v),
+                    VersionQuery::RootVersion(v) => Some(v),
                     _ => None,
                 },
                 at_checkpoint: match key.version_query {
-                    replay_interface::VersionQuery::AtCheckpoint(v) => Some(v),
+                    VersionQuery::AtCheckpoint(v) => Some(v),
                     _ => None,
                 },
             }

crates/sui-replay-2/build.rs renamed to crates/sui-data-store/build.rs

@@ -1,20 +1,39 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-//! Logical stores needed by the replay tool.
-//! Those stores are loosely modeled after the GQL schema in
-//! `crates/sui-indexer-alt-graphql/schema.graphql`.
-//! A `TransactionStore` is used to retrieve transaction data and effects by digest.
-//! An `EpochStore` is used to retrieve epoch information and protocol configuration.
-//! An `ObjectStore` is used to retrieve objects by their keys, with different query options.
+//! Multi-tier caching data store for Sui blockchain data.
 //!
-//! Data is usually retrieved by getting BCS-encoded data rather than navigating the
-//! GQL schema.
-//! Essentially the code uses the schema to retrieve the data, deserializes it into runtime
-//! structures, and then operates on those.
+//! This crate provides a flexible data store abstraction for retrieving and caching
+//! Sui blockchain data (transactions, epochs, objects). The stores are loosely modeled
+//! after the GQL schema in `crates/sui-indexer-alt-graphql/schema.graphql`.
 //!
-//! A `DataStore` with reasonable defaults is provided for convenience (`data_store.rs`).
-//! Other styles of data stores are also provided in `data_stores` for different use cases.
+//! ## Core Traits
+//!
+//! - [`TransactionStore`] - Retrieve transaction data and effects by digest
+//! - [`EpochStore`] - Retrieve epoch information and protocol configuration
+//! - [`ObjectStore`] - Retrieve objects by their keys with flexible version queries
+//!
+//! ## Store Implementations
+//!
+//! - [`stores::DataStore`] - Remote GraphQL-backed store (mainnet/testnet)
+//! - [`stores::FileSystemStore`] - Persistent local disk cache
+//! - [`stores::InMemoryStore`] - Unbounded in-memory cache
+//! - [`stores::LruMemoryStore`] - Bounded LRU cache
+//! - [`stores::ReadThroughStore`] - Composable two-tier caching pattern
+//!
+//! ## Composition
+//!
+//! Use `ReadThroughStore<Primary, Secondary>` to compose cache layers:
+//! - `ReadThroughStore<LruMemoryStore, DataStore>` - LRU + remote
+//! - `ReadThroughStore<InMemoryStore, FileSystemStore>` - Memory + disk
+//!   (e.g., for testing in CI with pre-populated disk cache)
+
+mod gql_queries;
+pub mod node;
+pub mod stores;
+
+// Re-export commonly used types
+pub use node::Node;
 
 use anyhow::{Error, Result};
 use std::io::Write;
@@ -27,7 +46,7 @@ use sui_types::{
 // Data store read traits
 // ============================================================================
 
-/// Transaction data with effects and checkpoint required to replay a transaction.
+/// Transaction data with effects and checkpoint.
 #[derive(Clone, Debug)]
 pub struct TransactionInfo {
     pub data: TransactionData,
@@ -36,10 +55,9 @@ pub struct TransactionInfo {
 }
 
 /// A `TransactionStore` has to be able to retrieve transaction data for a given digest.
-/// To replay a transaction the data provided to
-/// `sui_execution::executor::Executor::execute_transaction_to_effects` must be available.
-/// Some of that data is not provided by the user. It is naturally available at runtime on a
-/// live system and later saved in effects and in the context of a checkpoint.
+/// The data provided to `sui_execution::executor::Executor::execute_transaction_to_effects`
+/// must be available. Some of that data is not provided by the user. It is naturally available
+/// at runtime on a live system and later saved in effects and in the context of a checkpoint.
 pub trait TransactionStore {
     /// Given a transaction digest, return transaction info including data, effects,
     /// and the checkpoint that transaction was executed in.
@@ -50,7 +68,7 @@ pub trait TransactionStore {
     ) -> Result<Option<TransactionInfo>, Error>;
 }
 
-/// Epoch data required to reaplay a transaction.
+/// Epoch data.
 #[derive(Clone, Debug)]
 pub struct EpochData {
     pub epoch_id: u64,
@@ -95,7 +113,7 @@ pub enum VersionQuery {
 ///
 /// This trait can execute a subset of what is allowed by
 /// `crates/sui-indexer-alt-graphql/schema.graphql::multiGetObjects`.
-/// That query likely allows more than what the replay tool needs, which is fairly limited in
+/// That query likely allows more than what most clients need, which is fairly limited in
 /// its usage.
 pub trait ObjectStore {
     /// Retrieve objects by their keys, with different query options.
@@ -116,7 +134,7 @@ pub trait ObjectStore {
 // we want to revisit in the future.
 
 /// A trait to set up the data store.
-/// This is used to setup internal state of the data store before starting the replay.
+/// This is used to setup internal state of the data store before use.
 /// At the moment is exclusively used by the FileSystemStore to map network to chain id.
 pub trait SetupStore {
     /// Set up the data store.