@ton/sandbox 0.19.0 → 0.21.0-beta.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
         });