@tonappchain/sdk 0.7.3-rc6 → 0.7.3-rc8

package/README.md

@@ -67,9 +67,6 @@ The TAC SDK enables you to create frontends that:
   - [`TonConnectSender`](./docs/sdks/sender.md#tonconnectsender): Implements sending via TonConnect UI.
   - [`RawSender`](./docs/sdks/sender.md#rawsender): Implements sending using a raw private key.
 
-- **[`Utilities`](./docs/sdks/utilities.md)**: Helper functions and interfaces.
-  - [`startTracking`](./docs/sdks/utilities.md#starttracking): Utility function to poll and log operation status to the console.
-
 - **[`AgnosticSdk`](./docs/sdks/agnostic_proxy_sdk.md)**: Agnostic SDK for cross-chain interactions.
 
 - **[`Simulator`](./docs/sdks/simulator.md)**: Transaction simulation capabilities.

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

@@ -1,8 +1,9 @@
 import { SandboxContract } from '@ton/sandbox';
+import type { Message } from '@ton/ton';
 import { Address, Contract, OpenedContract, Transaction } from '@ton/ton';
 import { ContractOpener, ILogger } from '../interfaces';
 import { AddressInformation, GetTransactionsOptions } from '../structs/Struct';
-import { ContractState, TrackTransactionTreeParams, TrackTransactionTreeResult } from '../structs/Struct';
+import { ContractState, TrackTransactionTreeParams, TrackTransactionTreeResult, TransactionValidationError } from '../structs/Struct';
 /**
  * Base class for ContractOpener implementations with common functionality
  */
@@ -56,15 +57,15 @@ export declare abstract class BaseContractOpener implements ContractOpener {
     /**
      * Validate transaction phases and return error details
      */
-    private validateTransactionWithResult;
+    protected validateTransactionWithResult(tx: Transaction, ignoreOpcodeList: number[]): TransactionValidationError | null;
     /**
      * Find transaction by hash type
      */
-    private findTransactionByHashType;
+    protected findTransactionByHashType(address: Address, hash: string, hashType: 'unknown' | 'in' | 'out' | undefined, opts: GetTransactionsOptions, message?: Message): Promise<Transaction | null>;
     /**
      * Find transaction with retry logic
      */
-    private findTransactionWithRetry;
+    protected findTransactionWithRetry(address: Address, hash: string, hashType: 'unknown' | 'in' | 'out' | undefined, opts: GetTransactionsOptions, depth: number, message?: Message): Promise<Transaction | null>;
     /**
      * Track transaction tree and validate all transactions
      */

package/dist/src/adapters/BaseContractOpener.js

@@ -27,24 +27,33 @@ class BaseContractOpener {
      */
     async scanTransactionHistory(addr, opts, predicate) {
         const limit = opts?.limit ?? Consts_1.DEFAULT_FIND_TX_LIMIT;
-        const inclusive = opts?.inclusive ?? true;
+        const toLtInclusive = opts?.inclusive ?? true;
         const toLt = opts?.to_lt ? BigInt(opts.to_lt) : undefined;
         let currentLt = opts?.lt;
         let currentHash = opts?.hash ? (0, Utils_1.normalizeHashToBase64)(opts.hash) : undefined;
-        const seenCursors = new Set();
+        let requestInclusive = toLtInclusive;
+        const seenRequests = new Set();
         let scannedTransactions = 0;
         const maxScannedTransactions = opts?.maxScannedTransactions ?? Consts_1.DEFAULT_MAX_SCANNED_TRANSACTIONS;
         while (true) {
-            const list = await this.getTransactions(addr, {
+            const requestKey = `${currentLt ?? ''}:${currentHash ?? ''}:${requestInclusive}`;
+            if (seenRequests.has(requestKey)) {
+                break;
+            }
+            seenRequests.add(requestKey);
+            const requestOpts = {
                 limit,
                 lt: currentLt,
                 hash: currentHash,
                 to_lt: opts?.to_lt,
-                inclusive,
-                archival: opts?.archival ?? Consts_1.DEFAULT_FIND_TX_ARCHIVAL,
+                inclusive: requestInclusive,
                 timeoutMs: opts?.timeoutMs,
                 retryDelayMs: opts?.retryDelayMs,
-            });
+            };
+            if (opts?.archival !== undefined) {
+                requestOpts.archival = opts.archival;
+            }
+            const list = await this.getTransactions(addr, requestOpts);
             if (list.length === 0) {
                 break;
             }
@@ -54,7 +63,7 @@ class BaseContractOpener {
                 currentHash &&
                 firstTx.lt.toString() === currentLt &&
                 firstTx.hash().toString('base64') === currentHash;
-            if (firstTxMatchesCursor) {
+            if (firstTxMatchesCursor && !requestInclusive) {
                 startIndex = 1;
                 if (list.length === 1) {
                     if (firstTx.prevTransactionLt === 0n) {
@@ -65,13 +74,9 @@ class BaseContractOpener {
                     if (currentLt && BigInt(nextLt) >= BigInt(currentLt)) {
                         break;
                     }
-                    const cursorKey = `${nextLt}:${nextHash}`;
-                    if (seenCursors.has(cursorKey)) {
-                        break;
-                    }
-                    seenCursors.add(cursorKey);
                     currentLt = nextLt;
                     currentHash = nextHash;
+                    requestInclusive = true;
                     continue;
                 }
             }
@@ -90,21 +95,17 @@ class BaseContractOpener {
             if (oldestTx.prevTransactionLt === 0n)
                 break;
             if (toLt !== undefined) {
-                if (inclusive ? oldestTx.lt <= toLt : oldestTx.lt < toLt)
+                if (toLtInclusive ? oldestTx.lt <= toLt : oldestTx.lt < toLt)
                     break;
             }
             const nextLt = oldestTx.lt.toString();
             const nextHash = oldestTx.hash().toString('base64');
-            if (currentLt && BigInt(nextLt) >= BigInt(currentLt)) {
+            if (currentLt && currentHash && nextLt === currentLt && nextHash === currentHash && !requestInclusive) {
                 break;
             }
-            const cursorKey = `${nextLt}:${nextHash}`;
-            if (seenCursors.has(cursorKey)) {
-                break;
-            }
-            seenCursors.add(cursorKey);
             currentLt = nextLt;
             currentHash = nextHash;
+            requestInclusive = false;
         }
         return null;
     }
@@ -281,37 +282,31 @@ class BaseContractOpener {
     /**
      * Find transaction by hash type
      */
-    async findTransactionByHashType(address, hash, hashType, opts) {
-        const searchOpts = { archival: true, ...opts };
+    async findTransactionByHashType(address, hash, hashType, opts, message) {
+        const targetHash = message ? (0, ton_1.beginCell)().store((0, ton_1.storeMessage)(message)).endCell().hash().toString('base64') : hash;
         if (hashType === 'in') {
-            return this.getTransactionByInMsgHash(address, hash, searchOpts);
+            return this.getTransactionByInMsgHash(address, targetHash, opts);
         }
         else if (hashType === 'out') {
-            return this.getTransactionByOutMsgHash(address, hash, searchOpts);
+            return this.getTransactionByOutMsgHash(address, targetHash, opts);
         }
         else {
-            return this.getTransactionByHash(address, hash, searchOpts);
+            return this.getTransactionByHash(address, targetHash, opts);
         }
     }
     /**
      * Find transaction with retry logic
      */
-    async findTransactionWithRetry(address, hash, hashType, opts, depth) {
+    async findTransactionWithRetry(address, hash, hashType, opts, depth, message) {
         const retryDelayMs = opts.retryDelayMs ?? Consts_1.DEFAULT_RETRY_ON_NOT_FOUND_DELAY_MS;
         const maxRetries = opts.retries ?? Consts_1.DEFAULT_RETRY_ON_NOT_FOUND_RETRIES;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
-            let errorMsg;
-            try {
-                const tx = await this.findTransactionByHashType(address, hash, hashType, opts);
-                if (tx) {
-                    return tx;
-                }
-            }
-            catch (error) {
-                errorMsg = error instanceof Error ? error.message : String(error);
+            const tx = await this.findTransactionByHashType(address, hash, hashType, opts, message);
+            if (tx) {
+                return tx;
             }
             const isLastAttempt = attempt >= maxRetries;
-            const reason = errorMsg ?? 'not found';
+            const reason = 'not found';
             const retryInfo = isLastAttempt ? '' : `, retrying in ${retryDelayMs}ms`;
             this.logger?.debug(`Transaction not found at depth ${depth} (attempt ${attempt + 1}/${maxRetries + 1}): ${reason}${retryInfo}`);
             if (isLastAttempt) {
@@ -357,7 +352,7 @@ class BaseContractOpener {
         direction: Struct_1.TransactionTreeDirection.FORWARD,
         retryOnNotFound: Consts_1.DEFAULT_RETRY_ON_NOT_FOUND,
     }) {
-        const { maxDepth = Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList = Consts_1.IGNORE_OPCODE, limit = Consts_1.DEFAULT_FIND_TX_LIMIT, maxScannedTransactions = Consts_1.DEFAULT_MAX_SCANNED_TRANSACTIONS, direction = Struct_1.TransactionTreeDirection.FORWARD, retryOnNotFound = Consts_1.DEFAULT_RETRY_ON_NOT_FOUND, retryDelayMs, retries, } = params;
+        const { maxDepth = Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, ignoreOpcodeList = Consts_1.IGNORE_OPCODE, limit = Consts_1.DEFAULT_FIND_TX_LIMIT, maxScannedTransactions = Consts_1.DEFAULT_MAX_SCANNED_TRANSACTIONS, archival, rootLt, direction = Struct_1.TransactionTreeDirection.FORWARD, retryOnNotFound = Consts_1.DEFAULT_RETRY_ON_NOT_FOUND, retryDelayMs, retries, } = params;
         const parsedAddress = ton_1.Address.parse(address);
         const normalizedRootHash = (0, Utils_1.normalizeHashToBase64)(hash);
         const visitedSearchKeys = new Set();
@@ -365,25 +360,30 @@ class BaseContractOpener {
         let checkedCount = 0;
         const searchOpts = {
             limit,
-            archival: true,
             maxScannedTransactions,
             retryDelayMs,
             retries,
         };
+        if (archival !== undefined) {
+            searchOpts.archival = archival;
+        }
         const queue = [
             { address: parsedAddress, hash: normalizedRootHash, depth: 0, hashType: 'unknown' },
         ];
         while (queue.length > 0) {
-            const { hash: currentHash, depth: currentDepth, address: currentAddress, hashType } = queue.shift();
+            const { hash: currentHash, depth: currentDepth, address: currentAddress, hashType, message, } = queue.shift();
             const visitedKey = `${currentAddress.toString()}:${currentHash}:${hashType}`;
             if (visitedSearchKeys.has(visitedKey))
                 continue;
             visitedSearchKeys.add(visitedKey);
+            const currentSearchOpts = currentDepth === 0 && hashType === 'unknown' && rootLt
+                ? { ...searchOpts, lt: rootLt, hash: currentHash, inclusive: true }
+                : searchOpts;
             const tx = retryOnNotFound
-                ? await this.findTransactionWithRetry(currentAddress, currentHash, hashType, searchOpts, currentDepth)
-                : await this.findTransactionByHashType(currentAddress, currentHash, hashType, searchOpts);
+                ? await this.findTransactionWithRetry(currentAddress, currentHash, hashType, currentSearchOpts, currentDepth, message)
+                : await this.findTransactionByHashType(currentAddress, currentHash, hashType, currentSearchOpts, message);
             if (!tx) {
-                this.logger?.debug(`Transaction not found for hash: ${currentHash} (address=${currentAddress?.toString()}, hashType=${hashType ?? 'unknown'})`);
+                this.logger?.debug(`Transaction not found for hash: ${currentHash} (address=${currentAddress.toString()}, hashType=${hashType})`);
                 return {
                     success: false,
                     checkedCount,
@@ -392,8 +392,8 @@ class BaseContractOpener {
                         exitCode: 'N/A',
                         resultCode: 'N/A',
                         reason: 'not_found',
-                        address: currentAddress?.toString(),
-                        hashType: hashType ?? 'unknown',
+                        address: currentAddress.toString(),
+                        hashType,
                     },
                 };
             }
@@ -422,6 +422,7 @@ class BaseContractOpener {
                             address: dst,
                             depth: currentDepth + 1,
                             hashType: 'in',
+                            message: msg,
                         });
                     }
                 }
@@ -433,6 +434,7 @@ class BaseContractOpener {
                         address: tx.inMessage.info.src,
                         depth: currentDepth + 1,
                         hashType: 'out',
+                        message: tx.inMessage,
                     });
                 }
             }

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

@@ -42,4 +42,4 @@ export declare class RetryableContractOpener implements ContractOpener {
     private createRetryableContract;
     private callMethodAcrossOpeners;
 }
-export declare function createDefaultRetryableOpener(tonRpcEndpoint: string, networkType: Network, maxRetries?: number, retryDelay?: number, logger?: ILogger): Promise<RetryableContractOpener>;
+export declare function createDefaultRetryableOpener(tonRpcEndpoint: string, networkType: Network, maxRetries?: number, retryDelay?: number, logger?: ILogger, toncenterV3Endpoint?: string): Promise<RetryableContractOpener>;

package/dist/src/adapters/RetryableContractOpener.js

@@ -7,6 +7,8 @@ const errors_1 = require("../errors");
 const instances_1 = require("../errors/instances");
 const Consts_1 = require("../sdk/Consts");
 const Struct_1 = require("../structs/Struct");
+const ToncenterV3Indexer_1 = require("./ToncenterV3Indexer");
+const ToncenterV3Opener_1 = require("./ToncenterV3Opener");
 const TonClient4Opener_1 = require("./TonClient4Opener");
 const TonClientOpener_1 = require("./TonClientOpener");
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -271,12 +273,21 @@ class RetryableContractOpener {
     }
 }
 exports.RetryableContractOpener = RetryableContractOpener;
-async function createDefaultRetryableOpener(tonRpcEndpoint, networkType, maxRetries = Consts_1.DEFAULT_RETRY_MAX_COUNT, retryDelay = Consts_1.DEFAULT_RETRY_DELAY_MS, logger) {
+async function createDefaultRetryableOpener(tonRpcEndpoint, networkType, maxRetries = Consts_1.DEFAULT_RETRY_MAX_COUNT, retryDelay = Consts_1.DEFAULT_RETRY_DELAY_MS, logger, toncenterV3Endpoint) {
     const openers = [];
     const tonClient = new ton_1.TonClient({
         endpoint: new URL('api/v2/jsonRPC', tonRpcEndpoint).toString(),
         timeout: Consts_1.DEFAULT_HTTP_CLIENT_TIMEOUT_MS,
     });
+    if (toncenterV3Endpoint) {
+        openers.push({
+            opener: new ToncenterV3Opener_1.ToncenterV3Opener(new ToncenterV3Indexer_1.ToncenterV3Indexer(toncenterV3Endpoint), tonClient, logger),
+            retries: maxRetries,
+            retryDelay,
+            maxRetryDelay: Consts_1.DEFAULT_RETRY_MAX_DELAY_MS,
+            retryBackoffMultiplier: Consts_1.DEFAULT_RETRY_BACKOFF_MULTIPLIER,
+        });
+    }
     const opener = (0, TonClientOpener_1.tonClientOpener)(tonClient, logger);
     openers.push({
         opener,

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

@@ -1,3 +1,4 @@
+import type { Message } from '@ton/ton';
 import { Address, Contract, OpenedContract, TonClient, Transaction } from '@ton/ton';
 import { ILogger } from '../interfaces';
 import { AddressInformation, ContractState, GetTransactionsOptions, Network } from '../structs/Struct';
@@ -12,6 +13,7 @@ export declare class TonClientOpener extends BaseContractOpener {
     getContractState(address: Address): Promise<ContractState>;
     getTransactions(address: Address, opts: GetTransactionsOptions): Promise<Transaction[]>;
     getAddressInformation(addr: Address): Promise<AddressInformation>;
+    protected findTransactionByHashType(address: Address, hash: string, hashType: 'unknown' | 'in' | 'out' | undefined, opts: GetTransactionsOptions, message?: Message): Promise<Transaction | null>;
     getConfig(): Promise<string>;
 }
 export declare function tonClientOpener(client: TonClient, logger?: ILogger): TonClientOpener;

package/dist/src/adapters/TonClientOpener.js

@@ -38,7 +38,7 @@ class TonClientOpener extends BaseContractOpener_1.BaseContractOpener {
             hash: opts.hash ? (0, Utils_1.normalizeHashToBase64)(opts.hash) : undefined,
             to_lt: opts.to_lt,
             inclusive: opts.inclusive,
-            archival: opts.archival,
+            ...(opts.archival === undefined ? {} : { archival: opts.archival }),
         };
         return this.client.getTransactions(address, clientOpts);
     }
@@ -51,6 +51,40 @@ class TonClientOpener extends BaseContractOpener_1.BaseContractOpener {
             },
         };
     }
+    async findTransactionByHashType(address, hash, hashType, opts, message) {
+        if (opts.archival === true && message?.info.type === 'internal') {
+            const { src, dest, createdLt } = message.info;
+            const targetHash = (0, Utils_1.normalizeHashToBase64)(hash);
+            if (hashType === 'in') {
+                try {
+                    const tx = await this.client.tryLocateResultTx(src, dest, createdLt.toString());
+                    if (tx.inMessage &&
+                        (0, ton_1.beginCell)().store((0, ton_1.storeMessage)(tx.inMessage)).endCell().hash().toString('base64') ===
+                            targetHash) {
+                        return tx;
+                    }
+                }
+                catch {
+                    // Keep the regular hash scan semantics when Toncenter cannot locate a delivered result.
+                }
+            }
+            else if (hashType === 'out') {
+                try {
+                    const tx = await this.client.tryLocateSourceTx(src, dest, createdLt.toString());
+                    for (const outMessage of tx.outMessages.values()) {
+                        if ((0, ton_1.beginCell)().store((0, ton_1.storeMessage)(outMessage)).endCell().hash().toString('base64') ===
+                            targetHash) {
+                            return tx;
+                        }
+                    }
+                }
+                catch {
+                    // Keep the regular hash scan semantics when Toncenter cannot locate the source.
+                }
+            }
+        }
+        return super.findTransactionByHashType(address, hash, hashType, opts, message);
+    }
     async getConfig() {
         const info = await this.client.getMasterchainInfo();
         const url = new URL('getConfigAll', this.client.parameters.endpoint);

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

@@ -14,6 +14,7 @@ export declare class ToncenterV3Indexer implements IToncenterV3Indexer {
      * @returns Indexed transaction with owning account context, or null on 404 / empty result.
      */
     getTransactionByHash(transactionHash: string): Promise<ToncenterV3IndexedTransaction | null>;
+    getTransactionsByMessageHash(messageHash: string, direction: 'in' | 'out'): Promise<ToncenterV3IndexedTransaction[]>;
     /**
      * Queries Toncenter v3 indexed `/adjacentTransactions` endpoint by hash.
      * @param transactionHash TON transaction hash accepted by the indexer.

package/dist/src/adapters/ToncenterV3Indexer.js

@@ -27,20 +27,41 @@ class ToncenterV3Indexer {
             const response = await this.httpClient.get(endpoint, {
                 params: {
                     hash: transactionHash,
-                    limit: 1,
+                    limit: Consts_1.DEFAULT_FIND_TX_LIMIT,
                 },
                 transformResponse: [Utils_1.toCamelCaseTransformer],
             });
             return response.data.transactions?.[0] ?? null;
         }
         catch (error) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            if (error?.response?.status === 404) {
+            if (error.response?.status === Consts_1.HTTP_NOT_FOUND_STATUS_CODE) {
                 return null;
             }
             throw (0, errors_1.operationFetchError)(`request ${requestLabel} failed to resolve TON indexed transaction`, error);
         }
     }
+    async getTransactionsByMessageHash(messageHash, direction) {
+        const endpoint = this.endpoint.endsWith('/')
+            ? `${this.endpoint}transactionsByMessage`
+            : `${this.endpoint}/transactionsByMessage`;
+        try {
+            const { data } = await this.httpClient.get(endpoint, {
+                params: {
+                    msg_hash: messageHash,
+                    direction,
+                    limit: Consts_1.DEFAULT_FIND_TX_LIMIT,
+                },
+                transformResponse: [Utils_1.toCamelCaseTransformer],
+            });
+            return data.transactions ?? [];
+        }
+        catch (error) {
+            if (error.response?.status === Consts_1.HTTP_NOT_FOUND_STATUS_CODE) {
+                return [];
+            }
+            throw (0, errors_1.operationFetchError)(`request GET ${endpoint} failed to resolve TON indexed transactions by message`, error);
+        }
+    }
     /**
      * Queries Toncenter v3 indexed `/adjacentTransactions` endpoint by hash.
      * @param transactionHash TON transaction hash accepted by the indexer.
@@ -59,8 +80,7 @@ class ToncenterV3Indexer {
             return response.data.transactions ?? [];
         }
         catch (error) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            if (error?.response?.status === 404) {
+            if (error.response?.status === Consts_1.HTTP_NOT_FOUND_STATUS_CODE) {
                 return [];
             }
             throw (0, errors_1.operationFetchError)(`request ${requestLabel} failed to resolve adjacent TON indexed transactions`, error);
@@ -86,20 +106,19 @@ class ToncenterV3Indexer {
             return rootTransaction;
         }
         const queue = [{ hash: rootTransaction.hash, depth: 0 }];
-        const visitedHashes = new Set([(0, Utils_1.normalizeHashToHex)(rootTransaction.hash)]);
+        const visitedHashes = new Set([rootTransaction.hash]);
         let scannedTransactions = 0;
-        while (queue.length > 0) {
-            const { hash: currentHash, depth } = queue.shift();
+        for (let i = 0; i < queue.length; i++) {
+            const { hash: currentHash, depth } = queue[i];
             if (depth >= maxDepth || scannedTransactions >= maxScannedTransactions) {
                 continue;
             }
             const adjacentTransactions = await this.getAdjacentTransactions(currentHash);
             for (const transaction of adjacentTransactions) {
-                const normalizedHash = (0, Utils_1.normalizeHashToHex)(transaction.hash);
-                if (visitedHashes.has(normalizedHash)) {
+                if (visitedHashes.has(transaction.hash)) {
                     continue;
                 }
-                visitedHashes.add(normalizedHash);
+                visitedHashes.add(transaction.hash);
                 scannedTransactions += 1;
                 if (this.isCollectibleEventTransactionOnAccount(transaction, crossChainLayer)) {
                     return transaction;

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

@@ -0,0 +1,11 @@
+import { TonClient } from '@ton/ton';
+import { ILogger, IToncenterV3Indexer } from '../interfaces';
+import { TrackTransactionTreeParams, TrackTransactionTreeResult } from '../structs/Struct';
+import { TonClientOpener } from './TonClientOpener';
+export declare class ToncenterV3Opener extends TonClientOpener {
+    private readonly indexer;
+    constructor(indexer: IToncenterV3Indexer, client: TonClient, logger?: ILogger);
+    trackTransactionTreeWithResult(address: string, hash: string, params?: TrackTransactionTreeParams): Promise<TrackTransactionTreeResult>;
+    private findRootTransaction;
+    private validateIndexedTransactionWithResult;
+}

package/dist/src/adapters/ToncenterV3Opener.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToncenterV3Opener = void 0;
+const ton_1 = require("@ton/ton");
+const Consts_1 = require("../sdk/Consts");
+const Utils_1 = require("../sdk/Utils");
+const Struct_1 = require("../structs/Struct");
+const TonClientOpener_1 = require("./TonClientOpener");
+class ToncenterV3Opener extends TonClientOpener_1.TonClientOpener {
+    constructor(indexer, client, logger) {
+        super(client, logger);
+        this.indexer = indexer;
+    }
+    async trackTransactionTreeWithResult(address, hash, params = {}) {
+        const { maxDepth = Consts_1.DEFAULT_FIND_TX_MAX_DEPTH, direction = Struct_1.TransactionTreeDirection.FORWARD, retryOnNotFound = Consts_1.DEFAULT_RETRY_ON_NOT_FOUND, retryDelayMs = Consts_1.DEFAULT_RETRY_ON_NOT_FOUND_DELAY_MS, retries = Consts_1.DEFAULT_RETRY_ON_NOT_FOUND_RETRIES, } = params;
+        const rootAddress = ton_1.Address.parse(address);
+        const rootHash = (0, Utils_1.normalizeHashToBase64)(hash);
+        const attempts = retryOnNotFound ? retries + 1 : 1;
+        let rootTransaction = null;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            rootTransaction = await this.findRootTransaction(rootAddress, rootHash);
+            if (rootTransaction) {
+                break;
+            }
+            if (attempt < attempts - 1) {
+                await (0, Utils_1.sleep)(retryDelayMs);
+            }
+        }
+        if (!rootTransaction) {
+            return {
+                success: false,
+                checkedCount: 0,
+                error: {
+                    txHash: rootHash,
+                    exitCode: 'N/A',
+                    resultCode: 'N/A',
+                    reason: 'not_found',
+                    address: rootAddress.toString(),
+                },
+            };
+        }
+        const queue = [{ transaction: rootTransaction, depth: 0 }];
+        const processedTxHashes = new Set();
+        let checkedCount = 0;
+        for (let i = 0; i < queue.length; i++) {
+            const { transaction: tx, depth } = queue[i];
+            if (processedTxHashes.has(tx.hash)) {
+                continue;
+            }
+            processedTxHashes.add(tx.hash);
+            checkedCount += 1;
+            const validationError = this.validateIndexedTransactionWithResult(tx);
+            if (validationError) {
+                return { success: false, checkedCount, error: validationError };
+            }
+            if (depth >= maxDepth) {
+                continue;
+            }
+            const adjacentTransactions = await this.indexer.getAdjacentTransactions(tx.hash);
+            for (const adjacentTransaction of adjacentTransactions) {
+                if ((direction !== Struct_1.TransactionTreeDirection.BACKWARD &&
+                    tx.outMsgs.some((message) => message.hash && message.hash === adjacentTransaction.inMsg?.hash)) ||
+                    (direction !== Struct_1.TransactionTreeDirection.FORWARD &&
+                        adjacentTransaction.outMsgs.some((message) => message.hash && message.hash === tx.inMsg?.hash))) {
+                    queue.push({ transaction: adjacentTransaction, depth: depth + 1 });
+                }
+            }
+        }
+        return { success: true, checkedCount };
+    }
+    async findRootTransaction(address, hash) {
+        const tx = await this.indexer.getTransactionByHash(hash);
+        if (tx && ton_1.Address.parse(tx.account).equals(address)) {
+            return tx;
+        }
+        for (const direction of ['in', 'out']) {
+            const transactions = await this.indexer.getTransactionsByMessageHash(hash, direction);
+            const transaction = transactions.find((tx) => ton_1.Address.parse(tx.account).equals(address));
+            if (transaction) {
+                return transaction;
+            }
+        }
+        return null;
+    }
+    validateIndexedTransactionWithResult(tx) {
+        const { description } = tx;
+        if (description?.type && description.type !== 'generic') {
+            return null;
+        }
+        const computePh = description?.computePh;
+        const action = description?.action;
+        const exitCode = computePh && !computePh.skipped ? computePh.exitCode ?? 'N/A' : 'N/A';
+        const resultCode = action ? action.resultCode ?? 'N/A' : 'N/A';
+        let reason = null;
+        if (description?.aborted) {
+            reason = 'aborted';
+        }
+        else if (!computePh) {
+            reason = 'compute_phase_missing';
+        }
+        else if (!computePh.skipped && (computePh.success !== true || computePh.exitCode !== 0)) {
+            reason = 'compute_phase_failed';
+        }
+        else if (action && (action.success !== true || action.resultCode !== 0)) {
+            reason = 'action_phase_failed';
+        }
+        return reason ? { txHash: tx.hash, exitCode, resultCode, reason } : null;
+    }
+}
+exports.ToncenterV3Opener = ToncenterV3Opener;

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

@@ -4,5 +4,6 @@ export * from './OpenerUtils';
 export * from './RetryableContractOpener';
 export * from './SandboxOpener';
 export * from './ToncenterV3Indexer';
+export * from './ToncenterV3Opener';
 export * from './TonClient4Opener';
 export * from './TonClientOpener';

package/dist/src/adapters/index.js

@@ -20,5 +20,6 @@ __exportStar(require("./OpenerUtils"), exports);
 __exportStar(require("./RetryableContractOpener"), exports);
 __exportStar(require("./SandboxOpener"), exports);
 __exportStar(require("./ToncenterV3Indexer"), exports);
+__exportStar(require("./ToncenterV3Opener"), exports);
 __exportStar(require("./TonClient4Opener"), exports);
 __exportStar(require("./TonClientOpener"), exports);

package/dist/src/errors/index.d.ts

@@ -1,2 +1,2 @@
 export { AddressError, BitError, ContractError, EVMCallError, FetchError, FormatError, KeyError, MetadataError, SettingError, TokenError, TransactionError, WalletError, } from './errors';
-export { allEndpointsFailedError, blockGasLimitFetchError, emptyArrayError, emptyContractError, emptySettingError, estimatedGasExceedsBlockGasLimitError, evmAddressError, externalInMessageRequiredError, executedInTONStageFailedError, gasPriceFetchError, indexRequiredError, insufficientBalanceError, insufficientFeeParamsError, invalidTonExternalMessageBocError, invalidMethodNameError, missingDecimals, missingFeeParamsError, missingGasLimitError, missingJettonDataError, missingTvmExecutorFeeError, notMultiplyOf8Error, operationFetchError, operationIdRequiredForFinalizationError, prefixError, profilingFetchError, simulationFetchError, statusFetchError, tvmAddressError, txFinalizationError, unknownTokenTypeError, unknownWalletError, unsupportedFormatError, unsupportedKeyError, zeroRawAmountError, } from './instances';
+export { allEndpointsFailedError, blockGasLimitFetchError, emptyArrayError, emptyContractError, emptySettingError, estimatedGasExceedsBlockGasLimitError, evmAddressError, executedInTONStageFailedError, externalInMessageRequiredError, gasPriceFetchError, indexRequiredError, insufficientBalanceError, insufficientFeeParamsError, invalidMethodNameError, invalidTonExternalMessageBocError, missingDecimals, missingFeeParamsError, missingGasLimitError, missingJettonDataError, missingTvmExecutorFeeError, notMultiplyOf8Error, operationFetchError, operationIdRequiredForFinalizationError, prefixError, profilingFetchError, simulationFetchError, statusFetchError, tonIndexerRequiredForTonTransactionBocError, tvmAddressError, txFinalizationError, unknownTokenTypeError, unknownWalletError, unsupportedFormatError, unsupportedKeyError, zeroRawAmountError, } from './instances';

package/dist/src/errors/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.zeroRawAmountError = exports.unsupportedKeyError = exports.unsupportedFormatError = exports.unknownWalletError = exports.unknownTokenTypeError = exports.txFinalizationError = exports.tvmAddressError = exports.statusFetchError = exports.simulationFetchError = exports.profilingFetchError = exports.prefixError = exports.operationIdRequiredForFinalizationError = exports.operationFetchError = exports.notMultiplyOf8Error = exports.missingTvmExecutorFeeError = exports.missingJettonDataError = exports.missingGasLimitError = exports.missingFeeParamsError = exports.missingDecimals = exports.invalidMethodNameError = exports.invalidTonExternalMessageBocError = exports.insufficientFeeParamsError = exports.insufficientBalanceError = exports.indexRequiredError = exports.gasPriceFetchError = exports.executedInTONStageFailedError = exports.externalInMessageRequiredError = exports.evmAddressError = exports.estimatedGasExceedsBlockGasLimitError = exports.emptySettingError = exports.emptyContractError = exports.emptyArrayError = exports.blockGasLimitFetchError = exports.allEndpointsFailedError = exports.WalletError = exports.TransactionError = exports.TokenError = exports.SettingError = exports.MetadataError = exports.KeyError = exports.FormatError = exports.FetchError = exports.EVMCallError = exports.ContractError = exports.BitError = exports.AddressError = void 0;
+exports.zeroRawAmountError = exports.unsupportedKeyError = exports.unsupportedFormatError = exports.unknownWalletError = exports.unknownTokenTypeError = exports.txFinalizationError = exports.tvmAddressError = exports.tonIndexerRequiredForTonTransactionBocError = exports.statusFetchError = exports.simulationFetchError = exports.profilingFetchError = exports.prefixError = exports.operationIdRequiredForFinalizationError = exports.operationFetchError = exports.notMultiplyOf8Error = exports.missingTvmExecutorFeeError = exports.missingJettonDataError = exports.missingGasLimitError = exports.missingFeeParamsError = exports.missingDecimals = exports.invalidTonExternalMessageBocError = exports.invalidMethodNameError = exports.insufficientFeeParamsError = exports.insufficientBalanceError = exports.indexRequiredError = exports.gasPriceFetchError = exports.externalInMessageRequiredError = exports.executedInTONStageFailedError = exports.evmAddressError = exports.estimatedGasExceedsBlockGasLimitError = exports.emptySettingError = exports.emptyContractError = exports.emptyArrayError = exports.blockGasLimitFetchError = exports.allEndpointsFailedError = exports.WalletError = exports.TransactionError = exports.TokenError = exports.SettingError = exports.MetadataError = exports.KeyError = exports.FormatError = exports.FetchError = exports.EVMCallError = exports.ContractError = exports.BitError = exports.AddressError = void 0;
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "AddressError", { enumerable: true, get: function () { return errors_1.AddressError; } });
 Object.defineProperty(exports, "BitError", { enumerable: true, get: function () { return errors_1.BitError; } });
@@ -22,14 +22,14 @@ Object.defineProperty(exports, "emptyContractError", { enumerable: true, get: fu
 Object.defineProperty(exports, "emptySettingError", { enumerable: true, get: function () { return instances_1.emptySettingError; } });
 Object.defineProperty(exports, "estimatedGasExceedsBlockGasLimitError", { enumerable: true, get: function () { return instances_1.estimatedGasExceedsBlockGasLimitError; } });
 Object.defineProperty(exports, "evmAddressError", { enumerable: true, get: function () { return instances_1.evmAddressError; } });
-Object.defineProperty(exports, "externalInMessageRequiredError", { enumerable: true, get: function () { return instances_1.externalInMessageRequiredError; } });
 Object.defineProperty(exports, "executedInTONStageFailedError", { enumerable: true, get: function () { return instances_1.executedInTONStageFailedError; } });
+Object.defineProperty(exports, "externalInMessageRequiredError", { enumerable: true, get: function () { return instances_1.externalInMessageRequiredError; } });
 Object.defineProperty(exports, "gasPriceFetchError", { enumerable: true, get: function () { return instances_1.gasPriceFetchError; } });
 Object.defineProperty(exports, "indexRequiredError", { enumerable: true, get: function () { return instances_1.indexRequiredError; } });
 Object.defineProperty(exports, "insufficientBalanceError", { enumerable: true, get: function () { return instances_1.insufficientBalanceError; } });
 Object.defineProperty(exports, "insufficientFeeParamsError", { enumerable: true, get: function () { return instances_1.insufficientFeeParamsError; } });
-Object.defineProperty(exports, "invalidTonExternalMessageBocError", { enumerable: true, get: function () { return instances_1.invalidTonExternalMessageBocError; } });
 Object.defineProperty(exports, "invalidMethodNameError", { enumerable: true, get: function () { return instances_1.invalidMethodNameError; } });
+Object.defineProperty(exports, "invalidTonExternalMessageBocError", { enumerable: true, get: function () { return instances_1.invalidTonExternalMessageBocError; } });
 Object.defineProperty(exports, "missingDecimals", { enumerable: true, get: function () { return instances_1.missingDecimals; } });
 Object.defineProperty(exports, "missingFeeParamsError", { enumerable: true, get: function () { return instances_1.missingFeeParamsError; } });
 Object.defineProperty(exports, "missingGasLimitError", { enumerable: true, get: function () { return instances_1.missingGasLimitError; } });
@@ -42,6 +42,7 @@ Object.defineProperty(exports, "prefixError", { enumerable: true, get: function
 Object.defineProperty(exports, "profilingFetchError", { enumerable: true, get: function () { return instances_1.profilingFetchError; } });
 Object.defineProperty(exports, "simulationFetchError", { enumerable: true, get: function () { return instances_1.simulationFetchError; } });
 Object.defineProperty(exports, "statusFetchError", { enumerable: true, get: function () { return instances_1.statusFetchError; } });
+Object.defineProperty(exports, "tonIndexerRequiredForTonTransactionBocError", { enumerable: true, get: function () { return instances_1.tonIndexerRequiredForTonTransactionBocError; } });
 Object.defineProperty(exports, "tvmAddressError", { enumerable: true, get: function () { return instances_1.tvmAddressError; } });
 Object.defineProperty(exports, "txFinalizationError", { enumerable: true, get: function () { return instances_1.txFinalizationError; } });
 Object.defineProperty(exports, "unknownTokenTypeError", { enumerable: true, get: function () { return instances_1.unknownTokenTypeError; } });

package/dist/src/errors/instances.d.ts

@@ -43,3 +43,4 @@ export declare const blockGasLimitFetchError: (msg: string, inner?: unknown) =>
 export declare const estimatedGasExceedsBlockGasLimitError: (txName: string, estimatedGas: bigint, blockGasLimit: bigint) => TransactionError;
 export declare const invalidTonExternalMessageBocError: (reason?: string) => FormatError;
 export declare const externalInMessageRequiredError: (actualType: string) => FormatError;
+export declare const tonIndexerRequiredForTonTransactionBocError: SettingError;