solana_kit_rpc_subscriptions_channel_websocket #

WebSocket channel transport for Solana RPC subscriptions in the Solana Kit Dart SDK.

This is the Dart port of @solana/rpc-subscriptions-channel-websocket from the Solana TypeScript SDK.

Installation #

Add solana_kit_rpc_subscriptions_channel_websocket to your pubspec.yaml:

dependencies:
  solana_kit_rpc_subscriptions_channel_websocket:

Or, if you are using the umbrella package:

dependencies:
  solana_kit:

Documentation #

• Package page: https://pub.dev/packages/solana_kit_rpc_subscriptions_channel_websocket
• API reference: https://pub.dev/documentation/solana_kit_rpc_subscriptions_channel_websocket/latest/

Usage #

Creating a WebSocket channel #

The createWebSocketChannel function opens a WebSocket connection and returns an RpcSubscriptionsChannel that supports the DataPublisher interface for receiving messages and errors.

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  final channel = await createWebSocketChannel(
    WebSocketChannelConfig(
      url: Uri.parse('wss://api.devnet.solana.com'),
      signal: controller.signal,
    ),
  );

  // Subscribe to incoming messages.
  channel.on('message', (data) {
    print('Received: $data');
  });

  // Subscribe to errors.
  channel.on('error', (error) {
    print('Error: $error');
  });

  // Send a message through the channel.
  await channel.send('{"jsonrpc":"2.0","id":1,"method":"slotSubscribe"}');

  // Later, close the channel.
  controller.abort();
}

Abort lifecycle management #

The AbortController and AbortSignal classes manage the lifecycle of WebSocket connections. When you abort the signal, the WebSocket is closed with a normal closure code (1000).

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  // Check signal state.
  print(controller.signal.isAborted); // false

  // Open a channel with the signal.
  final channel = await createWebSocketChannel(
    WebSocketChannelConfig(
      url: Uri.parse('wss://api.devnet.solana.com'),
      signal: controller.signal,
    ),
  );

  // Abort with a reason.
  controller.abort('User cancelled');

  print(controller.signal.isAborted); // true
  print(controller.signal.reason); // 'User cancelled'

  // Sending on a closed channel throws SolanaError with code
  // rpcSubscriptionsChannelConnectionClosed.
}

Waiting for abort asynchronously #

The AbortSignal provides a future that completes when the signal is aborted. This is useful for composing with other async operations.

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  // Wait for the signal to fire.
  controller.signal.future.then((_) {
    print('Signal was aborted!');
  });

  // Abort after some delay.
  await Future<void>.delayed(Duration(seconds: 5));
  controller.abort();
  // Prints: 'Signal was aborted!'
}

Configuring the send buffer #

The sendBufferHighWatermark parameter controls how much data is allowed into the WebSocket's send buffer before messages are queued on the client.

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  final channel = await createWebSocketChannel(
    WebSocketChannelConfig(
      url: Uri.parse('wss://api.devnet.solana.com'),
      sendBufferHighWatermark: 256 * 1024, // 256KB buffer.
      signal: controller.signal,
    ),
  );

  // Use the channel...
  controller.abort();
}

Error handling #

The function throws SolanaError in several situations:

import 'package:solana_kit_errors/solana_kit_errors.dart';
import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  try {
    final channel = await createWebSocketChannel(
      WebSocketChannelConfig(
        url: Uri.parse('wss://invalid-host.example.com'),
        signal: controller.signal,
      ),
    );
  } on SolanaError catch (e) {
    if (isSolanaError(e, SolanaErrorCode.rpcSubscriptionsChannelFailedToConnect)) {
      print('Connection failed');
    }
  }

  // Already-aborted signals prevent connection.
  final abortedController = AbortController()..abort();
  try {
    await createWebSocketChannel(
      WebSocketChannelConfig(
        url: Uri.parse('wss://api.devnet.solana.com'),
        signal: abortedController.signal,
      ),
    );
  } on SolanaError catch (e) {
    if (isSolanaError(
      e,
      SolanaErrorCode.rpcSubscriptionsChannelConnectionClosed,
    )) {
      print('Channel was already closed');
    }
  }
}

API Reference #

Functions #

Classes #

Constants #

Example #

Use example/main.dart as a runnable starting point for solana_kit_rpc_subscriptions_channel_websocket.

• Import path: package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart
• This section is centrally maintained with mdt to keep package guidance aligned.
• After updating shared docs templates, run docs:update from the repo root.

Maintenance #

• Validate docs in CI and locally with docs:check.
• Keep examples focused on one workflow and reference package README sections for deeper API details.