Tolk 1.4 в TON: ABI, TypeScript-врапперы, source maps

11 мая 2026 команда TON выпустила Tolk 1.4, а 23 мая — патч 1.4.1 к нему. Это самый крупный апдейт языка с момента его релиза: появились ABI, TypeScript-врапперы, source maps и debugger marks, плюс декларативный contract-блок.

Разберём, что это значит для разработчиков и почему 1.4 — не «ещё один минорный апгрейд», а инфраструктурный сдвиг.

Главная идея 1.4: контракт как декларация

Раньше Tolk-файл выглядел как набор функций — onInternalMessage, get-методы, вспомогательные функции — и компилятор по сигнатурам догадывался, что это контракт. С 1.4 у вас появляется явный декларативный блок:

contract Counter {
    author: "Tolk Team"
    version: "0.1"
    description: "A small counter contract"

    storage: ContractStorage
    incomingMessages: Increment | Reset
}

// далее весь код как раньше:
// - типы и объявления
// - onInternalMessage
// - get methods

Этот блок не меняет байткод. Его задача — дать тулингу машинно-читаемое описание контракта. Из него компилятор знает:

• Кто автор и какая версия (для UI и блок-эксплореров).
• Какой тип используется в storage.
• Какие сообщения контракт умеет принимать.

С такой декларацией контракт перестаёт быть «непрозрачным набором функций» — он становится объектом с метаданными, понятными tooling’у.

ABI: автоматическая генерация интерфейса

Самое практичное следствие contract-блока — автоматический экспорт ABI. ABI (application binary interface) — это машинно-читаемое описание входов и выходов контракта: какие сообщения принимает, в каком формате, какие get-методы возвращают какие типы.

До 1.4 ABI на TON приходилось писать руками — отдельный JSON или YAML, который надо было синхронизировать с кодом контракта. После каждого изменения сигнатуры — обновлять ABI, иначе клиентская сторона валилась.

С 1.4 компилятор Tolk сам генерирует ABI из contract-декларации. То есть:

1. Изменили storage — ABI обновился автоматически.
2. Добавили новое incoming-сообщение — ABI знает о нём.
3. Создали новый get-метод — ABI его экспортирует.

Что это даёт: блок-эксплореры могут парсить транзакции по контракту с понятными именами полей, UI dApp’ов — генерировать формы под конкретные сообщения, тестовые тулзы — знать, какие методы вызывать.

TypeScript-врапперы: клиентский код почти бесплатно

Поверх ABI 1.4 даёт автоматическую генерацию TypeScript-врапперов. Это клиентская обёртка для вашего контракта, которая знает все его методы и сообщения, и предлагает их вам с автокомплитом и проверкой типов в IDE.

До 1.4 типичный workflow для подключения контракта в dApp выглядел так:

1. Написать контракт на Tolk/FunC.
2. Написать руками TypeScript-классы для каждого incoming-сообщения и каждого get-метода.
3. Сериализовать руками, парсить ответы руками.
4. При изменении контракта — синхронно обновлять TS-код.

С 1.4 шаги 2-4 делает компилятор. Вы пишете контракт, запускаете сборку — получаете готовый TS-модуль, который импортируется в dApp и сразу работает. Пример вызова:

import { Counter } from './tolk-output/Counter';

const counter = Counter.fromAddress(address);
await counter.send(provider, sender, value, { op: 'Increment' });
const value = await counter.getValue(provider);

Без 1.4 это всё надо было писать вручную; в 1.4 — генерируется.

Source maps и debugger marks: дебаг прямо по Tolk

Главное страдание TON-разработчика годами — отсутствие нормального отладчика. Контракт упал на 7-й инструкции TVM — поищи в байткоде, что это. С 1.4 это в прошлом.

Source maps. Это сопоставление между байткодом TVM и исходником Tolk: компилятор сохраняет, какая инструкция TVM соответствует какой строке вашего кода, какие переменные где в стеке, как устроены call frames. Когда транзакция падает на конкретной TVM-инструкции, source maps позволяют посмотреть: «упало здесь, в этой строке Tolk, в этой функции».

Debugger marks. Это маркеры, встраиваемые компилятором в байткод, по которым отладчик умеет делать брейкпойнты и step-by-step выполнение даже на полностью оптимизированных production-контрактах. Раньше для отладки приходилось собирать контракт в debug-режиме (медленный, не оптимизированный); теперь дебагать можно прямо рабочую версию.

Что это значит на практике: разработчик может взять production-контракт, прогнать на нём конкретную транзакцию в локальном эмуляторе с пошаговым выполнением — и видеть, где именно пошло не так. До 1.4 такого инструмента в TON фактически не было.

Новые правила импортов

contract-блок приносит с собой два правила, которые меняют структуру проекта:

Правило 1: все get-методы — в одном файле с contract. Раньше Tolk позволял раскидывать get-функции по нескольким файлам и импортировать их. С 1.4, если вы используете contract MyContract, все entrypoint’ы (onInternalMessage, onExternalMessage, get-методы) должны лежать в том же файле, что и декларация. Это не работает:

// файл: separate-getter.tolk
get fun method1() { ... }

// файл: MyContract.tolk
import "separate-getter"   // ошибка компиляции

contract MyContract { ... }

Зачем это сделано: чтобы файл с contract показывал весь интерфейс контракта в одном месте. Это упрощает чтение и понимание стороннему разработчику.

Правило 2: import "MyContract" не подтягивает entrypoint’ы. Если в проекте несколько контрактов (JettonMinter + JettonWallet), вы можете теперь импортировать один из другого без конфликта по onInternalMessage. До 1.4 приходилось аккуратно выносить общие типы в отдельные файлы; в 1.4 — contract-блок «прячет» внутренние entrypoint’ы при импорте.

Полезный side-effect: тесты можно писать как get-методы в отдельных файлах того же проекта. Они не конфликтуют с get-методами самого контракта, и в них работают все импортированные типы:

import "Counter"

get fun `test increase does not overflow`() {
    val initial = Storage { value: 0 };
    // ... тесты
}

PascalCase для имён файлов

Tolk 1.4 переходит на предпочтительное соглашение: имя файла = имя контракта в PascalCase. То есть JettonMinter.tolk вместо jetton_minter.tolk. Это не обязательно (старые имена работают), но идиоматично — и улучшает читаемость в IDE и в импортах.

Что в 1.4.1

Релиз 1.4.1 от 23 мая 2026 описан как «small fixes and minor updates» — стабилизирующий патч после 1.4.0. Конкретный список фиксов команда не публикует в развёрнутом виде, но факт самого патча через 12 дней говорит, что 1.4.0 поймал минорные баги, которые быстро поправили. Если вы переходите на 1.4 сейчас — берите сразу 1.4.1.

Кому обновляться и когда

Если вы автор активно поддерживаемого контракта на Tolk:

• Поставьте 1.4.1 на dev-машину, прогоните билд проекта.
• Добавьте contract-декларацию в основные файлы — получите ABI и TS-враппер бесплатно.
• В CI добавьте генерацию TS-модулей рядом с собранным контрактом.

Если вы планируете новый проект:

• Сразу начинайте с contract-блока. PascalCase для имён файлов.
• Используйте автоген TypeScript-врапперов — это сэкономит дни на интеграции с dApp.

Если вы на FunC:

• 1.4 — это сильный аргумент посмотреть в сторону Tolk. ABI и TS-врапперы из коробки — то, чего у FunC нет и не будет. Введение в язык — в нашем материале про Tolk.

Если вы только начинаете изучать TON-смарт-контракты:

• Tolk 1.4 + ABI + TypeScript-врапперы — самый низкий порог входа за всю историю TON. Начинайте с Tolk, не с FunC.

Что дальше

Согласно PR’у Tolk 1.4 и комментариям команды, ABI и source maps — «финальные части первоначальной визии». Это значит, что фундаментальный набор фич Tolk теперь complete. Что вероятно идёт следом:

• Дальнейшие language enhancements (типы, дженерики, паттерны).
• Расширение IDE-поддержки (debug UI, integration с TON Studio).
• Стандартизация ABI как формата экосистемы (чтобы блок-эксплореры и UI-фреймворки парсили один и тот же ABI).

Параллельно с Tolk развивается и сам TVM — апгрейд до TVM v14 идёт в TON Core v2026.05-rc. См. наш разбор релиза TON Core — там детали изменений, на которые Tolk 1.5+ будет опираться.

Полная экосистема разработки на TON — в сравнении SDK. Практика первого контракта (если ещё не писали) — в материале про Acton.