Seed-фразы и приватные ключи в TON

Выведешь ключи из BIP39-мнемоники через @ton/crypto, поймёшь связь seed → keypair → адрес и правила хранения секретов.

Seed — это корень ключей, не «пароль от биржи»

Seed-фраза (обычно 24 слова BIP39) детерминированно порождает пару Ed25519: publicKey + secretKey. Публичный ключ вместе с версией контракта кошелька задаёт адрес. Кто знает seed — владеет всеми средствами на всех версиях кошелька, выведенных из этой фразы.

В экосистеме TON стандартная библиотека — @ton/crypto (mnemonicNew, mnemonicToPrivateKey / mnemonicToWalletKey).

Генерация и вывод ключей (только testnet/sandbox)

typescript

// @ton/crypto ^3.3.0, @ton/ton ^15.1.0
import { mnemonicNew, mnemonicToPrivateKey } from "@ton/crypto";
import { WalletContractV4 } from "@ton/ton";

// 1) Новая фраза — только для sandbox/testnet. Никогда не коммить в git.
const words = await mnemonicNew(24);
console.log(words.join(" ")); // сохрани офлайн; это полный доступ к кошельку

// 2) Ключи из фразы
const keyPair = await mnemonicToPrivateKey(words);
// keyPair.publicKey — 32 байта
// keyPair.secretKey — 64 байта (seed+pub в формате библиотеки)

const wallet = WalletContractV4.create({
  workchain: 0,
  publicKey: keyPair.publicKey,
});

console.log(
  wallet.address.toString({ bounceable: false, testOnly: true }),
);

Для скриптов на testnet фразу берут из env / secret manager, не из репозитория. В открытом .env без шифрования seed = утечка при любом бэкапе или скриншоте.

Правила:

Действие	Допустимо
`mnemonicNew` в локальном скрипте → запись в password manager	да
Seed в CI secrets / encrypted vault для бота на testnet	да, с ограничением доступа
Seed в клиентском JS / публичном репо / чате	нет
Просить seed пользователя в dApp	нет — используй TON Connect

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

mnemonicNew(24) — энтропия → 24 слова по словарю BIP39.
mnemonicToPrivateKey применяет схему TON ("TON default seed" / PBKDF2 внутри @ton/crypto) → Ed25519 keypair.
Адрес не равен публичному ключу: адрес = хеш StateInit выбранной версии кошелька.
Одна фраза → бесконечно много адресов (v3/v4/v5, subwallet, workchain).

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

Вставил seed mainnet «для примера» в статью или issue → считай ключ скомпрометированным; переведи средства на новый кошелёк.

Хранишь seed в .env на проде без шифрования и ACL → любой с доступом к диску/бэкапу забирает баланс. Для серверных ботов — HSM/KMS или как минимум encrypted secret store + минимальные права.

Путаешь secretKey (64 байта) и «32-байтный seed» из других экосистем → в TON SDK используй пару из @ton/crypto as-is; не обрезай байты наугад.

Что дальше

Кошельки TON: версии контрактов v3/v4/v5 — один seed, разные адреса
Восстановление доступа к кошельку — импорт фразы и выбор версии
Tonkeeper: подключение и работа с расширением — dApp без seed

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