Reference

npm install --save-dev @ton/sandbox @ton/test-utils

class Blockchain {
    static create(opts?: {
        executor?: IExecutor;
        config?: BlockchainConfig;
        storage?: BlockchainStorage;
        meta?: ContractsMeta;
        autoDeployLibs?: boolean;
    }): Promise<Blockchain>

    // Contract and states management
    treasury(seed: string, params?: TreasuryParams): Promise<SandboxContract<TreasuryContract>>
    createWallets(n: number, params?: TreasuryParams): Promise<SandboxContract<TreasuryContract>[]>
    openContract<T extends Contract>(contract: T): SandboxContract<T>
    provider(address: Address, init?: StateInit | null): ContractProvider
    sender(address: Address): Sender
    getContract(address: Address): Promise<SmartContract>
    setShardAccount(address: Address, account: ShardAccount): Promise<void>
    getTransactions(address: Address, opts?: { limit?: number; lt?: string | bigint; hash?: string | Buffer }): Promise<BlockchainTransaction[]>

    // Core messaging methods
    sendMessage(message: Message | Cell, params?: MessageParams): Promise<SendMessageResult>
    sendMessageIter(message: Message | Cell, params?: SendMessageIterParams): Promise<AsyncIterator<BlockchainTransaction> & AsyncIterable<BlockchainTransaction>>
    runGetMethod(address: Address, method: number | string, stack?: TupleItem[], params?: GetMethodParams): Promise<GetMethodResult>
    runTickTock(on: Address | Address[], which: TickOrTock, params?: MessageParams): Promise<SendMessageResult>

    // Snapshotting
    snapshot(): BlockchainSnapshot
    loadFrom(snapshot: BlockchainSnapshot): Promise<void>

    // Coverage
    enableCoverage(enable?: boolean): void
    coverage(contract: Contract): Coverage | undefined
    coverageForCell(code: Cell, address?: Address): Coverage | undefined

    // Debugging
    getDebuggerExecutor(): Promise<Executor>
    get debug(): boolean
    set debug(value: boolean)

    // Configuration methods
    setVerbosityForAddress(address: Address, verbosity: Partial<LogsVerbosity> | Verbosity | undefined): Promise<void>
    setConfig(config: BlockchainConfig): void
    randomize(): Promise<Buffer>

    // Configuration properties
    get now(): number | undefined
    set now(now: number | undefined)
    get lt(): bigint
    get config(): Cell
    get configBase64(): string
    get verbosity(): LogsVerbosity
    set verbosity(value: LogsVerbosity)
    get libs(): Cell | undefined
    set libs(value: Cell | undefined)
    get random(): Buffer | undefined
    set random(value: Buffer | undefined)
    get recordStorage(): boolean
    set recordStorage(v: boolean)
    get autoDeployLibraries(): boolean
    set autoDeployLibraries(value: boolean)
    get prevBlocks(): PrevBlocksInfo | undefined
    set prevBlocks(value: PrevBlocksInfo | undefined)
}

static create(opts?: {
    executor?: IExecutor;
    config?: BlockchainConfig;
    storage?: BlockchainStorage;
    meta?: ContractsMeta;
    autoDeployLibs?: boolean;
}): Promise<Blockchain>

// Basic blockchain
const blockchain = await Blockchain.create();

// With slim config for faster execution
const blockchain = await Blockchain.create({ config: 'slim' });

// With remote storage
const blockchain = await Blockchain.create({
    storage: new RemoteBlockchainStorage(client)
});

// With auto-deploy libraries
const blockchain = await Blockchain.create({
    autoDeployLibs: true
});

treasury(seed: string, params?: TreasuryParams): Promise<SandboxContract<TreasuryContract>>

const deployer = await blockchain.treasury('deployer');
const user = await blockchain.treasury('user', { balance: toNano('100') });

// Same seed creates identical treasury
const wallet1 = await blockchain.treasury('same-seed');
const wallet2 = await blockchain.treasury('same-seed');
// wallet1.address equals wallet2.address

createWallets(n: number, params?: TreasuryParams): Promise<SandboxContract<TreasuryContract>[]>

const [wallet1, wallet2, wallet3] = await blockchain.createWallets(3);

openContract<T extends Contract>(contract: T): SandboxContract<T>

const myContract = blockchain.openContract(MyContract.createFromConfig(config, code));

provider(address: Address, init?: StateInit | null): ContractProvider

const contractProvider = blockchain.provider(address, init);

sender(address: Address): Sender

const sender = blockchain.sender(address);
await contract.send(sender, ...);

getContract(address: Address): Promise<SmartContract>

setShardAccount(address: Address, account: ShardAccount): Promise<void>

getTransactions(address: Address, opts?: {
    limit?: number;
    lt?: string | bigint;
    hash?: string | Buffer;
}): Promise<BlockchainTransaction[]>

const transactions = await blockchain.getTransactions(Address.parse('...'), {
    lt: '1234567890',
    hash: 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
    limit: 10
});

sendMessage(message: Message | Cell, params?: MessageParams): Promise<SendMessageResult>

const result = await blockchain.sendMessage(internal({
    from: sender.address,
    to: contract.address,
    value: toNano('1'),
    body: beginCell().storeUint(0, 32).endCell(),
}));

// Check transactions
expect(result.transactions).toHaveTransaction({
    from: sender.address,
    to: contract.address,
    success: true
});

sendMessageIter(message: Message | Cell, params?: SendMessageIterParams): Promise<AsyncIterator<BlockchainTransaction> & AsyncIterable<BlockchainTransaction>>

const message = internal({
    from: sender.address,
    to: address,
    value: toNano('1'),
    body: beginCell().storeUint(0, 32).endCell(),
});

for await (const tx of await blockchain.sendMessageIter(message, { randomSeed: crypto.randomBytes(32) })) {
    // process transaction
    console.log(tx);
}

runGetMethod(address: Address, method: number | string, stack?: TupleItem[], params?: GetMethodParams): Promise<GetMethodResult>

const { stackReader } = await blockchain.runGetMethod(address, 'get_now', [], {
    now: 2,
});
const now = stackReader.readNumber();

// With method ID
const result = await blockchain.runGetMethod(address, 123, []);

runTickTock(on: Address | Address[], which: TickOrTock, params?: MessageParams): Promise<SendMessageResult>

let res = await blockchain.runTickTock(address, 'tock');

snapshot(): BlockchainSnapshot

const snapshot = blockchain.snapshot();
// some operations
await blockchain.loadFrom(snapshot); // restores blockchain state

loadFrom(snapshot: BlockchainSnapshot): Promise<void>

const snapshot = blockchain.snapshot();
// ... perform operations
await blockchain.loadFrom(snapshot);

enableCoverage(enable?: boolean): void

blockchain.enableCoverage();
// ... execute contract methods
const coverage = blockchain.coverage(contract);

coverage(contract: Contract): Coverage | undefined

blockchain.enableCoverage();
await contract.send(sender, { value: toNano('1') }, 'increment');

const coverage = blockchain.coverage(contract);
const summary = coverage?.summary();
console.log(`Coverage: ${summary?.coveragePercentage?.toFixed(2)}%`);

const htmlReport = coverage?.report("html");
await fs.writeFile("coverage.html", htmlReport);

coverageForCell(code: Cell, address?: Address): Coverage | undefined

blockchain.enableCoverage();
const coverage = blockchain.coverageForCell(codeCell, contractAddress);
const allCoverage = blockchain.coverageForCell(codeCell); // Without address filtering

getDebuggerExecutor(): Promise<Executor>

const debugExecutor = await blockchain.getDebuggerExecutor();
// Use debugExecutor for debugging operations

get debug(): boolean
set debug(value: boolean)

setVerbosityForAddress(address: Address, verbosity: Partial<LogsVerbosity> | Verbosity | undefined): Promise<void>

await blockchain.setVerbosityForAddress(contract.address, {
    blockchainLogs: true,
    vmLogs: 'vm_logs_full'
});

setConfig(config: BlockchainConfig): void

blockchain.setConfig('slim'); // Use slim config for faster execution
blockchain.setConfig(customConfigCell); // Use custom config

randomize(): Promise<Buffer>

const newSeed = await blockchain.randomize();

get now(): number | undefined
set now(now: number | undefined)

// Get current time
const currentTime = blockchain.now;

// Set blockchain time
blockchain.now = Math.floor(Date.now() / 1000);

// Clear time (use system time)
blockchain.now = undefined;

get lt(): bigint

get config(): Cell

get configBase64(): string

get verbosity(): LogsVerbosity
set verbosity(value: LogsVerbosity)

// Get current verbosity
const currentVerbosity = blockchain.verbosity;

// Set verbosity
blockchain.verbosity = {
    print: true,
    blockchainLogs: true,
    vmLogs: 'vm_logs_full',
    debugLogs: true
};

get libs(): Cell | undefined
set libs(value: Cell | undefined)

// Get current libs
const currentLibs = blockchain.libs;

// Set libraries
const libsDict = Dictionary.empty(Dictionary.Keys.Buffer(32), Dictionary.Values.Cell());
libsDict.set(libCell.hash(), libCell);
blockchain.libs = beginCell().storeDictDirect(libsDict).endCell();

get random(): Buffer | undefined
set random(value: Buffer | undefined)

// Get current random seed
const currentSeed = blockchain.random;

// Set random seed
blockchain.random = crypto.randomBytes(32);

get recordStorage(): boolean
set recordStorage(v: boolean)

get autoDeployLibraries(): boolean
set autoDeployLibraries(value: boolean)

get prevBlocks(): PrevBlocksInfo | undefined
set prevBlocks(value: PrevBlocksInfo | undefined)

class TreasuryContract implements Contract {
    static readonly code: Cell;
    static create(workchain: number, subwalletId: bigint): TreasuryContract;
    readonly address: Address;
    readonly init: StateInit;
    readonly subwalletId: bigint;
    constructor(workchain: number, subwalletId: bigint);
    sendMessages(provider: ContractProvider, messages: MessageRelaxed[], sendMode?: SendMode): Promise<void>;
    send(provider: ContractProvider, args: SenderArguments): Promise<void>;
    getSender(provider: ContractProvider): Treasury;
    getBalance(provider: ContractProvider): Promise<bigint>;
    createTransfer(args: {
        messages: MessageRelaxed[];
        sendMode?: SendMode;
    }): Cell;
}

type Treasury = SandboxContract<TreasuryContract>

static readonly code: Cell

static create(workchain: number, subwalletId: bigint): TreasuryContract

readonly address: Address

readonly init: StateInit

readonly subwalletId: bigint

sendMessages(provider: ContractProvider, messages: MessageRelaxed[], sendMode?: SendMode): Promise<void>

send(provider: ContractProvider, args: SenderArguments): Promise<void>

getSender(): Sender

const deployer = await blockchain.treasury('deployer');
const sender = deployer.getSender();

// Sender automatically handles seqno and signing
await contract.sendDeploy(sender, toNano('0.05'));

getBalance(provider: ContractProvider): Promise<bigint>

const treasury = await blockchain.treasury('user');
const balance = await treasury.getBalance();
console.log(`Treasury balance: ${balance} nanoTON`);

createTransfer(args: {
    messages: MessageRelaxed[];
    sendMode?: SendMode;
}): Cell

// Create treasury with default 1M TON balance
const treasury = await blockchain.treasury('user');

// Create treasury with custom balance
const richTreasury = await blockchain.treasury('rich', {
    balance: toNano(10_000_000n)
});

// Use treasury sender for transactions
await contract.sendMessage(treasury.getSender(), toNano('1'), messageBody);

// Treasury handles all operations automatically

class RemoteBlockchainStorage implements BlockchainStorage {
    constructor(client: TonClient4Wrapper, blockSeqno?: number)
}

import { TonClient4 } from '@ton/ton';
import { RemoteBlockchainStorage, wrapTonClient4ForRemote } from '@ton/sandbox';

const blockchain = await Blockchain.create({
    storage: new RemoteBlockchainStorage(
        wrapTonClient4ForRemote(
            new TonClient4({
                endpoint: 'https://mainnet-v4.tonhubapi.com'
            })
        )
    )
});

export type SandboxContract<F> = {
    [P in keyof F]: P extends `${'get' | 'is'}${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];
};

// Open a contract in sandbox
const myContract = blockchain.openContract(MyContract.createFromConfig(config, code));

// Deploy the contract - returns SendMessageResult
const deployResult = await myContract.sendDeploy(deployer.getSender(), toNano('0.05'));
expect(deployResult.transactions).toHaveTransaction({
    from: deployer.address,
    to: myContract.address,
    success: true
});

// Send methods return SendMessageResult with transaction info
const incrementResult = await myContract.sendIncrement(user.getSender(), toNano('0.1'));
expect(incrementResult.transactions).toHaveTransaction({
    from: user.address,
    to: myContract.address,
    success: true
});

// Get methods work the same as production
const counter = await myContract.getCounter();
expect(counter).toBe(1n);

export type SendMessageResult = {
    transactions: BlockchainTransaction[];
    events: Event[];
    externals: ExternalOut[];
};

export type BlockchainTransaction = SmartContractTransaction & {
    events: Event[];
    parent?: BlockchainTransaction;
    children: BlockchainTransaction[];
    externals: ExternalOut[];
    mode?: number;
};

export type MessageParams = Partial<{
    now: number;
    randomSeed: Buffer;
    ignoreChksig: boolean;
}>;

export type GetMethodParams = Partial<{
    now: number;
    randomSeed: Buffer;
    gasLimit: bigint;
}>;

export type GetMethodResult = {
    stack: TupleItem[];
    stackReader: TupleReader;
    exitCode: number;
    gasUsed: bigint;
    blockchainLogs: string;
    vmLogs: string;
    debugLogs: string;
};

export type Verbosity = 'none' | 'vm_logs' | 'vm_logs_location' | 'vm_logs_gas' | 'vm_logs_full' | 'vm_logs_verbose';

export type LogsVerbosity = {
    print: boolean;
    blockchainLogs: boolean;
    vmLogs: Verbosity;
    debugLogs: boolean;
};

export type SmartContractTransaction = Transaction & {
    blockchainLogs: string;
    vmLogs: string;
    debugLogs: string;
    oldStorage?: Cell;
    newStorage?: Cell;
    outActions?: OutAction[];
};

export type BlockchainSnapshot = {
    contracts: SmartContractSnapshot[];
    networkConfig: string;
    lt: bigint;
    time?: number;
    verbosity: LogsVerbosity;
    libs?: Cell;
    nextCreateWalletIndex: number;
    prevBlocksInfo?: PrevBlocksInfo;
    randomSeed?: Buffer;
    autoDeployLibs: boolean;
    transactions: BlockchainTransaction[];
};

export type GetMethodResultSuccess = {
    success: true;
    stack: string;
    gas_used: string;
    vm_exit_code: number;
    vm_log: string;
    missing_library: string | null;
};

export type GetMethodResultError = {
    success: false;
    error: string;
};

export type EventAccountCreated = {
    type: 'account_created';
    account: Address;
};

export type EventAccountDestroyed = {
    type: 'account_destroyed';
    account: Address;
};

export type EventMessageSent = {
    type: 'message_sent';
    from: Address;
    to: Address;
    value: bigint;
    body: Cell;
    bounced: boolean;
};

export type Event = EventAccountCreated | EventAccountDestroyed | EventMessageSent;

export type BlockId = {
    workchain: number;
    shard: bigint;
    seqno: number;
    rootHash: Buffer;
    fileHash: Buffer;
};

export type PrevBlocksInfo = {
    lastMcBlocks: BlockId[];
    prevKeyBlock: BlockId;
    lastMcBlocks100?: BlockId[];
};

export type SerializableSnapshot = {
    contracts: {
        address: string;
        account: string;
        lastTxTime: number;
        verbosity?: Partial<LogsVerbosity>;
    }[];
    networkConfig: string;
    lt: string;
    time?: number;
    verbosity: LogsVerbosity;
    libs?: string;
    nextCreateWalletIndex: number;
    prevBlocksInfo?: {
        lastMcBlocks: SerializableBlockId[];
        prevKeyBlock: SerializableBlockId;
        lastMcBlocks100?: SerializableBlockId[];
    };
    randomSeed?: string;
    autoDeployLibs: boolean;
    transactions: {
        transaction: string;
        blockchainLogs: string;
        vmLogs: string;
        debugLogs: string;
        oldStorage?: string;
        newStorage?: string;
        outActions?: string;
        externals: string[];
        mode?: number;
        parentHash?: string;
        childrenHashes: string[];
    }[];
};

export type ExtraCurrency = {
    [key: number]: bigint;
};

export function loadConfig(configCellOrBase64: string | Cell): BlockchainConfig;

export function updateConfig(config: Cell, ...params: ConfigParam[]): Cell;

export function prettyLogTransaction(tx: Transaction, mapFunc?: AddressMapFunc): string;

export function prettyLogTransactions(txs: Transaction[], mapFunc?: AddressMapFunc): void;

null  ➡️  EQBGhqLAZseEqRXz4ByFPTGV7SVMlI4hrbs-Sps_Xzx01x8G
      ➡️  0.05 💎 EQC2VluVfpj2FoHNMAiDMpcMzwvjLZxxTG8ecq477RE3NvVt

export function internal(params: {
    from: Address;
    to: Address;
    value: bigint;
    body?: Cell;
    stateInit?: StateInit;
    bounce?: boolean;
    bounced?: boolean;
    ihrDisabled?: boolean;
    ihrFee?: bigint;
    forwardFee?: bigint;
    createdAt?: number;
    createdLt?: bigint;
    ec?: Dictionary<number, bigint> | [number, bigint][] | ExtraCurrency;
}): Message;

// Simple internal message
const message = internal({
    from: sender.address,
    to: contract.address,
    value: toNano('1'),
    body: beginCell().storeUint(1, 32).endCell()
});

// Message with stateInit for deployment
const deployMessage = internal({
    from: deployer.address,
    to: contract.address,
    value: toNano('0.05'),
    stateInit: { code, data },
    body: beginCell().endCell()
});

// Non-bounceable message
const nonBounceMessage = internal({
    from: sender.address,
    to: wallet.address,
    value: toNano('0.1'),
    bounce: false
});

export function printTransactionFees(transactions: Transaction[], mapFunc?: OpMapFunc): void;

export function snapshotToSerializable(snapshot: BlockchainSnapshot): SerializableSnapshot;

export function snapshotFromSerializable(serialized: SerializableSnapshot): BlockchainSnapshot;

import { snapshotToSerializable, snapshotFromSerializable } from '@ton/sandbox';
import fs from 'fs';

// Save snapshot to file
const snapshot = blockchain.snapshot();
const serializable = snapshotToSerializable(snapshot);
fs.writeFileSync('snapshot.json', JSON.stringify(serializable));

// Load snapshot from file
const loaded = JSON.parse(fs.readFileSync('snapshot.json', 'utf8'));
const restored = snapshotFromSerializable(loaded);
await blockchain.loadFrom(restored);

export function setGlobalVersion(config: Cell, version: number, capabilites?: bigint): Cell;

export async function fetchConfig(network: 'mainnet' | 'testnet', maxRetries?: number): Promise<Cell>;

export function registerCompiledContract(code: Cell, debugInfo: FuncDebugInfo, marks: Cell): Cell;