Understanding Smart Contract Address Formats
On the TON blockchain, every actor—including wallets and smart contracts—has a unique address. These addresses are essential for sending and receiving messages and transactions. There are two primary formats for smart contract addresses: Raw Addresses and User-Friendly Addresses.
Components of a TON Address
Each TON address consists of two main parts:
- Workchain ID: A signed 32-bit integer indicating which workchain the contract belongs to (e.g., "-1" for the masterchain, "0" for the basechain).
- Account ID: A unique identifier for the contract, typically 256 bits in length for the masterchain and basechain.
Raw Addresses vs. User-Friendly Addresses
Raw Addresses
Raw addresses contain only the basic elements:
- Workchain ID (e.g., "-1" for the masterchain)
- Account ID: A 256-bit unique identifier
Example: -1:fcb91a3a3816d0f7b8c2c76108b8a9bc5a6b7a55bd79f8ab101c52db29232260
Limitations:
- No built-in error-checking, increasing the risk of lost funds due to copying errors.
- Lack support for additional features like bounceable/non-bounceable options.
User-Friendly Addresses
User-friendly addresses solve these issues by including:
- Flags: Indicate whether the address is bounceable (for contracts) or non-bounceable (for wallets).
- Checksum: A 2-byte error-checking mechanism (CRC16) to detect errors before sending.
- Encoding: Uses base64 or base64url to convert raw addresses into readable, concise formats.
Example:
The same raw address above becomes: kf/8uRo6OBbQ97jCx2EIuKm8Wmt6Vb15+KsQHFLbKSMiYIny (base64)
Advantages:
- Prevents errors and allows funds to be returned if a transaction fails.
- Enhances security and usability.
Address States
Each TON address can be in one of the following states:
| State | Description |
|---|---|
| Nonexist | The address has no data (initial state for all addresses). |
| Uninit | The address holds a balance but lacks smart contract code. |
| Active | The address has enabled smart contract code and balance. |
| Frozen | The address is locked due to storage fees exceeding the balance. |
Converting Between Address Formats
To convert between raw and user-friendly addresses, use:
- TON API or developer tools like ton.org/address.
- These tools ensure correct formatting and seamless transitions.
👉 Learn more about TON address conversion tools
FAQ Section
Q1: What is the difference between bounceable and non-bounceable addresses?
A: Bounceable addresses are for smart contracts and allow failed transactions to return funds. Non-bounceable addresses are for wallets and discard failed transactions.
Q2: How do I check if a TON address is valid?
A: Use checksums in user-friendly addresses or tools like TON API to validate the format.
Q3: Can I change a smart contract's address after deployment?
A: No, the address is permanently tied to the contract's code and initial data.
Q4: What happens if I send funds to a nonexistent TON address?
A: The transaction will fail, and funds will remain in your wallet (if using a bounceable address) or be lost (if non-bounceable).
Best Practices for TON Addresses
- Always use user-friendly addresses for safety and error-checking.
- Verify addresses before sending transactions.
- Understand address states to manage contracts effectively.
👉 Explore advanced TON smart contract documentation