Blueprint

A standard Blueprint project follows this layout:

• contracts/: Source code for smart contracts (FunC) and their dependencies.
  • Standalone root contracts: contracts/*.fc
  • Shared imports: contracts/imports/*.fc
• wrappers/: TypeScript wrapper classes (implementing Contract from @ton/core) for interacting with contracts, including [de]serialization and compilation logic.
  • Builder configs: wrappers/*.compile.ts
• tests/: TypeScript tests for the contracts (typically using wrappers).
• scripts/: Project scripts, primarily deployment scripts.
• build/: Contains compiled contract artifacts (e.g., build/*.compiled.json).

A Blueprint project follows a specific directory structure:

• contracts/: Source code for all smart contracts and their imports.
• wrappers/: TypeScript interface classes for contracts (except Tact). Each wrapper implements the Contract interface from @ton/core and is used by tests and client code to interact with contracts via message (de)serialization and getters.
• compilables/: Compilation scripts for contracts.
• tests/: TypeScript test suite (uses Sandbox for in-process testing).
• scripts/: Deployment scripts and other scripts for interacting with live contracts.
• build/: Compilation artifacts (e.g., .compiled.json, Tact-generated files, or Fift output).

Tests run in Node.js using the sandbox library (running TVM in WebAssembly). Always ensure you build your contracts before running tests.

• Run tests: yarn test
• Generate gas metric report: yarn gas-report
• Save a gas metric snapshot: yarn gas-snapshot '<label name>'

To build your contracts, you must have a compilation script located at compilables/<CONTRACT>.compile.ts.

Interactive build:

npx blueprint build
# or
yarn blueprint build

Non-interactive build: To build a specific contract:

npx blueprint build <CONTRACT>
# or
yarn blueprint build <CONTRACT>

To build all contracts:

yarn blueprint build --all

Build results are stored in build/<CONTRACT>.compiled.json.

yarn blueprint build counter

Blueprint provides CLI commands to scaffold new contracts or rename existing ones.

Create a contract: Interactive:

npx blueprint create

Non-interactive:

npx blueprint create <CONTRACT> --type <TYPE>
# Example:
# yarn blueprint create MyNewContract --type tolk-empty

Rename a contract: Interactive:

npx blueprint rename

Non-interactive:

npx blueprint rename <OLD_NAME> <NEW_NAME>

Run your TypeScript tests using the Blueprint CLI or your package manager.

Using Blueprint:

npx blueprint test
# or
yarn blueprint test

Using npm/yarn:

npm test
# or
yarn test

Run specific contract tests:

yarn test <CONTRACT>

Collect coverage: To generate a coverage report, run:

blueprint test --coverage

Coverage results will be placed in the coverage directory.

yarn test counter

To start a new TON project using the Blueprint starter template, use the following command. This template includes FunC contracts, unit tests, compilation, and deployment scripts.

npm create ton@latest

You can collect performance metrics and gas reports for your contracts using the Sandbox integration.

Collect metrics snapshot:

npx blueprint snapshot [--label=<comment>|-l <comment>]

Compare metrics with gas report:

npx blueprint test --gas-report|-g

npx blueprint snapshot --label="my-benchmark"

To scaffold a new contract, use the blueprint create command. This will generate the necessary contract files and test files.

Example:

yarn blueprint create MyContract

To create a new TON development project using Blueprint, run the following command and follow the interactive on-screen instructions:

npm create ton@latest

After the project is created, navigate into the project directory and install the dependencies using npm install or yarn install.

When verifying contracts on a custom network, you must specify the network details via CLI flags or config. Crucially, the custom type MUST be specified as either mainnet or testnet when verifying.

Example CLI command:

npx blueprint verify --custom https://toncenter.com/api/v2/jsonRPC --custom-version v2 --custom-type mainnet --custom-key YOUR_API_KEY --compiler-version 0.4.4-newops.1

Deployment can be performed interactively or via CLI flags. Supported deployment methods include TON Connect, ton:// deep links/QR codes, Tonhub wallet, or Mnemonics.

Interactive mode: Run yarn blueprint run and follow the prompts to select the contract, network (mainnet/testnet), and deployment method.

Non-interactive mode: Use the following syntax: yarn blueprint run <CONTRACT> --<NETWORK> --<DEPLOY_METHOD>

Example:

yarn blueprint run pingpong --mainnet --tonconnect