@ton/sandbox 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.20.0] - 2024-05-31
+
+### Added
+
+- Added the ability to create `Blockchain` using a custom `IExecutor` instead of the default `Executor`
+- Added more information to `EmulationError`, extended its error message
+
 ## [0.19.0] - 2024-04-27
 
 ### Fixed

package/README.md

@@ -13,7 +13,9 @@ The key difference of this package from [ton-contract-executor](https://github.c
   * [Test a transaction with matcher](#test-a-transaction-with-matcher)
   * [Testing transaction fees](#testing-transaction-fees)
   * [Cross contract tests](#cross-contract-tests)
+  * [Testing key points](#testing-key-points)
   * [Test examples](#test-examples)
+* [Sandbox pitfalls](#sandbox-pitfalls)
 * [Viewing logs](#viewing-logs)
 * [Setting smart contract state directly](#setting-smart-contract-state-directly)
 * [Using snapshots](#using-snapshots)
@@ -265,6 +267,22 @@ it('minter admin should be able to mint jettons', async () => {
 });
 ```
 
+### Testing key points
+
+In order to make sure that the contract will work as expected, you need to follow the following points in testing
+
+* Test positive flows to make sure your contracts work
+* Test negative flows to make sure that smart contracts behave correctly under abnormal conditions. Abnormal conditions includes:
+  * incorrect input
+  * action list overflow
+  * insufficient toncoin amount
+  * integer overflow
+  * owner assertions
+
+More information about testing key points can be found here: 
+* [Testing key point](docs/testing-key-points.md)
+
+
 ### Test Examples
 You can typically find various tests for Sandbox-based project contracts in the `./tests` directory. 
 Learn more from examples:
@@ -272,6 +290,36 @@ 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) 
 
+
+## Sandbox pitfalls
+
+There are several pitfalls in the sandbox due to the limitations of emulation. Be aware of it while testing your smart contracts.
+
+* Libs cells not updating in contract by `SETLIBCODE`, `CHANGELIB`. They need to be updated manually.
+```typescript
+const blockchain = await Blockchain.create();
+const code = await compile('Contract');
+
+// consist of a hash of a lib cell and its representation
+const libsDict = Dictionary.empty(Dictionary.Keys.Buffer(32), Dictionary.Values.Cell());
+libsDict.set(code.hash(), code);
+
+// manualy set libs
+blockchain.libs = beginCell().storeDictDirect(libsDict).endCell();
+```
+* There is no blocks in emulation, so opcodes like `PREVBLOCKSINFO`, `PREVMCBLOCKS`, `PREVKEYBLOCK`  will return empty tuple.
+* The randomness in the TON is always deterministic and the same randomSeed always gives the same random number sequence. If necessary, you can change the randomSeed to make `RAND` provide result based on provided seed. Currently, there is no way to provide randomSeed in opened contracts.
+```typescript
+const res = await blockchain.runGetMethod(example.address,
+        'get_method',
+        [],
+        { randomSeed: randomBytes(32) }
+);
+const stack = new TupleReader(res.stack);
+// read data from stack ...
+```
+* Because there is no concept of blocks in Sandbox, things like sharding do not work.
+
 ## Viewing logs
 
 `Blockchain` and `SmartContract` use `LogsVerbosity` to determine what kinds of logs to print. Here is the definition:

package/dist/blockchain/Blockchain.d.ts

@@ -1,5 +1,5 @@
 import { Address, Cell, Message, Transaction, ContractProvider, Contract, Sender, ShardAccount, TupleItem, ExternalAddress, StateInit, OpenedContract } from "@ton/core";
-import { Executor, TickOrTock } from "../executor/Executor";
+import { IExecutor, TickOrTock } from "../executor/Executor";
 import { BlockchainStorage } from "./BlockchainStorage";
 import { Event } from "../event/Event";
 import { SandboxContractProvider } from "./BlockchainContractProvider";
@@ -27,6 +27,12 @@ export type BlockchainTransaction = Transaction & {
     children: BlockchainTransaction[];
     externals: ExternalOut[];
 };
+/**
+ * @type SendMessageResult Represents the result of sending a message.
+ * @property {BlockchainTransaction[]} transactions Array of blockchain transactions.
+ * @property {Event[]} events Array of blockchain events.
+ * @property {ExternalOut[]} externals - Array of external messages.
+ */
 export type SendMessageResult = {
     transactions: BlockchainTransaction[];
     events: Event[];
@@ -34,11 +40,20 @@ export type SendMessageResult = {
 };
 type ExtendsContractProvider<T> = T extends ContractProvider ? true : (T extends SandboxContractProvider ? true : false);
 export declare const SANDBOX_CONTRACT_SYMBOL: unique symbol;
+/**
+ * @type SandboxContract Represents a sandbox contract.
+ * @template F Type parameter representing the original contract object.
+ */
 export type SandboxContract<F> = {
     [P in keyof F]: P extends `get${string}` ? (F[P] extends (x: infer CP, ...args: infer P) => infer R ? (ExtendsContractProvider<CP> extends true ? (...args: P) => R : never) : never) : (P extends `send${string}` ? (F[P] extends (x: infer CP, ...args: infer P) => infer R ? (ExtendsContractProvider<CP> extends true ? (...args: P) => Promise<SendMessageResult & {
         result: R extends Promise<infer PR> ? PR : R;
     }> : never) : never) : F[P]);
 };
+/**
+ * Provide way to check if contract is in sandbox environment.
+ * @param contract Any open contract
+ * @throws Error if contract not a sandbox contract
+ */
 export declare function toSandboxContract<T>(contract: OpenedContract<T>): SandboxContract<T>;
 export type PendingMessage = (({
     type: 'message';
@@ -49,6 +64,13 @@ export type PendingMessage = (({
 })) & {
     parentTransaction?: BlockchainTransaction;
 };
+/**
+ * @type TreasuryParams Parameters for configuring a treasury contract.
+ * @property {number} workchain The workchain ID of the treasury.
+ * @property {boolean} predeploy If set the treasury will be deployed on the moment of creation.
+ * @property {bigint} balance Initial balance of the treasury. If omitted 1_000_000 is used.
+ * @property {boolean} resetBalanceIfZero If set and treasury balance is zero on moment of calling method it reset balance to {@link balance}.
+ */
 export type TreasuryParams = Partial<{
     workchain: number;
     predeploy: boolean;
@@ -76,22 +98,111 @@ export declare class Blockchain {
     protected lock: AsyncLock;
     protected contractFetches: Map<string, Promise<SmartContract>>;
     protected nextCreateWalletIndex: number;
-    readonly executor: Executor;
+    readonly executor: IExecutor;
+    /**
+     * Saves snapshot of current blockchain.
+     * ```ts
+     * const snapshot = blockchain.snapshot();
+     * // some operations
+     * await blockchain.loadFrom(snapshot); // restores blockchain state
+     * ```
+     */
     snapshot(): BlockchainSnapshot;
+    /**
+     * Restores blockchain state from snapshot.
+     * Usage provided in {@link snapshot}.
+     *
+     * @param snapshot Snapshot of blockchain
+     */
     loadFrom(snapshot: BlockchainSnapshot): Promise<void>;
+    /**
+     * @returns Current time in blockchain
+     */
     get now(): number | undefined;
+    /**
+     * Updates Current time in blockchain.
+     * @param now UNIX time to set
+     */
     set now(now: number | undefined);
+    /**
+     * @returns Current logical time in blockchain
+     */
     get lt(): bigint;
     protected constructor(opts: {
-        executor: Executor;
+        executor: IExecutor;
         config?: BlockchainConfig;
         storage: BlockchainStorage;
     });
+    /**
+     * @returns Config used in blockchain.
+     */
     get config(): Cell;
+    /**
+     * @returns Config used in blockchain in base64 format.
+     */
     get configBase64(): string;
+    /**
+     * Emulates the result of sending a message to this Blockchain. Emulates the whole chain of transactions before returning the result. Each transaction increases lt by 1000000.
+     * ```ts
+     * const result = await blockchain.sendMessage(internal({
+     *      from: sender.address,
+     *      to: address,
+     *      value: toNano('1'),
+     *      body: beginCell().storeUint(0, 32).endCell(),
+     * }));
+     * ```
+     *
+     * @param message Message to sent
+     * @param params Optional params
+     * @returns Result of queue processing
+     */
     sendMessage(message: Message | Cell, params?: MessageParams): Promise<SendMessageResult>;
+    /**
+     * Starts emulating the result of sending a message to this Blockchain (refer to {@link sendMessage}). Each iterator call emulates one transaction, so the whole chain is not emulated immediately, unlike in {@link sendMessage}.
+     * ```ts
+     * const message = internal({
+     *     from: sender.address,
+     *     to: address,
+     *     value: toNano('1'),
+     *     body: beginCell().storeUint(0, 32).endCell(),
+     * }, { randomSeed: crypto.randomBytes(32) });
+     * for await (const tx of await blockchain.sendMessageIter(message)) {
+     *     // process transaction
+     * }
+     * ```
+     *
+     * @param message Message to sent
+     * @param params Optional params
+     * @returns Async iterable of {@link BlockchainTransaction}
+     */
     sendMessageIter(message: Message | Cell, params?: MessageParams): Promise<AsyncIterator<BlockchainTransaction> & AsyncIterable<BlockchainTransaction>>;
+    /**
+     * Runs tick or tock transaction.
+     * ```ts
+     * let res = await blockchain.runTickTock(address, 'tock');
+     * ```
+     *
+     * @param on Address or addresses to run tick-tock
+     * @param which Type of transaction (tick or tock)
+     * @param [params] Params to run tick tock transaction
+     * @returns Result of tick-tock transaction
+     */
     runTickTock(on: Address | Address[], which: TickOrTock, params?: MessageParams): Promise<SendMessageResult>;
+    /**
+     * Runs get method on contract.
+     * ```ts
+     * const { stackReader } = await blockchain.runGetMethod(address, 'get_now', [], {
+     *     now: 2,
+     * });
+     * const now = res.stackReader.readNumber();
+     * ```
+     *
+     * @param address Address or addresses to run get method
+     * @param method MethodId or method name to run
+     * @param stack Method params
+     * @param [params] Params to run get method
+     * @returns Result of get method
+     */
     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>;
@@ -100,22 +211,120 @@ export declare class Blockchain {
     protected processInternal(params?: MessageParams): Promise<IteratorResult<BlockchainTransaction>>;
     protected processTx(needsLocking: boolean, params?: MessageParams): Promise<IteratorResult<BlockchainTransaction>>;
     protected processQueue(params?: MessageParams): Promise<BlockchainTransaction[]>;
+    /**
+     * Creates new {@link ContractProvider} for contract address.
+     * ```ts
+     * const contractProvider = blockchain.provider(address, init);
+     * const txs = await contractProvider.getTransactions(...);
+     * ```
+     *
+     * @param address Address to create contract provider for
+     * @param init Initial state of contract
+     */
     provider(address: Address, init?: StateInit | null): ContractProvider;
+    /**
+     * Creates {@link Sender} for address.
+     * ```ts
+     * const sender = this.sender(address);
+     * await contract.send(sender, ...);
+     * ```
+     *
+     * @param address Address to create sender for
+     */
     sender(address: Address): Sender;
     protected treasuryParamsToMapKey(workchain: number, seed: string): string;
+    /**
+     * Creates treasury wallet contract. This wallet is used as alternative to wallet-v4 smart contract.
+     * ```ts
+     * const wallet = await blockchain.treasury('wallet')
+     * await wallet.send({
+     *     to: someAddress,
+     *     value: toNano('0.5'),
+     * });
+     * ```
+     *
+     * @param {string} seed Initial seed for treasury. If the same seed is used to create a treasury, then these treasuries will be identical
+     * @param [params] Params for treasury creation. See {@link TreasuryParams} for more information.
+     */
     treasury(seed: string, params?: TreasuryParams): Promise<SandboxContract<TreasuryContract>>;
+    /**
+     * Bulk variant of {@link treasury}.
+     * ```ts
+     * const [wallet1, wallet2, wallet3] = await blockchain.createWallets(3);
+     * ```
+     * @param n Number of wallets to create
+     * @param params Params for treasury creation. See {@link TreasuryParams} for more information.
+     * @returns Array of opened treasury contracts
+     */
     createWallets(n: number, params?: TreasuryParams): Promise<SandboxContract<TreasuryContract>[]>;
+    /**
+     * Opens contract. Returns proxy that substitutes the blockchain Provider in methods starting with get and set.
+     * ```ts
+     * const contract = blockchain.openContract(new Contract(address));
+     * ```
+     *
+     * @param contract Contract to open.
+     */
     openContract<T extends Contract>(contract: T): SandboxContract<T>;
     protected startFetchingContract(address: Address): Promise<SmartContract>;
+    /**
+     * Retrieves {@link SmartContract} from {@link BlockchainStorage}.
+     * @param address Address of contract to get
+     */
     getContract(address: Address): Promise<SmartContract>;
+    /**
+     * @returns {LogsVerbosity} level
+     */
     get verbosity(): LogsVerbosity;
+    /**
+     * Updates logs verbosity level.
+     * @param {LogsVerbosity} value
+     */
     set verbosity(value: LogsVerbosity);
     setVerbosityForAddress(address: Address, verbosity: Partial<LogsVerbosity> | Verbosity | undefined): Promise<void>;
     setConfig(config: BlockchainConfig): void;
     setShardAccount(address: Address, account: ShardAccount): Promise<void>;
+    /**
+     * Retrieves global libs cell
+     */
     get libs(): Cell | undefined;
+    /**
+     * Update global blockchain libs.
+     * ```ts
+     * const code = await compile('Contract');
+     *
+     * const libsDict = Dictionary.empty(Dictionary.Keys.Buffer(32), Dictionary.Values.Cell());
+     * libsDict.set(code.hash(), code);
+     *
+     * blockchain.libs = beginCell().storeDictDirect(libsDict).endCell();
+     * ```
+     *
+     * @param value Cell in libs format: Dictionary<CellHash, Cell>
+     */
     set libs(value: Cell | undefined);
+    /**
+     * Creates instance of sandbox blockchain.
+     * ```ts
+     * const blockchain = await Blockchain.create({ config: 'slim' });
+     * ```
+     *
+     * Remote storage example:
+     * ```ts
+     * let client = new TonClient4({
+     *     endpoint: 'https://mainnet-v4.tonhubapi.com'
+     * })
+     *
+     * let blockchain = await Blockchain.create({
+     *     storage: new RemoteBlockchainStorage(wrapTonClient4ForRemote(client), 34892000)
+     * });
+     * ```
+     *
+     * @param [opts.executor] Custom contract executor. If omitted {@link Executor} used.
+     * @param [opts.config] Config used in blockchain. If omitted {@link defaultConfig} used.
+     * @param [opts.storage] Contracts storage used for blockchain. If omitted {@link LocalBlockchainStorage} used.
+     */
     static create(opts?: {
+        executor?: IExecutor;
         config?: BlockchainConfig;
         storage?: BlockchainStorage;
     }): Promise<Blockchain>;

package/dist/blockchain/Blockchain.js

@@ -19,6 +19,11 @@ function createWalletsSeed(idx) {
 }
 const LT_ALIGN = 1000000n;
 exports.SANDBOX_CONTRACT_SYMBOL = Symbol('SandboxContract');
+/**
+ * Provide way to check if contract is in sandbox environment.
+ * @param contract Any open contract
+ * @throws Error if contract not a sandbox contract
+ */
 function toSandboxContract(contract) {
     if (contract[exports.SANDBOX_CONTRACT_SYMBOL] === true) {
         return contract;
@@ -38,6 +43,14 @@ function blockchainConfigToBase64(config) {
     }
 }
 class Blockchain {
+    /**
+     * Saves snapshot of current blockchain.
+     * ```ts
+     * const snapshot = blockchain.snapshot();
+     * // some operations
+     * await blockchain.loadFrom(snapshot); // restores blockchain state
+     * ```
+     */
     snapshot() {
         return {
             contracts: this.storage.knownContracts().map(s => s.snapshot()),
@@ -49,6 +62,12 @@ class Blockchain {
             nextCreateWalletIndex: this.nextCreateWalletIndex,
         };
     }
+    /**
+     * Restores blockchain state from snapshot.
+     * Usage provided in {@link snapshot}.
+     *
+     * @param snapshot Snapshot of blockchain
+     */
     async loadFrom(snapshot) {
         this.storage.clearKnownContracts();
         for (const contract of snapshot.contracts) {
@@ -62,12 +81,22 @@ class Blockchain {
         this.globalLibs = snapshot.libs;
         this.nextCreateWalletIndex = snapshot.nextCreateWalletIndex;
     }
+    /**
+     * @returns Current time in blockchain
+     */
     get now() {
         return this.currentTime;
     }
+    /**
+     * Updates Current time in blockchain.
+     * @param now UNIX time to set
+     */
     set now(now) {
         this.currentTime = now;
     }
+    /**
+     * @returns Current logical time in blockchain
+     */
     get lt() {
         return this.currentLt;
     }
@@ -87,16 +116,55 @@ class Blockchain {
         this.executor = opts.executor;
         this.storage = opts.storage;
     }
+    /**
+     * @returns Config used in blockchain.
+     */
     get config() {
         return core_1.Cell.fromBase64(this.networkConfig);
     }
+    /**
+     * @returns Config used in blockchain in base64 format.
+     */
     get configBase64() {
         return this.networkConfig;
     }
+    /**
+     * Emulates the result of sending a message to this Blockchain. Emulates the whole chain of transactions before returning the result. Each transaction increases lt by 1000000.
+     * ```ts
+     * const result = await blockchain.sendMessage(internal({
+     *      from: sender.address,
+     *      to: address,
+     *      value: toNano('1'),
+     *      body: beginCell().storeUint(0, 32).endCell(),
+     * }));
+     * ```
+     *
+     * @param message Message to sent
+     * @param params Optional params
+     * @returns Result of queue processing
+     */
     async sendMessage(message, params) {
         await this.pushMessage(message);
         return await this.runQueue(params);
     }
+    /**
+     * Starts emulating the result of sending a message to this Blockchain (refer to {@link sendMessage}). Each iterator call emulates one transaction, so the whole chain is not emulated immediately, unlike in {@link sendMessage}.
+     * ```ts
+     * const message = internal({
+     *     from: sender.address,
+     *     to: address,
+     *     value: toNano('1'),
+     *     body: beginCell().storeUint(0, 32).endCell(),
+     * }, { randomSeed: crypto.randomBytes(32) });
+     * for await (const tx of await blockchain.sendMessageIter(message)) {
+     *     // process transaction
+     * }
+     * ```
+     *
+     * @param message Message to sent
+     * @param params Optional params
+     * @returns Async iterable of {@link BlockchainTransaction}
+     */
     async sendMessageIter(message, params) {
         params = {
             now: this.now,
@@ -106,12 +174,38 @@ class Blockchain {
         // Iterable will lock on per tx basis
         return await this.txIter(true, params);
     }
+    /**
+     * Runs tick or tock transaction.
+     * ```ts
+     * let res = await blockchain.runTickTock(address, 'tock');
+     * ```
+     *
+     * @param on Address or addresses to run tick-tock
+     * @param which Type of transaction (tick or tock)
+     * @param [params] Params to run tick tock transaction
+     * @returns Result of tick-tock transaction
+     */
     async runTickTock(on, which, params) {
         for (const addr of (Array.isArray(on) ? on : [on])) {
             await this.pushTickTock(addr, which);
         }
         return await this.runQueue(params);
     }
+    /**
+     * Runs get method on contract.
+     * ```ts
+     * const { stackReader } = await blockchain.runGetMethod(address, 'get_now', [], {
+     *     now: 2,
+     * });
+     * const now = res.stackReader.readNumber();
+     * ```
+     *
+     * @param address Address or addresses to run get method
+     * @param method MethodId or method name to run
+     * @param stack Method params
+     * @param [params] Params to run get method
+     * @returns Result of get method
+     */
     async runGetMethod(address, method, stack = [], params) {
         return await (await this.getContract(address)).get(method, stack, {
             now: this.now,
@@ -225,6 +319,16 @@ class Blockchain {
             return result;
         });
     }
+    /**
+     * Creates new {@link ContractProvider} for contract address.
+     * ```ts
+     * const contractProvider = blockchain.provider(address, init);
+     * const txs = await contractProvider.getTransactions(...);
+     * ```
+     *
+     * @param address Address to create contract provider for
+     * @param init Initial state of contract
+     */
     provider(address, init) {
         return new BlockchainContractProvider_1.BlockchainContractProvider({
             getContract: (addr) => this.getContract(addr),
@@ -234,6 +338,15 @@ class Blockchain {
             openContract: (contract) => this.openContract(contract),
         }, address, init);
     }
+    /**
+     * Creates {@link Sender} for address.
+     * ```ts
+     * const sender = this.sender(address);
+     * await contract.send(sender, ...);
+     * ```
+     *
+     * @param address Address to create sender for
+     */
     sender(address) {
         return new BlockchainSender_1.BlockchainSender({
             pushMessage: (msg) => this.pushMessage(msg),
@@ -242,6 +355,19 @@ class Blockchain {
     treasuryParamsToMapKey(workchain, seed) {
         return `${workchain}:${seed}`;
     }
+    /**
+     * Creates treasury wallet contract. This wallet is used as alternative to wallet-v4 smart contract.
+     * ```ts
+     * const wallet = await blockchain.treasury('wallet')
+     * await wallet.send({
+     *     to: someAddress,
+     *     value: toNano('0.5'),
+     * });
+     * ```
+     *
+     * @param {string} seed Initial seed for treasury. If the same seed is used to create a treasury, then these treasuries will be identical
+     * @param [params] Params for treasury creation. See {@link TreasuryParams} for more information.
+     */
     async treasury(seed, params) {
         const subwalletId = (0, testTreasurySubwalletId_1.testSubwalletId)(seed);
         const wallet = this.openContract(Treasury_1.TreasuryContract.create(params?.workchain ?? 0, subwalletId));
@@ -260,6 +386,15 @@ class Blockchain {
         }
         return wallet;
     }
+    /**
+     * Bulk variant of {@link treasury}.
+     * ```ts
+     * const [wallet1, wallet2, wallet3] = await blockchain.createWallets(3);
+     * ```
+     * @param n Number of wallets to create
+     * @param params Params for treasury creation. See {@link TreasuryParams} for more information.
+     * @returns Array of opened treasury contracts
+     */
     async createWallets(n, params) {
         const wallets = [];
         for (let i = 0; i < n; i++) {
@@ -268,6 +403,14 @@ class Blockchain {
         }
         return wallets;
     }
+    /**
+     * Opens contract. Returns proxy that substitutes the blockchain Provider in methods starting with get and set.
+     * ```ts
+     * const contract = blockchain.openContract(new Contract(address));
+     * ```
+     *
+     * @param contract Contract to open.
+     */
     openContract(contract) {
         let address;
         let init = undefined;
@@ -329,6 +472,10 @@ class Blockchain {
         this.contractFetches.set(addrString, promise);
         return promise;
     }
+    /**
+     * Retrieves {@link SmartContract} from {@link BlockchainStorage}.
+     * @param address Address of contract to get
+     */
     async getContract(address) {
         try {
             const contract = await this.startFetchingContract(address);
@@ -341,9 +488,16 @@ class Blockchain {
             this.contractFetches.delete(address.toRawString());
         }
     }
+    /**
+     * @returns {LogsVerbosity} level
+     */
     get verbosity() {
         return this.logsVerbosity;
     }
+    /**
+     * Updates logs verbosity level.
+     * @param {LogsVerbosity} value
+     */
     set verbosity(value) {
         this.logsVerbosity = value;
     }
@@ -358,15 +512,52 @@ class Blockchain {
         const contract = await this.getContract(address);
         contract.account = account;
     }
+    /**
+     * Retrieves global libs cell
+     */
     get libs() {
         return this.globalLibs;
     }
+    /**
+     * Update global blockchain libs.
+     * ```ts
+     * const code = await compile('Contract');
+     *
+     * const libsDict = Dictionary.empty(Dictionary.Keys.Buffer(32), Dictionary.Values.Cell());
+     * libsDict.set(code.hash(), code);
+     *
+     * blockchain.libs = beginCell().storeDictDirect(libsDict).endCell();
+     * ```
+     *
+     * @param value Cell in libs format: Dictionary<CellHash, Cell>
+     */
     set libs(value) {
         this.globalLibs = value;
     }
+    /**
+     * Creates instance of sandbox blockchain.
+     * ```ts
+     * const blockchain = await Blockchain.create({ config: 'slim' });
+     * ```
+     *
+     * Remote storage example:
+     * ```ts
+     * let client = new TonClient4({
+     *     endpoint: 'https://mainnet-v4.tonhubapi.com'
+     * })
+     *
+     * let blockchain = await Blockchain.create({
+     *     storage: new RemoteBlockchainStorage(wrapTonClient4ForRemote(client), 34892000)
+     * });
+     * ```
+     *
+     * @param [opts.executor] Custom contract executor. If omitted {@link Executor} used.
+     * @param [opts.config] Config used in blockchain. If omitted {@link defaultConfig} used.
+     * @param [opts.storage] Contracts storage used for blockchain. If omitted {@link LocalBlockchainStorage} used.
+     */
     static async create(opts) {
         return new Blockchain({
-            executor: await Executor_1.Executor.create(),
+            executor: opts?.executor ?? await Executor_1.Executor.create(),
             storage: opts?.storage ?? new BlockchainStorage_1.LocalBlockchainStorage(),
             ...opts
         });

package/dist/blockchain/BlockchainContractProvider.d.ts

@@ -5,6 +5,9 @@ import { GetMethodResult, SmartContract } from "./SmartContract";
 export interface SandboxContractProvider extends ContractProvider {
     tickTock(which: TickOrTock): Promise<void>;
 }
+/**
+ * Provider used in contracts to send messages or invoke getters. For additional information see {@link Blockchain.provider}
+ */
 export declare class BlockchainContractProvider implements SandboxContractProvider {
     private readonly blockchain;
     private readonly address;
@@ -16,16 +19,40 @@ export declare class BlockchainContractProvider implements SandboxContractProvid
         pushTickTock(on: Address, which: TickOrTock): Promise<void>;
         openContract<T extends Contract>(contract: T): OpenedContract<T>;
     }, address: Address, init?: StateInit | null | undefined);
+    /**
+     * Opens contract. For additional information see {@link Blockchain.open}
+     */
     open<T extends Contract>(contract: T): OpenedContract<T>;
     getState(): Promise<ContractState>;
+    /**
+     * Invokes get method.
+     * @param name Name of get method
+     * @param args Args to invoke get method.
+     */
     get(name: string, args: TupleItem[]): Promise<ContractGetMethodResult>;
+    /**
+     * Dummy implementation of getTransactions. Sandbox does not store transactions, so its ContractProvider cannot fetch any.
+     * Throws error in every call.
+     *
+     * @throws {Error}
+     */
     getTransactions(address: Address, lt: bigint, hash: Buffer, limit?: number | undefined): Promise<Transaction[]>;
+    /**
+     * Pushes external-in message to message queue.
+     * @param message Message to push
+     */
     external(message: Cell): Promise<void>;
+    /**
+     * Pushes internal message to message queue.
+     */
     internal(via: Sender, args: {
         value: string | bigint;
         bounce?: boolean | null;
         sendMode?: SendMode;
         body?: string | Cell | null;
     }): Promise<void>;
+    /**
+     * Pushes tick-tock message to message queue.
+     */
     tickTock(which: TickOrTock): Promise<void>;
 }

package/dist/blockchain/BlockchainContractProvider.js

@@ -32,12 +32,18 @@ function convertState(state) {
             };
     }
 }
+/**
+ * Provider used in contracts to send messages or invoke getters. For additional information see {@link Blockchain.provider}
+ */
 class BlockchainContractProvider {
     constructor(blockchain, address, init) {
         this.blockchain = blockchain;
         this.address = address;
         this.init = init;
     }
+    /**
+     * Opens contract. For additional information see {@link Blockchain.open}
+     */
     open(contract) {
         return this.blockchain.openContract(contract);
     }
@@ -52,6 +58,11 @@ class BlockchainContractProvider {
             state: convertState(contract.accountState),
         };
     }
+    /**
+     * Invokes get method.
+     * @param name Name of get method
+     * @param args Args to invoke get method.
+     */
     async get(name, args) {
         const result = await this.blockchain.runGetMethod(this.address, name, args);
         const ret = {
@@ -63,9 +74,19 @@ class BlockchainContractProvider {
         delete ret.stackReader;
         return ret;
     }
+    /**
+     * Dummy implementation of getTransactions. Sandbox does not store transactions, so its ContractProvider cannot fetch any.
+     * Throws error in every call.
+     *
+     * @throws {Error}
+     */
     getTransactions(address, lt, hash, limit) {
         throw new Error("`getTransactions` is not implemented in `BlockchainContractProvider`, do not use it in the tests");
     }
+    /**
+     * Pushes external-in message to message queue.
+     * @param message Message to push
+     */
     async external(message) {
         const init = ((await this.getState()).state.type !== 'active' && this.init) ? this.init : undefined;
         await this.blockchain.pushMessage({
@@ -78,6 +99,9 @@ class BlockchainContractProvider {
             body: message,
         });
     }
+    /**
+     * Pushes internal message to message queue.
+     */
     async internal(via, args) {
         const init = ((await this.getState()).state.type !== 'active' && this.init) ? this.init : undefined;
         const bounce = (args.bounce !== null && args.bounce !== undefined) ? args.bounce : true;
@@ -92,6 +116,9 @@ class BlockchainContractProvider {
             body,
         });
     }
+    /**
+     * Pushes tick-tock message to message queue.
+     */
     async tickTock(which) {
         await this.blockchain.pushTickTock(this.address, which);
     }

package/dist/blockchain/BlockchainSender.d.ts

@@ -1,4 +1,7 @@
 import { Address, Message, Sender, SenderArguments } from "@ton/core";
+/**
+ * Sender for sandbox blockchain. For additional information see {@link Blockchain.sender}
+ */
 export declare class BlockchainSender implements Sender {
     private readonly blockchain;
     readonly address: Address;

package/dist/blockchain/BlockchainSender.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BlockchainSender = void 0;
 const core_1 = require("@ton/core");
+/**
+ * Sender for sandbox blockchain. For additional information see {@link Blockchain.sender}
+ */
 class BlockchainSender {
     constructor(blockchain, address) {
         this.blockchain = blockchain;

package/dist/blockchain/BlockchainStorage.d.ts

@@ -2,6 +2,9 @@
 import { AccountState, Address } from "@ton/core";
 import { SmartContract } from "./SmartContract";
 import { Blockchain } from "./Blockchain";
+/**
+ * @interface BlockchainStorage Provides information about contracts by blockchain
+ */
 export interface BlockchainStorage {
     getContract(blockchain: Blockchain, address: Address): Promise<SmartContract>;
     knownContracts(): SmartContract[];
@@ -24,6 +27,19 @@ export interface RemoteBlockchainStorageClient {
         };
     }>;
 }
+/**
+ * Wraps ton client for remote storage.
+ *
+ * ```ts
+ * let client = new TonClient4({
+ *     endpoint: 'https://mainnet-v4.tonhubapi.com'
+ * })
+ *
+ * let remoteStorageClient = wrapTonClient4ForRemote(client);
+ * ```
+ *
+ * @param client TonClient4 to wrap
+ */
 export declare function wrapTonClient4ForRemote(client: {
     getLastBlock(): Promise<{
         last: {
@@ -52,6 +68,18 @@ export declare function wrapTonClient4ForRemote(client: {
         };
     }>;
 }): RemoteBlockchainStorageClient;
+/**
+ * @class {RemoteBlockchainStorage} Remote blockchain storage implementation.
+ * ```ts
+ * let client = new TonClient4({
+ *     endpoint: 'https://mainnet-v4.tonhubapi.com'
+ * })
+ *
+ * let blockchain = await Blockchain.create({
+ *     storage: new RemoteBlockchainStorage(wrapTonClient4ForRemote(client), 34892000)
+ * });
+ * ```
+ */
 export declare class RemoteBlockchainStorage implements BlockchainStorage {
     private contracts;
     private client;

package/dist/blockchain/BlockchainStorage.js

@@ -35,6 +35,19 @@ function convertTonClient4State(state) {
             throw new Error(`Unknown type ${state}`);
     }
 }
+/**
+ * Wraps ton client for remote storage.
+ *
+ * ```ts
+ * let client = new TonClient4({
+ *     endpoint: 'https://mainnet-v4.tonhubapi.com'
+ * })
+ *
+ * let remoteStorageClient = wrapTonClient4ForRemote(client);
+ * ```
+ *
+ * @param client TonClient4 to wrap
+ */
 function wrapTonClient4ForRemote(client) {
     return {
         getLastBlockSeqno: async () => {
@@ -55,6 +68,18 @@ function wrapTonClient4ForRemote(client) {
     };
 }
 exports.wrapTonClient4ForRemote = wrapTonClient4ForRemote;
+/**
+ * @class {RemoteBlockchainStorage} Remote blockchain storage implementation.
+ * ```ts
+ * let client = new TonClient4({
+ *     endpoint: 'https://mainnet-v4.tonhubapi.com'
+ * })
+ *
+ * let blockchain = await Blockchain.create({
+ *     storage: new RemoteBlockchainStorage(wrapTonClient4ForRemote(client), 34892000)
+ * });
+ * ```
+ */
 class RemoteBlockchainStorage {
     constructor(client, blockSeqno) {
         this.contracts = new Map();

package/dist/blockchain/SmartContract.d.ts

@@ -59,7 +59,9 @@ export declare class EmulationError extends Error {
     error: string;
     vmLogs?: string | undefined;
     exitCode?: number | undefined;
-    constructor(error: string, vmLogs?: string | undefined, exitCode?: number | undefined);
+    blockchainLogs?: string | undefined;
+    debugLogs?: string | undefined;
+    constructor(error: string, vmLogs?: string | undefined, exitCode?: number | undefined, blockchainLogs?: string | undefined, debugLogs?: string | undefined);
 }
 export type SmartContractSnapshot = {
     address: Address;

package/dist/blockchain/SmartContract.js

@@ -99,11 +99,26 @@ class TimeError extends Error {
 }
 exports.TimeError = TimeError;
 class EmulationError extends Error {
-    constructor(error, vmLogs, exitCode) {
-        super(`Error while executing transaction: ${error}`);
+    constructor(error, vmLogs, exitCode, blockchainLogs, debugLogs) {
+        let errMsg = `Error while executing transaction: ${error}`;
+        if (exitCode !== undefined) {
+            errMsg += `\nExit code: ${exitCode}`;
+        }
+        if (vmLogs !== undefined) {
+            errMsg += `\nVM logs:\n${vmLogs}`;
+        }
+        if (blockchainLogs !== undefined) {
+            errMsg += `\nBlockchain logs:\n${blockchainLogs}`;
+        }
+        if (debugLogs !== undefined) {
+            errMsg += `\nDebug logs:\n${debugLogs}`;
+        }
+        super(errMsg);
         this.error = error;
         this.vmLogs = vmLogs;
         this.exitCode = exitCode;
+        this.blockchainLogs = blockchainLogs;
+        this.debugLogs = debugLogs;
     }
 }
 exports.EmulationError = EmulationError;
@@ -212,7 +227,7 @@ class SmartContract {
             console.log(res.logs);
         }
         if (!res.result.success) {
-            throw new EmulationError(res.result.error, res.result.vmResults?.vmLog, res.result.vmResults?.vmExitCode);
+            throw new EmulationError(res.result.error, res.result.vmResults?.vmLog, res.result.vmResults?.vmExitCode, res.logs.length === 0 ? undefined : res.logs, res.debugLogs.length === 0 ? undefined : res.debugLogs);
         }
         if (this.verbosity.print && this.verbosity.vmLogs !== 'none' && res.result.vmLog.length > 0) {
             console.log(res.result.vmLog);

package/dist/treasury/Treasury.d.ts

@@ -2,6 +2,9 @@ import { Address, Cell, Contract, ContractProvider, MessageRelaxed, Sender, Send
 export type Treasury = Sender & {
     address: Address;
 };
+/**
+ * @class TreasuryContract is Wallet v4 alternative. For additional information see {@link Blockchain.treasury}
+ */
 export declare class TreasuryContract implements Contract {
     static readonly code: Cell;
     static create(workchain: number, subwalletId: bigint): TreasuryContract;
@@ -9,10 +12,27 @@ export declare class TreasuryContract implements Contract {
     readonly init: StateInit;
     readonly subwalletId: bigint;
     constructor(workchain: number, subwalletId: bigint);
+    /**
+     * Send bulk messages using one external message.
+     * @param messages Messages to send
+     * @param sendMode Send mode of every message
+     */
     sendMessages(provider: ContractProvider, messages: MessageRelaxed[], sendMode?: SendMode): Promise<void>;
+    /**
+     * Sends message by arguments specified.
+     */
     send(provider: ContractProvider, args: SenderArguments): Promise<void>;
+    /**
+     * @returns Sender
+     */
     getSender(provider: ContractProvider): Treasury;
+    /**
+     * @returns wallet balance in nanoTONs
+     */
     getBalance(provider: ContractProvider): Promise<bigint>;
+    /**
+     * Creates transfer cell for {@link sendMessages}.
+     */
     createTransfer(args: {
         messages: MessageRelaxed[];
         sendMode?: SendMode;

package/dist/treasury/Treasury.js

@@ -22,6 +22,9 @@ function senderArgsToMessageRelaxed(args) {
         bounce: args.bounce
     });
 }
+/**
+ * @class TreasuryContract is Wallet v4 alternative. For additional information see {@link Blockchain.treasury}
+ */
 class TreasuryContract {
     static create(workchain, subwalletId) {
         return new TreasuryContract(workchain, subwalletId);
@@ -34,6 +37,11 @@ class TreasuryContract {
         this.address = (0, core_1.contractAddress)(workchain, this.init);
         this.subwalletId = subwalletId;
     }
+    /**
+     * Send bulk messages using one external message.
+     * @param messages Messages to send
+     * @param sendMode Send mode of every message
+     */
     async sendMessages(provider, messages, sendMode) {
         let transfer = this.createTransfer({
             sendMode: sendMode,
@@ -41,9 +49,15 @@ class TreasuryContract {
         });
         await provider.external(transfer);
     }
+    /**
+     * Sends message by arguments specified.
+     */
     async send(provider, args) {
         await this.sendMessages(provider, [senderArgsToMessageRelaxed(args)], args.sendMode ?? undefined);
     }
+    /**
+     * @returns Sender
+     */
     getSender(provider) {
         return {
             address: this.address,
@@ -56,9 +70,15 @@ class TreasuryContract {
             }
         };
     }
+    /**
+     * @returns wallet balance in nanoTONs
+     */
     async getBalance(provider) {
         return (await provider.getState()).balance;
     }
+    /**
+     * Creates transfer cell for {@link sendMessages}.
+     */
     createTransfer(args) {
         let sendMode = core_1.SendMode.PAY_GAS_SEPARATELY;
         if (args.sendMode !== null && args.sendMode !== undefined) {

package/dist/utils/message.d.ts

@@ -1,4 +1,7 @@
 import { Address, Cell, Message, StateInit } from "@ton/core";
+/**
+ * Creates {@link Message} from params.
+ */
 export declare function internal(params: {
     from: Address;
     to: Address;

package/dist/utils/message.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.internal = void 0;
 const core_1 = require("@ton/core");
+/**
+ * Creates {@link Message} from params.
+ */
 function internal(params) {
     return {
         info: {

package/dist/utils/prettyLogTransaction.d.ts

@@ -1,3 +1,16 @@
 import { Transaction } from "@ton/core";
+/**
+ * @param tx Transaction to create log string
+ * @returns Transaction log string
+ */
 export declare function prettyLogTransaction(tx: Transaction): string;
+/**
+ * Log transaction using `console.log`. Logs base on result of {@link prettyLogTransaction}.
+ * Example output:
+ * ```
+ * null  ➡️  EQBGhqLAZseEqRXz4ByFPTGV7SVMlI4hrbs-Sps_Xzx01x8G
+ *       ➡️  0.05 💎 EQC2VluVfpj2FoHNMAiDMpcMzwvjLZxxTG8ecq477RE3NvVt
+ * ```
+ * @param txs Transactions to log
+ */
 export declare function prettyLogTransactions(txs: Transaction[]): void;

package/dist/utils/prettyLogTransaction.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prettyLogTransactions = exports.prettyLogTransaction = void 0;
 const core_1 = require("@ton/core");
+/**
+ * @param tx Transaction to create log string
+ * @returns Transaction log string
+ */
 function prettyLogTransaction(tx) {
     let res = `${tx.inMessage?.info.src}  ➡️  ${tx.inMessage?.info.dest}\n`;
     for (let message of tx.outMessages.values()) {
@@ -15,6 +19,15 @@ function prettyLogTransaction(tx) {
     return res;
 }
 exports.prettyLogTransaction = prettyLogTransaction;
+/**
+ * Log transaction using `console.log`. Logs base on result of {@link prettyLogTransaction}.
+ * Example output:
+ * ```
+ * null  ➡️  EQBGhqLAZseEqRXz4ByFPTGV7SVMlI4hrbs-Sps_Xzx01x8G
+ *       ➡️  0.05 💎 EQC2VluVfpj2FoHNMAiDMpcMzwvjLZxxTG8ecq477RE3NvVt
+ * ```
+ * @param txs Transactions to log
+ */
 function prettyLogTransactions(txs) {
     let out = '';
     for (let tx of txs) {

package/dist/utils/printTransactionFees.d.ts

@@ -1,3 +1,16 @@
 import { Transaction } from "@ton/core";
 export declare function formatCoinsPure(value: bigint, precision?: number): string;
+/**
+ * Prints transaction fees.
+ * Example output:
+ * ```
+ * ┌─────────┬─────────────┬────────────────┬────────────────┬────────────────┬────────────────┬───────────────┬────────────┬────────────────┬──────────┬────────────┐
+ * │ (index) │ op          │ valueIn        │ valueOut       │ totalFees      │ inForwardFee   │ outForwardFee │ outActions │ computeFee     │ exitCode │ actionCode │
+ * ├─────────┼─────────────┼────────────────┼────────────────┼────────────────┼────────────────┼───────────────┼────────────┼────────────────┼──────────┼────────────┤
+ * │ 0       │ 'N/A'       │ 'N/A'          │ '1000 TON'     │ '0.004007 TON' │ 'N/A'          │ '0.001 TON'   │ 1          │ '0.001937 TON' │ 0        │ 0          │
+ * │ 1       │ '0x45ab564' │ '1000 TON'     │ '998.8485 TON' │ '1.051473 TON' │ '0.000667 TON' │ '0.255 TON'   │ 255        │ '0.966474 TON' │ 0        │ 0          │
+ * │ 2       │ '0x0'       │ '3.917053 TON' │ '0 TON'        │ '0.00031 TON'  │ '0.000667 TON' │ 'N/A'         │ 0          │ '0.000309 TON' │ 0        │ 0          │
+ * ```
+ * @param transactions List of transaction to print fees
+ */
 export declare function printTransactionFees(transactions: Transaction[]): void;

package/dist/utils/printTransactionFees.js

@@ -30,6 +30,19 @@ function formatCoins(value, precision = 6) {
         return 'N/A';
     return formatCoinsPure(value, precision) + ' TON';
 }
+/**
+ * Prints transaction fees.
+ * Example output:
+ * ```
+ * ┌─────────┬─────────────┬────────────────┬────────────────┬────────────────┬────────────────┬───────────────┬────────────┬────────────────┬──────────┬────────────┐
+ * │ (index) │ op          │ valueIn        │ valueOut       │ totalFees      │ inForwardFee   │ outForwardFee │ outActions │ computeFee     │ exitCode │ actionCode │
+ * ├─────────┼─────────────┼────────────────┼────────────────┼────────────────┼────────────────┼───────────────┼────────────┼────────────────┼──────────┼────────────┤
+ * │ 0       │ 'N/A'       │ 'N/A'          │ '1000 TON'     │ '0.004007 TON' │ 'N/A'          │ '0.001 TON'   │ 1          │ '0.001937 TON' │ 0        │ 0          │
+ * │ 1       │ '0x45ab564' │ '1000 TON'     │ '998.8485 TON' │ '1.051473 TON' │ '0.000667 TON' │ '0.255 TON'   │ 255        │ '0.966474 TON' │ 0        │ 0          │
+ * │ 2       │ '0x0'       │ '3.917053 TON' │ '0 TON'        │ '0.00031 TON'  │ '0.000667 TON' │ 'N/A'         │ 0          │ '0.000309 TON' │ 0        │ 0          │
+ * ```
+ * @param transactions List of transaction to print fees
+ */
 function printTransactionFees(transactions) {
     console.table(transactions
         .map((tx) => {

package/package.json

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