@solana/errors 8.6.0 → 8.7.0-canary-20261102161207

package/src/json-rpc-error.ts

@@ -10,6 +10,7 @@ import {
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_STATUS_NOT_AVAILABLE_YET,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_FILTER_TRANSACTION_NOT_FOUND,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_KEY_EXCLUDED_FROM_SECONDARY_INDEX,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LEADER_SCHEDULE_IDENTITY_NOT_FOUND,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_SLOT_SKIPPED,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SLOT_SKIPPED,
@@ -130,6 +131,7 @@ export function getSolanaErrorFromJsonRpcError(putativeErrorResponse: unknown):
                 case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_STATUS_NOT_AVAILABLE_YET:
                 case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_FILTER_TRANSACTION_NOT_FOUND:
                 case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_KEY_EXCLUDED_FROM_SECONDARY_INDEX:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LEADER_SCHEDULE_IDENTITY_NOT_FOUND:
                 case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_SLOT_SKIPPED:
                 case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SLOT_SKIPPED:
                 case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_TRANSACTION_PRECOMPILE_VERIFICATION_FAILURE:
@@ -141,8 +143,13 @@ export function getSolanaErrorFromJsonRpcError(putativeErrorResponse: unknown):
                     errorContext = { __serverMessage: message };
                     break;
                 default:
-                    if (typeof data === 'object' && !Array.isArray(data)) {
+                    if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
                         errorContext = data;
+                    } else {
+                        // No structured data. Keep the server message so it's not lost; this
+                        // matters most for codes that this version of the library doesn't know
+                        // about (eg. one introduced by a newer RPC server).
+                        errorContext = { __serverMessage: message };
                     }
             }
             out = new SolanaError(code as SolanaErrorCode, errorContext as SolanaErrorContext[SolanaErrorCode]);

package/src/message-formatter.ts

@@ -20,6 +20,15 @@ export function getHumanReadableErrorMessage<TErrorCode extends SolanaErrorCode>
     code: TErrorCode,
     context: object = {},
 ): string {
+    if (!(code in SolanaErrorMessages)) {
+        // A code that this version of the library has no message for, such as a JSON-RPC error
+        // code introduced by a newer RPC server. Report the code rather than throwing, along with
+        // the server's own message if one was captured.
+        return '__serverMessage' in context
+            ? // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+              `Unknown Solana error code: ${code} (${context.__serverMessage})`
+            : `Unknown Solana error code: ${code}`;
+    }
     const messageFormatString = SolanaErrorMessages[code];
     if (messageFormatString.length === 0) {
         return '';

package/src/messages.ts

@@ -168,6 +168,7 @@ import {
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_EPOCH_REWARDS_PERIOD_ACTIVE,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_FILTER_TRANSACTION_NOT_FOUND,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_KEY_EXCLUDED_FROM_SECONDARY_INDEX,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LEADER_SCHEDULE_IDENTITY_NOT_FOUND,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_SLOT_SKIPPED,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_UNREACHABLE,
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_MIN_CONTEXT_SLOT_NOT_REACHED,
@@ -618,6 +619,7 @@ export const SolanaErrorMessages: Readonly<{
         'Epoch rewards period still active at slot $slot',
     [SOLANA_ERROR__JSON_RPC__SERVER_ERROR_FILTER_TRANSACTION_NOT_FOUND]: '$__serverMessage',
     [SOLANA_ERROR__JSON_RPC__SERVER_ERROR_KEY_EXCLUDED_FROM_SECONDARY_INDEX]: '$__serverMessage',
+    [SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LEADER_SCHEDULE_IDENTITY_NOT_FOUND]: '$__serverMessage',
     [SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_SLOT_SKIPPED]: '$__serverMessage',
     [SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_UNREACHABLE]:
         'Failed to query long-term storage; please try again',

package/src/simulation-errors.ts

@@ -2,9 +2,55 @@ import {
     SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
     SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT,
     SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS,
-    SolanaErrorCode,
+    SolanaErrorCodeWithSimulationResult,
 } from './codes';
-import { isSolanaError } from './error';
+import { isSolanaError, SolanaError } from './error';
+
+// Typed as a record so that the compiler fails whenever this list and the
+// `SolanaErrorCodeWithSimulationResult` union drift apart, in either direction.
+const SIMULATION_ERROR_CODES: Readonly<Record<SolanaErrorCodeWithSimulationResult, true>> = {
+    [SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE]: true,
+    [SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT]: true,
+    [SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS]: true,
+};
+
+/**
+ * A type guard that returns `true` if the input is a {@link SolanaError} thrown because a
+ * transaction simulation failed.
+ *
+ * When this returns `true`, TypeScript will refine the error's
+ * {@link SolanaError#context | `context`} to the simulation result (eg. `logs` and
+ * `unitsConsumed`). The underlying transaction error, if any, is available as the error's `cause`.
+ *
+ * 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}
+ * - {@link SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS}
+ *
+ * @param e - The value to check.
+ * @return `true` if the input is a simulation error, `false` otherwise.
+ *
+ * @example
+ * Reading the simulation logs of a failed transaction.
+ * ```ts
+ * import { isSimulationError } from '@solana/errors';
+ *
+ * try {
+ *     await sendTransaction(signedTransaction);
+ * } catch (e) {
+ *     if (isSimulationError(e)) {
+ *         console.log('Simulation failed due to:', e.cause);
+ *         console.log('Simulation logs:', e.context.logs);
+ *     }
+ *     throw e;
+ * }
+ * ```
+ *
+ * @see {@link unwrapSimulationError}
+ */
+export function isSimulationError(e: unknown): e is SolanaError<SolanaErrorCodeWithSimulationResult> {
+    return isSolanaError(e) && e.context.__code in SIMULATION_ERROR_CODES;
+}
 
 /**
  * Extracts the underlying cause from a simulation-related error.
@@ -16,10 +62,7 @@ import { isSolanaError } from './error';
  *
  * 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}
- * - {@link SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS}
+ * See {@link isSimulationError} for the list of error codes considered simulation errors.
  *
  * @param error - The error to unwrap.
  * @return The underlying cause if the error is a simulation error, otherwise the original error.
@@ -38,12 +81,7 @@ import { isSolanaError } from './error';
  * ```
  */
 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,
-        SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS,
-    ];
-    if (isSolanaError(error) && !!error.cause && simulationCodes.includes(error.context.__code)) {
+    if (isSimulationError(error) && !!error.cause) {
         return error.cause;
     }
     return error;