@solana/rpc-subscriptions-spec 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/rpc-subscriptions-spec",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "A generic implementation of JSON RPC Subscriptions using proxies",
   "homepage": "https://www.solanakit.com/api#solanarpc-subscriptions-spec",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,10 +56,10 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "6.3.1",
-    "@solana/promises": "6.3.1",
-    "@solana/subscribable": "6.3.1",
-    "@solana/rpc-spec-types": "6.3.1"
+    "@solana/errors": "6.3.2-canary-20260313112147",
+    "@solana/promises": "6.3.2-canary-20260313112147",
+    "@solana/rpc-spec-types": "6.3.2-canary-20260313112147",
+    "@solana/subscribable": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * This package contains types that describe the implementation of the JSON RPC Subscriptions API,
+ * as well as methods to create one. 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).
+ *
+ * @example
+ * ```ts
+ * const rpcSubscriptions =
+ *     // Step 1 - Create a `RpcSubscriptions` instance. This may be stateful.
+ *     createSolanaRpcSubscriptions(mainnet('wss://api.mainnet-beta.solana.com'));
+ * const response = await rpcSubscriptions
+ *     // Step 2 - Call supported methods on it to produce `PendingRpcSubscriptionsRequest` objects.
+ *     .slotNotifications({ commitment: 'confirmed' })
+ *     // Step 3 - Call the `subscribe()` method on those pending requests to trigger them.
+ *     .subscribe({ abortSignal: AbortSignal.timeout(10_000) });
+ * // Step 4 - Iterate over the result.
+ * try {
+ *     for await (const slotNotification of slotNotifications) {
+ *         console.log('Got a slot notification', slotNotification);
+ *     }
+ * } catch (e) {
+ *     console.error('The subscription closed unexpectedly', e);
+ * } finally {
+ *     console.log('We have stopped listening for notifications');
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * from './rpc-subscriptions-request';
+export * from './rpc-subscriptions';
+export * from './rpc-subscriptions-api';
+export * from './rpc-subscriptions-channel';
+export * from './rpc-subscriptions-pubsub-plan';
+export * from './rpc-subscriptions-transport';

package/src/rpc-subscriptions-api.ts

@@ -0,0 +1,168 @@
+import { Callable, RpcRequest, RpcRequestTransformer } from '@solana/rpc-spec-types';
+import { DataPublisher } from '@solana/subscribable';
+
+import { RpcSubscriptionsChannel } from './rpc-subscriptions-channel';
+import { RpcSubscriptionsTransportDataEvents } from './rpc-subscriptions-transport';
+
+export type RpcSubscriptionsApiConfig<TApiMethods extends RpcSubscriptionsApiMethods> = Readonly<{
+    planExecutor: RpcSubscriptionsPlanExecutor<ReturnType<TApiMethods[keyof TApiMethods]>>;
+    /**
+     * An optional function that transforms the {@link RpcRequest} before it is sent to the JSON RPC
+     * server.
+     *
+     * This is useful when the params supplied by the caller need to be transformed before
+     * forwarding the message to the server. Use cases for this include applying defaults,
+     * forwarding calls to renamed methods, and serializing complex values.
+     */
+    requestTransformer?: RpcRequestTransformer;
+}>;
+
+/**
+ * A function that implements a protocol for subscribing and unsubscribing from notifications given
+ * a {@link RpcSubscriptionsChannel}, a {@link RpcRequest}, and an `AbortSignal`.
+ *
+ * @returns A {@link DataPublisher} that emits {@link RpcSubscriptionsTransportDataEvents}
+ */
+type RpcSubscriptionsPlanExecutor<TNotification> = (
+    config: Readonly<{
+        channel: RpcSubscriptionsChannel<unknown, unknown>;
+        request: RpcRequest;
+        signal: AbortSignal;
+    }>,
+) => Promise<DataPublisher<RpcSubscriptionsTransportDataEvents<TNotification>>>;
+
+/**
+ * This type allows an {@link RpcSubscriptionsApi} to describe how a particular subscription should
+ * be issued to the JSON RPC server.
+ *
+ * Given a function that was called on a {@link RpcSubscriptions}, this object exposes an `execute`
+ * function that dictates which subscription request will be sent, how the underlying transport will
+ * be used, and how the notifications will be transformed.
+ *
+ * This function accepts a {@link RpcSubscriptionsChannel} and an `AbortSignal` and asynchronously
+ * returns a {@link DataPublisher}. This gives us the opportunity to:
+ *
+ * - define the `payload` from the requested method name and parameters before passing it to the
+ *   channel.
+ * - call the underlying channel zero, one or multiple times depending on the use-case (e.g.
+ *   caching or coalescing multiple subscriptions).
+ * - transform the notification from the JSON RPC server, in case it does not match the
+ *   `TNotification` specified by the
+ *   {@link PendingRpcSubscriptionsRequest | PendingRpcSubscriptionsRequest<TNotification>} emitted
+ *   from the publisher returned.
+ */
+export type RpcSubscriptionsPlan<TNotification> = Readonly<{
+    /**
+     * This method may be called with a newly-opened channel or a pre-established channel.
+     */
+    execute: (
+        config: Readonly<{
+            channel: RpcSubscriptionsChannel<unknown, unknown>;
+            signal: AbortSignal;
+        }>,
+    ) => Promise<DataPublisher<RpcSubscriptionsTransportDataEvents<TNotification>>>;
+    /**
+     * This request is used to uniquely identify the subscription.
+     * It typically comes from the method name and parameters of the subscription call,
+     * after potentially being transformed by the RPC Subscriptions API.
+     */
+    request: RpcRequest;
+}>;
+
+/**
+ * For each of `TRpcSubscriptionsMethods`, this object exposes a method with the same name that maps
+ * between its input arguments and a
+ * {@link RpcSubscriptionsPlan | RpcSubscriptionsPlan<TNotification>} that implements the execution
+ * of a JSON RPC subscription for `TNotifications`.
+ */
+export type RpcSubscriptionsApi<TRpcSubscriptionMethods> = {
+    [MethodName in keyof TRpcSubscriptionMethods]: RpcSubscriptionsReturnTypeMapper<
+        TRpcSubscriptionMethods[MethodName]
+    >;
+};
+
+type RpcSubscriptionsReturnTypeMapper<TRpcMethod> = TRpcMethod extends Callable
+    ? (...rawParams: unknown[]) => RpcSubscriptionsPlan<ReturnType<TRpcMethod>>
+    : never;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RpcSubscriptionsApiMethod = (...args: any) => any;
+export interface RpcSubscriptionsApiMethods {
+    [methodName: string]: RpcSubscriptionsApiMethod;
+}
+
+/**
+ * Creates a JavaScript proxy that converts _any_ function call called on it to a
+ * {@link RpcSubscriptionsPlan} by creating an `execute` function that:
+ *
+ * - calls the supplied {@link RpcSubscriptionsApiConfig.planExecutor} with a JSON RPC v2 payload
+ *   object with the requested `methodName` and `params` properties, optionally transformed by
+ *   {@link RpcSubscriptionsApiConfig.requestTransformer}.
+ *
+ * @example
+ * ```ts
+ * // For example, given this `RpcSubscriptionsApi`:
+ * const rpcSubscriptionsApi = createJsonRpcSubscriptionsApi({
+ *     async planExecutor({ channel, request }) {
+ *         await channel.send(request);
+ *         return {
+ *             ...channel,
+ *             on(type, listener, options) {
+ *                 if (type !== 'message') {
+ *                     return channel.on(type, listener, options);
+ *                 }
+ *                 return channel.on(
+ *                     'message',
+ *                     function resultGettingListener(message) {
+ *                         listener(message.result);
+ *                     },
+ *                     options,
+ *                 );
+ *             }
+ *         }
+ *     },
+ *     requestTransformer: (...rawParams) => rawParams.reverse(),
+ * });
+ *
+ * // ...the following function call:
+ * rpcSubscriptionsApi.foo('bar', { baz: 'bat' });
+ *
+ * // ...will produce a `RpcSubscriptionsPlan` that:
+ * // -   Uses the following payload: { id: 1, jsonrpc: '2.0', method: 'foo', params: [{ baz: 'bat' }, 'bar'] }.
+ * // -   Emits the "result" property of each RPC Subscriptions message.
+ * ```
+ */
+export function createRpcSubscriptionsApi<TRpcSubscriptionsApiMethods extends RpcSubscriptionsApiMethods>(
+    config: RpcSubscriptionsApiConfig<TRpcSubscriptionsApiMethods>,
+): RpcSubscriptionsApi<TRpcSubscriptionsApiMethods> {
+    return new Proxy({} as RpcSubscriptionsApi<TRpcSubscriptionsApiMethods>, {
+        defineProperty() {
+            return false;
+        },
+        deleteProperty() {
+            return false;
+        },
+        get<TNotificationName extends keyof RpcSubscriptionsApi<TRpcSubscriptionsApiMethods>>(
+            ...args: Parameters<NonNullable<ProxyHandler<RpcSubscriptionsApi<TRpcSubscriptionsApiMethods>>['get']>>
+        ) {
+            const [_, p] = args;
+            const methodName = p.toString() as keyof TRpcSubscriptionsApiMethods as string;
+            return function (
+                ...params: Parameters<
+                    TRpcSubscriptionsApiMethods[TNotificationName] extends CallableFunction
+                        ? TRpcSubscriptionsApiMethods[TNotificationName]
+                        : never
+                >
+            ): RpcSubscriptionsPlan<ReturnType<TRpcSubscriptionsApiMethods[TNotificationName]>> {
+                const rawRequest = { methodName, params };
+                const request = config.requestTransformer ? config.requestTransformer(rawRequest) : rawRequest;
+                return {
+                    execute(planConfig) {
+                        return config.planExecutor({ ...planConfig, request });
+                    },
+                    request,
+                };
+            };
+        },
+    });
+}

package/src/rpc-subscriptions-channel.ts

@@ -0,0 +1,101 @@
+import {
+    SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED,
+    SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CONNECTION_CLOSED,
+    SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_FAILED_TO_CONNECT,
+    SolanaError,
+} from '@solana/errors';
+import { DataPublisher } from '@solana/subscribable';
+
+type RpcSubscriptionsChannelSolanaErrorCode =
+    | typeof SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED
+    | typeof SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CONNECTION_CLOSED
+    | typeof SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_FAILED_TO_CONNECT;
+
+export type RpcSubscriptionChannelEvents<TInboundMessage> = {
+    /**
+     * Fires when the channel closes unexpectedly.
+     * @eventProperty
+     */
+    error: SolanaError<RpcSubscriptionsChannelSolanaErrorCode>;
+    /**
+     * Fires on every message received from the remote end.
+     * @eventProperty
+     */
+    message: TInboundMessage;
+};
+
+/**
+ * A {@link DataPublisher} on which you can subscribe to events of type
+ * {@link RpcSubscriptionChannelEvents | RpcSubscriptionChannelEvents<TInboundMessage>}.
+ * Additionally, you can use this object to send messages of type `TOutboundMessage` back to the
+ * remote end by calling its {@link RpcSubscriptionsChannel.send | `send(message)`} method.
+ */
+export interface RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage> extends DataPublisher<
+    RpcSubscriptionChannelEvents<TInboundMessage>
+> {
+    send(message: TOutboundMessage): Promise<void>;
+}
+
+/**
+ * A channel creator is a function that accepts an `AbortSignal`, returns a new
+ * {@link RpcSubscriptionsChannel}, and tears down the channel when the abort signal fires.
+ */
+export type RpcSubscriptionsChannelCreator<TOutboundMessage, TInboundMessage> = (
+    config: Readonly<{
+        abortSignal: AbortSignal;
+    }>,
+) => Promise<RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>>;
+
+/**
+ * Given a channel with inbound messages of type `T` and a function of type `T => U`, returns a new
+ * channel with inbound messages of type `U`.
+ *
+ * Note that this only affects messages of type `"message"` and thus, does not affect incoming error
+ * messages.
+ *
+ * @example Parsing incoming JSON messages
+ * ```ts
+ * const transformedChannel = transformChannelInboundMessages(channel, JSON.parse);
+ * ```
+ */
+export function transformChannelInboundMessages<TOutboundMessage, TNewInboundMessage, TInboundMessage>(
+    channel: RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>,
+    transform: (message: TInboundMessage) => TNewInboundMessage,
+): RpcSubscriptionsChannel<TOutboundMessage, TNewInboundMessage> {
+    return Object.freeze<RpcSubscriptionsChannel<TOutboundMessage, TNewInboundMessage>>({
+        ...channel,
+        on(type, subscriber, options) {
+            if (type !== 'message') {
+                return channel.on(
+                    type,
+                    subscriber as (data: RpcSubscriptionChannelEvents<TInboundMessage>[typeof type]) => void,
+                    options,
+                );
+            }
+            return channel.on(
+                'message',
+                message => (subscriber as (data: TNewInboundMessage) => void)(transform(message)),
+                options,
+            );
+        },
+    });
+}
+
+/**
+ * Given a channel with outbound messages of type `T` and a function of type `U => T`, returns a new
+ * channel with outbound messages of type `U`.
+ *
+ * @example Stringifying JSON messages before sending them over the wire
+ * ```ts
+ * const transformedChannel = transformChannelOutboundMessages(channel, JSON.stringify);
+ * ```
+ */
+export function transformChannelOutboundMessages<TNewOutboundMessage, TOutboundMessage, TInboundMessage>(
+    channel: RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>,
+    transform: (message: TNewOutboundMessage) => TOutboundMessage,
+): RpcSubscriptionsChannel<TNewOutboundMessage, TInboundMessage> {
+    return Object.freeze<RpcSubscriptionsChannel<TNewOutboundMessage, TInboundMessage>>({
+        ...channel,
+        send: message => channel.send(transform(message)),
+    });
+}

package/src/rpc-subscriptions-pubsub-plan.ts

@@ -0,0 +1,241 @@
+import {
+    getSolanaErrorFromJsonRpcError,
+    SOLANA_ERROR__INVARIANT_VIOLATION__DATA_PUBLISHER_CHANNEL_UNIMPLEMENTED,
+    SOLANA_ERROR__RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID,
+    SolanaError,
+} from '@solana/errors';
+import { AbortController } from '@solana/event-target-impl';
+import { safeRace } from '@solana/promises';
+import { createRpcMessage, RpcRequest, RpcResponseData, RpcResponseTransformer } from '@solana/rpc-spec-types';
+import { DataPublisher } from '@solana/subscribable';
+import { demultiplexDataPublisher } from '@solana/subscribable';
+
+import { RpcSubscriptionChannelEvents } from './rpc-subscriptions-channel';
+import { RpcSubscriptionsChannel } from './rpc-subscriptions-channel';
+
+type Config<TNotification> = Readonly<{
+    channel: RpcSubscriptionsChannel<unknown, RpcNotification<TNotification> | RpcResponseData<RpcSubscriptionId>>;
+    responseTransformer?: RpcResponseTransformer;
+    signal: AbortSignal;
+    subscribeRequest: RpcRequest;
+    unsubscribeMethodName: string;
+}>;
+
+type RpcNotification<TNotification> = Readonly<{
+    method: string;
+    params: Readonly<{
+        result: TNotification;
+        subscription: number;
+    }>;
+}>;
+
+type RpcSubscriptionId = number;
+
+type RpcSubscriptionNotificationEvents<TNotification> = Omit<RpcSubscriptionChannelEvents<TNotification>, 'message'> & {
+    notification: TNotification;
+};
+
+const subscriberCountBySubscriptionIdByChannel = new WeakMap<WeakKey, Record<number, number>>();
+function decrementSubscriberCountAndReturnNewCount(channel: WeakKey, subscriptionId?: number): number | undefined {
+    return augmentSubscriberCountAndReturnNewCount(-1, channel, subscriptionId);
+}
+function incrementSubscriberCount(channel: WeakKey, subscriptionId?: number): void {
+    augmentSubscriberCountAndReturnNewCount(1, channel, subscriptionId);
+}
+function getSubscriberCountBySubscriptionIdForChannel(channel: WeakKey): Record<number, number> {
+    let subscriberCountBySubscriptionId = subscriberCountBySubscriptionIdByChannel.get(channel);
+    if (!subscriberCountBySubscriptionId) {
+        subscriberCountBySubscriptionIdByChannel.set(channel, (subscriberCountBySubscriptionId = {}));
+    }
+    return subscriberCountBySubscriptionId;
+}
+function augmentSubscriberCountAndReturnNewCount(
+    amount: -1 | 1,
+    channel: WeakKey,
+    subscriptionId?: number,
+): number | undefined {
+    if (subscriptionId === undefined) {
+        return;
+    }
+    const subscriberCountBySubscriptionId = getSubscriberCountBySubscriptionIdForChannel(channel);
+    if (!subscriberCountBySubscriptionId[subscriptionId] && amount > 0) {
+        subscriberCountBySubscriptionId[subscriptionId] = 0;
+    }
+    const newCount = amount + subscriberCountBySubscriptionId[subscriptionId];
+    if (newCount <= 0) {
+        delete subscriberCountBySubscriptionId[subscriptionId];
+    } else {
+        subscriberCountBySubscriptionId[subscriptionId] = newCount;
+    }
+    return newCount;
+}
+
+const cache = new WeakMap();
+function getMemoizedDemultiplexedNotificationPublisherFromChannelAndResponseTransformer<TNotification>(
+    channel: RpcSubscriptionsChannel<unknown, RpcNotification<TNotification>>,
+    subscribeRequest: RpcRequest,
+    responseTransformer?: RpcResponseTransformer,
+): DataPublisher<{
+    [channelName: `notification:${number}`]: TNotification;
+}> {
+    let publisherByResponseTransformer = cache.get(channel);
+    if (!publisherByResponseTransformer) {
+        cache.set(channel, (publisherByResponseTransformer = new WeakMap()));
+    }
+    const responseTransformerKey = responseTransformer ?? channel;
+    let publisher = publisherByResponseTransformer.get(responseTransformerKey);
+    if (!publisher) {
+        publisherByResponseTransformer.set(
+            responseTransformerKey,
+            (publisher = demultiplexDataPublisher(channel, 'message', rawMessage => {
+                const message = rawMessage as RpcNotification<unknown> | RpcResponseData<unknown>;
+                if (!('method' in message)) {
+                    return;
+                }
+                const transformedNotification = responseTransformer
+                    ? responseTransformer(message.params.result, subscribeRequest)
+                    : message.params.result;
+                return [`notification:${message.params.subscription}`, transformedNotification];
+            })),
+        );
+    }
+    return publisher;
+}
+
+/**
+ * Given a channel, this function executes the particular subscription plan required by the Solana
+ * JSON RPC Subscriptions API.
+ *
+ * @param config
+ *
+ * 1. Calls the `subscribeRequest` on the remote RPC
+ * 2. Waits for a response containing the subscription id
+ * 3. Returns a {@link DataPublisher} that publishes notifications related to that subscriptions id,
+ *    filtering out all others
+ * 4. Calls the `unsubscribeMethodName` on the remote RPC when the abort signal is fired.
+ */
+export async function executeRpcPubSubSubscriptionPlan<TNotification>({
+    channel,
+    responseTransformer,
+    signal,
+    subscribeRequest,
+    unsubscribeMethodName,
+}: Config<TNotification>): Promise<DataPublisher<RpcSubscriptionNotificationEvents<TNotification>>> {
+    let subscriptionId: number | undefined;
+    channel.on(
+        'error',
+        () => {
+            // An error on the channel indicates that the subscriptions are dead.
+            // There is no longer any sense hanging on to subscription ids.
+            // Erasing it here will prevent the unsubscribe code from running.
+            subscriptionId = undefined;
+            subscriberCountBySubscriptionIdByChannel.delete(channel);
+        },
+        { signal },
+    );
+    /**
+     * STEP 1
+     * Create a promise that rejects if this subscription is aborted and sends
+     * the unsubscribe message if the subscription is active at that time.
+     */
+    const abortPromise = new Promise<never>((_, reject) => {
+        function handleAbort(this: AbortSignal) {
+            /**
+             * 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
+             * must be careful not to send the unsubscribe message until the last subscriber aborts.
+             */
+            if (decrementSubscriberCountAndReturnNewCount(channel, subscriptionId) === 0) {
+                const unsubscribePayload = createRpcMessage({
+                    methodName: unsubscribeMethodName,
+                    params: [subscriptionId],
+                });
+                subscriptionId = undefined;
+                channel.send(unsubscribePayload).catch(() => {});
+            }
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+            reject(this.reason);
+        }
+        if (signal.aborted) {
+            handleAbort.call(signal);
+        } else {
+            signal.addEventListener('abort', handleAbort);
+        }
+    });
+    /**
+     * STEP 2
+     * Send the subscription request.
+     */
+    const subscribePayload = createRpcMessage(subscribeRequest);
+    await channel.send(subscribePayload);
+    /**
+     * STEP 3
+     * Wait for the acknowledgement from the server with the subscription id.
+     */
+    const subscriptionIdPromise = new Promise<RpcSubscriptionId>((resolve, reject) => {
+        const abortController = new AbortController();
+        signal.addEventListener('abort', abortController.abort.bind(abortController));
+        const options = { signal: abortController.signal } as const;
+        channel.on(
+            'error',
+            err => {
+                abortController.abort();
+                reject(err);
+            },
+            options,
+        );
+        channel.on(
+            'message',
+            message => {
+                if (message && typeof message === 'object' && 'id' in message && message.id === subscribePayload.id) {
+                    abortController.abort();
+                    if ('error' in message) {
+                        reject(getSolanaErrorFromJsonRpcError(message.error));
+                    } else {
+                        resolve(message.result);
+                    }
+                }
+            },
+            options,
+        );
+    });
+    subscriptionId = await safeRace([abortPromise, subscriptionIdPromise]);
+    if (subscriptionId == null) {
+        throw new SolanaError(SOLANA_ERROR__RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID);
+    }
+    incrementSubscriberCount(channel, subscriptionId);
+    /**
+     * STEP 4
+     * Filter out notifications unrelated to this subscription.
+     */
+    const notificationPublisher = getMemoizedDemultiplexedNotificationPublisherFromChannelAndResponseTransformer(
+        channel,
+        subscribeRequest,
+        responseTransformer,
+    );
+    const notificationKey = `notification:${subscriptionId}` as const;
+    return {
+        on(type, listener, options) {
+            switch (type) {
+                case 'notification':
+                    return notificationPublisher.on(
+                        notificationKey,
+                        listener as (data: RpcSubscriptionNotificationEvents<TNotification>['notification']) => void,
+                        options,
+                    );
+                case 'error':
+                    return channel.on(
+                        'error',
+                        listener as (data: RpcSubscriptionNotificationEvents<TNotification>['error']) => void,
+                        options,
+                    );
+                default:
+                    throw new SolanaError(SOLANA_ERROR__INVARIANT_VIOLATION__DATA_PUBLISHER_CHANNEL_UNIMPLEMENTED, {
+                        channelName: type,
+                        supportedChannelNames: ['notification', 'error'],
+                    });
+            }
+        },
+    };
+}

package/src/rpc-subscriptions-request.ts

@@ -0,0 +1,17 @@
+/**
+ * Pending subscriptions are the result of calling a supported method on a {@link RpcSubscriptions}
+ * object. They encapsulate all of the information necessary to make the subscription without
+ * actually making it.
+ *
+ * Calling the {@link PendingRpcSubscriptionsRequest.subscribe | `subscribe(options)`} method on a
+ * {@link PendingRpcSubscriptionsRequest | PendingRpcSubscriptionsRequest<TNotification>} will
+ * trigger the subscription and return a promise for an async iterable that vends `TNotifications`.
+ */
+export type PendingRpcSubscriptionsRequest<TNotification> = {
+    subscribe(options: RpcSubscribeOptions): Promise<AsyncIterable<TNotification>>;
+};
+
+export type RpcSubscribeOptions = Readonly<{
+    /** An `AbortSignal` to fire when you want to unsubscribe */
+    abortSignal: AbortSignal;
+}>;

package/src/rpc-subscriptions-transport.ts

@@ -0,0 +1,32 @@
+import { SolanaError } from '@solana/errors';
+import { DataPublisher } from '@solana/subscribable';
+
+import { RpcSubscriptionsPlan } from './rpc-subscriptions-api';
+
+export type RpcSubscriptionsTransportDataEvents<TNotification> = {
+    /**
+     * Fires when there is an error with the subscription or the channel.
+     * @eventProperty
+     */
+    error: SolanaError;
+    /**
+     * Fires on every notification received.
+     * @eventProperty
+     */
+    notification: TNotification;
+};
+
+interface RpcSubscriptionsTransportConfig<TNotification> extends RpcSubscriptionsPlan<TNotification> {
+    /** An `AbortSignal` to fire when you want to unsubscribe */
+    signal: AbortSignal;
+}
+
+/**
+ * A function that can act as a transport for a {@link RpcSubscriptions}. It need only return a
+ * promise for a {@link DataPublisher} given the supplied config.
+ */
+export interface RpcSubscriptionsTransport {
+    <TNotification>(
+        config: RpcSubscriptionsTransportConfig<TNotification>,
+    ): Promise<DataPublisher<RpcSubscriptionsTransportDataEvents<TNotification>>>;
+}

package/src/rpc-subscriptions.ts

@@ -0,0 +1,95 @@
+import { SOLANA_ERROR__RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_PLAN, SolanaError } from '@solana/errors';
+import { Callable, Flatten, OverloadImplementations, UnionToIntersection } from '@solana/rpc-spec-types';
+import { createAsyncIterableFromDataPublisher } from '@solana/subscribable';
+
+import { RpcSubscriptionsApi, RpcSubscriptionsPlan } from './rpc-subscriptions-api';
+import { PendingRpcSubscriptionsRequest, RpcSubscribeOptions } from './rpc-subscriptions-request';
+import { RpcSubscriptionsTransport } from './rpc-subscriptions-transport';
+
+export type RpcSubscriptionsConfig<TRpcMethods> = Readonly<{
+    api: RpcSubscriptionsApi<TRpcMethods>;
+    transport: RpcSubscriptionsTransport;
+}>;
+
+/**
+ * An object that exposes all of the functions described by `TRpcSubscriptionsMethods`.
+ *
+ * Calling each method returns a
+ * {@link PendingRpcSubscriptionsRequest | PendingRpcSubscriptionsRequest<TNotification>} where
+ * `TNotification` is that method's notification type.
+ */
+export type RpcSubscriptions<TRpcSubscriptionsMethods> = {
+    [TMethodName in keyof TRpcSubscriptionsMethods]: PendingRpcSubscriptionsRequestBuilder<
+        OverloadImplementations<TRpcSubscriptionsMethods, TMethodName>
+    >;
+};
+
+type PendingRpcSubscriptionsRequestBuilder<TSubscriptionMethodImplementations> = UnionToIntersection<
+    Flatten<{
+        [P in keyof TSubscriptionMethodImplementations]: PendingRpcSubscriptionsRequestReturnTypeMapper<
+            TSubscriptionMethodImplementations[P]
+        >;
+    }>
+>;
+
+type PendingRpcSubscriptionsRequestReturnTypeMapper<TSubscriptionMethodImplementation> =
+    // Check that this property of the TRpcSubscriptionMethods interface is, in fact, a function.
+    TSubscriptionMethodImplementation extends Callable
+        ? (
+              ...args: Parameters<TSubscriptionMethodImplementation>
+          ) => PendingRpcSubscriptionsRequest<ReturnType<TSubscriptionMethodImplementation>>
+        : never;
+
+/**
+ * Creates a {@link RpcSubscriptions} instance given a
+ * {@link RpcSubscriptionsApi | RpcSubscriptionsApi<TRpcSubscriptionsApiMethods>} and a
+ * {@link RpcSubscriptionsTransport} capable of fulfilling them.
+ */
+export function createSubscriptionRpc<TRpcSubscriptionsApiMethods>(
+    rpcConfig: RpcSubscriptionsConfig<TRpcSubscriptionsApiMethods>,
+): RpcSubscriptions<TRpcSubscriptionsApiMethods> {
+    return new Proxy(rpcConfig.api, {
+        defineProperty() {
+            return false;
+        },
+        deleteProperty() {
+            return false;
+        },
+        get(target, p, receiver) {
+            if (p === 'then') {
+                return undefined;
+            }
+            return function (...rawParams: unknown[]) {
+                const notificationName = p.toString();
+                const createRpcSubscriptionPlan = Reflect.get(target, notificationName, receiver);
+                if (!createRpcSubscriptionPlan) {
+                    throw new SolanaError(SOLANA_ERROR__RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_PLAN, {
+                        notificationName,
+                    });
+                }
+                const subscriptionPlan = createRpcSubscriptionPlan(...rawParams);
+                return createPendingRpcSubscription(rpcConfig.transport, subscriptionPlan);
+            };
+        },
+    }) as RpcSubscriptions<TRpcSubscriptionsApiMethods>;
+}
+
+function createPendingRpcSubscription<TNotification>(
+    transport: RpcSubscriptionsTransport,
+    subscriptionsPlan: RpcSubscriptionsPlan<TNotification>,
+): PendingRpcSubscriptionsRequest<TNotification> {
+    return {
+        async subscribe({ abortSignal }: RpcSubscribeOptions): Promise<AsyncIterable<TNotification>> {
+            const notificationsDataPublisher = await transport({
+                signal: abortSignal,
+                ...subscriptionsPlan,
+            });
+            return createAsyncIterableFromDataPublisher<TNotification>({
+                abortSignal,
+                dataChannelName: 'notification',
+                dataPublisher: notificationsDataPublisher,
+                errorChannelName: 'error',
+            });
+        },
+    };
+}