Understanding TON Wallet Contracts: A Comprehensive Guide

The Open Network (TON) blockchain supports a variety of wallet implementations, each designed with specific functionality and security features. These wallets are not traditional software applications but smart contracts that manage user funds and enable secure interactions on the network.

In this guide, we’ll break down the evolution of TON wallet contracts, from the basic V1 to the advanced V5, and explore special-purpose wallets like high-load, lockup, and restricted versions. Whether you're a developer building on TON or a user seeking deeper understanding, this article will clarify how wallet versions differ and which one suits your needs.

👉 Discover how modern wallet contracts empower decentralized applications today.

Core Concepts Behind TON Wallets

Before diving into versions, it’s essential to understand that TON wallets are smart contracts—not standalone apps. They reside on the blockchain and interact through messages, just like any other contract.

Key concepts you should be familiar with:

• Message management: Wallets process external and internal messages to execute transactions.
• FunC language: The primary programming language used to write TON smart contracts.

Wallets in TON follow a standard interface, allowing different clients (wallet apps) to interact with them uniformly. All core implementations are open-sourced in the official TON monorepo, particularly under crypto/smartcont/.

While wallets can receive messages, send funds, and expose get methods, their security model relies heavily on:

• Sequence numbers (seqno): Prevent replay attacks.
• Ed25519 signatures: Ensure only authorized users trigger actions.

Now let’s explore how these principles evolve across wallet versions.

Wallet V1: The Foundation

Wallet V1 is the simplest implementation, serving as the baseline for all future versions.

Key Features

• Supports up to four transactions per message.
• Validates only signature and sequence number.
• No built-in way to retrieve public key or check transaction expiration.

Due to limitations like missing valid_until checks and no public key getter, V1 is rarely used in production. These issues were addressed in later revisions: V1R2 and V1R3, which added get_public_key() and improved usability.

Data Structure

• seqno: 32-bit sequence number.
• public-key: 256-bit Ed25519 public key.

Message Layout

An external message includes:

• Signature (512 bits)
• Sequence number
• Up to four sending modes
• Up to four message references (cells)

Exit Codes

Developers must ensure internal messages are correctly formatted—wallets do not validate payload structure.

Wallet V2: Adding Time Constraints

Wallet V2 introduces the valid_until field, a critical upgrade for transaction safety.

What Changed?

• Added UNIX timestamp (valid-until) to prevent delayed execution.
• New exit code 0x23 triggers if transaction exceeds time limit.

This version ensures transactions cannot be processed too late, reducing risk in unreliable network conditions.

Revisions V2R1 and V2R2 further refined functionality, with V2R2 adding the public key getter.

👉 See how time-bound transactions enhance security in decentralized systems.

Wallet V3: Multi-Wallet Support via Subwallet ID

Currently the most widely used version, Wallet V3 enables multiple wallets under a single keypair using subwallet_id.

Why It Matters

• Users can generate multiple addresses from one seed phrase.
• Each subwallet has a unique address due to hashing of state + code + subwallet_id.

This design improves privacy and organization without compromising security.

Data Layout

• seqno: 32-bit
• subwallet: 32-bit ID
• public-key: 256-bit

Enhanced Message Format

Includes:

• Signature
• Subwallet ID
• Sequence number
• valid-until timestamp
• Sending modes and message references

Exit Codes

New code 0x22 indicates mismatched subwallet ID, enhancing error clarity.

Popular implementations use V3R2, which includes full getter support.

Wallet V4: Introducing Plugin Architecture

Wallet V4 brings a groundbreaking feature: plugins—smart contracts that interact programmatically with your wallet.

Plugin Functionality

Plugins are stored in a dictionary within wallet storage. Once approved, they can:

• Request fund transfers.
• Remove themselves from the allowed list.

Use cases include automated payments, subscription services, or DApp integrations requiring recurring actions.

External Operations (Op-Codes)

Plugins must be deployed separately unless using op-code 0x1, which handles deployment via state_init.

Internal Message Handling

Unlike earlier versions, V4 processes internal messages with logic:

• op-code = 0x706c7567: Request funds.
• op-code = 0x64737472: Remove plugin.

Exit codes like 0x27 (plugin manipulation failure) and 0x50 (insufficient funds) help debug issues.

Get Methods

V4 expands query capabilities:

• is_plugin_installed(wc, addr_hash)
• get_plugin_list()

This transparency empowers users to monitor active integrations.

Wallet V5: The Future of Smart Wallets

Developed by Tonkeeper, Wallet V5 represents the next generation—supporting gasless transactions, account delegation, and up to 255 actions per message.

Key Upgrades

• Gas-free transactions: Third-party services pay fees in Toncoin while charging fees in tokens (e.g., USDt).
• Account recovery & delegation: Flexible access control via extensions.
• High-throughput transfers: Ideal for DeFi and mass payouts.

State Structure

ContractState {
  is_signature_allowed: 1-bit flag
  seqno: 32-bit
  wallet_id: 32-bit
  public_key: 256-bit
  extensions_dict: hashmap(256 → int)
}

The is_signature_allowed flag allows disabling signature-based access—critical for securing compromised keys.

Authentication Modes

V5 supports two paths:

1. Signature-based: Traditional owner access.
2. Extension-based: Auth via registered smart contracts.

This dual model enables third-party relayers to submit transactions on behalf of users—enabling true gasless experiences.

Action System

All operations go through InnerRequest, which supports:

• OutList: Chain of outgoing messages (up to 255).

• ActionList: Extended operations:

  • Add/remove extension (action_add_ext, action_delete_ext)
  • Toggle signature access (action_set_signature_auth_allowed)

This modular approach makes V5 highly extensible.

Exit Codes (Partial List)

These codes prevent accidental lockout scenarios.

Get Methods

• is_signature_allowed()
• get_extensions() returns full dictionary

Special-Purpose Wallets

Beyond standard versions, TON offers specialized contracts for niche use cases.

Highload Wallets

Designed for services processing high-frequency transactions, such as exchanges or payment gateways. Optimized for low latency and bulk operations.

Learn more in the Highload Wallet specification.

Lockup Wallets

Ideal for vesting schedules or long-term savings. Funds are locked until a defined time, with optional periodic unlocks.

Example: Lock 1M TON for 10 years, with 8,333 TON unlocking monthly after a 1-year cliff.

Source: lockup-wallet-contract

Restricted Wallets

Limits all outgoing transfers to a single predefined address. Useful for payroll systems or automated treasury management.

Note: Still allows staking-related transfers (e.g., validator deposits).

Source: restricted-wallet

Frequently Asked Questions

Q: Which wallet version should I use in my app?
A: For most users and developers, V3R2 or V4R2 offer the best balance of compatibility and features. If you need gasless transactions or advanced extensibility, consider upgrading to V5.

Q: Can I upgrade my wallet from V3 to V5?
A: Not directly. You’d need to deploy a new contract instance. However, since both use the same keypair, you can manage both from one seed phrase.

Q: Are plugins safe? How do I avoid malicious ones?
A: Plugins require explicit approval via signed transaction. Always verify the contract address and code before installation. Treat plugins like app permissions—only trust audited sources.

Q: What are gasless transactions and how do they work?
A: Gasless transactions let users pay fees in tokens instead of Toncoin. A relayer pays the blockchain fee in Toncoin and charges a small fee in USDt or another token. This improves UX for non-custodial wallets.

Q: How do I check my wallet’s version?
A: Use a blockchain explorer like tonviewer.com or query the contract code hash programmatically. Compare it with official hashes listed in documentation.

Q: Can I lose access to my wallet using V5’s signature toggle?
A: Yes—if you disable signature access and remove all extensions, you may permanently lock yourself out. Always maintain at least one active extension or keep signature access enabled during setup.

Final Thoughts

TON wallet contracts have evolved significantly—from simple transaction relays in V1 to programmable identity hubs in V5. Each version builds upon the last, introducing stronger security, better usability, and new capabilities like plugins and gasless transactions.

For everyday use, V3R2 remains reliable, while V5 opens doors for next-gen dApps. Specialized wallets further expand what’s possible—from automated vesting to high-throughput trading systems.

As TON continues growing, understanding these smart contract patterns becomes crucial for developers and informed users alike.

👉 Start building smarter wallet integrations with cutting-edge blockchain tools.