@ton/sandbox 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.13.0] - 2023-10-05
+
+### Changed
+
+- On transaction emulation error, an `EmulationError` is now thrown that has an `error` string, `vmLogs`, and `exitCode` (the latter two being optional). The error is no longer being dumped into console
+
+## [0.12.0] - 2023-10-03
+
+### Added
+
+- Step by step execution (`blockchain.sendMessageIter`)
+- Better docs
+
+### Fixed
+
+- `now` from `Blockchain` is now honored in `SmartContract.receiveMessage`
+- Exit code 1 is now counted as success in get methods
+
 ## [0.11.1] - 2023-07-26
 
 ### Changed

package/README.md

@@ -261,9 +261,12 @@ it('minter admin should be able to mint jettons', async () => {
 });
 ```
 
-### Test examples
-You can typically find various tests for Sandbox-based project contracts in the `./tests` directory. Some examples can be found in the following [list](https://docs.ton.org/develop/smart-contracts/examples#examples-of-tests-for-smart-contracts).
+### Test Examples
+You can typically find various tests for Sandbox-based project contracts in the `./tests` directory. 
+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) 
 
 ## Viewing logs
 

package/dist/blockchain/Blockchain.d.ts

@@ -88,11 +88,15 @@ export declare class Blockchain {
     get config(): Cell;
     get configBase64(): string;
     sendMessage(message: Message | Cell, params?: MessageParams): Promise<SendMessageResult>;
+    sendMessageIter(message: Message | Cell, params?: MessageParams): Promise<AsyncIterator<BlockchainTransaction> & AsyncIterable<BlockchainTransaction>>;
     runTickTock(on: Address | Address[], which: TickOrTock, params?: MessageParams): Promise<SendMessageResult>;
     runGetMethod(address: Address, method: number | string, stack?: TupleItem[], params?: GetMethodParams): Promise<import("./SmartContract").GetMethodResult>;
     protected pushMessage(message: Message | Cell): Promise<void>;
     protected pushTickTock(on: Address, which: TickOrTock): Promise<void>;
     protected runQueue(params?: MessageParams): Promise<SendMessageResult>;
+    protected txIter(needsLocking: boolean, params?: MessageParams): AsyncIterator<BlockchainTransaction> & AsyncIterable<BlockchainTransaction>;
+    protected processInternal(params?: MessageParams): Promise<IteratorResult<BlockchainTransaction>>;
+    protected processTx(needsLocking: boolean, params?: MessageParams): Promise<IteratorResult<BlockchainTransaction>>;
     protected processQueue(params?: MessageParams): Promise<BlockchainTransaction[]>;
     provider(address: Address, init?: {
         code: Cell;

package/dist/blockchain/Blockchain.js

@@ -89,6 +89,15 @@ class Blockchain {
         await this.pushMessage(message);
         return await this.runQueue(params);
     }
+    async sendMessageIter(message, params) {
+        params = {
+            now: this.now,
+            ...params,
+        };
+        await this.pushMessage(message);
+        // Iterable will lock on per tx basis
+        return await this.txIter(true, params);
+    }
     async runTickTock(on, which, params) {
         for (const addr of (Array.isArray(on) ? on : [on])) {
             await this.pushTickTock(addr, which);
@@ -130,60 +139,80 @@ class Blockchain {
             externals: txes.map(tx => tx.externals).flat(),
         };
     }
+    txIter(needsLocking, params) {
+        const it = { next: () => this.processTx(needsLocking, params), [Symbol.asyncIterator]() { return it; } };
+        return it;
+    }
+    async processInternal(params) {
+        let result = undefined;
+        let done = this.messageQueue.length == 0;
+        while (!done) {
+            const message = this.messageQueue.shift();
+            let tx;
+            if (message.type === 'message') {
+                if (message.info.type === 'external-out') {
+                    done = this.messageQueue.length == 0;
+                    continue;
+                }
+                this.currentLt += LT_ALIGN;
+                tx = (await this.getContract(message.info.dest)).receiveMessage(message, params);
+            }
+            else {
+                this.currentLt += LT_ALIGN;
+                tx = (await this.getContract(message.on)).runTickTock(message.which, params);
+            }
+            const transaction = {
+                ...tx,
+                events: (0, Event_1.extractEvents)(tx),
+                parent: message.parentTransaction,
+                children: [],
+                externals: [],
+            };
+            transaction.parent?.children.push(transaction);
+            result = transaction;
+            done = true;
+            for (const message of transaction.outMessages.values()) {
+                if (message.info.type === 'external-out') {
+                    transaction.externals.push({
+                        info: {
+                            type: 'external-out',
+                            src: message.info.src,
+                            dest: message.info.dest ?? undefined,
+                            createdAt: message.info.createdAt,
+                            createdLt: message.info.createdLt,
+                        },
+                        init: message.init ?? undefined,
+                        body: message.body,
+                    });
+                    continue;
+                }
+                this.messageQueue.push({
+                    type: 'message',
+                    parentTransaction: transaction,
+                    ...message,
+                });
+                if (message.info.type === 'internal') {
+                    this.startFetchingContract(message.info.dest);
+                }
+            }
+        }
+        return result === undefined ? { value: result, done: true } : { value: result, done: false };
+    }
+    async processTx(needsLocking, params) {
+        // Lock only if not locked already
+        return needsLocking ? await this.lock.with(async () => this.processInternal(params)) : await this.processInternal(params);
+    }
     async processQueue(params) {
         params = {
             now: this.now,
             ...params,
         };
         return await this.lock.with(async () => {
+            // Locked already
+            const txs = this.txIter(false, params);
             const result = [];
-            while (this.messageQueue.length > 0) {
-                const message = this.messageQueue.shift();
-                let tx;
-                if (message.type === 'message') {
-                    if (message.info.type === 'external-out') {
-                        continue;
-                    }
-                    this.currentLt += LT_ALIGN;
-                    tx = (await this.getContract(message.info.dest)).receiveMessage(message, params);
-                }
-                else {
-                    this.currentLt += LT_ALIGN;
-                    tx = (await this.getContract(message.on)).runTickTock(message.which, params);
-                }
-                const transaction = {
-                    ...tx,
-                    events: (0, Event_1.extractEvents)(tx),
-                    parent: message.parentTransaction,
-                    children: [],
-                    externals: [],
-                };
-                transaction.parent?.children.push(transaction);
-                result.push(transaction);
-                for (const message of transaction.outMessages.values()) {
-                    if (message.info.type === 'external-out') {
-                        transaction.externals.push({
-                            info: {
-                                type: 'external-out',
-                                src: message.info.src,
-                                dest: message.info.dest ?? undefined,
-                                createdAt: message.info.createdAt,
-                                createdLt: message.info.createdLt,
-                            },
-                            init: message.init ?? undefined,
-                            body: message.body,
-                        });
-                        continue;
-                    }
-                    this.messageQueue.push({
-                        type: 'message',
-                        parentTransaction: transaction,
-                        ...message,
-                    });
-                    if (message.info.type === 'internal') {
-                        this.startFetchingContract(message.info.dest);
-                    }
-                }
+            for await (const tx of txs) {
+                result.push(tx);
             }
             return result;
         });

package/dist/blockchain/SmartContract.d.ts

@@ -55,6 +55,12 @@ export declare class TimeError extends Error {
     currentTime: number;
     constructor(address: Address, previousTxTime: number, currentTime: number);
 }
+export declare class EmulationError extends Error {
+    error: string;
+    vmLogs?: string | undefined;
+    exitCode?: number | undefined;
+    constructor(error: string, vmLogs?: string | undefined, exitCode?: number | undefined);
+}
 export type SmartContractSnapshot = {
     address: Address;
     account: ShardAccount;

package/dist/blockchain/SmartContract.js

@@ -12,7 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _SmartContract_account, _SmartContract_parsedAccount, _SmartContract_lastTxTime, _SmartContract_verbosity;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SmartContract = exports.TimeError = exports.GetMethodError = exports.createEmptyShardAccount = exports.createShardAccount = void 0;
+exports.SmartContract = exports.EmulationError = exports.TimeError = exports.GetMethodError = exports.createEmptyShardAccount = exports.createShardAccount = void 0;
 const core_1 = require("@ton/core");
 const selector_1 = require("../utils/selector");
 function createShardAccount(args) {
@@ -98,6 +98,15 @@ class TimeError extends Error {
     }
 }
 exports.TimeError = TimeError;
+class EmulationError extends Error {
+    constructor(error, vmLogs, exitCode) {
+        super(`Error while executing transaction: ${error}`);
+        this.error = error;
+        this.vmLogs = vmLogs;
+        this.exitCode = exitCode;
+    }
+}
+exports.EmulationError = EmulationError;
 class SmartContract {
     constructor(shardAccount, blockchain) {
         _SmartContract_account.set(this, void 0);
@@ -181,6 +190,11 @@ class SmartContract {
         };
     }
     receiveMessage(message, params) {
+        // Sync now with blockchain instance if not specified in parameters
+        params = {
+            now: this.blockchain.now,
+            ...params,
+        };
         return this.runCommon(() => this.blockchain.executor.runTransaction({
             ...this.createCommonArgs(params),
             message: (0, core_1.beginCell)().store((0, core_1.storeMessage)(message)).endCell(),
@@ -198,8 +212,7 @@ class SmartContract {
             console.log(res.logs);
         }
         if (!res.result.success) {
-            console.error('Error:', res.result.error, 'VM logs', res.result.vmResults);
-            throw new Error('Error executing transaction');
+            throw new EmulationError(res.result.error, res.result.vmResults?.vmLog, res.result.vmResults?.vmExitCode);
         }
         if (this.verbosity.print && this.verbosity.vmLogs !== 'none' && res.result.vmLog.length > 0) {
             console.log(res.result.vmLog);
@@ -249,7 +262,7 @@ class SmartContract {
         if (this.verbosity.print && this.verbosity.debugLogs && res.debugLogs.length > 0) {
             console.log(res.debugLogs);
         }
-        if (res.output.vm_exit_code !== 0) {
+        if (res.output.vm_exit_code !== 0 && res.output.vm_exit_code !== 1) {
             throw new GetMethodError(res.output.vm_exit_code, BigInt(res.output.gas_used), res.logs, res.output.vm_log, res.debugLogs);
         }
         const resStack = (0, core_1.parseTuple)(core_1.Cell.fromBase64(res.output.stack));

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { Blockchain, SendMessageResult, BlockchainTransaction, PendingMessage, S
 export { BlockchainContractProvider, SandboxContractProvider, } from './blockchain/BlockchainContractProvider';
 export { BlockchainSender, } from './blockchain/BlockchainSender';
 export { BlockchainStorage, LocalBlockchainStorage, RemoteBlockchainStorage, RemoteBlockchainStorageClient, wrapTonClient4ForRemote, } from './blockchain/BlockchainStorage';
-export { Verbosity, LogsVerbosity, SmartContract, SmartContractTransaction, MessageParams, GetMethodParams, GetMethodResult, createEmptyShardAccount, createShardAccount, GetMethodError, TimeError, SmartContractSnapshot, } from './blockchain/SmartContract';
+export { Verbosity, LogsVerbosity, SmartContract, SmartContractTransaction, MessageParams, GetMethodParams, GetMethodResult, createEmptyShardAccount, createShardAccount, GetMethodError, TimeError, SmartContractSnapshot, EmulationError, } from './blockchain/SmartContract';
 export { TickOrTock, } from './executor/Executor';
 export { Event, EventAccountCreated, EventAccountDestroyed, EventMessageSent, } from './event/Event';
 export { Treasury, TreasuryContract, } from './treasury/Treasury';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.internal = exports.printTransactionFees = exports.prettyLogTransactions = exports.prettyLogTransaction = exports.TreasuryContract = exports.TimeError = exports.GetMethodError = exports.createShardAccount = exports.createEmptyShardAccount = exports.SmartContract = exports.wrapTonClient4ForRemote = exports.RemoteBlockchainStorage = exports.LocalBlockchainStorage = exports.BlockchainSender = exports.BlockchainContractProvider = exports.Blockchain = exports.defaultConfigSeqno = exports.defaultConfig = void 0;
+exports.internal = exports.printTransactionFees = exports.prettyLogTransactions = exports.prettyLogTransaction = exports.TreasuryContract = exports.EmulationError = exports.TimeError = exports.GetMethodError = exports.createShardAccount = exports.createEmptyShardAccount = exports.SmartContract = exports.wrapTonClient4ForRemote = exports.RemoteBlockchainStorage = exports.LocalBlockchainStorage = exports.BlockchainSender = exports.BlockchainContractProvider = exports.Blockchain = exports.defaultConfigSeqno = exports.defaultConfig = void 0;
 var defaultConfig_1 = require("./config/defaultConfig");
 Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return defaultConfig_1.defaultConfig; } });
 Object.defineProperty(exports, "defaultConfigSeqno", { enumerable: true, get: function () { return defaultConfig_1.defaultConfigSeqno; } });
@@ -20,6 +20,7 @@ Object.defineProperty(exports, "createEmptyShardAccount", { enumerable: true, ge
 Object.defineProperty(exports, "createShardAccount", { enumerable: true, get: function () { return SmartContract_1.createShardAccount; } });
 Object.defineProperty(exports, "GetMethodError", { enumerable: true, get: function () { return SmartContract_1.GetMethodError; } });
 Object.defineProperty(exports, "TimeError", { enumerable: true, get: function () { return SmartContract_1.TimeError; } });
+Object.defineProperty(exports, "EmulationError", { enumerable: true, get: function () { return SmartContract_1.EmulationError; } });
 var Treasury_1 = require("./treasury/Treasury");
 Object.defineProperty(exports, "TreasuryContract", { enumerable: true, get: function () { return Treasury_1.TreasuryContract; } });
 var prettyLogTransaction_1 = require("./utils/prettyLogTransaction");

package/package.json

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