diff --git a/README.md b/README.md index 4875f11..a91fc02 100644 --- a/README.md +++ b/README.md @@ -4,44 +4,74 @@ 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: +## Table of Contents + +* [Quick start](#quick-start-) +* [Overview](#overview) + * [Core features](#core-features) + * [Tech stack](#tech-stack) + * [Requirements](#requirements) +* [Features overview](#features-overview) + * [Project creation](#project-creation) + * [Directory structure](#directory-structure) + * [Building contracts](#building-contracts) + * [Running the test suites](#running-the-test-suites) + * [Deploying contracts](#deploying-contracts) + * [Custom scripts](#custom-scripts) +* [Contract development](#contract-development) + * [Creating contracts](#creating-contracts) + * [Writing contract code](#writing-contract-code) + * [Testing contracts](#testing-contracts) +* [Configuration](#configuration) + * [Plugins](#plugins) + * [Custom network](#custom-network) +* [Contributors](#contributors) +* [License](#license) +* [Donations](#donations) + +## Quick start 🚀 + +Run the command in terminal to create a new project and follow the on-screen instructions: ```console npm create ton@latest ``` -  +## Overview + +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](https://docs.ton.org/develop/func/overview) and [Tact](https://docs.tact-lang.org/) languages -### Core features 🔥 +### Core features -* Create a development environment from template in one click - `npm create ton@latest` +* 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 ### 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](https://github.com/ton-connect), [Tonhub wallet](https://tonhub.com/) or a `ton://` deeplink +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](https://github.com/ton-connect), [Tonhub wallet](https://tonhub.com/) or a `ton://` deeplink ### Requirements -* [Node.js](https://nodejs.org) with a recent version like v18, verify version with `node -v` -* IDE with TypeScript and FunC support like [Visual Studio Code](https://code.visualstudio.com/) with the [FunC plugin](https://marketplace.visualstudio.com/items?itemName=tonwhales.func-vscode) or [IntelliJ IDEA](https://www.jetbrains.com/idea/) with the [TON Development plugin](https://plugins.jetbrains.com/plugin/23382-ton) +* [Node.js](https://nodejs.org) with a recent version like v18. Version can be verified with `node -v` +* IDE with TON support: + * [Visual Studio Code](https://code.visualstudio.com/) with the [FunC plugin](https://marketplace.visualstudio.com/items?itemName=tonwhales.func-vscode) + * [IntelliJ IDEA](https://www.jetbrains.com/idea/) with the [TON Development plugin](https://plugins.jetbrains.com/plugin/23382-ton) -  +## Features overview -## Create a new project +### Project creation -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` +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 ### Directory structure -* `contracts/` - Source code in [FunC](https://ton.org/docs/develop/func/overview) for all smart contracts and their imports +* `contracts/` - Source code in [FunC](https://docs.ton.org/develop/func/overview) or [Tact](https://tact-lang.org/) for all smart contracts and their imports * `wrappers/` - TypeScript interface classes for all contracts (implementing `Contract` from [@ton/core](https://www.npmjs.com/package/@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 @@ -49,61 +79,79 @@ npm create ton@latest * `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 +### Building contracts 1. You need a compilation script in `wrappers/.compile.ts` - [example](/example/wrappers/Counter.compile.ts) 2. Run interactive:    `npx blueprint build`   or   `yarn blueprint build` 3. Non-interactive:   `npx/yarn blueprint build `   OR build all contracts   `yarn blueprint build --all` * Example: `yarn blueprint build counter` 4. Build results are generated in `build/.compiled.json` +5. Tact generated files are located in `build/` directory -### Run the test suite +### Running the test suites 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 ` + * Example: `yarn test counter` > Learn more about writing tests from the Sandbox's documentation - [here](https://github.com/ton-org/sandbox#writing-tests). -### Deploy one of the contracts +### Deploying contracts -1. You need a deploy script in `scripts/deploy.ts` - [example](/example/scripts/deployCounter.ts) +1. You need a deployment script in `scripts/deploy.ts` - [example](/example/scripts/deployCounter.ts) 2. Run interactive:    `npx blueprint run`   or   `yarn blueprint run` -3. Non-interactive:   `npx/yarn blueprint run -- --` +3. Non-interactive:   `npx/yarn blueprint run deploy -- --` * Example: `yarn blueprint run deployCounter --mainnet --tonconnect` +### Custom scripts + +1. Custom scripts should be located in `scripts` folder +2. Script file must have exported function `run` +```ts +export async function run(provider: NetworkProvider) { + // +} +``` +3. Script can be run using `npx/yarn blueprint run