Start here
Condensed overview of documentation and TON blockchain
The documentation is organized by layers of detail, with lower-level details appearing later on the sidebar on the left.
| Onboarding | Overview of the basic tools to onboard in TON: from AI and wallets to explorers and analytics. |
| Nodes | Guides for running TON infrastructure: nodes, validators, staking setups, and related tooling. |
| Applications | Tools and guides for building user-facing dApps: SDKs, AppKit, TON Pay, WalletKit, TON Connect, as well as guides on monitoring and handling blockchain transactions for business applications. |
| APIs | Options for reading TON data and interacting with it from the off-chain world. |
| Smart contracts | Working with the most popular standardized contracts and guides on developing new smart contracts. |
| Tolk language | Reference documentation for the official TON smart contract language. |
| TON Virtual Machine | Description of the low-level language that runs smart-contracts, and details of the runtime. |
| Blockchain foundations | Comprehensive description of the blockchain. Includes web version of whitepapers. |
| Legacy languages | Documentation for older TON languages kept for maintaining older contracts and understanding historical tooling. |
| Contributing | Documentation on writing this documentation. |
This is a condensed description of TON. The rest of the documentation may assume that all of this is already known to the reader.
TON overview
TON is a blockchain. It provides a distributed platform for storing data and code, as well as running computations, all the ingredients to host applications. Roughly speaking, it works as if it were a single server executing all the code. The hosted applications are called smart-contracts.
The platform runs on a set of servers, called nodes. Most important type of nodes, validators, are owned by individuals or organizations with a large stake in TON and great interest in keeping the platform safe, fair, and operational. Validators have to reach consensus on the state of the blockchain. Typically, the process takes below a second to reach transaction finality, a time to mint a new block.
Network communication
The nodes that run the blockchain interact via the ADNL protocol. User-facing applications usually use servers that proxy JSON HTTP requests into the ADNL network. The official version of such a proxy server is provided by the liteserver software. There are public instances of liteserver, so developers are not required to host one on their own servers.
Gram and fees
Gram (GRAM) is the TON's primary cryptocurrency. It is used to pay for the execution of smart contracts, the storage of their data, and network traffic. Such payments are called fees.
Mainnet and testnet
There are two instances of TON blockchain: mainnet and testnet.
Mainnet is the "real" network. It's where actual payments in Gram are made. Applications use the mainnet by default.
The other network is testnet, and it is used by TON developers to check that their applications work correctly before deploying them to mainnet. It uses "test coins" that barely have any value.
Usually, when the TON blockchain gets an update, it is first deployed to testnet, and then to mainnet after a brief period of testing, so sometimes they may run different software. Also, their configuration, availability, and throughput might be different.
Workchains and shards
Key term: workchain
A workchain is a TON blockchain with its own rules and account space. The masterchain holds global configuration and system smart contracts, while the basechain host most accounts and user space smart contracts and can be split into shardchains for scalability. In future there might be new workchains with there own set of rules and logic. Practical note: addresses include the workchain ID, and most apps use workchain 0 (basechain).
Each network is split into workchains that can freely interact with each other, but their implementations may differ significantly.
At the moment, there are two workchains: basechain (workchain_id = 0) for regular use, and a very similar masterchain (workchain_id = -1) for TON's internal bookkeeping. The masterchain follows mostly the same rules, except that using it is more expensive to limit the amount of traffic that interferes with TON's internals.
To be freely scalable, each workchain is split into shards. The number of shards is determined dynamically based on the current network load. Internally, every shard is implemented as a separate blockchain. Except for increased latency, the effect on the user-facing code is minimal.
Accounts
It's easiest to visualize the blockchain as a set of accounts. Each account has an address and a status.
Account statuses
Over its lifetime, an account changes its status among four values:
nonexist: There wasn't a single operation with the account, or it was removed. It has neither a balance, nor code.uninit: If some Gram is transferred to an account, it now exists, but there is still no smart contract code on it. It now has a balance.active: After a deploy message (see below) with code and initial data is sent to an account, it becomes active and can process other messages. It now has a balance, code, and internal state.frozen: If an account is overdue on its storage fees, it will be frozen until the fees are paid. If the overdue amount reaches a maximum limit specified by the blockchain, the account goes completely bankrupt, is removed, and ceases to exist.
Smart contracts
The code on an active account is a smart contract. The term contract is often used for an account that holds the code.