Struct SurfnetSvmLocker 

pub struct SurfnetSvmLocker(pub Arc<RwLock<SurfnetSvm>>);

Helper function to apply an override to a JSON value using dot notation path

Arguments

• json - The JSON value to modify
• path - Dot-separated path to the field (e.g., “price_message.price”)
• value - The new value to set

Returns

Result indicating success or error

Tuple Fields

0: Arc<RwLock<SurfnetSvm>>

Implementations

impl SurfnetSvmLocker

Functions for reading and writing to the underlying SurfnetSvm instance

pub fn shutdown(&self)

Explicitly shutdown the SVM, performing cleanup like WAL checkpoint for SQLite. This should be called before the application exits to ensure data is persisted.

pub fn with_svm_reader<T, F>(&self, reader: F) -> T

where F: FnOnce(&SurfnetSvm) -> T + Send + Sync,

Executes a read-only operation on the underlying SurfnetSvm by acquiring a blocking read lock. Accepts a closure that receives a shared reference to SurfnetSvm and returns a value.

Returns

The result produced by the closure.

pub fn with_svm_writer<T, F>(&self, writer: F) -> T

where F: FnOnce(&mut SurfnetSvm) -> T + Send + Sync, T: Send + 'static,

Executes a write operation on the underlying SurfnetSvm by acquiring a blocking write lock. Accepts a closure that receives a mutable reference to SurfnetSvm and returns a value.

Returns

The result produced by the closure.

impl SurfnetSvmLocker

Functions for creating and initializing the underlying SurfnetSvm instance

pub fn new(svm: SurfnetSvm) -> Self

Constructs a new SurfnetSvmLocker wrapping the given SurfnetSvm instance.

pub async fn initialize( &self, remote_ctx: &Option<SurfnetRemoteClient>, ) -> SurfpoolResult<()>

Initializes the locked SurfnetSvm with remote-derived startup state when available.

impl SurfnetSvmLocker

Functions for getting accounts from the underlying SurfnetSvm instance or remote client

pub fn get_account_local( &self, pubkey: &Pubkey, ) -> SvmAccessContext<GetAccountResult>

Retrieves a local account from the SVM cache, returning a contextualized result.

pub async fn get_account_local_then_remote( &self, client: &SurfnetRemoteClient, pubkey: &Pubkey, commitment_config: CommitmentConfig, ) -> SurfpoolContextualizedResult<GetAccountResult>

Attempts local retrieval, then fetches from remote if missing, returning a contextualized result.

Does not fetch from remote if the account has been explicitly blocked from remote downloads.

pub async fn get_account( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, pubkey: &Pubkey, factory: Option<AccountFactory>, ) -> SurfpoolContextualizedResult<GetAccountResult>

Retrieves an account, using local or remote based on context, applying a default factory if provided.

pub fn get_multiple_accounts_local( &self, pubkeys: &[Pubkey], ) -> SvmAccessContext<Vec<GetAccountResult>>

Retrieves multiple accounts from local cache, returning a contextualized result.

pub async fn get_multiple_accounts_with_remote_fallback( &self, client: &SurfnetRemoteClient, pubkeys: &[Pubkey], commitment_config: CommitmentConfig, ) -> SurfpoolContextualizedResult<Vec<GetAccountResult>>

Retrieves multiple accounts from local storage, with remote fallback for missing accounts.

Returns accounts in the same order as the input pubkeys array. Accounts found locally are returned as-is; accounts not found locally are fetched from the remote RPC client. Accounts that have been marked offline are not fetched from remote.

pub async fn get_multiple_accounts( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, pubkeys: &[Pubkey], factory: Option<AccountFactory>, ) -> SurfpoolContextualizedResult<Vec<GetAccountResult>>

Retrieves multiple accounts, using local or remote context and applying factory defaults if provided.

pub async fn load_snapshot( &self, snapshot: &BTreeMap<String, Option<AccountSnapshot>>, remote_client: Option<&SurfnetRemoteClient>, commitment_config: CommitmentConfig, ) -> SurfpoolResult<usize>

Loads accounts from a snapshot into the SVM.

This method should be called before geyser plugins start to ensure they receive the account updates with is_startup=true.

Arguments

• snapshot - A map of pubkey strings to optional account snapshots.
  • If the value is Some(AccountSnapshot), the account is loaded directly.
  • If the value is None, the account is fetched from the remote RPC (if available).
• remote_client - Optional remote RPC client to fetch None accounts.
• commitment_config - Commitment level for remote RPC calls.

Returns

The number of accounts successfully loaded.

pub fn get_largest_accounts_local( &self, config: RpcLargestAccountsConfig, ) -> SurfpoolContextualizedResult<Vec<RpcAccountBalance>>

Retrieves largest accounts from local cache, returning a contextualized result.

pub async fn get_largest_accounts_local_then_remote( &self, client: &SurfnetRemoteClient, config: RpcLargestAccountsConfig, commitment_config: CommitmentConfig, ) -> SurfpoolContextualizedResult<Vec<RpcAccountBalance>>

pub async fn get_largest_accounts( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, config: RpcLargestAccountsConfig, ) -> SurfpoolContextualizedResult<Vec<RpcAccountBalance>>

pub fn account_to_rpc_keyed_account<T: ReadableAccount + Send + Sync>( &self, pubkey: &Pubkey, account: &T, config: &RpcAccountInfoConfig, token_mint: Option<Pubkey>, ) -> RpcKeyedAccount

impl SurfnetSvmLocker

Get signatures for Addresses

pub fn get_signatures_for_address_local( &self, pubkey: &Pubkey, config: Option<&RpcSignaturesForAddressConfig>, ) -> SvmAccessContext<Vec<RpcConfirmedTransactionStatusWithSignature>>

Returns local getSignaturesForAddress results in the same newest-first order expected by the Solana RPC.

The implementation has to do more than filter by slot:

• transactions are ordered by descending slot
• transactions within the same slot are ordered by their execution order in the block
• before and until are pagination boundaries in that final ordered stream

To preserve those semantics, we first collect matching transactions, reconstruct their intra-slot ordering from block headers, sort the full result stream, and only then apply the before / until window followed by limit.

pub async fn get_signatures_for_address_local_then_remote( &self, client: &SurfnetRemoteClient, pubkey: &Pubkey, config: Option<&RpcSignaturesForAddressConfig>, ) -> SurfpoolContextualizedResult<Vec<RpcConfirmedTransactionStatusWithSignature>>

pub async fn get_signatures_for_address( &self, remote_ctx: &Option<(SurfnetRemoteClient, ())>, pubkey: &Pubkey, config: Option<&RpcSignaturesForAddressConfig>, ) -> SurfpoolContextualizedResult<Vec<RpcConfirmedTransactionStatusWithSignature>>

impl SurfnetSvmLocker

Functions for getting transactions from the underlying SurfnetSvm instance or remote client

pub async fn get_transaction( &self, remote_ctx: &Option<SurfnetRemoteClient>, signature: &Signature, config: RpcTransactionConfig, ) -> SurfpoolResult<GetTransactionResult>

Retrieves a transaction by signature, using local or remote based on context.

pub fn store_bundle( &self, bundle_id: String, signatures: Vec<String>, ) -> SurfpoolResult<()>

Stores a bundle’s signatures under the given bundle ID.

pub fn get_bundle(&self, bundle_id: &str) -> Option<Vec<String>>

Retrieves the list of transaction signatures for a previously stored bundle.

Returns None when there is no local entry for bundle_id (or the backing store read fails). This is not an “invalid id” signal: callers such as Jito getBundleStatuses treat None as “no data” and return a null RPC result rather than an error.

pub fn get_transaction_local( &self, signature: &Signature, config: &RpcTransactionConfig, ) -> SurfpoolResult<GetTransactionResult>

Retrieves a transaction from local cache, returning a contextualized result.

pub async fn get_transaction_local_then_remote( &self, client: &SurfnetRemoteClient, signature: &Signature, config: RpcTransactionConfig, ) -> SurfpoolResult<GetTransactionResult>

Retrieves a transaction locally then from remote if missing, returning a contextualized result.

impl SurfnetSvmLocker

Functions for simulating and processing transactions in the underlying SurfnetSvm instance

pub fn simulate_transaction( &self, transaction: VersionedTransaction, sigverify: bool, ) -> Result<SimulatedTransactionInfo, FailedTransactionMetadata>

Simulates a transaction on the SVM, returning detailed info or failure metadata.

pub fn is_instruction_profiling_enabled(&self) -> bool

pub fn get_profiling_map_capacity(&self) -> usize

pub async fn process_transaction( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, transaction: VersionedTransaction, status_tx: Sender<TransactionStatusEvent>, skip_preflight: bool, sigverify: bool, ) -> SurfpoolResult<()>

pub async fn profile_transaction( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, transaction: VersionedTransaction, tag: Option<String>, ) -> SurfpoolContextualizedResult<Uuid>

impl SurfnetSvmLocker

Functions for writing account updates to the underlying SurfnetSvm instance

pub fn write_account_update(&self, account_update: GetAccountResult)

Writes a single account update into the SVM state if present.

pub fn write_multiple_account_updates( &self, account_updates: &[GetAccountResult], )

Writes multiple account updates into the SVM state when any are present.

pub fn reset_account( &self, pubkey: Pubkey, include_owned_accounts: bool, ) -> SurfpoolResult<()>

Resets an account in the SVM state for refresh/streaming.

This function coordinates the reset of accounts by removing them from the local cache, allowing them to be fetched fresh from mainnet on the next access. It handles program accounts (including their program data accounts) and can optionally cascade the reset to all accounts owned by a program.

pub async fn reset_network( &self, remote_ctx: &Option<SurfnetRemoteClient>, ) -> SurfpoolResult<()>

Resets SVM state and clears all offline account entries.

This function coordinates the reset of the entire network state. It also clears the offline account set so all accounts can be fetched from mainnet again.

pub async fn insert_offline_account( &self, pubkey: Pubkey, include_owned_accounts: bool, ) -> SurfpoolResult<()>

Marks an account as offline, preventing it from being downloaded from the remote RPC.

When include_owned_accounts is enabled, this also marks accounts as offline that are already known locally. Accounts discovered later through direct remote fetches are rejected lazily if they are owned by an offline owner.

pub fn stream_account( &self, pubkey: Pubkey, include_owned_accounts: bool, ) -> SurfpoolResult<()>

Streams an account by its pubkey.

pub fn get_streamed_accounts(&self) -> Vec<(String, bool)>

pub fn remove_offline_account( &self, pubkey: Pubkey, include_owned_accounts: bool, ) -> SurfpoolResult<()>

Removes an account from the offline account set.

This allows the account to be fetched from mainnet again if requested. This is useful when resetting an account for a refresh/stream operation.

pub fn is_account_offline(&self, pubkey: &Pubkey) -> bool

Returns true if the given pubkey is marked offline.

pub fn get_offline_account_owners(&self) -> Vec<Pubkey>

Gets all owners whose accounts are marked offline.

pub fn register_scenario( &self, scenario: Scenario, slot: Option<Slot>, ) -> SurfpoolResult<()>

Registers a scenario for execution

pub async fn materialize_overrides_for_slot( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, slot: Slot, ) -> SurfpoolResult<()>

Materializes overrides for a specific slot (not necessarily the current slot)

impl SurfnetSvmLocker

Token account related functions

pub async fn get_token_accounts_by_owner( &self, remote_ctx: &Option<SurfnetRemoteClient>, owner: Pubkey, filter: &TokenAccountsFilter, config: &RpcAccountInfoConfig, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

Fetches all token accounts for an owner, returning remote results and missing pubkeys contexts.

pub fn get_token_accounts_by_owner_local( &self, owner: Pubkey, filter: &TokenAccountsFilter, config: &RpcAccountInfoConfig, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

pub async fn get_token_accounts_by_owner_local_then_remote( &self, owner: Pubkey, filter: &TokenAccountsFilter, remote_client: &SurfnetRemoteClient, config: &RpcAccountInfoConfig, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

pub async fn get_token_accounts_by_delegate( &self, remote_ctx: &Option<SurfnetRemoteClient>, delegate: Pubkey, filter: &TokenAccountsFilter, config: &RpcAccountInfoConfig, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

impl SurfnetSvmLocker

Token account by delegate related functions

pub fn get_token_accounts_by_delegate_local( &self, delegate: Pubkey, filter: &TokenAccountsFilter, config: &RpcAccountInfoConfig, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

pub async fn get_token_accounts_by_delegate_local_then_remote( &self, delegate: Pubkey, filter: &TokenAccountsFilter, remote_client: &SurfnetRemoteClient, config: &RpcAccountInfoConfig, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

impl SurfnetSvmLocker

Get largest account related account

pub fn get_token_largest_accounts_local( &self, mint: &Pubkey, ) -> SvmAccessContext<Vec<RpcTokenAccountBalance>>

pub async fn get_token_largest_accounts_local_then_remote( &self, client: &SurfnetRemoteClient, mint: &Pubkey, commitment_config: CommitmentConfig, ) -> SurfpoolContextualizedResult<Vec<RpcTokenAccountBalance>>

pub async fn get_token_largest_accounts( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, mint: &Pubkey, ) -> SurfpoolContextualizedResult<Vec<RpcTokenAccountBalance>>

Fetches the largest token accounts for a specific mint, returning contextualized results.

impl SurfnetSvmLocker

Address lookup table related functions

pub fn get_pubkeys_from_message( &self, message: &VersionedMessage, all_transaction_lookup_table_addresses: Option<Vec<&Pubkey>>, ) -> Vec<Pubkey>

Extracts pubkeys from a VersionedMessage, resolving address lookup tables as needed.

pub async fn get_loaded_addresses( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, message: &VersionedMessage, ) -> SurfpoolResult<Option<TransactionLoadedAddresses>>

Gets addresses loaded from on-chain lookup tables from a VersionedMessage.

pub async fn get_lookup_table_addresses( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, address_table_lookup: &MessageAddressTableLookup, transaction_loaded_addresses: &mut TransactionLoadedAddresses, ) -> SurfpoolResult<()>

Retrieves loaded addresses from a lookup table account, validating owner and indices.

impl SurfnetSvmLocker

Profiling helper functions

pub fn estimate_compute_units( &self, transaction: &VersionedTransaction, ) -> SvmAccessContext<ComputeUnitsEstimationResult>

Estimates compute units for a transaction via contextualized simulation.

pub fn get_profile_result( &self, signature_or_uuid: UuidOrSignature, config: &RpcProfileResultConfig, ) -> SurfpoolResult<Option<UiKeyedProfileResult>>

Returns the profile result for a given signature or UUID, and whether it exists in the SVM.

pub fn encode_ui_keyed_profile_result( &self, profile: KeyedProfileResult, config: &RpcProfileResultConfig, ) -> UiKeyedProfileResult

pub fn get_profile_results_by_tag( &self, tag: String, config: &RpcProfileResultConfig, ) -> SurfpoolResult<Option<Vec<UiKeyedProfileResult>>>

Returns the profile results for a given tag.

pub fn register_idl(&self, idl: Idl, slot: Option<Slot>) -> SurfpoolResult<()>

pub fn get_idl(&self, address: &Pubkey, slot: Option<Slot>) -> Option<Idl>

pub fn get_forged_account_data( &self, account_pubkey: &Pubkey, account_data: &[u8], idl: &Idl, overrides: &HashMap<String, Value>, ) -> SurfpoolResult<Vec<u8>>

Forges account data by decoding with IDL, applying overrides, and re-encoding.

Arguments

• account_pubkey - The public key of the account (used for error messages)
• account_data - The raw account data bytes
• idl - The IDL for decoding/encoding the account data
• overrides - HashMap of field paths (dot notation) to values to override

Returns

The modified account data bytes with discriminator Forges account data by applying overrides to existing account data

This delegates to the SurfnetSvm implementation.

Arguments

• account_pubkey - The account address (for error messages)
• account_data - The original account data bytes
• idl - The IDL for the account’s program
• overrides - Map of field paths to new values

Returns

The forged account data as bytes, or an error

impl SurfnetSvmLocker

Program account related functions

pub async fn clone_program_account( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, source_program_id: &Pubkey, destination_program_id: &Pubkey, ) -> SurfpoolContextualizedResult<()>

Clones a program account from source to destination, handling upgradeable loader state.

pub async fn set_program_authority( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, program_id: Pubkey, new_authority: Option<Pubkey>, ) -> SurfpoolContextualizedResult<()>

pub async fn get_program_accounts( &self, remote_ctx: &Option<SurfnetRemoteClient>, program_id: &Pubkey, account_config: RpcAccountInfoConfig, filters: Option<Vec<RpcFilterType>>, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

pub fn get_program_accounts_local( &self, program_id: &Pubkey, account_config: RpcAccountInfoConfig, filters: Option<Vec<RpcFilterType>>, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

Retrieves program accounts from the local SVM cache, returning a contextualized result.

pub fn encode_ui_account( &self, pubkey: &Pubkey, account: &Account, encoding: UiAccountEncoding, additional_data: Option<AccountAdditionalDataV3>, data_slice: Option<UiDataSliceConfig>, ) -> UiAccount

pub async fn get_program_accounts_local_then_remote( &self, client: &SurfnetRemoteClient, program_id: &Pubkey, account_config: RpcAccountInfoConfig, filters: Option<Vec<RpcFilterType>>, ) -> SurfpoolContextualizedResult<Vec<RpcKeyedAccount>>

Retrieves program accounts from the local cache and remote client, combining results.

impl SurfnetSvmLocker

pub fn get_first_local_slot(&self) -> Option<Slot>

Returns the first local slot (the genesis_slot when this surfnet started). Since empty blocks can be reconstructed on-the-fly, all slots from genesis_slot onwards are valid.

pub async fn get_block( &self, remote_ctx: &Option<SurfnetRemoteClient>, slot: &Slot, config: &RpcBlockConfig, ) -> SurfpoolContextualizedResult<Option<UiConfirmedBlock>>

pub fn get_block_local( &self, slot: &Slot, config: &RpcBlockConfig, ) -> SurfpoolResult<Option<UiConfirmedBlock>>

pub fn get_genesis_hash_local(&self) -> SvmAccessContext<Hash>

pub async fn get_genesis_hash( &self, remote_ctx: &Option<SurfnetRemoteClient>, ) -> SurfpoolContextualizedResult<Hash>

impl SurfnetSvmLocker

Pass through functions for accessing the underlying SurfnetSvm instance

pub fn simnet_events_tx(&self) -> Sender<SimnetEvent>

Returns a sender for simulation events from the underlying SVM.

pub fn get_epoch_info(&self) -> EpochInfo

Retrieves the latest epoch info from the underlying SVM.

pub fn time_travel( &self, key: Option<(Hash, String)>, simnet_command_tx: Sender<SimnetCommand>, config: TimeTravelConfig, ) -> SurfpoolResult<EpochInfo>

pub fn get_latest_absolute_slot(&self) -> Slot

Retrieves the latest absolute slot from the underlying SVM.

pub fn get_latest_blockhash(&self, config: &CommitmentConfig) -> Option<Hash>

Retrieves the latest blockhash for the given commitment config from the underlying SVM.

pub fn latest_absolute_blockhash(&self) -> Hash

pub fn get_slot_for_commitment(&self, commitment: &CommitmentConfig) -> Slot

pub fn airdrop( &self, pubkey: &Pubkey, lamports: u64, ) -> Result<TransactionResult, AirdropError>

Executes an airdrop via the underlying SVM.

pub fn airdrop_pubkeys(&self, lamports: u64, addresses: &[Pubkey])

Executes a batch airdrop via the underlying SVM.

pub async fn confirm_current_block( &self, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, ) -> SurfpoolResult<()>

Confirms the current block on the underlying SVM, returning Ok(()) or an error.

pub fn subscribe_for_signature_updates( &self, signature: &Signature, subscription_type: SignatureSubscriptionType, ) -> Receiver<(Slot, Option<TransactionError>)>

Subscribes for signature updates (confirmed/finalized) and returns a receiver of events.

pub fn subscribe_for_account_updates( &self, account_pubkey: &Pubkey, encoding: Option<UiAccountEncoding>, ) -> Receiver<UiAccount>

Subscribes for account updates and returns a receiver of account updates.

pub fn subscribe_for_program_updates( &self, program_id: &Pubkey, encoding: Option<UiAccountEncoding>, filters: Option<Vec<RpcFilterType>>, ) -> Receiver<RpcKeyedAccount>

Subscribes for program account updates and returns a receiver of keyed account updates.

pub fn subscribe_for_slot_updates(&self) -> Receiver<SlotInfo>

Subscribes for slot updates and returns a receiver of slot updates.

pub fn subscribe_for_slots_updates(&self) -> Receiver<Arc<SlotUpdate>>

Subscribes for tagged slotsUpdatesSubscribe notifications and returns a receiver of shared SlotUpdate events.

pub fn subscribe_for_logs_updates( &self, commitment_level: &CommitmentLevel, filter: &RpcTransactionLogsFilter, ) -> Receiver<(Slot, RpcLogsResponse)>

Subscribes for logs updates and returns a receiver of logs updates.

pub fn subscribe_for_snapshot_import_updates( &self, snapshot_url: &str, snapshot_id: &str, ) -> Receiver<SnapshotImportNotification>

Subscribes for snapshot import updates and returns a receiver of snapshot import notifications. This method spawns a background task that fetches the snapshot and loads it via load_snapshot.

pub fn runbook_executions(&self) -> Vec<RunbookExecutionStatusReport>

pub fn start_runbook_execution(&self, runbook_id: String)

pub fn complete_runbook_execution( &self, runbook_id: String, error: Option<Vec<String>>, re_enable_ix_profiling: bool, )

pub fn export_snapshot( &self, config: ExportSnapshotConfig, ) -> SurfpoolResult<BTreeMap<String, AccountSnapshot>>

pub fn get_start_time(&self) -> SystemTime

impl SurfnetSvmLocker

Helpers for writing program accounts

pub async fn write_program( &self, program_id: Pubkey, authority: Option<Pubkey>, offset: usize, data: &[u8], remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, ) -> SurfpoolResult<()>

pub async fn get_or_create_program_account( &self, program_id: Pubkey, program_data_address: Pubkey, remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, ) -> SurfpoolResult<Account>

pub async fn write_program_data_account_with_offset( &self, program_id: Pubkey, authority: Option<Pubkey>, program_data_address: Pubkey, offset: usize, data: &[u8], remote_ctx: &Option<(SurfnetRemoteClient, CommitmentConfig)>, ) -> SurfpoolResult<Account>

Trait Implementations

impl Clone for SurfnetSvmLocker

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.