Blueprint

Blueprint — это официальный фреймворк для разработки, тестирования и деплоя смарт-контрактов на TON. Подобно тому, как Hardhat стал стандартом для Ethereum-разработки, Blueprint объединяет компиляцию, тестирование и деплой в единый workflow. Знание Blueprint экономит часы рутинной работы и обеспечивает воспроизводимость результатов при командной разработке.

Blueprint — официальный инструментарий (toolchain) для разработки смарт-контрактов на TON. Он объединяет компиляцию, тестирование и деплой в единый рабочий процесс.

Что такое Blueprint?

Blueprint для TON — это аналог Hardhat/Foundry для Ethereum. Он предоставляет:

• Создание проекта — шаблон с правильной структурой
• Компиляция — Tact/FunC/Tolk в TVM bytecode
• Тестирование — интеграция с Sandbox (локальный эмулятор)
• Деплой — скрипты для деплоя в testnet/mainnet
• Wrappers — TypeScript-обёртки для взаимодействия с контрактами

Создание проекта

npm create ton@latest

Эта команда запускает интерактивный мастер создания проекта. Вы выбираете:

• Имя проекта
• Язык контракта (Tact, FunC, Tolk)
• Шаблон (Empty, Counter, Jetton)

Структура проекта

Директория contracts/

Здесь хранятся исходные файлы контрактов. Для Tact это файлы .tact:

// contracts/counter.tact
import "@stdlib/deploy";

contract Counter with Deployable {
    counter: Int as uint32;

    init() {
        self.counter = 0;
    }

    receive("increment") {
        self.counter += 1;
    }

    get fun counter(): Int {
        return self.counter;
    }
}

Директория wrappers/

Wrappers — TypeScript-классы, которые оборачивают скомпилированный контракт для удобного взаимодействия из тестов и скриптов:

// wrappers/Counter.ts
import { Address, beginCell, Cell, Contract,

         ContractProvider, Sender, SendMode } from '@ton/core';

export class Counter implements Contract {
    constructor(
        readonly address: Address,
        readonly init?: { code: Cell; data: Cell }
    ) {}

    // Отправить сообщение "increment"
    async sendIncrement(provider: ContractProvider, via: Sender) {
        await provider.internal(via, {
            value: '0.02',
            body: beginCell()
                .storeUint(0, 32)           // op = 0 (текстовое сообщение)
                .storeStringTail('increment')
                .endCell(),
        });
    }

    // Вызвать get-метод
    async getCounter(provider: ContractProvider): Promise<bigint> {
        const result = await provider.get('counter', []);
        return result.stack.readBigNumber();
    }
}

Основные команды

Сборка (Build)

npx blueprint build

Компилирует все контракты из contracts/. Результат — скомпилированные Cell-файлы в директории build/.

Процесс компиляции:

1. Tact компилирует .tact в .fc (FunC)
2. FunC компилирует .fc в TVM bytecode
3. Bytecode упаковывается в Cell (BoC формат)

Тестирование (Test)

npx blueprint test

Запускает Jest-тесты из директории tests/. Тесты используют @ton/sandbox для локальной эмуляции блокчейна (подробнее в следующем уроке).

Запуск скриптов (Run)

npx blueprint run deployCounter
npx blueprint run deployCounter --testnet
npx blueprint run deployCounter --mainnet

Выполняет TypeScript-скрипт из scripts/. Флаги --testnet и --mainnet определяют сеть.

Конфигурация

// blueprint.config.ts
import { Config } from '@ton/blueprint';

export const config: Config = {
    network: {
        endpoint: 'https://toncenter.com/api/v2/jsonRPC',
        type: 'mainnet',
        version: 'v2',
        apiKey: process.env.TONCENTER_API_KEY,
    },
};

Рабочий процесс разработки

Типичный workflow с Blueprint:

1. Создать проект        → npm create ton@latest
2. Написать контракт     → contracts/myContract.tact
3. Собрать               → npx blueprint build
4. Написать тесты        → tests/MyContract.spec.ts
5. Запустить тесты       → npx blueprint test
6. Деплой в testnet      → npx blueprint run deploy --testnet
7. Проверить в explorer  → tonscan.org/testnet
8. Деплой в mainnet      → npx blueprint run deploy --mainnet

Частые ошибки

1. Не инициализируют проект через npm create ton@latest, а пытаются настроить структуру вручную, что приводит к отсутствию важных конфигурационных файлов.
2. Забывают запускать npx blueprint build перед тестированием: тесты используют скомпилированный артефакт, и устаревшая версия может скрыть баги.
3. Путают скрипты деплоя и тестовые скрипты: деплой-скрипт отправляет реальную транзакцию, а тест работает в sandbox.
4. Не используют wrappers, сгенерированные Blueprint, для взаимодействия с контрактом, что приводит к ручной сериализации сообщений и частым ошибкам.