@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

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, create a blueprint.config.ts file in the root of your project with something like this:

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)

It is important that the config is exported, is named config, and is not default exported.

Here are some of the plugins developed by the community:

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

Contributors

Special thanks to @qdevstudio for their logo for blueprint.

License

MIT

Donations

TON - EQAQR1d1Q4NaE5EefwUMdrr1QvXg-8mDB0XI2-fwDBD0nYxC

Changelog

[0.15.0] - 2023-12-15

Added

• Added flags --custom-version, --custom-key, --custom-type to run and verify commands to allow better control over custom API behavior

Changed

• --custom now always adds jsonRPC to API URL for v2 APIs

Fixed

• Fixed argument handling