Blueprint

Blueprint is the official TON smart-contract development framework, maintained by the ton-org team. Functionally it is the TON equivalent of Hardhat or Foundry in the Ethereum world: a single toolchain that wraps contract authoring, in-memory testing, and on-chain deployment behind one CLI.

Why it exists

Before Blueprint, a typical TON contract pipeline had to be assembled by hand: a FunC compiler invocation, custom deployment scripts, a third-party test runner. It worked but required a lot of boilerplate and was unfriendly to newcomers. Blueprint bundles those stages into a single command-line tool and ships an opinionated project layout with contracts, wrappers, tests and scripts directories.

How it works

Internally Blueprint stitches together several ecosystem components:

• FunC and Tact compilers — both contract languages are supported out of the box; the choice is set in the project config.
• TypeScript contract wrappers — the wrappers folder holds a class that exposes contract methods through a typed JS API. npx blueprint create scaffolds the wrapper automatically.
• Sandbox — the @ton/sandbox package emulates TVM inside the Node process, so tests run instantly without spinning up a local node.
• Scripts — TypeScript deploy and interaction scripts launched via npx blueprint run. Scripts can connect to Tonkeeper or any TON Connect wallet to sign the deployment transaction.

Standard workflow

A typical loop looks like this: the developer edits a contract in contracts/MyContract.fc, refreshes the wrapper, and describes a scenario in tests/MyContract.spec.ts. Running npx blueprint test boots the sandbox, deploys the contract into an ephemeral environment, and asserts on the resulting messages and state. Once green, npx blueprint run deployMyContract sends a real deployment transaction to the chosen network.

Where it is used

Blueprint is the framework of choice in most TON Foundation tutorials, in the TON Hello World learning track, and inside DeFi and NFT teams building on TON. It has become the de-facto standard for open-source contract repositories: a typical TON project README starts with “clone the repo, install dependencies, run npx blueprint test”.

Limitations

Blueprint is a developer tool, not a runtime, and it does not replace validator infrastructure. The sandbox is a very close emulation of TVM but is not bit-perfect: some gas edge cases and unusual shard configurations only reproduce on testnet. Serious projects always go through a testnet pass and an audit before mainnet deployment, even if sandbox tests are green.

Even so, Blueprint remains the fastest way to start writing TON contracts: a new developer can get a working contract-test-deploy loop in an evening without learning the low-level details of ADNL and lite-server protocols.