Internal address formats

According to TEP 0002, there are two internal address formats on TON blockchain:

• raw;
• user-friendly.

Every internal address can be represented in each of these formats. However, these representations are equivalent: they refer to the same address, though they look different.

Raw format

The raw format is the canonical, on-chain representation of the address of a smart contract. It is this format that is used by developers of smart contracts in the manual creation of messages and is inspired by the corresponding TL-B schemes.

Structure

In existing workchains, the raw format consists of two components separated by a colon:

• workchain_id: a signed 8-bit integer identifying the workchain.
  Examples: -1 for the masterchain and 0 for the basechain.
• account_id: a 256-bit identifier that is derived from a smart contract StateInit.

Example: 0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e

Uppercase letters (A–F) may be used in address strings instead of their lowercase counterparts (a-f).

Drawbacks

Raw addresses lack built-in safety features, making them unsuitable for general use:

• No error detection: the format includes no checksum. A single-character mistake can cause irreversible loss of funds.
• No metadata: for instance, each smart contract can be deployed on both Testnet and Mainnet, in which it will have the same address. An attempt to send real funds to the Testnet variant will result in their loss. It is desirable to have a flag in the address that prevents users from making such a mistake.

User-friendly format

The main purpose of the user-friendly format is to help prevent users from accidentally losing their funds due to a small mistake in the raw format, unwise use of the bounce flag, or from having to manually compose a message when they interact with the intended recipient through wallet applications.

The user-friendly address format is a secure, base64-encoded (or base64url-encoded, URL-safe) wrapper around the raw format. It adds metadata flags and a checksum to prevent common errors and provide greater control over message routing.

Structure

A user-friendly address is a 36-byte structure with the following components:

1. Flags (1 byte): metadata that changes the handling of messages in the wallet application.
   • 0x11 requires bounceable messages.
   • 0x51 permits non-bounceable messages.
   • Add 0x80 if the message should not be accepted on mainnet (testnet-only).
2. workchain_id (1 byte): an 8-bit signed integer.
3. account_id (32 bytes): the 256-bit (big-endian) account identifier.
4. Checksum (2 bytes): a CRC16-CCITT checksum of the preceding 34 bytes.

The checksum mechanism in user-friendly addresses is similar to the Luhn algorithm, providing a first-line defense against input errors by validating format integrity upfront.

Flag definitions

The first 8 bits of the user-friendly format encode the handling of messages, as defined in TEP 0002:

There are four variants in total:

• a bounceable address usable on mainnet or testnet;
• a non-bounceable address usable on mainnet or testnet;
• a bounceable address restricted to testnet;
• a non-bounceable address restricted to testnet.

Encoding

The 36-byte structure is encoded into a 48-character non-space string using either standard base64 (i.e., with digits, upper- and lowercase Latin letters, / and +) or URL-safe base64 (with _ and - instead of / and +). Both encodings are valid and must be supported by applications.

Examples:

• Bounceable: EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF
• Non-bounceable: UQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPuwA
• Bounceable-Testnet: kQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPgpP
• Non-bounceable-Testnet: 0QDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPleK

Custom address safety

When developing custom solutions on TON blockchain, it is critical to implement proper address handling logic. First, always verify whether the recipient address is initialized before sending funds to prevent unintended losses.

For user-friendly format selection according to TEP 0002:

• Use non-bounceable addresses for wallet contracts so funds can be credited even if the recipient is uninitialized.
• Use bounceable addresses for contracts with custom logic so funds can be returned if message processing fails.

Drawbacks

• Public key extraction: it is impossible to extract the public key from the address, which is needed for some tasks (for example, to send an encrypted message to this address). Thus, until the smart contract is deployed for this address, there is no way to get the public key on-chain.
• UI: most OS do not allow you to select an address with a double click because of _, -, /, + base64 symbols.

Wallet address handling

TEP 0002 specifies non-bounceable receiving addresses for wallet contracts and bounceable addresses for other smart contracts.

The address's bounceable flag and the recipient's account status determine the message's bounce flag:

Wallet apps should also check the address's length, valid characters, prefix, and checksum. If the address is invalid, an alert should be shown and the sending operation should not be performed. Additionally, mainnet apps should reject addresses marked testnet-only.

Summary

• Raw format is for system-level use and lacks safety features.
• User-friendly format is for application-level use; it includes flags and a checksum.

Next steps

For more technical details, refer to:

• Account status: how addresses evolve (active, frozen, etc.).