Skip to main content
Version: 11.x

Class: SubscriptionChannel

Defined in: src/channel/ws/subscriptionChannel.ts:62

The starknet_subscribe* surface of one spec version.

Versioned because params and result types differ between specs even though the five method names do not — so this class lives in the same namespace as its spec's RpcChannel, and a namespace means "everything for this spec version".

It borrows a WsTransport: it sends through it, listens to its notifications, and learns from its state that the connection is gone. It never closes the socket — one object owns it.

Reach for it directly only when you want subscriptions without a provider; otherwise use WebSocketProvider, whose subscriptions property is an instance of this class already paired with the request channel of the same spec version.

Example​

const transport = new ReconnectingWsTransport({ nodeUrl: 'wss://…/rpc/v0_10' });
const channel = new RPC0103.SubscriptionChannel({ transport });

const sub = await channel.subscribeNewHeads();
sub.on((header) => console.log(header.block_number));

Extended by​

Constructors​

Constructor​

new SubscriptionChannel(options): SubscriptionChannel

Defined in: src/channel/ws/subscriptionChannel.ts:115

Parameters​

options​

SubscriptionChannelOptions

Returns​

SubscriptionChannel

Properties​

id​

readonly id: string = 'RPC0.10.2-subscriptions'

Defined in: src/channel/ws/subscriptionChannel.ts:63

channelSpecVersion​

readonly channelSpecVersion: "0.9.0" | "0.10.0" | "0.10.2" | "0.10.3" | "0.10.4" = SupportedRpcVersion.v0_10_2

Defined in: src/channel/ws/subscriptionChannel.ts:65

transport​

protected readonly transport: WsTransport

Defined in: src/channel/ws/subscriptionChannel.ts:67

maxBufferSize​

protected readonly maxBufferSize: number

Defined in: src/channel/ws/subscriptionChannel.ts:69

Accessors​

subscriptions​

Get Signature​

get subscriptions(): ReadonlyMap<string, Subscription<any>>

Defined in: src/channel/ws/subscriptionChannel.ts:413

Internal

The live subscriptions, keyed by the id the node issued. Exposed for the WebSocketChannel compatibility façade.

Returns​

ReadonlyMap<string, Subscription<any>>

Methods​

send()​

protected send<T>(method, params?): Promise<T>

Defined in: src/channel/ws/subscriptionChannel.ts:131

Sends one JSON-RPC call and returns its result, applying the same error contract as RpcChannel: a protocol error becomes a typed RpcError.

Type Parameters​

T​

T

Parameters​

method​

string

params?​

object

Returns​

Promise<T>

openSubscription()​

protected openSubscription<T>(method, rpcParams): Promise<Subscription<T>>

Defined in: src/channel/ws/subscriptionChannel.ts:147

Registers a new subscription and returns the handle the caller keeps.

Type Parameters​

T​

T

Parameters​

method​

string

rpcParams​

object

Returns​

Promise<Subscription<T>>

subscribeNewHeads()​

subscribeNewHeads(params?): Promise<SubscriptionNewHeadsEvent>

Defined in: src/channel/ws/subscriptionChannel.ts:191

Subscribes to new block headers.

Parameters​

params?​

SubscribeNewHeadsParams = {}

Where to start from. Defaults to the latest block; a block number or hash replays from there, up to 1024 blocks back.

Returns​

Promise<SubscriptionNewHeadsEvent>

A Subscription delivering one block header per new block.

Example​

const sub = await channel.subscribeNewHeads();
sub.on((header) => console.log(header.block_number, header.block_hash));

subscribeEvents()​

subscribeEvents(params?): Promise<SubscriptionStarknetEventsEvent>

Defined in: src/channel/ws/subscriptionChannel.ts:215

Subscribes to events matching a given filter.

Parameters​

params?​

SubscribeEventsParams = {}

Filters on the emitting address, the event keys, the starting block and the finality status. All are optional: without any, every event of the network is delivered.

Returns​

Promise<SubscriptionStarknetEventsEvent>

A Subscription delivering one emitted event at a time.

Example​

const sub = await channel.subscribeEvents({
  fromAddress: '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7',
  finalityStatus: 'ACCEPTED_ON_L2',
});
sub.on((event) => console.log(event.from_address, event.keys, event.data));

subscribeTransactionStatus()​

subscribeTransactionStatus(params): Promise<SubscriptionTransactionStatusEvent>

Defined in: src/channel/ws/subscriptionChannel.ts:244

Subscribes to status updates for a specific transaction.

Parameters​

params​

SubscribeTransactionStatusParams

The transactionHash to follow, and optionally the block to start from.

Returns​

Promise<SubscriptionTransactionStatusEvent>

A Subscription delivering the transaction's current status, then every change.

Example​

const sub = await channel.subscribeTransactionStatus({ transactionHash: '0x0123...' });
sub.on((update) => console.log(update.status.finality_status));

subscribeNewTransactionReceipts()​

subscribeNewTransactionReceipts(params?): Promise<SubscriptionNewTransactionReceiptsEvent>

Defined in: src/channel/ws/subscriptionChannel.ts:270

Subscribes to new transaction receipts.

Same filters as subscribeNewTransactions, but the full receipt is delivered instead of the transaction.

Parameters​

params?​

SubscribeNewTransactionReceiptsParams = {}

Optional filters on the finality status and on the sender addresses.

Returns​

Promise<SubscriptionNewTransactionReceiptsEvent>

A Subscription delivering one receipt per matching transaction.

Example​

const sub = await channel.subscribeNewTransactionReceipts({
  finalityStatus: ['ACCEPTED_ON_L2'],
});
sub.on((receipt) => console.log(receipt.transaction_hash, receipt.execution_status));

subscribeNewTransactions()​

subscribeNewTransactions(params?): Promise<SubscriptionNewTransactionEvent>

Defined in: src/channel/ws/subscriptionChannel.ts:297

Subscribes to new transactions and to their finality status changes.

One event is fired per status update, so the same transaction can be delivered several times.

Parameters​

params?​

SubscribeNewTransactionsParams = {}

Optional filters on the finality status (defaults to ['ACCEPTED_ON_L2']) and on the sender addresses.

Returns​

Promise<SubscriptionNewTransactionEvent>

A Subscription delivering one transaction per matching status update.

Example​

const sub = await channel.subscribeNewTransactions({
  finalityStatus: ['RECEIVED', 'ACCEPTED_ON_L2'],
});
sub.on((tx) => console.log(tx.transaction_hash, tx.finality_status));

restore()​

restore(): Promise<void>

Defined in: src/channel/ws/subscriptionChannel.ts:354

Re-issues every live subscription on a freshly reconnected socket.

A subscription that cannot be re-established is not put back in the map, and its handle is closed: otherwise it would keep reporting itself as live while nothing could ever reach its handler again.

Returns​

Promise<void>

unsubscribe()​

unsubscribe(subscriptionId): Promise<boolean>

Defined in: src/channel/ws/subscriptionChannel.ts:380

Internal

Unsubscribes from a Starknet subscription.

Prefer subscription.unsubscribe().

Parameters​

subscriptionId​

string

Returns​

Promise<boolean>

removeSubscription()​

removeSubscription(subscriptionId): void

Defined in: src/channel/ws/subscriptionChannel.ts:405

Internal

Removes a subscription from the active map.

Parameters​

subscriptionId​

string

Returns​

void

waitForUnsubscription()​

waitForUnsubscription(targetId): Promise<void>

Defined in: src/channel/ws/subscriptionChannel.ts:418

Resolves when a specific subscription is successfully unsubscribed.

Parameters​

targetId​

string

Returns​

Promise<void>

close()​

close(): void

Defined in: src/channel/ws/subscriptionChannel.ts:448

Stops listening to the transport and settles anything still waiting.

Does not close the socket: this channel borrowed it.

Returns​

void