@ton/sandbox 0.36.0-dev.20250804114000.4e90ae1 → 0.36.0

package/CHANGELOG.md

@@ -5,10 +5,11 @@ 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
+## [0.36.0] - 2025-08-04
 
 ### Added
 
+- Added `Blockchain.getTransactions` method to fetch transactions
 - Added coverage
 - Added `allowParallel` flag to `Blockchain.sendMessageIter` method, allowing for testing MITM attack
 - Added `autoDeployLibs` flag, that allow to detect libraries, deployed by contract in masterchain automatically

package/dist/blockchain/Blockchain.d.ts

@@ -91,6 +91,7 @@ export type BlockchainSnapshot = {
     prevBlocksInfo?: PrevBlocksInfo;
     randomSeed?: Buffer;
     autoDeployLibs: boolean;
+    transactions: BlockchainTransaction[];
 };
 export type SendMessageIterParams = MessageParams & {
     allowParallel?: boolean;
@@ -111,10 +112,11 @@ export declare class Blockchain {
     protected randomSeed?: Buffer;
     protected shouldDebug: boolean;
     protected autoDeployLibs: boolean;
+    protected transactions: BlockchainTransaction[];
     protected defaultQueueManager: MessageQueueManager;
     protected collectCoverage: boolean;
-    protected readonly txs: BlockchainTransaction[][];
-    protected readonly getMethodResults: GetMethodResult[];
+    protected readonly coverageTransactions: BlockchainTransaction[][];
+    protected readonly coverageGetMethodResults: GetMethodResult[];
     readonly executor: IExecutor;
     protected debuggerExecutor?: Executor;
     getDebuggerExecutor(): Promise<Executor>;
@@ -262,6 +264,33 @@ export declare class Blockchain {
      * const now = res.stackReader.readNumber();
      */
     runGetMethod(address: Address, method: number | string, stack?: TupleItem[], params?: GetMethodParams): Promise<GetMethodResult>;
+    /**
+     * Retrieves transactions for the specified address. Transactions are ordered from newest to oldest.
+     *
+     * If both `lt` and `hash` are provided, the result will include transactions up to and including the one matching them.
+     *
+     * @param {Address} address - The address to retrieve transactions for.
+     * @param opts - Options to fetch transactions
+     * @param [opts.lt] - Logical time of the transaction to start from. Must be used together with `hash`.
+     * @param [opts.hash] - Hash of the transaction to start from. Must be used together with `lt`.
+     * @param [opts.limit] - Maximum number of transactions to return.
+     *
+     * @returns {Promise<BlockchainTransaction[]>} Promise resolving to an array of transactions involving the given address.
+     *
+     * @throws {Error} If both `lt` and `hash` are provided but no matching transaction is found.
+     *
+     * @example
+     * const transactions = await blockchain.getTransactions(Address.parse(...), {
+     *   lt: '1234567890',
+     *   hash: 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
+     *   limit: 10
+     * });
+     */
+    getTransactions(address: Address, opts?: {
+        limit?: number;
+        lt?: string | bigint;
+        hash?: string | Buffer;
+    }): Promise<BlockchainTransaction[]>;
     protected increaseLt(): void;
     /**
      * Creates new {@link ContractProvider} for contract address.

package/dist/blockchain/Blockchain.js

@@ -69,10 +69,11 @@ class Blockchain {
     randomSeed;
     shouldDebug = false;
     autoDeployLibs;
+    transactions = [];
     defaultQueueManager;
     collectCoverage = false;
-    txs = [];
-    getMethodResults = [];
+    coverageTransactions = [];
+    coverageGetMethodResults = [];
     executor;
     debuggerExecutor;
     async getDebuggerExecutor() {
@@ -100,6 +101,7 @@ class Blockchain {
             prevBlocksInfo: (0, deepcopy_1.deepcopy)(this.prevBlocksInfo),
             randomSeed: (0, deepcopy_1.deepcopy)(this.randomSeed),
             autoDeployLibs: this.autoDeployLibs,
+            transactions: this.transactions.map((tx) => tx),
         };
     }
     /**
@@ -124,6 +126,7 @@ class Blockchain {
         this.prevBlocksInfo = (0, deepcopy_1.deepcopy)(snapshot.prevBlocksInfo);
         this.randomSeed = (0, deepcopy_1.deepcopy)(snapshot.randomSeed);
         this.autoDeployLibs = snapshot.autoDeployLibs;
+        this.transactions = snapshot.transactions.map((tx) => tx);
     }
     get recordStorage() {
         return this.shouldRecordStorage;
@@ -186,6 +189,7 @@ class Blockchain {
             setLibs: (value) => (this.libs = value),
             getAutoDeployLibs: () => this.autoDeployLibs,
             registerTxsForCoverage: (txs) => this.registerTxsForCoverage(txs),
+            addTransaction: (transaction) => this.transactions.push(transaction),
         });
     }
     /**
@@ -315,6 +319,45 @@ class Blockchain {
         this.registerGetMethodForCoverage(result);
         return result;
     }
+    /**
+     * Retrieves transactions for the specified address. Transactions are ordered from newest to oldest.
+     *
+     * If both `lt` and `hash` are provided, the result will include transactions up to and including the one matching them.
+     *
+     * @param {Address} address - The address to retrieve transactions for.
+     * @param opts - Options to fetch transactions
+     * @param [opts.lt] - Logical time of the transaction to start from. Must be used together with `hash`.
+     * @param [opts.hash] - Hash of the transaction to start from. Must be used together with `lt`.
+     * @param [opts.limit] - Maximum number of transactions to return.
+     *
+     * @returns {Promise<BlockchainTransaction[]>} Promise resolving to an array of transactions involving the given address.
+     *
+     * @throws {Error} If both `lt` and `hash` are provided but no matching transaction is found.
+     *
+     * @example
+     * const transactions = await blockchain.getTransactions(Address.parse(...), {
+     *   lt: '1234567890',
+     *   hash: 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
+     *   limit: 10
+     * });
+     */
+    async getTransactions(address, opts) {
+        const transactionByAddress = this.transactions.reverse().filter((transaction) => {
+            const dst = transaction.inMessage?.info?.dest;
+            return core_1.Address.isAddress(dst) && dst.equals(address);
+        });
+        const { lt, hash, limit } = opts ?? {};
+        let resultTransactions = transactionByAddress;
+        if (lt !== undefined && hash !== undefined) {
+            const hashBuffer = typeof hash === 'string' ? Buffer.from(hash, 'hex') : hash;
+            const transaction = transactionByAddress.find((tx) => tx.lt === BigInt(lt) && tx.hash() === hashBuffer);
+            if (!transaction) {
+                throw new Error('Transaction with provided lt and hash not found.');
+            }
+            resultTransactions = resultTransactions.filter((tx) => tx.lt <= transaction.lt);
+        }
+        return resultTransactions.slice(0, limit);
+    }
     increaseLt() {
         this.currentLt += LT_ALIGN;
     }
@@ -329,6 +372,7 @@ class Blockchain {
      */
     provider(address, init) {
         return new BlockchainContractProvider_1.BlockchainContractProvider({
+            getTransactions: (address, opts) => this.getTransactions(address, opts),
             getContract: (addr) => this.getContract(addr),
             pushMessage: (msg) => this.defaultQueueManager.pushMessage(msg),
             runGetMethod: (addr, method, args) => this.runGetMethod(addr, method, args),
@@ -589,12 +633,12 @@ class Blockchain {
     registerTxsForCoverage(txs) {
         if (!this.collectCoverage)
             return;
-        this.txs.push(txs);
+        this.coverageTransactions.push(txs);
     }
     registerGetMethodForCoverage(get) {
         if (!this.collectCoverage)
             return;
-        this.getMethodResults.push(get);
+        this.coverageGetMethodResults.push(get);
     }
     /**
      * Returns coverage analysis for the specified code cell.
@@ -620,8 +664,8 @@ class Blockchain {
         if (!this.collectCoverage || this.verbosity.vmLogs !== 'vm_logs_verbose') {
             return undefined;
         }
-        const txs = this.txs.flatMap((tx) => (0, coverage_1.collectTxsCoverage)(code, address, tx));
-        const gets = this.getMethodResults.flatMap((get) => (0, coverage_1.collectAsmCoverage)(code, get.vmLogs));
+        const txs = this.coverageTransactions.flatMap((tx) => (0, coverage_1.collectTxsCoverage)(code, address, tx));
+        const gets = this.coverageGetMethodResults.flatMap((get) => (0, coverage_1.collectAsmCoverage)(code, get.vmLogs));
         const coverages = [...txs, ...gets];
         return new coverage_1.Coverage((0, coverage_1.mergeCoverages)(...coverages));
     }

package/dist/blockchain/BlockchainContractProvider.d.ts

@@ -1,6 +1,7 @@
 import { Address, Cell, Contract, ContractGetMethodResult, ContractProvider, ContractState, ExtraCurrency, Message, OpenedContract, Sender, SendMode, StateInit, Transaction, TupleItem } from '@ton/core';
 import { TickOrTock } from '../executor/Executor';
 import { GetMethodResult, SmartContract } from './SmartContract';
+import { BlockchainTransaction } from './Blockchain';
 export interface SandboxContractProvider extends ContractProvider {
     tickTock(which: TickOrTock): Promise<void>;
 }
@@ -12,6 +13,11 @@ export declare class BlockchainContractProvider implements SandboxContractProvid
     private readonly address;
     private readonly init?;
     constructor(blockchain: {
+        getTransactions(address: Address, opts?: {
+            limit?: number;
+            lt?: string | bigint;
+            hash?: string | Buffer;
+        }): Promise<BlockchainTransaction[]>;
         getContract(address: Address): Promise<SmartContract>;
         pushMessage(message: Message): Promise<void>;
         runGetMethod(address: Address, method: string, args: TupleItem[]): Promise<GetMethodResult>;
@@ -30,12 +36,16 @@ export declare class BlockchainContractProvider implements SandboxContractProvid
      */
     get(name: string, args: TupleItem[]): Promise<ContractGetMethodResult>;
     /**
-     * Dummy implementation of getTransactions. Sandbox does not store transactions, so its ContractProvider cannot fetch any.
-     * Throws error in every call.
+     * Retrieves transactions for the specified address using the provided logical time (lt), hash, and optional limit.
+     * This implementation fetches transactions directly from the underlying blockchain instance.
      *
-     * @throws {Error}
+     * @param address - The address to retrieve transactions for.
+     * @param lt - Logical time of transaction to start with, must be used with hash.
+     * @param hash - Hash of transaction to start with, in buffer or hex encoding, must be sent with lt.
+     * @param limit - Optional maximum number of transactions to fetch.
+     * @returns An array of transactions.
      */
-    getTransactions(_address: Address, _lt: bigint, _hash: Buffer, _limit?: number | undefined): Promise<Transaction[]>;
+    getTransactions(address: Address, lt: bigint, hash: Buffer, limit?: number | undefined): Promise<Transaction[]>;
     /**
      * Pushes external-in message to message queue.
      * @param message Message to push

package/dist/blockchain/BlockchainContractProvider.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BlockchainContractProvider = void 0;
 const core_1 = require("@ton/core");
+const transaction_1 = require("../utils/transaction");
 function bigintToBuffer(x, n = 32) {
     const b = Buffer.alloc(n);
     for (let i = 0; i < n; i++) {
@@ -80,13 +81,18 @@ class BlockchainContractProvider {
         return ret;
     }
     /**
-     * Dummy implementation of getTransactions. Sandbox does not store transactions, so its ContractProvider cannot fetch any.
-     * Throws error in every call.
+     * Retrieves transactions for the specified address using the provided logical time (lt), hash, and optional limit.
+     * This implementation fetches transactions directly from the underlying blockchain instance.
      *
-     * @throws {Error}
+     * @param address - The address to retrieve transactions for.
+     * @param lt - Logical time of transaction to start with, must be used with hash.
+     * @param hash - Hash of transaction to start with, in buffer or hex encoding, must be sent with lt.
+     * @param limit - Optional maximum number of transactions to fetch.
+     * @returns An array of transactions.
      */
-    getTransactions(_address, _lt, _hash, _limit) {
-        throw new Error('`getTransactions` is not implemented in `BlockchainContractProvider`, do not use it in the tests');
+    async getTransactions(address, lt, hash, limit) {
+        const blockchainTransactions = await this.blockchain.getTransactions(address, { lt, hash, limit });
+        return blockchainTransactions.map((blockchainTx) => (0, transaction_1.extractTransaction)(blockchainTx));
     }
     /**
      * Pushes external-in message to message queue.

package/dist/blockchain/MessageQueueManager.d.ts

@@ -15,6 +15,7 @@ export declare class MessageQueueManager {
         setLibs(libs: Cell | undefined): void;
         getAutoDeployLibs(): boolean;
         registerTxsForCoverage(txs: BlockchainTransaction[]): void;
+        addTransaction(transaction: BlockchainTransaction): void;
     });
     pushMessage(message: Message | Cell): Promise<void>;
     pushTickTock(on: Address, which: TickOrTock): Promise<void>;

package/dist/blockchain/MessageQueueManager.js

@@ -98,6 +98,7 @@ class MessageQueueManager {
                 mode: message.type === 'message' ? message.mode : undefined,
             };
             transaction.parent?.children.push(transaction);
+            this.blockchain.addTransaction(transaction);
             result = transaction;
             done = true;
             const sendMsgActions = (transaction.outActions?.filter((action) => action.type === 'sendMsg') ??

package/dist/utils/transaction.d.ts

@@ -0,0 +1,2 @@
+import { Transaction } from '@ton/core';
+export declare function extractTransaction(transactionLike: Transaction & Record<string, unknown>): Transaction;

package/dist/utils/transaction.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTransaction = extractTransaction;
+function extractTransaction(transactionLike) {
+    return {
+        address: transactionLike.address,
+        lt: transactionLike.lt,
+        prevTransactionHash: transactionLike.prevTransactionHash,
+        prevTransactionLt: transactionLike.prevTransactionLt,
+        now: transactionLike.now,
+        outMessagesCount: transactionLike.outMessagesCount,
+        oldStatus: transactionLike.oldStatus,
+        endStatus: transactionLike.endStatus,
+        inMessage: transactionLike.inMessage,
+        outMessages: transactionLike.outMessages,
+        totalFees: transactionLike.totalFees,
+        stateUpdate: transactionLike.stateUpdate,
+        description: transactionLike.description,
+        raw: transactionLike.raw,
+        hash: transactionLike.hash,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ton/sandbox",
-  "version": "0.36.0-dev.20250804114000.4e90ae1",
+  "version": "0.36.0",
   "description": "TON transaction emulator",
   "main": "dist/index.js",
   "license": "MIT",