@solana/errors 6.3.1 → 6.3.2-canary-20260313112147

package/src/rpc-enum-errors.ts

@@ -0,0 +1,53 @@
+import { SolanaErrorCode } from './codes';
+import { SolanaErrorContext } from './context';
+import { SolanaError } from './error';
+import { safeCaptureStackTrace } from './stack-trace';
+
+type Config = Readonly<{
+    /**
+     * Oh, hello. You might wonder what in tarnation is going on here. Allow us to explain.
+     *
+     * One of the goals of `@solana/errors` is to allow errors that are not interesting to your
+     * application to shake out of your app bundle in production. This means that we must never
+     * export large hardcoded maps of error codes/messages.
+     *
+     * Unfortunately, where instruction and transaction errors from the RPC are concerned, we have
+     * no choice but to keep a map between the RPC `rpcEnumError` enum name and its corresponding
+     * `SolanaError` code. In the interest of implementing that map in as few bytes of source code
+     * as possible, we do the following:
+     *
+     *   1. Reserve a block of sequential error codes for the enum in question
+     *   2. Hardcode the list of enum names in that same order
+     *   3. Match the enum error name from the RPC with its index in that list, and reconstruct the
+     *      `SolanaError` code by adding the `errorCodeBaseOffset` to that index
+     */
+    errorCodeBaseOffset: number;
+    getErrorContext: (
+        errorCode: SolanaErrorCode,
+        rpcErrorName: string,
+        rpcErrorContext?: unknown,
+    ) => SolanaErrorContext[SolanaErrorCode];
+    orderedErrorNames: string[];
+    rpcEnumError: string | { [key: string]: unknown };
+}>;
+
+export function getSolanaErrorFromRpcError(
+    { errorCodeBaseOffset, getErrorContext, orderedErrorNames, rpcEnumError }: Config,
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    constructorOpt: Function,
+): SolanaError {
+    let rpcErrorName;
+    let rpcErrorContext;
+    if (typeof rpcEnumError === 'string') {
+        rpcErrorName = rpcEnumError;
+    } else {
+        rpcErrorName = Object.keys(rpcEnumError)[0];
+        rpcErrorContext = rpcEnumError[rpcErrorName];
+    }
+    const codeOffset = orderedErrorNames.indexOf(rpcErrorName);
+    const errorCode = (errorCodeBaseOffset + codeOffset) as SolanaErrorCode;
+    const errorContext = getErrorContext(errorCode, rpcErrorName, rpcErrorContext);
+    const err = new SolanaError(errorCode, errorContext);
+    safeCaptureStackTrace(err, constructorOpt);
+    return err;
+}

package/src/simulation-errors.ts

@@ -0,0 +1,47 @@
+import {
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
+    SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT,
+    SolanaErrorCode,
+} from './codes';
+import { isSolanaError } from './error';
+
+/**
+ * Extracts the underlying cause from a simulation-related error.
+ *
+ * When a transaction simulation fails, the error is often wrapped in a
+ * simulation-specific {@link SolanaError}. This function unwraps such errors
+ * by returning the `cause` property, giving you access to the actual error
+ * that triggered the simulation failure.
+ *
+ * If the provided error is not a simulation-related error, it is returned unchanged.
+ *
+ * The following error codes are considered simulation errors:
+ * - {@link SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE}
+ * - {@link SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT}
+ *
+ * @param error - The error to unwrap.
+ * @return The underlying cause if the error is a simulation error, otherwise the original error.
+ *
+ * @example
+ * Unwrapping a preflight failure to access the root cause.
+ * ```ts
+ * import { unwrapSimulationError } from '@solana/errors';
+ *
+ * try {
+ *     await sendTransaction(signedTransaction);
+ * } catch (e) {
+ *     const cause = unwrapSimulationError(e);
+ *     console.log('Send transaction failed due to:', cause);
+ * }
+ * ```
+ */
+export function unwrapSimulationError(error: unknown): unknown {
+    const simulationCodes: SolanaErrorCode[] = [
+        SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
+        SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT,
+    ];
+    if (isSolanaError(error) && !!error.cause && simulationCodes.includes(error.context.__code)) {
+        return error.cause;
+    }
+    return error;
+}

package/src/stack-trace.ts

@@ -0,0 +1,5 @@
+export function safeCaptureStackTrace(...args: Parameters<typeof Error.captureStackTrace>): void {
+    if ('captureStackTrace' in Error && typeof Error.captureStackTrace === 'function') {
+        Error.captureStackTrace(...args);
+    }
+}

package/src/transaction-error.ts

@@ -0,0 +1,94 @@
+import {
+    SOLANA_ERROR__TRANSACTION_ERROR__DUPLICATE_INSTRUCTION,
+    SOLANA_ERROR__TRANSACTION_ERROR__INSUFFICIENT_FUNDS_FOR_RENT,
+    SOLANA_ERROR__TRANSACTION_ERROR__PROGRAM_EXECUTION_TEMPORARILY_RESTRICTED,
+    SOLANA_ERROR__TRANSACTION_ERROR__UNKNOWN,
+} from './codes';
+import { SolanaError } from './error';
+import { getSolanaErrorFromInstructionError } from './instruction-error';
+import { getSolanaErrorFromRpcError } from './rpc-enum-errors';
+
+/**
+ * How to add an error when an entry is added to the RPC `TransactionError` enum:
+ *
+ *   1. Follow the instructions in `./codes.ts` to add a corresponding Solana error code
+ *   2. Add the `TransactionError` enum name in the same order as it appears in `./codes.ts`
+ *   3. Add the new error name/code mapping to `./__tests__/transaction-error-test.ts`
+ */
+const ORDERED_ERROR_NAMES = [
+    // Keep synced with RPC source: https://github.com/anza-xyz/agave/blob/master/sdk/src/transaction/error.rs
+    // If this list ever gets too large, consider implementing a compression strategy like this:
+    // https://gist.github.com/steveluscher/aaa7cbbb5433b1197983908a40860c47
+    'AccountInUse',
+    'AccountLoadedTwice',
+    'AccountNotFound',
+    'ProgramAccountNotFound',
+    'InsufficientFundsForFee',
+    'InvalidAccountForFee',
+    'AlreadyProcessed',
+    'BlockhashNotFound',
+    // `InstructionError` intentionally omitted; delegated to `getSolanaErrorFromInstructionError`
+    'CallChainTooDeep',
+    'MissingSignatureForFee',
+    'InvalidAccountIndex',
+    'SignatureFailure',
+    'InvalidProgramForExecution',
+    'SanitizeFailure',
+    'ClusterMaintenance',
+    'AccountBorrowOutstanding',
+    'WouldExceedMaxBlockCostLimit',
+    'UnsupportedVersion',
+    'InvalidWritableAccount',
+    'WouldExceedMaxAccountCostLimit',
+    'WouldExceedAccountDataBlockLimit',
+    'TooManyAccountLocks',
+    'AddressLookupTableNotFound',
+    'InvalidAddressLookupTableOwner',
+    'InvalidAddressLookupTableData',
+    'InvalidAddressLookupTableIndex',
+    'InvalidRentPayingAccount',
+    'WouldExceedMaxVoteCostLimit',
+    'WouldExceedAccountDataTotalLimit',
+    'DuplicateInstruction',
+    'InsufficientFundsForRent',
+    'MaxLoadedAccountsDataSizeExceeded',
+    'InvalidLoadedAccountsDataSizeLimit',
+    'ResanitizationNeeded',
+    'ProgramExecutionTemporarilyRestricted',
+    'UnbalancedTransaction',
+];
+
+export function getSolanaErrorFromTransactionError(transactionError: string | { [key: string]: unknown }): SolanaError {
+    if (typeof transactionError === 'object' && 'InstructionError' in transactionError) {
+        return getSolanaErrorFromInstructionError(
+            ...(transactionError.InstructionError as Parameters<typeof getSolanaErrorFromInstructionError>),
+        );
+    }
+    return getSolanaErrorFromRpcError(
+        {
+            errorCodeBaseOffset: 7050001,
+            getErrorContext(errorCode, rpcErrorName, rpcErrorContext) {
+                if (errorCode === SOLANA_ERROR__TRANSACTION_ERROR__UNKNOWN) {
+                    return {
+                        errorName: rpcErrorName,
+                        ...(rpcErrorContext !== undefined ? { transactionErrorContext: rpcErrorContext } : null),
+                    };
+                } else if (errorCode === SOLANA_ERROR__TRANSACTION_ERROR__DUPLICATE_INSTRUCTION) {
+                    return {
+                        index: Number(rpcErrorContext as bigint | number),
+                    };
+                } else if (
+                    errorCode === SOLANA_ERROR__TRANSACTION_ERROR__INSUFFICIENT_FUNDS_FOR_RENT ||
+                    errorCode === SOLANA_ERROR__TRANSACTION_ERROR__PROGRAM_EXECUTION_TEMPORARILY_RESTRICTED
+                ) {
+                    return {
+                        accountIndex: Number((rpcErrorContext as { account_index: bigint | number }).account_index),
+                    };
+                }
+            },
+            orderedErrorNames: ORDERED_ERROR_NAMES,
+            rpcEnumError: transactionError,
+        },
+        getSolanaErrorFromTransactionError,
+    );
+}