feat(core): enable persistent surfnets

.cargo/config.toml

@@ -1,5 +1,5 @@
 [alias]
-surfpool-install = "install --path crates/cli --locked --force --features supervisor_ui --features version_check"
-surfpool-install-dev = "install --path crates/cli --locked --force --features supervisor_ui"
+surfpool-install = "install --path crates/cli --locked --force --features supervisor_ui --features version_check --features sqlite"
+surfpool-install-dev = "install --path crates/cli --locked --force --features supervisor_ui --features sqlite"
 # useful for local builds that point to local txtx crates - prevents conflicts with the supervisor_ui feature
 surfpool-install-minimal = "install --path crates/cli --locked --force"

Cargo.toml

@@ -139,6 +139,7 @@ solana-signer = { version = "3.0.0", default-features = false }
 solana-slot-hashes = { version = "3.0.0", default-features = false }
 solana-system-interface = { version = "2.0.0", default-features = false }
 solana-sysvar = { version = "3.0.0", default-features = false }
+solana-sysvar-id = { version = "3.0.0", default-features = false }
 solana-transaction = { version = "3.0.0", default-features = false }
 solana-transaction-context = { version = "3.0.0", default-features = false }
 solana-transaction-error = { version = "3.0.0", default-features = false }
@@ -147,7 +148,9 @@ solana-version = { version = "3.0.0", default-features = false }
 spl-associated-token-account-interface = { version = "2.0.0", default-features = false }
 spl-token-2022-interface = { version = "2.0.0", default-features = false }
 spl-token-interface = { version = "2.0.0", default-features = false }
+tempfile = "3.23.0"
 test-case = "^3.3.1"
+thiserror = "2.0"
 tokio = { version = "1.43.0", default-features = false }
 tokio-tungstenite = { version = "=0.20.1", default-features = false }
 toml = { version = "0.8.23", default-features = false }

crates/cli/Cargo.toml

@@ -73,8 +73,8 @@ cli = ["clap/derive", "clap/env", "clap_complete", "toml", "ctrlc", "hiro-system
 supervisor_ui = ["txtx-supervisor-ui/crates_build"]
 explorer = []
 geyser_plugin = ["surfpool-core/geyser_plugin"]
-sqlite = ["surfpool-gql/sqlite"]
-postgres = ["surfpool-gql/postgres"]
+sqlite = ["surfpool-gql/sqlite", "surfpool-core/sqlite"]
+postgres = ["surfpool-gql/postgres", "surfpool-core/postgres"]
 version_check = []
 subgraph = ["surfpool-core/subgraph"]
 

crates/cli/src/cli/mod.rs

@@ -241,6 +241,12 @@ pub struct StartSimnet {
     /// A set of inputs to use for the runbook (eg. surfpool start --runbook-input myInputs.json)
     #[arg(long = "runbook-input", short = 'i')]
     pub runbook_input: Vec<String>,
+    /// Surfnet database connection URL for persistent Surfnets. For an in-memory sqlite database, use ":memory:". For an on-disk sqlite database, use a filename ending in '.sqlite'.
+    #[arg(long = "db")]
+    pub db: Option<String>,
+    /// Unique identifier for this surfnet instance. Used to isolate database storage when multiple surfnets share the same database. Defaults to 0.
+    #[arg(long = "surfnet-id", default_value_t = 0)]
+    pub surfnet_id: u32,
     /// Path to JSON snapshot file(s) to preload accounts from. Can be specified multiple times.
     /// (eg. surfpool start --snapshot ./snapshot1.json --snapshot ./snapshot2.json)
     /// The snapshot format matches the output of surfnet_exportSnapshot RPC method.
@@ -403,6 +409,7 @@ impl StartSimnet {
             },
             feature_config: self.feature_config(),
             skip_signature_verification: false,
+            surfnet_id: self.surfnet_id,
             snapshot,
         }
     }

crates/cli/src/cli/simnet/mod.rs

@@ -60,7 +60,9 @@ pub async fn handle_start_local_surfnet_command(
     }
 
     // We start the simnet as soon as possible, as it needs to be ready for deployments
-    let (mut surfnet_svm, simnet_events_rx, geyser_events_rx) = SurfnetSvm::new();
+    let (mut surfnet_svm, simnet_events_rx, geyser_events_rx) =
+        SurfnetSvm::new_with_db(cmd.db.as_deref(), cmd.surfnet_id)
+            .map_err(|e| format!("Failed to initialize Surfnet SVM: {}", e))?;
 
     // Apply feature configuration from CLI flags
     let feature_config = cmd.feature_config();
@@ -168,7 +170,7 @@ pub async fn handle_start_local_surfnet_command(
     let config_copy = config.clone();
 
     let simnet_events_tx_for_thread = simnet_events_tx.clone();
-    let _handle = hiro_system_kit::thread_named("simnet")
+    let simnet_handle = hiro_system_kit::thread_named("simnet")
         .spawn(move || {
             let future = start_local_surfnet(
                 surfnet_svm,
@@ -188,18 +190,18 @@ pub async fn handle_start_local_surfnet_command(
 
     // Collect events that occur before Ready so we can re-send them to the TUI
     let mut early_events = Vec::new();
-    loop {
+    let initial_transactions = loop {
         match simnet_events_rx.recv() {
             Ok(SimnetEvent::Aborted(error)) => {
                 eprintln!("Error: {}", error);
                 return Err(error);
             }
             Ok(SimnetEvent::Shutdown) => return Ok(()),
-            Ok(SimnetEvent::Ready) => break,
+            Ok(SimnetEvent::Ready(initial_transactions)) => break initial_transactions,
             Ok(other) => early_events.push(other),
             Err(_) => continue,
         }
-    }
+    };
 
     // Re-send early events (like snapshot loading messages) so the TUI receives them
     for event in early_events {
@@ -262,9 +264,13 @@ pub async fn handle_start_local_surfnet_command(
         explorer_handle,
         ctx_cc,
         Some(runloop_terminator),
+        initial_transactions,
     )
     .await;
 
+    // Wait for the simnet thread to finish cleanup (including Drop/checkpoint)
+    let _ = simnet_handle.join();
+
     Ok(())
 }
 
@@ -280,6 +286,7 @@ async fn start_service(
     explorer_handle: Option<ServerHandle>,
     _ctx: Context,
     runloop_terminator: Option<Arc<AtomicBool>>,
+    initial_transactions: u64,
 ) -> Result<(), String> {
     let displayed_url = if cmd.no_studio {
         DisplayedUrl::Datasource(sanitized_config)
@@ -306,12 +313,14 @@ async fn start_service(
             deploy_progress_rx,
             displayed_url,
             breaker,
+            initial_transactions,
         )
         .map_err(|e| format!("{}", e))?;
     }
     if let Some(explorer_handle) = explorer_handle {
         let _ = explorer_handle.stop(true).await;
     }
+
     Ok(())
 }
 
@@ -325,8 +334,11 @@ fn log_events(
 ) -> Result<(), String> {
     let mut deployment_completed = false;
     let do_stop_loop = runloop_terminator.clone();
+    let terminate_tx = simnet_commands_tx.clone();
     ctrlc::set_handler(move || {
         do_stop_loop.store(true, Ordering::Relaxed);
+        // Send terminate command to allow graceful shutdown (Drop to run)
+        let _ = terminate_tx.send(SimnetCommand::Terminate(None));
     })
     .expect("Error setting Ctrl-C handler");
 
@@ -399,7 +411,7 @@ fn log_events(
                         error!("{}", error);
                         return Err(error);
                     }
-                    SimnetEvent::Ready => {}
+                    SimnetEvent::Ready(_) => {}
                     SimnetEvent::Connected(_rpc_url) => {}
                     SimnetEvent::Shutdown => {
                         break;

crates/cli/src/tui/simnet.rs

@@ -285,6 +285,7 @@ impl App {
         deploy_progress_rx: Vec<Receiver<BlockEvent>>,
         displayed_url: DisplayedUrl,
         breaker: Option<Keypair>,
+        initial_transactions: u64,
     ) -> App {
         let theme = Theme::detect();
         let palette = theme.palette();
@@ -328,7 +329,7 @@ impl App {
                 block_height: 0,
                 transaction_count: None,
             },
-            successful_transactions: 0,
+            successful_transactions: initial_transactions as u32,
             events,
             include_debug_logs,
             deploy_progress_rx,
@@ -403,6 +404,7 @@ pub fn start_app(
     deploy_progress_rx: Vec<Receiver<BlockEvent>>,
     displayed_url: DisplayedUrl,
     breaker: Option<Keypair>,
+    initial_transactions: u64,
 ) -> Result<(), Box<dyn Error>> {
     // setup terminal
     enable_raw_mode()?;
@@ -419,6 +421,7 @@ pub fn start_app(
         deploy_progress_rx,
         displayed_url,
         breaker,
+        initial_transactions,
     );
     let res = run_app(&mut terminal, app);
 
@@ -553,7 +556,7 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
                             SimnetEvent::Aborted(_error) => {
                                 break;
                             }
-                            SimnetEvent::Ready => {}
+                            SimnetEvent::Ready(_) => {}
                             SimnetEvent::Connected(_) => {}
                             SimnetEvent::Shutdown => {
                                 break;
@@ -705,10 +708,16 @@ fn run_app<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<(
                 if key_event.kind == KeyEventKind::Press {
                     use KeyCode::*;
                     if key_event.modifiers == KeyModifiers::CONTROL && key_event.code == Char('c') {
+                        // Send terminate command to allow graceful shutdown (Drop to run)
+                        let _ = app.simnet_commands_tx.send(SimnetCommand::Terminate(None));
                         return Ok(());
                     }
                     match key_event.code {
-                        Char('q') | Esc => return Ok(()),
+                        Char('q') | Esc => {
+                            // Send terminate command to allow graceful shutdown (Drop to run)
+                            let _ = app.simnet_commands_tx.send(SimnetCommand::Terminate(None));
+                            return Ok(());
+                        }
                         Down => app.next(),
                         Up => app.previous(),
                         Char('f') | Char('j') => {

crates/core/Cargo.toml

@@ -20,6 +20,7 @@ base64 = { workspace = true }
 bincode = { workspace = true }
 blake3 = { workspace = true }
 borsh = { workspace = true }
+bytemuck = "1.21"
 bs58 = { workspace = true }
 chrono = { workspace = true }
 convert_case = { workspace = true }
@@ -77,16 +78,20 @@ solana-signer = { workspace = true }
 solana-slot-hashes = { workspace = true }
 solana-system-interface = { workspace = true }
 solana-sysvar = { workspace = true }
+solana-sysvar-id = { workspace = true }
 solana-transaction = { workspace = true }
+solana-transaction-context = { workspace = true }
 solana-transaction-error = { workspace = true }
 solana-transaction-status = { workspace = true }
 solana-version = { workspace = true }
 spl-associated-token-account-interface = { workspace = true }
 spl-token-interface = { workspace = true }
 spl-token-2022-interface = { workspace = true }
+thiserror = { workspace = true }
 tokio = { workspace = true }
 uuid = { workspace = true }
 
+surfpool-db = { workspace = true }
 surfpool-subgraph = { workspace = true, optional = true }
 surfpool-types = { workspace = true }
 
@@ -99,8 +104,12 @@ txtx-addon-network-svm = { workspace = true }
 [dev-dependencies]
 test-case = { workspace = true }
 env_logger = "*"
+tempfile = { workspace = true }
 
 [features]
+default = ["sqlite"]
+sqlite = ["surfpool-db/sqlite"]
+postgres = ["surfpool-db/postgres"]
 ignore_tests_ci = []
 geyser_plugin = ["solana-geyser-plugin-manager"]
 subgraph = ["surfpool-subgraph"]

crates/core/src/error.rs

@@ -2,13 +2,16 @@ use std::{fmt::Display, future::Future, pin::Pin};
 
 use crossbeam_channel::TrySendError;
 use jsonrpc_core::{Error, Result};
+use litesvm::error::LiteSVMError;
 use serde::Serialize;
 use serde_json::json;
 use solana_client::{client_error::ClientError, rpc_request::TokenAccountsFilter};
 use solana_clock::Slot;
 use solana_pubkey::Pubkey;
 use solana_transaction_status::EncodeError;
 
+use crate::storage::StorageError;
+
 pub type SurfpoolResult<T> = std::result::Result<T, SurfpoolError>;
 
 #[derive(Debug, Clone)]
@@ -447,3 +450,19 @@ impl SurfpoolError {
         Self(error)
     }
 }
+
+impl From<StorageError> for SurfpoolError {
+    fn from(e: StorageError) -> Self {
+        let mut error = Error::internal_error();
+        error.data = Some(json!(format!("Storage error: {}", e.to_string())));
+        SurfpoolError(error)
+    }
+}
+
+impl From<LiteSVMError> for SurfpoolError {
+    fn from(e: LiteSVMError) -> Self {
+        let mut error = Error::internal_error();
+        error.data = Some(json!(format!("LiteSVM error: {}", e.to_string())));
+        SurfpoolError(error)
+    }
+}

crates/core/src/lib.rs

@@ -15,6 +15,7 @@ pub mod helpers;
 pub mod rpc;
 pub mod runloops;
 pub mod scenarios;
+pub mod storage;
 pub mod surfnet;
 pub mod types;