@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

 

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 one of the 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>
   • 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

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

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

 

Contributors

Special thanks to @qdevstudio for their logo for blueprint.

License

MIT

Donations

TON - EQAQR1d1Q4NaE5EefwUMdrr1QvXg-8mDB0XI2-fwDBD0nYxC

Changelog

[0.10.0] - 2023-06-06

Added

• Added two optional fields to the CompilerConfig: preCompileHook?: () => Promise<void> and postCompileHook?: (code: Cell) => Promise<void>. The former one gets called before any compilation of the respective contract happens, the latter one - after any compilation with the compiled code cell (they are called both during the build command and when calling the compile function for the respective contracts)

Changed

• Changed the run command to only show .ts scripts