[TEP-2] Standardizing TON Blockchain Addresses: An Overview of the TEP-2 Framework

The evolution of blockchain technology necessitates standardized protocols for address representation to ensure seamless interaction and integration across various platforms. This paper examines the TON Enhancement Proposal (TEP-2), titled “TON Addresses,” which establishes a comprehensive framework for the representation of addresses within the TON (The Open Network) blockchain ecosystem. This framework is pivotal for developers, users, and wallet applications, facilitating a more intuitive and error-resistant way to handle blockchain addresses.

Introduction to TON Address Types

TEP-2 delineates several address types within the TON blockchain, including smart-contract addresses, public keys, and ADNL (Abstract Data Network Layer) addresses. Each address type serves distinct purposes, from identifying smart contracts to facilitating secure communications within the TON network.

Smart-Contract Addresses

Smart-contract addresses in TON are bifurcated into workchain IDs and addresses within those workchains, primarily focusing on the masterchain and basic workchain, which utilize 256-bit addresses. TEP-2 specifies two primary representations for these addresses:

  • Raw Format: A straightforward representation featuring the decimal workchain ID followed by a 64-character hexadecimal address.
  • User-Friendly Format: A more accessible version that employs a base64 or base64url encoding, incorporating a tag byte, workchain ID, address bytes, and a checksum for error detection.

Example Representation

Address Type Representation
Raw -1:e56754f83426f69b09267bd876ac97c44821345b7e266bd956a7bfbfb98df35c
User-Friendly (B64) Ef_lZ1T4NCb2mwkme9h2rJfESCE0W34ma9lWp7-_uY3zXDvq (Bounceable)
User-Friendly (B64) Uf_lZ1T4NCb2mwkme9h2rJfESCE0W34ma9lWp7-_uY3zXGYv (Non-Bounceable)

Public Keys and ADNL Addresses

Public keys, specifically the 256-bit Ed25519 keys, and ADNL addresses, which underpin the TON’s network protocol, are also standardized under TEP-2. Similar to smart-contract addresses, these entities are represented in both raw and user-friendly (armored) formats, with the latter incorporating a base64(base64url) encoding for public keys and a base32 encoding for ADNL addresses.

Implications for Wallet Applications

TEP-2’s standardization has direct implications for TON wallet applications, influencing how addresses are displayed and processed for transactions. Key considerations include:

  • Receiving Addresses: Wallets are encouraged to display user-friendly, bounceable forms of addresses to enhance usability.
  • Sending Addresses: Wallets must validate destination addresses for correctness, network compatibility (mainnet vs. testnet), and bounceable/non-bounceable status, ensuring transactions are executed as intended.

Operational Guidelines for Wallets

Operation Guidelines
Address Validation Check for valid length, characters, prefix, and checksum.
Network Compatibility Checks Ensure addresses are compatible with the wallet’s network (mainnet/testnet).
Bounceable Flag Retrieval Determine the bounceable status from the address for message sending.
Transaction Execution Based on the address’s state (initialized/uninitialized) and bounceable status, appropriately set the bounce field of the sending message.

Challenges and Considerations

While TEP-2 significantly enhances the usability and safety of handling TON addresses, it introduces challenges related to user interface design, particularly the selection difficulty caused by base64 symbols. Additionally, the inability to extract public keys directly from addresses poses limitations for certain on-chain operations.


The TEP-2 proposal for TON addresses represents a critical step towards standardizing blockchain address representations, ensuring that users and developers can interact with the TON blockchain more efficiently and securely. By establishing clear guidelines for address formats and their handling by wallet applications, TEP-2 facilitates a more user-friendly and error-resistant blockchain ecosystem. Future enhancements and proposals may further refine these standards to address the evolving needs of the TON community and its technological infrastructure.

1 Like

The TEP-2 proposal is a foundational document that outlines the structure and representation of addresses within the TON network. It sets a clear and standardized framework for the identification of smart contracts, wallets, public keys, and ADNL addresses, crucial for the secure and efficient operation of the network. This proposal is instrumental in ensuring interoperability and user-friendly interactions within the TON ecosystem.

Professional Insight:

The specification distinguishes between smart-contract addresses, public keys, and ADNL addresses, providing a comprehensive approach to addressing within the TON network. The dual representation of addresses — “Raw” and “User-friendly” — caters to both technical operations and end-user convenience. This duality is crucial for encouraging adoption by making blockchain interactions more accessible to a broader audience. The inclusion of a checksum in the “User-friendly” format is a thoughtful addition, enhancing security by reducing the risk of errors in transactions.

Technical Considerations:

  1. Checksum Implementation:

    • The use of CRC16-CCITT for checksum calculation is a well-established method for error detection, which adds a layer of security by verifying the integrity of the address data. However, it’s essential to ensure that wallet and dApp developers correctly implement this checksum to prevent any discrepancies in address validation.
  2. Workchain ID Representation:

    • The inclusion of workchain ID in the address structure supports the multi-workchain architecture of the TON network, allowing for greater scalability and flexibility. However, it also introduces complexity in address management, necessitating clear documentation and tools to assist users and developers in handling addresses across different workchains.
  3. Base64 and Base64url Encoding:

    • The choice of base64 and base64url encoding for the “User-friendly” format ensures compatibility across different platforms and applications. Nevertheless, as highlighted in the drawbacks, the presence of characters that are not uniformly handled by operating systems’ text selection mechanisms (e.g., ‘_’, ‘-’, ‘/’, ‘+’) could impact usability. Addressing this usability concern requires educating users on the correct methods for copying and sharing TON addresses.

Professional Questions:

  1. Public Key Retrieval:

    • Given the drawback mentioned regarding the inability to extract public keys from addresses before smart contract deployment, what are the proposed solutions or workarounds for applications requiring pre-deployment communication with smart contracts?
  2. Address Usability:

    • Considering the usability challenge with “User-friendly” addresses in user interfaces, are there any recommended practices or tools for application developers to improve user experience when interacting with these addresses?
  3. Multi-Workchain Address Handling:

    • How does TEP-2 propose to simplify the user and developer experience in managing and interacting with addresses across multiple workchains, especially for those new to the TON ecosystem?
  4. Future Address Types:

    • With the current specification covering smart contracts, public keys, and ADNL addresses, is there anticipation for introducing new types of addresses or identifiers in the TON network? If so, how will TEP-2 evolve to accommodate these new types?

In summary, TEP-2 lays a solid foundation for addressing within the TON network, balancing technical requirements with usability considerations. Addressing the identified technical considerations and questions will be critical in ensuring the widespread adoption and seamless operation of the TON ecosystem.