Ton Blueprint

Skill is based on Blueprint (ton-org/blueprint), generated at 2026-02-25.

Blueprint is a development environment for the TON blockchain: create projects with npm create ton@latest, then build (Tolk/FunC/Tact), test (Sandbox), and run scripts (deploy via TonConnect, deeplink, or mnemonic). Projects use a fixed layout: contracts/, wrappers/, compilables/, tests/, scripts/, build/.

Core References

Features

Scripts and compilation

Best practices

Generation Info

• Source: sources/ton-blueprint
• Git SHA: 3fec080855a271fe6bb6cf6530c63f37fd761c99
• Generated: 2026-02-25

Deploy Practices

Recommended deploy flow

1. Compile: code = await compile('ContractName'). 2. Build contract instance: Contract.createFromConfig(config, code) (or Tact equivalent). 3. Open with provider: provider.open(contract). 4. Send deploy: contract.sendDeploy(provider.sender(), toNano('0.05')) (or contract-specific method). 5. Wait: await provider.waitForDeploy(contract.address). 6. Use opened contract for getters or further messages.

Avoid the deprecated provider.deploy(contract, value, body, waitAttempts).

Wallet / send options

When running scripts, choose how to sign and send:

• TonConnect (--tonconnect): TON Connect–compatible wallet (e.g. Tonkeeper). Not for custom network.
• Deeplink (--deeplink): Generate ton:// link or QR for signing.
• Mnemonic (--mnemonic): Use env vars so no interactive wallet.

Mnemonic env vars

For --mnemonic (or choosing “Mnemonic” interactively), set in .env:

• Required: WALLET_MNEMONIC (space-separated words), WALLET_VERSION (e.g. v4r1, v5r1).
• Optional: WALLET_ID, SUBWALLET_NUMBER (for v5r1), WALLET_VERSION one of: v1r1, v1r2, v1r3, v2r1, v2r2, v3r1, v3r2, v4r1, v4r2, v5r1.

Example non-interactive: yarn blueprint run deployCounter --testnet --mnemonic.

Custom network and verify

Use blueprint.config.ts network or CLI --custom, --custom-type, --custom-version, --custom-key for custom RPC. For contract verification, custom type must be mainnet or testnet. Example: blueprint verify ... --custom <endpoint> --custom-type mainnet --custom-key <key> --compiler-version 0.4.4-newops.1.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Deploying contracts, Using Mnemonic Provider, Custom network, Contract Verification)

-->

Testing

Tests are in tests/*.spec.ts, use @ton/sandbox (in-process blockchain) and contract wrappers. Run with yarn test or yarn blueprint test; optionally yarn test <CONTRACT>.

Test layout

import { Blockchain, SandboxContract, TreasuryContract } from '@ton/sandbox';
import { Cell, toNano } from '@ton/core';
import { MyContract } from '../wrappers/MyContract';
import '@ton/test-utils';
import { compile } from '@ton/blueprint';

describe('MyContract', () => {
    let code: Cell;

    beforeAll(async () => {
        code = await compile('MyContract');
    });

    let blockchain: Blockchain;
    let deployer: SandboxContract<TreasuryContract>;
    let contract: SandboxContract<MyContract>;

    beforeEach(async () => {
        blockchain = await Blockchain.create();
        contract = blockchain.openContract(MyContract.createFromConfig({}, code));
        deployer = await blockchain.treasury('deployer');

        const result = await contract.sendDeploy(deployer.getSender(), toNano('0.05'));
        expect(result.transactions).toHaveTransaction({
            from: deployer.address,
            to: contract.address,
            deploy: true,
            success: true,
        });
    });

    it('should do something', async () => {
        // use contract.get*(), contract.send*(), expect(...)
    });
});

Patterns

• Use compile('ContractName') once in beforeAll.
• Create Blockchain and blockchain.treasury('deployer') in beforeEach.
• Open contract with blockchain.openContract(Contract.createFromConfig(config, code)).
• Assert deploy with toHaveTransaction({ deploy: true, success: true }) from @ton/test-utils.
• Use wrapper getters and send methods for behavior tests.

Coverage and gas

• Coverage: blueprint test --coverage; output in coverage/.
• Gas report: blueprint test --gas-report (or -g) compares to last snapshot.
• Snapshot: blueprint snapshot [--label=<comment>] saves current gas metrics for later comparison.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Testing contracts, Benchmark contracts)
• https://github.com/ton-org/sandbox (writing tests, benchmark)
• sources/ton-blueprint/src/templates (spec.ts.template)

-->

CLI Commands

Invoke with npx blueprint <command> or yarn blueprint <command>. Commands can be interactive or accept args/flags.

Command list

Run flags

For blueprint run:

• Network: --mainnet, --testnet, --tetra, or --custom <endpoint> with optional --custom-type, --custom-version, --custom-key, --custom-domain, --custom-network-id.
• Wallet: --tonconnect, --deeplink, --mnemonic.
• Explorer: --tonscan, --tonviewer, --toncx, --dton (default: tonscan in code, README says tonviewer).

Script args go after flags: blueprint run deployCounter --testnet --tonconnect arg1 arg2.

Verify flags

• --mainnet / --testnet — network (custom requires --custom-type mainnet/testnet).
• --verifier — verifier ID (default: verifier.ton.org).
• --list-verifiers — list available verifiers.
• --compiler-version — exact compiler version string (e.g. 0.4.4-newops.1); does not change local compiler.
• --custom, --custom-version, --custom-key, --custom-type — custom API for verify.

Plugin commands

Plugins registered in blueprint.config.ts add extra commands; their help is merged into blueprint help.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Features overview, Help and additional commands)
• sources/ton-blueprint/src/cli/cli.ts
• sources/ton-blueprint/src/cli/constants.ts
• sources/ton-blueprint/src/cli/help.ts

-->

Configuration

Create blueprint.config.ts in the project root. Export a named config (not default) of type Config from @ton/blueprint.

import { Config } from '@ton/blueprint';

export const config: Config = {
    // optional fields
};

Options

Custom network

export const config: Config = {
    network: {
        endpoint: 'https://toncenter.com/api/v2/jsonRPC',
        type: 'mainnet',
        version: 'v2',
        key: 'YOUR_API_KEY',
    },
};

Same effect as: blueprint run --custom <endpoint> --custom-type mainnet --custom-version v2 --custom-key <key>.

Liteclient

export const config: Config = {
    network: {
        endpoint: 'https://ton.org/testnet-global.config.json', // mainnet: global.config.json
        version: 'liteclient',
        type: 'testnet',
    },
};

Plugins

import { Config } from '@ton/blueprint';
import { ScaffoldPlugin } from 'blueprint-scaffold';

export const config: Config = {
    plugins: [new ScaffoldPlugin()],
};

Plugins implement Plugin: runners(): PluginRunner[] (name, runner, help).

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Configuration, Plugins, Custom network, Liteclient)
• sources/ton-blueprint/src/config/Config.ts

-->

NetworkProvider

Scripts and deploy flows receive a NetworkProvider from @ton/blueprint. Use it to send transactions, open contracts, and wait for deployment or transaction confirmation.

Getting a provider in scripts

Scripts export run(provider: NetworkProvider, args?: string[]). The CLI passes the provider when you run blueprint run <SCRIPT>.

import { NetworkProvider } from '@ton/blueprint';

export async function run(provider: NetworkProvider, args: string[]) {
    const sender = provider.sender();
    const address = /* ... */;
    await provider.open(MyContract.createFromAddress(address)).send(sender, { value: toNano('0.05') });
    await provider.waitForLastTransaction();
}

Key methods

Deploy pattern

import { toNano } from '@ton/core';
import { compile, NetworkProvider } from '@ton/blueprint';
import { MyContract } from '../wrappers/MyContract';

export async function run(provider: NetworkProvider) {
    const code = await compile('MyContract');
    const contract = provider.open(MyContract.createFromConfig({ /* config */ }, code));
    await contract.sendDeploy(provider.sender(), toNano('0.05'));
    await provider.waitForDeploy(contract.address);
    // use contract...
}

• Prefer the contract’s sendDeploy (or equivalent) plus waitForDeploy; avoid the deprecated provider.deploy().

<!-- Source references:

• https://github.com/ton-org/blueprint (README, NetworkProvider interface in src/network/NetworkProvider.ts)

-->

Project Structure

Blueprint projects follow a fixed layout. Use this when creating or navigating a TON project created with npm create ton@latest.

Directory layout

Conventions

• One contract name maps to: contracts/<Name>.(tolk|fc|tact), a wrapper (or Tact-generated wrapper), and optionally compilables/<Name>.compile.ts (or inside wrappers/).
• Wrappers implement Contract and usually expose createFromAddress, createFromConfig, and sendDeploy (or equivalent).
• Scripts are run with npx blueprint run <SCRIPT> [args...]; the script file must export run(provider: NetworkProvider, args?: string[]).

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Directory structure, Building contracts)

-->

UIProvider

Scripts and CLI runners receive a UIProvider (e.g. InquirerUIProvider) for user interaction. Use it to write messages, prompt for input, or show status instead of hard-coding console.log or readline.

Interface

Usage in scripts

Scripts receive NetworkProvider; get UI via provider.ui():

export async function run(provider: NetworkProvider, args: string[]) {
    const ui = provider.ui();
    ui.write('Deploying contract...');
    ui.setActionPrompt('Waiting for confirmation...');
    // ... send deploy, wait
    ui.clearActionPrompt();
    const ok = await ui.prompt('Open in explorer?');
    if (ok) { /* ... */ }
}

Usage in runners

CLI runners receive (args, ui, runnerContext); use ui for all prompts and output so behavior stays consistent across interactive and non-interactive use.

<!-- Source references:

• sources/ton-blueprint/src/ui/UIProvider.ts
• sources/ton-blueprint/src/network/createNetworkProvider.ts (provider.ui())

-->

Build API

Blueprint exports buildOne, buildAll, and buildAllTact for building contracts from code (e.g. in plugins or custom scripts). The CLI blueprint build uses these internally.

Functions

import { buildOne, buildAll, buildAllTact } from '@ton/blueprint';
import type { UIProvider } from '@ton/blueprint';

// Build a single contract
await buildOne('Counter', ui);

// Build all discovered contracts (wrappers/compilables + Tact projects)
await buildAll(ui);

// Build only Tact contracts (legacy .compile.ts Tact + tact.config.json projects)
await buildAllTact(ui);

• buildOne(contract: string, ui?: UIProvider) — Compiles one contract, writes artifact to build/<contract>.compiled.json, and for FunC/Tolk writes Fift to build/<contract>/<contract>.fif. For Tact, writes generated files from result.fs to disk. Optional ui for progress messages and action prompt.
• buildAll(ui?) — Resolves all contracts via findContracts() (compilables + Tact config) and runs buildOne for each.
• buildAllTact(ui?) — Builds only Tact contracts: those with lang === 'tact' in compilables plus projects from root tact.config.json.

Artifact format

build/<Contract>.compiled.json contains:

• hash — code cell hash (hex).
• hashBase64 — same hash in base64.
• hex — full BOC of the code cell (hex).
• libraryHash, libraryBoc — present only when compiler config has buildLibrary: true.

Tact also writes generated files (wrappers, etc.) under paths from the compiler result; FunC/Tolk write <Contract>.fif into build/<Contract>/.

When to use

• buildAll — Before pack, or when you need every contract built (e.g. CI).
• buildOne — After creating a single new contract (e.g. create runner builds the new Tact contract once).
• buildAllTact — When only Tact contracts need rebuilding.

<!-- Source references:

• sources/ton-blueprint/src/build.ts
• sources/ton-blueprint/src/index.ts (exports)
• sources/ton-blueprint/src/paths.ts (BUILD_DIR)

-->

Compilation

Blueprint compiles Tolk, FunC, and Tact contracts. Use compile() in tests/scripts or the blueprint build CLI.

Programmatic compile

import { compile, getCompilerConfigForContract, CompilerConfig, CompileOpts } from '@ton/blueprint';

// Compile by contract name (resolves .compile.ts or tact.config.json)
const code: Cell = await compile('MyContract');

// With options: hooks user data, debug info, build as library cell
const code2 = await compile('MyContract', {
    hookUserData: { env: 'test' },
    debugInfo: true,
    buildLibrary: true,
});

Contract name must match a compilable: either compilables/<Name>.compile.ts (or under wrappers/ when separateCompilables is false) or a Tact contract with tact.config.json.

Compiler config resolution

• Tact: If getTactConfigForContract(name) finds a Tact config, that is used; Tact puts generated wrappers in build/<name>/.
• FunC/Tolk: Otherwise config is loaded from extractCompilableConfig(path) for <name>.compile.ts in the compilables directory.

import { getCompilerConfigForContract, getCompilablesDirectory } from '@ton/blueprint';

const config = await getCompilerConfigForContract('Counter');
const dir = await getCompilablesDirectory(); // 'compilables' or 'wrappers' per config

CompilerConfig and hooks

Config can be CompilableConfig (FunC/Tolk/Tact legacy) or TactCompilerConfig. Common options:

• preCompileHook(params: HookParams): Promise<void> — runs before compile; params.userData from CompileOpts.hookUserData.
• postCompileHook(code: Cell, params: HookParams): Promise<void> — runs after compile.
• buildLibrary?: boolean — output as library cell (see docs.ton.org library-cells).

Compilable-specific: lang ('func' | 'tolk' | 'tact'), targets, sources, entrypoint, optimizationLevel, etc., depending on language.

Build output

• FunC/Tolk: Build writes artifacts (e.g. to build/); doCompile returns FuncCompileResult / TolkCompileResult with code, version, snapshot, etc.
• Tact: Generated files in build/<Contract>/; result includes fs (virtual files) and .pkg.
• Library cell: Use buildLibrary: true in config or CompileOpts to get a library cell via libraryCellFromCode(code).

Exports

• compile(name, opts?) — returns Promise<Cell> (compiled code).
• doCompile(name, opts?) — returns full result (TactCompileResult | FuncCompileResult | TolkCompileResult).
• getCompilerConfigForContract(name) — returns Promise<CompilerConfig>.
• getCompilablesDirectory() — returns 'compilables' or 'wrappers' per config.separateCompilables.
• libraryCellFromCode(code: Cell) — packs code hash into library cell.
• Types: CompileOpts, HookParams, CompilerConfig, CompilableConfig, TactCompileResult, FuncCompileResult, TolkCompileResult.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Building contracts)
• sources/ton-blueprint/src/compile/compile.ts
• sources/ton-blueprint/src/compile/CompilerConfig.ts
• sources/ton-blueprint/src/index.ts

-->

Pack (publish wrappers)

The blueprint pack command builds all contracts and produces a publish-ready npm package containing wrappers and compiled code. Use it before npm publish when shipping contract interfaces to consumers.

Usage

blueprint pack
blueprint pack --no-warn   # skip confirmation about modifying files

Without --no-warn, the command prompts to confirm because it will modify tsconfig.json, package.json, and remove dist/.

What pack does

1. Build all contracts — runs buildAll(ui) (same as blueprint build --all). 2. Generate `package.ts` — entry point that imports each contract wrapper and exports ContractNameCode (Cell from build/<Contract>.compiled.json). 3. Update `tsconfig.json` — sets outDir: 'dist', declaration: true, esModuleInterop: true, adds package.ts to include. 4. Remove `dist/` and run tsc to compile the package. 5. Update `package.json` — sets main: 'dist/package.js', files: ['dist/**/*'].

Result: a dist/ tree ready for publishing; consumers get wrappers and compiled code cells.

Wrapper path resolution

• FunC/Tolk: wrapper path is ./wrappers/<Contract>.
• Tact: wrapper path is ./<output>/<Contract>_<Contract> (from Tact config, typically build/<Contract>/).

All contracts returned by findContracts() (from compilables/wrappers and Tact config) are included. Each must have a build/<Contract>.compiled.json artifact after build.

When to use

• Before npm publish --access public when publishing a library of TON contract wrappers.
• Ensure tsconfig.json, package.json, and important source files are committed before running; use --no-warn in CI once confident.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Publishing Wrapper Code)
• sources/ton-blueprint/src/cli/pack.ts
• sources/ton-blueprint/src/paths.ts

-->

Plugins

Blueprint supports plugins that add new CLI commands (runners) and help text. Plugins are configured in blueprint.config.ts and run in the same process as built-in commands.

Config

import { Config } from '@ton/blueprint';
import { ScaffoldPlugin } from 'blueprint-scaffold';

export const config: Config = {
    plugins: [new ScaffoldPlugin()],
};

Only named export config is used; do not default-export.

Plugin interface

import type { Plugin, PluginRunner, Runner, RunnerContext, Args } from '@ton/blueprint';

interface Plugin {
    runners(): PluginRunner[];
}

interface PluginRunner {
    name: string;   // command name, e.g. 'scaffold'
    runner: Runner;
    help: string;   // shown in blueprint help <name>
}

type Runner = (
    args: Args,
    ui: UIProvider,
    context: RunnerContext
) => Promise<void>;

interface RunnerContext {
    config?: Config;
}

Plugin commands are merged with built-in ones; duplicate names override (plugin wins). Help for plugin commands is registered so blueprint help <name> shows runner.help.

Implementing a plugin

1. Implement Plugin: return an array of { name, runner, help }. 2. In runner, use args (parsed with argSpec), ui for output/prompts, and context.config for blueprint config. 3. Add the plugin instance to config.plugins in blueprint.config.ts.

Example (pseudo):

import { Plugin, PluginRunner, Args, RunnerContext } from '@ton/blueprint';
import type { UIProvider } from '@ton/blueprint';

class MyPlugin implements Plugin {
    runners(): PluginRunner[] {
        return [{
            name: 'mycommand',
            help: 'Usage: blueprint mycommand [options]\nDoes something useful.',
            runner: this.run.bind(this),
        }];
    }
    private async run(args: Args, ui: UIProvider, context: RunnerContext) {
        ui.write('Running mycommand');
        // context.config?.plugins, context.config?.network, etc.
    }
}

Community plugins

• blueprint-scaffold — generate a simple dapp from wrappers.
• blueprint-misti — integrate Misti static analyzer.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Plugins)
• sources/ton-blueprint/src/config/Plugin.ts
• sources/ton-blueprint/src/cli/Runner.ts
• sources/ton-blueprint/src/cli/cli.ts (loading plugins, effectiveRunners)

-->

Scripts

Scripts live in scripts/ and are executed with npx blueprint run <SCRIPT> [args...]. Each script must export a run function.

Signature

export async function run(provider: NetworkProvider, args: string[]): Promise<void>

• provider: same NetworkProvider used for deploy (sender, open, waitForDeploy, etc.).
• args: CLI arguments after the script name (e.g. blueprint run myScript a b → args = ['a', 'b']).

Shorter form when you don’t need args:

export async function run(provider: NetworkProvider): Promise<void>

Deploy script pattern

Typical deploy script: compile contract, open with config, send deploy, wait for deploy.

import { toNano } from '@ton/core';
import { compile, NetworkProvider } from '@ton/blueprint';
import { Counter } from '../wrappers/Counter';

export async function run(provider: NetworkProvider) {
    const counter = provider.open(
        Counter.createFromConfig(
            { id: Math.floor(Math.random() * 10000), counter: 0 },
            await compile('Counter')
        )
    );
    await counter.sendDeploy(provider.sender(), toNano('0.05'));
    await provider.waitForDeploy(counter.address);
    console.log('ID', await counter.getID());
}

Script with arguments

import { NetworkProvider, sleep } from '@ton/blueprint';

export async function run(provider: NetworkProvider, args: string[]) {
    const contractAddress = args[0];
    if (!contractAddress) {
        provider.ui().write('Usage: blueprint run increment <address>');
        return;
    }
    // ... open contract, send message, optionally waitForLastTransaction()
    await provider.waitForLastTransaction();
}

Run: yarn blueprint run increment EQ... --testnet --tonconnect.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Running scripts, Deploying contracts)
• sources/ton-blueprint/src/templates (deploy and increment script templates)

-->

Contract verification

Blueprint can verify a deployed contract on verifier.ton.org so the source is publicly linked to the on-chain code.

Usage

blueprint verify [ContractName] --mainnet
blueprint verify MyContract --testnet --compiler-version 0.4.4-newops.1
blueprint verify --list-verifiers

If contract name is omitted, an interactive contract selection is shown.

Flags

Flow (agent-oriented)

1. Resolve contract (arg or interactive). 2. Create network provider (no custom network type; mainnet/testnet/tetra allowed). 3. Compile locally with doCompile(selectedContract, { buildLibrary: false }). 4. Get deployed address: prompt user, or lookup by code hash via dton.io GraphQL. 5. Build source payload (Func/Tact/Tolk) and send to verifier backend /source. 6. Collect signatures until verifier quorum; send verification message to verifier registry contract. 7. Output success URL: https://verifier.ton.org/<address>?testnet=true if testnet.

Verifier config is fetched from: https://raw.githubusercontent.com/ton-community/contract-verifier-config/main/config.json. Verifier registry addresses: mainnet EQD-BJSVUJviud_Qv7Ymfd3qzXdrmV525e3YDzWQoHIAiInL, testnet EQCsdKYwUaXkgJkz2l0ol6qT_WxeRbE_wBCwnEybmR0u5TO8.

Custom network and config

When using a custom API for verify, specify --custom-type mainnet or --custom-type testnet; custom type is required. You can use blueprint.config.ts network so that --custom etc. are implied.

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Contract Verification Using Custom Network)
• sources/ton-blueprint/src/cli/verify.ts
• sources/ton-blueprint/src/cli/constants.ts (helpMessages.verify)

-->

Wrappers

Wrappers are TypeScript classes that implement Contract from @ton/core. They provide address/init, message encoding, getters, and a standard deploy helper. Tact generates its own wrappers under build/<CONTRACT>/.

Contract interface (from @ton/core)

• address: Address
• init?: { code: Cell; data: Cell }
• Used with provider.open(contract) and contract.sendDeploy(via, value) (or custom send methods).

Manual wrapper pattern (FunC/Tolk)

import { Address, beginCell, Cell, Contract, contractAddress, ContractProvider, Sender, SendMode } from '@ton/core';

export type CounterConfig = { id: number; counter: number };

export function counterConfigToCell(config: CounterConfig): Cell {
    return beginCell().storeUint(config.id, 32).storeUint(config.counter, 32).endCell();
}

export class Counter implements Contract {
    constructor(readonly address: Address, readonly init?: { code: Cell; data: Cell }) {}

    static createFromAddress(address: Address) {
        return new Counter(address);
    }

    static createFromConfig(config: CounterConfig, code: Cell, workchain = 0) {
        const data = counterConfigToCell(config);
        const init = { code, data };
        return new Counter(contractAddress(workchain, init), init);
    }

    async sendDeploy(provider: ContractProvider, via: Sender, value: bigint) {
        await provider.internal(via, {
            value,
            sendMode: SendMode.PAY_GAS_SEPARATELY,
            body: beginCell().endCell(),
        });
    }

    async getID(provider: ContractProvider) {
        const { stack } = await provider.get('get_id', []);
        return stack.readBigNumber();
    }
}

Usage in tests and scripts

• Tests: blockchain.openContract(Contract.createFromConfig(config, code)) then sendDeploy(deployer.getSender(), toNano('0.05')).
• Scripts: provider.open(Contract.createFromConfig(config, await compile('Contract'))) then contract.sendDeploy(provider.sender(), toNano('0.05')) and provider.waitForDeploy(contract.address).

Tact-generated wrappers follow the same Contract pattern; import from build/<CONTRACT>/tact_<Contract>.ts (or path set in tact.config.json).

<!-- Source references:

• https://github.com/ton-org/blueprint/blob/main/README.md (Directory structure, wrappers)
• sources/ton-blueprint/src/templates (wrapper and deploy templates)

-->