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

• Quick start
• Overview
  • Core features
  • Tech stack
  • Requirements
• Features overview
  • Project creation
  • Directory structure
  • Building contracts
  • Running the test suites
  • Deploying contracts
  • Custom scripts
• Contract development
  • Creating contracts
  • Writing contract code
  • Testing contracts
• Configuration
  • Plugins
  • Custom network
• Contributors
• License
• Donations

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 FunC and Tact languages

• Create a development environment from template - 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

1. Compiling FunC with https://github.com/ton-community/func-js
2. Compiling Tact with https://github.com/tact-lang/tact
3. Testing smart contracts with https://github.com/ton-org/sandbox
4. Deploying smart contracts with TON Connect 2, Tonhub wallet or a ton:https:// deeplink

• Node.js with a recent version like v18. Version can be verified with node -v
• IDE with TON support:
  • Visual Studio Code with the FunC plugin
  • IntelliJ IDEA with the TON Development plugin

1. Run and follow the on-screen instructions:   npm create ton@latest   or   npx create-ton@latest
2. From the project directory run   npm/yarn install   to install dependencies

• contracts/ - Source code in FunC or Tact 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
• compilables/ - Compilations scripts for contracts
• 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

1. You need a compilation script in compilables/<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
5. Tact generated files are located in build/<CONTRACT> directory

1. Run in terminal:   npx blueprint test   or   yarn blueprint test
2. Alternative method:   npm test   or   yarn test
3. You can specify test file to run:   npm/yarn test <CONTRACT>
   • Example: yarn test counter

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

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

1. Custom scripts should be located in scripts folder
2. Script file must have exported function run

export async function run(provider: NetworkProvider) {
  // 
}

3. Script can be run using npx/yarn blueprint run <SCRIPT> command

FunC version can be updated using npx/yarn blueprint set func 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

1. Run interactive:    npx blueprint create   or   yarn blueprint create
2. 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

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

1. Implement tact contract in contracts/<CONTRACT>.tact
2. Wrappers will be automatically generated in build/<CONTRACT>/tact_<CONTRACT>.ts

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.

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:

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

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).

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

(or similarly using the config), however custom type MUST be specified as either mainnet or testnet when verifying.

Special thanks to @qdevstudio for their logo for blueprint.

MIT

TON - EQAQR1d1Q4NaE5EefwUMdrr1QvXg-8mDB0XI2-fwDBD0nYxC