@ton/sandbox 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.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.js

@@ -181,6 +181,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(),
@@ -249,7 +254,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/package.json

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