feat: add fail reasons (#16)

Author: Alejandbel

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- Added fail reason (`failReason`) to failed transaction
+
 ## [0.5.0] - 2025-01-17
 
 ### Added

src/errors.json

@@ -0,0 +1,115 @@
+{
+  "2": {
+    "description": "Stack underflow"
+  },
+  "3": {
+    "description": "Stack overflow"
+  },
+  "4": {
+    "description": "Integer overflow"
+  },
+  "5": {
+    "description": "Integer out of expected range"
+  },
+  "6": {
+    "description": "Invalid opcode"
+  },
+  "7": {
+    "description": "Type check error"
+  },
+  "8": {
+    "description": "Cell overflow"
+  },
+  "9": {
+    "description": "Cell underflow"
+  },
+  "10": {
+    "description": "Dictionary error"
+  },
+  "11": {
+    "description": "'Unknown' error"
+  },
+  "12": {
+    "description": "Fatal error"
+  },
+  "13": {
+    "description": "Out of gas error"
+  },
+  "14": {
+    "description": "Virtualization error"
+  },
+  "32": {
+    "description": "Action list is invalid"
+  },
+  "33": {
+    "description": "Action list is too long"
+  },
+  "34": {
+    "description": "Action is invalid or not supported"
+  },
+  "35": {
+    "description": "Invalid source address in outbound description"
+  },
+  "36": {
+    "description": "Invalid destination address in outbound message"
+  },
+  "37": {
+    "description": "Not enough Toncoin"
+  },
+  "38": {
+    "description": "Not enough extra currencies"
+  },
+  "39": {
+    "description": "Outbound message does not fit into a cell after rewriting"
+  },
+  "40": {
+    "description": "Cannot process a message"
+  },
+  "41": {
+    "description": "Library reference is null"
+  },
+  "42": {
+    "description": "Library change action error"
+  },
+  "43": {
+    "description": "Exceeded maximum number of cells in the library or the maximum depth of the Merkle tree"
+  },
+  "50": {
+    "description": "Account state size exceeded limits"
+  },
+
+  "128": {
+    "description": "Null reference exception"
+  },
+  "129": {
+    "description": "Invalid serialization prefix"
+  },
+  "130": {
+    "description": "Invalid incoming message"
+  },
+  "131": {
+    "description": "Constraints error"
+  },
+  "132": {
+    "description": "Access denied"
+  },
+  "133": {
+    "description": "Contract stopped"
+  },
+  "134": {
+    "description": "Invalid argument"
+  },
+  "135": {
+    "description": "Code of a contract was not found"
+  },
+  "136": {
+    "description": "Invalid standard address"
+  },
+  "138": {
+    "description": "Not a basechain address"
+  },
+
+  "65535": {
+    "description": "Unrecognized message opcode"
+  }
+}

src/test/transaction.ts

@@ -1,6 +1,11 @@
 import { AccountStatus, Address, Cell, CurrencyCollection, Transaction } from "@ton/core";
 import { inspect } from "node-inspect-extracted";
 import { CompareResult } from "./interface";
+import errors from "../errors.json";
+
+export type FailReason = {
+    description: string;
+}
 
 export type FlatTransaction = {
     from?: Address
@@ -28,6 +33,16 @@ export type FlatTransaction = {
     success?: boolean
 }
 
+const typedErrors: Partial<Record<string, FailReason>> = errors;
+
+export function extractFailReason(tx: FlatTransaction): FailReason | undefined {
+    if (tx.success) {
+        return;
+    }
+
+    return typedErrors[String(tx.exitCode)] ?? typedErrors[String(tx.actionResultCode)];
+}
+
 type WithFunctions<T> = {
     [K in keyof T]: T[K] | ((x: T[K]) => boolean)
 }
@@ -52,6 +67,19 @@ function extractEc(cc: CurrencyCollection): [number, bigint][] {
     return r;
 }
 
+export type PrettyTransaction = FlatTransaction & {
+    failReason?: FailReason;
+}
+
+export function prettifyTransaction(tx: Transaction): PrettyTransaction {
+    const flatTx = flattenTransaction(tx);
+    const failReason = extractFailReason(flatTx);
+    return {
+        ...flatTx,
+        failReason,
+    }
+}
+
 export function flattenTransaction(tx: Transaction): FlatTransaction {
     return {
         lt: tx.lt,
@@ -152,16 +180,15 @@ export function compareTransactionForTest(subject: any, cmp: FlatTransactionComp
     if (Array.isArray(subject)) {
         return {
             pass: subject.some(tx => compareTransaction(flattenTransaction(tx), cmp)),
-            posMessage: ((subj: any[], cmp: FlatTransactionComparable) => `Expected ${inspect(subj.map(tx => flattenTransaction(tx)))} to contain a transaction that matches pattern ${inspect(cmp)}`).bind(undefined, subject, cmp),
-            negMessage: ((subj: any[], cmp: FlatTransactionComparable) => `Expected ${inspect(subj.map(tx => flattenTransaction(tx)))} NOT to contain a transaction that matches pattern ${inspect(cmp)}, but it does`).bind(undefined, subject, cmp),
+            posMessage: ((subj: any[], cmp: FlatTransactionComparable) => `Expected ${inspect(subj.map(tx => prettifyTransaction(tx)))} to contain a transaction that matches pattern ${inspect(cmp)}`).bind(undefined, subject, cmp),
+            negMessage: ((subj: any[], cmp: FlatTransactionComparable) => `Expected ${inspect(subj.map(tx => prettifyTransaction(tx)))} NOT to contain a transaction that matches pattern ${inspect(cmp)}, but it does`).bind(undefined, subject, cmp),
         }
     } else {
         try {
-            const flat = flattenTransaction(subject)
             return {
-                pass: compareTransaction(flat, cmp),
-                posMessage: ((flat: any, cmp: FlatTransactionComparable) => `Expected ${inspect(flat)} to match pattern ${inspect(cmp)}`).bind(undefined, flat, cmp),
-                negMessage: ((flat: any, cmp: FlatTransactionComparable) => `Expected ${inspect(flat)} NOT to match pattern ${inspect(cmp)}, but it does`).bind(undefined, flat, cmp),
+                pass: compareTransaction(flattenTransaction(subject), cmp),
+                posMessage: ((subj: any, cmp: FlatTransactionComparable) => `Expected ${inspect(prettifyTransaction(subj))} to match pattern ${inspect(cmp)}`).bind(undefined, subject, cmp),
+                negMessage: ((subj: any, cmp: FlatTransactionComparable) => `Expected ${inspect(prettifyTransaction(subj))} NOT to match pattern ${inspect(cmp)}, but it does`).bind(undefined, subject, cmp),
             }
         } catch (e) {
             if (subject.transactions !== undefined) {

tsconfig.json

@@ -8,6 +8,7 @@
         "forceConsistentCasingInFileNames": true,
         "strict": true,
         "skipLibCheck": true,
+        "resolveJsonModule": true
     },
     "include": [
         "src/**/*"