@solana/kit 6.3.1 → 6.3.2-canary-20260313112147

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * This is the JavaScript SDK for building Solana apps for Node, web, and React Native.
+ *
+ * In addition to re-exporting functions from packages in the `@solana/*` namespace, this package
+ * offers additional helpers for building Solana applications, with sensible defaults.
+ *
+ * @packageDocumentation
+ */
+export * from '@solana/accounts';
+export * from '@solana/addresses';
+export * from '@solana/codecs';
+export * from '@solana/errors';
+export * from '@solana/functional';
+export * from '@solana/instructions';
+export * from '@solana/instruction-plans';
+export * from '@solana/keys';
+export * from '@solana/offchain-messages';
+export * from '@solana/plugin-core';
+export type * from '@solana/plugin-interfaces';
+export * from '@solana/programs';
+export * from '@solana/rpc';
+export * from '@solana/rpc-parsed-types';
+export * from '@solana/rpc-subscriptions';
+export * from '@solana/rpc-types';
+export * from '@solana/signers';
+export * from '@solana/transaction-messages';
+export * from '@solana/transactions';
+export * from './airdrop';
+export * from './decompile-transaction-message-fetching-lookup-tables';
+export * from './fetch-lookup-tables';
+export * from './get-minimum-balance-for-rent-exemption';
+export * from './send-and-confirm-durable-nonce-transaction';
+export * from './send-and-confirm-transaction';
+export * from './send-transaction-without-confirming';
+
+export type {
+    RpcRequest,
+    RpcRequestTransformer,
+    RpcResponse,
+    RpcResponseData,
+    RpcResponseTransformer,
+} from '@solana/rpc-spec-types';
+export { createRpcMessage } from '@solana/rpc-spec-types';

package/src/program-client-core.ts

@@ -0,0 +1 @@
+export * from '@solana/program-client-core';

package/src/send-and-confirm-durable-nonce-transaction.ts

@@ -0,0 +1,172 @@
+import { getSolanaErrorFromTransactionError, isSolanaError, SOLANA_ERROR__INVALID_NONCE } from '@solana/errors';
+import { Signature } from '@solana/keys';
+import type { GetAccountInfoApi, GetSignatureStatusesApi, Rpc, SendTransactionApi } from '@solana/rpc';
+import type { AccountNotificationsApi, RpcSubscriptions, SignatureNotificationsApi } from '@solana/rpc-subscriptions';
+import { commitmentComparator } from '@solana/rpc-types';
+import {
+    createNonceInvalidationPromiseFactory,
+    createRecentSignatureConfirmationPromiseFactory,
+    waitForDurableNonceTransactionConfirmation,
+} from '@solana/transaction-confirmation';
+import {
+    getSignatureFromTransaction,
+    SendableTransaction,
+    Transaction,
+    TransactionWithDurableNonceLifetime,
+} from '@solana/transactions';
+
+import { sendAndConfirmDurableNonceTransaction_INTERNAL_ONLY_DO_NOT_EXPORT } from './send-transaction-internal';
+
+type SendAndConfirmDurableNonceTransactionFunction = (
+    transaction: SendableTransaction & Transaction & TransactionWithDurableNonceLifetime,
+    config: Omit<
+        Parameters<typeof sendAndConfirmDurableNonceTransaction_INTERNAL_ONLY_DO_NOT_EXPORT>[0],
+        'confirmDurableNonceTransaction' | 'rpc' | 'transaction'
+    >,
+) => Promise<void>;
+
+type SendAndConfirmDurableNonceTransactionFactoryConfig<TCluster> = {
+    /** An object that supports the {@link GetSignatureStatusesApi} and the {@link SendTransactionApi} of the Solana RPC API */
+    rpc: Rpc<GetAccountInfoApi & GetSignatureStatusesApi & SendTransactionApi> & { '~cluster'?: TCluster };
+    /** An object that supports the {@link AccountNotificationsApi} and the {@link SignatureNotificationsApi} of the Solana RPC Subscriptions API */
+    rpcSubscriptions: RpcSubscriptions<AccountNotificationsApi & SignatureNotificationsApi> & { '~cluster'?: TCluster };
+};
+
+/**
+ * Returns a function that you can call to send a nonce-based transaction to the network and to wait
+ * until it has been confirmed.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import {
+ *     isSolanaError,
+ *     sendAndConfirmDurableNonceTransactionFactory,
+ *     SOLANA_ERROR__INVALID_NONCE,
+ *     SOLANA_ERROR__NONCE_ACCOUNT_NOT_FOUND,
+ * } from '@solana/kit';
+ *
+ * const sendAndConfirmNonceTransaction = sendAndConfirmDurableNonceTransactionFactory({ rpc, rpcSubscriptions });
+ *
+ * try {
+ *     await sendAndConfirmNonceTransaction(transaction, { commitment: 'confirmed' });
+ * } catch (e) {
+ *     if (isSolanaError(e, SOLANA_ERROR__NONCE_ACCOUNT_NOT_FOUND)) {
+ *         console.error(
+ *             'The lifetime specified by this transaction refers to a nonce account ' +
+ *                 `\`${e.context.nonceAccountAddress}\` that does not exist`,
+ *         );
+ *     } else if (isSolanaError(e, SOLANA_ERROR__INVALID_NONCE)) {
+ *         console.error('This transaction depends on a nonce that is no longer valid');
+ *     } else {
+ *         throw e;
+ *     }
+ * }
+ * ```
+ */
+export function sendAndConfirmDurableNonceTransactionFactory({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmDurableNonceTransactionFactoryConfig<'devnet'>): SendAndConfirmDurableNonceTransactionFunction;
+export function sendAndConfirmDurableNonceTransactionFactory({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmDurableNonceTransactionFactoryConfig<'testnet'>): SendAndConfirmDurableNonceTransactionFunction;
+export function sendAndConfirmDurableNonceTransactionFactory({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmDurableNonceTransactionFactoryConfig<'mainnet'>): SendAndConfirmDurableNonceTransactionFunction;
+export function sendAndConfirmDurableNonceTransactionFactory<
+    TCluster extends 'devnet' | 'mainnet' | 'testnet' | void = void,
+>({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmDurableNonceTransactionFactoryConfig<TCluster>): SendAndConfirmDurableNonceTransactionFunction {
+    const getNonceInvalidationPromise = createNonceInvalidationPromiseFactory({ rpc, rpcSubscriptions } as Parameters<
+        typeof createNonceInvalidationPromiseFactory
+    >[0]);
+    const getRecentSignatureConfirmationPromise = createRecentSignatureConfirmationPromiseFactory({
+        rpc,
+        rpcSubscriptions,
+    } as Parameters<typeof createRecentSignatureConfirmationPromiseFactory>[0]);
+
+    /**
+     * Creates a wrapped version of getNonceInvalidationPromise that handles the race condition
+     * where the nonce account update notification arrives before the signature confirmation.
+     *
+     * When the nonce changes, we check if our transaction actually landed on-chain.
+     * If it did, we don't throw - letting the signature confirmation promise continue.
+     */
+    function createNonceInvalidationPromiseHandlingRaceCondition(
+        signature: Signature,
+    ): typeof getNonceInvalidationPromise {
+        return async function wrappedGetNonceInvalidationPromise(config) {
+            try {
+                return await getNonceInvalidationPromise(config);
+            } catch (e) {
+                // If nonce became invalid, check if our transaction actually landed
+                if (isSolanaError(e, SOLANA_ERROR__INVALID_NONCE)) {
+                    let status;
+                    try {
+                        const { value: statuses } = await rpc
+                            .getSignatureStatuses([signature])
+                            .send({ abortSignal: config.abortSignal });
+                        status = statuses[0];
+                    } catch {
+                        // RPC failed - propagate the original nonce error
+                        throw e;
+                    }
+
+                    if (status === null || status === undefined) {
+                        // Transaction doesn't exist - nonce was truly invalid
+                        throw e;
+                    }
+
+                    // Check if status meets required commitment
+                    if (
+                        status.confirmationStatus !== null &&
+                        commitmentComparator(status.confirmationStatus, config.commitment) >= 0
+                    ) {
+                        // Transaction failed on-chain, throw the error from the transaction
+                        if (status.err !== null) {
+                            throw getSolanaErrorFromTransactionError(status.err);
+                        }
+                        // Transaction succeeded, resolve the promise successfully
+                        return;
+                    }
+
+                    // Commitment not met yet - return a never-resolving promise
+                    // This lets the signature confirmation promise continue
+                    return await new Promise(() => {});
+                }
+                throw e;
+            }
+        };
+    }
+
+    async function confirmDurableNonceTransaction(
+        config: Omit<
+            Parameters<typeof waitForDurableNonceTransactionConfirmation>[0],
+            'getNonceInvalidationPromise' | 'getRecentSignatureConfirmationPromise'
+        >,
+    ) {
+        const wrappedGetNonceInvalidationPromise = createNonceInvalidationPromiseHandlingRaceCondition(
+            getSignatureFromTransaction(config.transaction),
+        );
+
+        await waitForDurableNonceTransactionConfirmation({
+            ...config,
+            getNonceInvalidationPromise: wrappedGetNonceInvalidationPromise,
+            getRecentSignatureConfirmationPromise,
+        });
+    }
+    return async function sendAndConfirmDurableNonceTransaction(transaction, config) {
+        await sendAndConfirmDurableNonceTransaction_INTERNAL_ONLY_DO_NOT_EXPORT({
+            ...config,
+            confirmDurableNonceTransaction,
+            rpc,
+            transaction,
+        });
+    };
+}

package/src/send-and-confirm-transaction.ts

@@ -0,0 +1,95 @@
+import type { GetEpochInfoApi, GetSignatureStatusesApi, Rpc, SendTransactionApi } from '@solana/rpc';
+import type { RpcSubscriptions, SignatureNotificationsApi, SlotNotificationsApi } from '@solana/rpc-subscriptions';
+import {
+    createBlockHeightExceedencePromiseFactory,
+    createRecentSignatureConfirmationPromiseFactory,
+    TransactionWithLastValidBlockHeight,
+    waitForRecentTransactionConfirmation,
+} from '@solana/transaction-confirmation';
+import { SendableTransaction, Transaction } from '@solana/transactions';
+
+import { sendAndConfirmTransactionWithBlockhashLifetime_INTERNAL_ONLY_DO_NOT_EXPORT } from './send-transaction-internal';
+
+type SendAndConfirmTransactionWithBlockhashLifetimeFunction = (
+    transaction: SendableTransaction & Transaction & TransactionWithLastValidBlockHeight,
+    config: Omit<
+        Parameters<typeof sendAndConfirmTransactionWithBlockhashLifetime_INTERNAL_ONLY_DO_NOT_EXPORT>[0],
+        'confirmRecentTransaction' | 'rpc' | 'transaction'
+    >,
+) => Promise<void>;
+
+type SendAndConfirmTransactionWithBlockhashLifetimeFactoryConfig<TCluster> = {
+    /** An object that supports the {@link GetSignatureStatusesApi} and the {@link SendTransactionApi} of the Solana RPC API */
+    rpc: Rpc<GetEpochInfoApi & GetSignatureStatusesApi & SendTransactionApi> & { '~cluster'?: TCluster };
+    /** An object that supports the {@link SignatureNotificationsApi} and the {@link SlotNotificationsApi} of the Solana RPC Subscriptions API */
+    rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi & SlotNotificationsApi> & { '~cluster'?: TCluster };
+};
+
+/**
+ * Returns a function that you can call to send a blockhash-based transaction to the network and to
+ * wait until it has been confirmed.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import { isSolanaError, sendAndConfirmTransactionFactory, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED } from '@solana/kit';
+ *
+ * const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
+ *
+ * try {
+ *     await sendAndConfirmTransaction(transaction, { commitment: 'confirmed' });
+ * } catch (e) {
+ *     if (isSolanaError(e, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED)) {
+ *         console.error('This transaction depends on a blockhash that has expired');
+ *     } else {
+ *         throw e;
+ *     }
+ * }
+ * ```
+ */
+export function sendAndConfirmTransactionFactory({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmTransactionWithBlockhashLifetimeFactoryConfig<'devnet'>): SendAndConfirmTransactionWithBlockhashLifetimeFunction;
+export function sendAndConfirmTransactionFactory({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmTransactionWithBlockhashLifetimeFactoryConfig<'testnet'>): SendAndConfirmTransactionWithBlockhashLifetimeFunction;
+export function sendAndConfirmTransactionFactory({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmTransactionWithBlockhashLifetimeFactoryConfig<'mainnet'>): SendAndConfirmTransactionWithBlockhashLifetimeFunction;
+export function sendAndConfirmTransactionFactory<TCluster extends 'devnet' | 'mainnet' | 'testnet' | void = void>({
+    rpc,
+    rpcSubscriptions,
+}: SendAndConfirmTransactionWithBlockhashLifetimeFactoryConfig<TCluster>): SendAndConfirmTransactionWithBlockhashLifetimeFunction {
+    const getBlockHeightExceedencePromise = createBlockHeightExceedencePromiseFactory({
+        rpc,
+        rpcSubscriptions,
+    } as Parameters<typeof createBlockHeightExceedencePromiseFactory>[0]);
+    const getRecentSignatureConfirmationPromise = createRecentSignatureConfirmationPromiseFactory({
+        rpc,
+        rpcSubscriptions,
+    } as Parameters<typeof createRecentSignatureConfirmationPromiseFactory>[0]);
+    async function confirmRecentTransaction(
+        config: Omit<
+            Parameters<typeof waitForRecentTransactionConfirmation>[0],
+            'getBlockHeightExceedencePromise' | 'getRecentSignatureConfirmationPromise'
+        >,
+    ) {
+        await waitForRecentTransactionConfirmation({
+            ...config,
+            getBlockHeightExceedencePromise,
+            getRecentSignatureConfirmationPromise,
+        });
+    }
+    return async function sendAndConfirmTransaction(transaction, config) {
+        await sendAndConfirmTransactionWithBlockhashLifetime_INTERNAL_ONLY_DO_NOT_EXPORT({
+            ...config,
+            confirmRecentTransaction,
+            rpc,
+            transaction,
+        });
+    };
+}

package/src/send-transaction-internal.ts

@@ -0,0 +1,134 @@
+import type { Signature } from '@solana/keys';
+import type { Rpc, SendTransactionApi } from '@solana/rpc';
+import { Commitment, commitmentComparator } from '@solana/rpc-types';
+import {
+    TransactionWithLastValidBlockHeight,
+    waitForDurableNonceTransactionConfirmation,
+    waitForRecentTransactionConfirmation,
+} from '@solana/transaction-confirmation';
+import {
+    getBase64EncodedWireTransaction,
+    SendableTransaction,
+    Transaction,
+    TransactionWithDurableNonceLifetime,
+} from '@solana/transactions';
+
+interface SendAndConfirmDurableNonceTransactionConfig
+    extends SendTransactionBaseConfig, SendTransactionConfigWithoutEncoding {
+    confirmDurableNonceTransaction: (
+        config: Omit<
+            Parameters<typeof waitForDurableNonceTransactionConfirmation>[0],
+            'getNonceInvalidationPromise' | 'getRecentSignatureConfirmationPromise'
+        >,
+    ) => Promise<void>;
+    transaction: SendableTransaction & Transaction & TransactionWithDurableNonceLifetime;
+}
+
+interface SendAndConfirmTransactionWithBlockhashLifetimeConfig
+    extends SendTransactionBaseConfig, SendTransactionConfigWithoutEncoding {
+    confirmRecentTransaction: (
+        config: Omit<
+            Parameters<typeof waitForRecentTransactionConfirmation>[0],
+            'getBlockHeightExceedencePromise' | 'getRecentSignatureConfirmationPromise'
+        >,
+    ) => Promise<void>;
+    transaction: SendableTransaction & Transaction & TransactionWithLastValidBlockHeight;
+}
+
+interface SendTransactionBaseConfig extends SendTransactionConfigWithoutEncoding {
+    abortSignal?: AbortSignal;
+    commitment: Commitment;
+    rpc: Rpc<SendTransactionApi>;
+    transaction: SendableTransaction & Transaction;
+}
+
+type SendTransactionConfigWithoutEncoding = Omit<
+    NonNullable<Parameters<SendTransactionApi['sendTransaction']>[1]>,
+    'encoding'
+>;
+
+function getSendTransactionConfigWithAdjustedPreflightCommitment(
+    commitment: Commitment,
+    config?: SendTransactionConfigWithoutEncoding,
+): SendTransactionConfigWithoutEncoding | void {
+    if (
+        // The developer has supplied no value for `preflightCommitment`.
+        !config?.preflightCommitment &&
+        // The value of `commitment` is lower than the server default of `preflightCommitment`.
+        commitmentComparator(commitment, 'finalized' /* default value of `preflightCommitment` */) < 0
+    ) {
+        return {
+            ...config,
+            // In the common case, it is unlikely that you want to simulate a transaction at
+            // `finalized` commitment when your standard of commitment for confirming the
+            // transaction is lower. Cap the simulation commitment level to the level of the
+            // confirmation commitment.
+            preflightCommitment: commitment,
+        };
+    }
+    // The commitment at which the developer wishes to confirm the transaction is at least as
+    // high as the commitment at which they want to simulate it. Honour the config as-is.
+    return config;
+}
+
+export async function sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT({
+    abortSignal,
+    commitment,
+    rpc,
+    transaction,
+    ...sendTransactionConfig
+}: SendTransactionBaseConfig): Promise<Signature> {
+    const base64EncodedWireTransaction = getBase64EncodedWireTransaction(transaction);
+    return await rpc
+        .sendTransaction(base64EncodedWireTransaction, {
+            ...getSendTransactionConfigWithAdjustedPreflightCommitment(commitment, sendTransactionConfig),
+            encoding: 'base64',
+        })
+        .send({ abortSignal });
+}
+
+export async function sendAndConfirmDurableNonceTransaction_INTERNAL_ONLY_DO_NOT_EXPORT({
+    abortSignal,
+    commitment,
+    confirmDurableNonceTransaction,
+    rpc,
+    transaction,
+    ...sendTransactionConfig
+}: SendAndConfirmDurableNonceTransactionConfig): Promise<Signature> {
+    const transactionSignature = await sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT({
+        ...sendTransactionConfig,
+        abortSignal,
+        commitment,
+        rpc,
+        transaction,
+    });
+    await confirmDurableNonceTransaction({
+        abortSignal,
+        commitment,
+        transaction,
+    });
+    return transactionSignature;
+}
+
+export async function sendAndConfirmTransactionWithBlockhashLifetime_INTERNAL_ONLY_DO_NOT_EXPORT({
+    abortSignal,
+    commitment,
+    confirmRecentTransaction,
+    rpc,
+    transaction,
+    ...sendTransactionConfig
+}: SendAndConfirmTransactionWithBlockhashLifetimeConfig): Promise<Signature> {
+    const transactionSignature = await sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT({
+        ...sendTransactionConfig,
+        abortSignal,
+        commitment,
+        rpc,
+        transaction,
+    });
+    await confirmRecentTransaction({
+        abortSignal,
+        commitment,
+        transaction,
+    });
+    return transactionSignature;
+}

package/src/send-transaction-without-confirming.ts

@@ -0,0 +1,52 @@
+import type { Rpc, SendTransactionApi } from '@solana/rpc';
+import { SendableTransaction, Transaction } from '@solana/transactions';
+
+import { sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT } from './send-transaction-internal';
+
+type SendTransactionWithoutConfirmingFunction = (
+    transaction: SendableTransaction & Transaction,
+    config: Omit<Parameters<typeof sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT>[0], 'rpc' | 'transaction'>,
+) => Promise<void>;
+
+interface SendTransactionWithoutConfirmingFactoryConfig {
+    /** An object that supports the {@link SendTransactionApi} of the Solana RPC API */
+    rpc: Rpc<SendTransactionApi>;
+}
+
+/**
+ * Returns a function that you can call to send a transaction with any kind of lifetime to the
+ * network without waiting for it to be confirmed.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import {
+ *     sendTransactionWithoutConfirmingFactory,
+ *     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
+ * } from '@solana/kit';
+ *
+ * const sendTransaction = sendTransactionWithoutConfirmingFactory({ rpc });
+ *
+ * try {
+ *     await sendTransaction(transaction, { commitment: 'confirmed' });
+ * } catch (e) {
+ *     if (isSolanaError(e, SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE)) {
+ *         console.error('The transaction failed in simulation', e.cause);
+ *     } else {
+ *         throw e;
+ *     }
+ * }
+ * ```
+ */
+export function sendTransactionWithoutConfirmingFactory({
+    rpc,
+}: SendTransactionWithoutConfirmingFactoryConfig): SendTransactionWithoutConfirmingFunction {
+    return async function sendTransactionWithoutConfirming(transaction, config) {
+        await sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT({
+            ...config,
+            rpc,
+            transaction,
+        });
+    };
+}