Accordingly to TEP 0002
there exist 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: refer to exactly one address,
although visually differ greatly from each other.
For a detection how wallets and other applications use these formats, see the adresses workflow page.
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.
In existent workchains, the raw format consists of two components separated by a colon:
workchain_id: a signed 32-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 state_init.
Example:
0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3eUppercase letters (A–F) may be used in address strings instead of their lowercase counterparts (a-f).
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 such a mistake.
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 or unwise use of the bounce flag and from having to manually compose a message when they interact with the
intended recipient through wallet applications (for instance, Tonkeeper).In fact, the user-friendly address format is a secure, base64-encoded (or base64url-encoded) wrapper around the raw format. It adds metadata
flags and a checksum to prevent common errors and provide greater control over message routing.Nota bene: this format can be applied only to addresses that are described according to the addr_std TL-B scheme, see addresses general info subpage.
A user-friendly address is a 36-byte structure with the following components:
Flags (1 byte): metadata that changes the handling of messages in the wallet application. 0x11 for sending bounceable messages, 0x51 for non-bounceable, add the 0x80 summand if that address should not be accepted by software running in Mainnet.
workchain_id (1 byte): an 8-bit signed integer.
account_id (32 bytes): the 256-bit (big-endian) account identifier.
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.
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:
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 forms selection: use bounceable addresses for user smart contracts with custom logic to ensure funds are returned if the contract is invalid, and non-bounceable addresses for wallets to guarantee funds are credited even if the recipient is uninitialized.
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 double click because of _, -, /, + base64 symbols.
