Skip to main content
Blueprint is a CLI tool for TON smart contract development. This reference covers all available commands, options, configuration, and API methods.

Quick navigation

CLI commands

  • create — create new contracts from templates
  • build — build contracts
  • run — execute deployment and custom scripts
  • test — run test suites
  • verify — verify contracts using TON Contract Verifier.
  • help — display command help information
  • set — configure language version
  • convert — convert legacy build scripts
  • rename — rename contracts across the project
  • pack — package contracts for deployment
  • snapshot — create gas usage snapshots

API reference

Configuration

CLI commands

Blueprint provides a comprehensive set of CLI commands for smart contract development, testing, and deployment. Commands support both interactive and non-interactive modes.

create

Creates a new smart contract with all necessary files including the contract source, TypeScript wrapper, test file, and deployment script.

Interactive mode

Launches an interactive wizard that guides you through:
  1. Contract name selection (validates CamelCase format)
  2. Programming language choice (Tolk, FunC, or Tact)
  3. Template type selection (empty or counter example)

Non-interactive mode

Parameters:
  • <CONTRACT> — contract name in CamelCase format (e.g., MyAwesomeContract)
  • <TYPE> — template type from available options
Available template types:
  • tolk-empty — an empty contract (Tolk)
  • func-empty — an empty contract (FunC)
  • tact-empty — an empty contract (Tact)
  • tolk-counter — a simple counter contract (Tolk)
  • func-counter — a simple counter contract (FunC)
  • tact-counter — a simple counter contract (Tact)
Usage examples:
Generated files:
  • contracts/MyContract.{tolk|fc|tact} — contract source code
  • wrappers/MyContract.ts — TypeScript wrapper for contract interaction
  • tests/MyContract.spec.ts — Jest test suite with basic test cases
  • scripts/deployMyContract.ts — deployment script with network configuration

build

Compiles smart contracts using their corresponding .compile.ts configuration files.

Interactive mode

Displays a list of all available contracts with .compile.ts files for selection. Shows compilation status and allows building individual contracts or all at once.

Non-interactive mode

Parameters:
  • <CONTRACT> — specific contract name to build (matches the .compile.ts filename)
  • --all — build all contracts in the project that have compilation configurations
Usage examples:
For detailed information about build artifacts, see Compiled Artifacts.

run

Executes TypeScript scripts from the scripts/ directory with full network provider access. Commonly used for contract deployment, interaction, and maintenance tasks.

Interactive mode

Displays a list of all available scripts in the scripts/ directory to select from.

Non-interactive mode

Parameters:
  • <SCRIPT> — script name (without .ts extension)
  • <ARGS...> — optional arguments passed to the script
  • --<NETWORK> — network selection (mainnet, testnet)
  • --<DEPLOY_METHOD> — deployment method (tonconnect, mnemonic)
Network options:
  • --mainnet — use TON Mainnet
  • --testnet — use TON Testnet
  • --custom <URL> — use custom network endpoint
  • --custom-version <VERSION> — API version (v2, v4)
  • --custom-type <TYPE> — network type (custom, mainnet, testnet)
  • --custom-key <KEY> — API key (v2 only)
Deploy options:
  • --tonconnect — use TON Connect for deployment
  • --deeplink — use deep link for deployment
  • --mnemonic — use mnemonic for deployment
Explorer options:
  • --tonscan — use Tonscan explorer
  • --tonviewer — use Tonviewer explorer (default)
  • --toncx — use Toncx explorer
  • --dton — use Dton explorer
Usage examples:
  • <YOUR_API_KEY> — API key for the selected provider (v2 only).
Requirements:
  • Scripts must be located in scripts/ directory
  • Script files must export a run function:
Environment variables: For mnemonic-based deployments, configure these environment variables.

test

Run the full project test suite with all .spec.ts files.

Basic usage

Run all test files in the tests/ directory.

Collecting coverage

Run tests and collect coverage into coverage/ directory.

Gas reporting

Run tests and compare with the last snapshot’s metrics.

Specific test file

Examples:
Test file requirements:
  • Test files should be located in tests/ directory
  • Use .spec.ts extension
  • Supports standard Jest syntax and matchers

verify

Verify a deployed contract using TON Contract Verifier.

Basic usage

Interactive mode to select contract and network.

Non-interactive mode

Parameters:
  • <CONTRACT> — contract name to verify
  • --network <NETWORK> — network (mainnet, testnet)
  • --compiler-version <VERSION> — compiler version used for building
  • --custom <URL> — custom network endpoint
  • --custom-version <VERSION> — API version (v2 default)
  • --custom-type <TYPE> — network type (mainnet, testnet)
  • --custom-key <KEY> — API key (v2 only)
Examples:
Custom network verification:

help

Show detailed help.
Examples:

set

Sets language versions.
Available keys:
  • func — overrides @ton-community/func-js-bin version

convert

Converts legacy bash build scripts to Blueprint wrappers.

rename

Renames a contract by matching in wrappers, scripts, and tests.

pack

Builds and prepares a publish-ready package of wrappers.
Flags:
  • --no-warn, -n — ignore warnings about modifying tsconfig.json and package.json, and about removing the dist directory
Output:
  • Creates deployment-ready package
  • Includes compiled artifacts
  • Bundles dependencies

snapshot

Creates snapshots with gas usage and cell sizes.
Flags:
  • --label=<COMMENT>, -l=<COMMENT> — add a comment label to the snapshot
Features:
  • Run with gas usage and cell sizes collected
  • Write a new snapshot
  • Useful for regression testing

Environment variables

Blueprint supports environment variables for wallet configuration when using mnemonic provider:
  • WALLET_MNEMONIC — wallet mnemonic phrase (space-separated words).
  • WALLET_VERSION — wallet contract version (v1r1, v1r2, v1r3, v2r1, v2r2, v3r1, v3r2, v4r1, v4r2, v4, v5r1).
  • WALLET_ID — wallet ID for versions earlier than v5r1.
  • SUBWALLET_NUMBER — subwallet number for v5r1 wallets.

Example .env file

  • <MNEMONIC_24_WORDS> — 24-word wallet mnemonic (space-separated).

API reference

Blueprint exports functions and classes for programmatic interaction with TON smart contracts. Generates a TON deep link for transfer.
Parameters:
  • address — the recipient’s TON address
  • amount — the amount of nanoTON to send
  • body — optional message body as a Cell
  • stateInit — optional state init cell for deploying a contract
  • testOnly — optional flag to determine output address format
Returns: a URL deep link that can be opened in TON wallets Example:
Generates a link to view a TON address in a selected blockchain explorer.
Parameters:
  • address — the TON address to view in explorer
  • network — the target network (mainnet or testnet)
  • explorer — the desired explorer (tonscan, tonviewer, toncx, dton)
Returns: a full URL pointing to the address in the selected explorer Example:

getNormalizedExtMessageHash

Generates a normalized hash of an external-in message for comparison.
This function ensures consistent hashing of external-in messages by following TEP-467. Parameters:
  • message — the message to be normalized and hashed (must be of type external-in)
Returns: the hash of the normalized message as Buffer Throws: error if the message type is not external-in

compile

Compiles a contract using the specified configuration for tact, func, or tolk languages.
Parameters:
  • name — the name of the contract to compile (should correspond to a file named <name>.compile.ts)
  • opts — optional CompileOpts, including user data passed to hooks
Returns: a promise that resolves to the compiled contract code as a Cell Example:

libraryCellFromCode

Packs resulting code hash into library cell.
Parameters:
  • code — the contract code cell
Returns: a library cell containing the code hash

NetworkProvider

Interface representing a network provider for interacting with the TON Blockchain.

network()

Returns: current network type that the provider is connected to

explorer()

Returns: Explorer name for the current network

sender()

Returns: the SenderWithSendResult instance used for sending transactions

api()

Returns: the underlying BlueprintTonClient API for direct blockchain interactions

provider()

Creates a contract provider for interacting with a contract at the specified address. Parameters:
  • address — the contract address to interact with
  • init — optional contract initialization data
    • code — Contract code cell
    • data — Contract initial data cell
Returns: contractProvider instance for the specified address

isContractDeployed()

Checks whether a contract is deployed at the specified address. Parameters:
  • address — the contract address to check
Returns: promise resolving to true if contract is deployed, false otherwise Usage example:

waitForDeploy()

Waits for a contract to be deployed by polling the address until the contract appears on-chain. Parameters:
  • address — the contract address to monitor
  • attempts — maximum number of polling attempts (default: 20)
  • sleepDuration — delay between attempts in milliseconds (default: 2000)
Returns: promise that resolves when contract is deployed Throws: error if contract is not deployed within the specified attempts Usage example:

waitForLastTransaction()

Waits for the last sent transaction to be processed and confirmed on the blockchain. Parameters:
  • attempts — maximum number of polling attempts (default: 20)
  • sleepDuration — delay between attempts in milliseconds (default: 2000)
Returns: promise that resolves when the last transaction is confirmed Usage example:

getContractState()

Retrieves the current state of a contract including its balance, code, and data. Parameters:
  • address — the contract address to query
Returns: promise resolving to ContractState. Usage example:

getConfig()

Fetches the current blockchain configuration parameters. Parameters:
  • configAddress — optional config contract address (uses default if not provided)
Returns: promise resolving to BlockchainConfig

open()

Opens a contract instance for interaction, binding it to the current provider. Parameters:
  • contract — the contract instance to open
Returns: openedContract wrapper that enables direct method calls Usage example:

ui()

Returns: UIProvider instance for console interactions Usage example:

UIProvider

Interface for handling user interactions, such as displaying messages, prompting for input, and managing action prompts. This interface abstracts console interactions and can be used in both interactive and automated scenarios.

write()

Displays a message to the user console. Parameters:
  • message — the text message to display
Usage example:

prompt()

Displays a yes/no prompt to the user and waits for their response. Parameters:
  • message — the prompt message to display
Returns: promise resolving to true for yes, false for no Usage example:

inputAddress()

Prompts the user to input a TON address with validation. Parameters:
  • message — the prompt message to display
  • fallback — optional default address to use if user provides empty input
Returns: promise resolving to Address object Usage example:

input()

Prompts the user for a text input and returns the entered string. Parameters:
  • message — the prompt message to display
Returns: promise resolving to the user’s input as a string Usage example:

choose()

Presents a list of choices to the user and returns the selected option. Parameters:
  • message — the prompt message to display
  • choices — array of options to choose from
  • display — function to convert each choice to a display string
Returns: promise resolving to the selected choice Usage example:

setActionPrompt()

Sets a persistent action prompt that remains visible during operations. Parameters:
  • message — the action prompt message to display
Usage example:

clearActionPrompt()

Clears the current action prompt, removing it from display. Usage example:

Type definitions

Blueprint exports several TypeScript types for configuration and compilation options. These types provide type safety and IntelliSense support when working with Blueprint programmatically.

CompileOpts

Optional compilation settings, including user data passed to hooks and compilation flags.
Properties:
  • hookUserData — optional user data passed to pre/post compile hooks
  • debugInfo — enable debug information in compiled output (default: false)
  • buildLibrary — build as a library instead of a regular contract (default: false)
Usage example:

CommonCompilerConfig

Base configuration shared by all compiler types. This interface defines common compilation hooks and options.
Properties:
  • preCompileHook — optional function called before compilation starts (receives HookParams)
  • postCompileHook — optional function called after compilation completes (receives compiled Cell and HookParams)
  • buildLibrary — whether to build as a library (default: false)
Usage example:
./wrappers/MyContract.compile.ts

FuncCompilerConfig

Configuration specific to the FunC compiler, including optimization levels and source file specifications.
Properties:
  • lang — compiler language identifier (optional, defaults to 'func')
  • optLevel — optimization level (0-2, default: 2)
  • debugInfo — include debug information in output
  • targets — array of FunC source file paths to compile
  • sources — alternative source specification method
Usage example:
./wrappers/MyContract.compile.ts

TolkCompilerConfig

Configuration for the Tolk compiler, including optimization and debugging options.
Properties:
  • lang — compiler language identifier (must be 'tolk')
  • entrypoint — path to the main Tolk source file
  • optimizationLevel — optimization level
  • withStackComments — include stack operation comments in Fift output
  • withSrcLineComments — include source line comments in Fift output
  • experimentalOptions — additional experimental compiler flags
Usage example:
./wrappers/MyContract.compile.ts

TactLegacyCompilerConfig

Configuration for the Tact compiler (legacy configuration format).
Properties:
  • lang — compiler language identifier (must be 'tact')
  • target — path to the main Tact source file
  • options — additional Tact compiler options
Usage example:
./wrappers/MyContract.compile.ts

HookParams

Parameters passed to compilation hooks, providing context about the compilation process.
Properties:
  • userData — optional user data passed from CompileOpts

SenderWithSendResult

Extended sender interface that tracks the result of the last send operation.
Properties:
  • lastSendResult — optional result from the most recent send operation

BlueprintTonClient

Union type representing supported TON client implementations.
Supported clients:
  • TonClient4 — TON HTTP API v4 client
  • TonClient — TON HTTP API v2/v3 client
  • ContractAdapter — TON API adapter
  • LiteClient — Lite client for direct node communication

Explorer

Supported blockchain explorer types.
Supported explorers:
  • 'tonscan' — TONScan explorer
  • 'tonviewer' — Tonviewer explorer (default)
  • 'toncx' — TON.cx explorer
  • 'dton' — dton.io explorer

Configuration

For detailed configuration options, refer to the Blueprint Configuration guide.