@ton/sandbox 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [0.32.0] - 2025-06-02
+
+### Added
+
+- Added contract meta gathering via meta field in blockchain
+- Added ability to set `PREVBLOCKS` information
+
+## [0.31.0] - 2025-05-20
+
+### Added
+
+- Added methods to collect metrics of contracts
+- Added `@ton/sandbox/jest-environment` and `@ton/sandbox/jest-reporter` to write metric snapshots from test run results
+- Added contract method ABI auto-mapping mechanism for detailed benchmark metrics
+- Added methods to generate delta reports from metrics of contracts
+
 ## [0.30.0] - 2025-05-12
 
 ### Changed
@@ -383,4 +399,4 @@ type LogsVerbosity = {
 
 ### Removed
 
-- Changed `blockchain.pushMessage`, `blockchain.processQueue`, `blockchain.runQueue` to be private
+- Changed `blockchain.pushMessage`, `blockchain.processQueue`, `blockchain.runQueue` to be private

package/README.md

@@ -15,6 +15,7 @@ The key difference of this package from [ton-contract-executor](https://github.c
   * [Cross contract tests](#cross-contract-tests)
   * [Testing key points](#testing-key-points)
   * [Test examples](#test-examples)
+* [Benchmark contracts](#benchmark-contracts)
 * [Sandbox pitfalls](#sandbox-pitfalls)
 * [Viewing logs](#viewing-logs)
 * [Setting smart contract state directly](#setting-smart-contract-state-directly)
@@ -290,6 +291,109 @@ Learn more from examples:
 * [FunC Test Examples](https://docs.ton.org/develop/smart-contracts/examples#examples-of-tests-for-smart-contracts)
 * [Tact Test Examples](docs/tact-testing-examples.md) 
 
+## Benchmark contracts
+
+The `@ton/sandbox` package provides `@ton/sandbox/jest-environment` and `@ton/sandbox/jest-reporter` built-in support for benchmarking smart contract behavior during tests, including tracking gas usage, cell size, opcode execution, and action phases.
+This is especially useful for performance analysis, gas optimization, and regression checks on contract logic.
+
+> ℹ️ See also: [Collect metric API](docs/collect-metric-api.md) for low-level control and manual snapshots.
+
+### Features
+
+* Automatic metric collection from all transactions triggered during tests
+* Snapshot reporting with contract-level filters
+* Integration with [blueprint](https://github.com/ton-org/blueprint#benchmark-contracts)
+
+### Setup in `jest.config.ts`
+
+```ts
+import type { Config } from 'jest';
+
+const config: Config = {
+    preset: 'ts-jest',
+    testEnvironment: '@ton/sandbox/jest-environment',
+    globalSetup: './jest.setup.ts',
+    testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+    reporters: [
+        'default',
+        ['@ton/sandbox/jest-reporter', {
+            // options
+            snapshotDir: '.snapshot',              // output folder for benchmark reports, default: '.snapshot'
+            contractDatabase: 'contract.abi.json', // path or json a map of known contracts, see Collect metric API, default: 'contract.abi.json'
+            reportName: 'gas-report',              // report name, default: 'gas-report'
+            depthCompare: 2,                       // comparison depth, default: 2
+            removeRawResult: true,                 // remove raw metric file, default: true
+            contractExcludes: [                    // exclude specific contracts from snapshot, default: []
+                'TreasuryContract',
+            ],
+        }],
+    ],
+};
+
+export default config;
+```
+
+### How to run benchmarks
+
+To collect and save snapshot metrics:
+
+```bash
+BENCH_NEW="some" npx jest
+# or
+npx blueprint snapshot --label "some" 
+```
+
+This will:
+
+* Run your tests
+* Collect contract execution metrics
+* Save a snapshot in `.snapshot/<timestamp>.json`
+
+To compare with a previous snapshot:
+
+```bash
+BENCH_DIFF=true npx jest
+# or
+npx blueprint test --gas-report
+```
+
+### Or setup in `gas-report.config.ts`
+
+```ts
+import config from './jest.config';
+
+config.testNamePattern = '^DescribeName .* - test name$'
+config.testEnvironment = '@ton/sandbox/jest-environment'
+config.reporters = [
+    ['@ton/sandbox/jest-reporter', {
+        contractDatabase: 'abi.json',
+        contractExcludes: [
+            'TreasuryContract',
+        ],
+    }],
+]
+export default config;
+```
+
+**Collect metric and get report:**
+
+```bash
+npx blueprint snapshot --label "some label" -- --config gas-report.config.ts
+npx blueprint test --gas-report -- --config gas-report.config.ts
+```
+
+### Output structure
+
+By default, the reporter generates:
+
+```
+.project-root/
+├── .snapshot/
+│   └── 4200000000000.json    // timestamped snapshot file
+├── .sandbox-metric-raw.jsonl // raw metric log (auto-deleted by default)
+├── contract.abi.json         // map of known contracts, see Collect metric API
+└── gas-report.json           // aggregate report in json format
+```
 
 ## Sandbox pitfalls
 

package/dist/blockchain/Blockchain.d.ts

@@ -1,11 +1,12 @@
 import { Address, Cell, Message, Transaction, ContractProvider, Contract, Sender, ShardAccount, TupleItem, ExternalAddress, StateInit, OpenedContract } from "@ton/core";
-import { IExecutor, TickOrTock } from "../executor/Executor";
+import { IExecutor, TickOrTock, PrevBlocksInfo } from "../executor/Executor";
 import { BlockchainStorage } from "./BlockchainStorage";
 import { Event } from "../event/Event";
 import { SandboxContractProvider } from "./BlockchainContractProvider";
 import { TreasuryContract } from "../treasury/Treasury";
 import { GetMethodParams, LogsVerbosity, MessageParams, SmartContract, SmartContractSnapshot, Verbosity } from "./SmartContract";
 import { AsyncLock } from "../utils/AsyncLock";
+import { ContractsMeta } from "../meta/ContractsMeta";
 export type ExternalOutInfo = {
     type: 'external-out';
     src: Address;
@@ -101,6 +102,8 @@ export declare class Blockchain {
     protected contractFetches: Map<string, Promise<SmartContract>>;
     protected nextCreateWalletIndex: number;
     protected shouldRecordStorage: boolean;
+    protected meta?: ContractsMeta;
+    protected prevBlocksInfo?: PrevBlocksInfo;
     readonly executor: IExecutor;
     /**
      * Saves snapshot of current blockchain.
@@ -143,6 +146,7 @@ export declare class Blockchain {
         executor: IExecutor;
         config?: BlockchainConfig;
         storage: BlockchainStorage;
+        meta?: ContractsMeta;
     });
     /**
      * @returns Config used in blockchain.
@@ -152,6 +156,15 @@ export declare class Blockchain {
      * @returns Config used in blockchain in base64 format.
      */
     get configBase64(): string;
+    /**
+     * @returns Current PrevBlocksInfo
+     */
+    get prevBlocks(): PrevBlocksInfo | undefined;
+    /**
+     * Sets PrevBlocksInfo.
+     * @param value PrevBlocksInfo to set
+     */
+    set prevBlocks(value: PrevBlocksInfo | undefined);
     /**
      * Emulates the result of sending a message to this Blockchain. Emulates the whole chain of transactions before returning the result. Each transaction increases lt by 1000000.
      *
@@ -329,7 +342,7 @@ export declare class Blockchain {
      * @param [opts.executor] Custom contract executor. If omitted {@link Executor} is used.
      * @param [opts.config] Config used in blockchain. If omitted {@link defaultConfig} is used.
      * @param [opts.storage] Contracts storage used for blockchain. If omitted {@link LocalBlockchainStorage} is used.
-     *
+     * @param [opts.meta] Optional contracts metadata provider. If not provided, {@link @ton/test-utils.contractsMeta} will be used to accumulate contracts metadata.
      * @example
      * const blockchain = await Blockchain.create({ config: 'slim' });
      *
@@ -346,6 +359,7 @@ export declare class Blockchain {
         executor?: IExecutor;
         config?: BlockchainConfig;
         storage?: BlockchainStorage;
+        meta?: ContractsMeta;
     }): Promise<Blockchain>;
 }
 export {};

package/dist/blockchain/Blockchain.js

@@ -13,6 +13,7 @@ const AsyncLock_1 = require("../utils/AsyncLock");
 const message_1 = require("../utils/message");
 const slimConfig_1 = require("../config/slimConfig");
 const testTreasurySubwalletId_1 = require("../utils/testTreasurySubwalletId");
+const collectMetric_1 = require("../metric/collectMetric");
 const CREATE_WALLETS_PREFIX = 'CREATE_WALLETS';
 function createWalletsSeed(idx) {
     return `${CREATE_WALLETS_PREFIX}${idx}`;
@@ -129,6 +130,7 @@ class Blockchain {
         this.networkConfig = blockchainConfigToBase64(opts.config);
         this.executor = opts.executor;
         this.storage = opts.storage;
+        this.meta = opts.meta;
     }
     /**
      * @returns Config used in blockchain.
@@ -142,6 +144,19 @@ class Blockchain {
     get configBase64() {
         return this.networkConfig;
     }
+    /**
+     * @returns Current PrevBlocksInfo
+     */
+    get prevBlocks() {
+        return this.prevBlocksInfo;
+    }
+    /**
+     * Sets PrevBlocksInfo.
+     * @param value PrevBlocksInfo to set
+     */
+    set prevBlocks(value) {
+        this.prevBlocksInfo = value;
+    }
     /**
      * Emulates the result of sending a message to this Blockchain. Emulates the whole chain of transactions before returning the result. Each transaction increases lt by 1000000.
      *
@@ -400,6 +415,7 @@ class Blockchain {
         else if ((params?.resetBalanceIfZero ?? true) && contract.balance === 0n) {
             contract.balance = params?.balance ?? (0, core_1.toNano)(TREASURY_INIT_BALANCE_TONS);
         }
+        this.meta?.upsert(wallet.address, { treasurySeed: seed });
         return wallet;
     }
     /**
@@ -443,6 +459,7 @@ class Blockchain {
             }
             init = contract.init;
         }
+        this.meta?.upsert(address, { wrapperName: contract?.constructor?.name, abi: contract.abi });
         const provider = this.provider(address, init);
         const blkch = this;
         return new Proxy(contract, {
@@ -452,25 +469,25 @@ class Blockchain {
                 }
                 const value = target[prop];
                 if (typeof prop === 'string' && typeof value === 'function') {
+                    const ctx = {
+                        contract,
+                        methodName: prop,
+                    };
                     if (prop.startsWith('get')) {
                         return (...args) => value.apply(target, [provider, ...args]);
                     }
                     else if (prop.startsWith('send')) {
                         return async (...args) => {
-                            const ret = value.apply(target, [provider, ...args]);
+                            let ret = value.apply(target, [provider, ...args]);
                             if (ret instanceof Promise) {
-                                const r = await ret;
-                                return {
-                                    ...await blkch.runQueue(),
-                                    result: r,
-                                };
-                            }
-                            else {
-                                return {
-                                    ...await blkch.runQueue(),
-                                    result: ret,
-                                };
+                                ret = await ret;
                             }
+                            const out = {
+                                ...await blkch.runQueue(),
+                                result: ret,
+                            };
+                            await (0, collectMetric_1.collectMetric)(blkch, ctx, out);
+                            return out;
                         };
                     }
                 }
@@ -564,7 +581,7 @@ class Blockchain {
      * @param [opts.executor] Custom contract executor. If omitted {@link Executor} is used.
      * @param [opts.config] Config used in blockchain. If omitted {@link defaultConfig} is used.
      * @param [opts.storage] Contracts storage used for blockchain. If omitted {@link LocalBlockchainStorage} is used.
-     *
+     * @param [opts.meta] Optional contracts metadata provider. If not provided, {@link @ton/test-utils.contractsMeta} will be used to accumulate contracts metadata.
      * @example
      * const blockchain = await Blockchain.create({ config: 'slim' });
      *
@@ -581,6 +598,7 @@ class Blockchain {
         return new Blockchain({
             executor: opts?.executor ?? await Executor_1.Executor.create(),
             storage: opts?.storage ?? new BlockchainStorage_1.LocalBlockchainStorage(),
+            meta: opts?.meta ?? require('@ton/test-utils')?.contractsMeta,
             ...opts
         });
     }

package/dist/blockchain/SmartContract.js

@@ -214,6 +214,7 @@ class SmartContract {
             randomSeed: params?.randomSeed ?? Buffer.alloc(32),
             ignoreChksig: params?.ignoreChksig ?? false,
             debugEnabled: this.verbosity.debugLogs,
+            prevBlocksInfo: this.blockchain.prevBlocks,
         };
     }
     async receiveMessage(message, params) {
@@ -287,6 +288,7 @@ class SmartContract {
             gasLimit: params?.gasLimit ?? 10000000n,
             debugEnabled: this.verbosity.debugLogs,
             extraCurrency: this.ec,
+            prevBlocksInfo: this.blockchain.prevBlocks,
         });
         if (this.verbosity.print && this.verbosity.blockchainLogs && res.logs.length > 0) {
             console.log(res.logs);

package/dist/executor/Executor.d.ts

@@ -1,6 +1,18 @@
 /// <reference types="node" />
 import { Address, Cell, TupleItem } from "@ton/core";
 import { ExtraCurrency } from "../utils/ec";
+export type BlockId = {
+    workchain: number;
+    shard: bigint;
+    seqno: number;
+    rootHash: Buffer;
+    fileHash: Buffer;
+};
+export type PrevBlocksInfo = {
+    lastMcBlocks: BlockId[];
+    prevKeyBlock: BlockId;
+    lastMcBlocks100?: BlockId[];
+};
 export type GetMethodArgs = {
     code: Cell;
     data: Cell;
@@ -16,6 +28,7 @@ export type GetMethodArgs = {
     gasLimit: bigint;
     debugEnabled: boolean;
     extraCurrency?: ExtraCurrency;
+    prevBlocksInfo?: PrevBlocksInfo;
 };
 export type GetMethodResultSuccess = {
     success: true;
@@ -44,6 +57,7 @@ export type RunCommonArgs = {
     randomSeed: Buffer | null;
     ignoreChksig: boolean;
     debugEnabled: boolean;
+    prevBlocksInfo?: PrevBlocksInfo;
 };
 export type RunTransactionArgs = {
     message: Cell;

package/dist/executor/Executor.js

@@ -4,6 +4,32 @@ exports.Executor = void 0;
 const core_1 = require("@ton/core");
 const base64_1 = require("../utils/base64");
 const EmulatorModule = require('./emulator-emscripten.js');
+function blockIdToTuple(blockId) {
+    return [
+        { type: 'int', value: BigInt(blockId.workchain) },
+        { type: 'int', value: blockId.shard },
+        { type: 'int', value: BigInt(blockId.seqno) },
+        { type: 'int', value: BigInt('0x' + blockId.rootHash.toString('hex')) },
+        { type: 'int', value: BigInt('0x' + blockId.fileHash.toString('hex')) },
+    ];
+}
+function prevBlocksInfoToTuple(prevBlocksInfo) {
+    const r = [
+        { type: 'tuple', items: prevBlocksInfo.lastMcBlocks.map(bid => ({ type: 'tuple', items: blockIdToTuple(bid) })) },
+        { type: 'tuple', items: blockIdToTuple(prevBlocksInfo.prevKeyBlock) },
+    ];
+    if (prevBlocksInfo.lastMcBlocks100) {
+        r.push({ type: 'tuple', items: prevBlocksInfo.lastMcBlocks100.map(bid => ({ type: 'tuple', items: blockIdToTuple(bid) })) });
+    }
+    return r;
+}
+function serializeTupleAsStackEntry(tuple) {
+    const c = (0, core_1.serializeTuple)([{ type: 'tuple', items: tuple }]);
+    const s = c.beginParse();
+    s.skip(24);
+    s.loadRef();
+    return s.asCell();
+}
 const verbosityToNum = {
     'short': 0,
     'full': 1,
@@ -13,13 +39,17 @@ const verbosityToNum = {
     'full_location_stack_verbose': 5,
 };
 function runCommonArgsToInternalParams(args) {
-    return {
+    const p = {
         utime: args.now,
         lt: args.lt.toString(),
         rand_seed: args.randomSeed === null ? '' : args.randomSeed.toString('hex'),
         ignore_chksig: args.ignoreChksig,
         debug_enabled: args.debugEnabled,
     };
+    if (args.prevBlocksInfo !== undefined) {
+        p.prev_blocks_info = serializeTupleAsStackEntry(prevBlocksInfoToTuple(args.prevBlocksInfo)).toBoc().toString('base64');
+    }
+    return p;
 }
 class Pointer {
     constructor(length, rawPointer) {
@@ -99,6 +129,9 @@ class Executor {
                 params.extra_currencies[k] = v.toString();
             }
         }
+        if (args.prevBlocksInfo !== undefined) {
+            params.prev_blocks_info = serializeTupleAsStackEntry(prevBlocksInfoToTuple(args.prevBlocksInfo)).toBoc().toString('base64');
+        }
         let stack = (0, core_1.serializeTuple)(args.stack);
         this.debugLogs = [];
         const resp = JSON.parse(this.extractString(this.invoke('_run_get_method', [