feat: support tracing transaction with base info triple (#6)

Author: i582

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-05-16
+
+Add `retraceBaseTx` function to retrace transactions by their triple (`lt`, `hash`, `address`).
+
+## [0.0.1] - 2025-05-10
+
+Initial release

README.md

@@ -40,7 +40,16 @@ import {retrace} from "@tonstudio/txtracer-core"
  * @param txHash - hex transaction hash
  * @returns Detailed execution report (TraceResult)
  */
-const result = await retrace(testnet, txHash)
+const result1 = await retrace(testnet, txHash)
+
+/**
+ * Retrace transaction described as triple
+ */
+const result2 = await retraceBaseTx(testnet, {
+    lt: 56166043000001n,
+    hash: Buffer.from("T6Y6ZoW71mrznFA0RyU/xV5ILpz9WUPJ9i9/4xPq1Is=", "base64"),
+    address: Address.parse("EQCqKZrrce8Ss6SZaLI-OkH2w8-xtPP9_ZvyyIZLhy9Hmpf8"),
+})
 ```
 
 ### Helper Methods

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tonstudio/txtracer-core",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "description": "Core TxTracer library for collecting transaction information",
     "main": "dist/index.js",
     "scripts": {

src/runner.ts

@@ -1,5 +1,6 @@
 import {TraceResult} from "./types"
 import {
+    BaseTxInfo,
     collectUsedLibraries,
     computeFinalData,
     computeMinLt,
@@ -54,6 +55,17 @@ export const retrace = async (testnet: boolean, txLink: string): Promise<TraceRe
     if (baseTx === undefined) {
         throw new Error("Cannot find transaction info")
     }
+    return retraceBaseTx(testnet, baseTx)
+}
+
+/**
+ * Fully reproduce (re‑trace) a TON transaction inside a local TON Sandbox
+ * and return a structured report with VM logs, money flow, generated
+ * actions and other data.
+ *
+ * See {@link retrace} for the full description of the workflow.
+ */
+export const retraceBaseTx = async (testnet: boolean, baseTx: BaseTxInfo): Promise<TraceResult> => {
     const [tx] = await findRawTxByHash(testnet, baseTx)
     // eslint bug
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition

src/test/__snapshots__/test.spec.ts.snap

@@ -1,5 +1,46 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`transactions should return correct information for base transaction 1`] = `"b5ee9c7241021401000281000114ff00f4a413f4bcf2c80b01020120020d020148030402dcd020d749c120915b8f6320d70b1f2082106578746ebd21821073696e74bdb0925f03e082106578746eba8eb48020d72101d074d721fa4030fa44f828fa443058bd915be0ed44d0810141d721f4058307f40e6fa1319130e18040d721707fdb3ce03120d749810280b99130e070e2100f020120050c020120060902016e07080019adce76a2684020eb90eb85ffc00019af1df6a2684010eb90eb858fc00201480a0b0017b325fb51341c75c875c2c7e00011b262fb513435c280200019be5f0f6a2684080a0eb90fa02c0102f20e011e20d70b1f82107369676ebaf2e08a7f0f01e68ef0eda2edfb218308d722028308d723208020d721d31fd31fd31fed44d0d200d31f20d31fd3ffd70a000af90140ccf9109a28945f0adb31e1f2c087df02b35007b0f2d0845125baf2e0855036baf2e086f823bbf2d0882292f800de01a47fc8ca00cb1f01cf16c9ed542092f80fde70db3cd81003f6eda2edfb02f404216e926c218e4c0221d73930709421c700b38e2d01d72820761e436c20d749c008f2e09320d74ac002f2e09320d71d06c712c2005230b0f2d089d74cd7393001a4e86c128407bbf2e093d74ac000f2e093ed55e2d20001c000915be0ebd72c08142091709601d72c081c12e25210b1e30f20d74a111213009601fa4001fa44f828fa443058baf2e091ed44d0810141d718f405049d7fc8ca0040048307f453f2e08b8e14038307f45bf2e08c22d70a00216e01b3b0f2d090e2c85003cf1612f400c9ed54007230d72c08248e2d21f2e092d200ed44d0d2005113baf2d08f54503091319c01810140d721d70a00f2e08ee2c8ca0058cf16c9ed5493f2c08de20010935bdb31e1d74cd0b4d6c35e"`;
+
+exports[`transactions should return correct information for base transaction 2`] = `"b5ee9c7241021401000281000114ff00f4a413f4bcf2c80b01020120020d020148030402dcd020d749c120915b8f6320d70b1f2082106578746ebd21821073696e74bdb0925f03e082106578746eba8eb48020d72101d074d721fa4030fa44f828fa443058bd915be0ed44d0810141d721f4058307f40e6fa1319130e18040d721707fdb3ce03120d749810280b99130e070e2100f020120050c020120060902016e07080019adce76a2684020eb90eb85ffc00019af1df6a2684010eb90eb858fc00201480a0b0017b325fb51341c75c875c2c7e00011b262fb513435c280200019be5f0f6a2684080a0eb90fa02c0102f20e011e20d70b1f82107369676ebaf2e08a7f0f01e68ef0eda2edfb218308d722028308d723208020d721d31fd31fd31fed44d0d200d31f20d31fd3ffd70a000af90140ccf9109a28945f0adb31e1f2c087df02b35007b0f2d0845125baf2e0855036baf2e086f823bbf2d0882292f800de01a47fc8ca00cb1f01cf16c9ed542092f80fde70db3cd81003f6eda2edfb02f404216e926c218e4c0221d73930709421c700b38e2d01d72820761e436c20d749c008f2e09320d74ac002f2e09320d71d06c712c2005230b0f2d089d74cd7393001a4e86c128407bbf2e093d74ac000f2e093ed55e2d20001c000915be0ebd72c08142091709601d72c081c12e25210b1e30f20d74a111213009601fa4001fa44f828fa443058baf2e091ed44d0810141d718f405049d7fc8ca0040048307f453f2e08b8e14038307f45bf2e08c22d70a00216e01b3b0f2d090e2c85003cf1612f400c9ed54007230d72c08248e2d21f2e092d200ed44d0d2005113baf2d08f54503091319c01810140d721d70a00f2e08ee2c8ca0058cf16c9ed5493f2c08de20010935bdb31e1d74cd0b4d6c35e"`;
+
+exports[`transactions should return correct information for base transaction 3`] = `undefined`;
+
+exports[`transactions should return correct information for base transaction 4`] = `"EQCqKZrrce8Ss6SZaLI-OkH2w8-xtPP9_ZvyyIZLhy9Hmpf8"`;
+
+exports[`transactions should return correct information for base transaction 5`] = `undefined`;
+
+exports[`transactions should return correct information for base transaction 6`] = `56166043000001n`;
+
+exports[`transactions should return correct information for base transaction 7`] = `1744898820`;
+
+exports[`transactions should return correct information for base transaction 8`] = `
+{
+  "exitCode": 0,
+  "gasFees": 1975600n,
+  "gasUsed": 4939n,
+  "success": true,
+  "vmSteps": 143,
+}
+`;
+
+exports[`transactions should return correct information for base transaction 9`] = `
+"x{0EC3C86D03}
+ x{}
+ x{62004729ACCB84DBCE80E1C7063E54BC94896318DF88EEC4080C5BDB47E0E2F716DC2017D7840000000000000000000000000001}
+  x{0F8A7EA5546DE4EF7EB185CE3989680800891E15DA14405903E5C99092ACC3BB1DC7F00C6C3B707868EE97885F944FB77F002A8A66BADC7BC4ACE9265A2C8F8E907DB0F3EC6D3CFF7F66FCB22192E1CBD1E68203}
+   x{0000000057656C636F6D65204368616C6C656E6765205072697A652E20436F6E67726174756C6174696F6E7320F09F8E89}"
+`;
+
+exports[`transactions should return correct information for base transaction 10`] = `
+{
+  "balanceAfter": 328324326n,
+  "balanceBefore": 382413532n,
+  "sentTotal": 50000000n,
+  "totalFees": 3485468n,
+}
+`;
+
 exports[`transactions should return correct information for simple transaction with exit code 0 1`] = `"b5ee9c724101010100710000deff0020dd2082014c97ba218201339cbab19f71b0ed44d0d31fd31f31d70bffe304e0a4f2608308d71820d31fd31fd31ff82313bbf263ed44d0d31fd31fd3ffd15132baf2a15144baf2a204f901541055f910f2a3f8009320d74a96d307d402fb00e8d101a4c8cb1fcb1fcbffc9ed5410bd6dad"`;
 
 exports[`transactions should return correct information for simple transaction with exit code 0 2`] = `"b5ee9c724101010100710000deff0020dd2082014c97ba218201339cbab19f71b0ed44d0d31fd31f31d70bffe304e0a4f2608308d71820d31fd31fd31ff82313bbf263ed44d0d31fd31fd3ffd15132baf2a15144baf2a204f901541055f910f2a3f8009320d74a96d307d402fb00e8d101a4c8cb1fcb1fcbffc9ed5410bd6dad"`;

src/test/test.spec.ts

@@ -1,5 +1,7 @@
-import {retrace} from "../runner"
+import {retrace, retraceBaseTx} from "../runner"
 import {TraceResult} from "../types"
+import {Buffer} from "buffer"
+import {Address} from "@ton/core"
 
 const DEFAULT_TIMEOUT = 100_000
 const DELAY_FOR_RATE_LIMIT = process.env["CI"] === undefined ? 5000 : 10_000
@@ -116,6 +118,23 @@ describe("transactions", () => {
         DEFAULT_TIMEOUT,
     )
 
+    it(
+        "should return correct information for base transaction",
+        async () => {
+            await wait()
+
+            const testnet = false
+
+            const res = await retraceBaseTx(testnet, {
+                lt: 56_166_043_000_001n,
+                hash: Buffer.from("T6Y6ZoW71mrznFA0RyU/xV5ILpz9WUPJ9i9/4xPq1Is=", "base64"),
+                address: Address.parse("EQCqKZrrce8Ss6SZaLI-OkH2w8-xtPP9_ZvyyIZLhy9Hmpf8"),
+            })
+            checkResult(res)
+        },
+        DEFAULT_TIMEOUT,
+    )
+
     function checkResult(res: TraceResult, expectedOk: boolean = true): void {
         expect(res.stateUpdateHashOk).toEqual(expectedOk)
         expect(res.codeCell?.toBoc().toString("hex")).toMatchSnapshot()