Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
This page provides a complete technical specification for Highload Wallet v2, covering storage structure, message formats, replay protection, and limitations.
## What is Highload Wallet v2?
Highload Wallet v2 is a specialized wallet contract designed for services that need to send many transactions in a short time. It uses dictionary-based replay protection to enable parallel transaction submission.
**Key difference from standard wallets:**\
Unlike seqno-based wallets that require sequential transaction processing, Highload v2 stores processed request identifiers in a dictionary, enabling parallel submissions.
**Replaced by:** [Highload Wallet v3](/standard/wallets/highload/v3/specification)
## TL-B schema
[TL-B (Type Language - Binary)](/languages/tl-b/overview) is a domain-specific language designed to describe data structures in TON. The schemas below define the binary layout of the contract's storage and external messages.
### Storage structure
```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
storage$_ subwallet_id:uint32 last_cleaned:uint64 public_key:bits256
queries:(HashmapE 64 Cell) = Storage;
```
### Query ID structure
```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
_ query_id:uint64 = QueryId;
```
### External message structure
```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
_ mode:uint8 message:^Cell = OutListNode;
msg_body$_ signature:bits512 subwallet_id:uint32 query_id:uint64
messages:(HashmapE 16 Cell) = ExternalInMsgBody;
```
## Storage structure
The Highload Wallet v2 contract stores four persistent fields (in this order):
### `subwallet_id` (32 bits)
**Purpose:**\
Allows a single keypair to control multiple wallets with different addresses.
**How it works:**\
The `subwallet_id` is part of the contract's initial state. Changing it produces a different contract address. Each external message must include the correct `subwallet_id`; mismatches result in transaction failure.
***
### `last_cleaned` (64 bits)
**Purpose:**\
Timestamp (in query\_id format) of the oldest query that was kept during the last cleanup.
**How it works:**\
During each transaction, the contract removes queries older than **64 seconds** from the `queries` dictionary. The `last_cleaned` field tracks the last query ID that was removed.
**Cleanup logic:**
```func theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
bound -= (64 << 32); // Clean up records expired more than 64 seconds ago
```
Queries with `query_id < (now() - 64) << 32` are removed from storage.
***
### `public_key` (256 bits)
**Purpose:**\
The Ed25519 public key is used to verify signatures on incoming external messages.
**How it works:**\
When the wallet receives an external message, it verifies that the 512-bit signature was created by the holder of the private key corresponding to this public key.
***
### `queries` (HashmapE 64 Cell)
**Purpose:**\
Stores processed `query_id` values for replay protection.
**Structure:**
* **Key:** 64-bit `query_id`
* **Value:** Cell containing metadata (typically the timestamp when processed)
**How it works:**\
Before processing a message, the contract checks if `query_id` exists in `queries`. If found, the message is rejected (replay attack). If not found, the `query_id` is added to `queries`, and the message is processed.
## External message structure
### Message layout
```text theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
signature:bits512
subwallet_id:uint32
query_id:uint64
messages:(HashmapE 16 Cell)
```
**Key point:**\
Unlike v3, in v2 the signature is in the **same cell** as the message body, not in a separate reference cell.
### `signature` (512 bits)
**Type:**\
Ed25519 signature (512 bits).
**What is signed:**\
The hash of the remaining slice after the signature, containing `subwallet_id`, `query_id`, and `messages`.
**From source code:**
```func theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
throw_unless(35, check_signature(slice_hash(in_msg), signature, public_key));
```
The contract uses `slice_hash()` on the message body after loading the signature.
***
### `subwallet_id` (32 bits)
**Purpose:**\
Identifies which subwallet this message targets.
**Validation:**\
Must match the `subwallet_id` stored in contract storage.
***
### `query_id` (64 bits)
**Purpose:**\
Unique identifier for replay protection and timestamp validation.
**Structure:**\
The 64-bit value is internally interpreted as a timestamped identifier:
* High 32 bits: Unix timestamp (seconds)
* Low 32 bits: counter within that second
**Validation:**\
The contract checks `query_id >= now() << 32`, ensuring the query ID is not from the past (based on the current time shifted left by 32 bits).
**Total unique IDs:**\
Approximately **32,000** unique query IDs (limited by the cleanup mechanism and the bitmap structure).
***
### `messages` (HashmapE 16)
**Purpose:**\
Dictionary of messages to send in this transaction.
**Structure:**
* **Key:** `uint16` (message index, 0 to 65,535)
* **Value:** `mode:uint8` + `^Cell` (reference to internal message)
**How it works:**\
The contract iterates through the dictionary and sends each message with its corresponding [send mode](/foundations/messages/modes):
```func theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
int i = -1;
do {
(i, var cs, var f) = dict.idict_get_next?(16, i);
if (f) {
var mode = cs~load_uint(8);
send_raw_message(cs~load_ref(), mode);
}
} until (~ f);
```
**Max batch size:**\
Up to **255 messages** (limited by action list size, not dictionary structure).
***
## Replay protection mechanism
### Validation sequence
1. **Check query\_id timestamp:** `query_id >= now() << 32` (exit code `35` if too old)
2. **Check replay:** `query_id` must not be in `queries` (exit code `32` if already processed)
3. **Check subwallet:** `subwallet_id == stored_subwallet` (exit code `34` if mismatch)
4. **Verify signature:** Ed25519 signature verification (exit code `35` if invalid)
5. **Mark as processed:** Add `query_id` to `queries`
6. **Send messages:** Iterate through the message dictionary and send each message
7. **Cleanup:** Remove queries older than 64 seconds
***
## Exit codes
| Exit code | Name | Description | How to fix |
| --------- | ------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------- |
| `0` | Success | Message processed successfully | — |
| `32` | Query already executed | The `query_id` was already processed (found in `queries`) | Use a new, unique `query_id` |
| `34` | Subwallet ID mismatch | The `subwallet_id` in the message does not match storage | Verify you are using the correct `subwallet_id` for this wallet |
| `35` | Invalid signature or query\_id | Ed25519 signature verification failed, or `query_id` is too old | Check the private key and ensure `query_id >= now() << 32` |
***
## Limitations and constraints
### Storage size limit
**Limit:**\
The `queries` dictionary cannot exceed **65,535 cells**.
**What happens if exceeded:**\
An exception is thrown during the action phase, and the transaction fails. The failed transaction may be replayed, potentially locking funds.
### Gas limit for cleanup
**Limit:**\
Transaction gas limit is **1,000,000 gas**.
**What happens if exceeded:**\
Cleanup operations that exceed this limit will fail, preventing the contract from processing new transactions.
**Recommended limits:**
* Queries within expiration window: ≤ 1,000
* Queries cleaned per transaction: ≤ 100
### Query ID expiration
**Expiration time:**\
Queries older than **64 seconds** are removed from storage during cleanup.
**Effective limit:**\
With the 64-second expiration window and recommended limit of ≤1,000 queries per window, the effective query ID space is approximately **32,000** unique IDs before cleanup is required.
***
## Get methods
| Method | Returns | Description |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `processed?(query_id)` | `int` | Returns `-1` if processed, `0` if not processed, `1` if unknown (forgotten after cleanup) |
| `get_public_key()` | `int` (256 bits) | Returns the Ed25519 public key |
### `processed?` method details
**Returns:**
* `-1` (true) — the `query_id` was processed and is still stored in `queries`
* `0` (false) — the `query_id` has not been processed yet
* `1` (unknown) — the `query_id` is older than `last_cleaned` and was forgotten during cleanup
***
## Implementation
**Source code:**\
[ton-blockchain/ton (highload-wallet-v2-code.fc)](https://github.com/ton-blockchain/ton/blob/4ebd7412c52248360464c2df5f434c8aaa3edfe1/crypto/smartcont/highload-wallet-v2-code.fc)
**SDK wrappers:**
* **Go:** [`tonutils-go`](https://github.com/xssnick/tonutils-go) — includes Highload v2 wrapper
* **Python:** [`pytoniq`](https://github.com/yungwine/pytoniq) — includes Highload v2 wrapper
For new projects, consider using [Highload Wallet v3](/standard/wallets/highload/v3/specification) instead.
***
## See also
* [Highload Wallet v3 specification](/standard/wallets/highload/v3/specification) — recommended version
* [Version comparison](/standard/wallets/highload/overview#version-comparison) — v1 vs v2 vs v3