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

Compiling FunC with https://github.com/ton-community/func-js (no CLI)
Testing smart contracts with https://github.com/ton-org/sandbox
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

Run and follow the on-screen instructions: npm create ton@latest or npx create-ton@latest
(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

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

Run the test suite

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

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

Deploy one of the contracts

You need a deploy script in scripts/deploy<CONTRACT>.ts - example
Run interactive: npx blueprint run or yarn blueprint run
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

Make sure you have a project to host the contract
Run interactive: npx blueprint create or yarn blueprint create
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

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

Test suite

Implement TypeScript tests in tests/<CONTRACT>.spec.ts
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

Implement a compilation script in wrappers/<CONTRACT>.compile.ts
Implement a deployment script in scripts/deploy<CONTRACT>.ts
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

elsvv / blueprint