Struct SurfnetSvm

pub struct SurfnetSvm {
    pub inner: LiteSVM,
    pub transactions: HashMap<Signature, SurfnetTransactionStatus>,
    pub transactions_queued_for_confirmation: VecDeque<(VersionedTransaction, Sender<TransactionStatusEvent>)>,
    pub transactions_queued_for_finalization: VecDeque<(Slot, VersionedTransaction, Sender<TransactionStatusEvent>)>,
    pub perf_samples: VecDeque<RpcPerfSample>,
    pub transactions_processed: u64,
    pub connection: SurfnetDataConnection,
    pub latest_epoch_info: EpochInfo,
    pub simnet_events_tx: Sender<SimnetEvent>,
    pub geyser_events_tx: Sender<GeyserEvent>,
}

SurfnetSvm provides a lightweight Solana Virtual Machine (SVM) for testing and simulation.

It supports a local in-memory blockchain state, remote RPC connections, transaction processing, and account management.

It also exposes channels to listen for simulation events (SimnetEvent) and Geyser plugin events (GeyserEvent).

Fields

inner: LiteSVM

transactions: HashMap<Signature, SurfnetTransactionStatus>

transactions_queued_for_confirmation: VecDeque<(VersionedTransaction, Sender<TransactionStatusEvent>)>

transactions_queued_for_finalization: VecDeque<(Slot, VersionedTransaction, Sender<TransactionStatusEvent>)>

perf_samples: VecDeque<RpcPerfSample>

transactions_processed: u64

connection: SurfnetDataConnection

latest_epoch_info: EpochInfo

simnet_events_tx: Sender<SimnetEvent>

geyser_events_tx: Sender<GeyserEvent>

Implementations

impl SurfnetSvm

pub fn new() -> (Self, Receiver<SimnetEvent>, Receiver<GeyserEvent>)

Creates a new instance of SurfnetSvm.

Returns a tuple containing the instance itself, a receiver for simulation events, and a receiver for Geyser plugin events.

pub async fn connect( &mut self, rpc_url: &str, ) -> Result<EpochInfo, Box<dyn Error>>

Connects the SurfnetSvm to a live Solana RPC endpoint.

This updates the internal epoch information and sends connection events over the simulation event channel.

Arguments

• rpc_url - The URL of the Solana RPC endpoint to connect to.

Returns

• Ok(EpochInfo) on success, or an error if the RPC request fails.

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

Airdrops a specified amount of lamports to a single public key.

Arguments

• pubkey - The recipient public key.
• lamports - The amount of lamports to airdrop.

Returns

• TransactionResult indicating success or failure.

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

Airdrops a specified amount of lamports to a list of public keys.

Arguments

• lamports - The amount of lamports to airdrop.
• addresses - A vector of Pubkey recipients.

pub fn expected_rpc_client(&self) -> RpcClient

Returns an RpcClient instance pointing to the currently connected RPC URL.

Panics if the SurfnetSvm is not connected to an RPC endpoint.

pub fn is_connected(&self) -> bool

pub fn get_latest_absolute_slot(&self) -> Slot

Returns the latest known absolute slot from the local epoch info.

pub fn latest_blockhash(&self) -> Hash

Returns the latest blockhash known by the SurfnetSvm.

pub fn new_blockhash(&mut self)

pub fn check_blockhash_is_recent(&self, recent_blockhash: &Hash) -> bool

pub fn set_account( &mut self, pubkey: &Pubkey, account: Account, ) -> SurfpoolResult<()>

Sets an account in the local SVM state.

Arguments

• pubkey - The public key of the account.
• account - The Account to insert.

Returns

• Ok(()) on success, or an error if the operation fails.

pub async fn get_account( &self, pubkey: &Pubkey, strategy: GetAccountStrategy, ) -> Result<Option<Account>, SurfpoolError>

Retrieves an account for the specified public key based on the given strategy.

This function checks the GetAccountStrategy to decide whether to fetch the account from the local cache or from a remote RPC endpoint, falling back to the connection if needed.

Parameters

• pubkey: The public key of the account to retrieve.
• strategy: The strategy to use for fetching the account (LocalOrDefault, ConnectionOrDefault, etc.).

Returns

A Result containing an optional account, which may be None if the account was not found.

pub async fn get_account_mut( &mut self, pubkey: &Pubkey, strategy: GetAccountStrategy, ) -> Result<Option<Account>, SurfpoolError>

Retrieves a mutable account for the specified public key based on the given strategy.

This function works similarly to get_account, but will mutate the underlying state with the Account. Note: if the requested account is executable, the data account is also retrieved and stored.

Parameters

• pubkey: The public key of the account to retrieve.
• strategy: The strategy to use for fetching the account (LocalOrDefault, ConnectionOrDefault, etc.).

Returns

A Result containing an optional mutable account.

pub async fn get_multiple_accounts_mut( &mut self, pubkeys: &Vec<Pubkey>, strategy: GetAccountStrategy, ) -> Result<Vec<Option<Account>>, SurfpoolError>

Retrieves multiple accounts in a mutable fashion, based on the specified strategy.

This function allows fetching multiple accounts at once. It uses different strategies to decide whether to fetch the account from local storage or the network, depending on the availability of the accounts and the given strategy. Note: requested accounts that are executable, are also getting their associate data retrieved and stored.

Parameters

• pubkeys: A vector of public keys for the accounts to retrieve.
• strategy: The strategy for fetching the account information (LocalOrDefault, ConnectionOrDefault, or LocalThenConnectionOrDefault).

Returns

A Result containing a vector of Option<Account> for each requested public key. If the account is found, it is wrapped in Some; otherwise, None will be returned for the missing accounts.

pub async fn get_transaction( &self, signature: &Signature, encoding: Option<UiTransactionEncoding>, ) -> Result<Option<(EncodedConfirmedTransactionWithStatusMeta, TransactionStatus)>, Box<dyn Error>>

Fetches a transaction’s details by its signature.

This function retrieves the details of a transaction based on its signature. It first checks if the transaction is cached locally. If not, it fetches the transaction from the RPC client. The transaction details are returned along with the transaction’s status.

Parameters

• signature: The signature of the transaction to retrieve.
• encoding: An optional parameter specifying the encoding format for the transaction (e.g., Json or other formats).

Returns

Returns a Result containing either:

• Some((EncodedConfirmedTransactionWithStatusMeta, TransactionStatus)) if the transaction was successfully found, or
• None if the transaction is not found.

The EncodedConfirmedTransactionWithStatusMeta contains the full transaction details, and TransactionStatus includes the status of the transaction (e.g., whether it was confirmed).

pub fn send_transaction( &mut self, tx: VersionedTransaction, ) -> TransactionResult

Sends a transaction to the system for execution.

This function attempts to send a transaction to the blockchain. It first increments the transactions_processed counter. Then it sends the transaction to the system and updates its status. If the transaction is successfully processed, it is cached locally, and a “transaction processed” event is sent. If the transaction fails, the error is recorded and an event is sent indicating the failure.

Parameters

• tx: The transaction to send for processing.

Returns

Returns a Result:

• Ok(res) if the transaction was successfully sent and processed, containing the result of the transaction.
• Err(tx_failure) if the transaction failed, containing the error information.

pub fn simulate_transaction( &mut self, tx: VersionedTransaction, ) -> Result<SimulatedTransactionInfo, FailedTransactionMetadata>

pub async fn process_transaction( &mut self, transaction: VersionedTransaction, status_tx: Sender<TransactionStatusEvent>, skip_preflight: bool, ) -> Result<(), SurfpoolError>

Processes a transaction by verifying, simulating, and executing it on the blockchain.

This function processes a transaction with an associated sender for status updates. The transaction is verified for valid signatures, missing accounts are fetched from the network if needed, and the transaction is simulated or executed depending on the configuration.

Parameters

• transaction: The VersionedTransaction to process.
• status_tx: A Sender<TransactionStatusEvent> used to send status updates.
• skip_preflight: A bool indicating whether to skip the preflight simulation step for the transaction.

Returns

Returns a Result:

• Ok(()) if the transaction was successfully processed.
• Err(SurfpoolError) if an error occurred during processing.

pub fn confirm_transactions(&mut self) -> Result<(), SurfpoolError>

Confirms transactions that are queued for confirmation.

This function processes all transactions in the confirmation queue, sending a confirmation event for each transaction. It updates the internal epoch and slot information, ensuring that the latest epoch and slot are reflected in the system. Additionally, it maintains performance samples for the last 30 slots, tracking the number of transactions processed in each slot.

The function performs the following steps:

1. Iterates through the transactions_queued_for_confirmation queue and sends a TransactionStatusEvent::Success event for each transaction, indicating that the transaction has been confirmed.
2. Updates the latest_epoch_info to increment the slot index and absolute slot.
3. If the slot index exceeds the number of slots in the current epoch, it resets the slot index to 0 and increments the epoch.
4. Maintains a rolling window of performance samples, ensuring that only the last 30 slots are retained.
5. Sends a SimnetEvent::ClockUpdate event with the updated clock information.
6. Updates the system’s clock sysvar with the new clock information.

This function is typically called periodically to ensure that transactions are confirmed and the system’s state remains consistent with the passage of time.

pub fn finalize_transactions(&mut self) -> Result<(), SurfpoolError>

Finalizes transactions that are queued for finalization.

This function processes transactions in the finalization queue, sending a TransactionStatusEvent::Success event with the Finalized status for each transaction that has reached the required finalization slot threshold. Transactions that have not yet reached the finalization threshold are requeued for future processing.

The function performs the following steps:

1. Iterates through the transactions_queued_for_finalization queue.
2. For each transaction, checks if the current slot has reached or exceeded the transaction’s finalized_at slot.
3. If the transaction is ready for finalization, sends a TransactionStatusEvent::Success event with the Finalized status.
4. If the transaction is not yet ready for finalization, requeues it for future processing.

This function ensures that transactions are finalized only after the required number of slots have passed, maintaining consistency with the blockchain’s finalization rules.

Returns

• Ok(()) on successful processing of the finalization queue.
• Err(SurfpoolError) if an error occurs during processing.