@solana/programs 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/programs",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Helpers for defining programs and resolving program errors",
   "homepage": "https://www.solanakit.com/api#solanaprograms",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,8 +56,8 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/addresses": "6.3.1",
-    "@solana/errors": "6.3.1"
+    "@solana/addresses": "6.3.2-canary-20260313112147",
+    "@solana/errors": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * This package contains helpers for identifying custom program errors. 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).
+ *
+ * @packageDocumentation
+ */
+export * from './program-error';

package/src/program-error.ts

@@ -0,0 +1,46 @@
+import type { Address } from '@solana/addresses';
+import { isSolanaError, SOLANA_ERROR__INSTRUCTION_ERROR__CUSTOM, SolanaError } from '@solana/errors';
+
+/**
+ * Identifies whether an error -- typically caused by a transaction failure -- is a custom program
+ * error from the provided program address.
+ *
+ * @param transactionMessage The transaction message that failed to execute. Since the RPC response
+ * only provides the index of the failed instruction, the transaction message is required to
+ * determine its program address
+ * @param programAddress The address of the program from which the error is expected to have
+ * originated
+ * @param code The expected error code of the custom program error. When provided, the function will
+ * check that the custom program error code matches the given value.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     // Send and confirm your transaction.
+ * } catch (error) {
+ *     if (isProgramError(error, transactionMessage, myProgramAddress, 42)) {
+ *         // Handle custom program error 42 from this program.
+ *     } else if (isProgramError(error, transactionMessage, myProgramAddress)) {
+ *         // Handle all other custom program errors from this program.
+ *     } else {
+ *         throw error;
+ *     }
+ * }
+ * ```
+ */
+export function isProgramError<TProgramErrorCode extends number>(
+    error: unknown,
+    transactionMessage: { instructions: Record<number, { programAddress: Address }> },
+    programAddress: Address,
+    code?: TProgramErrorCode,
+): error is Readonly<{ context: Readonly<{ code: TProgramErrorCode }> }> &
+    SolanaError<typeof SOLANA_ERROR__INSTRUCTION_ERROR__CUSTOM> {
+    if (!isSolanaError(error, SOLANA_ERROR__INSTRUCTION_ERROR__CUSTOM)) {
+        return false;
+    }
+    const instructionProgramAddress = transactionMessage.instructions[error.context.index]?.programAddress;
+    if (!instructionProgramAddress || instructionProgramAddress !== programAddress) {
+        return false;
+    }
+    return typeof code === 'undefined' || error.context.code === code;
+}