Highload wallets

Highload Wallets are specialized wallet contracts for services that submit many outgoing transfers, such as exchanges and payment processors. They do not guarantee a transactions-per-second rate; actual throughput depends on network load, message size, fees, and account execution.

What makes them different

Unlike seqno-based wallets, Highload Wallet v2 and v3 store processed request identifiers in dictionaries. Clients can submit requests with distinct IDs concurrently. TON still processes transactions for one account sequentially.

seqno (sequence number) is stored in standard wallets for replay protection. A signed request must include the next seqno — the wallet advances it when the request commits.

Standard wallet coordination:
Clients must coordinate the current seqno and submit requests in an order the wallet can accept. A mismatched value fails. A future-seqno request can be retried after earlier requests advance the wallet, while it remains valid. A stale request must be signed again with the current value.

Highload Wallet submission:
Clients can submit multiple requests without waiting for a new seqno, using a distinct query_id for each. Reserve IDs atomically to prevent duplicates. The account still processes each transaction one at a time.

Version history

Highload Wallet v1

The first highload wallet, Highload Wallet v1, used a simple seqno counter:

Simple seqno-based: Sequential processing like standard wallets
Batch support: Could send up to 254 messages per transaction
Replay marker rollback: A non-skipped action-phase failure can roll back the seqno update (replay behavior).

Legacy contracts

Highload Wallet v1 and v2 are deprecated. Use Highload Wallet v3 for all new deployments.

Highload Wallet v2

Highload Wallet v2 introduced dictionary-based replay protection:

Fund locking risk: If old_queries grows beyond storage limits or the contract exceeds the gas limit during cleanups, the wallet can become unable to process new requests.
High cleanup gas: Storage updates and cleanup operations can consume substantial gas.
Replay marker rollback: A non-skipped action-phase failure can roll back the query marker (replay behavior).

Legacy contracts

Highload Wallet v1 and v2 are deprecated. Use Highload Wallet v3 for all new deployments.

Highload Wallet v3

Highload Wallet v3 is the recommended version for new deployments.

Query ID space: Up to 8,380,416 unique IDs, with rotation between two dictionaries.
Cleanup: The design rotates query dictionaries to limit storage growth. Unlike previous highload wallet versions, clean up does not have a fund-locking risk.
Batch replay protection: Unlike previous highload wallet versions and standard wallets V1 to V4, a later failure in the internal batch transaction cannot roll back its query marker after a successful first transaction. The query_id is always committed before attempting to send messages. However, direct single-message requests use one transaction.

Highload Wallet version comparison

	v1	v2	v3
Risk of message replays (`query_id`)	⚠️ Present	⚠️ Present	✅ Absent: batch transactions commit `query_id`, single-message sends use one transaction
Fund locking risk (`old_queries`)	✅ Absent	⚠️ Present	✅ Absent
Gas efficiency	Not optimized	⚠️ High cleanup costs	✅ Optimized
Max messages per batch	254 per request	254 per request	254 per internal action list
Replay protection	Simple `seqno`	Query ID dictionary	Dual dictionary + timestamp
Transaction pattern	Single transaction	Single transaction	Two-transaction pattern for batches; single for direct message sends
Query ID space	Sequential `seqno`	~32,000 unique IDs	8,380,416 unique IDs
Parallel submissions	❌ Sequential only	✅ Supported	✅ Supported
Status	⚠️ Deprecated	⚠️ Deprecated	✅ Recommended

Replay protection rollback

In standard wallets V1-V4, a non-skipped action-phase failure can roll back the seqno replay marker. Highload Wallet v1 and v2 can likewise roll back their seqno or query-ID marker. The +2 send mode skips eligible errors. Without a committed replay marker, resubmitting a failed request can repeat the same work while it remains valid.

Highload v3 batch behavior: The external transaction records the query_id and queues an internal message to itself. Once that first transaction succeeds, a failure in the later internal batch transaction cannot undo its marker. Direct single-message requests use one transaction, so they do not get this separation. The COMMIT instruction is not a blanket guarantee against every non-skipped action-phase failure.