@ton/sandbox 0.28.0 → 0.29.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.29.0] - 2025-04-30
+
+### Changed
+
+- Updated API docs
+- Updated emulator WASM binary (TON v2025.04)
+
 ## [0.28.0] - 2025-04-01
 
 ### Added

package/dist/blockchain/Blockchain.d.ts

@@ -104,21 +104,27 @@ export declare class Blockchain {
     readonly executor: IExecutor;
     /**
      * Saves snapshot of current blockchain.
-     * ```ts
+     * @example
      * 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}.
+     * Usage provided in {@link Blockchain#snapshot}.
      *
      * @param snapshot Snapshot of blockchain
      */
     loadFrom(snapshot: BlockchainSnapshot): Promise<void>;
     get recordStorage(): boolean;
+    /**
+     * If set to `true`, [BlockchainTransaction]{@link BlockchainTransaction} will have `oldStorage` and `newStorage` fields.
+     *
+     * Note that enabling this flag will disable a certain optimization, which will slow down contract emulation
+     *
+     * @param v
+     */
     set recordStorage(v: boolean);
     /**
      * @returns Current time in blockchain
@@ -148,23 +154,28 @@ export declare class Blockchain {
     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
+     *
+     * @param message Message to send
+     * @param params Optional params
+     * @returns Result of queue processing
+     *
+     * @example
      * 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
+     *
+     * @param message Message to send
+     * @param params Optional params
+     * @returns Async iterable of {@link BlockchainTransaction}
+     *
+     * @example
      * const message = internal({
      *     from: sender.address,
      *     to: address,
@@ -174,39 +185,34 @@ export declare class Blockchain {
      * 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
+     *
+     * @example
+     * let res = await blockchain.runTickTock(address, 'tock');
      */
     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
+     *
+     * @example
+     * const { stackReader } = await blockchain.runGetMethod(address, 'get_now', [], {
+     *     now: 2,
+     * });
+     * const now = res.stackReader.readNumber();
      */
     runGetMethod(address: Address, method: number | string, stack?: TupleItem[], params?: GetMethodParams): Promise<import("./SmartContract").GetMethodResult>;
     protected pushMessage(message: Message | Cell): Promise<void>;
@@ -218,57 +224,59 @@ export declare class Blockchain {
     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
+     *
+     * @example
+     * const contractProvider = blockchain.provider(address, init);
      */
     provider(address: Address, init?: StateInit | null): ContractProvider;
     /**
      * Creates {@link Sender} for address.
-     * ```ts
+     *
+     * Note, that this sender pushes internal messages to Blockchain directly.
+     * No value is deducted from sender address, all the values are set to defaults. Use for test purposes only.
+     *
+     * @example
      * 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
+     * Creates treasury wallet contract. This wallet is used as alternative to wallet smart contract.
+     *
+     * @param {string} seed Initial seed for treasury. If the same seed is used to create a treasury, then these treasuries will be identical
+     * @param {TreasuryParams} params Params for treasury creation. See {@link TreasuryParams} for more information.
+     *
+     * @example
      * 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
+     *
+     * @example
+     * const [wallet1, wallet2, wallet3] = await blockchain.createWallets(3);
      */
     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.
+     *
+     * @example
+     * const contract = blockchain.openContract(new Contract(address));
      */
     openContract<T extends Contract>(contract: T): SandboxContract<T>;
     protected startFetchingContract(address: Address): Promise<SmartContract>;
@@ -286,7 +294,15 @@ export declare class Blockchain {
      * @param {LogsVerbosity} value
      */
     set verbosity(value: LogsVerbosity);
+    /**
+     * Updates logs verbosity level for address.
+     */
     setVerbosityForAddress(address: Address, verbosity: Partial<LogsVerbosity> | Verbosity | undefined): Promise<void>;
+    /**
+     * Updates blockchain config
+     *
+     * @param {BlockchainConfig} config - Custom config in Cell format, or predefined `default` | `slim`
+     */
     setConfig(config: BlockchainConfig): void;
     setShardAccount(address: Address, account: ShardAccount): Promise<void>;
     /**
@@ -295,26 +311,29 @@ export declare class Blockchain {
     get libs(): Cell | undefined;
     /**
      * Update global blockchain libs.
-     * ```ts
+     *
+     * @param value Cell in libs format: Dictionary<CellHash, Cell>
+     *
+     * @example
      * 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
+     *
+     * @param [opts.executor] Custom contract executor. If omitted {@link Executor} is used.
+     * @param [opts.config] Config used in blockchain. If omitted {@link defaultConfig} is used.
+     * @param [opts.storage] Contracts storage used for blockchain. If omitted {@link LocalBlockchainStorage} is used.
+     *
+     * @example
      * const blockchain = await Blockchain.create({ config: 'slim' });
-     * ```
      *
-     * Remote storage example:
-     * ```ts
+     * @example Remote storage
      * let client = new TonClient4({
      *     endpoint: 'https://mainnet-v4.tonhubapi.com'
      * })
@@ -322,11 +341,6 @@ export declare class Blockchain {
      * 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;

package/dist/blockchain/Blockchain.js

@@ -45,11 +45,10 @@ function blockchainConfigToBase64(config) {
 class Blockchain {
     /**
      * Saves snapshot of current blockchain.
-     * ```ts
+     * @example
      * const snapshot = blockchain.snapshot();
      * // some operations
      * await blockchain.loadFrom(snapshot); // restores blockchain state
-     * ```
      */
     snapshot() {
         return {
@@ -64,7 +63,7 @@ class Blockchain {
     }
     /**
      * Restores blockchain state from snapshot.
-     * Usage provided in {@link snapshot}.
+     * Usage provided in {@link Blockchain#snapshot}.
      *
      * @param snapshot Snapshot of blockchain
      */
@@ -85,6 +84,13 @@ class Blockchain {
     get recordStorage() {
         return this.shouldRecordStorage;
     }
+    /**
+     * If set to `true`, [BlockchainTransaction]{@link BlockchainTransaction} will have `oldStorage` and `newStorage` fields.
+     *
+     * Note that enabling this flag will disable a certain optimization, which will slow down contract emulation
+     *
+     * @param v
+     */
     set recordStorage(v) {
         this.shouldRecordStorage = v;
     }
@@ -138,18 +144,18 @@ class Blockchain {
     }
     /**
      * 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
+     *
+     * @param message Message to send
+     * @param params Optional params
+     * @returns Result of queue processing
+     *
+     * @example
      * 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);
@@ -157,7 +163,12 @@ class Blockchain {
     }
     /**
      * 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
+     *
+     * @param message Message to send
+     * @param params Optional params
+     * @returns Async iterable of {@link BlockchainTransaction}
+     *
+     * @example
      * const message = internal({
      *     from: sender.address,
      *     to: address,
@@ -167,11 +178,6 @@ class Blockchain {
      * 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 = {
@@ -184,14 +190,14 @@ class Blockchain {
     }
     /**
      * 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
+     *
+     * @example
+     * let res = await blockchain.runTickTock(address, 'tock');
      */
     async runTickTock(on, which, params) {
         for (const addr of (Array.isArray(on) ? on : [on])) {
@@ -201,18 +207,18 @@ class Blockchain {
     }
     /**
      * 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
+     *
+     * @example
+     * const { stackReader } = await blockchain.runGetMethod(address, 'get_now', [], {
+     *     now: 2,
+     * });
+     * const now = res.stackReader.readNumber();
      */
     async runGetMethod(address, method, stack = [], params) {
         return await (await this.getContract(address)).get(method, stack, {
@@ -329,13 +335,12 @@ class Blockchain {
     }
     /**
      * 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
+     *
+     * @example
+     * const contractProvider = blockchain.provider(address, init);
      */
     provider(address, init) {
         return new BlockchainContractProvider_1.BlockchainContractProvider({
@@ -348,10 +353,13 @@ class Blockchain {
     }
     /**
      * Creates {@link Sender} for address.
-     * ```ts
+     *
+     * Note, that this sender pushes internal messages to Blockchain directly.
+     * No value is deducted from sender address, all the values are set to defaults. Use for test purposes only.
+     *
+     * @example
      * const sender = this.sender(address);
      * await contract.send(sender, ...);
-     * ```
      *
      * @param address Address to create sender for
      */
@@ -364,17 +372,17 @@ class Blockchain {
         return `${workchain}:${seed}`;
     }
     /**
-     * Creates treasury wallet contract. This wallet is used as alternative to wallet-v4 smart contract.
-     * ```ts
+     * Creates treasury wallet contract. This wallet is used as alternative to wallet smart contract.
+     *
+     * @param {string} seed Initial seed for treasury. If the same seed is used to create a treasury, then these treasuries will be identical
+     * @param {TreasuryParams} params Params for treasury creation. See {@link TreasuryParams} for more information.
+     *
+     * @example
      * 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);
@@ -396,12 +404,12 @@ class Blockchain {
     }
     /**
      * 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
+     *
+     * @example
+     * const [wallet1, wallet2, wallet3] = await blockchain.createWallets(3);
      */
     async createWallets(n, params) {
         const wallets = [];
@@ -413,11 +421,11 @@ class Blockchain {
     }
     /**
      * 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.
+     *
+     * @example
+     * const contract = blockchain.openContract(new Contract(address));
      */
     openContract(contract) {
         let address;
@@ -509,10 +517,18 @@ class Blockchain {
     set verbosity(value) {
         this.logsVerbosity = value;
     }
+    /**
+     * Updates logs verbosity level for address.
+     */
     async setVerbosityForAddress(address, verbosity) {
         const contract = await this.getContract(address);
         contract.setVerbosity(verbosity);
     }
+    /**
+     * Updates blockchain config
+     *
+     * @param {BlockchainConfig} config - Custom config in Cell format, or predefined `default` | `slim`
+     */
     setConfig(config) {
         this.networkConfig = blockchainConfigToBase64(config);
     }
@@ -528,28 +544,31 @@ class Blockchain {
     }
     /**
      * Update global blockchain libs.
-     * ```ts
+     *
+     * @param value Cell in libs format: Dictionary<CellHash, Cell>
+     *
+     * @example
      * 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
+     *
+     * @param [opts.executor] Custom contract executor. If omitted {@link Executor} is used.
+     * @param [opts.config] Config used in blockchain. If omitted {@link defaultConfig} is used.
+     * @param [opts.storage] Contracts storage used for blockchain. If omitted {@link LocalBlockchainStorage} is used.
+     *
+     * @example
      * const blockchain = await Blockchain.create({ config: 'slim' });
-     * ```
      *
-     * Remote storage example:
-     * ```ts
+     * @example Remote storage
      * let client = new TonClient4({
      *     endpoint: 'https://mainnet-v4.tonhubapi.com'
      * })
@@ -557,11 +576,6 @@ class Blockchain {
      * 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({

package/dist/blockchain/BlockchainStorage.d.ts

@@ -6,10 +6,28 @@ import { Blockchain } from "./Blockchain";
  * @interface BlockchainStorage Provides information about contracts by blockchain
  */
 export interface BlockchainStorage {
+    /**
+     * Retrieves a smart contract by blockchain and address.
+     *
+     * @param {Blockchain} blockchain - The blockchain instance.
+     * @param {Address} address - The address of the smart contract.
+     * @returns {Promise<SmartContract>} - The smart contract instance.
+     */
     getContract(blockchain: Blockchain, address: Address): Promise<SmartContract>;
+    /**
+     * Lists all known smart contracts.
+     *
+     * @returns {SmartContract[]} - An array of known smart contracts.
+     */
     knownContracts(): SmartContract[];
+    /**
+     * Clears the internal cache of known contracts.
+     */
     clearKnownContracts(): void;
 }
+/**
+ * In-memory storage for blockchain smart contracts.
+ */
 export declare class LocalBlockchainStorage implements BlockchainStorage {
     private contracts;
     getContract(blockchain: Blockchain, address: Address): Promise<SmartContract>;
@@ -30,13 +48,12 @@ export interface RemoteBlockchainStorageClient {
 /**
  * Wraps ton client for remote storage.
  *
- * ```ts
+ * @example
  * let client = new TonClient4({
  *     endpoint: 'https://mainnet-v4.tonhubapi.com'
  * })
  *
  * let remoteStorageClient = wrapTonClient4ForRemote(client);
- * ```
  *
  * @param client TonClient4 to wrap
  */
@@ -70,7 +87,8 @@ export declare function wrapTonClient4ForRemote(client: {
 }): RemoteBlockchainStorageClient;
 /**
  * @class {RemoteBlockchainStorage} Remote blockchain storage implementation.
- * ```ts
+ *
+ * @example
  * let client = new TonClient4({
  *     endpoint: 'https://mainnet-v4.tonhubapi.com'
  * })
@@ -78,7 +96,6 @@ export declare function wrapTonClient4ForRemote(client: {
  * let blockchain = await Blockchain.create({
  *     storage: new RemoteBlockchainStorage(wrapTonClient4ForRemote(client), 34892000)
  * });
- * ```
  */
 export declare class RemoteBlockchainStorage implements BlockchainStorage {
     private contracts;

package/dist/blockchain/BlockchainStorage.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RemoteBlockchainStorage = exports.wrapTonClient4ForRemote = exports.LocalBlockchainStorage = void 0;
 const core_1 = require("@ton/core");
 const SmartContract_1 = require("./SmartContract");
+/**
+ * In-memory storage for blockchain smart contracts.
+ */
 class LocalBlockchainStorage {
     constructor() {
         this.contracts = new Map();
@@ -38,13 +41,12 @@ function convertTonClient4State(state) {
 /**
  * Wraps ton client for remote storage.
  *
- * ```ts
+ * @example
  * let client = new TonClient4({
  *     endpoint: 'https://mainnet-v4.tonhubapi.com'
  * })
  *
  * let remoteStorageClient = wrapTonClient4ForRemote(client);
- * ```
  *
  * @param client TonClient4 to wrap
  */
@@ -70,7 +72,8 @@ function wrapTonClient4ForRemote(client) {
 exports.wrapTonClient4ForRemote = wrapTonClient4ForRemote;
 /**
  * @class {RemoteBlockchainStorage} Remote blockchain storage implementation.
- * ```ts
+ *
+ * @example
  * let client = new TonClient4({
  *     endpoint: 'https://mainnet-v4.tonhubapi.com'
  * })
@@ -78,7 +81,6 @@ exports.wrapTonClient4ForRemote = wrapTonClient4ForRemote;
  * let blockchain = await Blockchain.create({
  *     storage: new RemoteBlockchainStorage(wrapTonClient4ForRemote(client), 34892000)
  * });
- * ```
  */
 class RemoteBlockchainStorage {
     constructor(client, blockSeqno) {