[TEP-131] Enhancing TON Transactions with Referral Codes in Query ID


The proposed TEP introduces a structured approach to utilizing the Query ID field in TON transactions, dividing it into two distinct parts: a referral code and an app-specific data segment. This structure aims to facilitate the implementation of referral and profit-sharing programs, as well as to improve the collection of usage statistics for applications on the TON network.

Motivation Behind the Proposal

The primary motivation for this proposal is to standardize the way applications and services identify themselves when initiating transactions on the TON network. By allocating a portion of the Query ID for referral codes, apps can more easily participate in referral programs, attribute transactions to their origins, and gather valuable data on app usage. Additionally, this approach respects user privacy by allowing applications to opt-out of using referral codes, thereby catering to privacy-preserving applications and their users’ expectations.

Detailed Specification

The Query ID, traditionally a 64-bit field, is proposed to be divided as follows:

Segment Bit Allocation Purpose
Referral Code First 32 bits Identifies the author of the transaction, such as a dApp or wallet, distinguishing the application within the TON network.
App-Specific Data Second 32 bits Reserved for arbitrary use by the application, such as individual query identification in smart contracts, random nonces, or any other application-specific data.

This division allows applications to self-assign unique identifiers, facilitating easier identification and operation within the network’s ecosystem.

Considerations and Drawbacks

One of the main considerations of this proposal is the reduction of the identifier space for both the referral code and the app-specific data to 32 bits each. Applications requiring more extensive identifiers may need to utilize a portion of their allocated referral code space, potentially complicating the unique identification process.

Rationale and Alternatives

The simplicity and straightforwardness of the proposed division make it an attractive option for application developers and service providers on the TON network. It enables easy integration of referral programs and efficient collection of usage statistics without significantly complicating the transaction initiation process. Alternatives might involve more complex encoding schemes or the use of additional metadata fields, potentially increasing the complexity and reducing the accessibility of such features.


By structuring the Query ID to include both a referral code and app-specific data, the TEP aims to standardize application identification in TON transactions, enhancing the network’s functionality for developers and users alike. This proposal strikes a balance between usability, privacy, and the need for detailed transaction attribution, marking a step forward in the evolution of the TON blockchain’s capabilities.

1 Like

Great idea :+1:t2:i beleive rhhis to be a sound implementation to add into ton transactions and refereals :heart: