@ton/sandbox 0.37.0-tvmbeta.1 → 0.37.1

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.37.1] - 2025-09-03
+
+### Fixed
+
+- Made `@ton/test-utils` import optional, preventing errors in environments where it's not installed.
+
+## [0.37.0] - 2025-08-18
+
+### Added
+
+- Added `snapshotToSerializable` and `snapshotFromSerializable` utilities to enable snapshot serialization (e.g., to JSON), allowing snapshots to be saved, transferred, and restored easily.
+
+### Changed
+
+- Switched to Jest 30
+
 ## [0.36.0] - 2025-08-04
 
 ### Added

package/README.md

@@ -23,6 +23,7 @@ The key difference of this package from [ton-contract-executor](https://github.c
 * [Viewing logs](#viewing-logs)
 * [Setting smart contract state directly](#setting-smart-contract-state-directly)
 * [Using snapshots](#using-snapshots)
+  * [Serializing snapshots](#serializing-snapshots)
 * [Performing testing on contracts from a real network](#performing-testing-on-contracts-from-a-real-network)
 * [Step-by-step execution](#step-by-step-execution)
 * [Network/Block configuration](#networkblock-configuration)
@@ -666,11 +667,13 @@ Note that this is a low-level function and does not check any invariants, such a
 It is possible to store the whole `Blockchain` state in an object and restore this state later. This can be useful to compare the outcomes of different actions after a certain point, or to store the state of the contract system after a long series of configuration actions in order to quickly restore it for all required tests instead of setting it up each time.
 
 To store the state, do the following:
+
 ```typescript
 const snapshot = blockchain.snapshot()
 ```
 
 To restore the state, do the following:
+
 ```typescript
 await blockchain.loadFrom(snapshot)
 ```
@@ -686,6 +689,32 @@ Note: snapshots store **the entire state** of a `Blockchain` instance, that incl
 
 Basically, the state of a `Blockchain` instance after it is restored using a snapshot is the same as if the same actions were performed on that instance as on the instance from which the snapshot originates.
 
+### Serializing snapshots
+
+Snapshots contain `Cell`s and `Buffer`s, which are **not JSON-safe**. Use the provided helpers to convert snapshots to/from plain JSON objects:
+
+```ts
+import { snapshotToSerializable, snapshotFromSerializable } from './BlockchainSnapshot';
+
+const serializable = snapshotToSerializable(blockchain.snapshot());
+const restored = snapshotFromSerializable(serializable);
+await blockchain.loadFrom(restored);
+```
+
+This is useful for saving snapshots to disk or sending them over the network.
+
+```ts
+import fs from 'fs';
+
+fs.writeFileSync(
+    'snapshot.json',
+    JSON.stringify(snapshotToSerializable(blockchain.snapshot()))
+);
+
+const snapshotJson = JSON.parse(fs.readFileSync('snapshot.json', 'utf8'));
+await blockchain.loadFrom(snapshotFromSerializable(snapshotJson));
+```
+
 ## Performing testing on contracts from a real network
 
 It is possible to use Sandbox to perform tests on contracts that are deployed to a real network. To do that, create your `Blockchain` instance using a `RemoteBlockchainStorage`, like so:

package/dist/blockchain/Blockchain.d.ts

@@ -4,11 +4,12 @@ import { BlockchainStorage } from './BlockchainStorage';
 import { Event } from '../event/Event';
 import { SandboxContractProvider } from './BlockchainContractProvider';
 import { TreasuryContract } from '../treasury/Treasury';
-import { GetMethodParams, GetMethodResult, LogsVerbosity, MessageParams, SmartContract, SmartContractSnapshot, SmartContractTransaction, Verbosity } from './SmartContract';
+import { GetMethodParams, GetMethodResult, LogsVerbosity, MessageParams, SmartContract, SmartContractTransaction, Verbosity } from './SmartContract';
 import { ContractsMeta } from '../meta/ContractsMeta';
 import { Coverage } from '../coverage';
 import { MessageQueueManager } from './MessageQueueManager';
 import { AsyncLock } from '../utils/AsyncLock';
+import { BlockchainSnapshot } from './BlockchainSnapshot';
 export type ExternalOutInfo = {
     type: 'external-out';
     src: Address;
@@ -80,19 +81,6 @@ export type TreasuryParams = Partial<{
     resetBalanceIfZero: boolean;
 }>;
 export type BlockchainConfig = Cell | 'default' | 'slim';
-export type BlockchainSnapshot = {
-    contracts: SmartContractSnapshot[];
-    networkConfig: string;
-    lt: bigint;
-    time?: number;
-    verbosity: LogsVerbosity;
-    libs?: Cell;
-    nextCreateWalletIndex: number;
-    prevBlocksInfo?: PrevBlocksInfo;
-    randomSeed?: Buffer;
-    autoDeployLibs: boolean;
-    transactions: BlockchainTransaction[];
-};
 export type SendMessageIterParams = MessageParams & {
     allowParallel?: boolean;
 };

package/dist/blockchain/Blockchain.js

@@ -18,6 +18,7 @@ const deepcopy_1 = require("../utils/deepcopy");
 const coverage_1 = require("../coverage");
 const MessageQueueManager_1 = require("./MessageQueueManager");
 const AsyncLock_1 = require("../utils/AsyncLock");
+const require_1 = require("../utils/require");
 const CREATE_WALLETS_PREFIX = 'CREATE_WALLETS';
 function createWalletsSeed(idx) {
     return `${CREATE_WALLETS_PREFIX}${idx}`;
@@ -693,8 +694,7 @@ class Blockchain {
         return new Blockchain({
             executor: opts?.executor ?? (await Executor_1.Executor.create()),
             storage: opts?.storage ?? new BlockchainStorage_1.LocalBlockchainStorage(),
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            meta: opts?.meta ?? require('@ton/test-utils')?.contractsMeta,
+            meta: opts?.meta ?? (0, require_1.requireOptional)('@ton/test-utils')?.contractsMeta,
             ...opts,
         });
     }

package/dist/blockchain/BlockchainSnapshot.d.ts

@@ -0,0 +1,61 @@
+import { Cell } from '@ton/core';
+import { LogsVerbosity, SmartContractSnapshot } from './SmartContract';
+import { BlockId, PrevBlocksInfo } from '../executor/Executor';
+import { BlockchainTransaction } from './Blockchain';
+export type BlockchainSnapshot = {
+    contracts: SmartContractSnapshot[];
+    networkConfig: string;
+    lt: bigint;
+    time?: number;
+    verbosity: LogsVerbosity;
+    libs?: Cell;
+    nextCreateWalletIndex: number;
+    prevBlocksInfo?: PrevBlocksInfo;
+    randomSeed?: Buffer;
+    autoDeployLibs: boolean;
+    transactions: BlockchainTransaction[];
+};
+export type SerializableBlockId = {
+    workchain: number;
+    shard: string;
+    seqno: number;
+    rootHash: string;
+    fileHash: string;
+};
+export declare function blockIdToSerializable(blockId: BlockId): SerializableBlockId;
+export type SerializableSnapshot = {
+    contracts: {
+        address: string;
+        account: string;
+        lastTxTime: number;
+        verbosity?: Partial<LogsVerbosity>;
+    }[];
+    networkConfig: string;
+    lt: string;
+    time?: number;
+    verbosity: LogsVerbosity;
+    libs?: string;
+    nextCreateWalletIndex: number;
+    prevBlocksInfo?: {
+        lastMcBlocks: SerializableBlockId[];
+        prevKeyBlock: SerializableBlockId;
+        lastMcBlocks100?: SerializableBlockId[];
+    };
+    randomSeed?: string;
+    autoDeployLibs: boolean;
+    transactions: {
+        transaction: string;
+        blockchainLogs: string;
+        vmLogs: string;
+        debugLogs: string;
+        oldStorage?: string;
+        newStorage?: string;
+        outActions?: string;
+        externals: string[];
+        mode?: number;
+        parentHash?: string;
+        childrenHashes: string[];
+    }[];
+};
+export declare function snapshotToSerializable(snapshot: BlockchainSnapshot): SerializableSnapshot;
+export declare function snapshotFromSerializable(serialized: SerializableSnapshot): BlockchainSnapshot;

package/dist/blockchain/BlockchainSnapshot.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockIdToSerializable = blockIdToSerializable;
+exports.snapshotToSerializable = snapshotToSerializable;
+exports.snapshotFromSerializable = snapshotFromSerializable;
+const core_1 = require("@ton/core");
+const Event_1 = require("../event/Event");
+function blockIdToSerializable(blockId) {
+    return {
+        workchain: blockId.workchain,
+        shard: blockId.shard.toString(),
+        seqno: blockId.seqno,
+        rootHash: blockId.rootHash.toString('hex'),
+        fileHash: blockId.fileHash.toString('hex'),
+    };
+}
+function writableToBase64(writer) {
+    return (0, core_1.beginCell)().store(writer).endCell().toBoc().toString('base64');
+}
+function snapshotToSerializable(snapshot) {
+    return {
+        contracts: snapshot.contracts.map((contract) => ({
+            account: writableToBase64((0, core_1.storeShardAccount)(contract.account)),
+            address: contract.address.toString(),
+            lastTxTime: contract.lastTxTime,
+            verbosity: contract.verbosity,
+        })),
+        networkConfig: snapshot.networkConfig,
+        lt: snapshot.lt.toString(),
+        time: snapshot.time,
+        verbosity: snapshot.verbosity,
+        libs: snapshot.libs?.toBoc().toString('base64'),
+        nextCreateWalletIndex: snapshot.nextCreateWalletIndex,
+        prevBlocksInfo: snapshot.prevBlocksInfo
+            ? {
+                lastMcBlocks: snapshot.prevBlocksInfo.lastMcBlocks.map(blockIdToSerializable),
+                prevKeyBlock: blockIdToSerializable(snapshot.prevBlocksInfo.prevKeyBlock),
+                lastMcBlocks100: snapshot.prevBlocksInfo.lastMcBlocks100?.map(blockIdToSerializable),
+            }
+            : undefined,
+        randomSeed: snapshot.randomSeed?.toString('hex'),
+        autoDeployLibs: snapshot.autoDeployLibs,
+        transactions: snapshot.transactions.map((transaction) => {
+            return {
+                transaction: writableToBase64((0, core_1.storeTransaction)(transaction)),
+                blockchainLogs: transaction.blockchainLogs,
+                vmLogs: transaction.vmLogs,
+                debugLogs: transaction.debugLogs,
+                oldStorage: transaction.oldStorage?.toBoc().toString('base64'),
+                newStorage: transaction.newStorage?.toBoc().toString('base64'),
+                outActions: transaction.outActions ? writableToBase64((0, core_1.storeOutList)(transaction.outActions)) : undefined,
+                externals: transaction.externals.map((external) => writableToBase64((0, core_1.storeMessageRelaxed)(external))),
+                mode: transaction.mode,
+                parentHash: transaction.parent?.hash().toString('hex'),
+                childrenHashes: transaction.children.map((tx) => tx.hash().toString('hex')),
+            };
+        }),
+    };
+}
+function blockIdFromSerializable(s) {
+    return {
+        workchain: s.workchain,
+        shard: BigInt(s.shard),
+        seqno: s.seqno,
+        rootHash: Buffer.from(s.rootHash, 'hex'),
+        fileHash: Buffer.from(s.fileHash, 'hex'),
+    };
+}
+function snapshotFromSerializable(serialized) {
+    const transactions = serialized.transactions.map((t) => {
+        const transaction = (0, core_1.loadTransaction)(core_1.Cell.fromBase64(t.transaction).beginParse());
+        return {
+            ...transaction,
+            blockchainLogs: t.blockchainLogs,
+            vmLogs: t.vmLogs,
+            debugLogs: t.debugLogs,
+            oldStorage: t.oldStorage ? core_1.Cell.fromBase64(t.oldStorage) : undefined,
+            newStorage: t.newStorage ? core_1.Cell.fromBase64(t.newStorage) : undefined,
+            outActions: t.outActions ? (0, core_1.loadOutList)(core_1.Cell.fromBase64(t.outActions).beginParse()) : undefined,
+            events: (0, Event_1.extractEvents)(transaction),
+            mode: t.mode,
+            externals: t.externals.map((ext) => (0, core_1.loadMessageRelaxed)(core_1.Cell.fromBase64(ext).beginParse())),
+            children: [],
+        };
+    });
+    const transactionsMap = new Map(transactions.map((tx) => [tx.hash().toString('hex'), tx]));
+    for (let i = 0; i < transactions.length; i++) {
+        const { parentHash, childrenHashes } = serialized.transactions[i];
+        transactions[i].parent = parentHash ? transactionsMap.get(parentHash) : undefined;
+        transactions[i].children = childrenHashes.map((hash) => transactionsMap.get(hash));
+    }
+    return {
+        contracts: serialized.contracts.map((contract) => ({
+            address: core_1.Address.parse(contract.address),
+            account: (0, core_1.loadShardAccount)(core_1.Cell.fromBase64(contract.account).beginParse()),
+            lastTxTime: contract.lastTxTime,
+            verbosity: contract.verbosity,
+        })),
+        networkConfig: serialized.networkConfig,
+        lt: BigInt(serialized.lt),
+        time: serialized.time,
+        verbosity: serialized.verbosity,
+        libs: serialized.libs ? core_1.Cell.fromBase64(serialized.libs) : undefined,
+        nextCreateWalletIndex: serialized.nextCreateWalletIndex,
+        prevBlocksInfo: serialized.prevBlocksInfo
+            ? {
+                lastMcBlocks: serialized.prevBlocksInfo.lastMcBlocks.map(blockIdFromSerializable),
+                prevKeyBlock: blockIdFromSerializable(serialized.prevBlocksInfo.prevKeyBlock),
+                lastMcBlocks100: serialized.prevBlocksInfo.lastMcBlocks100?.map(blockIdFromSerializable),
+            }
+            : undefined,
+        randomSeed: serialized.randomSeed ? Buffer.from(serialized.randomSeed, 'hex') : undefined,
+        autoDeployLibs: serialized.autoDeployLibs,
+        transactions,
+    };
+}