@solana/programs 2.0.0-experimental.109615d

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2023 Solana Labs, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+[![npm][npm-image]][npm-url]
+[![npm-downloads][npm-downloads-image]][npm-url]
+[![semantic-release][semantic-release-image]][semantic-release-url]
+<br />
+[![code-style-prettier][code-style-prettier-image]][code-style-prettier-url]
+
+[code-style-prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square
+[code-style-prettier-url]: https://github.com/prettier/prettier
+[npm-downloads-image]: https://img.shields.io/npm/dm/@solana/programs/experimental.svg?style=flat
+[npm-image]: https://img.shields.io/npm/v/@solana/programs/experimental.svg?style=flat
+[npm-url]: https://www.npmjs.com/package/@solana/programs/v/experimental
+[semantic-release-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
+[semantic-release-url]: https://github.com/semantic-release/semantic-release
+
+# @solana/programs
+
+This package contains types for defining programs and helpers for resolving program errors. It can be used standalone, but it is also exported as part of the Solana JavaScript SDK [`@solana/web3.js@experimental`](https://github.com/solana-labs/solana-web3.js/tree/master/packages/library).
+
+## Types
+
+### `Program`
+
+The `Program` type defines a Solana program.
+
+```ts
+const myProgram: Program<'1234..5678'> = {
+    name: 'myProgramName',
+    address: '1234..5678' as Address<'1234..5678'>,
+};
+```
+
+### `ProgramWithErrors`
+
+The `ProgramWithErrors` type helps extend the `Program` type by defining a `getErrorFromCode` function that can be used to resolve a custom program error from a transaction error code.
+
+```ts
+enum MyProgramErrorCode {
+    UNINITIALIZED_ACCOUNT = 0,
+    INVALID_ACCOUNT_OWNER = 1,
+    INVALID_ACCOUNT_DATA = 2,
+    SOME_OTHER_ERROR = 3,
+}
+
+class MyProgramError extends Error {
+    // ...
+}
+
+const myProgram: Program<'1234..5678'> & ProgramWithErrors<MyProgramErrorCode, MyProgramError> = {
+    name: 'myProgramName',
+    address: '1234..5678' as Address<'1234..5678'>,
+    getErrorFromCode: (code: MyProgramErrorCode, originalError: Error): MyProgramError => {
+        // ...
+    },
+};
+```
+
+## Functions
+
+### `resolveTransactionError()`
+
+This function takes a raw error caused by a transaction failure and attempts to resolve it into a custom program error.
+
+For this to work, the `resolveTransactionError` function also needs the following parameters:
+
+-   The `transaction` object that failed to execute. This allows us to identify the failing instruction and correctly identify the program that caused the error.
+-   An array of all `programs` that can be used to resolve the error. If the program that caused the error is not present in the array, the function won't be able to return a custom program error.
+
+Note that, if the error cannot be resolved into a custom program error, the original error is returned as-is.
+
+```ts
+// Store your programs.
+const programs = [createSplSystemProgram(), createSplComputeBudgetProgram(), createSplAddressLookupTableProgram()];
+
+try {
+    // Send and confirm your transaction.
+} catch (error) {
+    throw resolveTransactionError(error, transaction, programs);
+}
+```

package/dist/index.browser.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// src/resolve-transaction-error.ts
+function resolveTransactionError(error, transaction, programs) {
+  const fullLogs = error.message + "\n" + (error.logs ?? []).join("\n");
+  const instructionRegex = /Error processing Instruction (\d+)/;
+  const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;
+  const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;
+  if (instructionIndex === null)
+    return error;
+  const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;
+  const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;
+  const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;
+  if (errorCode === null)
+    return error;
+  const programAddress = transaction.instructions[instructionIndex]?.programAddress ?? null;
+  if (!programAddress)
+    return error;
+  const program = programs.find(
+    (program2) => program2.address === programAddress && typeof program2.getErrorFromCode !== "undefined"
+  ) ?? null;
+  if (!program)
+    return error;
+  return program.getErrorFromCode(errorCode, error);
+}
+
+exports.resolveTransactionError = resolveTransactionError;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.browser.cjs.map

package/dist/index.browser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve-transaction-error.ts"],"names":["program"],"mappings":";AAkBO,SAAS,wBACZ,OACA,aACA,UACK;AAEL,QAAM,WAAW,MAAM,UAAU,QAAQ,MAAM,QAAQ,CAAC,GAAG,KAAK,IAAI;AAGpE,QAAM,mBAAmB;AACzB,QAAM,yBAAyB,SAAS,MAAM,gBAAgB,IAAI,CAAC,KAAK;AACxE,QAAM,mBAAmB,yBAAyB,SAAS,wBAAwB,EAAE,IAAI;AACzF,MAAI,qBAAqB;AAAM,WAAO;AAGtC,QAAM,iBAAiB;AACvB,QAAM,kBAAkB,SAAS,MAAM,cAAc,IAAI,CAAC,KAAK;AAC/D,QAAM,YAAY,kBAAkB,SAAS,iBAAiB,EAAE,IAAI;AACpE,MAAI,cAAc;AAAM,WAAO;AAG/B,QAAM,iBAAiC,YAAY,aAAa,gBAAgB,GAAG,kBAAkB;AACrG,MAAI,CAAC;AAAgB,WAAO;AAG5B,QAAM,UACF,SAAS;AAAA,IACL,CAACA,aACGA,SAAQ,YAAY,kBAAkB,OAAOA,SAAQ,qBAAqB;AAAA,EAClF,KAAK;AACT,MAAI,CAAC;AAAS,WAAO;AAGrB,SAAO,QAAQ,iBAAiB,WAAW,KAAK;AACpD","sourcesContent":["import type { Address } from '@solana/addresses';\nimport type { Transaction } from '@solana/transactions';\n\nimport { Program, ProgramWithErrors } from './program';\n\n/**\n * Resolves a custom program error from a transaction error\n * with logs using the provided list of programs.\n * The original error is returned if the error cannot be\n * resolved from the given programs.\n *\n * @param error The raw error to resolve containing the program logs.\n * @param transaction The transaction that caused the error.\n * @param programs The list of programs to go through when resolving the transaction error.\n * They should ideally contain all programs the transaction is sending instructions to.\n * @returns The resolved program error, or the original transaction error\n * if the error cannot be resolved using the provided programs.\n */\nexport function resolveTransactionError(\n    error: Error & Readonly<{ logs?: readonly string[] }>,\n    transaction: Transaction,\n    programs: Program[],\n): Error {\n    // Compute the full logs from which to parse the instruction index and error code.\n    const fullLogs = error.message + '\\n' + (error.logs ?? []).join('\\n');\n\n    // Parse the instruction number, or return the original error.\n    const instructionRegex = /Error processing Instruction (\\d+)/;\n    const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;\n    const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;\n    if (instructionIndex === null) return error;\n\n    // Parse the error code, or return the original error.\n    const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;\n    const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;\n    const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;\n    if (errorCode === null) return error;\n\n    // Get the program address from the instruction in the transaction, or return the original error.\n    const programAddress: Address | null = transaction.instructions[instructionIndex]?.programAddress ?? null;\n    if (!programAddress) return error;\n\n    // Find a matching program with error handling, or return the original error.\n    const program: ProgramWithErrors | null =\n        programs.find(\n            (program): program is Program & ProgramWithErrors =>\n                program.address === programAddress && typeof program.getErrorFromCode !== 'undefined',\n        ) ?? null;\n    if (!program) return error;\n\n    // Resolve the error from the identified program.\n    return program.getErrorFromCode(errorCode, error);\n}\n"]}

package/dist/index.browser.js

@@ -0,0 +1,27 @@
+// src/resolve-transaction-error.ts
+function resolveTransactionError(error, transaction, programs) {
+  const fullLogs = error.message + "\n" + (error.logs ?? []).join("\n");
+  const instructionRegex = /Error processing Instruction (\d+)/;
+  const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;
+  const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;
+  if (instructionIndex === null)
+    return error;
+  const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;
+  const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;
+  const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;
+  if (errorCode === null)
+    return error;
+  const programAddress = transaction.instructions[instructionIndex]?.programAddress ?? null;
+  if (!programAddress)
+    return error;
+  const program = programs.find(
+    (program2) => program2.address === programAddress && typeof program2.getErrorFromCode !== "undefined"
+  ) ?? null;
+  if (!program)
+    return error;
+  return program.getErrorFromCode(errorCode, error);
+}
+
+export { resolveTransactionError };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.browser.js.map

package/dist/index.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve-transaction-error.ts"],"names":["program"],"mappings":";AAkBO,SAAS,wBACZ,OACA,aACA,UACK;AAEL,QAAM,WAAW,MAAM,UAAU,QAAQ,MAAM,QAAQ,CAAC,GAAG,KAAK,IAAI;AAGpE,QAAM,mBAAmB;AACzB,QAAM,yBAAyB,SAAS,MAAM,gBAAgB,IAAI,CAAC,KAAK;AACxE,QAAM,mBAAmB,yBAAyB,SAAS,wBAAwB,EAAE,IAAI;AACzF,MAAI,qBAAqB;AAAM,WAAO;AAGtC,QAAM,iBAAiB;AACvB,QAAM,kBAAkB,SAAS,MAAM,cAAc,IAAI,CAAC,KAAK;AAC/D,QAAM,YAAY,kBAAkB,SAAS,iBAAiB,EAAE,IAAI;AACpE,MAAI,cAAc;AAAM,WAAO;AAG/B,QAAM,iBAAiC,YAAY,aAAa,gBAAgB,GAAG,kBAAkB;AACrG,MAAI,CAAC;AAAgB,WAAO;AAG5B,QAAM,UACF,SAAS;AAAA,IACL,CAACA,aACGA,SAAQ,YAAY,kBAAkB,OAAOA,SAAQ,qBAAqB;AAAA,EAClF,KAAK;AACT,MAAI,CAAC;AAAS,WAAO;AAGrB,SAAO,QAAQ,iBAAiB,WAAW,KAAK;AACpD","sourcesContent":["import type { Address } from '@solana/addresses';\nimport type { Transaction } from '@solana/transactions';\n\nimport { Program, ProgramWithErrors } from './program';\n\n/**\n * Resolves a custom program error from a transaction error\n * with logs using the provided list of programs.\n * The original error is returned if the error cannot be\n * resolved from the given programs.\n *\n * @param error The raw error to resolve containing the program logs.\n * @param transaction The transaction that caused the error.\n * @param programs The list of programs to go through when resolving the transaction error.\n * They should ideally contain all programs the transaction is sending instructions to.\n * @returns The resolved program error, or the original transaction error\n * if the error cannot be resolved using the provided programs.\n */\nexport function resolveTransactionError(\n    error: Error & Readonly<{ logs?: readonly string[] }>,\n    transaction: Transaction,\n    programs: Program[],\n): Error {\n    // Compute the full logs from which to parse the instruction index and error code.\n    const fullLogs = error.message + '\\n' + (error.logs ?? []).join('\\n');\n\n    // Parse the instruction number, or return the original error.\n    const instructionRegex = /Error processing Instruction (\\d+)/;\n    const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;\n    const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;\n    if (instructionIndex === null) return error;\n\n    // Parse the error code, or return the original error.\n    const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;\n    const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;\n    const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;\n    if (errorCode === null) return error;\n\n    // Get the program address from the instruction in the transaction, or return the original error.\n    const programAddress: Address | null = transaction.instructions[instructionIndex]?.programAddress ?? null;\n    if (!programAddress) return error;\n\n    // Find a matching program with error handling, or return the original error.\n    const program: ProgramWithErrors | null =\n        programs.find(\n            (program): program is Program & ProgramWithErrors =>\n                program.address === programAddress && typeof program.getErrorFromCode !== 'undefined',\n        ) ?? null;\n    if (!program) return error;\n\n    // Resolve the error from the identified program.\n    return program.getErrorFromCode(errorCode, error);\n}\n"]}

package/dist/index.native.js

@@ -0,0 +1,27 @@
+// src/resolve-transaction-error.ts
+function resolveTransactionError(error, transaction, programs) {
+  const fullLogs = error.message + "\n" + (error.logs ?? []).join("\n");
+  const instructionRegex = /Error processing Instruction (\d+)/;
+  const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;
+  const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;
+  if (instructionIndex === null)
+    return error;
+  const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;
+  const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;
+  const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;
+  if (errorCode === null)
+    return error;
+  const programAddress = transaction.instructions[instructionIndex]?.programAddress ?? null;
+  if (!programAddress)
+    return error;
+  const program = programs.find(
+    (program2) => program2.address === programAddress && typeof program2.getErrorFromCode !== "undefined"
+  ) ?? null;
+  if (!program)
+    return error;
+  return program.getErrorFromCode(errorCode, error);
+}
+
+export { resolveTransactionError };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.native.js.map

package/dist/index.native.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve-transaction-error.ts"],"names":["program"],"mappings":";AAkBO,SAAS,wBACZ,OACA,aACA,UACK;AAEL,QAAM,WAAW,MAAM,UAAU,QAAQ,MAAM,QAAQ,CAAC,GAAG,KAAK,IAAI;AAGpE,QAAM,mBAAmB;AACzB,QAAM,yBAAyB,SAAS,MAAM,gBAAgB,IAAI,CAAC,KAAK;AACxE,QAAM,mBAAmB,yBAAyB,SAAS,wBAAwB,EAAE,IAAI;AACzF,MAAI,qBAAqB;AAAM,WAAO;AAGtC,QAAM,iBAAiB;AACvB,QAAM,kBAAkB,SAAS,MAAM,cAAc,IAAI,CAAC,KAAK;AAC/D,QAAM,YAAY,kBAAkB,SAAS,iBAAiB,EAAE,IAAI;AACpE,MAAI,cAAc;AAAM,WAAO;AAG/B,QAAM,iBAAiC,YAAY,aAAa,gBAAgB,GAAG,kBAAkB;AACrG,MAAI,CAAC;AAAgB,WAAO;AAG5B,QAAM,UACF,SAAS;AAAA,IACL,CAACA,aACGA,SAAQ,YAAY,kBAAkB,OAAOA,SAAQ,qBAAqB;AAAA,EAClF,KAAK;AACT,MAAI,CAAC;AAAS,WAAO;AAGrB,SAAO,QAAQ,iBAAiB,WAAW,KAAK;AACpD","sourcesContent":["import type { Address } from '@solana/addresses';\nimport type { Transaction } from '@solana/transactions';\n\nimport { Program, ProgramWithErrors } from './program';\n\n/**\n * Resolves a custom program error from a transaction error\n * with logs using the provided list of programs.\n * The original error is returned if the error cannot be\n * resolved from the given programs.\n *\n * @param error The raw error to resolve containing the program logs.\n * @param transaction The transaction that caused the error.\n * @param programs The list of programs to go through when resolving the transaction error.\n * They should ideally contain all programs the transaction is sending instructions to.\n * @returns The resolved program error, or the original transaction error\n * if the error cannot be resolved using the provided programs.\n */\nexport function resolveTransactionError(\n    error: Error & Readonly<{ logs?: readonly string[] }>,\n    transaction: Transaction,\n    programs: Program[],\n): Error {\n    // Compute the full logs from which to parse the instruction index and error code.\n    const fullLogs = error.message + '\\n' + (error.logs ?? []).join('\\n');\n\n    // Parse the instruction number, or return the original error.\n    const instructionRegex = /Error processing Instruction (\\d+)/;\n    const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;\n    const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;\n    if (instructionIndex === null) return error;\n\n    // Parse the error code, or return the original error.\n    const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;\n    const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;\n    const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;\n    if (errorCode === null) return error;\n\n    // Get the program address from the instruction in the transaction, or return the original error.\n    const programAddress: Address | null = transaction.instructions[instructionIndex]?.programAddress ?? null;\n    if (!programAddress) return error;\n\n    // Find a matching program with error handling, or return the original error.\n    const program: ProgramWithErrors | null =\n        programs.find(\n            (program): program is Program & ProgramWithErrors =>\n                program.address === programAddress && typeof program.getErrorFromCode !== 'undefined',\n        ) ?? null;\n    if (!program) return error;\n\n    // Resolve the error from the identified program.\n    return program.getErrorFromCode(errorCode, error);\n}\n"]}

package/dist/index.node.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// src/resolve-transaction-error.ts
+function resolveTransactionError(error, transaction, programs) {
+  const fullLogs = error.message + "\n" + (error.logs ?? []).join("\n");
+  const instructionRegex = /Error processing Instruction (\d+)/;
+  const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;
+  const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;
+  if (instructionIndex === null)
+    return error;
+  const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;
+  const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;
+  const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;
+  if (errorCode === null)
+    return error;
+  const programAddress = transaction.instructions[instructionIndex]?.programAddress ?? null;
+  if (!programAddress)
+    return error;
+  const program = programs.find(
+    (program2) => program2.address === programAddress && typeof program2.getErrorFromCode !== "undefined"
+  ) ?? null;
+  if (!program)
+    return error;
+  return program.getErrorFromCode(errorCode, error);
+}
+
+exports.resolveTransactionError = resolveTransactionError;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.node.cjs.map

package/dist/index.node.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve-transaction-error.ts"],"names":["program"],"mappings":";AAkBO,SAAS,wBACZ,OACA,aACA,UACK;AAEL,QAAM,WAAW,MAAM,UAAU,QAAQ,MAAM,QAAQ,CAAC,GAAG,KAAK,IAAI;AAGpE,QAAM,mBAAmB;AACzB,QAAM,yBAAyB,SAAS,MAAM,gBAAgB,IAAI,CAAC,KAAK;AACxE,QAAM,mBAAmB,yBAAyB,SAAS,wBAAwB,EAAE,IAAI;AACzF,MAAI,qBAAqB;AAAM,WAAO;AAGtC,QAAM,iBAAiB;AACvB,QAAM,kBAAkB,SAAS,MAAM,cAAc,IAAI,CAAC,KAAK;AAC/D,QAAM,YAAY,kBAAkB,SAAS,iBAAiB,EAAE,IAAI;AACpE,MAAI,cAAc;AAAM,WAAO;AAG/B,QAAM,iBAAiC,YAAY,aAAa,gBAAgB,GAAG,kBAAkB;AACrG,MAAI,CAAC;AAAgB,WAAO;AAG5B,QAAM,UACF,SAAS;AAAA,IACL,CAACA,aACGA,SAAQ,YAAY,kBAAkB,OAAOA,SAAQ,qBAAqB;AAAA,EAClF,KAAK;AACT,MAAI,CAAC;AAAS,WAAO;AAGrB,SAAO,QAAQ,iBAAiB,WAAW,KAAK;AACpD","sourcesContent":["import type { Address } from '@solana/addresses';\nimport type { Transaction } from '@solana/transactions';\n\nimport { Program, ProgramWithErrors } from './program';\n\n/**\n * Resolves a custom program error from a transaction error\n * with logs using the provided list of programs.\n * The original error is returned if the error cannot be\n * resolved from the given programs.\n *\n * @param error The raw error to resolve containing the program logs.\n * @param transaction The transaction that caused the error.\n * @param programs The list of programs to go through when resolving the transaction error.\n * They should ideally contain all programs the transaction is sending instructions to.\n * @returns The resolved program error, or the original transaction error\n * if the error cannot be resolved using the provided programs.\n */\nexport function resolveTransactionError(\n    error: Error & Readonly<{ logs?: readonly string[] }>,\n    transaction: Transaction,\n    programs: Program[],\n): Error {\n    // Compute the full logs from which to parse the instruction index and error code.\n    const fullLogs = error.message + '\\n' + (error.logs ?? []).join('\\n');\n\n    // Parse the instruction number, or return the original error.\n    const instructionRegex = /Error processing Instruction (\\d+)/;\n    const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;\n    const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;\n    if (instructionIndex === null) return error;\n\n    // Parse the error code, or return the original error.\n    const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;\n    const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;\n    const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;\n    if (errorCode === null) return error;\n\n    // Get the program address from the instruction in the transaction, or return the original error.\n    const programAddress: Address | null = transaction.instructions[instructionIndex]?.programAddress ?? null;\n    if (!programAddress) return error;\n\n    // Find a matching program with error handling, or return the original error.\n    const program: ProgramWithErrors | null =\n        programs.find(\n            (program): program is Program & ProgramWithErrors =>\n                program.address === programAddress && typeof program.getErrorFromCode !== 'undefined',\n        ) ?? null;\n    if (!program) return error;\n\n    // Resolve the error from the identified program.\n    return program.getErrorFromCode(errorCode, error);\n}\n"]}

package/dist/index.node.js

@@ -0,0 +1,27 @@
+// src/resolve-transaction-error.ts
+function resolveTransactionError(error, transaction, programs) {
+  const fullLogs = error.message + "\n" + (error.logs ?? []).join("\n");
+  const instructionRegex = /Error processing Instruction (\d+)/;
+  const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;
+  const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;
+  if (instructionIndex === null)
+    return error;
+  const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;
+  const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;
+  const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;
+  if (errorCode === null)
+    return error;
+  const programAddress = transaction.instructions[instructionIndex]?.programAddress ?? null;
+  if (!programAddress)
+    return error;
+  const program = programs.find(
+    (program2) => program2.address === programAddress && typeof program2.getErrorFromCode !== "undefined"
+  ) ?? null;
+  if (!program)
+    return error;
+  return program.getErrorFromCode(errorCode, error);
+}
+
+export { resolveTransactionError };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.node.js.map

package/dist/index.node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve-transaction-error.ts"],"names":["program"],"mappings":";AAkBO,SAAS,wBACZ,OACA,aACA,UACK;AAEL,QAAM,WAAW,MAAM,UAAU,QAAQ,MAAM,QAAQ,CAAC,GAAG,KAAK,IAAI;AAGpE,QAAM,mBAAmB;AACzB,QAAM,yBAAyB,SAAS,MAAM,gBAAgB,IAAI,CAAC,KAAK;AACxE,QAAM,mBAAmB,yBAAyB,SAAS,wBAAwB,EAAE,IAAI;AACzF,MAAI,qBAAqB;AAAM,WAAO;AAGtC,QAAM,iBAAiB;AACvB,QAAM,kBAAkB,SAAS,MAAM,cAAc,IAAI,CAAC,KAAK;AAC/D,QAAM,YAAY,kBAAkB,SAAS,iBAAiB,EAAE,IAAI;AACpE,MAAI,cAAc;AAAM,WAAO;AAG/B,QAAM,iBAAiC,YAAY,aAAa,gBAAgB,GAAG,kBAAkB;AACrG,MAAI,CAAC;AAAgB,WAAO;AAG5B,QAAM,UACF,SAAS;AAAA,IACL,CAACA,aACGA,SAAQ,YAAY,kBAAkB,OAAOA,SAAQ,qBAAqB;AAAA,EAClF,KAAK;AACT,MAAI,CAAC;AAAS,WAAO;AAGrB,SAAO,QAAQ,iBAAiB,WAAW,KAAK;AACpD","sourcesContent":["import type { Address } from '@solana/addresses';\nimport type { Transaction } from '@solana/transactions';\n\nimport { Program, ProgramWithErrors } from './program';\n\n/**\n * Resolves a custom program error from a transaction error\n * with logs using the provided list of programs.\n * The original error is returned if the error cannot be\n * resolved from the given programs.\n *\n * @param error The raw error to resolve containing the program logs.\n * @param transaction The transaction that caused the error.\n * @param programs The list of programs to go through when resolving the transaction error.\n * They should ideally contain all programs the transaction is sending instructions to.\n * @returns The resolved program error, or the original transaction error\n * if the error cannot be resolved using the provided programs.\n */\nexport function resolveTransactionError(\n    error: Error & Readonly<{ logs?: readonly string[] }>,\n    transaction: Transaction,\n    programs: Program[],\n): Error {\n    // Compute the full logs from which to parse the instruction index and error code.\n    const fullLogs = error.message + '\\n' + (error.logs ?? []).join('\\n');\n\n    // Parse the instruction number, or return the original error.\n    const instructionRegex = /Error processing Instruction (\\d+)/;\n    const instructionIndexString = fullLogs.match(instructionRegex)?.[1] ?? null;\n    const instructionIndex = instructionIndexString ? parseInt(instructionIndexString, 10) : null;\n    if (instructionIndex === null) return error;\n\n    // Parse the error code, or return the original error.\n    const errorCodeRegex = /Custom program error: (0x[a-f0-9]+)/i;\n    const errorCodeString = fullLogs.match(errorCodeRegex)?.[1] ?? null;\n    const errorCode = errorCodeString ? parseInt(errorCodeString, 16) : null;\n    if (errorCode === null) return error;\n\n    // Get the program address from the instruction in the transaction, or return the original error.\n    const programAddress: Address | null = transaction.instructions[instructionIndex]?.programAddress ?? null;\n    if (!programAddress) return error;\n\n    // Find a matching program with error handling, or return the original error.\n    const program: ProgramWithErrors | null =\n        programs.find(\n            (program): program is Program & ProgramWithErrors =>\n                program.address === programAddress && typeof program.getErrorFromCode !== 'undefined',\n        ) ?? null;\n    if (!program) return error;\n\n    // Resolve the error from the identified program.\n    return program.getErrorFromCode(errorCode, error);\n}\n"]}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './program.js';
+export * from './resolve-transaction-error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,6BAA6B,CAAC"}

package/dist/types/program.d.ts

@@ -0,0 +1,31 @@
+import type { Address } from '@solana/addresses';
+/**
+ * Defines a Solana program.
+ */
+export type Program<TAddress extends string = string> = {
+    /**
+     * A unique name for the Program.
+     *
+     * To avoid conflict with other organizations, it is recommended
+     * to prefix the program name with a namespace that is unique to
+     * your organization. For instance, programs belonging to the
+     * Solana Program Library are prefixed with `spl` like so:
+     * `splMemo` or `splToken`.
+     */
+    name: string;
+    /**
+     * The base58 address of the program.
+     */
+    address: Address<TAddress>;
+    /**
+     * Retrieves a program-specific error from a given error code.
+     */
+    getErrorFromCode?: (code: number, cause?: Error) => Error;
+};
+/**
+ * Defines a Solana program that can return custom errors from a provided error code.
+ */
+export type ProgramWithErrors<TErrorCode extends number = number, TError extends Error = Error> = {
+    getErrorFromCode: (code: TErrorCode, cause?: Error) => TError;
+};
+//# sourceMappingURL=program.d.ts.map

package/dist/types/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,OAAO,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,IAAI;IACpD;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE3B;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,KAAK,CAAC;CAC7D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,SAAS,KAAK,GAAG,KAAK,IAAI;IAC9F,gBAAgB,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,MAAM,CAAC;CACjE,CAAC"}

package/dist/types/resolve-transaction-error.d.ts

@@ -0,0 +1,19 @@
+import type { Transaction } from '@solana/transactions';
+import { Program } from './program.js';
+/**
+ * Resolves a custom program error from a transaction error
+ * with logs using the provided list of programs.
+ * The original error is returned if the error cannot be
+ * resolved from the given programs.
+ *
+ * @param error The raw error to resolve containing the program logs.
+ * @param transaction The transaction that caused the error.
+ * @param programs The list of programs to go through when resolving the transaction error.
+ * They should ideally contain all programs the transaction is sending instructions to.
+ * @returns The resolved program error, or the original transaction error
+ * if the error cannot be resolved using the provided programs.
+ */
+export declare function resolveTransactionError(error: Error & Readonly<{
+    logs?: readonly string[];
+}>, transaction: Transaction, programs: Program[]): Error;
+//# sourceMappingURL=resolve-transaction-error.d.ts.map

package/dist/types/resolve-transaction-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-transaction-error.d.ts","sourceRoot":"","sources":["../../src/resolve-transaction-error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,OAAO,EAAqB,MAAM,WAAW,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACnC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,EACrD,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,OAAO,EAAE,GACpB,KAAK,CA8BP"}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@solana/programs",
+  "version": "2.0.0-experimental.109615d",
+  "description": "Helpers for defining programs and resolving program errors",
+  "exports": {
+    "browser": {
+      "import": "./dist/index.browser.js",
+      "require": "./dist/index.browser.cjs"
+    },
+    "node": {
+      "import": "./dist/index.node.js",
+      "require": "./dist/index.node.cjs"
+    },
+    "react-native": "./dist/index.native.js",
+    "types": "./dist/types/index.d.ts"
+  },
+  "browser": {
+    "./dist/index.node.cjs": "./dist/index.browser.cjs",
+    "./dist/index.node.js": "./dist/index.browser.js"
+  },
+  "main": "./dist/index.node.cjs",
+  "module": "./dist/index.node.js",
+  "react-native": "./dist/index.native.js",
+  "types": "./dist/types/index.d.ts",
+  "type": "module",
+  "files": [
+    "./dist/"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "blockchain",
+    "solana",
+    "web3"
+  ],
+  "author": "Solana Labs Maintainers <maintainers@solanalabs.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/solana-labs/solana-web3.js"
+  },
+  "bugs": {
+    "url": "http://github.com/solana-labs/solana-web3.js/issues"
+  },
+  "browserslist": [
+    "supports bigint and not dead",
+    "maintained node versions"
+  ],
+  "devDependencies": {
+    "@solana/eslint-config-solana": "^1.0.2",
+    "@swc/jest": "^0.2.29",
+    "@types/jest": "^29.5.11",
+    "@typescript-eslint/eslint-plugin": "^6.13.2",
+    "@typescript-eslint/parser": "^6.3.0",
+    "agadoo": "^3.0.0",
+    "eslint": "^8.45.0",
+    "eslint-plugin-sort-keys-fix": "^1.1.2",
+    "jest": "^29.7.0",
+    "jest-runner-eslint": "^2.1.2",
+    "jest-runner-prettier": "^1.0.0",
+    "prettier": "^3.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.2.2",
+    "version-from-git": "^1.1.1",
+    "@solana/addresses": "2.0.0-experimental.109615d",
+    "@solana/functional": "2.0.0-experimental.109615d",
+    "@solana/transactions": "2.0.0-experimental.109615d",
+    "build-scripts": "0.0.0",
+    "test-config": "0.0.0",
+    "tsconfig": "0.0.0"
+  },
+  "bundlewatch": {
+    "defaultCompression": "gzip",
+    "files": [
+      {
+        "path": "./dist/index*.js"
+      }
+    ]
+  },
+  "scripts": {
+    "compile:js": "tsup --config build-scripts/tsup.config.package.ts",
+    "compile:typedefs": "tsc -p ./tsconfig.declarations.json && node node_modules/build-scripts/add-js-extension-to-types.mjs",
+    "dev": "jest -c node_modules/test-config/jest-dev.config.ts --rootDir . --watch",
+    "publish-packages": "pnpm publish --tag experimental --access public --no-git-checks",
+    "style:fix": "pnpm eslint --fix src/* && pnpm prettier -w src/* package.json",
+    "test:lint": "jest -c node_modules/test-config/jest-lint.config.ts --rootDir . --silent",
+    "test:prettier": "jest -c node_modules/test-config/jest-prettier.config.ts --rootDir . --silent",
+    "test:treeshakability:browser": "agadoo dist/index.browser.js",
+    "test:treeshakability:native": "agadoo dist/index.native.js",
+    "test:treeshakability:node": "agadoo dist/index.node.js",
+    "test:typecheck": "tsc --noEmit",
+    "test:unit:browser": "jest -c node_modules/test-config/jest-unit.config.browser.ts --rootDir . --silent",
+    "test:unit:node": "jest -c node_modules/test-config/jest-unit.config.node.ts --rootDir . --silent"
+  }
+}