Wallet contract version

Wallet contract version refers to the exact revision of the smart-contract code that represents a user’s wallet on TON. Unlike EVM chains, where an address is just a derivation of a public key, every TON user has a real contract deployed on-chain. Which code is deployed defines both the feature set and the address itself.

Why the address depends on the version

A TON contract’s address is the hash of its initial state, which includes the contract code and the initial data (public key, seqno, etc.). Different code yields a different hash, which yields a different address. This is the core reason upgrading from v4R2 to v5R1 produces a new address for the same seed phrase — it is not a bug, it is how addressing works on TON.

Versions in production

• v3R2 — the early baseline, dominant before 2022. Supports plain Toncoin transfers and arbitrary outbound messages. Minimal logic and gas footprint. Still present for users who created their wallet early and never upgraded.
• v4R2 — added plugins and subscription support: the contract can store a list of sub-contracts allowed to pull funds on a schedule. Plugins never reached mass usage, but v4R2 served for years as the default wallet code in Tonkeeper and other major wallets.
• v5R1 / W5 — released in 2024 and the current default in most wallets. Key changes:
  • Gasless transfers. The fee for a jetton transfer can be paid in the jetton itself (USDT, for example) rather than in Toncoin. This solves the classic “I have USDT but no TON for gas” problem.
  • Batched messages. Up to 255 outbound messages in a single transaction, versus 4 in v4. Useful for airdrop distributions and multi-step DeFi flows in one click.
  • Extensions. A more flexible plugin model than v4R2’s design.

Adjacent contract families exist: Highload Wallet (high-throughput variant for exchanges and services) and Multisig wallets. These are separate lineages, not just newer versions of the regular wallet.

The upgrade UX problem

Because the address changes with the version, wallets typically display several addresses under one seed: “v4R2 with 0 TON”, “v5R1 with 12 TON”. When upgrading, the user must manually move funds from the old address to the new one, and incoming payments keep arriving at the old address until counterparties update their records.

Tonkeeper, MyTonWallet and Tonhub all support the active versions and let users switch between them in settings. Fresh installs usually start at v5R1/W5 by default.

When each version makes sense

• Regular user — v5R1/W5, the default.
• Exchange or service running thousands of withdrawals per hour — Highload Wallet.
• A team that needs joint approval for transactions — Multisig.
• Legacy v3R2/v4R2 wallets are worth upgrading, especially if gasless USDT transfers are useful.