Struct SurfpoolWsRpc

pub struct SurfpoolWsRpc {
    pub uid: AtomicUsize,
    pub signature_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<Response<RpcSignatureResult>>>>>,
    pub account_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<Response<UiAccount>>>>>,
    pub slot_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<SlotInfo>>>>,
    pub logs_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<Response<RpcLogsResponse>>>>>,
    pub tokio_handle: Handle,
}

WebSocket RPC server implementation for Surfpool.

This struct manages WebSocket subscriptions for both signature status updates and account change notifications in the Surfpool environment. It provides a complete WebSocket RPC interface that allows clients to subscribe to real-time updates from the Solana Virtual Machine (SVM) and handles the lifecycle of WebSocket connections.

Fields

• uid: Atomic counter for generating unique subscription IDs across all subscription types.
• signature_subscription_map: Thread-safe HashMap containing active signature subscriptions, mapping subscription IDs to their notification sinks.
• account_subscription_map: Thread-safe HashMap containing active account subscriptions, mapping subscription IDs to their notification sinks.
• slot_subscription_map: Thread-safe HashMap containing active slot subscriptions, mapping subscription IDs to their notification sinks.
• tokio_handle: Runtime handle for spawning asynchronous subscription monitoring tasks.

Features

• Concurrent Subscriptions: Supports multiple simultaneous subscriptions without blocking.
• Thread Safety: All subscription management operations are thread-safe using RwLock.
• Automatic Cleanup: Subscriptions are automatically cleaned up when completed or unsubscribed.
• Efficient Monitoring: Each subscription runs in its own async task for optimal performance.
• Real-time Updates: Provides immediate notifications when monitored conditions are met.

Usage

This struct implements the Rpc trait and is typically used as part of a larger WebSocket server infrastructure to provide real-time blockchain data to clients.

Notes

• Each subscription is assigned a unique numeric ID for tracking and management.
• The struct maintains separate maps for different subscription types to optimize performance.
• All async operations are managed through the provided Tokio runtime handle.

See Also

• Rpc: The trait interface this struct implements
• RpcAccountSubscribeConfig: Configuration options for account subscriptions

Fields

uid: AtomicUsize

signature_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<Response<RpcSignatureResult>>>>>

account_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<Response<UiAccount>>>>>

slot_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<SlotInfo>>>>

logs_subscription_map: Arc<RwLock<HashMap<SubscriptionId, Sink<Response<RpcLogsResponse>>>>>

tokio_handle: Handle

Trait Implementations

impl Rpc for SurfpoolWsRpc

fn signature_subscribe( &self, meta: Self::Metadata, subscriber: Subscriber<RpcResponse<RpcSignatureResult>>, signature_str: String, config: Option<RpcSignatureSubscribeConfig>, )

Implementation of signature subscription for WebSocket clients.

This method handles the complete lifecycle of signature subscriptions:

1. Validates the provided signature string format
2. Determines the subscription type (received vs commitment-based)
3. Checks if the transaction already exists in the desired state
4. If found and confirmed, immediately notifies the subscriber
5. Otherwise, sets up a continuous monitoring loop
6. Spawns an async task to handle ongoing subscription management

Error Handling

• Rejects subscription with InvalidParams for malformed signatures
• Handles RPC context retrieval failures
• Manages subscription cleanup on completion or failure

Concurrency

Each subscription runs in its own async task, allowing multiple concurrent subscriptions without blocking each other.

fn signature_unsubscribe( &self, _meta: Option<Self::Metadata>, subscription: SubscriptionId, ) -> Result<bool>

Implementation of signature unsubscription for WebSocket clients.

This method removes an active signature subscription from the internal tracking maps, effectively stopping further notifications for that subscription.

Implementation Details

• Attempts to remove the subscription from the active subscriptions map
• Returns success if the subscription existed and was removed
• Returns an error if the subscription ID was not found

Thread Safety

Uses write locks to ensure thread-safe removal from the subscription map.

fn account_subscribe( &self, meta: Self::Metadata, subscriber: Subscriber<RpcResponse<UiAccount>>, pubkey_str: String, config: Option<RpcAccountSubscribeConfig>, )

Implementation of account subscription for WebSocket clients.

This method handles the complete lifecycle of account subscriptions:

1. Validates the provided public key string format
2. Parses the subscription configuration (commitment and encoding)
3. Generates a unique subscription ID and assigns it to the subscriber
4. Spawns an async task to continuously monitor account changes
5. Sends notifications whenever the account state changes

Monitoring Loop

The spawned task runs a continuous loop that:

• Checks if the subscription is still active (not unsubscribed)
• Polls for account updates from the SVM
• Sends notifications to the subscriber when changes occur
• Automatically terminates when the subscription is removed

Error Handling

• Rejects subscription with InvalidParams for malformed public keys
• Handles encoding configuration for account data serialization
• Manages subscription cleanup through the monitoring loop

Performance

Uses efficient polling with minimal CPU overhead and automatic cleanup when subscriptions are no longer needed.

fn account_unsubscribe( &self, _meta: Option<Self::Metadata>, subscription: SubscriptionId, ) -> Result<bool>

Implementation of account unsubscription for WebSocket clients.

This method removes an active account subscription from the internal tracking maps, effectively stopping further notifications for that subscription. The monitoring loop in the corresponding subscription task will detect this removal and automatically terminate.

Implementation Details

• Attempts to remove the subscription from the account subscriptions map
• Returns success if the subscription existed and was removed
• Returns an error if the subscription ID was not found
• The removal triggers automatic cleanup of the monitoring task

Thread Safety

Uses write locks to ensure thread-safe removal from the subscription map. The monitoring task uses read locks to check subscription status, creating a clean synchronization pattern.

type Metadata = Option<SurfpoolWebsocketMeta>

fn slot_subscribe(&self, meta: Self::Metadata, subscriber: Subscriber<SlotInfo>)

Subscribe to slot notifications.

fn slot_unsubscribe( &self, _meta: Option<Self::Metadata>, subscription: SubscriptionId, ) -> Result<bool>

Unsubscribe from slot notifications.

fn logs_subscribe( &self, meta: Self::Metadata, subscriber: Subscriber<RpcResponse<RpcLogsResponse>>, mentions: Option<RpcTransactionLogsFilter>, commitment: Option<CommitmentLevel>, )

Subscribe to logs notifications.

fn logs_unsubscribe( &self, _meta: Option<Self::Metadata>, subscription: SubscriptionId, ) -> Result<bool>

Unsubscribe from logs notifications.

fn to_delegate(self) -> IoDelegate<Self, Self::Metadata>

Create an IoDelegate, wiring rpc calls to the trait methods.