Skip to main content

Smart contract addresses

This document provides a high-level overview of smart contract addresses on TON Blockchain. Every actor, including wallets and smart contracts, is represented by an address, used for all on-chain interactions.

Address components

A TON address is a composite identifier consisting of two main components:

  • Workchain ID: a signed 32-bit integer that identifies a specific Workchain.
    The Masterchain uses -1, and the Basechain uses 0.
  • Account ID: a 256-bit unique identifier for a contract within its Workchain.
    It is derived from a hash of the contract's initial code and state.

For detailed technical specifications, see the Smart contract addresses documentation.

Address formats

TON addresses are represented in two standard formats:

  • Raw format: a direct representation of the workchain_id and account_id (e.g., -1:fcb...260). Intended for system-level use, it does not include user-facing safety features.
  • User-friendly format: a base64-encoded version of the raw address that includes flags and a checksum. Designed for user interfaces, this format enhances security and prevents errors.

These formats are not interchangeable. The user-friendly format includes critical metadata, such as bounceable flags that determine message-handling behavior for uninitialized accounts. A bounceable message sent to an inactive address is returned to the sender. In contrast, a non-bounceable message will be credited to the account.

For a detailed breakdown of address structures, encoding, and flags, refer to the address formats documentation.

Address states

Every address on TON Blockchain exists in one of four states, reflecting its lifecycle and operational status:

  • nonexist: the initial state for all potential addresses. The address has no associated code, data, or balance.
  • uninit: the address has received funds and has a balance but contains no smart contract code or data. It cannot execute logic.
  • active: the address holds a balance, smart contract code, and data. It is fully operational and can process messages.
  • frozen: the contract's storage fees have exceeded its balance, freezing its state. The address cannot execute transactions until it is unfrozen by replenishing its balance and providing its state.

The address state dictates its capabilities and is fundamental to transaction processing. Further details are available in the address states documentation.

See also

Was this article useful?