Class: WebSocketChannel
Defined in: src/channel/ws/ws_0_10.ts:175
Manages a WebSocket connection to a Starknet node for receiving real-time updates. This class handles subscriptions, automatic reconnection, and request queueing.
Since the transport split, this is a façade: the socket and its reconnection policy live in
ReconnectingWsTransport, and the starknet_subscribe* surface lives in SubscriptionChannel.
Every member below behaves exactly as it did before — WebSocketChannel.test.ts and
WebSocketChannel.reconnect.test.ts are the specification of that, and they pass unmodified.
Example
const channel = new WebSocketChannel({ nodeUrl: 'YOUR_NODE_URL' });
await channel.waitForConnection();
const sub = await channel.subscribeNewHeads();
sub.on((data) => {
console.log('New Block:', data);
});
// ... later
await sub.unsubscribe();
channel.disconnect();
Constructors
Constructor
new WebSocketChannel(
options):WebSocketChannel
Defined in: src/channel/ws/ws_0_10.ts:212
Creates an instance of WebSocketChannel.
Parameters
options
The options for configuring the channel.
Returns
WebSocketChannel
Properties
nodeUrl
nodeUrl:
string
Defined in: src/channel/ws/ws_0_10.ts:180
The URL of the WebSocket RPC Node.
Example
'wss://your-starknet-node/rpc/v0_10'
Accessors
websocket
Get Signature
get websocket():
WebSocket
Defined in: src/channel/ws/ws_0_10.ts:196
The underlying WebSocket instance.
A getter rather than a field: a reconnection replaces the socket, and callers — including
the test suite, which spies on channel.websocket.send — must see the live one.
Returns
WebSocket
Methods
send()
send(
method,params?,id?):number
Defined in: src/channel/ws/ws_0_10.ts:243
Sends a JSON-RPC request over the WebSocket connection without waiting for a response.
This is a low-level method. Prefer sendReceive for most use cases.
Parameters
method
string
The RPC method name.
params?
object
The parameters for the RPC method.
id?
number
A specific request ID. If not provided, an auto-incrementing ID is used.
Returns
number
The ID of the sent request.
Throws
If the WebSocket is not connected.
sendReceive()
sendReceive<
T>(method,params?):Promise<T>
Defined in: src/channel/ws/ws_0_10.ts:292
Sends a JSON-RPC request and returns a Promise that resolves with the result. This method abstracts the request/response cycle over WebSockets. If the connection is lost, it will queue the request and send it upon reconnection.
Type Parameters
T
T = any
The expected type of the result.
Parameters
method
string
The RPC method name.
params?
object
The parameters for the RPC method.
Returns
Promise<T>
A Promise that resolves with the RPC response result.
Throws
If the request does not receive a response within the configured requestTimeout.
Throws
If the WebSocket is not connected and auto-reconnect is disabled.
isConnected()
isConnected():
boolean
Defined in: src/channel/ws/ws_0_10.ts:313
Checks if the WebSocket connection is currently open.
Returns
boolean
true if the connection is open, false otherwise.
waitForConnection()
waitForConnection():
Promise<number>
Defined in: src/channel/ws/ws_0_10.ts:328
Returns a Promise that resolves when the WebSocket connection is open. Can be used to block execution until the connection is established.
Returns
Promise<number>
A Promise that resolves with the WebSocket's readyState when connected.
Example
const channel = new WebSocketChannel({ nodeUrl: '...' });
await channel.waitForConnection();
console.log('Connected!');
disconnect()
disconnect(
code?,reason?):void
Defined in: src/channel/ws/ws_0_10.ts:357
Closes the WebSocket connection. This method is user-initiated and will prevent automatic reconnection for this closure.
Parameters
code?
number
The WebSocket connection close code.
reason?
string
The WebSocket connection close reason.
Returns
void
waitForDisconnection()
waitForDisconnection():
Promise<number|Event>
Defined in: src/channel/ws/ws_0_10.ts:365
Returns a Promise that resolves when the WebSocket connection is closed.
Returns
Promise<number | Event>
A Promise that resolves with the WebSocket's readyState or a CloseEvent when disconnected.
unsubscribe()
unsubscribe(
subscriptionId):Promise<boolean>
Defined in: src/channel/ws/ws_0_10.ts:400
Internal
Unsubscribes from a Starknet subscription.
It is recommended to use the unsubscribe() method on the Subscription object instead.
Parameters
subscriptionId
string
The ID of the subscription to unsubscribe from.
Returns
Promise<boolean>
A Promise that resolves with true if the unsubscription was successful.
waitForUnsubscription()
waitForUnsubscription(
targetId):Promise<void>
Defined in: src/channel/ws/ws_0_10.ts:419
Returns a Promise that resolves when a specific subscription is successfully unsubscribed.
Parameters
targetId
string
The ID of the subscription to wait for.
Returns
Promise<void>
Example
await channel.waitForUnsubscription(mySubscription.id);
console.log('Successfully unsubscribed.');
reconnect()
reconnect():
void
Defined in: src/channel/ws/ws_0_10.ts:427
Manually initiates a reconnection attempt. This creates a new WebSocket instance and re-establishes listeners.
Returns
void
subscribeNewHeads()
subscribeNewHeads(
params?):Promise<SubscriptionNewHeadsEvent>
Defined in: src/channel/ws/ws_0_10.ts:436
Subscribes to new block headers.
Parameters
params?
The parameters for the subscription.
Returns
Promise<SubscriptionNewHeadsEvent>
A Promise that resolves with a Subscription object for new block headers.
subscribeEvents()
subscribeEvents(
params?):Promise<SubscriptionStarknetEventsEvent>
Defined in: src/channel/ws/ws_0_10.ts:448
Subscribes to events matching a given filter.
Parameters
params?
The parameters for the subscription.
Returns
Promise<SubscriptionStarknetEventsEvent>
A Promise that resolves with a Subscription object for the specified events.
subscribeTransactionStatus()
subscribeTransactionStatus(
params):Promise<SubscriptionTransactionStatusEvent>
Defined in: src/channel/ws/ws_0_10.ts:460
Subscribes to status updates for a specific transaction.
Parameters
params
SubscribeTransactionStatusParams
The parameters for the subscription.
Returns
Promise<SubscriptionTransactionStatusEvent>
A Promise that resolves with a Subscription object for the transaction's status.
subscribeNewTransactionReceipts()
subscribeNewTransactionReceipts(
params?):Promise<SubscriptionNewTransactionReceiptsEvent>
Defined in: src/channel/ws/ws_0_10.ts:472
Subscribes to new transaction receipts.
Parameters
params?
SubscribeNewTransactionReceiptsParams = {}
The parameters for the subscription.
Returns
Promise<SubscriptionNewTransactionReceiptsEvent>
A Promise that resolves with a Subscription object for new transaction receipts.
subscribeNewTransactions()
subscribeNewTransactions(
params?):Promise<SubscriptionNewTransactionEvent>
Defined in: src/channel/ws/ws_0_10.ts:484
Subscribes to new transactions.
Parameters
params?
SubscribeNewTransactionsParams = {}
The parameters for the subscription.
Returns
Promise<SubscriptionNewTransactionEvent>
A Promise that resolves with a Subscription object for new transactions.
removeSubscription()
removeSubscription(
id):void
Defined in: src/channel/ws/ws_0_10.ts:495
Internal
Internal method to remove subscription from active map.
Parameters
id
string
Returns
void
on()
on<
K>(event,listener):void
Defined in: src/channel/ws/ws_0_10.ts:504
Adds a listener for a given event.
Type Parameters
K
K extends keyof WebSocketChannelEvents
Parameters
event
K
The event name.
listener
(data) => void
The listener function to add.
Returns
void
off()
off<
K>(event,listener):void
Defined in: src/channel/ws/ws_0_10.ts:516
Removes a listener for a given event.
Type Parameters
K
K extends keyof WebSocketChannelEvents
Parameters
event
K
The event name.
listener
(data) => void
The listener function to remove.
Returns
void