Wallets history - TON Docs

You may have heard about different versions of wallets on TON Blockchain. But what do these versions actually mean, and how do they differ? In this article, we will explore the various versions and modifications of TON wallets.

Common concept

We should first understand that wallets are not a specific entity in the TON ecosystem. They are still just smart contracts consisting of code and data, and, in that sense, are equal to any other actor (i.e., smart contract) in TON. Read more about differences. Like your own custom smart contract, or any other one, wallets can receive external and internal messages, send internal messages and logs, and provide get methods. So the question is: what functionality do they provide and how do they differ between versions? You can consider each wallet version as a smart contract implementation providing a standard external interface, allowing different external clients to interact with the wallets in the same way. You can find these implementations in FunC and Fift languages in the main TON monorepo:

ton/crypto/smartcont/

Basic wallets

Wallet contract hashes

Here, you can find the current hashes of the wallet contract code versions. For detailed specifications of each wallet contract, please refer further down the page or check the ContractSources.md.

Contract version	Hash
V1 R1	`a0cfc2c48aee16a271f2cfc0b7382d81756cecb1017d077faaab3bb602f6868c`
V1 R2	`d4902fcc9fad74698fa8e353220a68da0dcf72e32bcb2eb9ee04217c17d3062c`
V1 R3	`587cc789eff1c84f46ec3797e45fc809a14ff5ae24f1e0c7a6a99cc9dc9061ff`
V2 R1	`5c9a5e68c108e18721a07c42f9956bfb39ad77ec6d624b60c576ec88eee65329`
V2 R2	`fe9530d3243853083ef2ef0b4c2908c0abf6fa1c31ea243aacaa5bf8c7d753f1`
V3 R1	`b61041a58a7980b946e8fb9e198e3c904d24799ffa36574ea4251c41a566f581`
V3 R2	`84dafa449f98a6987789ba232358072bc0f76dc4524002a5d0918b9a75d2d599`
V4 R1	`64dd54805522c5be8a9db59cea0105ccf0d08786ca79beb8cb79e880a8d7322d`
V4 R2	`feb5ff6820e2ff0d9483e7e0d62c817d846789fb4ae580c878866d959dabd5c0`
V5 R1	`20834b7b72b112147e1b2fb457b84e74d1a30f04f737d4f62a668e9552d2b72f`

Note: These hashes can also be found in the explorers.

Wallet V1

This is the simplest one. It only allows you to send four transactions at a time and doesn’t check anything besides your signature and seqno. Wallet source code:

ton/crypto/smartcont/new-wallet.fif

This version isn’t even used in regular apps because it has some major issues:

No easy way to retrieve the seqno and public key from the contract.
No valid_until check, so you can’t be sure that the transaction won’t be confirmed too late.

The first issue was fixed in V1R2 and V1R3. The R stands for revision. Usually, revisions are just small updates that only add get methods; you can find all of those in the changes history of new-wallet.fif. Hereinafter, we will consider only the latest revisions. Nevertheless, because each subsequent version inherits the functionality of the previous one, we should still stick to it, as this will help us with later versions.

Official code hashes

Contract version	Hash
V1 R1	`a0cfc2c48aee16a271f2cfc0b7382d81756cecb1017d077faaab3bb602f6868c`
V1 R2	`d4902fcc9fad74698fa8e353220a68da0dcf72e32bcb2eb9ee04217c17d3062c`
V1 R3	`587cc789eff1c84f46ec3797e45fc809a14ff5ae24f1e0c7a6a99cc9dc9061ff`

Persistent memory layout

seqno: 32-bit long sequence number.
public-key: 256-bit long public key.

External message body layout

Data:
- signature: 512-bit long Ed25519 signature.
- msg-seqno: 32-bit long sequence number.
- (0-4) mode: up to four 8-bit long integers defining sending mode for each message.
Up to 4 references to cells containing messages.

As you can see, the main functionality of the wallet is to provide a safe way to communicate with TON Blockchain from the outside world. The seqno mechanism protects against replay attacks, and the Ed25519 signature provides authorized access to wallet functionality. The payload data consists of up to 4 references to cells and the corresponding number of modes, which will be directly transferred to the send_raw_message method.

Exit codes

Exit code	Description
33	`seqno` check failed, replay protection occurred
34	`Ed25519 signature` check failed
0	Standard successful execution exit code.

Get methods

int seqno() returns current stored seqno.
int get_public_key() returns current stored public key.

Wallet V2

Wallet source code:

ton/crypto/smartcont/wallet-code.fc

This version introduces the valid_until parameter, which is used to set a time limit for a transaction in case you don’t want it to be confirmed too late. This version also does not have a get method for the public key, which was added in V2R2. All differences compared to the previous version are a consequence of adding the valid_until functionality. A new exit code was added: 35, marking the failure of the valid_until check. Additionally, a new Unix time field has been added to the external message body layout, setting the time limit for the transaction. All get methods remain the same.

Official code hashes

Contract version	Hash
V2 R1	`5c9a5e68c108e18721a07c42f9956bfb39ad77ec6d624b60c576ec88eee65329`
V2 R2	`fe9530d3243853083ef2ef0b4c2908c0abf6fa1c31ea243aacaa5bf8c7d753f1`

External message body layout

Data:
- signature: 512-bit long Ed25519 signature.
- msg-seqno: 32-bit long sequence number.
- valid-until: 32-bit long Unix time integer.
- (0-4) mode: up to four 8-bit integers defining the sending mode for each message.
Up to 4 references to cells containing messages.

Wallet V3

This version introduces the subwallet_id parameter, which allows you to create multiple wallets using the same public key (so you can have only one seed phrase and multiple wallets). As before, V3R2 only adds the get method for the public key. Wallet source code:

ton/crypto/smartcont/wallet3-code.fc

Essentially, subwallet_id is just a number added to the contract state when it’s deployed. Since the contract address in TON is a hash of its state and code, the wallet address will change with a different subwallet_id. This version is the most widely used right now. It covers most use cases and remains clean, simple, and mostly the same as previous versions. All get methods remain the same.

Official code hashes

Contract version	Hash
V3 R1	`b61041a58a7980b946e8fb9e198e3c904d24799ffa36574ea4251c41a566f581`
V3 R2	`84dafa449f98a6987789ba232358072bc0f76dc4524002a5d0918b9a75d2d599`

Persistent memory layout

seqno: 32-bit sequence number.
subwallet_id: 32-bit subwallet ID.
public-key: 256-bit public key.

External message body layout

Data:
- signature: 512-bit Ed25519 signature.
- subwallet_id: 32-bit subwallet ID.
- msg-seqno: 32-bit sequence number.
- valid-until: 32-bit Unix time integer.
- (0-4) mode: up to four 8-bit integers defining the sending mode for each message.
Up to 4 references to cells containing messages.

Exit codes

Exit code	Description
33	`seqno` check failed; replay protection triggered
34	`subwallet_id` does not match the stored one
35	`valid_until` check failed; transaction confirmation attempted too late
35	`Ed25519 signature` check failed
0	Standard successful execution exit code.

Wallet V4

This version retains all the functionality of the previous versions but also introduces something very powerful: plugins. Wallet source code:

ton-blockchain/wallet-contract

This feature allows developers to implement complex logic that works in tandem with a user’s wallet. For example, a DApp may require a user to pay a small amount of coins every day to use certain features. In this case, the user would need to install the plugin on their wallet by signing a transaction. The plugin would then send coins to the destination address daily when requested by an external message.

Official code hashes

Contract version	Hash
V4 R1	`64dd54805522c5be8a9db59cea0105ccf0d08786ca79beb8cb79e880a8d7322d`
V4 R2	`feb5ff6820e2ff0d9483e7e0d62c817d846789fb4ae580c878866d959dabd5c0`

Plugins

Plugins are essentially other smart contracts on TON that developers are free to implement as they wish. In relation to the wallet, they are simply addresses of smart contracts stored in a dictionary in the wallet’s persistent memory. These plugins are allowed to request funds and remove themselves from the “allowed list” by sending internal messages to the wallet.

Persistent memory layout

seqno: 32-bit long sequence number.
subwallet_id: 32-bit long subwallet_id.
public-key: 256-bit long public key.
plugins: dictionary containing plugins (may be empty)

Receiving internal messages

All previous versions of wallets had a straightforward implementation for receiving internal messages. They simply accepted incoming funds from any sender, ignoring the internal message body if present, or in other words, they had an empty recv_internal method. However, as mentioned earlier, the fourth version of the wallet introduces two additional available operations. Let’s take a look at the internal message body layout:

opcode?: 32-bit long operation code. This is an optional field. Any message containing less than 32 bits in the message body, an incorrect opcode, or a sender address that isn’t registered as a plugin will be considered a simple transfer, similar to previous wallet versions.
query-id: 64-bit long integer. This field has no effect on the smart contract’s behavior; it is used to track chains of messages between contracts.

opcode = 0x706c7567, request funds operation code.
- Toncoin: VARUINT16 amount of requested Toncoin.
- extra_currencies: dictionary containing the amount of requested extra currencies (may be empty).
opcode = 0x64737472, request removal of plugin-sender from the “allowed list”.

External message body layout

signature: 512-bit long Ed25519 signature.
subwallet_id: 32-bit long subwallet ID.
valid-until: 32-bit long Unix time integer.
msg-seqno: 32-bit long sequence number.
opcode: 32-bit long operation code.

opcode = 0x0, simple send.
- (0-4) mode: up to four 8-bit integers defining the sending mode for each message.
- (0-4) messages: up to four references to cells containing messages.
opcode = 0x1, deploy and install plugin.
- workchain: 8-bit long integer.
- balance: VARUINT16 Toncoin amount of initial balance.
- state_init: cell reference containing plugin initial state.
- body: cell reference containing body.
opcode = 0x2/0x3, install plugin/remove plugin.
- wc_n_address: 8-bit long compact workchain ID specific to this layout + 256-bit long plugin address.
- balance: VARUINT16 Toncoin amount of initial balance.
- query-id: 64-bit long integer.

As you can see, the fourth version still provides standard functionality through the 0x0 opcode, similar to previous versions. The 0x2 and 0x3 operations allow manipulation of the plugin dictionary. Note that in the case of 0x2, you need to deploy the plugin with that address yourself. In contrast, the 0x1 opcode also handles the deployment process with the state_init field.

Exit codes

Exit code	Description
33	`seqno` check failed, replay protection triggered
34	`subwallet_id` does not match the stored one
35	`Ed25519 signature` check failed
36	`valid_until` check failed, transaction confirmation attempted too late
39	Plugins dictionary manipulation failed (0x1-0x3 recv_external opcodes)
80	Not enough funds for the funds request
0	Standard successful execution exit code.

Get methods

int seqno() returns current stored seqno.
int get_public_key() returns current stored public key.
int get_subwallet_id() returns current subwallet ID.
int is_plugin_installed(int wc, int addr_hash) checks if plugin with defined workchain_id and address hash is installed.
tuple get_plugin_list() returns list of plugins.

Wallet V5

It is the most modern wallet version at the moment, developed by the Tonkeeper team, aimed at replacing V4 and allowing arbitrary extensions.

The V5 wallet standard offers many benefits that improve the experience for both users and merchants. V5 supports gasless transactions, account delegation and recovery, subscription payments using tokens and Toncoin, and low-cost multi-transfers. In addition to retaining the previous functionality (V4), the new contract allows you to send up to 255 messages at a time. Wallet source code:

ton-blockchain/wallet-contract-v5

TL-B scheme:

ton-blockchain/wallet-contract-v5/types.tlb

Official code hash

Contract version	Hash
V5 R1	`20834b7b72b112147e1b2fb457b84e74d1a30f04f737d4f62a668e9552d2b72f`

Persistent memory layout

contract_state$_
    is_signature_allowed:(## 1)
    seqno:#
    wallet_id:(## 32)
    public_key:(## 256)
    extensions_dict:(HashmapE 256 int1) = ContractState;

As you can see, the ContractState, compared to previous versions, hasn’t undergone major changes. The main difference is the new is_signature_allowed 1-bit flag, which restricts or allows access through the signature and stored public key. We will describe the importance of this change in later topics.

Authentication process

signed_request$_             // 32 (opcode from outer)
  wallet_id:    #            // 32
  valid_until:  #            // 32
  msg_seqno:    #            // 32
  inner:        InnerRequest //
  signature:    bits512      // 512
= SignedRequest;             // Total: 688 .. 976 + ^Cell

internal_signed#73696e74 signed:SignedRequest = InternalMsgBody;

internal_extension#6578746e
    query_id:(## 64)
    inner:InnerRequest = InternalMsgBody;

external_signed#7369676e signed:SignedRequest = ExternalMsgBody;

Before we get to the actual payload of our messages — InnerRequest — let’s first look at how version 5 differs from previous versions in the authentication process. The InternalMsgBody combinator describes two ways to access wallet actions through internal messages. The first method is one we are already familiar with from version 4: authentication as a previously registered extension, the address of which is stored in extensions_dict. The second method is authentication through the stored public key and signature, similar to external requests. At first, this might seem like an unnecessary feature, but it actually enables requests to be processed through external services (smart contracts) that are not part of your wallet’s extension infrastructure — a key feature of V5. Gasless transactions rely on this functionality. Note that simply receiving funds is still an option. Practically, any received internal message that doesn’t pass the authentication process will be considered a transfer.

Actions

The first thing that we should notice is InnerRequest, which we have already seen in the authentication process. In contrast to the previous version, both external and internal messages have access to the same functionality, except for changing the signature mode (i.e., the is_signature_allowed flag).

out_list_empty$_ = OutList 0;
out_list$_ {n:#}
    prev:^(OutList n)
    action:OutAction = OutList (n + 1);

action_send_msg#0ec3c86d mode:(## 8) out_msg:^(MessageRelaxed Any) = OutAction;

// Extended actions in V5:
action_list_basic$_ {n:#} actions:^(OutList n) = ActionList n 0;
action_list_extended$_ {m:#} {n:#} action:ExtendedAction prev:^(ActionList n m) = ActionList n (m+1);

action_add_ext#02 addr:MsgAddressInt = ExtendedAction;
action_delete_ext#03 addr:MsgAddressInt = ExtendedAction;
action_set_signature_auth_allowed#04 allowed:(## 1) = ExtendedAction;

actions$_ out_actions:(Maybe OutList) has_other_actions:(## 1) {m:#} {n:#} other_actions:(ActionList n m) = InnerRequest;

We can consider InnerRequest as two lists of actions: the first, OutList, is an optional chain of cell references, each containing a send message request led by the message mode. The second, ActionList, is led by a one-bit flag, has_other_actions, which marks the presence of extended actions, starting from the first cell and continuing as a chain of cell references. We are already familiar with the first two extended actions, action_add_ext and action_delete_ext, followed by the internal address that we want to add or delete from the extensions dictionary. The third, action_set_signature_auth_allowed, restricts or allows authentication through the public key, leaving the only way to interact with the wallet through extensions. This functionality might be extremely important in the case of a lost or compromised private key.

Exit codes

Exit code	Description
132	Authentication attempt through signature while it’s disabled
133	`seqno` check failed, replay protection occurred
134	`wallet_id` does not correspond to the stored one
135	`Ed25519 signature` check failed
136	`valid-until` check failed
137	Enforce that `send_mode` has the +2 bit (ignore errors) set for external messages.
138	`external_signed` prefix doesn’t correspond to the received one
139	Add extension operation was not successful
140	Remove extension operation was not successful
141	Unsupported extended message prefix
142	Tried to disable auth by signature while the extension dictionary is empty
143	Attempt to set signature to an already set state
144	Tried to remove the last extension when signature is disabled
145	Extension has the wrong workchain
146	Tried to change signature mode through external message
147	Invalid `c5`, `action_send_msg` verification failed
0	Standard successful execution exit code.

Get methods

int is_signature_allowed() returns stored is_signature_allowed flag.
int seqno() returns current stored seqno.
int get_wallet_id() returns current wallet ID.
int get_public_key() returns current stored public key.
cell get_extensions() returns extensions dictionary.

Preparing for gasless transactions

Starting with v5, the wallet smart contract supports owner-signed internal messages (internal_signed), which enables gasless transactions—for example, paying network fees in USDt when transferring USDt. The common scheme looks like this:

Flow

When sending USDt, the user signs one message containing two outgoing USDt transfers:
1. USDt transfer to the recipient’s address.
2. Transfer of a small amount of USDt in favor of the service.
This signed message is sent off-chain by HTTPS to the service backend. The service backend sends it to the TON Blockchain, paying Toncoin for network fees.

The beta version of the gasless backend API is available at tonapi.io/api-v2. If you are developing a wallet app and have feedback about these methods, please share it in @tonapitech chat. Wallet source code:

ton-blockchain/wallet-contract-v5

Special wallets

Sometimes the functionality of basic wallets isn’t enough. That’s why there are several types of specialized wallet: high-load, lockup and restricted. Let’s have a look at them.

Highload wallets

When working with many messages in a short period, there is a need for a special wallet called a Highload Wallet. Read the article for more information.

Lockup wallet

If you, for some reason, need to lock coins in a wallet for some time without the possibility to withdraw them before that time passes, have a look at the lockup wallet. It allows you to set the time until which you won’t be able to withdraw anything from the wallet. You can also customize it by setting unlock periods so that you will be able to spend some coins during these set periods. For example: you can create a wallet which will hold 1 million coins with total vesting time of 10 years. Set the cliff duration to one year, so the funds will be locked for the first year after the wallet is created. Then, you can set the unlock period to one month, so 1'000'000 Toncoin / 120 months = ~8333 Toncoin will unlock every month. Wallet source code:

ton-blockchain/lockup-wallet-contract

Restricted wallet

This wallet’s function is to act like a regular wallet, but restrict transfers to only one pre-defined destination address. You can set the destination when you create this wallet and then you’ll only be able to transfer funds from it to that address. But note that you can still transfer funds to validation contracts so you can run a validator with this wallet. Wallet source code:

EmelyanenkoK/nomination-contract/restricted-wallet

Conclusion

As you see, there are many different versions of wallets in TON. For new deployments, prefer V5. Use V3R2 or V4R2 only for legacy compatibility or specific constraints. You can also use one of the special wallets if you want additional functionality like periodic unlocking of funds.

​Common concept

​Basic wallets

​Wallet contract hashes

​Wallet V1

​Official code hashes

​Persistent memory layout

​External message body layout

​Exit codes

​Get methods

​Wallet V2

​Official code hashes

​External message body layout

​Wallet V3

​Official code hashes

​Persistent memory layout

​External message body layout

​Exit codes

​Wallet V4

​Official code hashes

​Plugins

​Persistent memory layout

​Receiving internal messages

​External message body layout

​Exit codes

​Get methods

​Wallet V5

​Official code hash

​Persistent memory layout

​Authentication process

​Actions

​Exit codes

​Get methods

​Preparing for gasless transactions

​Flow

​Special wallets

​Highload wallets

​Lockup wallet

​Restricted wallet

​Conclusion

​See also

Common concept

Basic wallets

Wallet contract hashes

Wallet V1

Official code hashes

Persistent memory layout

External message body layout

Exit codes

Get methods

Wallet V2

Official code hashes

External message body layout

Wallet V3

Official code hashes

Persistent memory layout

External message body layout

Exit codes

Wallet V4

Official code hashes

Plugins

Persistent memory layout

Receiving internal messages

External message body layout

Exit codes

Get methods

Wallet V5

Official code hash

Persistent memory layout

Authentication process

Actions

Exit codes

Get methods

Preparing for gasless transactions

Flow

Special wallets

Highload wallets

Lockup wallet

Restricted wallet

Conclusion

See also