@solana/rpc-subscriptions 6.3.1 → 6.3.2-canary-20260313143218

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/rpc-subscriptions",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313143218",
   "description": "A library for subscribing to Solana RPC notifications",
   "homepage": "https://www.solanakit.com/api#solanarpc-subscriptions",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,17 +56,17 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "6.3.1",
-    "@solana/functional": "6.3.1",
-    "@solana/promises": "6.3.1",
-    "@solana/rpc-spec-types": "6.3.1",
-    "@solana/fast-stable-stringify": "6.3.1",
-    "@solana/rpc-subscriptions-channel-websocket": "6.3.1",
-    "@solana/rpc-subscriptions-api": "6.3.1",
-    "@solana/rpc-transformers": "6.3.1",
-    "@solana/rpc-subscriptions-spec": "6.3.1",
-    "@solana/rpc-types": "6.3.1",
-    "@solana/subscribable": "6.3.1"
+    "@solana/errors": "6.3.2-canary-20260313143218",
+    "@solana/fast-stable-stringify": "6.3.2-canary-20260313143218",
+    "@solana/functional": "6.3.2-canary-20260313143218",
+    "@solana/promises": "6.3.2-canary-20260313143218",
+    "@solana/rpc-spec-types": "6.3.2-canary-20260313143218",
+    "@solana/rpc-subscriptions-api": "6.3.2-canary-20260313143218",
+    "@solana/rpc-subscriptions-channel-websocket": "6.3.2-canary-20260313143218",
+    "@solana/rpc-subscriptions-spec": "6.3.2-canary-20260313143218",
+    "@solana/rpc-transformers": "6.3.2-canary-20260313143218",
+    "@solana/rpc-types": "6.3.2-canary-20260313143218",
+    "@solana/subscribable": "6.3.2-canary-20260313143218"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * This package contains types that implement RPC subscriptions as required by the Solana RPC.
+ * Additionally, it incorporates some useful defaults that make working with subscriptions easier,
+ * more performant, and more reliable. It can be used standalone, but it is also exported as part of
+ * Kit [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * @packageDocumentation
+ */
+export * from '@solana/rpc-subscriptions-api';
+export * from '@solana/rpc-subscriptions-spec';
+
+export * from './rpc-default-config';
+export * from './rpc-subscriptions-autopinger';
+export * from './rpc-subscriptions-channel-pool';
+export * from './rpc-subscriptions-channel';
+export * from './rpc-subscriptions-clusters';
+export * from './rpc-subscriptions-coalescer';
+export * from './rpc-subscriptions-json-bigint';
+export * from './rpc-subscriptions-json';
+export * from './rpc-subscriptions-transport';
+export * from './rpc-subscriptions';

package/src/rpc-default-config.ts

@@ -0,0 +1,12 @@
+import type { createSolanaRpcSubscriptionsApi } from '@solana/rpc-subscriptions-api';
+
+import { createSolanaJsonRpcIntegerOverflowError } from './rpc-integer-overflow-error';
+
+export const DEFAULT_RPC_SUBSCRIPTIONS_CONFIG: Partial<
+    NonNullable<Parameters<typeof createSolanaRpcSubscriptionsApi>[0]>
+> = {
+    defaultCommitment: 'confirmed',
+    onIntegerOverflow(request, keyPath, value) {
+        throw createSolanaJsonRpcIntegerOverflowError(request.methodName, keyPath, value);
+    },
+};

package/src/rpc-integer-overflow-error.ts

@@ -0,0 +1,43 @@
+import { safeCaptureStackTrace, SOLANA_ERROR__RPC__INTEGER_OVERFLOW, SolanaError } from '@solana/errors';
+import type { KeyPath } from '@solana/rpc-transformers';
+
+export function createSolanaJsonRpcIntegerOverflowError(
+    methodName: string,
+    keyPath: KeyPath,
+    value: bigint,
+): SolanaError<typeof SOLANA_ERROR__RPC__INTEGER_OVERFLOW> {
+    let argumentLabel = '';
+    if (typeof keyPath[0] === 'number') {
+        const argPosition = keyPath[0] + 1;
+        const lastDigit = argPosition % 10;
+        const lastTwoDigits = argPosition % 100;
+        if (lastDigit == 1 && lastTwoDigits != 11) {
+            argumentLabel = argPosition + 'st';
+        } else if (lastDigit == 2 && lastTwoDigits != 12) {
+            argumentLabel = argPosition + 'nd';
+        } else if (lastDigit == 3 && lastTwoDigits != 13) {
+            argumentLabel = argPosition + 'rd';
+        } else {
+            argumentLabel = argPosition + 'th';
+        }
+    } else {
+        argumentLabel = `\`${keyPath[0].toString()}\``;
+    }
+    const path =
+        keyPath.length > 1
+            ? keyPath
+                  .slice(1)
+                  .map(pathPart => (typeof pathPart === 'number' ? `[${pathPart}]` : pathPart))
+                  .join('.')
+            : undefined;
+    const error = new SolanaError(SOLANA_ERROR__RPC__INTEGER_OVERFLOW, {
+        argumentLabel,
+        keyPath: keyPath as readonly (number | string | symbol)[],
+        methodName,
+        optionalPathLabel: path ? ` at path \`${path}\`` : '',
+        value,
+        ...(path !== undefined ? { path } : undefined),
+    });
+    safeCaptureStackTrace(error, createSolanaJsonRpcIntegerOverflowError);
+    return error;
+}

package/src/rpc-subscriptions-autopinger.ts

@@ -0,0 +1,83 @@
+import { isSolanaError, SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CONNECTION_CLOSED } from '@solana/errors';
+import { AbortController } from '@solana/event-target-impl';
+import type { RpcSubscriptionsChannel } from '@solana/rpc-subscriptions-spec';
+
+type Config<TChannel extends RpcSubscriptionsChannel<unknown, unknown>> = Readonly<{
+    abortSignal: AbortSignal;
+    channel: TChannel;
+    intervalMs: number;
+}>;
+
+const PING_PAYLOAD = {
+    jsonrpc: '2.0',
+    method: 'ping',
+} as const;
+
+/**
+ * Given a {@link RpcSubscriptionsChannel}, will return a new channel that sends a ping message to
+ * the inner channel if a message has not been sent or received in the last `intervalMs`. In web
+ * browsers, this implementation sends no ping when the network is down, and sends a ping
+ * immediately upon the network coming back up.
+ */
+export function getRpcSubscriptionsChannelWithAutoping<TChannel extends RpcSubscriptionsChannel<object, unknown>>({
+    abortSignal: callerAbortSignal,
+    channel,
+    intervalMs,
+}: Config<TChannel>): TChannel {
+    let intervalId: ReturnType<typeof setInterval> | undefined;
+    function sendPing() {
+        channel.send(PING_PAYLOAD).catch((e: unknown) => {
+            if (isSolanaError(e, SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CONNECTION_CLOSED)) {
+                pingerAbortController.abort();
+            }
+        });
+    }
+    function restartPingTimer() {
+        clearInterval(intervalId);
+        intervalId = setInterval(sendPing, intervalMs);
+    }
+    const pingerAbortController = new AbortController();
+    pingerAbortController.signal.addEventListener('abort', () => {
+        clearInterval(intervalId);
+    });
+    callerAbortSignal.addEventListener('abort', () => {
+        pingerAbortController.abort();
+    });
+    channel.on(
+        'error',
+        () => {
+            pingerAbortController.abort();
+        },
+        { signal: pingerAbortController.signal },
+    );
+    channel.on('message', restartPingTimer, { signal: pingerAbortController.signal });
+    if (!__BROWSER__ || globalThis.navigator.onLine) {
+        restartPingTimer();
+    }
+    if (__BROWSER__) {
+        globalThis.addEventListener(
+            'offline',
+            function handleOffline() {
+                clearInterval(intervalId);
+            },
+            { signal: pingerAbortController.signal },
+        );
+        globalThis.addEventListener(
+            'online',
+            function handleOnline() {
+                sendPing();
+                restartPingTimer();
+            },
+            { signal: pingerAbortController.signal },
+        );
+    }
+    return {
+        ...channel,
+        send(...args) {
+            if (!pingerAbortController.signal.aborted) {
+                restartPingTimer();
+            }
+            return channel.send(...args);
+        },
+    };
+}

package/src/rpc-subscriptions-channel-pool-internal.ts

@@ -0,0 +1,16 @@
+import { RpcSubscriptionsChannel } from '@solana/rpc-subscriptions-spec';
+
+export type ChannelPoolEntry = {
+    channel: PromiseLike<RpcSubscriptionsChannel<unknown, unknown>> | RpcSubscriptionsChannel<unknown, unknown>;
+    readonly dispose: () => void;
+    subscriptionCount: number;
+};
+
+type ChannelPool = { readonly entries: ChannelPoolEntry[]; freeChannelIndex: number };
+
+export function createChannelPool(): ChannelPool {
+    return {
+        entries: [],
+        freeChannelIndex: -1,
+    };
+}

package/src/rpc-subscriptions-channel-pool.ts

@@ -0,0 +1,113 @@
+import { AbortController } from '@solana/event-target-impl';
+import { RpcSubscriptionsChannelCreator } from '@solana/rpc-subscriptions-spec';
+
+import { ChannelPoolEntry, createChannelPool } from './rpc-subscriptions-channel-pool-internal';
+
+type Config = Readonly<{
+    maxSubscriptionsPerChannel: number;
+    minChannels: number;
+}>;
+
+/**
+ * Given a channel creator, will return a new channel creator with the following behavior.
+ *
+ * 1. When called, returns a {@link RpcSubscriptionsChannel}. Adds that channel to a pool.
+ * 2. When called again, creates and returns new
+ *    {@link RpcSubscriptionChannel | RpcSubscriptionChannels} up to the number specified by
+ *    `minChannels`.
+ * 3. When `minChannels` channels have been created, subsequent calls vend whichever existing
+ *    channel from the pool has the fewest subscribers, or the next one in rotation in the event of
+ *    a tie.
+ * 4. Once all channels carry the number of subscribers specified by the number
+ *    `maxSubscriptionsPerChannel`, new channels in excess of `minChannel` will be created,
+ *    returned, and added to the pool.
+ * 5. A channel will be destroyed once all of its subscribers' abort signals fire.
+ */
+export function getChannelPoolingChannelCreator<
+    TChannelCreator extends RpcSubscriptionsChannelCreator<unknown, unknown>,
+>(createChannel: TChannelCreator, { maxSubscriptionsPerChannel, minChannels }: Config): TChannelCreator {
+    const pool = createChannelPool();
+    /**
+     * This function advances the free channel index to the pool entry with the most capacity. It
+     * sets the index to `-1` if all channels are full.
+     */
+    function recomputeFreeChannelIndex() {
+        if (pool.entries.length < minChannels) {
+            // Don't set the free channel index until the pool fills up; we want to keep creating
+            // channels before we start rotating among them.
+            pool.freeChannelIndex = -1;
+            return;
+        }
+        let mostFreeChannel: Readonly<{ poolIndex: number; subscriptionCount: number }> | undefined;
+        for (let ii = 0; ii < pool.entries.length; ii++) {
+            const nextPoolIndex = (pool.freeChannelIndex + ii + 2) % pool.entries.length;
+            const nextPoolEntry =
+                // Start from the item two positions after the current item. This way, the
+                // search will finish on the item after the current one. This ensures that, if
+                // any channels tie for having the most capacity, the one that will be chosen is
+                // the one immediately to the current one's right (wrapping around).
+                pool.entries[nextPoolIndex];
+            if (
+                nextPoolEntry.subscriptionCount < maxSubscriptionsPerChannel &&
+                (!mostFreeChannel || mostFreeChannel.subscriptionCount >= nextPoolEntry.subscriptionCount)
+            ) {
+                mostFreeChannel = {
+                    poolIndex: nextPoolIndex,
+                    subscriptionCount: nextPoolEntry.subscriptionCount,
+                };
+            }
+        }
+        pool.freeChannelIndex = mostFreeChannel?.poolIndex ?? -1;
+    }
+    return function getExistingChannelWithMostCapacityOrCreateChannel({ abortSignal }) {
+        let poolEntry: ChannelPoolEntry;
+        function destroyPoolEntry() {
+            const index = pool.entries.findIndex(entry => entry === poolEntry);
+            pool.entries.splice(index, 1);
+            poolEntry.dispose();
+            recomputeFreeChannelIndex();
+        }
+        if (pool.freeChannelIndex === -1) {
+            const abortController = new AbortController();
+            const newChannelPromise = createChannel({ abortSignal: abortController.signal });
+            newChannelPromise
+                .then(newChannel => {
+                    newChannel.on('error', destroyPoolEntry, { signal: abortController.signal });
+                })
+                .catch(destroyPoolEntry);
+            poolEntry = {
+                channel: newChannelPromise,
+                dispose() {
+                    abortController.abort();
+                },
+                subscriptionCount: 0,
+            };
+            pool.entries.push(poolEntry);
+        } else {
+            poolEntry = pool.entries[pool.freeChannelIndex];
+        }
+        /**
+         * A note about subscription counts.
+         * Because of https://github.com/solana-labs/solana/pull/18943, two subscriptions for
+         * materially the same notification will be coalesced on the server. This means they will be
+         * assigned the same subscription id, and will occupy one subscription slot. We can't tell,
+         * from here, whether a subscription will be treated in this way or not, so we
+         * unconditionally increment the subscription count every time a subscription request is
+         * made. This may result in subscription channels being treated as out-of-capacity when in
+         * fact they are not.
+         */
+        poolEntry.subscriptionCount++;
+        abortSignal.addEventListener('abort', function destroyConsumer() {
+            poolEntry.subscriptionCount--;
+            if (poolEntry.subscriptionCount === 0) {
+                destroyPoolEntry();
+            } else if (pool.freeChannelIndex !== -1) {
+                // Back the free channel index up one position, and recompute it.
+                pool.freeChannelIndex--;
+                recomputeFreeChannelIndex();
+            }
+        });
+        recomputeFreeChannelIndex();
+        return poolEntry.channel;
+    } as TChannelCreator;
+}

package/src/rpc-subscriptions-channel.ts

@@ -0,0 +1,114 @@
+import { createWebSocketChannel } from '@solana/rpc-subscriptions-channel-websocket';
+import type { RpcSubscriptionsChannel } from '@solana/rpc-subscriptions-spec';
+import type { ClusterUrl } from '@solana/rpc-types';
+
+import { getRpcSubscriptionsChannelWithAutoping } from './rpc-subscriptions-autopinger';
+import { getChannelPoolingChannelCreator } from './rpc-subscriptions-channel-pool';
+import { RpcSubscriptionsChannelCreatorFromClusterUrl } from './rpc-subscriptions-clusters';
+import { getRpcSubscriptionsChannelWithJSONSerialization } from './rpc-subscriptions-json';
+import { getRpcSubscriptionsChannelWithBigIntJSONSerialization } from './rpc-subscriptions-json-bigint';
+
+export type DefaultRpcSubscriptionsChannelConfig<TClusterUrl extends ClusterUrl> = Readonly<{
+    /**
+     * The number of milliseconds to wait since the last message sent or received over the channel
+     * before sending a ping message to keep the channel open.
+     */
+    intervalMs?: number;
+    /**
+     * The number of subscribers that may share a channel before a new channel must be created.
+     *
+     * It is important that you set this to the maximum number of subscriptions that your RPC
+     * provider recommends making over a single connection; the default is set deliberately low, so
+     * as to comply with the restrictive limits of the public mainnet RPC node.
+     *
+     * @defaultValue 100
+     */
+    maxSubscriptionsPerChannel?: number;
+    /** The number of channels to create before reusing a channel for a new subscription. */
+    minChannels?: number;
+    /**
+     * The number of bytes of data to admit into the
+     * [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) buffer before
+     * buffering data on the client.
+     */
+    sendBufferHighWatermark?: number;
+    /** The URL of the web socket server. Must use the `ws` or `wss` protocols. */
+    url: TClusterUrl;
+}>;
+
+/**
+ * Similar to {@link createDefaultRpcSubscriptionsChannelCreator} with some Solana-specific
+ * defaults.
+ *
+ * For instance, it safely handles `BigInt` values in JSON messages since Solana RPC servers accept
+ * and return integers larger than [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER).
+ */
+export function createDefaultSolanaRpcSubscriptionsChannelCreator<TClusterUrl extends ClusterUrl>(
+    config: DefaultRpcSubscriptionsChannelConfig<TClusterUrl>,
+): RpcSubscriptionsChannelCreatorFromClusterUrl<TClusterUrl, unknown, unknown> {
+    return createDefaultRpcSubscriptionsChannelCreatorImpl({
+        ...config,
+        jsonSerializer: getRpcSubscriptionsChannelWithBigIntJSONSerialization,
+    });
+}
+
+/**
+ * Creates a function that returns new subscription channels when called.
+ */
+export function createDefaultRpcSubscriptionsChannelCreator<TClusterUrl extends ClusterUrl>(
+    config: DefaultRpcSubscriptionsChannelConfig<TClusterUrl>,
+): RpcSubscriptionsChannelCreatorFromClusterUrl<TClusterUrl, unknown, unknown> {
+    return createDefaultRpcSubscriptionsChannelCreatorImpl({
+        ...config,
+        jsonSerializer: getRpcSubscriptionsChannelWithJSONSerialization,
+    });
+}
+
+function createDefaultRpcSubscriptionsChannelCreatorImpl<TClusterUrl extends ClusterUrl>(
+    config: DefaultRpcSubscriptionsChannelConfig<TClusterUrl> & {
+        jsonSerializer: (channel: RpcSubscriptionsChannel<string, string>) => RpcSubscriptionsChannel<unknown, unknown>;
+    },
+): RpcSubscriptionsChannelCreatorFromClusterUrl<TClusterUrl, unknown, unknown> {
+    if (/^wss?:/i.test(config.url) === false) {
+        const protocolMatch = config.url.match(/^([^:]+):/);
+        throw new DOMException(
+            protocolMatch
+                ? "Failed to construct 'WebSocket': The URL's scheme must be either 'ws' or " +
+                      `'wss'. '${protocolMatch[1]}:' is not allowed.`
+                : `Failed to construct 'WebSocket': The URL '${config.url}' is invalid.`,
+        );
+    }
+    const { intervalMs, ...rest } = config;
+    const createDefaultRpcSubscriptionsChannel = (({ abortSignal }) => {
+        return createWebSocketChannel({
+            ...rest,
+            sendBufferHighWatermark:
+                config.sendBufferHighWatermark ??
+                // Let 128KB of data into the WebSocket buffer before buffering it in the app.
+                131_072,
+            signal: abortSignal,
+        })
+            .then(config.jsonSerializer)
+            .then(channel =>
+                getRpcSubscriptionsChannelWithAutoping({
+                    abortSignal,
+                    channel,
+                    intervalMs: intervalMs ?? 5_000,
+                }),
+            );
+    }) as RpcSubscriptionsChannelCreatorFromClusterUrl<TClusterUrl, unknown, unknown>;
+    return getChannelPoolingChannelCreator(createDefaultRpcSubscriptionsChannel, {
+        maxSubscriptionsPerChannel:
+            config.maxSubscriptionsPerChannel ??
+            /**
+             * A note about this default. The idea here is that, because some RPC providers impose
+             * an upper limit on the number of subscriptions you can make per channel, we must
+             * choose a number low enough to avoid hitting that limit. Without knowing what provider
+             * a given person is using, or what their limit is, we have to choose the lowest of all
+             * known limits. As of this writing (October 2024) that is the public mainnet RPC node
+             * (api.mainnet-beta.solana.com) at 100 subscriptions.
+             */
+            100,
+        minChannels: config.minChannels ?? 1,
+    });
+}

package/src/rpc-subscriptions-clusters.ts

@@ -0,0 +1,305 @@
+import type {
+    RpcSubscriptions,
+    RpcSubscriptionsChannel,
+    RpcSubscriptionsChannelCreator,
+    RpcSubscriptionsTransport,
+} from '@solana/rpc-subscriptions-spec';
+import type { ClusterUrl, DevnetUrl, MainnetUrl, TestnetUrl } from '@solana/rpc-types';
+
+export type RpcSubscriptionsChannelCreatorDevnet<TOutboundMessage, TInboundMessage> = RpcSubscriptionsChannelCreator<
+    TOutboundMessage,
+    TInboundMessage
+> & {
+    '~cluster': 'devnet';
+};
+export type RpcSubscriptionsChannelCreatorTestnet<TOutboundMessage, TInboundMessage> = RpcSubscriptionsChannelCreator<
+    TOutboundMessage,
+    TInboundMessage
+> & {
+    '~cluster': 'testnet';
+};
+export type RpcSubscriptionsChannelCreatorMainnet<TOutboundMessage, TInboundMessage> = RpcSubscriptionsChannelCreator<
+    TOutboundMessage,
+    TInboundMessage
+> & {
+    '~cluster': 'mainnet';
+};
+export type RpcSubscriptionsChannelCreatorWithCluster<TOutboundMessage, TInboundMessage> =
+    | RpcSubscriptionsChannelCreatorDevnet<TOutboundMessage, TInboundMessage>
+    | RpcSubscriptionsChannelCreatorMainnet<TOutboundMessage, TInboundMessage>
+    | RpcSubscriptionsChannelCreatorTestnet<TOutboundMessage, TInboundMessage>;
+export type RpcSubscriptionsChannelCreatorFromClusterUrl<
+    TClusterUrl extends ClusterUrl,
+    TOutboundMessage,
+    TInboundMessage,
+> = TClusterUrl extends DevnetUrl
+    ? RpcSubscriptionsChannelCreatorDevnet<TOutboundMessage, TInboundMessage>
+    : TClusterUrl extends TestnetUrl
+      ? RpcSubscriptionsChannelCreatorTestnet<TOutboundMessage, TInboundMessage>
+      : TClusterUrl extends MainnetUrl
+        ? RpcSubscriptionsChannelCreatorMainnet<TOutboundMessage, TInboundMessage>
+        : RpcSubscriptionsChannelCreator<TOutboundMessage, TInboundMessage>;
+
+/**
+ * A {@link RpcSubscriptionsChannel} that communicates with the devnet cluster.
+ *
+ * Such channels are understood to communicate with a RPC server that services devnet, and as such
+ * might only be accepted for use as the channel of a {@link RpcSubscriptionsTransportDevnet}.
+ *
+ * This is useful in cases where you need to make assertions about what capabilities a RPC offers.
+ * You can use the ability to assert on the type of RPC channel at compile time to prevent calling
+ * unimplemented methods or presuming the existence of unavailable programs or data.
+ */
+export type RpcSubscriptionsChannelDevnet<TOutboundMessage, TInboundMessage> = RpcSubscriptionsChannel<
+    TOutboundMessage,
+    TInboundMessage
+> & { '~cluster': 'devnet' };
+/**
+ * A {@link RpcSubscriptionsChannel} that communicates with the testnet cluster.
+ *
+ * Such channels are understood to communicate with a RPC server that services testnet, and as such
+ * might only be accepted for use as the channel of a {@link RpcSubscriptionsTransportTestnet}.
+ *
+ * This is useful in cases where you need to make assertions about what capabilities a RPC offers.
+ * You can use the ability to assert on the type of RPC channel at compile time to prevent calling
+ * unimplemented methods or presuming the existence of unavailable programs or data.
+ */
+export type RpcSubscriptionsChannelTestnet<TOutboundMessage, TInboundMessage> = RpcSubscriptionsChannel<
+    TOutboundMessage,
+    TInboundMessage
+> & { '~cluster': 'testnet' };
+/**
+ * A {@link RpcSubscriptionsChannel} that communicates with the mainnet cluster.
+ *
+ * Such channels are understood to communicate with a RPC server that services mainnet, and as such
+ * might only be accepted for use as the channel of a {@link RpcSubscriptionsTransportMainnet}.
+ *
+ * This is useful in cases where you need to make assertions about what capabilities a RPC offers.
+ * You can use the ability to assert on the type of RPC channel at compile time to prevent calling
+ * unimplemented methods or presuming the existence of unavailable programs or data.
+ */
+export type RpcSubscriptionsChannelMainnet<TOutboundMessage, TInboundMessage> = RpcSubscriptionsChannel<
+    TOutboundMessage,
+    TInboundMessage
+> & { '~cluster': 'mainnet' };
+export type RpcSubscriptionsChannelWithCluster<TOutboundMessage, TInboundMessage> =
+    | RpcSubscriptionsChannelDevnet<TOutboundMessage, TInboundMessage>
+    | RpcSubscriptionsChannelMainnet<TOutboundMessage, TInboundMessage>
+    | RpcSubscriptionsChannelTestnet<TOutboundMessage, TInboundMessage>;
+/**
+ * Given a {@link ClusterUrl}, this utility type will resolve to as specific a
+ * {@link RpcSubscriptionsChannel} as possible.
+ *
+ * @example
+ * ```ts
+ * function createCustomSubscriptionsChannel<TClusterUrl extends ClusterUrl>(
+ *     clusterUrl: TClusterUrl,
+ * ): RpcSubscriptionsChannelFromClusterUrl<TClusterUrl> {
+ *     /* ... *\/
+ * }
+ *
+ * const channel = createCustomSubscriptionsChannel(testnet('ws://api.testnet.solana.com'));
+ * channel satisfies RpcSubscriptionsChannelTestnet; // OK
+ * ```
+ */
+export type RpcSubscriptionsChannelFromClusterUrl<
+    TClusterUrl extends ClusterUrl,
+    TOutboundMessage,
+    TInboundMessage,
+> = TClusterUrl extends DevnetUrl
+    ? RpcSubscriptionsChannelDevnet<TOutboundMessage, TInboundMessage>
+    : TClusterUrl extends TestnetUrl
+      ? RpcSubscriptionsChannelTestnet<TOutboundMessage, TInboundMessage>
+      : TClusterUrl extends MainnetUrl
+        ? RpcSubscriptionsChannelMainnet<TOutboundMessage, TInboundMessage>
+        : RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>;
+
+/**
+ * A {@link RpcSubscriptionsTransport} that communicates with the devnet cluster.
+ *
+ * Such transports are understood to communicate with a RPC server that services devnet, and as such
+ * might only be accepted for use as the transport of a {@link RpcSubscriptionsDevnet}.
+ *
+ * This is useful in cases where you need to make assertions about what capabilities a RPC offers.
+ * You can use the ability to assert on the type of RPC transport at compile time to prevent calling
+ * unimplemented methods or presuming the existence of unavailable programs or data.
+ */
+export type RpcSubscriptionsTransportDevnet = RpcSubscriptionsTransport & { '~cluster': 'devnet' };
+/**
+ * A {@link RpcSubscriptionsTransport} that communicates with the testnet cluster.
+ *
+ * Such transports are understood to communicate with a RPC server that services testnet, and as
+ * such might only be accepted for use as the transport of a {@link RpcSubscriptionsTestnet}.
+ *
+ * This is useful in cases where you need to make assertions about what capabilities a RPC offers.
+ * You can use the ability to assert on the type of RPC transport at compile time to prevent calling
+ * unimplemented methods or presuming the existence of unavailable programs or data.
+ */
+export type RpcSubscriptionsTransportTestnet = RpcSubscriptionsTransport & { '~cluster': 'testnet' };
+/**
+ * A {@link RpcSubscriptionsTransport} that communicates with the mainnet cluster.
+ *
+ * Such transports are understood to communicate with a RPC server that services mainnet, and as
+ * such might only be accepted for use as the transport of a {@link RpcSubscriptionsMainnet}.
+ *
+ * This is useful in cases where you need to make assertions about what capabilities a RPC offers.
+ * You can use the ability to assert on the type of RPC transport at compile time to prevent calling
+ * unimplemented methods or presuming the existence of unavailable programs or data.
+ */
+export type RpcSubscriptionsTransportMainnet = RpcSubscriptionsTransport & { '~cluster': 'mainnet' };
+export type RpcSubscriptionsTransportWithCluster =
+    | RpcSubscriptionsTransportDevnet
+    | RpcSubscriptionsTransportMainnet
+    | RpcSubscriptionsTransportTestnet;
+/**
+ * Given a {@link ClusterUrl}, this utility type will resolve to as specific a
+ * {@link RpcSubscriptionsTransport} as possible.
+ *
+ * @example
+ * ```ts
+ * function createCustomSubscriptionsTransport<TClusterUrl extends ClusterUrl>(
+ *     clusterUrl: TClusterUrl,
+ * ): RpcSubscriptionsTransportFromClusterUrl<TClusterUrl> {
+ *     /* ... *\/
+ * }
+ *
+ * const transport = createCustomSubscriptionsTransport(testnet('ws://api.testnet.solana.com'));
+ * transport satisfies RpcSubscriptionsTransportTestnet; // OK
+ * ```
+ */
+export type RpcSubscriptionsTransportFromClusterUrl<TClusterUrl extends ClusterUrl> = TClusterUrl extends DevnetUrl
+    ? RpcSubscriptionsTransportDevnet
+    : TClusterUrl extends TestnetUrl
+      ? RpcSubscriptionsTransportTestnet
+      : TClusterUrl extends MainnetUrl
+        ? RpcSubscriptionsTransportMainnet
+        : RpcSubscriptionsTransport;
+/**
+ * A {@link RpcSubscriptions} that supports the RPC Subscriptions methods available on the devnet
+ * cluster.
+ *
+ * This is useful in cases where you need to make assertions about the suitability of a RPC for a
+ * given purpose. For example, you might like to make it a type error to combine certain types with
+ * RPCs belonging to certain clusters, at compile time.
+ *
+ * @example
+ * ```ts
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address<'ReAL1111111111111111111111111111'>,
+ *     rpcSubscriptions: RpcSubscriptionsMainnet<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>>;
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address<'TeST1111111111111111111111111111'>,
+ *     rpcSubscriptions: RpcSubscriptionsDevnet<unknown> | RpcTestnet<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>>;
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address,
+ *     rpcSubscriptions: RpcSubscriptions<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>> {
+ *     /* ... *\/
+ * }
+ * const rpcSubscriptions = createSolanaRpcSubscriptions(devnet('https://api.devnet.solana.com'));
+ * await subscribeToSpecialAccountNotifications(address('ReAL1111111111111111111111111111'), rpcSubscriptions); // ERROR
+ * ```
+ */
+export type RpcSubscriptionsDevnet<TRpcMethods> = RpcSubscriptions<TRpcMethods> & { '~cluster': 'devnet' };
+/**
+ * A {@link RpcSubscriptions} that supports the RPC Subscriptions methods available on the testnet
+ * cluster.
+ *
+ * This is useful in cases where you need to make assertions about the suitability of a RPC for a
+ * given purpose. For example, you might like to make it a type error to combine certain types with
+ * RPCs belonging to certain clusters, at compile time.
+ *
+ * @example
+ * ```ts
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address<'ReAL1111111111111111111111111111'>,
+ *     rpcSubscriptions: RpcSubscriptionsMainnet<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>>;
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address<'TeST1111111111111111111111111111'>,
+ *     rpcSubscriptions: RpcSubscriptionsDevnet<unknown> | RpcTestnet<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>>;
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address,
+ *     rpcSubscriptions: RpcSubscriptions<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>> {
+ *     /* ... *\/
+ * }
+ * const rpcSubscriptions = createSolanaRpcSubscriptions(devnet('https://api.devnet.solana.com'));
+ * await subscribeToSpecialAccountNotifications(address('ReAL1111111111111111111111111111'), rpcSubscriptions); // ERROR
+ * ```
+ */
+
+export type RpcSubscriptionsTestnet<TRpcMethods> = RpcSubscriptions<TRpcMethods> & { '~cluster': 'testnet' };
+/**
+ * A {@link RpcSubscriptions} that supports the RPC Subscriptions methods available on the mainnet
+ * cluster.
+ *
+ * This is useful in cases where you need to make assertions about the suitability of a RPC for a
+ * given purpose. For example, you might like to make it a type error to combine certain types with
+ * RPCs belonging to certain clusters, at compile time.
+ *
+ * @example
+ * ```ts
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address<'ReAL1111111111111111111111111111'>,
+ *     rpcSubscriptions: RpcSubscriptionsMainnet<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>>;
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address<'TeST1111111111111111111111111111'>,
+ *     rpcSubscriptions: RpcSubscriptionsDevnet<unknown> | RpcTestnet<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>>;
+ * async function subscribeToSpecialAccountNotifications(
+ *     address: Address,
+ *     rpcSubscriptions: RpcSubscriptions<unknown>,
+ *     abortSignal: AbortSignal,
+ * ): Promise<AsyncIterable<SpecialAccountInfo>> {
+ *     /* ... *\/
+ * }
+ * const rpcSubscriptions = createSolanaRpcSubscriptions(devnet('https://api.devnet.solana.com'));
+ * await subscribeToSpecialAccountNotifications(address('ReAL1111111111111111111111111111'), rpcSubscriptions); // ERROR
+ * ```
+ */
+export type RpcSubscriptionsMainnet<TRpcMethods> = RpcSubscriptions<TRpcMethods> & { '~cluster': 'mainnet' };
+/**
+ * Given a {@link RpcSubscriptionsTransport} and a set of RPC methods denoted by `TRpcMethods`, this
+ * utility type will resolve to a {@link RpcSubscriptions} that supports those methods on as
+ * specific a cluster as possible.
+ *
+ * @example
+ * ```ts
+ * function createCustomRpcSubscriptions<TRpcSubscriptionsTransport extends RpcSubscriptionsTransport>(
+ *     transport: TRpcSubscriptionsTransport,
+ * ): RpcSubscriptionsFromTransport<MyCustomRpcMethods, TRpcSubscriptionsTransport> {
+ *     /* ... *\/
+ * }
+ * const transport = createDefaultRpcSubscriptionsTransport({
+ *     createChannel: createDefaultSolanaRpcSubscriptionsChannelCreator({
+ *         url: mainnet('ws://rpc.company'),
+ *     }),
+ * });
+ * transport satisfies RpcSubscriptionsTransportMainnet; // OK
+ * const rpcSubscriptions = createCustomRpcSubscriptions(transport);
+ * rpcSubscriptions satisfies RpcSubscriptionsMainnet<MyCustomRpcMethods>; // OK
+ * ```
+ */
+export type RpcSubscriptionsFromTransport<
+    TRpcMethods,
+    TRpcSubscriptionsTransport extends RpcSubscriptionsTransport,
+> = TRpcSubscriptionsTransport extends RpcSubscriptionsTransportDevnet
+    ? RpcSubscriptionsDevnet<TRpcMethods>
+    : TRpcSubscriptionsTransport extends RpcSubscriptionsTransportTestnet
+      ? RpcSubscriptionsTestnet<TRpcMethods>
+      : TRpcSubscriptionsTransport extends RpcSubscriptionsTransportMainnet
+        ? RpcSubscriptionsMainnet<TRpcMethods>
+        : RpcSubscriptions<TRpcMethods>;

package/src/rpc-subscriptions-coalescer.ts

@@ -0,0 +1,73 @@
+import { AbortController } from '@solana/event-target-impl';
+import fastStableStringify from '@solana/fast-stable-stringify';
+import { RpcSubscriptionsTransport } from '@solana/rpc-subscriptions-spec';
+import { DataPublisher } from '@solana/subscribable';
+
+type CacheEntry = {
+    readonly abortController: AbortController;
+    readonly dataPublisherPromise: Promise<DataPublisher>;
+    numSubscribers: number;
+};
+
+/**
+ * Given a {@link RpcSubscriptionsTransport}, will return a new transport that coalesces identical
+ * subscriptions into a single subscription request to the server. The determination of whether a
+ * subscription is the same as another is based on the `rpcRequest` returned by its
+ * {@link RpcSubscriptionsPlan}. The subscription will only be aborted once all subscribers abort,
+ * or there is an error.
+ */
+export function getRpcSubscriptionsTransportWithSubscriptionCoalescing<TTransport extends RpcSubscriptionsTransport>(
+    transport: TTransport,
+): TTransport {
+    const cache = new Map<string, CacheEntry>();
+    return function rpcSubscriptionsTransportWithSubscriptionCoalescing(config) {
+        const { request, signal } = config;
+        const subscriptionConfigurationHash = fastStableStringify([request.methodName, request.params]);
+
+        let cachedDataPublisherPromise = cache.get(subscriptionConfigurationHash);
+        if (!cachedDataPublisherPromise) {
+            const abortController = new AbortController();
+            const dataPublisherPromise = transport({
+                ...config,
+                signal: abortController.signal,
+            });
+            dataPublisherPromise
+                .then(dataPublisher => {
+                    dataPublisher.on(
+                        'error',
+                        () => {
+                            cache.delete(subscriptionConfigurationHash);
+                            abortController.abort();
+                        },
+                        { signal: abortController.signal },
+                    );
+                })
+                .catch(() => {});
+            cache.set(
+                subscriptionConfigurationHash,
+                (cachedDataPublisherPromise = {
+                    abortController,
+                    dataPublisherPromise,
+                    numSubscribers: 0,
+                }),
+            );
+        }
+        cachedDataPublisherPromise.numSubscribers++;
+        signal.addEventListener(
+            'abort',
+            () => {
+                cachedDataPublisherPromise.numSubscribers--;
+                if (cachedDataPublisherPromise.numSubscribers === 0) {
+                    queueMicrotask(() => {
+                        if (cachedDataPublisherPromise.numSubscribers === 0) {
+                            cache.delete(subscriptionConfigurationHash);
+                            cachedDataPublisherPromise.abortController.abort();
+                        }
+                    });
+                }
+            },
+            { signal: cachedDataPublisherPromise.abortController.signal },
+        );
+        return cachedDataPublisherPromise.dataPublisherPromise;
+    } as TTransport;
+}

package/src/rpc-subscriptions-json-bigint.ts

@@ -0,0 +1,24 @@
+import { pipe } from '@solana/functional';
+import { parseJsonWithBigInts, stringifyJsonWithBigInts } from '@solana/rpc-spec-types';
+import {
+    RpcSubscriptionsChannel,
+    transformChannelInboundMessages,
+    transformChannelOutboundMessages,
+} from '@solana/rpc-subscriptions-spec';
+
+/**
+ * Similarly, to {@link getRpcSubscriptionsChannelWithJSONSerialization}, this function will
+ * stringify and parse JSON message to and from the given `string` channel. However, this function
+ * parses any integer value as a `BigInt` in order to safely handle numbers that exceed the
+ * JavaScript [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)
+ * value.
+ */
+export function getRpcSubscriptionsChannelWithBigIntJSONSerialization(
+    channel: RpcSubscriptionsChannel<string, string>,
+): RpcSubscriptionsChannel<unknown, unknown> {
+    return pipe(
+        channel,
+        c => transformChannelInboundMessages(c, parseJsonWithBigInts),
+        c => transformChannelOutboundMessages(c, stringifyJsonWithBigInts),
+    );
+}

package/src/rpc-subscriptions-json.ts

@@ -0,0 +1,21 @@
+import { pipe } from '@solana/functional';
+import {
+    RpcSubscriptionsChannel,
+    transformChannelInboundMessages,
+    transformChannelOutboundMessages,
+} from '@solana/rpc-subscriptions-spec';
+
+/**
+ * Given a {@link RpcSubscriptionsChannel}, will return a new channel that parses data published to
+ * the `'message'` channel as JSON, and JSON-stringifies messages sent via the
+ * {@link RpcSubscriptionsChannel.send | send(message)} method.
+ */
+export function getRpcSubscriptionsChannelWithJSONSerialization(
+    channel: RpcSubscriptionsChannel<string, string>,
+): RpcSubscriptionsChannel<unknown, unknown> {
+    return pipe(
+        channel,
+        c => transformChannelInboundMessages(c, JSON.parse),
+        c => transformChannelOutboundMessages(c, JSON.stringify),
+    );
+}

package/src/rpc-subscriptions-transport.ts

@@ -0,0 +1,56 @@
+import { pipe } from '@solana/functional';
+import { RpcSubscriptionsChannelCreator, RpcSubscriptionsTransport } from '@solana/rpc-subscriptions-spec';
+import { ClusterUrl } from '@solana/rpc-types';
+
+import {
+    RpcSubscriptionsChannelCreatorDevnet,
+    RpcSubscriptionsChannelCreatorFromClusterUrl,
+    RpcSubscriptionsChannelCreatorMainnet,
+    RpcSubscriptionsChannelCreatorTestnet,
+    RpcSubscriptionsTransportDevnet,
+    RpcSubscriptionsTransportFromClusterUrl,
+    RpcSubscriptionsTransportMainnet,
+    RpcSubscriptionsTransportTestnet,
+} from './rpc-subscriptions-clusters';
+import { getRpcSubscriptionsTransportWithSubscriptionCoalescing } from './rpc-subscriptions-coalescer';
+
+export type DefaultRpcSubscriptionsTransportConfig<TClusterUrl extends ClusterUrl> = Readonly<{
+    createChannel: RpcSubscriptionsChannelCreatorFromClusterUrl<TClusterUrl, unknown, unknown>;
+}>;
+
+/**
+ * Creates a {@link RpcSubscriptionsTransport} with some default behaviours.
+ *
+ * The default behaviours include:
+ * - Logic that coalesces multiple subscriptions for the same notifications with the same arguments
+ *   into a single subscription.
+ *
+ * @param config
+ */
+export function createDefaultRpcSubscriptionsTransport<TClusterUrl extends ClusterUrl>({
+    createChannel,
+}: DefaultRpcSubscriptionsTransportConfig<TClusterUrl>) {
+    return pipe(
+        createRpcSubscriptionsTransportFromChannelCreator(
+            createChannel,
+        ) as RpcSubscriptionsTransport as RpcSubscriptionsTransportFromClusterUrl<TClusterUrl>,
+        transport => getRpcSubscriptionsTransportWithSubscriptionCoalescing(transport),
+    );
+}
+
+export function createRpcSubscriptionsTransportFromChannelCreator<
+    TChannelCreator extends RpcSubscriptionsChannelCreator<TOutboundMessage, TInboundMessage>,
+    TInboundMessage,
+    TOutboundMessage,
+>(createChannel: TChannelCreator) {
+    return (async ({ execute, signal }) => {
+        const channel = await createChannel({ abortSignal: signal });
+        return await execute({ channel, signal });
+    }) as TChannelCreator extends RpcSubscriptionsChannelCreatorDevnet<TOutboundMessage, TInboundMessage>
+        ? RpcSubscriptionsTransportDevnet
+        : TChannelCreator extends RpcSubscriptionsChannelCreatorTestnet<TOutboundMessage, TInboundMessage>
+          ? RpcSubscriptionsTransportTestnet
+          : TChannelCreator extends RpcSubscriptionsChannelCreatorMainnet<TOutboundMessage, TInboundMessage>
+            ? RpcSubscriptionsTransportMainnet
+            : RpcSubscriptionsTransport;
+}

package/src/rpc-subscriptions.ts

@@ -0,0 +1,69 @@
+import type { SolanaRpcSubscriptionsApi, SolanaRpcSubscriptionsApiUnstable } from '@solana/rpc-subscriptions-api';
+import { createSolanaRpcSubscriptionsApi } from '@solana/rpc-subscriptions-api';
+import {
+    createSubscriptionRpc,
+    RpcSubscriptionsApiMethods,
+    type RpcSubscriptionsTransport,
+} from '@solana/rpc-subscriptions-spec';
+import { ClusterUrl } from '@solana/rpc-types';
+
+import { DEFAULT_RPC_SUBSCRIPTIONS_CONFIG } from './rpc-default-config';
+import {
+    createDefaultSolanaRpcSubscriptionsChannelCreator,
+    DefaultRpcSubscriptionsChannelConfig,
+} from './rpc-subscriptions-channel';
+import type { RpcSubscriptionsFromTransport } from './rpc-subscriptions-clusters';
+import { createDefaultRpcSubscriptionsTransport } from './rpc-subscriptions-transport';
+
+type Config<TClusterUrl extends ClusterUrl> = DefaultRpcSubscriptionsChannelConfig<TClusterUrl>;
+
+function createSolanaRpcSubscriptionsImpl<TClusterUrl extends ClusterUrl, TApi extends RpcSubscriptionsApiMethods>(
+    clusterUrl: TClusterUrl,
+    config?: Omit<Config<TClusterUrl>, 'url'>,
+) {
+    const transport = createDefaultRpcSubscriptionsTransport({
+        createChannel: createDefaultSolanaRpcSubscriptionsChannelCreator({ ...config, url: clusterUrl }),
+    });
+    return createSolanaRpcSubscriptionsFromTransport<typeof transport, TApi>(transport);
+}
+
+/**
+ * Creates a {@link RpcSubscriptions} instance that exposes the Solana JSON RPC WebSocket API given
+ * a cluster URL and some optional channel config. See
+ * {@link createDefaultRpcSubscriptionsChannelCreator} for the shape of the channel config.
+ */
+export function createSolanaRpcSubscriptions<TClusterUrl extends ClusterUrl>(
+    clusterUrl: TClusterUrl,
+    config?: Omit<Config<TClusterUrl>, 'url'>,
+) {
+    return createSolanaRpcSubscriptionsImpl<TClusterUrl, SolanaRpcSubscriptionsApi>(clusterUrl, config);
+}
+
+/**
+ * Creates a {@link RpcSubscriptions} instance that exposes the Solana JSON RPC WebSocket API,
+ * including its unstable methods, given a cluster URL and some optional channel config. See
+ * {@link createDefaultRpcSubscriptionsChannelCreator} for the shape of the channel config.
+ */
+export function createSolanaRpcSubscriptions_UNSTABLE<TClusterUrl extends ClusterUrl>(
+    clusterUrl: TClusterUrl,
+    config?: Omit<Config<TClusterUrl>, 'url'>,
+) {
+    return createSolanaRpcSubscriptionsImpl<TClusterUrl, SolanaRpcSubscriptionsApi & SolanaRpcSubscriptionsApiUnstable>(
+        clusterUrl,
+        config,
+    );
+}
+
+/**
+ * Creates a {@link RpcSubscriptions} instance that exposes the Solana JSON RPC WebSocket API given
+ * the supplied {@link RpcSubscriptionsTransport}.
+ */
+export function createSolanaRpcSubscriptionsFromTransport<
+    TTransport extends RpcSubscriptionsTransport,
+    TApi extends RpcSubscriptionsApiMethods = SolanaRpcSubscriptionsApi,
+>(transport: TTransport) {
+    return createSubscriptionRpc({
+        api: createSolanaRpcSubscriptionsApi<TApi>(DEFAULT_RPC_SUBSCRIPTIONS_CONFIG),
+        transport,
+    }) as RpcSubscriptionsFromTransport<TApi, TTransport>;
+}