@ton/blueprint

Blueprint

A development environment for TON blockchain for writing, testing, and deploying smart contracts.

Quick start 🚀

Run the following in terminal to create a new project and follow the on-screen instructions:

npm create ton@latest

 

Core features 🔥

• Create a development environment from template in one click - npm create ton@latest
• Streamlined workflow for building, testing and deploying smart contracts
• Dead simple deployment to mainnet/testnet using your favorite wallet (eg. Tonkeeper)
• Blazing fast testing of multiple smart contracts in an isolated blockchain running in-process

Tech stack

1. Compiling FunC with https://github.com/ton-community/func-js (no CLI)
2. Testing smart contracts with https://github.com/ton-org/sandbox
3. Deploying smart contracts with TON Connect 2, Tonhub wallet or a ton:// deeplink

Requirements

• Node.js with a recent version like v18, verify version with node -v
• IDE with TypeScript and FunC support like Visual Studio Code with the FunC plugin or IntelliJ Idea with the TON Development plugin

 

Create a new project

1. Run and follow the on-screen instructions:   npm create ton@latest   or   npx create-ton@latest
2. (Optional) Then from the project directory:   npm install   or   yarn install

Directory structure

• contracts/ - Source code in FunC for all smart contracts and their imports
• wrappers/ - TypeScript interface classes for all contracts (implementing Contract from @ton/core)
  • include message [de]serialization primitives, getter wrappers and compilation functions
  • used by the test suite and client code to interact with the contracts from TypeScript
• tests/ - 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 contracts
• build/ - Compilation artifacts created here after running a build command

Build contracts

1. You need a compilation script in wrappers/<CONTRACT>.compile.ts - example
2. Run interactive:    npx blueprint build   or   yarn blueprint build
3. Non-interactive:   npx/yarn blueprint build <CONTRACT>   OR build all contracts   yarn blueprint build --all
   • Example: yarn blueprint build counter
4. Build results are generated in build/<CONTRACT>.compiled.json

Run the test suite

1. Run in terminal:   npx blueprint test   or   yarn blueprint test
2. Alternative method:   npm test   or   yarn test

Learn more about writing tests from the Sandbox's documentation - here.

Deploy one of the contracts

1. You need a deploy script in scripts/deploy<CONTRACT>.ts - example
2. Run interactive:    npx blueprint run   or   yarn blueprint run
3. Non-interactive:   npx/yarn blueprint run <CONTRACT> --<NETWORK> --<DEPLOY_METHOD>
   • Example: yarn blueprint run deployCounter --mainnet --tonconnect

Help and additional commands

Run in terminal:   npx blueprint help   or   yarn blueprint help

 

Develop a new contract

1. Make sure you have a project to host the contract
2. Run interactive:    npx blueprint create   or   yarn blueprint create
3. Non-interactive:   npx/yarn blueprint create <CONTRACT> --type <TYPE> (type can be func-empty, func-counter, tact-empty, tact-counter)
   • Example: yarn blueprint create MyNewContract --type func-empty

Contract code

1. Implement the standalone FunC root contract in contracts/<CONTRACT>.fc
2. Implement shared FunC imports (if breaking code to multiple files) in contracts/imports/*.fc
3. Implement wrapper TypeScript class in wrappers/<CONTRACT>.ts to encode messages and decode getters

Test suite

1. Implement TypeScript tests in tests/<CONTRACT>.spec.ts
2. Rely on the wrapper TypeScript class from wrappers/<CONTRACT>.ts to interact with the contract

Learn more about writing tests from the Sandbox's documentation - here.

Compilation and deployment

1. Implement a compilation script in wrappers/<CONTRACT>.compile.ts
2. Implement a deployment script in scripts/deploy<CONTRACT>.ts
3. Rely on the wrapper TypeScript class from wrappers/<CONTRACT>.ts to initialize the contract

Config

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.

Plugins

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:

• scaffold - allows developers to quickly create a simple dapp automatically using the wrappers' code

Custom network

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/',
        type: 'mainnet',
        version: 'v2',
        key: 'YOUR_API_KEY',
    },
};

Properties of the network object have the same semantics as the --custom flags with respective names (see blueprint help run).

Contributors

Special thanks to @qdevstudio for their logo for blueprint.

License

MIT

Donations

TON - EQAQR1d1Q4NaE5EefwUMdrr1QvXg-8mDB0XI2-fwDBD0nYxC

Changelog

[0.16.0] - 2024-02-15

Added

• Added the network entry to the global config, which allows one to specify a custom network to be used instead of having to add --custom flags on each run
• Added the convert command which attempts to convert a legacy bash build script into a blueprint .compile.ts file
• Added the ability to pass any user data into the compile hooks

Changed

• Improved the verify command