Wallets, keys and recovery

Every TON address on this install is a full, independent wallet whose secret this platform holds. There is no HD tree, no master seed, and no derivation index — a hundred customers holding TON means a hundred separate 24-word mnemonics sitting encrypted in one database table.

That shape decides what a backup has to contain, what a restore can and cannot recover, and what you can do for a single customer when the platform itself cannot pay them. Read Master wallets and the vault first — the vault, the passphrase trade-off and the two ways to lose an entire install are described there and are not repeated here.

How an address is created

The first time a user opens the deposit page for TON, the platform builds a wallet for them and never builds another one for that wallet row.

What is stored, and where

One row per ECO wallet, in wallet_data, keyed by the unique triple (walletId, currency, chain):

Decrypted, data is a small JSON object with exactly three fields:

{
  "mnemonic": "word word word … word",
  "publicKey": "…64 hex chars…",
  "privateKey": "…128 hex chars…"
}

mnemonic is the 24 words joined by single spaces. publicKey is the Ed25519 public key as hex. privateKey is the Ed25519 secret key as hex — the field name says private key, the value is the 64-byte secret key the signing library produces, and it is what the withdrawal path feeds back in.

The address itself is not in that blob. It lives in the wallet row:

{
  "TON": {
    "address": "UQ…",
    "network": "mainnet",
    "balance": 0
  }
}

network is a label stamped from TON_NETWORK at the moment the address was generated. Nothing re-reads it, and a TON account address is the same string on both networks, so it is a diagnostic breadcrumb rather than a setting.

The encrypted blob is the only persisted copy of that key material. Nothing is written to a plaintext file, no admin screen displays it, and there is no export button anywhere in the product — deliberately, because any file-read or backup leak would otherwise drain every address on the install.

The wallet version is part of the address

This is the single most expensive thing to misunderstand about TON custody.

An address is derived from the public key and the code of the wallet contract holding it. Change the contract version and the same key produces a completely different address. The platform creates v3R1 wallets, and modern mobile wallets default to v4R2 or W5.

The withdrawal path is built so this can never drift on the platform's side: it rebuilds the wallet from the stored public key, the stored secret key and the stored address, so the reconstructed contract is always the same account the deposits went to, whatever the library's current default happens to be.

What it does not do is look at any other version. Coins sent to a v4 address derived from the same key are invisible to this platform for ever.

Address form: UQ and EQ are the same account

A user-friendly TON address encodes a bounce flag in its first byte, which is what makes it start UQ (non-bounceable) or EQ (bounceable). Both decode to the same workchain and the same account hash.

The platform is non-bounceable everywhere. The address stored at creation is user-friendly and non-bounceable; every address the service re-renders — for fetching transactions, and for both ends of a withdrawal — is user-friendly, URL-safe and non-bounceable.

Two related format details are covered on Deposit addresses and detection: the stored address uses standard rather than URL-safe base64, so it can contain + and / — which the platform's own withdrawal form rejects — and a testnet install still renders the mainnet-style UQ… prefix.

Uninitialised contracts and the sequence number

A TON wallet contract is not deployed by receiving coins. It is deployed by sending them.

Before that, asking the account for its sequence number returns nothing. The withdrawal handler reads it, treats null, undefined and NaN alike as 0, and a transfer signed at seqno 0 carries the contract's initial state alongside it — so the customer's first outgoing transfer deploys the wallet and sends in one operation.

Three consequences worth knowing before you look at an explorer:

• A brand-new customer address will show as uninitialised or nonexistent on explorers even while it holds a balance. That is normal, not a fault.
• The first withdrawal from an address costs more in network fee than later ones, because it carries the contract deployment.
• The seqno read swallows every error. A rate-limited or timed-out read is indistinguishable from a genuinely undeployed contract, and both become 0. On an address that has already sent once, that produces a message the wallet contract will not accept — see Choosing and sizing the TON endpoint.

What a backup has to contain

A backup that actually covers TON custody is three things, stored in at least two places:

1. The database, including wallet_data (the keys) and wallet (the address map). Both tables — the address map is how you know which account a given blob belongs to without reconstructing it.
2. .env, or at minimum ENCRYPTED_ENCRYPTION_KEY, kept somewhere your database dumps are not.
3. The passphrase, kept somewhere neither of the first two live. It is the only thing that opens the key, and it is not in the database.

The raw 32-byte vault key is printed once, on screen, by node ./scripts/kms/generate.mjs when it first creates the value. If you kept that line, it is a second route to your own ciphertext and should be treated with the same care as the passphrase.

The TON master wallet is stored the same way — its own independent 24 words, encrypted with the same vault key, in ecosystem_master_wallet.data. It is not a fallback for anything; see below.

There is no master seed covering the estate

On the EVM chains, every customer address is derived from the master wallet's HD material at the next unused index, so one seed in principle regenerates them all. TON works nothing like that.

Each call that creates a TON address generates a fresh, unrelated mnemonic. The index column is always 0 and is not a derivation index. The TON master wallet is created by the very same routine as a customer wallet — it is one more independent v3R1 wallet that happens to belong to you, and it derives nothing, covers nothing and cannot sign for anything but itself. TON withdrawals never touch it; the customer's own address signs.

Two consequences, pulling in opposite directions:

Losing the TON master wallet strands nothing. Every customer key is self-contained. Create a new master wallet and the chain carries on.

Losing one wallet_data row loses one customer for ever. There is no seed to re-derive it from and no second copy. A restore that silently skips or truncates that table is a set of addresses you can never sign for again — verify row counts after any restore, per chain:

SELECT chain, currency, COUNT(*) FROM wallet_data GROUP BY chain, currency;

Recovering one customer by hand

Use this when the platform cannot pay a customer but the coins are demonstrably at their address — a wound-down install, a chain you have disabled, or a withdrawal path you no longer trust. It is not a routine operation.

Related

• Deposit addresses and detection — what happens at those addresses
• Withdrawals and fees — how the platform signs, and the two failure modes with money attached
• Choosing and sizing the TON endpoint — the seqno read and what throttling does to it
• Ecosystem: Master wallets and the vault — the vault, the passphrase and the install-wide recovery story
• Ecosystem: Deposit wallets and custody — the platform-wide custody model