TON wallet mnemonics

Key pair

TON wallet mnemonics use asymmetric cryptography and derive Ed25519 key pairs. The private key signs wallet messages as message signatures, while the contract verifies these signatures with the public key in its account state.

Mnemonic schemes

TON, multichain, and rotation mnemonics use the BIP-39 English word list. They have different validation and derivation rules.

For new wallets, a 12-word multichain phrase is recommended, while a 24-word TON phrase may also be used.

Multichain mnemonic derivation

Normalize the phrase and optional BIP-39 passphrase with NFKD. Use the phrase as the PBKDF2-HMAC-SHA512 password, with 2048 iterations and salt mnemonic followed by the normalized passphrase. The output is a 64-byte seed. The passphrase defaults to empty and differs from a TON password.

Derive an Ed25519 key with BIP-44 and SLIP-0010 at TON path m/44'/607'/{i}'. For instance, index 0 gives m/44'/607'/0'. Record the path and index because a different index derives a different key pair.

The derivation-path index is separate from the wallet contract's subwalletId. A derived key can initialize different wallet contracts or subwallet IDs, producing different addresses from their StateInit and workchain.

Mnemonic import and scheme detection

Accept 12- and 24-word input. Treat a 12-word phrase as multichain.

For a 24-word phrase, check TON mnemonic validity with the supplied TON password, if applicable. Check the BIP-39 checksum for all 24 words. If the wallet supports rotation, check the BIP-39 checksum of each 12-word half.

If exactly one supported scheme matches, import with that scheme. If several match, derive and show each candidate account for user selection; do not choose silently. Reject a phrase that matches no supported scheme.

Rotation mnemonic

A rotation mnemonic has two independently valid 12-word multichain halves. Derive each half separately at m/44'/607'/0'. Do not derive one seed from all 24 words.

The anchor half must come from a cryptographically secure random source. It does not rotate.

Before all rotations, words 13-24 repeat words 1-12 — that is, anchor key is identical to the signing key upon deployment of the WalletTg contract. Each rotation must replace them with a new 12-word multichain phrase from a cryptographically secure random source.

The new, rotated half must be independent of the anchor and all earlier signing halves. A wallet must not derive it from an old key or set it back to the anchor.

A rotation-capable contract must keep its current signing key separate from the values that determine its address. It must accept only the stored current key for ordinary outgoing messages.

Key pair from a mnemonic

To transform a TON mnemonic phrase into a key pair, a seed is first derived using PBKDF2, and the key pair is then derived from that seed.

PBKDF2 has five input parameters: PRF, Password, Salt, c, and dkLen. Each of those parameters is assigned a concrete value.

Seed of the mnemonic is derived with PBKDF2 with these parameters:

The first 32 seed bytes initialize the Ed25519 private key.

Generate a key pair

import { mnemonicNew, mnemonicToPrivateKey } from '@ton/crypto';

const mnemonic = await mnemonicNew(24);
const keyPair = await mnemonicToPrivateKey(mnemonic);

console.log(`Public key: ${keyPair.publicKey.toString('hex')}`);

This example generates a TON mnemonic and prints only the public key. The same words and TON password always produce the same key pair.

Mnemonic validation

Require all 24 words to be in the BIP-39 English word list. Notice, that TON validity does not use the BIP-39 checksum, but the TON seed.

Following TON seed checks use entropy from the HMAC step as the PBKDF2-HMAC-SHA512 password and produce 64 bytes:

For a phrase without a TON password, the basic-seed check must pass with an empty password. For a password-enabled phrase, the password marker must pass and the basic-seed check must fail without the password. The basic-seed check must then pass with the supplied password. Use a TON mnemonic implementation for these checks.

Generate a mnemonic

import { mnemonicNew, mnemonicValidate } from '@ton/crypto';

const mnemonic = await mnemonicNew(24);
console.log(await mnemonicValidate(mnemonic));

The example prints true for a valid phrase, not the recovery phrase. tonlib selects words from the BIP-39 list using secure random bytes. It retries until TON checks pass.