Blueprint development environment setup (TON)

Setting Up Blueprint Development Environment (TON)

TON is an asynchronous blockchain platform with architecture fundamentally different from EVM. Smart contracts are written in FunC or Tact, compiled to TVM bytecode. Blueprint is the official framework for developing, testing, and deploying TON contracts. Without it, starting TON development is difficult: you need to manually configure the compiler, test runner, and sandbox. Blueprint solves all of this out of the box.

What Blueprint Provides in Practice

After project initialization through npm create ton@latest, you get a structure with tests, deploy scripts, and configuration for working with @ton/sandbox — a local TVM emulator that lets you test contracts without accessing the real network.

Key difference from Hardhat/Foundry: in TON there's no global network state in tests. Each test creates its own Blockchain instance through Blockchain.create(), deploys contracts there, and works in isolation. This is fast (no network requests) and deterministic.

Project Structure

contracts/          # FunC or Tact sources
wrappers/           # TypeScript wrappers over contracts (sending messages, reading data)
tests/              # Jest tests with Sandbox
scripts/            # Deploy scripts for testnet/mainnet

Wrappers are an important Blueprint concept. Each contract has a TypeScript class that encapsulates serialization/deserialization of cell structures (cells being the main data format in TON). Without a wrapper, you need to manually build beginCell().storeUint(...).endCell() every time during testing.

Setting Up Sandbox and First Test

A typical problem when first learning: a test deploys a contract, sends a message, but doesn't know how to check the result. In EVM this is simple — emit events, look at logs. TON architecture is different: contracts exchange messages, and responses are separate transactions.

Sandbox returns SendMessageResult with array of transactions. Each transaction contains inMessage, outMessages, description. For verification, Blueprint comes with @ton/test-utils, which adds custom Jest matchers:

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

Without these matchers, checking transactions is multi-line imperative code. With them — readable assertions.

Integration with TON Connect and Deploy

For deployment, Blueprint uses NetworkProvider — an abstraction that works identically on testnet (Testnet via tonapi.io) and mainnet. Deploy scripts are run through npx blueprint run deployMyContract and automatically offer network selection.

Frequent difficulty: deployment in TON is sending a message to an uninit address (contract address is calculated from code and initial data before deployment). If initial data is incorrectly serialized in wrapper, contract deploys to a different address than expected. Verify address through Contract.address in wrapper and compare with tonscan.org before actual deployment.

Configuration for Multiple Contracts

In projects with several interacting contracts, it's important to correctly configure deploy order and address passing. Blueprint supports this through script parameters. For master contract that stores addresses of child contracts:

1. Deploy child contract → get address
2. Deploy master with child address in initial data
3. Verify connection through Sandbox test

Timeline

Basic Blueprint setup for new project (initialization, Sandbox configuration, first contract with tests) — 4-8 hours. Full development environment with CI/CD via GitHub Actions and deployment on testnet/mainnet — 1-2 working days.