txtracer-core-test-dev/dist/methods.d.ts

Core TxTracer library for collecting transaction information

import { Address, Cell, ShardAccount, Transaction } from "@ton/core";
import { AccountFromAPI, Block, BlockInfo, ComputeInfo, RawTransaction, StateFromAPI, TraceMoneyResult } from "./types";
import { EmulationResult, EmulationResultSuccess } from "@ton/sandbox/dist/executor/Executor";
import { AccountState as CoreAccountState } from "@ton/core/dist/types/AccountState";
/**
 * Minimal “handle” for locating a transaction on the TON blockchain.
 * A tuple of (lt, hash, address) is guaranteed to be unique and can be
 * passed to RPC methods such as `getAccountTransactions` to retrieve
 * the full on‑chain record.
 *
 * Can be obtained by {@link findBaseTxByHash}.
 */
export interface BaseTxInfo {
    /**
     * Logical‑time of the transaction.
     */
    lt: bigint;
    /**
     * Raw 256‑bit hash of the transaction BoC.
     */
    hash: Buffer;
    /**
     * Contract address that issued / owns the transaction.
     */
    address: Address;
}
/**
 * Returns base transaction information by its hash.
 * @param testnet if true finds in testnet otherwise in mainnet
 * @param txHash  transaction hash to find
 */
export declare const findBaseTxByHash: (testnet: boolean, txHash: string) => Promise<BaseTxInfo | undefined>;
/**
 * Returns full information for transaction by base information obtained from `findBaseTxByHash`
 * @param testnet if true finds in testnet otherwise in mainnet
 * @param info    information for search
 */
export declare const findRawTxByHash: (testnet: boolean, info: BaseTxInfo) => Promise<RawTransaction[]>;
/**
 * Return the shard‑block header that contains a given
 * {@link RawTransaction}.
 *
 * @param testnet  Mainnet/testnet flag.
 * @param tx       Raw transaction object.
 * @returns        The matching shard‑block or `undefined`
 *                 if Toncenter cannot find it.
 */
export declare const findShardBlockForTx: (testnet: boolean, tx: RawTransaction) => Promise<Block | undefined>;
/**
 * Return a master‑block (full representation, including `shards[]`)
 * by its `seqno` via TON API v4.
 *
 * @param testnet  Mainnet/testnet flag.
 * @param seqno    Master‑block sequence number.
 * @returns        The complete {@link BlockInfo}.
 */
export declare const findFullBlockForSeqno: (testnet: boolean, seqno: number) => Promise<BlockInfo>;
/**
 * Retrieve all transactions of a given account whose logical‑time
 * lies in the interval `(minLt, baseTx.lt]`, inclusive of `baseTx`.
 *
 * Used to reconstruct in‑block history before emulation.
 *
 * @param testnet  Mainnet/testnet flag.
 * @param baseTx   The “upper bound” transaction.
 * @param minLt    Lower logical‑time boundary
 * @returns        Transactions ordered **newest → oldest**.
 */
export declare const findAllTransactionsBetween: (testnet: boolean, baseTx: BaseTxInfo, minLt: bigint) => Promise<Transaction[]>;
/**
 * Load the global configuration cell valid for the master‑block that
 * encloses the target transaction. Required by the TVM executor to
 * calculate gas, random‑seed and limits exactly as onchain.
 *
 * @param testnet   Mainnet/testnet flag.
 * @param block     Full master‑block object (with `shards[]` array).
 * @returns         Config cell as a string.
 */
export declare const getBlockConfig: (testnet: boolean, block: BlockInfo) => Promise<string>;
/**
 * Return an account snapshot *before* the current master‑block.
 * The snapshot is converted to {@link ShardAccount} so it can be
 * directly fed into `runTransaction`.
 *
 * @param testnet   Mainnet/testnet flag.
 * @param address   Account address.
 * @param block     Master‑block N (the one that contains the tx).
 * @returns         ShardAccount representing state on master‑block N‑1.
 */
export declare const getBlockAccount: (testnet: boolean, address: Address, block: BlockInfo) => Promise<ShardAccount>;
/**
 * Scan every shard‑summary inside a master‑block and return the
 * smallest `lt` for the specified account. This value marks the
 * earliest transaction of the account inside that master‑block.
 *
 * @param tx         Target (latest) transaction object.
 * @param address    Account address.
 * @param block      Master‑block that contains `tx`.
 * @returns          Minimum logical‑time as `bigint`.
 */
export declare const computeMinLt: (tx: Transaction, address: Address, block: BlockInfo) => bigint;
/**
 * Load a library cell (T‑lib) from dton.io GraphQL by its
 * 256‑bit hash.
 *
 * @param testnet  Mainnet/testnet flag.
 * @param hash     Hex string of the library hash.
 * @returns        Decoded {@link Cell} containing actual code.
 * @throws         Error if the library is missing on the server.
 */
export declare const getLibraryByHash: (testnet: boolean, hash: string) => Promise<Cell>;
/**
 * Inspect the contract’s current code and (optionally) the init
 * code of the pending message, detect all **exotic library cells**
 * (tag 2) and build a dict mapping hash → real library code.
 *
 * @param testnet   Mainnet/testnet flag.
 * @param account   Current {@link ShardAccount} snapshot.
 * @param tx        Transaction whose `inMessage` may include `Init`.
 * @returns         Serialized dict cell or `undefined`
 *                  when no libraries are referenced and actual code cell if
 *                  original code is just an exotic library cell
 */
export declare const collectUsedLibraries: (testnet: boolean, account: ShardAccount, tx: Transaction) => Promise<[Cell | undefined, Cell | undefined]>;
/**
 * Convert an account record received from Toncenter / Tonhub API
 * (`AccountFromAPI`) into the low‑level `ShardAccount` structure
 * expected by core TON libraries and the sandbox executor.
 *
 * @param apiAccount  Raw JSON account object from REST API.
 * @param address     Parsed {@link Address} of the account
 *                    (API does not always include it).
 * @returns           A fully‑typed {@link ShardAccount} ready for
 *                    serialization with `storeShardAccount`.
 */
export declare function createShardAccountFromAPI(apiAccount: AccountFromAPI, address: Address): ShardAccount;
/**
 * Transform the `state` sub‑object of an API response into the canonical
 * `AccountState` union used by `@ton/core`.
 *
 * @param givenState  State payload exactly as returned by Toncenter API.
 * @returns           Normalised `AccountState` object suitable for TVM.
 */
export declare function normalizeStateFromAPI(givenState: StateFromAPI): CoreAccountState;
/**
 * Sequentially emulate the list of earlier transactions to roll
 * the shard‑account forward until the moment right before the
 * target transaction. Returns the updated balance and the new
 * base64‑encoded shard‑account string.
 *
 * @param prevBalance         Balance at the snapshot start.
 * @param prevTxsInBlock      Transactions to replay (oldest → newest).
 * @param emulate             Helper that runs a single transaction.
 * @param shardAccountBase64  Starting shard‑account (base64).
 * @returns                   `{ prevBalance, shardAccountBase64 }`
 *                            after applying all txs.
 */
export declare const emulatePreviousTransactions: (prevBalance: bigint, prevTxsInBlock: Transaction[], emulate: (tx: Transaction, shardAccountStr: string) => Promise<EmulationResult>, shardAccountBase64: string) => Promise<{
    prevBalance: bigint;
    shardAccountBase64: string;
}>;
/**
 * Spin up TON Sandbox, configure verbosity, wrap the executor
 * into a convenience helper `emulate` and return both the helper
 * and the sandbox version metadata.
 *
 * @param blockConfig  Global config cell.
 * @param libs         Dict of referenced libraries or `undefined`.
 * @param randSeed     Random seed from master‑block header.
 * @returns            `{ emulatorVersion, emulate }`
 */
export declare const prepareEmulator: (blockConfig: string, libs: Cell | undefined, randSeed: Buffer) => Promise<{
    emulatorVersion: {
        commitHash: string;
        commitDate: string;
    };
    emulate: (tx: Transaction, shardAccountBase64: string) => Promise<EmulationResult>;
}>;
/**
 * Convert the raw `EmulationResultSuccess` plus the prior balance
 * into a structured set of money movements, compute‑phase stats and
 * convenience fields for higher‑level reporting.
 *
 * @param res            Successful result from TVM executor.
 * @param balanceBefore  Balance **before** the emulated tx.
 * @returns              Breakdown containing sender/dest, amounts,
 *                       gas usage and the parsed `emulatedTx`.
 */
export declare const computeFinalData: (res: EmulationResultSuccess, balanceBefore: bigint) => {
    sender: Address | undefined;
    contract: Address;
    money: TraceMoneyResult;
    emulatedTx: Transaction;
    amount: bigint | undefined;
    computeInfo: ComputeInfo;
};
/**
 * Extract the final `c5` register (action list) from emulation results,
 * decode it into an array of `OutAction`s and
 * return both the list and the original `c5` cell.
 *
 * @param res  Successful emulation result.
 * @returns    `{ finalActions, c5 }`
 */
export declare const findFinalActions: (res: EmulationResultSuccess) => {
    finalActions: never[];
    c5: undefined;
} | {
    finalActions: import("@ton/core").OutAction[];
    c5: Cell;
};
/**
 * Sum the value (`coins`) of every *internal* outgoing message
 * produced by a transaction. External messages are ignored since its
 * value is always 0.
 *
 * @param tx  Parsed {@link Transaction}.
 * @returns   Total toncoins sent out by the contract in this tx.
 */
export declare const calculateSentTotal: (tx: Transaction) => bigint;
/**
 * Helper to serialize a {@link ShardAccount} object into base64
 * exactly as expected by `executor.runTransaction`.
 *
 * @param shardAccountBeforeTx  Account snapshot to serialize.
 * @returns                     Base64 string of the BOC‑encoded cell.
 */
export declare const shardAccountToBase64: (shardAccountBeforeTx: ShardAccount) => string;