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

package/src/index.ts

@@ -0,0 +1,261 @@
+import {
+    createRpcSubscriptionsApi,
+    executeRpcPubSubSubscriptionPlan,
+    RpcSubscriptionsApi,
+    RpcSubscriptionsApiMethods,
+} from '@solana/rpc-subscriptions-spec';
+import {
+    AllowedNumericKeypaths,
+    getDefaultRequestTransformerForSolanaRpc,
+    getDefaultResponseTransformerForSolanaRpcSubscriptions,
+    jsonParsedAccountsConfigs,
+    KEYPATH_WILDCARD,
+    RequestTransformerConfig,
+} from '@solana/rpc-transformers';
+
+import { AccountNotificationsApi } from './account-notifications';
+import { BlockNotificationsApi } from './block-notifications';
+import { LogsNotificationsApi } from './logs-notifications';
+import { ProgramNotificationsApi } from './program-notifications';
+import { RootNotificationsApi } from './root-notifications';
+import { SignatureNotificationsApi } from './signature-notifications';
+import { SlotNotificationsApi } from './slot-notifications';
+import { SlotsUpdatesNotificationsApi } from './slots-updates-notifications';
+import { VoteNotificationsApi } from './vote-notifications';
+
+export type SolanaRpcSubscriptionsApi = AccountNotificationsApi &
+    LogsNotificationsApi &
+    ProgramNotificationsApi &
+    RootNotificationsApi &
+    SignatureNotificationsApi &
+    SlotNotificationsApi;
+export type SolanaRpcSubscriptionsApiUnstable = BlockNotificationsApi &
+    SlotsUpdatesNotificationsApi &
+    VoteNotificationsApi;
+
+export type {
+    AccountNotificationsApi,
+    BlockNotificationsApi,
+    LogsNotificationsApi,
+    ProgramNotificationsApi,
+    RootNotificationsApi,
+    SignatureNotificationsApi,
+    SlotNotificationsApi,
+    SlotsUpdatesNotificationsApi,
+    VoteNotificationsApi,
+};
+
+type Config = RequestTransformerConfig;
+
+function createSolanaRpcSubscriptionsApi_INTERNAL<TApi extends RpcSubscriptionsApiMethods>(
+    config?: Config,
+): RpcSubscriptionsApi<TApi> {
+    const requestTransformer = getDefaultRequestTransformerForSolanaRpc(config);
+    const responseTransformer = getDefaultResponseTransformerForSolanaRpcSubscriptions({
+        allowedNumericKeyPaths: getAllowedNumericKeypaths(),
+    });
+    return createRpcSubscriptionsApi<TApi>({
+        planExecutor({ request, ...rest }) {
+            return executeRpcPubSubSubscriptionPlan({
+                ...rest,
+                responseTransformer,
+                subscribeRequest: { ...request, methodName: request.methodName.replace(/Notifications$/, 'Subscribe') },
+                unsubscribeMethodName: request.methodName.replace(/Notifications$/, 'Unsubscribe'),
+            });
+        },
+        requestTransformer,
+    });
+}
+
+export function createSolanaRpcSubscriptionsApi<TApi extends RpcSubscriptionsApiMethods = SolanaRpcSubscriptionsApi>(
+    config?: Config,
+): RpcSubscriptionsApi<TApi> {
+    return createSolanaRpcSubscriptionsApi_INTERNAL<TApi>(config);
+}
+
+export function createSolanaRpcSubscriptionsApi_UNSTABLE(config?: Config) {
+    return createSolanaRpcSubscriptionsApi_INTERNAL<SolanaRpcSubscriptionsApi & SolanaRpcSubscriptionsApiUnstable>(
+        config,
+    );
+}
+
+let memoizedKeypaths: AllowedNumericKeypaths<
+    RpcSubscriptionsApi<SolanaRpcSubscriptionsApi & SolanaRpcSubscriptionsApiUnstable>
+>;
+
+/**
+ * These are keypaths at the end of which you will find a numeric value that should *not* be upcast
+ * to a `bigint`. These are values that are legitimately defined as `u8` or `usize` on the backend.
+ */
+function getAllowedNumericKeypaths(): AllowedNumericKeypaths<
+    RpcSubscriptionsApi<SolanaRpcSubscriptionsApi & SolanaRpcSubscriptionsApiUnstable>
+> {
+    if (!memoizedKeypaths) {
+        memoizedKeypaths = {
+            accountNotifications: jsonParsedAccountsConfigs.map(c => ['value', ...c]),
+            blockNotifications: [
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'preTokenBalances',
+                    KEYPATH_WILDCARD,
+                    'accountIndex',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'preTokenBalances',
+                    KEYPATH_WILDCARD,
+                    'uiTokenAmount',
+                    'decimals',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'postTokenBalances',
+                    KEYPATH_WILDCARD,
+                    'accountIndex',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'postTokenBalances',
+                    KEYPATH_WILDCARD,
+                    'uiTokenAmount',
+                    'decimals',
+                ],
+                ['value', 'block', 'transactions', KEYPATH_WILDCARD, 'meta', 'rewards', KEYPATH_WILDCARD, 'commission'],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'innerInstructions',
+                    KEYPATH_WILDCARD,
+                    'index',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'innerInstructions',
+                    KEYPATH_WILDCARD,
+                    'instructions',
+                    KEYPATH_WILDCARD,
+                    'programIdIndex',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'innerInstructions',
+                    KEYPATH_WILDCARD,
+                    'instructions',
+                    KEYPATH_WILDCARD,
+                    'accounts',
+                    KEYPATH_WILDCARD,
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'transaction',
+                    'message',
+                    'addressTableLookups',
+                    KEYPATH_WILDCARD,
+                    'writableIndexes',
+                    KEYPATH_WILDCARD,
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'transaction',
+                    'message',
+                    'addressTableLookups',
+                    KEYPATH_WILDCARD,
+                    'readonlyIndexes',
+                    KEYPATH_WILDCARD,
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'transaction',
+                    'message',
+                    'instructions',
+                    KEYPATH_WILDCARD,
+                    'programIdIndex',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'transaction',
+                    'message',
+                    'instructions',
+                    KEYPATH_WILDCARD,
+                    'accounts',
+                    KEYPATH_WILDCARD,
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'transaction',
+                    'message',
+                    'header',
+                    'numReadonlySignedAccounts',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'transaction',
+                    'message',
+                    'header',
+                    'numReadonlyUnsignedAccounts',
+                ],
+                [
+                    'value',
+                    'block',
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'transaction',
+                    'message',
+                    'header',
+                    'numRequiredSignatures',
+                ],
+                ['value', 'block', 'rewards', KEYPATH_WILDCARD, 'commission'],
+            ],
+            programNotifications: jsonParsedAccountsConfigs.flatMap(c => [
+                ['value', KEYPATH_WILDCARD, 'account', ...c],
+                [KEYPATH_WILDCARD, 'account', ...c],
+            ]),
+        };
+    }
+    return memoizedKeypaths;
+}

package/src/logs-notifications.ts

@@ -0,0 +1,62 @@
+import type { Address } from '@solana/addresses';
+import type { Signature } from '@solana/keys';
+import type { Commitment, SolanaRpcResponse, TransactionError } from '@solana/rpc-types';
+
+type LogsNotificationsApiNotification = SolanaRpcResponse<
+    Readonly<{
+        /** Error if transaction failed, null if transaction succeeded. */
+        err: TransactionError | null;
+        /** Array of log messages the transaction instructions output during execution. */
+        logs: readonly string[];
+        /** Transaction signature as base-58 encoded string */
+        signature: Signature;
+    }>
+>;
+
+type LogsNotificationsApiConfig = Readonly<{
+    /**
+     * Get notified on logs from new transactions that have reached this level of commitment.
+     *
+     * @defaultValue Whichever default is applied by the underlying {@link RpcSubscriptionsApi} in
+     * use. For example, when using an API created by a `createSolanaRpcSubscriptions*()` helper,
+     * the default commitment is `"confirmed"` unless configured otherwise. Unmitigated by an API
+     * layer on the client, the default commitment applied by the server is `"finalized"`.
+     */
+    commitment?: Commitment;
+}>;
+
+export type LogsNotificationsApi = {
+    /**
+     * Subscribe to receive notifications containing the logs of all non-vote transactions.
+     *
+     * {@label non-vote}
+     * @see https://solana.com/docs/rpc/websocket/logssubscribe
+     */
+    logsNotifications(filter: 'all', config?: LogsNotificationsApiConfig): LogsNotificationsApiNotification;
+    /**
+     * Subscribe to receive notifications containing the logs of all transactions.
+     *
+     * {@label all}
+     * @see https://solana.com/docs/rpc/websocket/logssubscribe
+     */
+    logsNotifications(filter: 'allWithVotes', config?: LogsNotificationsApiConfig): LogsNotificationsApiNotification;
+    /**
+     * Subscribe to receive notifications containing the logs of transactions that mention the
+     * supplied program or account.
+
+    * {@label all-that-mention}
+     * @see https://solana.com/docs/rpc/websocket/logssubscribe
+     */
+    logsNotifications(
+        filter: {
+            /**
+             * This filter matches when a transaction mentions the single address provided.
+             *
+             * This filter currently only supports one address per method call. Listing additional
+             * addresses will result in an error.
+             */
+            mentions: [Address];
+        },
+        config?: LogsNotificationsApiConfig,
+    ): LogsNotificationsApiNotification;
+};

package/src/program-notifications.ts

@@ -0,0 +1,145 @@
+import type { Address } from '@solana/addresses';
+import type {
+    AccountInfoBase,
+    AccountInfoWithBase58Bytes,
+    AccountInfoWithBase58EncodedData,
+    AccountInfoWithBase64EncodedData,
+    AccountInfoWithBase64EncodedZStdCompressedData,
+    AccountInfoWithJsonData,
+    AccountInfoWithPubkey,
+    Commitment,
+    GetProgramAccountsDatasizeFilter,
+    GetProgramAccountsMemcmpFilter,
+    SolanaRpcResponse,
+} from '@solana/rpc-types';
+
+type ProgramNotificationsApiNotificationBase<TData> = SolanaRpcResponse<AccountInfoWithPubkey<AccountInfoBase & TData>>;
+
+type ProgramNotificationsApiCommonConfig = Readonly<{
+    /**
+     * Get notified when a modification to an account has reached this level of commitment.
+     *
+     * @defaultValue Whichever default is applied by the underlying {@link RpcSubscriptionsApi} in
+     * use. For example, when using an API created by a `createSolanaRpcSubscriptions*()` helper,
+     * the default commitment is `"confirmed"` unless configured otherwise. Unmitigated by an API
+     * layer on the client, the default commitment applied by the server is `"finalized"`.
+     */
+    commitment?: Commitment;
+    /**
+     * Limits results to those that match all of these filters.
+     *
+     * This is useful when your aim is to find program accounts whose purpose is uniquely determined
+     * by having a data buffer of a known size, or whose data contains a known series of bytes (eg.
+     * a discriminator).
+     *
+     * You can specify up to 4 filters.
+     *
+     * @defaultValue When omitted, no filters are applied.
+     */
+    filters?: readonly Readonly<GetProgramAccountsDatasizeFilter | GetProgramAccountsMemcmpFilter>[];
+}>;
+
+export type ProgramNotificationsApi = {
+    /**
+     * Subscribe for notifications when there is a change in the {@link Lamports} or data of any
+     * account owned by the program at the given address changes.
+     *
+     * The notification format is the same as seen in the
+     * {@link GetProgramAccountsApi.getProgramAccounts} RPC HTTP method.
+     *
+     * If the account has data, it will be returned in the response as a tuple whose first element
+     * is a base64-encoded string.
+     *
+     * {@label base64}
+     * @see https://solana.com/docs/rpc/websocket/programsubscribe
+     */
+    programNotifications(
+        programId: Address,
+        config: ProgramNotificationsApiCommonConfig &
+            Readonly<{
+                encoding: 'base64';
+            }>,
+    ): ProgramNotificationsApiNotificationBase<AccountInfoWithBase64EncodedData>;
+    /**
+     * Subscribe for notifications when there is a change in the {@link Lamports} or data of any
+     * account owned by the program at the given address changes.
+     *
+     * The notification format is the same as seen in the
+     * {@link GetProgramAccountsApi.getProgramAccounts} RPC HTTP method.
+     *
+     * If the account has data, it will first be compressed using
+     * [ZStandard](https://facebook.github.io/zstd/) and the result will be returned in the response
+     * as a tuple whose first element is a base64-encoded string.
+     *
+     * {@label base64-zstd-compressed}
+     * @see https://solana.com/docs/rpc/websocket/programsubscribe
+     */
+    programNotifications(
+        programId: Address,
+        config: ProgramNotificationsApiCommonConfig &
+            Readonly<{
+                encoding: 'base64+zstd';
+            }>,
+    ): ProgramNotificationsApiNotificationBase<AccountInfoWithBase64EncodedZStdCompressedData>;
+    /**
+     * Subscribe for notifications when there is a change in the {@link Lamports} or data of any
+     * account owned by the program at the given address changes.
+     *
+     * The notification format is the same as seen in the
+     * {@link GetProgramAccountsApi.getProgramAccounts} RPC HTTP method.
+     *
+     * If the account has data, the server will attempt to process it using a parser specific to the
+     * account's owning program. If successful, the parsed data will be returned in the response as
+     * JSON. Otherwise, the raw account data will be returned in the response as a tuple whose first
+     * element is a base64-encoded string.
+     *
+     * {@label parsed}
+     * @see https://solana.com/docs/rpc/websocket/programsubscribe
+     */
+    programNotifications(
+        programId: Address,
+        config: ProgramNotificationsApiCommonConfig &
+            Readonly<{
+                encoding: 'jsonParsed';
+            }>,
+    ): ProgramNotificationsApiNotificationBase<AccountInfoWithJsonData>;
+    /**
+     * Subscribe for notifications when there is a change in the {@link Lamports} or data of any
+     * account owned by the program at the given address changes.
+     *
+     * The notification format is the same as seen in the
+     * {@link GetProgramAccountsApi.getProgramAccounts} RPC HTTP method.
+     *
+     * If the account has data, it will be returned in the response as a tuple whose first element
+     * is a base58-encoded string. If the account contains more than 129 bytes of data, the `data`
+     * field will materialize as the string `"error: data too large for bs58 encoding"`.
+     *
+     * {@label base58}
+     * @see https://solana.com/docs/rpc/websocket/programsubscribe
+     */
+    programNotifications(
+        programId: Address,
+        config: ProgramNotificationsApiCommonConfig &
+            Readonly<{
+                encoding: 'base58';
+            }>,
+    ): ProgramNotificationsApiNotificationBase<AccountInfoWithBase58EncodedData>;
+    /**
+     * Subscribe for notifications when there is a change in the {@link Lamports} or data of any
+     * account owned by the program at the given address changes.
+     *
+     * The notification format is the same as seen in the
+     * {@link GetProgramAccountsApi.getProgramAccounts} RPC HTTP method.
+     *
+     * If the account has data, it will be returned in the response as a base58-encoded string. If
+     * the account contains more than 129 bytes of data, the `data` field will materialize as the
+     * string `"error: data too large for bs58 encoding"`.
+     *
+     * {@label base58-legacy}
+     * @see https://solana.com/docs/rpc/websocket/programsubscribe
+     */
+    programNotifications(
+        programId: Address,
+        config?: ProgramNotificationsApiCommonConfig,
+    ): ProgramNotificationsApiNotificationBase<AccountInfoWithBase58Bytes>;
+};

package/src/root-notifications.ts

@@ -0,0 +1,13 @@
+import type { Slot } from '@solana/rpc-types';
+
+type RootNotificationsApiNotification = Slot;
+
+export type RootNotificationsApi = {
+    /**
+     * Subscribe to receive notifications anytime a new root is set by the validator.
+     *
+     * @returns The number of the rooted slot
+     * @see https://solana.com/docs/rpc/websocket/rootsubscribe
+     */
+    rootNotifications(): RootNotificationsApiNotification;
+};

package/src/signature-notifications.ts

@@ -0,0 +1,74 @@
+import type { Signature } from '@solana/keys';
+import type { Commitment, SolanaRpcResponse, TransactionError } from '@solana/rpc-types';
+
+type SignatureNotificationsApiNotificationReceived = SolanaRpcResponse<Readonly<'receivedSignature'>>;
+
+type SignatureNotificationsApiNotificationProcessed = SolanaRpcResponse<
+    Readonly<{
+        /** Error if transaction failed, null if transaction succeeded. */
+        err: TransactionError | null;
+    }>
+>;
+
+type SignatureNotificationsApiConfigBase = Readonly<{
+    /**
+     * Get notified when the transaction with the specified signature has reached this level of
+     * commitment.
+     *
+     * @defaultValue Whichever default is applied by the underlying {@link RpcSubscriptionsApi} in
+     * use. For example, when using an API created by a `createSolanaRpcSubscriptions*()` helper,
+     * the default commitment is `"confirmed"` unless configured otherwise. Unmitigated by an API
+     * layer on the client, the default commitment applied by the server is `"finalized"`.
+     */
+    commitment?: Commitment;
+    /**
+     * Whether or not to subscribe for notifications when signatures are received by the RPC, in
+     * addition to when they are processed.
+     *
+     * @defaultValue false
+     */
+    enableReceivedNotification?: boolean;
+}>;
+
+export type SignatureNotificationsApi = {
+    /**
+     * Subscribe to a receive a notification when the transaction identified by the given signature
+     * is received by the cluster, then again when it reaches the specified level of commitment.
+     *
+     * This subscription will not issue notifications for events that have already happened. To
+     * fetch the commitment status of any transaction at a point in time use the
+     * {@link GetSignatureStatusesApi.getSignatureStatuses | getSignatureStatuses} method of the RPC
+     * API.
+     *
+     * @param signature Transaction signature as base-58 encoded string
+     *
+     * @see https://solana.com/docs/rpc/websocket/signaturesubscribe
+     */
+    signatureNotifications(
+        signature: Signature,
+        config: Readonly<{
+            enableReceivedNotification: true;
+        }> &
+            SignatureNotificationsApiConfigBase,
+    ): SignatureNotificationsApiNotificationProcessed | SignatureNotificationsApiNotificationReceived;
+    /**
+     * Subscribe to a receive a notification when the transaction identified by the given signature
+     * reaches the specified level of commitment.
+     *
+     * This subscription will not issue notifications for events that have already happened. To
+     * fetch the commitment status of any transaction at a point in time use the
+     * {@link GetSignatureStatusesApi.getSignatureStatuses | getSignatureStatuses} method of the RPC
+     * API.
+     *
+     * @param signature Transaction signature as base-58 encoded string
+     *
+     * @see https://solana.com/docs/rpc/websocket/signaturesubscribe
+     */
+    signatureNotifications(
+        signature: Signature,
+        config?: Readonly<{
+            enableReceivedNotification?: false;
+        }> &
+            SignatureNotificationsApiConfigBase,
+    ): SignatureNotificationsApiNotificationProcessed;
+};

package/src/slot-notifications.ts

@@ -0,0 +1,19 @@
+import type { Slot } from '@solana/rpc-types';
+
+type SlotNotificationsApiNotification = Readonly<{
+    /** The parent slot */
+    parent: Slot;
+    /** The current root slot */
+    root: Slot;
+    /** The newly set slot value */
+    slot: Slot;
+}>;
+
+export type SlotNotificationsApi = {
+    /**
+     * Subscribe to receive notifications anytime a slot is processed by the validator.
+     *
+     * @see https://solana.com/docs/rpc/websocket/slotsubscribe
+     */
+    slotNotifications(): SlotNotificationsApiNotification;
+};

package/src/slots-updates-notifications.ts

@@ -0,0 +1,51 @@
+import type { Slot } from '@solana/rpc-types';
+
+type SlotsUpdatesNotificationsApiNotificationBase = Readonly<{
+    /** The newly updated slot */
+    slot: Slot;
+    /** The Unix timestamp of the update in milliseconds */
+    timestamp: bigint;
+    type: 'completed' | 'firstShredReceived' | 'optimisticConfirmation' | 'root';
+}>;
+
+type SlotsUpdatesNotificationsApiNotificationCreatedBank = Readonly<{
+    /** The parent slot */
+    parent: Slot;
+    type: 'createdBank';
+}> &
+    SlotsUpdatesNotificationsApiNotificationBase;
+
+type SlotsUpdatesNotificationsApiNotificationDead = Readonly<{
+    err: string;
+    type: 'dead';
+}> &
+    SlotsUpdatesNotificationsApiNotificationBase;
+
+type SlotsUpdatesNotificationsApiNotificationFrozen = Readonly<{
+    stats: Readonly<{
+        maxTransactionsPerEntry: bigint;
+        numFailedTransactions: bigint;
+        numSuccessfulTransactions: bigint;
+        numTransactionEntries: bigint;
+    }>;
+    type: 'frozen';
+}> &
+    SlotsUpdatesNotificationsApiNotificationBase;
+
+type SlotsUpdatesNotificationsApiNotification =
+    | SlotsUpdatesNotificationsApiNotificationBase
+    | SlotsUpdatesNotificationsApiNotificationCreatedBank
+    | SlotsUpdatesNotificationsApiNotificationDead
+    | SlotsUpdatesNotificationsApiNotificationFrozen;
+
+export type SlotsUpdatesNotificationsApi = {
+    /**
+     * Subscribe to receive a notification from the validator on a variety of updates on every slot.
+     *
+     * This subscription is unstable. The format of this subscription may change in the future, and
+     * may not be supported by every node.
+     *
+     * @see https://solana.com/docs/rpc/websocket/slotsupdatessubscribe
+     */
+    slotsUpdatesNotifications(): SlotsUpdatesNotificationsApiNotification;
+};

package/src/vote-notifications.ts

@@ -0,0 +1,32 @@
+import type { Address } from '@solana/addresses';
+import type { Signature } from '@solana/keys';
+import type { Blockhash, Slot, UnixTimestamp } from '@solana/rpc-types';
+
+type VoteNotificationsApiNotification = Readonly<{
+    /** The vote hash */
+    hash: Blockhash;
+    /** The signature of the transaction that contained this vote */
+    signature: Signature;
+    /** The slots covered by the vote */
+    slots: readonly Slot[];
+    /** The timestamp of the vote */
+    timestamp: UnixTimestamp | null;
+    /** The address of the vote account */
+    votePubkey: Address;
+}>;
+
+export type VoteNotificationsApi = {
+    /**
+     * Subscribe to receive notifications anytime a new vote is observed in gossip.
+     *
+     * These votes are pre-consensus therefore there is no guarantee these votes will enter the
+     * ledger.
+     *
+     * This subscription is unstable and only available if the validator was started with the
+     * `--rpc-pubsub-enable-vote-subscription` flag. The format of this subscription may change in
+     * the future.
+     *
+     * @see https://solana.com/docs/rpc/websocket/votesubscribe
+     */
+    voteNotifications(): VoteNotificationsApiNotification;
+};