gramdocs.tech
Документация

Локальный TON-нод: зачем и как поднять

Поймёшь, когда нужен свой нод, и поднимешь liteserver через официальный Docker-образ MyTonCtrl.

Когда свой нод нужен — и когда нет

Для разработки контрактов почти всегда хватает @ton/sandbox и публичных API (Toncenter / TonAPI). Свой нод имеет смысл, если:

  • поднимаешь свой индексёр (ton-index-worker / TON-ETL) и не хочешь упираться в чужие rate limit;
  • нужен приватный liteserver с предсказуемой latency;
  • готовишь инфраструктуру валидатора / архивной ноды (это уже ops, не «локалка для Tact»).

Полная синхронизация mainnet — сотни GB и часы/дни. Для учебы контрактов это избыточно.

Liteserver в Docker (MyTonCtrl)

Официальный образ: ton-blockchain/ton-docker-ctrl. Минимальный старт на testnet:

bash
# docker compose + MyTonCtrl (образ ghcr.io/ton-blockchain/ton-docker-ctrl)
mkdir ton-node && cd ton-node

curl -fsSL -o .env \
  https://raw.githubusercontent.com/ton-blockchain/ton-docker-ctrl/main/.env
curl -fsSL -o docker-compose.yml \
  https://raw.githubusercontent.com/ton-blockchain/ton-docker-ctrl/main/docker-compose.yml

В .env обязательно задай публичный IP и testnet-конфиг:

bash
# фрагмент .env — testnet liteserver
PUBLIC_IP=203.0.113.10
TON_BRANCH=testnet
GLOBAL_CONFIG_URL=https://ton.org/testnet-global.config.json
MODE=liteserver
DUMP=true
VALIDATOR_PORT=30001
LITESERVER_PORT=30003
bash
docker compose up -d
docker exec -it ton-node bash
mytonctrl
# внутри MyTonCtrl: status — дождись синхронизации (out of sync → 0)

После синка получи локальный config для клиентов (local.config.json / команда печати liteserver-конфига в MyTonCtrl) и укажи его в Blueprint:

typescript
// @ton/blueprint — liteclient вместо публичного HTTP
import { Config } from "@ton/blueprint";

export const config: Config = {
  network: {
    endpoint: "/absolute/path/to/local.config.json",
    version: "liteclient",
    type: "testnet",
  },
};

Для полностью изолированной dev-сети смотри MyLocalTon в документации TON — это отдельный локальный блокчейн, не синхронизация публичного testnet/mainnet.

Как это работает

  • Нода хранит шарды/блоки и отвечает по протоколу lite-client.
  • MyTonCtrl — операторская обёртка: режимы validator / liteserver, статус синка, кошельки ноды.
  • DUMP=true ускоряет первичный sync ценой скачивания дампа.
  • Приложениям обычно не нужна полная нода: достаточно стабильного HTTP API или одного liteserver endpoint.

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

Стартуешь без PUBLIC_IP → контейнер не поднимается или пиры не видят ноду. Укажи реальный IPv4 и открой UDP VALIDATOR_PORT.

Ждёшь «лёгкий» mainnet на ноутбуке → диск и время не рассчитаны на это. Для разработки бери testnet + dump или оставайся на Sandbox/публичном API.

Путаешь свой нод с Sandbox → Sandbox не ходит в сеть и не заменяет liteserver. Unit-тесты — в Sandbox; интеграция с реальной цепью — testnet API или свой нод.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация