@ton/sandbox 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.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
+
+- Updated emulator WASM binary
+
 ## [0.38.0] - 2025-10-15
 
 ### Added

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,