@ton/blueprint
Advanced tools
A development environment for TON blockchain for writing, testing, and deploying smart contracts.
Run the command in terminal to create a new project and follow the on-screen instructions:
npm create ton@latest
Blueprint is an all-in-one development environment designed to enhance the process of creating, testing, and deploying smart contracts on TON blockchain using Tolk, FunC, and Tact languages.
npm create ton@latesttact.config.json as the build configuration fileton:// deeplinknode -vnpm create ton@latest or npx create-ton@latestnpm/yarn install to install dependenciescontracts/ - Source code for all smart contracts and their importswrappers/ - TypeScript interface classes for all contracts except Tact.
tact.config.jsonContract interface from @ton/corecompilables/ - Compilations scripts for contractstests/ - TypeScript test suite for all contracts (relying on Sandbox for in-process tests)scripts/ - Deployment scripts to mainnet/testnet and other scripts interacting with live contractsbuild/ - Compilation artifacts created here after running a build commandcompilables/<CONTRACT>.compile.ts - examplenpx blueprint build or yarn blueprint buildnpx/yarn blueprint build <CONTRACT> OR build all contracts yarn blueprint build --all
yarn blueprint build counterbuild/<CONTRACT>.compiled.jsonbuild/<CONTRACT> directorybuild/<CONTRACT>/<CONTRACT>.fifnpx blueprint test or yarn blueprint testnpm test or yarn testnpm/yarn test <CONTRACT>
yarn test counterLearn more about writing tests from the Sandbox's documentation - here.
scripts folderrunexport async function run(provider: NetworkProvider, args: string[]) {
//
}
npx/yarn blueprint run <SCRIPT> [arg1, arg2, ...] commandscripts/deploy<CONTRACT>.ts - examplenpx blueprint run or yarn blueprint runnpx/yarn blueprint run deploy<CONTRACT> --<NETWORK> --<DEPLOY_METHOD>yarn blueprint run deployCounter --mainnet --tonconnectTo run scripts using a wallet by mnemonic authentication, you need to configure your environment and use the Mnemonic option when running scripts.
Start by adding the following environment variables to your .env file:
WALLET_MNEMONIC: Your wallet's mnemonic phrase (space-separated words).WALLET_VERSION: The wallet contract version to use. Supported versions: v1r1, v1r2, v1r3, v2r1, v2r2, v3r1, v3r2, v4r1, v4r2 (or v4), v5r1.Optional variables:
WALLET_ID: The wallet ID (can be used with versions below v5r1).SUBWALLET_NUMBER: The subwallet number used to build the wallet ID (can be used with v5r1 wallets).Once your environment is set up, you can use the mnemonic wallet for deployment with the appropriate configuration.
Tolk version can be updated to the latest using npm update/yarn upgrade @ton/tolk-js command
FunC version can be updated to a specific version using npx/yarn blueprint set func command, or to the latest using npm update/yarn upgrade @ton-community/func-js command
Tact version can be updated to the latest using npm update/yarn upgrade @tact-lang/compiler command
Run in terminal: npx blueprint help or yarn blueprint help
Before developing, make sure that your current working directory is located in the root of the project created using npm create ton@latest
npx blueprint create or yarn blueprint createnpx/yarn blueprint create <CONTRACT> --type <TYPE> (type can be tolk-empty, func-empty, tact-empty, tolk-counter, func-counter, tact-counter)
yarn blueprint create MyNewContract --type tolk-emptynpx blueprint rename or yarn blueprint renamenpx/yarn blueprint rename <OLD_NAME> <NEW_NAME>yarn blueprint rename OldContract NewContract contracts/<CONTRACT>.tolk; if you wish, split into multiple fileswrappers/<CONTRACT>.ts to encode messages and decode getterscontracts/<CONTRACT>.fccontracts/imports/*.fcwrappers/<CONTRACT>.ts to encode messages and decode getterscontracts/<CONTRACT>.tactbuild/<CONTRACT>/tact_<CONTRACT>.tstests/<CONTRACT>.spec.tswrappers/<CONTRACT>.ts to interact with the contractTo collect coverage run blueprint test --coverage. Coverage will appear in coverage directory.
Learn more about writing tests from the Sandbox's documentation - here.
npm adduser to log in to your npm account.📝 Note: You can learn more about advanced authentication in the official npm docs: npmrc – Auth-Related Configuration
Update the package version
Edit the version field in your package.json to reflect the new release (e.g., 1.0.1 → 1.0.2).
Build the package Run the following command to generate and bundle your contract wrappers:
blueprint pack
npm publish --access public
npx blueprint snapshot [--label=<comment>|-l <comment>] to collect metrics of contracts and save snapshotnpx blueprint test --gas-report|-g to compare current metrics and saved snapshotLearn more about collect metric from the Sandbox's documentation - here.
A config may be created in order to control some of blueprint's features. If a config is needed, create a blueprint.config.ts file in the root of your project with something like this:
import { Config } from '@ton/blueprint';
export const config: Config = {
// config contents
};
It is important that the config is exported, is named config, and is not default exported.
Config's features are explained below.
Blueprint has a plugin system to allow the community to develop their own additions for the ecosystem without the need to change blueprint's code.
In order to use plugins, add a plugins array to your config:
import { Config } from '@ton/blueprint';
import { ScaffoldPlugin } from 'blueprint-scaffold';
export const config: Config = {
plugins: [new ScaffoldPlugin()],
};
(This example shows how to add the scaffold plugin)
Here are some of the plugins developed by the community:
A custom network may be specified by using the --custom flags, which you can read about by running blueprint help run, but it can be tiresome to use these at all times. Instead, to specify a custom network to always be used (unless --custom flags are present), add a network object to your config:
import { Config } from '@ton/blueprint';
export const config: Config = {
network: {
endpoint: 'https://toncenter.com/api/v2/jsonRPC',
type: 'mainnet',
version: 'v2',
key: 'YOUR_API_KEY',
},
};
The above config parameters are equivalent to the arguments in the following command:
npx blueprint run --custom https://toncenter.com/api/v2/jsonRPC --custom-version v2 --custom-type mainnet --custom-key YOUR_API_KEY
Properties of the network object have the same semantics as the --custom flags with respective names (see blueprint help run).
Lite client is supported through the following configuration:
import { Config } from '@ton/blueprint';
export const config: Config = {
network: {
endpoint: 'https://ton.org/testnet-global.config.json', // Use https://ton.org/global.config.json for mainnet or any custom configuration
version: 'liteclient',
type: 'testnet',
}
};
You can also provide these parameters via CLI:
npx blueprint run \
--custom https://ton.org/testnet-global.config.json \
--custom-version liteclient \
--custom-type testnet
You can also use custom network to verify contracts, like so:
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
(or similarly using the config), however custom type MUST be specified as either mainnet or testnet when verifying.
You can optionally configure how long HTTP requests should wait before timing out using the requestTimout field. This can be especially useful when working with unstable or slow networks.
import { Config } from '@ton/blueprint';
export const config: Config = {
requestTimeout: 10000, // 10 seconds
};
You can configure whether the wrappers or compilables directories should be searched recursively for contracts configs by setting the recursiveWrappers field.
import { Config } from '@ton/blueprint';
export const config: Config = {
recursiveWrappers: true,
};
By default, this is set to false.
If you're using a TonConnect provider, you can override the default manifest URL by specifying the manifestUrl field.
import { Config } from '@ton/blueprint';
export const config: Config = {
manifestUrl: 'https://yourdomain.com/custom-manifest.json',
};
By default, the manifest URL is set to:
https://raw.githubusercontent.com/ton-org/blueprint/main/tonconnect/manifest.json
Special thanks to @qdevstudio for their logo for blueprint.
MIT
TON - EQAQR1d1Q4NaE5EefwUMdrr1QvXg-8mDB0XI2-fwDBD0nYxC
FAQs
Framework for development of TON smart contracts
The npm package @ton/blueprint receives a total of 11,022 weekly downloads. As such, @ton/blueprint popularity was classified as popular.
We found that @ton/blueprint demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious Chrome extension posing as an Ethereum wallet steals seed phrases by encoding them into Sui transactions, enabling full wallet takeover.
Security News
Socket is heading to London! Stop by our booth or schedule a meeting to see what we've been working on.
Security News
OWASP’s 2025 Top 10 introduces Software Supply Chain Failures as a new category, reflecting rising concern over dependency and build system risks.