@ton/sandbox 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.41.0] - 2025-12-05
+
+### Changed
+
+- Updated emulator WASM binary
+- Debug logs are now extracted from VM logs (due to emulator changes), which interacts in subtle ways with the verbosity settings
+
+## [0.40.0] - 2025-12-04
+
+### Added
+
+- Sandbox UI support
+
+### Changed
+
+- Updated emulator WASM binary
+- Updated dependencies
+- `Blockchain` now allows null code and data in state init
+
+### Fixed
+
+- Fixed `@ton/test-utils` import
+
 ## [0.39.0] - 2025-10-29
 
 ### Changed

package/dist/blockchain/Blockchain.d.ts

@@ -10,6 +10,9 @@ import { Coverage } from '../coverage';
 import { MessageQueueManager } from './MessageQueueManager';
 import { AsyncLock } from '../utils/AsyncLock';
 import { BlockchainSnapshot } from './BlockchainSnapshot';
+import { IUIConnector } from '../ui/connection/UIConnector';
+import { WebSocketConnectionOptions } from '../ui/connection/websocket/types';
+import { IUIManager } from '../ui/UIManager';
 export type ExternalOutInfo = {
     type: 'external-out';
     src: Address;
@@ -59,6 +62,7 @@ export type SandboxContract<F> = {
 export declare function toSandboxContract<T>(contract: OpenedContract<T>): SandboxContract<T>;
 export type PendingMessage = (({
     type: 'message';
+    callStack?: string;
     mode?: number;
 } & Message) | {
     type: 'ticktock';
@@ -84,6 +88,10 @@ export type BlockchainConfig = Cell | 'default' | 'slim';
 export type SendMessageIterParams = MessageParams & {
     allowParallel?: boolean;
 };
+export type UIOptions = {
+    enabled?: boolean;
+    connector?: IUIConnector;
+} & WebSocketConnectionOptions;
 export declare class Blockchain {
     protected lock: AsyncLock;
     protected storage: BlockchainStorage;
@@ -102,6 +110,7 @@ export declare class Blockchain {
     protected autoDeployLibs: boolean;
     protected transactions: BlockchainTransaction[];
     protected defaultQueueManager: MessageQueueManager;
+    protected uiManager: IUIManager;
     protected collectCoverage: boolean;
     protected readonly coverageTransactions: BlockchainTransaction[][];
     protected readonly coverageGetMethodResults: GetMethodResult[];
@@ -155,7 +164,9 @@ export declare class Blockchain {
         storage: BlockchainStorage;
         meta?: ContractsMeta;
         autoDeployLibs?: boolean;
+        uiOptions?: UIOptions;
     });
+    protected createUiManager(opts?: UIOptions): IUIManager;
     protected createQueueManager(): MessageQueueManager;
     /**
      * @returns Config used in blockchain.
@@ -332,11 +343,12 @@ export declare class Blockchain {
      * Opens contract. Returns proxy that substitutes the blockchain Provider in methods starting with get and set.
      *
      * @param contract Contract to open.
+     * @param name     Name of the contract.
      *
      * @example
      * const contract = blockchain.openContract(new Contract(address));
      */
-    openContract<T extends Contract>(contract: T): SandboxContract<T>;
+    openContract<T extends Contract>(contract: T, name?: string): SandboxContract<T>;
     protected startFetchingContract(address: Address): Promise<SmartContract>;
     /**
      * Retrieves {@link SmartContract} from {@link BlockchainStorage}.
@@ -444,6 +456,7 @@ export declare class Blockchain {
      * @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.
      * @param [opts.autoDeployLibs] Optional flag. If set to true, libraries will be collected automatically
+     * @param [opts.uiOptions] Optional object to configure the UI connector.
      * @example
      * const blockchain = await Blockchain.create({ config: 'slim' });
      *
@@ -462,6 +475,7 @@ export declare class Blockchain {
         storage?: BlockchainStorage;
         meta?: ContractsMeta;
         autoDeployLibs?: boolean;
+        uiOptions?: UIOptions;
     }): Promise<Blockchain>;
 }
 export {};

package/dist/blockchain/Blockchain.js

@@ -19,6 +19,10 @@ const coverage_1 = require("../coverage");
 const MessageQueueManager_1 = require("./MessageQueueManager");
 const AsyncLock_1 = require("../utils/AsyncLock");
 const require_1 = require("../utils/require");
+const noop_1 = require("../utils/noop");
+const environment_1 = require("../utils/environment");
+const OneTimeWebSocketConnector_1 = require("../ui/connection/websocket/OneTimeWebSocketConnector");
+const UIManager_1 = require("../ui/UIManager");
 const CREATE_WALLETS_PREFIX = 'CREATE_WALLETS';
 function createWalletsSeed(idx) {
     return `${CREATE_WALLETS_PREFIX}${idx}`;
@@ -72,6 +76,7 @@ class Blockchain {
     autoDeployLibs;
     transactions = [];
     defaultQueueManager;
+    uiManager;
     collectCoverage = false;
     coverageTransactions = [];
     coverageGetMethodResults = [];
@@ -180,6 +185,18 @@ class Blockchain {
         this.meta = opts.meta;
         this.autoDeployLibs = opts.autoDeployLibs ?? false;
         this.defaultQueueManager = this.createQueueManager();
+        this.uiManager = this.createUiManager(opts.uiOptions);
+    }
+    createUiManager(opts) {
+        if (!opts?.enabled) {
+            // noop implementation
+            return { publishTransactions: noop_1.noop };
+        }
+        const connector = opts.connector ?? new OneTimeWebSocketConnector_1.OneTimeWebSocketConnector(opts);
+        return new UIManager_1.UIManager(connector, {
+            getMeta: (address) => this.meta?.get(address),
+            knownContracts: () => this.storage.knownContracts(),
+        });
     }
     createQueueManager() {
         return new MessageQueueManager_1.MessageQueueManager(this.lock, {
@@ -189,8 +206,11 @@ class Blockchain {
             getLibs: () => this.libs,
             setLibs: (value) => (this.libs = value),
             getAutoDeployLibs: () => this.autoDeployLibs,
-            registerTxsForCoverage: (txs) => this.registerTxsForCoverage(txs),
-            addTransaction: (transaction) => this.transactions.push(transaction),
+            onTransactions: (txs) => {
+                this.registerTxsForCoverage(txs);
+                this.uiManager.publishTransactions(txs);
+            },
+            onTransaction: (transaction) => this.transactions.push(transaction),
         });
     }
     /**
@@ -456,11 +476,12 @@ class Blockchain {
      * Opens contract. Returns proxy that substitutes the blockchain Provider in methods starting with get and set.
      *
      * @param contract Contract to open.
+     * @param name     Name of the contract.
      *
      * @example
      * const contract = blockchain.openContract(new Contract(address));
      */
-    openContract(contract) {
+    openContract(contract, name) {
         let address;
         let init = undefined;
         if (!core_1.Address.isAddress(contract.address)) {
@@ -468,15 +489,19 @@ class Blockchain {
         }
         address = contract.address;
         if (contract.init) {
-            if (!(contract.init.code instanceof core_1.Cell)) {
+            if (contract.init.code !== undefined &&
+                contract.init.code !== null &&
+                !(contract.init.code instanceof core_1.Cell)) {
                 throw Error('Invalid init.code');
             }
-            if (!(contract.init.data instanceof core_1.Cell)) {
+            if (contract.init.data !== undefined &&
+                contract.init.data !== null &&
+                !(contract.init.data instanceof core_1.Cell)) {
                 throw Error('Invalid init.data');
             }
             init = contract.init;
         }
-        this.meta?.upsert(address, { wrapperName: contract?.constructor?.name, abi: contract.abi });
+        this.meta?.upsert(address, { wrapperName: name ?? contract?.constructor?.name, abi: contract.abi });
         const provider = this.provider(address, init);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         return new Proxy(contract, {
@@ -596,6 +621,7 @@ class Blockchain {
      */
     enableCoverage(enable = true) {
         this.collectCoverage = enable;
+        this.verbosity.print = false;
         this.verbosity.vmLogs = 'vm_logs_verbose';
     }
     /**
@@ -678,6 +704,7 @@ class Blockchain {
      * @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.
      * @param [opts.autoDeployLibs] Optional flag. If set to true, libraries will be collected automatically
+     * @param [opts.uiOptions] Optional object to configure the UI connector.
      * @example
      * const blockchain = await Blockchain.create({ config: 'slim' });
      *
@@ -691,12 +718,22 @@ class Blockchain {
      * });
      */
     static async create(opts) {
-        return new Blockchain({
+        const uiEnabled = opts?.uiOptions?.enabled ?? (0, environment_1.getOptionalEnv)('SANDBOX_UI_ENABLED', 'boolean');
+        const blockchain = new Blockchain({
             executor: opts?.executor ?? (await Executor_1.Executor.create()),
             storage: opts?.storage ?? new BlockchainStorage_1.LocalBlockchainStorage(),
-            meta: opts?.meta ?? (0, require_1.requireOptional)('@ton/test-utils')?.contractsMeta,
+            meta: opts?.meta ?? (0, require_1.requireTestUtils)()?.contractsMeta,
             ...opts,
+            uiOptions: {
+                enabled: uiEnabled,
+                ...opts?.uiOptions,
+            },
         });
+        if (uiEnabled) {
+            blockchain.verbosity.print = false;
+            blockchain.verbosity.vmLogs = 'vm_logs_verbose';
+        }
+        return blockchain;
     }
 }
 exports.Blockchain = Blockchain;

package/dist/blockchain/MessageQueueManager.d.ts

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

package/dist/blockchain/MessageQueueManager.js

@@ -65,7 +65,7 @@ class MessageQueueManager {
             }
             return result;
         });
-        this.blockchain.registerTxsForCoverage(results);
+        this.blockchain.onTransactions(results);
         return results;
     }
     async processMessage(params) {
@@ -73,16 +73,18 @@ class MessageQueueManager {
         let done = this.messageQueue.length == 0;
         while (!done) {
             const message = this.messageQueue.shift();
+            let callStack;
             let tx;
             let smartContract;
             if (message.type === 'message') {
+                callStack = message.callStack;
                 if (message.info.type === 'external-out') {
                     done = this.messageQueue.length == 0;
                     continue;
                 }
                 this.blockchain.increaseLt();
                 smartContract = await this.blockchain.getContract(message.info.dest);
-                tx = await smartContract.receiveMessage(message, params);
+                tx = await smartContract.receiveMessage(message, params, callStack);
             }
             else {
                 this.blockchain.increaseLt();
@@ -98,7 +100,7 @@ class MessageQueueManager {
                 mode: message.type === 'message' ? message.mode : undefined,
             };
             transaction.parent?.children.push(transaction);
-            this.blockchain.addTransaction(transaction);
+            this.blockchain.onTransaction(transaction);
             result = transaction;
             done = true;
             const sendMsgActions = (transaction.outActions?.filter((action) => action.type === 'sendMsg') ??
@@ -122,6 +124,7 @@ class MessageQueueManager {
                     type: 'message',
                     parentTransaction: transaction,
                     mode: sendMsgActions[index]?.mode,
+                    callStack,
                     ...message,
                 });
                 if (message.info.type === 'internal') {

package/dist/blockchain/SmartContract.d.ts

@@ -30,6 +30,7 @@ export type SmartContractTransaction = Transaction & {
     blockchainLogs: string;
     vmLogs: string;
     debugLogs: string;
+    callStack?: string;
     oldStorage?: Cell;
     newStorage?: Cell;
     outActions?: OutActionExtended[];
@@ -109,9 +110,9 @@ export declare class SmartContract {
     }): SmartContract;
     static empty(blockchain: Blockchain, address: Address): SmartContract;
     protected createCommonArgs(params?: MessageParams): RunCommonArgs;
-    receiveMessage(message: Message, params?: MessageParams): Promise<SmartContractTransaction>;
+    receiveMessage(message: Message, params?: MessageParams, callStack?: string): Promise<SmartContractTransaction>;
     runTickTock(which: TickOrTock, params?: MessageParams): Promise<SmartContractTransaction>;
-    protected runCommon(run: () => Promise<EmulationResult>): Promise<SmartContractTransaction>;
+    protected runCommon(run: () => Promise<EmulationResult>, callStack?: string): Promise<SmartContractTransaction>;
     get(method: string | number, stack?: TupleItem[], params?: GetMethodParams): Promise<GetMethodResult>;
     get verbosity(): LogsVerbosity;
     set verbosity(value: LogsVerbosity);

package/dist/blockchain/SmartContract.js

@@ -294,7 +294,7 @@ class SmartContract {
             prevBlocksInfo: this.blockchain.prevBlocks,
         };
     }
-    async receiveMessage(message, params) {
+    async receiveMessage(message, params, callStack) {
         const args = {
             ...this.createCommonArgs(params),
             message: (0, core_1.beginCell)().store((0, core_1.storeMessage)(message)).endCell(),
@@ -304,14 +304,14 @@ class SmartContract {
             const { uninitialized, debugInfo } = debugContext.getDebugInfo(this.account);
             if (debugInfo !== undefined) {
                 const executor = await this.blockchain.getDebuggerExecutor();
-                return await this.runCommon(() => debugContext.debugTransaction(executor, args, debugInfo));
+                return await this.runCommon(() => debugContext.debugTransaction(executor, args, debugInfo), callStack);
             }
             else if (uninitialized) {
                 // eslint-disable-next-line no-console
                 console.log('Debugging uninitialized accounts is unsupported in debugger beta');
             }
         }
-        return await this.runCommon(() => this.blockchain.executor.runTransaction(args));
+        return await this.runCommon(() => this.blockchain.executor.runTransaction(args), callStack);
     }
     async runTickTock(which, params) {
         return await this.runCommon(() => this.blockchain.executor.runTickTock({
@@ -319,7 +319,7 @@ class SmartContract {
             which,
         }));
     }
-    async runCommon(run) {
+    async runCommon(run, callStack) {
         let oldStorage = undefined;
         if (this.blockchain.recordStorage && this.account.account?.storage.state.type === 'active') {
             oldStorage = this.account.account?.storage.state.state.data ?? undefined;
@@ -357,6 +357,7 @@ class SmartContract {
             blockchainLogs: res.logs,
             vmLogs: res.result.vmLog,
             debugLogs: res.debugLogs,
+            callStack,
             oldStorage,
             newStorage,
             outActions,

package/dist/executor/Executor.d.ts

@@ -96,10 +96,8 @@ export declare class Executor implements IExecutor {
     private module;
     private heap;
     private emulator?;
-    private debugLogs;
     debugLogFunc: (s: string) => void;
     private constructor();
-    private handleDebugLog;
     static create(opts?: {
         debug?: boolean;
     }): Promise<Executor>;

package/dist/executor/Executor.js

@@ -164,62 +164,63 @@ function getDebuggerWasmBinary() {
     debuggerWasmBinary = (0, bpatch_1.decodePatch)(getWasmBinary(), unzipped);
     return debuggerWasmBinary;
 }
+function splitVmLog(log) {
+    const vm = [];
+    const debug = [];
+    for (const line of log.split('\n')) {
+        if (line.startsWith('#DEBUG#')) {
+            debug.push(line);
+        }
+        else {
+            vm.push(line);
+        }
+    }
+    return { vmLog: vm.join('\n'), debugLog: debug.join('\n') };
+}
 class Executor {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     module;
     heap;
     emulator;
-    debugLogs = [];
+    // TODO: this is not used anymore - debug logs are now included in the VM log, and so we cannot emit them during execution
     debugLogFunc = () => { };
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     constructor(module) {
         this.module = module;
         this.heap = new Heap(module);
     }
-    handleDebugLog(text) {
-        this.debugLogs.push(text);
-        this.debugLogFunc(text);
-    }
     static async create(opts) {
         const binary = opts?.debug ? getDebuggerWasmBinary() : getWasmBinary();
         const module = opts?.debug ? DebuggerEmulatorModule : EmulatorModule;
         let ex = undefined;
-        const printErr = (text) => {
-            if (ex === undefined) {
-                // eslint-disable-next-line no-console
-                console.error('Debug log received before executor was created:', text);
-            }
-            else {
-                ex.handleDebugLog(text);
-            }
-        };
         ex = new Executor(await module({
             wasmBinary: binary,
-            printErr,
         }));
         return ex;
     }
     async runGetMethod(args) {
         const params = getMethodArgsToInternalParams(args);
         let stack = (0, core_1.serializeTuple)(args.stack);
-        this.debugLogs = [];
         const resp = JSON.parse(this.extractString(this.invoke('_run_get_method', [JSON.stringify(params), stack.toBoc().toString('base64'), args.config])));
-        const debugLogs = this.debugLogs.join('\n');
         if (resp.fail) {
             // eslint-disable-next-line no-console
             console.error(resp);
             throw new Error('Unknown emulation error');
         }
+        const { vmLog, debugLog } = splitVmLog('vm_log' in resp.output ? resp.output.vm_log : '');
         return {
-            output: resp.output,
+            output: 'vm_log' in resp.output
+                ? {
+                    ...resp.output,
+                    vm_log: vmLog,
+                }
+                : resp.output,
             logs: resp.logs,
-            debugLogs,
+            debugLogs: debugLog,
         };
     }
     runCommon(args) {
-        this.debugLogs = [];
         const resp = JSON.parse(this.extractString(this.invoke('_emulate_with_emulator', args)));
-        const debugLogs = this.debugLogs.join('\n');
         if (resp.fail) {
             // eslint-disable-next-line no-console
             console.error(resp);
@@ -227,13 +228,14 @@ class Executor {
         }
         const logs = resp.logs;
         const result = resp.output;
+        const { vmLog, debugLog } = splitVmLog('vm_log' in result ? result.vm_log : '');
         return {
             result: result.success
                 ? {
                     success: true,
                     transaction: result.transaction,
                     shardAccount: result.shard_account,
-                    vmLog: result.vm_log,
+                    vmLog: vmLog,
                     actions: result.actions,
                 }
                 : {
@@ -241,13 +243,13 @@ class Executor {
                     error: result.error,
                     vmResults: 'vm_log' in result
                         ? {
-                            vmLog: result.vm_log,
+                            vmLog: vmLog,
                             vmExitCode: result.vm_exit_code,
                         }
                         : undefined,
                 },
             logs,
-            debugLogs,
+            debugLogs: debugLog,
         };
     }
     async runTickTock(args) {
@@ -312,7 +314,6 @@ class Executor {
     sbsGetMethodSetup(args) {
         const params = getMethodArgsToInternalParams(args);
         let stack = (0, core_1.serializeTuple)(args.stack);
-        this.debugLogs = [];
         const res = this.invoke('_setup_sbs_get_method', [
             JSON.stringify(params),
             stack.toBoc().toString('base64'),
@@ -360,17 +361,21 @@ class Executor {
     }
     sbsGetMethodResult(ptr) {
         const resp = JSON.parse(this.extractString(this.invoke('_sbs_get_method_result', [ptr])));
-        const debugLogs = this.debugLogs.join('\n');
+        const { vmLog, debugLog } = splitVmLog('vm_log' in resp ? resp.vm_log : '');
         return {
-            output: resp,
+            output: 'vm_log' in resp
+                ? {
+                    ...resp,
+                    vm_log: vmLog,
+                }
+                : resp,
             logs: 'BLOCKCHAIN LOGS ARE NOT AVAILABLE IN DEBUGGER BETA',
-            debugLogs,
+            debugLogs: debugLog,
         };
     }
     sbsTransactionSetup(args) {
         const emptr = this.invoke('_create_emulator', [args.config, verbosityToNum[args.verbosity]]);
         const params = runCommonArgsToInternalParams(args);
-        this.debugLogs = [];
         const res = this.invoke('_emulate_sbs', [
             emptr,
             args.libs?.toBoc().toString('base64') ?? 0,
@@ -420,14 +425,14 @@ class Executor {
     }
     sbsTransactionResult(ptr) {
         const result = JSON.parse(this.extractString(this.invoke('_em_sbs_result', [ptr])));
-        const debugLogs = this.debugLogs.join('\n');
+        const { vmLog, debugLog } = splitVmLog('vm_log' in result ? result.vm_log : '');
         return {
             result: result.success
                 ? {
                     success: true,
                     transaction: result.transaction,
                     shardAccount: result.shard_account,
-                    vmLog: result.vm_log,
+                    vmLog: vmLog,
                     actions: result.actions,
                 }
                 : {
@@ -435,13 +440,13 @@ class Executor {
                     error: result.error,
                     vmResults: 'vm_log' in result
                         ? {
-                            vmLog: result.vm_log,
+                            vmLog: vmLog,
                             vmExitCode: result.vm_exit_code,
                         }
                         : undefined,
                 },
             logs: 'BLOCKCHAIN LOGS ARE NOT AVAILABLE IN DEBUGGER BETA',
-            debugLogs,
+            debugLogs: debugLog,
         };
     }
     extractString(ptr) {