WalletTg: Telegram wallet contract
WalletTg (tg-wallet, TgWallet, or Telegram Wallet) is the TON wallet contract used by Telegram's native Gram wallet.
Features
- Receive Gram, jettons, and non-fungible tokens (NFTs) at a stable address.
- Send a single message or a batch of up to 255 messages.
- Connect to decentralized applications (dApps) through TON Connect.
- Import 12-word phrases or 24-word rotation mnemonics in compatible wallet apps.
- Rotate the signing key while keeping the same address.
- Submit signed internal requests through a relayer that attaches Gram for processing.
Shared implementation
Each account stores immutable trampoline code. The trampoline loads the shared implementation from configuration parameter -123, while each account keeps its own balance and storage.
Validators approve configuration changes through voting. An update changes the implementation used by every WalletTg account on that network. Wallet owners cannot change the implementation or opt out of updates.
The brief contract reference documents storage and upgrade migration behavior.
Two-key rotation architecture
WalletTg is the only TON wallet contract that can rotate its public signing key without changing its address. Its 24-word rotation mnemonic combines two 12-word multichain mnemonics: the first half derives an anchor key, and the second half derives a signing key. The complete rotation mnemonic preserves both the anchor and the signing keys.
Initially, an anchor key is also the signing key. The contract's StateInit uses the anchor public key as its first signing public key. The rotation replaces the current on-chain signing key with a new one. It requires a request signed by the current private key and a rotation proof signed by the new private key. The anchor key does not change.
After rotation, only the new signing key authorizes requests — the anchor key continues to derive the original address, but it cannot restore signing access on its own.
Composing a new StateInit with the new signing key would yield a different address. The original StateInit must always be composed with the original signing key, which is the anchor key.
Comparison with V5
Wallet V5 is the default general-purpose wallet contract on TON. It does not rotate the signing key, has an optional extensions support, and does not allow code upgrades. Additionally, V5 uses a different messages format compared to the WalletTg messages.
WalletTg is used primarily by Telegram. Wallet apps and services should default to Wallet V5 for all new TON wallet contracts, but also support importing rotation mnemonics and managing WalletTg contracts.
Compare wallet capabilities in the table.