Addresses overview

TON implements an actor model, where entities, including wallets, are smart contracts that exchange messages. Each smart contract is hosted on a distinct account that manages its balance and persistent storage. These accounts have identifiable addresses, used for sending and receiving messages on the blockchain.

Each actor (account) processes incoming messages on its address one at a time, updating its internal state and generating outgoing messages. While multiple accounts can share the same code, each maintains its own storage and balance. To uphold this separation, each account address is unique.

On the TON blockchain, there are several types of addresses. The two most relevant ones for developers are internal and external. Every account has an internal address, while external addresses are intended for use by off-chain software.

Internal addresses

Each smart contract deployed on TON has an internal address. The corresponding TL-B schemes are:

addr_std$10 anycast:(Maybe Anycast)
   workchain_id:int8 address:bits256 = MsgAddressInt;
addr_var$11 anycast:(Maybe Anycast) addr_len:(## 9)
   workchain_id:int32 address:(bits addr_len) = MsgAddressInt.

There are two constructors:

• addr_std: standardized addresses with a fixed length that are suitable for SHA256 encryption. Must be used whenever possible.
• addr_var: represents addresses in workchains with a large 32-bit workchain_id, or addresses with a length not equal to 256. Currently, it is not used and is intended for future extensions.

And four components:

• workchain_id: the workchain ID — a signed 8-bit integer in case of addr_std and a 32-bit integer in case of addr_var.
• address: an address of the account — from 64 to 512 bits, depending on the workchain. To avoid confusion with a full address, this field is usually called account_id or a hash part of address.
• addr_len: a length of the non-standardized address.
• anycast: not currently used in the blockchain and is always replaced with a zero bit. It was designed to implement shard splitting for global (or large) accounts, but was later deprecated in TVM 10.

Workchain ID

TON Blockchain is actually a collection of blockchains, with workchain being one of them. TON supports up to 2^32 unique workchains, each with its own rules and even virtual machines. The 8- or 32-bit workchain_id prefix in smart contract addresses ensures interoperability, allowing contracts to send and receive messages across different workchains.

Currently, two workchains are active:

• masterchain (workchain_id = -1): contains general information about the TON blockchain protocol and the current values of its parameters, the set of validators and their stakes, the set of currently active workchains and their shards, and, most importantly, the set of hashes of the most recent blocks of all workchains and shard chains.
• basechain (workchain_id = 0): the default workchain for most operations.

Both use 256-bit addresses for accounts.

Account ID

In the currently used workchains, the account ID is defined as the hash of the contract's initial state (StateInit) structure, which holds its code and data:

account_id = hash(initial_code, initial_data)

Uninitialized account can only become active by providing a StateInit that matches its account ID (hash) in the incoming message. If the fixed_prefix_length is set, the first respective bits of the destination account ID are not compared with the StateInit hash — only the remaining bits must match. That short prefix is used to deploy a contract in the specific shard.

As such, for each pair of initial_code and initial_data, there exists a specific set of account IDs to which a smart contract with such code and data can be deployed. Account IDs are crucial for sharding and for delivering messages between shards during Hypercube Routing.

Some contracts can transform into another contract with specified code and data as their first action. They are called vanity contracts because they allow for a wider range of account IDs, helping to find a subjectively prettier address for the new contract. Their off-chain generation parts try different StateInit values, often by changing a salt, until the resulting account ID has a desired prefix or suffix. After deployment, the contract can set its runtime code and data to the intended contract state, retaining the address obtained with the initial StateInit.

External addresses

External addresses are closely related to External messages: ones that originate outside the blockchain or are intended for actors outside it. These messages enable interaction between smart contracts and the external world.

Actually, external addresses are ignored by the TON Blockchain software altogether, but may be used by external software for its own purposes.

The corresponding TL-B schemes are as follows:

addr_none$00 = MsgAddressExt;
addr_extern$01 len:(## 9) external_address:(bits len)
             = MsgAddressExt.

• addr_none: it is used as a stub for the source or destination field in incoming and outgoing external messages when there is no need to put any explanatory information for off-chain actors. It is also used as a stub for the source address of internal messages, since this field is always overwritten to the correct one by the validators.
• addr_extern: contains up to nine bits of additional information. For example, a special external service may inspect the destination address of all outbound external messages found in all blocks of the blockchain, and, if a special magic number is present in the external_address field, parse the remainder as an IP address and UDP port or a (TON Network) ADNL address, and send a datagram with a copy of the message to the network address thus obtained.

Summary

• Every actor is a smart contract, each with a unique address for message routing.
• Main internal address fields:
  • workchain_id (8- or 32-bit): identifies the workchain.
  • account_id (256-bit in active workchains): a hash of the contract's initial code and data.
• Active workchains: masterchain and basechain, both using 256-bit IDs.
• Flexibility: TON supports up to 2^32 workchains, allowing future chains to customize address lengths from 64 to 512 bits.
• External addresses: may be used by external software but are ignored on-chain.

Next steps

For more technical details, refer to:

• Internal address formats: encoding rules and practical examples.
• Account status: how addresses evolve (active, frozen, etc.).