TON Sandbox

The recommended way to interact with contracts in Sandbox is to implement the Contract interface from @ton/core and then use blockchain.openContract to create a proxy wrapper.

The Proxy Wrapper Behavior

When you "open" a contract instance using blockchain.openContract(contractInstance):

1. Automatic Provider Injection: All methods starting with get or send will automatically receive a ContractProvider as their first argument. You do not need to pass it manually when calling methods on the opened instance.
2. Promisified send methods: Methods starting with send are promisified. They return an object containing the original method's result in a result field, along with the results of running the blockchain message queue.
3. Direct get methods: Methods starting with get return the original result as-is to the caller.

Implementation Requirements

• Method Signatures: Every get or send method in your contract class MUST accept provider: ContractProvider as the first argument, even if the method body does not use it. This is required for the proxy wrapper to function.
• Method Constraints:
  • Inside a send method, ideally make at most one call to provider.internal or provider.external.
  • Never make calls to provider.external or provider.internal inside a get method; doing so will cause incorrect results in subsequent send calls.

// Example of a contract implementation compatible with Sandbox wrappers
import { Address, beginCell, Cell, Contract, ContractProvider, Sender, toNano, Builder } from "@ton/core";

class NftItem implements Contract {
    // Must accept provider as first argument
    async sendTransfer(provider: ContractProvider, via: Sender, params: { 
        value?: bigint, 
        to: Address 
    }) {
        await provider.internal(via, {
            value: params.value ?? toNano('0.05'),
            body: beginCell().storeUint(0x5fcc3d14, 32).endCell()
        });
    }

    // Must accept provider as first argument
    async getData(provider: ContractProvider) {
        const { stack } = await provider.get('get_nft_data', []);
        return stack.readBoolean();
    }
}

// Usage in a test
const nftItem = await blockchain.openContract(new NftItem(address, init));
await nftItem.sendTransfer(treasury.getSender(), { to: recipient }); // provider is injected automatically

You can capture the entire state of a Blockchain instance (including all contracts, network config, transaction lt, unix timestamp, verbosity, and libraries) and restore it later. This is useful for resetting tests to a known configuration point.

Basic usage:

const snapshot = blockchain.snapshot();
// ... later ...
await blockchain.loadFrom(snapshot);

Serializing snapshots for disk/network storage: Since snapshots contain Cells and Buffers which are not JSON-safe, use snapshotToSerializable and snapshotFromSerializable to convert them to plain JSON objects.

import { snapshotToSerializable, snapshotFromSerializable } from './BlockchainSnapshot';

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

// Restore from disk
const snapshotJson = JSON.parse(fs.readFileSync('snapshot.json', 'utf8'));
await blockchain.loadFrom(snapshotFromSerializable(snapshotJson));

import { snapshotToSerializable, snapshotFromSerializable } from './BlockchainSnapshot';

// Capture and serialize
const serializable = snapshotToSerializable(blockchain.snapshot());

// Restore from serialized object
const restored = snapshotFromSerializable(serializable);
await blockchain.loadFrom(restored);

You can use Sandbox to test against contracts deployed on a real network (e.g., mainnet) by using RemoteBlockchainStorage. When the Blockchain instance encounters an unknown contract, it will pull its state from the remote network.

Note: This only applies to unknown contracts. If a contract's state has already been set locally (via creation, manual setting, or previous retrieval), it will not be re-read from the network.

import { TonClient4 } from '@ton/ton'
import { Blockchain, RemoteBlockchainStorage, wrapTonClient4ForRemote } from '@ton/sandbox'
import { getHttpV4Endpoint } from '@orbs-network/ton-access'

const blockchain = await Blockchain.create({
    storage: new RemoteBlockchainStorage(wrapTonClient4ForRemote(new TonClient4({
        endpoint: await getHttpV4Endpoint({
            network: 'mainnet'
        })
    })))
})

To pull state from a specific block number instead of the latest, pass blockSeqno as the second argument to the RemoteBlockchainStorage constructor.