{"id":13409827,"url":"https://github.com/ton-org/blueprint","last_synced_at":"2025-05-16T03:06:49.744Z","repository":{"id":65462586,"uuid":"589809404","full_name":"ton-org/blueprint","owner":"ton-org","description":"TON development for professionals - all-in-one tool for writing, testing and deploying smart contracts","archived":false,"fork":false,"pushed_at":"2025-05-15T07:43:05.000Z","size":2369,"stargazers_count":559,"open_issues_count":56,"forks_count":129,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-05-15T08:42:10.155Z","etag":null,"topics":["hack-ton-berfest","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ton-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-17T01:33:40.000Z","updated_at":"2025-05-09T10:52:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"86aedbd7-2872-4577-b280-02c02d5b99a6","html_url":"https://github.com/ton-org/blueprint","commit_stats":null,"previous_names":["ton-community/tinfoil","ton-org/blueprint","ton-community/blueprint"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-org%2Fblueprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-org%2Fblueprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-org%2Fblueprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-org%2Fblueprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ton-org","download_url":"https://codeload.github.com/ton-org/blueprint/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310265,"owners_count":22049458,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hack-ton-berfest","hacktoberfest"],"created_at":"2024-07-30T20:01:03.571Z","updated_at":"2025-05-16T03:06:44.736Z","avatar_url":"https://github.com/ton-org.png","language":"TypeScript","funding_links":[],"categories":["🧑‍💻 Get Coding"],"sub_categories":["Dev Tools"],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/ton-org/blueprint/main/logo.svg\" width=400 \u003e\n\n# Blueprint\n\nA development environment for TON blockchain for writing, testing, and deploying smart contracts.\n\n## Table of Contents\n\n* [Quick start](#quick-start-)\n* [Overview](#overview)\n  * [Core features](#core-features)\n  * [Tech stack](#tech-stack)\n  * [Requirements](#requirements)\n* [Features overview](#features-overview)\n  * [Project creation](#project-creation)\n  * [Directory structure](#directory-structure)\n  * [Building contracts](#building-contracts)\n  * [Running the test suites](#running-the-test-suites)\n  * [Deploying contracts](#deploying-contracts)\n  * [Custom scripts](#custom-scripts)\n* [Contract development](#contract-development)\n  * [Creating contracts](#creating-contracts)\n  * [Writing contract code](#writing-contract-code)\n  * [Testing contracts](#testing-contracts)\n* [Configuration](#configuration)\n  * [Plugins](#plugins)\n  * [Custom network](#custom-network)\n* [Contributors](#contributors)\n* [License](#license)\n* [Donations](#donations)\n\n## Quick start 🚀\n\nRun the command in terminal to create a new project and follow the on-screen instructions:\n\n```console\nnpm create ton@latest\n```\n\n## Overview\n\nBlueprint 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), [Tolk](https://docs.ton.org/develop/tolk/overview), and [Tact](https://docs.tact-lang.org/) languages.\n\n### Core features\n\n* Create a development environment from template - `npm create ton@latest`\n* Streamlined workflow for building, testing and deploying smart contracts\n* Dead simple deployment to mainnet/testnet using your favorite wallet (eg. Tonkeeper)\n* Blazing fast testing of multiple smart contracts in an isolated blockchain running in-process\n\n### Tech stack\n\n1. Compiling FunC with https://github.com/ton-community/func-js\n2. Compiling Tolk with https://github.com/ton-blockchain/tolk-js\n3. Compiling Tact with https://github.com/tact-lang/tact\n4. Testing smart contracts with https://github.com/ton-org/sandbox\n5. Deploying smart contracts with [TON Connect 2](https://github.com/ton-connect) or a `ton://` deeplink\n\n### Requirements\n\n* [Node.js](https://nodejs.org) with a recent version like v18. Version can be verified with `node -v`\n* IDE with TON support:\n  * [Visual Studio Code](https://code.visualstudio.com/) with the [FunC plugin](https://marketplace.visualstudio.com/items?itemName=tonwhales.func-vscode), [Tolk plugin](https://marketplace.visualstudio.com/items?itemName=ton-core.tolk-vscode) or [Tact plugin](https://marketplace.visualstudio.com/items?itemName=tonstudio.vscode-tact)\n  * [IntelliJ IDEA](https://www.jetbrains.com/idea/) with the [TON Development plugin](https://plugins.jetbrains.com/plugin/23382-ton)\n\n## Features overview\n\n### Project creation\n\n1. Run and follow the on-screen instructions: \u0026nbsp; `npm create ton@latest` \u0026nbsp; or \u0026nbsp; `npx create-ton@latest`\n2. From the project directory run \u0026nbsp; `npm/yarn install` \u0026nbsp; to install dependencies\n\n### Directory structure\n\n* `contracts/` - Source code for all smart contracts and their imports\n* `wrappers/` - TypeScript interface classes for all contracts (implementing `Contract` from [@ton/core](https://www.npmjs.com/package/@ton/core))\n  * include message [de]serialization primitives, getter wrappers and compilation functions\n  * used by the test suite and client code to interact with the contracts from TypeScript\n* `compilables/` - Compilations scripts for contracts\n* `tests/` - TypeScript test suite for all contracts (relying on [Sandbox](https://github.com/ton-org/sandbox) for in-process tests)\n* `scripts/` - Deployment scripts to mainnet/testnet and other scripts interacting with live contracts\n* `build/` - Compilation artifacts created here after running a build command\n\n### Building contracts\n\n1. You need a compilation script in `compilables/\u003cCONTRACT\u003e.compile.ts` - [example](/example/compilables/Counter.compile.ts)\n2. Run interactive: \u0026nbsp;\u0026nbsp; `npx blueprint build` \u0026nbsp; or \u0026nbsp; `yarn blueprint build`\n3. Non-interactive: \u0026nbsp; `npx/yarn blueprint build \u003cCONTRACT\u003e` \u0026nbsp; OR build all contracts \u0026nbsp; `yarn blueprint build --all`\n   * Example: `yarn blueprint build counter`\n4. Build results are generated in `build/\u003cCONTRACT\u003e.compiled.json`\n5. Tact generated files are located in `build/\u003cCONTRACT\u003e` directory\n\n### Running the test suites\n\n1. Run in terminal: \u0026nbsp; `npx blueprint test` \u0026nbsp; or \u0026nbsp; `yarn blueprint test`\n2. Alternative method: \u0026nbsp; `npm test` \u0026nbsp; or \u0026nbsp; `yarn test`\n3. You can specify test file to run:  \u0026nbsp; `npm/yarn test \u003cCONTRACT\u003e`\n    * Example: `yarn test counter`\n\n\u003e Learn more about writing tests from the Sandbox's documentation - [here](https://github.com/ton-org/sandbox#writing-tests).\n\n### Deploying contracts\n\n1. You need a deployment script in `scripts/deploy\u003cCONTRACT\u003e.ts` - [example](/example/scripts/deployCounter.ts)\n2. Run interactive: \u0026nbsp;\u0026nbsp; `npx blueprint run` \u0026nbsp; or \u0026nbsp; `yarn blueprint run`\n3. Non-interactive: \u0026nbsp; `npx/yarn blueprint run deploy\u003cCONTRACT\u003e --\u003cNETWORK\u003e --\u003cDEPLOY_METHOD\u003e`\n   * Example: `yarn blueprint run deployCounter --mainnet --tonconnect`\n\n### Custom scripts\n\n1. Custom scripts should be located in `scripts` folder\n2. Script file must have exported function `run`\n```ts\nexport async function run(provider: NetworkProvider) {\n  // \n}\n```\n3. Script can be run using `npx/yarn blueprint run \u003cSCRIPT\u003e` command\n\n### Updating FunC version\n\nFunC version can be updated using `npx/yarn blueprint set func` command\n\n### Help and additional commands\n\nRun in terminal: \u0026nbsp; `npx blueprint help` \u0026nbsp; or \u0026nbsp; `yarn blueprint help`\n\n## Contract development\n\nBefore developing, make sure that your current working directory is located in the root of the project created using `npm create ton@latest`\n\n### Creating contracts\n\n1. Run interactive: \u0026nbsp;\u0026nbsp; `npx blueprint create` \u0026nbsp; or \u0026nbsp; `yarn blueprint create`\n2. Non-interactive: \u0026nbsp; `npx/yarn blueprint create \u003cCONTRACT\u003e --type \u003cTYPE\u003e` (type can be `func-empty`, `tolk-empty`, `tact-empty`, `func-counter`, `tolk-counter`, `tact-counter`)\n   * Example: `yarn blueprint create MyNewContract --type func-empty`\n\n### Writing contract code\n\n#### FunC\n1. Implement the standalone FunC root contract in `contracts/\u003cCONTRACT\u003e.fc`\n2. Implement shared FunC imports (if breaking code to multiple files) in `contracts/imports/*.fc`\n3. Implement wrapper TypeScript class in `wrappers/\u003cCONTRACT\u003e.ts` to encode messages and decode getters\n\n#### Tolk\n1. Implement the contract in `contracts/\u003cCONTRACT\u003e.tolk`; if you wish, split into multiple files\n2. Implement wrapper TypeScript class in `wrappers/\u003cCONTRACT\u003e.ts` to encode messages and decode getters\n\n#### Tact\n1. Implement the contract in `contracts/\u003cCONTRACT\u003e.tact`\n2. Wrappers will be automatically generated in `build/\u003cCONTRACT\u003e/tact_\u003cCONTRACT\u003e.ts`\n\n### Testing contracts\n\n1. Implement TypeScript tests in `tests/\u003cCONTRACT\u003e.spec.ts`\n2. Rely on the wrapper TypeScript class from `wrappers/\u003cCONTRACT\u003e.ts` to interact with the contract\n\n\u003e Learn more about writing tests from the Sandbox's documentation - [here](https://github.com/ton-org/sandbox#writing-tests).\n\n## Configuration\n\nA 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:\n```typescript\nimport { Config } from '@ton/blueprint';\n\nexport const config: Config = {\n    // config contents\n};\n```\nIt is important that the config is exported, is named `config`, and is not `default` exported.\n\nConfig's features are explained below.\n\n### Plugins\n\nBlueprint has a plugin system to allow the community to develop their own additions for the ecosystem without the need to change blueprint's code.\n\nIn order to use plugins, add a `plugins` array to your config:\n```typescript\nimport { Config } from '@ton/blueprint';\nimport { ScaffoldPlugin } from 'blueprint-scaffold';\n\nexport const config: Config = {\n    plugins: [new ScaffoldPlugin()],\n};\n```\n(This example shows how to add the [scaffold](https://github.com/1IxI1/blueprint-scaffold) plugin)\n\nHere are some of the plugins developed by the community:\n- [scaffold](https://github.com/1IxI1/blueprint-scaffold) - allows developers to quickly create a simple dapp automatically using the wrappers' code\n- [misti](https://github.com/nowarp/blueprint-misti) - simplifies workflow with the [Misti](https://nowarp.github.io/tools/misti/) static analyzer\n\n### Custom network\n\nA 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:\n```typescript\nimport { Config } from '@ton/blueprint';\n\nexport const config: Config = {\n    network: {\n        endpoint: 'https://toncenter.com/api/v2/jsonRPC',\n        type: 'mainnet',\n        version: 'v2',\n        key: 'YOUR_API_KEY',\n    },\n};\n```\n\nThe above config parameters are equivalent to the arguments in the following command:\n```bash\nnpx blueprint run --custom https://toncenter.com/api/v2/jsonRPC --custom-version v2 --custom-type mainnet --custom-key YOUR_API_KEY\n```\n\nProperties of the `network` object have the same semantics as the `--custom` flags with respective names (see `blueprint help run`).\n\nYou can also use custom network to verify contracts, like so:\n```bash\nnpx blueprint verify --custom https://toncenter.com/api/v2/jsonRPC --custom-version v2 --custom-type mainnet --custom-key YOUR_API_KEY\n```\n(or similarly using the config), however custom type MUST be specified as either `mainnet` or `testnet` when verifying.\n\n## Contributors\n\nSpecial thanks to [@qdevstudio](https://t.me/qdevstudio) for their logo for blueprint.\n\n## License\n\nMIT\n\n## Donations\n\nTON - `EQAQR1d1Q4NaE5EefwUMdrr1QvXg-8mDB0XI2-fwDBD0nYxC`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fton-org%2Fblueprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fton-org%2Fblueprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fton-org%2Fblueprint/lists"}