@tonappchain/sdk 0.7.2-alpha-11 → 0.7.2-alpha-14

package/dist/src/sdk/TxFinalizer.js

@@ -1,140 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TonIndexerTxFinalizer = exports.TonTxFinalizer = void 0;
-const ton_1 = require("@ton/ton");
+exports.TonTxFinalizer = void 0;
 const errors_1 = require("../errors");
 const AxiosHttpClient_1 = require("./AxiosHttpClient");
 const Consts_1 = require("./Consts");
 const Logger_1 = require("./Logger");
 const Utils_1 = require("./Utils");
-const IGNORE_OPCODE = [
-    0xd53276db, // Excess
-];
 class TonTxFinalizer {
-    constructor(contractOpener, logger = new Logger_1.NoopLogger()) {
-        this.contractOpener = contractOpener;
-        this.logger = logger;
-    }
-    // Fetches adjacent transactions from toncenter
-    async fetchAdjacentTransactions(address, hash, retries = 5, delay = 1000, opts) {
-        for (let i = retries; i >= 0; i--) {
-            try {
-                const txs = await this.contractOpener.getAdjacentTransactions(address, hash, opts);
-                return txs;
-            }
-            catch (error) {
-                const errorMessage = error.message;
-                // Rate limit error (429) - retry
-                if (errorMessage.includes('429')) {
-                    if (i > 0) {
-                        await (0, Utils_1.sleep)(delay);
-                    }
-                    continue;
-                }
-                // Log all errors except 404 Not Found
-                if (!errorMessage.includes('404')) {
-                    const logMessage = error instanceof Error ? error.message : error;
-                    this.logger.warn(`Failed to fetch adjacent transactions for ${hash}:`, logMessage);
-                }
-                if (i > 0) {
-                    await (0, Utils_1.sleep)(delay);
-                }
-            }
-        }
-        return [];
-    }
-    // Checks if all transactions in the tree are successful
-    async trackTransactionTree(address, hash, params = { maxDepth: Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList: IGNORE_OPCODE }) {
-        const { maxDepth = Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList = IGNORE_OPCODE } = params;
-        const parsedAddress = ton_1.Address.parse(address);
-        const visitedHashes = new Set();
-        const queue = [{ address: parsedAddress, hash, depth: 0 }];
-        while (queue.length > 0) {
-            const { hash: currentHash, depth: currentDepth, address: currentAddress } = queue.shift();
-            if (visitedHashes.has(currentHash)) {
-                continue;
-            }
-            visitedHashes.add(currentHash);
-            this.logger.debug(`Checking hash (depth ${currentDepth}): ${currentHash}`);
-            const transactions = await this.fetchAdjacentTransactions(currentAddress, currentHash, 5, 1000, {
-                limit: 10,
-                archival: true,
-            });
-            this.logger.debug(`Found ${transactions.length} adjacent transactions for ${currentHash}`);
-            if (transactions.length === 0)
-                continue;
-            for (const tx of transactions) {
-                if (tx.description.type !== 'generic' || !tx.inMessage)
-                    continue;
-                if (tx.inMessage.info.type === 'internal' && tx.inMessage.info.value.coins === Consts_1.IGNORE_MSG_VALUE_1_NANO)
-                    continue; // we ignore messages with 1 nanoton value as they are for notification purpose only
-                const bodySlice = tx.inMessage.body.beginParse();
-                if (bodySlice.remainingBits < 32)
-                    continue;
-                const opcode = bodySlice.loadUint(32);
-                if (!ignoreOpcodeList.includes(opcode)) {
-                    const { aborted, computePhase, actionPhase } = tx.description;
-                    const failureCase = (() => {
-                        if (aborted) {
-                            return 'Transaction was aborted';
-                        }
-                        if (!computePhase) {
-                            return 'computePhase not present';
-                        }
-                        if (computePhase.type === 'skipped') {
-                            return 'computePhase was skipped';
-                        }
-                        if (!computePhase.success) {
-                            return 'computePhase not successful';
-                        }
-                        if (computePhase.exitCode !== 0) {
-                            return `computePhase.exitCode was not zero (exitCode=${computePhase.exitCode})`;
-                        }
-                        if (actionPhase && !actionPhase.success) {
-                            return 'actionPhase not successful';
-                        }
-                        if (actionPhase && actionPhase.resultCode !== 0) {
-                            return `actionPhase.resultCode was not zero (resultCode=${actionPhase.resultCode})`;
-                        }
-                        return null;
-                    })();
-                    if (failureCase) {
-                        throw (0, errors_1.txFinalizationError)(`${tx.hash().toString('base64')}: ${failureCase}`);
-                    }
-                    if (currentDepth + 1 < maxDepth) {
-                        if (tx.outMessages.size > 0) {
-                            queue.push({
-                                hash: tx.hash().toString('base64'),
-                                address: tx.inMessage.info.dest,
-                                depth: currentDepth + 1,
-                            });
-                        }
-                    }
-                }
-                else {
-                    this.logger.debug(`Skipping hash (depth ${currentDepth}): ${tx.hash().toString('base64')}`);
-                }
-            }
-            this.logger.debug(`Finished checking hash (depth ${currentDepth}): ${currentHash}`);
-        }
-    }
-}
-exports.TonTxFinalizer = TonTxFinalizer;
-class TonIndexerTxFinalizer {
     constructor(apiConfig, logger = new Logger_1.NoopLogger(), httpClient = new AxiosHttpClient_1.AxiosHttpClient()) {
         this.apiConfig = apiConfig;
         this.logger = logger;
         this.httpClient = httpClient;
     }
     // Fetches adjacent transactions from toncenter
-    async fetchAdjacentTransactions(hash, retries = 5, delay = 1000) {
+    async fetchAdjacentTransactions(hash, retries = Consts_1.DEFAULT_RETRY_MAX_COUNT, delay = Consts_1.DEFAULT_RETRY_DELAY_MS) {
         for (let i = retries; i >= 0; i--) {
             try {
                 const url = this.apiConfig.urlBuilder(hash);
+                const authHeaders = this.apiConfig.authorization
+                    ? { [this.apiConfig.authorization.header]: this.apiConfig.authorization.value }
+                    : undefined;
                 const response = await this.httpClient.get(url, {
-                    headers: {
-                        [this.apiConfig.authorization.header]: this.apiConfig.authorization.value,
-                    },
+                    ...(authHeaders ? { headers: authHeaders } : {}),
                     transformResponse: [Utils_1.toCamelCaseTransformer],
                 });
                 return response.data.transactions || [];
@@ -161,8 +48,8 @@ class TonIndexerTxFinalizer {
         return [];
     }
     // Checks if all transactions in the tree are successful
-    async trackTransactionTree(_, hash, params = { maxDepth: Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList: IGNORE_OPCODE }) {
-        const { maxDepth = Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList = IGNORE_OPCODE } = params;
+    async trackTransactionTree(_, hash, params = { maxDepth: Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList: Consts_1.IGNORE_OPCODE }) {
+        const { maxDepth = Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList = Consts_1.IGNORE_OPCODE } = params;
         const visitedHashes = new Set();
         const queue = [{ hash, depth: 0 }];
         while (queue.length > 0) {
@@ -191,18 +78,20 @@ class TonIndexerTxFinalizer {
                             return 'computePh not successful';
                         }
                         if (computePh.exitCode !== 0) {
-                            return `computePh.exitCode was not zero (exitCode=${computePh.exitCode})`;
+                            return `computePh.exitCode was not zero`;
                         }
                         if (action && !action.success) {
                             return 'action not successful';
                         }
                         if (action && action.resultCode !== 0) {
-                            return `action.resultCode was not zero (resultCode=${action.resultCode})`;
+                            return `action.resultCode was not zero`;
                         }
                         return null;
                     })();
                     if (failureCase) {
-                        throw (0, errors_1.txFinalizationError)(`${tx.hash}: ${failureCase}`);
+                        const exitCode = computePh ? computePh.exitCode : 'N/A';
+                        const resultCode = action ? action.resultCode : 'N/A';
+                        throw (0, errors_1.txFinalizationError)(`${tx.hash}: ${failureCase} (exitCode=${exitCode}, resultCode=${resultCode})`);
                     }
                     if (currentDepth + 1 < maxDepth) {
                         if (tx.outMsgs.length > 0) {
@@ -217,4 +106,4 @@ class TonIndexerTxFinalizer {
         }
     }
 }
-exports.TonIndexerTxFinalizer = TonIndexerTxFinalizer;
+exports.TonTxFinalizer = TonTxFinalizer;

package/dist/src/sdk/Utils.d.ts

@@ -37,6 +37,16 @@ export declare function getString(cell?: Cell): string;
  * Calculates (a * b + c / 2) / c with proper rounding
  */
 export declare function muldivr(a: bigint, b: bigint, c: bigint): bigint;
+/**
+ * Normalize hash string to base64 format
+ * Accepts: base64, hex, or raw string
+ */
+export declare function normalizeHashToBase64(hash: string): string;
+/**
+ * Normalize hash string to hex format
+ * Accepts: base64, hex
+ */
+export declare function normalizeHashToHex(hash: string): string;
 export declare function getNormalizedExtMessageHash(message: Message): string;
 export declare function retry<T>(fn: () => Promise<T>, options: {
     retries: number;

package/dist/src/sdk/Utils.js

@@ -20,6 +20,8 @@ exports.getAddressString = getAddressString;
 exports.getNumber = getNumber;
 exports.getString = getString;
 exports.muldivr = muldivr;
+exports.normalizeHashToBase64 = normalizeHashToBase64;
+exports.normalizeHashToHex = normalizeHashToHex;
 exports.getNormalizedExtMessageHash = getNormalizedExtMessageHash;
 exports.retry = retry;
 exports.recurisivelyCollectCellStats = recurisivelyCollectCellStats;
@@ -316,6 +318,57 @@ function muldivr(a, b, c) {
     }
     return (a * b + c / 2n) / c;
 }
+/**
+ * Normalize hash string to base64 format
+ * Accepts: base64, hex, or raw string
+ */
+function normalizeHashToBase64(hash) {
+    const input = hash.trim();
+    if (!input)
+        return input;
+    const hex = input.startsWith('0x') ? input.slice(2) : input;
+    if (/^[0-9a-fA-F]{64}$/.test(hex)) {
+        return Buffer.from(hex, 'hex').toString('base64');
+    }
+    const decoded = decodeBase64Like(input);
+    if (decoded) {
+        return decoded.toString('base64');
+    }
+    return input;
+}
+/**
+ * Normalize hash string to hex format
+ * Accepts: base64, hex
+ */
+function normalizeHashToHex(hash) {
+    const input = hash.trim();
+    if (!input)
+        return input;
+    const maybeHex = input.startsWith('0x') ? input.slice(2) : input;
+    if (/^[0-9a-fA-F]+$/.test(maybeHex) && maybeHex.length % 2 === 0) {
+        return maybeHex.toLowerCase();
+    }
+    const decoded = decodeBase64Like(input);
+    if (decoded) {
+        return decoded.toString('hex');
+    }
+    return input;
+}
+function decodeBase64Like(input) {
+    const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+    const padLength = normalized.length % 4;
+    const padded = padLength === 0 ? normalized : normalized + '='.repeat(4 - padLength);
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(padded)) {
+        return null;
+    }
+    try {
+        const buf = Buffer.from(padded, 'base64');
+        return buf.length > 0 ? buf : null;
+    }
+    catch {
+        return null;
+    }
+}
 function getNormalizedExtMessageHash(message) {
     if (message.info.type !== 'external-in') {
         throw new Error(`Message must be "external-in", got ${message.info.type}`);

package/dist/src/structs/InternalStruct.d.ts

@@ -99,13 +99,14 @@ export type TransactionDepth = {
     address?: Address;
     hash: string;
     depth: number;
+    hashType?: 'unknown' | 'in' | 'out';
 };
 export type AdjacentTransactionsResponse = {
     transactions: ToncenterTransaction[];
 };
 export type TxFinalizerConfig = {
     urlBuilder: (hash: string) => string;
-    authorization: {
+    authorization?: {
         header: string;
         value: string;
     };
@@ -123,22 +124,6 @@ export type ConvertedCurrencyRawResult = {
     tacPrice: USDPriceInfoRaw;
     tonPrice: USDPriceInfoRaw;
 };
-export type GetTransactionsOptions = {
-    limit: number;
-    lt?: string;
-    hash?: string;
-    to_lt?: string;
-    inclusive?: boolean;
-    archival?: boolean;
-    timeoutMs?: number;
-    retryDelayMs?: number;
-};
-export type AddressInformation = {
-    lastTransaction: {
-        lt: string;
-        hash: string;
-    };
-};
 export type TONFeesParams = {
     accountBitPrice: number;
     accountCellPrice: number;

package/dist/src/structs/Struct.d.ts

@@ -4,7 +4,6 @@ import { AbstractProvider } from 'ethers';
 import { JettonMinter, JettonMinterData } from '../../artifacts/tonTypes';
 import type { FT, NFT } from '../assets';
 import type { Asset, ContractOpener, ILogger } from '../interfaces';
-import { ITxFinalizer } from '../interfaces/ITxFinalizer';
 import { SendResult } from './InternalStruct';
 export type ContractState = {
     balance: bigint;
@@ -61,10 +60,6 @@ export type TONParams = {
      * Address of TON settings contract. Use only for tests.
      */
     settingsAddress?: string;
-    /**
-     * TxFinalizer for tracking transaction tree
-     */
-    txFinalizer?: ITxFinalizer;
 };
 export type SDKParams = {
     /**
@@ -451,7 +446,124 @@ export type TacGasPrice = {
     fast: number;
     slow: number;
 };
+/**
+ * Parameters for tracking and validating transaction trees
+ */
 export type TrackTransactionTreeParams = {
+    /**
+     * Maximum number of transactions to fetch per pagination request
+     * @default 100
+     */
+    limit?: number;
+    /**
+     * Maximum depth to traverse in the transaction tree, inclusive (prevents infinite loops)
+     * @default 10
+     */
     maxDepth?: number;
+    /**
+     * Maximum number of transactions to scan while searching by hash in account history.
+     * Prevents excessive full-history scans on high-activity accounts.
+     * @default 100
+     */
+    maxScannedTransactions?: number;
+    /**
+     * List of operation codes (opcodes) to skip for extra checks.
+     * Core phase validation is still applied.
+     * @default [ 0xd53276db ] // Excess
+     */
     ignoreOpcodeList?: number[];
+    /**
+     * Direction to search the transaction tree:
+     * - 'forward': only search children (outgoing messages)
+     * - 'backward': only search parents (incoming messages)
+     * - 'both': search in both directions (default)
+     * @default 'both'
+     */
+    direction?: 'forward' | 'backward' | 'both';
+    /**
+     * Internal option: wait for the root transaction to appear before failing with `not_found`.
+     * Useful right after sending a message when transaction indexing is eventually consistent.
+     * @default true
+     */
+    waitForRootTransaction?: boolean;
+};
+/**
+ * Details about a transaction validation error
+ */
+export type TransactionValidationError = {
+    /**
+     * Base64-encoded hash of the failed transaction (or the searched hash if not found)
+     */
+    txHash: string;
+    /**
+     * Exit code from the compute phase, or 'N/A' if compute phase is missing
+     */
+    exitCode: number | 'N/A';
+    /**
+     * Result code from the action phase, or 'N/A' if action phase is missing
+     */
+    resultCode: number | 'N/A';
+    /**
+     * Reason for validation failure:
+     * - 'aborted': default: transaction was aborted
+     * - 'compute_phase_missing': compute phase is missing
+     * - 'compute_phase_failed': compute phase failed (exitCode !== 0)
+     * - 'action_phase_failed': action phase failed (resultCode !== 0)
+     * - 'not_found': transaction or message hash not found during traversal
+     */
+    reason: 'aborted' | 'compute_phase_missing' | 'compute_phase_failed' | 'action_phase_failed' | 'not_found';
+    /**
+     * Address where the lookup was performed (for reason: 'not_found')
+     */
+    address?: string;
+    /**
+     * Hash type used in lookup (for reason: 'not_found')
+     */
+    hashType?: 'unknown' | 'in' | 'out';
+};
+/**
+ * Result of transaction tree tracking and validation
+ */
+export type TrackTransactionTreeResult = {
+    /**
+     * Whether all transactions in the tree passed validation
+     */
+    success: boolean;
+    /**
+     * Count of unique transactions checked during traversal
+     */
+    checkedCount?: number;
+    /**
+     * Details about the first validation error encountered (if any)
+     */
+    error?: TransactionValidationError;
+};
+export type GetTransactionsOptions = {
+    /** Maximum number of transactions to retrieve */
+    limit?: number;
+    /** Logical time of the transaction to start from */
+    lt?: string;
+    /** Hash of the transaction to start from */
+    hash?: string;
+    /** Logical time of the transaction to end at */
+    to_lt?: string;
+    /** Whether to include the starting transaction in the results */
+    inclusive?: boolean;
+    /** Whether to search in archival nodes for historical data */
+    archival?: boolean;
+    /** Request timeout in milliseconds */
+    timeoutMs?: number;
+    /** Delay between retry attempts in milliseconds */
+    retryDelayMs?: number;
+    /** Internal scan guard: maximum transactions to inspect while traversing history */
+    maxScannedTransactions?: number;
+};
+export type AddressInformation = {
+    /** Information about the last transaction of the address */
+    lastTransaction: {
+        /** Logical time of the last transaction */
+        lt: string;
+        /** Hash of the last transaction */
+        hash: string;
+    };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tonappchain/sdk",
-    "version": "0.7.2-alpha-11",
+    "version": "0.7.2-alpha-14",
     "repository": "https://github.com/TacBuild/tac-sdk.git",
     "author": "TAC. <developers@tac>",
     "license": "MIT",

package/dist/src/adapters/contractOpener.d.ts

@@ -1,24 +0,0 @@
-import { Blockchain } from '@ton/sandbox';
-import { Address, TonClient, Transaction } from '@ton/ton';
-import { ContractOpener } from '../interfaces';
-import { GetTransactionsOptions } from '../structs/InternalStruct';
-import { Network } from '../structs/Struct';
-export declare function getAdjacentTransactionsHelper(addr: Address, hashB64: string, getTransactions: (addr: Address, opts: GetTransactionsOptions) => Promise<Transaction[]>, opts?: GetTransactionsOptions): Promise<Transaction[]>;
-type LiteServer = {
-    ip: number;
-    port: number;
-    id: {
-        '@type': string;
-        key: string;
-    };
-};
-export declare function liteClientOpener(options: {
-    liteservers: LiteServer[];
-} | {
-    network: Network;
-}): Promise<ContractOpener>;
-export declare function sandboxOpener(blockchain: Blockchain): ContractOpener;
-export declare function orbsOpener(network: Network): Promise<ContractOpener>;
-export declare function orbsOpener4(network: Network, timeout?: number): Promise<ContractOpener>;
-export declare function tonClientOpener(client: TonClient): ContractOpener;
-export {};