From 13135b1ed1bc0e31f9a215bec3cea9ccea9d4431 Mon Sep 17 00:00:00 2001 From: Alex Date: Thu, 11 Sep 2025 18:27:30 +0300 Subject: [PATCH 01/15] Initial commit --- resources/images/status-changes-diagram.svg | 1 + ton/states.mdx | 133 +++++++++++++++++++- 2 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 resources/images/status-changes-diagram.svg diff --git a/resources/images/status-changes-diagram.svg b/resources/images/status-changes-diagram.svg new file mode 100644 index 000000000..afeaf9188 --- /dev/null +++ b/resources/images/status-changes-diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/ton/states.mdx b/ton/states.mdx index 2f361f79c..7dce2f717 100644 --- a/ton/states.mdx +++ b/ton/states.mdx @@ -1,5 +1,134 @@ --- -title: "Contract states" +title: "Address statuses" --- -Stub +[//]: # (import ZoomableImage from '@site/src/components/ZoomableImage') + +This article describes the four possible states of a smart contract address on TON Blockchain. +Understanding these states is crucial for accurately predicting transaction outcomes and ensuring the correct deployment. + +## What is the address status? + +The address status is a formal indicator of what actions can occur with an address, what it can store, whether it contains a contract code or not. In other words, it is one of the main factors determining the behavior of a given address during a transaction. The address status at the beginning and end of a transaction is recorded in [the corresponding TL-B block](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L285) in the fields `orig_status` and `end_status`. Thus, it allows developers to always view the current status of an address before sending it a message and restore the history of its status changes. + +## Status variety + +Each address exists in one of the following statuses: + +- **nonexist**: the default status for addresses with no transaction history or that were deleted. Contains no code, data, or balance. All 2256 addresses start in this state. +- **uninit**: holds a balance and metadata, but no code and persistent data. It cannot execute logic but retains funds (and accumulate the storage fee) until the contract code is deployed. +- **active**: contains code, data, and a balance. Fully deployed and operational, capable of processing messages. +- **frozen**: occurs when the storage debt of an active address exceeds 0.1 TON. Only the hashes of the previous code and data cells are preserved. While frozen, the contract cannot execute. To unfreeze, send a message with the valid `state_init` and sufficient funds for storage fees. Recovery is complex; avoid reaching this state. A project to unfreeze addresses is available [here](https://unfreezer.ton.org/). + +### Why exactly these four statuses? +Although the need for the `active` and `nonexist` statuses is obvious, the purpose of the `uninit` and `frozen` statuses is not immediately clear. + +**`nonexist` vs `uninit`**: + +As was mentioned above, each address starts in the `nonexist` status. Beside code and persistent data, in this status an address also has no [metadata](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L258), so it does not accumulate the storage fee. At the same time, the `uninit` status of an address indicates that some actions were performed with it and, possibly, it is prepared for the deployment. So, the `uninit` address always has the [positive balance and some addtional information](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L259-L260) for which it must pay storage fee. + +Sending an internal message with valid `state_init` and proper `value` to `nonexist` address results in its deployment and the status changes to `active`. The key point is that the deployment occurs during the compute phase, which requires a suitable number of nanotons to run. But often you want to be able to deploy an account through an **external message**, to which you can also attach `state_init`, but it is impossible to attach `value`! This is also the purpose for which `uninit` exists. You can initially transfer the balance to the address via an internal message, notifying the rest of the blockchain participants of your intention to deploy an account in the future. And only then, including through an external message, to deploy. + +**`frozen` vs `uninit`**: + +When the active account's storage debt exceeds 0.1 TON, it becomes `frozen` or `uninit`. It is possible to restore the account from these statuses by paying off the debt and attaching `state_init`. If the account code and its persistent data have not changed during the lifetime of the account, then there is no problem restoring it from `uninit`. But what if they have changed? Since the `uninit` status does not allow you to store any information about account's history, its last state will be lost forever. To prevent such situations, the `frozen` status exists. + +The main difference between the `uninit` and `frozen` statuses is that in addition to metadata, the `frozen` address contains hash of the [last account state](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L268). Thus, it becomes possible to restore the last state of an account before it was frozen by sending a `state_nint` to it, whose hash matches the one recorded on the address. + +## Status transitions + +We present here a diagram that describes all potential changes in the account status during the receipt of internal or external messages. + +### Diagram +In the diagram below, there are four nodes representing the four different address statuses. Each arrow and loop corresponds to a change in the address status at the end of a given transaction. The parameters in the blocks above the arrows (and loops) briefly describe what caused the transaction and also contain some fields that affect the change in the address status. + + +![alt text](/resources/images/status-changes-diagram.svg) + + +So, let's look at what changes can occur to a `nonexist` address depending on the messages that come to it. + - **Receiving external messages**: no changes. + - **Receiving internal messages**: + - **With valid `state_init` and sufficient value**: the contract is deployed on its address that becomes `active` before processing the message. + - **Without/with invalid `state_init` or with insufficient value**: if the message is **bounceable**, then it returns to the sender, and the address state isn't changed. Otherwise, with no `value` in the message, the address state isn't changed. Finally, it becomes `uninit` if received a valid `state_init` but insufficient nanotons or if `state_init` is absent or invalid. + +With the diagram **Legend** below, you can inspect all possible changes in the address status when receiving messages with different parameters. + +### Legend + - **type**: message type. + - any; + - internal; + - external; + - **bounce**: `bounce` flag of an internal message. + - any; + - true; + - false; + - **value**: an amount of nanotons in a message. + - any; + - 0; + - \> 0. + - **StateInit**: StateInit structure. + - any; + - none; + - invalid: the address computed from a given `state_init` does not match the recipient address; + - valid: the computed address matches a recipient address; + - valid last state: must be `state_init` of the last successful transaction before the address change to frozen. + - **balance**: The account balance in nanotons after **Storage phase** of the transaction. + - 0; + - \> 0; + - \< 40000; + - \>= 40000; + - (0, 40000). + - **storage_fees_due**: the number of storage fees that were charged but could not be conducted. In the diagram this field indicates `storage_fees_due` after **Storage phase**. + - 0; + - < 0.1; + - < 1; + - \>= 0.1; + - \>= 1. + - **send_dest_if_zero**: is there any out-going message with flag 32 in the action phase? + - any; + - false; + - true; + - invalid: there was no **Action phase**. + - **zero_bal_after_dest_act**: did the account balance become zero when sending some of messages with the flag 32? This field is meaningful only if there's at least one such message during **Action phase**. + - any; + - false; + - true. + - **action_phase_is_successful**: was **Action phase** successful? + - false; + - true. + - **account_state_changed**: has the account's state changed during its lifetime? + - false; + - true. + +### Key points + + We additionally review some important points regarding the statuses except `nonexist`. + +**Sending to `uninit` address**: + - **Messages of any type without `state_init`**: changes to `nonexist` if its balance becomes zero. + - **Messages of any type with valid `state_init`**: changes to `active` if the balance is at least 40000 nanotons. + +**Sending to `frozen` address**: + - **Messages of any type**: Changes to `nonexist` if its `storage_fees_due` exceeds 1 TON and the balance is zero. + - **Internal message with valid `state_init` (non-bounceable)**: changes to `active` if its `storage_fees_due` becomes zero. + - **Internal message with valid `state_init` (bounceable)**: changes to `active` with the same debt and the account balance equals message's balance minus compute and action fees. + +**Sending to `active` address**: + - **Messages of any type**: changes to `frozen` if its `storage_fees_due` exceeds 0.1 TON and the account's state has ever changed. + - **Messages of any type**: changes to `uninit` if its `storage_fees_due` exceeds 0.1 TON and the account's state has never changed. + - **Messages of any type**: if in the action list there is an outgoing message with the flag 32 but the action phase was unsuccessful or the balance after this action is positive, the address state doesn't change. + - **Internal message with any `state_init`**: new `state_init` will be ignored and therefore doesn't change the address state. + +**Deployment strategy**: the standard practice for deploying a wallet is to first send a non-bounceable message with Toncoin to its address. This transitions the address to the `uninit` state. The wallet owner can then deploy the contract in a subsequent transaction, using the pre-funded balance. + +**Protection against errors**: standard wallets and applications manage these complexities by automatically setting the `bounce` flag based on the state of the destination address. Developers of custom applications must implement similar logic to prevent fund loss. + +## Summary + +- The address state (`nonexist`, `uninit`, `active`, `frozen`) defines behavior. +- Correct handling of `state_init` and the `bounce` flag is crucial for successful deployment and avoiding unintended fund transfers. +- There are many cases when the address state can become `nonexist` or `frozen`. Keep track of the amount of TON on the account balance! +- Each new `state_init` is ignored when the address state is active. + + From 977d4d3de026b00735d79195134fbdce9ebdbef7 Mon Sep 17 00:00:00 2001 From: Alex Date: Fri, 12 Sep 2025 13:19:58 +0300 Subject: [PATCH 02/15] Address status -> Account status + some minor fixes --- ton/states.mdx | 52 +++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/ton/states.mdx b/ton/states.mdx index 7dce2f717..c06d0999f 100644 --- a/ton/states.mdx +++ b/ton/states.mdx @@ -1,58 +1,58 @@ --- -title: "Address statuses" +title: "Account statuses" --- [//]: # (import ZoomableImage from '@site/src/components/ZoomableImage') -This article describes the four possible states of a smart contract address on TON Blockchain. +This article describes the four possible states of an account on TON Blockchain. Understanding these states is crucial for accurately predicting transaction outcomes and ensuring the correct deployment. -## What is the address status? +## What is the account status? -The address status is a formal indicator of what actions can occur with an address, what it can store, whether it contains a contract code or not. In other words, it is one of the main factors determining the behavior of a given address during a transaction. The address status at the beginning and end of a transaction is recorded in [the corresponding TL-B block](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L285) in the fields `orig_status` and `end_status`. Thus, it allows developers to always view the current status of an address before sending it a message and restore the history of its status changes. +The account status is a formal indicator of what actions can occur with an account, what it can store, whether it contains a contract code or not. In other words, it is one of the main factors determining the behavior of a given account during a transaction. The account status at the beginning and end of a transaction is recorded in [the corresponding TL-B block](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L285) in the fields `orig_status` and `end_status`. Thus, it allows developers to always view the current status of an account before sending it a message and restore the history of its status changes. ## Status variety -Each address exists in one of the following statuses: +Each account exists in one of the following statuses: -- **nonexist**: the default status for addresses with no transaction history or that were deleted. Contains no code, data, or balance. All 2256 addresses start in this state. +- **nonexist**: the default status for accounts with no transaction history or that were deleted. Contains no code, data, or balance. All 2256 accounts start in this status. - **uninit**: holds a balance and metadata, but no code and persistent data. It cannot execute logic but retains funds (and accumulate the storage fee) until the contract code is deployed. - **active**: contains code, data, and a balance. Fully deployed and operational, capable of processing messages. -- **frozen**: occurs when the storage debt of an active address exceeds 0.1 TON. Only the hashes of the previous code and data cells are preserved. While frozen, the contract cannot execute. To unfreeze, send a message with the valid `state_init` and sufficient funds for storage fees. Recovery is complex; avoid reaching this state. A project to unfreeze addresses is available [here](https://unfreezer.ton.org/). +- **frozen**: occurs when the storage debt of an active account exceeds 0.1 TON. Only the hashes of the previous code and data cells are preserved. While frozen, the contract cannot execute. To unfreeze, send a message with the valid `state_init` and sufficient funds for storage fees. Recovery is complex; avoid reaching this state. A project to unfreeze accounts is available [here](https://unfreezer.ton.org/). ### Why exactly these four statuses? Although the need for the `active` and `nonexist` statuses is obvious, the purpose of the `uninit` and `frozen` statuses is not immediately clear. **`nonexist` vs `uninit`**: -As was mentioned above, each address starts in the `nonexist` status. Beside code and persistent data, in this status an address also has no [metadata](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L258), so it does not accumulate the storage fee. At the same time, the `uninit` status of an address indicates that some actions were performed with it and, possibly, it is prepared for the deployment. So, the `uninit` address always has the [positive balance and some addtional information](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L259-L260) for which it must pay storage fee. +As was mentioned above, each account starts in the `nonexist` status. Beside code and persistent data, in this status an account also has no [metadata](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L258), so it does not accumulate the storage fee. At the same time, the `uninit` status of an account indicates that some actions were performed with it and, possibly, it is prepared for the deployment. So, the `uninit` account always has the [positive balance and some addtional information](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L259-L260) for which it must pay storage fee. -Sending an internal message with valid `state_init` and proper `value` to `nonexist` address results in its deployment and the status changes to `active`. The key point is that the deployment occurs during the compute phase, which requires a suitable number of nanotons to run. But often you want to be able to deploy an account through an **external message**, to which you can also attach `state_init`, but it is impossible to attach `value`! This is also the purpose for which `uninit` exists. You can initially transfer the balance to the address via an internal message, notifying the rest of the blockchain participants of your intention to deploy an account in the future. And only then, including through an external message, to deploy. +Sending an internal message with valid `state_init` and proper `value` to `nonexist` account results in its deployment and the status changes to `active`. The key point is that the deployment occurs during the compute phase, which requires a suitable number of nanotons to run. But often you want to be able to deploy an account through an **external message**, to which you can also attach `state_init`, but it is impossible to attach `value`! This is also the purpose for which `uninit` exists. You can initially transfer the balance to the account via an internal message, notifying the rest of the blockchain participants of your intention to deploy an account in the future. And only then, including through an external message, to deploy. **`frozen` vs `uninit`**: When the active account's storage debt exceeds 0.1 TON, it becomes `frozen` or `uninit`. It is possible to restore the account from these statuses by paying off the debt and attaching `state_init`. If the account code and its persistent data have not changed during the lifetime of the account, then there is no problem restoring it from `uninit`. But what if they have changed? Since the `uninit` status does not allow you to store any information about account's history, its last state will be lost forever. To prevent such situations, the `frozen` status exists. -The main difference between the `uninit` and `frozen` statuses is that in addition to metadata, the `frozen` address contains hash of the [last account state](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L268). Thus, it becomes possible to restore the last state of an account before it was frozen by sending a `state_nint` to it, whose hash matches the one recorded on the address. +The main difference between the `uninit` and `frozen` statuses is that in addition to metadata, the `frozen` account contains hash of the [last account state](https://github.com/ton-blockchain/ton/blob/cac968f77dfa5a14e63db40190bda549f0eaf746/crypto/block/block.tlb#L268). Thus, it becomes possible to restore the last state of an account before it was frozen by sending a `state_nint` to it, whose hash matches the one recorded on the account. ## Status transitions We present here a diagram that describes all potential changes in the account status during the receipt of internal or external messages. ### Diagram -In the diagram below, there are four nodes representing the four different address statuses. Each arrow and loop corresponds to a change in the address status at the end of a given transaction. The parameters in the blocks above the arrows (and loops) briefly describe what caused the transaction and also contain some fields that affect the change in the address status. +In the diagram below, there are four nodes representing the four different account statuses. Each arrow and loop corresponds to a change in the account status at the end of a given transaction. The parameters in the blocks above the arrows (and loops) briefly describe what caused the transaction and also contain some fields that affect the change in the account status. ![alt text](/resources/images/status-changes-diagram.svg) -So, let's look at what changes can occur to a `nonexist` address depending on the messages that come to it. +So, let's look at what changes can occur to a `nonexist` account depending on the messages that come to it. - **Receiving external messages**: no changes. - **Receiving internal messages**: - **With valid `state_init` and sufficient value**: the contract is deployed on its address that becomes `active` before processing the message. - - **Without/with invalid `state_init` or with insufficient value**: if the message is **bounceable**, then it returns to the sender, and the address state isn't changed. Otherwise, with no `value` in the message, the address state isn't changed. Finally, it becomes `uninit` if received a valid `state_init` but insufficient nanotons or if `state_init` is absent or invalid. + - **Without/with invalid `state_init` or with insufficient value**: if the message is **bounceable**, then it returns to the sender, and the account status isn't changed. Otherwise, with no `value` in the message, the account status isn't changed. Finally, it becomes `uninit` if received a valid `state_init` but insufficient nanotons or if `state_init` is absent or invalid. -With the diagram **Legend** below, you can inspect all possible changes in the address status when receiving messages with different parameters. +With the diagram **Legend** below, you can inspect all possible changes in the account status when receiving messages with different parameters. ### Legend - **type**: message type. @@ -72,7 +72,7 @@ With the diagram **Legend** below, you can inspect all possible changes in the a - none; - invalid: the address computed from a given `state_init` does not match the recipient address; - valid: the computed address matches a recipient address; - - valid last state: must be `state_init` of the last successful transaction before the address change to frozen. + - valid last state: must be `state_init` of the last successful transaction before the account change to frozen. - **balance**: The account balance in nanotons after **Storage phase** of the transaction. - 0; - \> 0; @@ -85,7 +85,7 @@ With the diagram **Legend** below, you can inspect all possible changes in the a - < 1; - \>= 0.1; - \>= 1. - - **send_dest_if_zero**: is there any out-going message with flag 32 in the action phase? + - **send_dest_if_zero**: is there any out-going message with flag 32 in **Action phase**? - any; - false; - true; @@ -105,30 +105,30 @@ With the diagram **Legend** below, you can inspect all possible changes in the a We additionally review some important points regarding the statuses except `nonexist`. -**Sending to `uninit` address**: +**Sending to `uninit` account**: - **Messages of any type without `state_init`**: changes to `nonexist` if its balance becomes zero. - **Messages of any type with valid `state_init`**: changes to `active` if the balance is at least 40000 nanotons. -**Sending to `frozen` address**: +**Sending to `frozen` account**: - **Messages of any type**: Changes to `nonexist` if its `storage_fees_due` exceeds 1 TON and the balance is zero. - **Internal message with valid `state_init` (non-bounceable)**: changes to `active` if its `storage_fees_due` becomes zero. - **Internal message with valid `state_init` (bounceable)**: changes to `active` with the same debt and the account balance equals message's balance minus compute and action fees. -**Sending to `active` address**: +**Sending to `active` account**: - **Messages of any type**: changes to `frozen` if its `storage_fees_due` exceeds 0.1 TON and the account's state has ever changed. - **Messages of any type**: changes to `uninit` if its `storage_fees_due` exceeds 0.1 TON and the account's state has never changed. - - **Messages of any type**: if in the action list there is an outgoing message with the flag 32 but the action phase was unsuccessful or the balance after this action is positive, the address state doesn't change. - - **Internal message with any `state_init`**: new `state_init` will be ignored and therefore doesn't change the address state. + - **Messages of any type**: if in the action list there is an outgoing message with the flag 32 but **Action phase** was unsuccessful or the balance after this action is positive, the account status doesn't change. + - **Messages of any type with any `state_init`**: new `state_init` will be ignored and therefore doesn't change the account status. -**Deployment strategy**: the standard practice for deploying a wallet is to first send a non-bounceable message with Toncoin to its address. This transitions the address to the `uninit` state. The wallet owner can then deploy the contract in a subsequent transaction, using the pre-funded balance. +**Deployment strategy**: the standard practice for deploying a wallet is to first send a non-bounceable message with Toncoin to its address. This transitions the account to the `uninit` status. The wallet owner can then deploy the contract in a subsequent transaction, using the pre-funded balance. -**Protection against errors**: standard wallets and applications manage these complexities by automatically setting the `bounce` flag based on the state of the destination address. Developers of custom applications must implement similar logic to prevent fund loss. +**Protection against errors**: standard wallets and applications manage these complexities by automatically setting the `bounce` flag based on the status of the destination account. Developers of custom applications must implement similar logic to prevent fund loss. ## Summary -- The address state (`nonexist`, `uninit`, `active`, `frozen`) defines behavior. +- The account statuses (`nonexist`, `uninit`, `active`, `frozen`) defines behavior. - Correct handling of `state_init` and the `bounce` flag is crucial for successful deployment and avoiding unintended fund transfers. -- There are many cases when the address state can become `nonexist` or `frozen`. Keep track of the amount of TON on the account balance! -- Each new `state_init` is ignored when the address state is active. +- There are many cases when the account status can become `nonexist` or `frozen`. Keep track of the amount of TON on the account balance! +- Each new `state_init` is ignored when the account status is active. From 3837c1f5ed3cd2c9636f819609f4fbd675fc2c25 Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 16 Sep 2025 13:13:38 +0300 Subject: [PATCH 03/15] Tempo --- docs.json | 2 ++ ton/address.mdx | 5 +++- ton/general-info.mdx | 66 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 ton/general-info.mdx diff --git a/docs.json b/docs.json index 131ddbad6..2f3dd13ce 100644 --- a/docs.json +++ b/docs.json @@ -239,6 +239,8 @@ "group": "Foundations", "pages": [ "ton/overview", + "ton/general-info", + "ton/comparison", "ton/address", "ton/states", "ton/transaction", diff --git a/ton/address.mdx b/ton/address.mdx index d144f0f90..09d5fa2d0 100644 --- a/ton/address.mdx +++ b/ton/address.mdx @@ -2,4 +2,7 @@ title: "Address" --- -Stub +- https://docs.ton.org/v3/concepts/dive-into-ton/ton-blockchain/smart-contract-addresses +- https://docs.ton.org/v3/guidelines/dapps/cookbook#working-with-contract-addresses +- https://docs.ton.org/v3/documentation/smart-contracts/addresses/address +- https://docs.ton.org/v3/documentation/smart-contracts/addresses/address-formats \ No newline at end of file diff --git a/ton/general-info.mdx b/ton/general-info.mdx new file mode 100644 index 000000000..f879a4817 --- /dev/null +++ b/ton/general-info.mdx @@ -0,0 +1,66 @@ +--- +title: "General info" +--- + +# Smart contract addresses + +TON implements the actor model, where all entities, including wallets, are smart contracts. Each actor: + +- processes incoming messages; +- updates its internal state; +- generates outgoing messages. + +As a result, every actor must have a unique address to ensure the correct message routing. This section explains how these addresses are structured and why they are fundamental to the TON architecture. + +There are a lot of addresses that are used in TON blockchain. We focus here on the two types that are most important for developers: **internal** and **external** addresses. But we will also mention the other types in passing, without going into details. + +## Internal addresses + +Each smart contract deployed on TON blockchain has this type of address in its `SmartContractInfo`. Let's look at the corresponding TL-Bs: +``` +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; +``` +In general, smart contract addresses on TON consist of two main components: + +- **workchain_id**: the WorkChain ID (signed 32-bit integer). +- **account_id**: the address of the account (64-512 bits, depending on the WorkChain). + +### WorkChain ID + +TON Blockchain supports up to `2^32` unique WorkChains, each with its own rules. The 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`): the central coordinating chain. +- **BaseChain** (`workchain_id = 0`): the default WorkChain for most operations. + +Both use **256-bit addresses** for accounts. + +### Account ID + +All account IDs on TON use 256-bit addresses on the MasterChain and BaseChain (also referred to as the basic WorkChain). + +An account ID (**account_id**) is defined as the result of applying a hash function to a smart contract object. Every smart contract operating on TON Blockchain stores two main components: + +1. _Compiled code_. The contract logic in bytecode. +2. _Initial data_. The contract's values at the moment it is deployed on-chain. + +The contract’s address is derived by calculating the hash of the **(initial code, initial data)** pair: + +**account_id = hash(initial code, initial data)** + +## Summary + +- **Every actor is a smart contract**, each with a unique address for message routing. +- **Address structure**: + - `workchain_id` (32-bit): identifies the WorkChain. + - `account_id` (256-bit): a hash of the contract’s initial code and state. +- **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 (64–512 bits). + +## Next steps +For more technical details, refer to: +- [Address formats](/v3/documentation/smart-contracts/addresses/address-formats): encoding rules and practical examples. +- [Address states](/v3/documentation/smart-contracts/addresses/address-states): how addresses evolve (active, frozen, etc.). From 58a5e1a7134858847e3920256d158ef4873118f9 Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 16 Sep 2025 19:01:39 +0300 Subject: [PATCH 04/15] Initial commit --- docs.json | 11 ++- ton/address.mdx | 8 --- ton/addresses/address-formats.mdx | 5 ++ ton/addresses/addresses-general-info.mdx | 88 ++++++++++++++++++++++++ ton/general-info.mdx | 66 ------------------ ton/{states.mdx => statuses.mdx} | 0 6 files changed, 101 insertions(+), 77 deletions(-) delete mode 100644 ton/address.mdx create mode 100644 ton/addresses/address-formats.mdx create mode 100644 ton/addresses/addresses-general-info.mdx delete mode 100644 ton/general-info.mdx rename ton/{states.mdx => statuses.mdx} (100%) diff --git a/docs.json b/docs.json index 2f3dd13ce..dc9c16a27 100644 --- a/docs.json +++ b/docs.json @@ -239,10 +239,15 @@ "group": "Foundations", "pages": [ "ton/overview", - "ton/general-info", "ton/comparison", - "ton/address", - "ton/states", + { + "group": "Addresses", + "pages": [ + "ton/addresses/addresses-general-info", + "ton/addresses/address-formats" + ] + }, + "ton/statuses", "ton/transaction", "ton/phases-and-fees", "ton/shards", diff --git a/ton/address.mdx b/ton/address.mdx deleted file mode 100644 index 09d5fa2d0..000000000 --- a/ton/address.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Address" ---- - -- https://docs.ton.org/v3/concepts/dive-into-ton/ton-blockchain/smart-contract-addresses -- https://docs.ton.org/v3/guidelines/dapps/cookbook#working-with-contract-addresses -- https://docs.ton.org/v3/documentation/smart-contracts/addresses/address -- https://docs.ton.org/v3/documentation/smart-contracts/addresses/address-formats \ No newline at end of file diff --git a/ton/addresses/address-formats.mdx b/ton/addresses/address-formats.mdx new file mode 100644 index 000000000..40aaf1412 --- /dev/null +++ b/ton/addresses/address-formats.mdx @@ -0,0 +1,5 @@ +--- +title: "Address formats" +--- + +Stub diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx new file mode 100644 index 000000000..d4b2ae13c --- /dev/null +++ b/ton/addresses/addresses-general-info.mdx @@ -0,0 +1,88 @@ +--- +title: "General information" +--- + +TON implements **Actor model**, where all entities, including wallets, are smart contracts. Each actor: + +- processes incoming messages; +- updates its internal state; +- generates outgoing messages. + +As a result, every actor must have a unique address to ensure the correct message routing. This section explains how these addresses are structured and why they are fundamental to the TON architecture. + +There are a few address types that are used in TON blockchain. We focus here on the two that are most important for developers: **internal** and **external**. + +For the so called **Intermediate** and **DNS** addresses see the [Hypercude Routing]() and [DNS: .ton domains](/services/dns) pages respectively. + +## Internal addresses + +Each smart contract deployed on TON blockchain has this type of the address. Let's look at the corresponding TL-B schemes: +``` +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. +``` +As we can see, there are two constructors: +- `addr_std`: standardized addresses with fixed length suitable for SHA256 encryption. Must be used whenever possible. +- `addr_var`: represents addresses in workchains with a _large_ workchain_id, or addresses of length not equal to 256. Currently is not used and intended for future extensions. + +And four components: + +- `workchain_id`: the WorkChain ID (signed 8- or 32-bit integer). +- `address`: the address of the account (64-512 bits, depending on the WorkChain). In order not to confuse this field with a whole address, it is usually called `account_id`. +- `addr_len`: the length of the non-standardized address. +- `anycast`: not currently used in the blockchain and is always replaced with a zero bit. It's designed to implement the shard spliting of global (or large) accounts, which is not implemented at the moment. + +### WorkChain ID + +TON Blockchain supports up to `2^32` unique WorkChains, each with its own rules and even virtual machines. The 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`): the central coordinating chain. +- **BaseChain** (`workchain_id = 0`): the default WorkChain for most operations. + +Both use **256-bit addresses** for accounts. + +### Account ID + +In currently used WorkChains an account ID is defined as the result of applying a hash function to a `state_init` structure that stores initial code and data of a smart contract. +``` +account_id = hash(initial code, initial data) +``` +Thus, account IDs and smart contracts are closely linked. For every possible result of hashing, there is a specific address where a smart contract with that hash must be deployed. + +**Nota bene: although the smart contract code and data may change during its lifetime, its account ID will no longer change.** + +Additionaly, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during **Hypercube Routing**. + +## External addresses + +External addresses are closely related to **external messages**: ones that originates outside the blockchain or is 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` (32-bit): identifies the WorkChain. + - `account_id` (256-bit): 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 (64–512 bits). +- **External addresses**: may be used by external software for its own purposes but are ignored by the TON Blockchain software. + +## Next steps +For more technical details, refer to: +- [Address formats](/ton/addresses/address-formats): encoding rules and practical examples. +- [Account statuses](/ton/statuses): how addresses evolve (active, frozen, etc.). diff --git a/ton/general-info.mdx b/ton/general-info.mdx deleted file mode 100644 index f879a4817..000000000 --- a/ton/general-info.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "General info" ---- - -# Smart contract addresses - -TON implements the actor model, where all entities, including wallets, are smart contracts. Each actor: - -- processes incoming messages; -- updates its internal state; -- generates outgoing messages. - -As a result, every actor must have a unique address to ensure the correct message routing. This section explains how these addresses are structured and why they are fundamental to the TON architecture. - -There are a lot of addresses that are used in TON blockchain. We focus here on the two types that are most important for developers: **internal** and **external** addresses. But we will also mention the other types in passing, without going into details. - -## Internal addresses - -Each smart contract deployed on TON blockchain has this type of address in its `SmartContractInfo`. Let's look at the corresponding TL-Bs: -``` -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; -``` -In general, smart contract addresses on TON consist of two main components: - -- **workchain_id**: the WorkChain ID (signed 32-bit integer). -- **account_id**: the address of the account (64-512 bits, depending on the WorkChain). - -### WorkChain ID - -TON Blockchain supports up to `2^32` unique WorkChains, each with its own rules. The 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`): the central coordinating chain. -- **BaseChain** (`workchain_id = 0`): the default WorkChain for most operations. - -Both use **256-bit addresses** for accounts. - -### Account ID - -All account IDs on TON use 256-bit addresses on the MasterChain and BaseChain (also referred to as the basic WorkChain). - -An account ID (**account_id**) is defined as the result of applying a hash function to a smart contract object. Every smart contract operating on TON Blockchain stores two main components: - -1. _Compiled code_. The contract logic in bytecode. -2. _Initial data_. The contract's values at the moment it is deployed on-chain. - -The contract’s address is derived by calculating the hash of the **(initial code, initial data)** pair: - -**account_id = hash(initial code, initial data)** - -## Summary - -- **Every actor is a smart contract**, each with a unique address for message routing. -- **Address structure**: - - `workchain_id` (32-bit): identifies the WorkChain. - - `account_id` (256-bit): a hash of the contract’s initial code and state. -- **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 (64–512 bits). - -## Next steps -For more technical details, refer to: -- [Address formats](/v3/documentation/smart-contracts/addresses/address-formats): encoding rules and practical examples. -- [Address states](/v3/documentation/smart-contracts/addresses/address-states): how addresses evolve (active, frozen, etc.). diff --git a/ton/states.mdx b/ton/statuses.mdx similarity index 100% rename from ton/states.mdx rename to ton/statuses.mdx From 8326459cccf8a77fdee40f66153e523de1a9801b Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 16 Sep 2025 19:09:32 +0300 Subject: [PATCH 05/15] Update Account statuses page --- ton/statuses.mdx | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/ton/statuses.mdx b/ton/statuses.mdx index c06d0999f..538538619 100644 --- a/ton/statuses.mdx +++ b/ton/statuses.mdx @@ -2,8 +2,6 @@ title: "Account statuses" --- -[//]: # (import ZoomableImage from '@site/src/components/ZoomableImage') - This article describes the four possible states of an account on TON Blockchain. Understanding these states is crucial for accurately predicting transaction outcomes and ensuring the correct deployment. @@ -55,49 +53,49 @@ So, let's look at what changes can occur to a `nonexist` account depending on th With the diagram **Legend** below, you can inspect all possible changes in the account status when receiving messages with different parameters. ### Legend - - **type**: message type. + - `type`: message type. - any; - internal; - external; - - **bounce**: `bounce` flag of an internal message. + - `bounce`: `bounce` flag of an internal message. - any; - true; - false; - - **value**: an amount of nanotons in a message. + - `value`: an amount of nanotons in a message. - any; - 0; - \> 0. - - **StateInit**: StateInit structure. + - `StateInit`: StateInit structure. - any; - none; - invalid: the address computed from a given `state_init` does not match the recipient address; - valid: the computed address matches a recipient address; - valid last state: must be `state_init` of the last successful transaction before the account change to frozen. - - **balance**: The account balance in nanotons after **Storage phase** of the transaction. + - `balance`: The account balance in nanotons after **Storage phase** of the transaction. - 0; - \> 0; - \< 40000; - \>= 40000; - (0, 40000). - - **storage_fees_due**: the number of storage fees that were charged but could not be conducted. In the diagram this field indicates `storage_fees_due` after **Storage phase**. + - `storage_fees_due`: the number of storage fees that were charged but could not be conducted. In the diagram this field indicates `storage_fees_due` after **Storage phase**. - 0; - < 0.1; - < 1; - \>= 0.1; - \>= 1. - - **send_dest_if_zero**: is there any out-going message with flag 32 in **Action phase**? + - `send_dest_if_zero`: is there any out-going message with flag 32 in **Action phase**? - any; - false; - true; - invalid: there was no **Action phase**. - - **zero_bal_after_dest_act**: did the account balance become zero when sending some of messages with the flag 32? This field is meaningful only if there's at least one such message during **Action phase**. + - `zero_bal_after_dest_act`: did the account balance become zero when sending some of messages with the flag 32? This field is meaningful only if there's at least one such message during **Action phase**. - any; - false; - true. - - **action_phase_is_successful**: was **Action phase** successful? + - `action_phase_is_successful`: was **Action phase** successful? - false; - true. - - **account_state_changed**: has the account's state changed during its lifetime? + - `account_state_changed`: has the account's state changed during its lifetime? - false; - true. @@ -129,6 +127,4 @@ With the diagram **Legend** below, you can inspect all possible changes in the a - The account statuses (`nonexist`, `uninit`, `active`, `frozen`) defines behavior. - Correct handling of `state_init` and the `bounce` flag is crucial for successful deployment and avoiding unintended fund transfers. - There are many cases when the account status can become `nonexist` or `frozen`. Keep track of the amount of TON on the account balance! -- Each new `state_init` is ignored when the account status is active. - - +- Each new `state_init` is ignored when the account status is active. \ No newline at end of file From 805f8a6c8c8057f5db1c353f41899b053fb37168 Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 16 Sep 2025 19:13:59 +0300 Subject: [PATCH 06/15] Minor fixes --- .vale/config/vocabularies/Custom/accept.txt | 2 ++ ton/addresses/addresses-general-info.mdx | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.vale/config/vocabularies/Custom/accept.txt b/.vale/config/vocabularies/Custom/accept.txt index 0581720f9..b512d28f4 100644 --- a/.vale/config/vocabularies/Custom/accept.txt +++ b/.vale/config/vocabularies/Custom/accept.txt @@ -99,6 +99,7 @@ api asm asms basechain +bene bitwise blazingly blockchain @@ -180,6 +181,7 @@ nanotoncoins nanotons nft offchain +nota param performant pragma diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index d4b2ae13c..93b0803bf 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -25,14 +25,14 @@ addr_var$11 anycast:(Maybe Anycast) addr_len:(## 9) ``` As we can see, there are two constructors: - `addr_std`: standardized addresses with fixed length suitable for SHA256 encryption. Must be used whenever possible. -- `addr_var`: represents addresses in workchains with a _large_ workchain_id, or addresses of length not equal to 256. Currently is not used and intended for future extensions. +- `addr_var`: represents addresses in workchains with a _large_ `workchain_id`, or addresses of length not equal to 256. Currently is not used and intended for future extensions. And four components: - `workchain_id`: the WorkChain ID (signed 8- or 32-bit integer). - `address`: the address of the account (64-512 bits, depending on the WorkChain). In order not to confuse this field with a whole address, it is usually called `account_id`. - `addr_len`: the length of the non-standardized address. -- `anycast`: not currently used in the blockchain and is always replaced with a zero bit. It's designed to implement the shard spliting of global (or large) accounts, which is not implemented at the moment. +- `anycast`: not currently used in the blockchain and is always replaced with a zero bit. It's designed to implement the shard splitting of global (or large) accounts, which is not implemented at the moment. ### WorkChain ID @@ -54,7 +54,7 @@ Thus, account IDs and smart contracts are closely linked. For every possible res **Nota bene: although the smart contract code and data may change during its lifetime, its account ID will no longer change.** -Additionaly, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during **Hypercube Routing**. +Additionally, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during **Hypercube Routing**. ## External addresses From 2cf367fdefd9d0e6e484e8e3b2e9120ac36f475f Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 16 Sep 2025 19:15:53 +0300 Subject: [PATCH 07/15] And ones more --- .vale/config/vocabularies/Custom/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale/config/vocabularies/Custom/accept.txt b/.vale/config/vocabularies/Custom/accept.txt index b512d28f4..4d34d742a 100644 --- a/.vale/config/vocabularies/Custom/accept.txt +++ b/.vale/config/vocabularies/Custom/accept.txt @@ -182,6 +182,7 @@ nanotons nft offchain nota +nonexist param performant pragma From 3fa7f9d937d657da72ebd2038ccff5f39b3fa908 Mon Sep 17 00:00:00 2001 From: Alex Date: Wed, 17 Sep 2025 15:12:57 +0300 Subject: [PATCH 08/15] Some improvements --- ton/addresses/addresses-general-info.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index 93b0803bf..0f5b91b10 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -10,7 +10,7 @@ TON implements **Actor model**, where all entities, including wallets, are smart As a result, every actor must have a unique address to ensure the correct message routing. This section explains how these addresses are structured and why they are fundamental to the TON architecture. -There are a few address types that are used in TON blockchain. We focus here on the two that are most important for developers: **internal** and **external**. +There are several types of addresses used in the TON blockchain. Here, we will focus on the two most important ones for developers: **internal** and **external**. For the so called **Intermediate** and **DNS** addresses see the [Hypercude Routing]() and [DNS: .ton domains](/services/dns) pages respectively. @@ -24,15 +24,15 @@ addr_var$11 anycast:(Maybe Anycast) addr_len:(## 9) workchain_id:int32 address:(bits addr_len) = MsgAddressInt. ``` As we can see, there are two constructors: -- `addr_std`: standardized addresses with fixed length suitable for SHA256 encryption. Must be used whenever possible. -- `addr_var`: represents addresses in workchains with a _large_ `workchain_id`, or addresses of length not equal to 256. Currently is not used and intended for future extensions. +- `addr_std`: standardized addresses with a fixed length that are suitable for [SHA256 encryption](https://en.wikipedia.org/wiki/SHA-2). Must be used whenever possible. +- `addr_var`: represents addresses in workchains with a _large_ `workchain_id`, or addresses with a length not equal to 256. Currently is not used and intended for future extensions. And four components: - `workchain_id`: the WorkChain ID (signed 8- or 32-bit integer). -- `address`: the address of the account (64-512 bits, depending on the WorkChain). In order not to confuse this field with a whole address, it is usually called `account_id`. -- `addr_len`: the length of the non-standardized address. -- `anycast`: not currently used in the blockchain and is always replaced with a zero bit. It's designed to implement the shard splitting of global (or large) accounts, which is not implemented at the moment. +- `address`: an address of the account (64-512 bits, depending on the WorkChain). In order not to confuse this field with a whole address, it is usually called `account_id`. +- `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's designed to implement [Shard splitting]() of _global_ (or _large_) accounts, which is not implemented at the moment. ### WorkChain ID @@ -54,11 +54,11 @@ Thus, account IDs and smart contracts are closely linked. For every possible res **Nota bene: although the smart contract code and data may change during its lifetime, its account ID will no longer change.** -Additionally, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during **Hypercube Routing**. +Additionally, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during [Hypercube Routing](). ## External addresses -External addresses are closely related to **external messages**: ones that originates outside the blockchain or is intended for actors outside it. These messages enable interaction between smart contracts and the external world. +External addresses are closely related to [External messages](http://localhost:3000/ton/transaction): ones that originates outside the blockchain or is 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. From 01ce711f48b6af77ee150dbfb6798f0d239e1b05 Mon Sep 17 00:00:00 2001 From: Alex Date: Wed, 17 Sep 2025 15:27:03 +0300 Subject: [PATCH 09/15] change name --- ton/addresses/address-formats.mdx | 2 +- ton/addresses/addresses-general-info.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ton/addresses/address-formats.mdx b/ton/addresses/address-formats.mdx index 40aaf1412..e27410a68 100644 --- a/ton/addresses/address-formats.mdx +++ b/ton/addresses/address-formats.mdx @@ -1,5 +1,5 @@ --- -title: "Address formats" +title: "Internal address formats" --- Stub diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index 0f5b91b10..fc924db8f 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -84,5 +84,5 @@ addr_extern$01 len:(## 9) external_address:(bits len) ## Next steps For more technical details, refer to: -- [Address formats](/ton/addresses/address-formats): encoding rules and practical examples. +- [Internal address formats](/ton/addresses/address-formats): encoding rules and practical examples. - [Account statuses](/ton/statuses): how addresses evolve (active, frozen, etc.). From 4e360774695320c7798d4a462b463a252086cad6 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Wed, 17 Sep 2025 16:58:10 +0200 Subject: [PATCH 10/15] Update ton/addresses/addresses-general-info.mdx --- ton/addresses/addresses-general-info.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index fc924db8f..5ce25bd69 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -12,7 +12,7 @@ As a result, every actor must have a unique address to ensure the correct messag There are several types of addresses used in the TON blockchain. Here, we will focus on the two most important ones for developers: **internal** and **external**. -For the so called **Intermediate** and **DNS** addresses see the [Hypercude Routing]() and [DNS: .ton domains](/services/dns) pages respectively. +For the so called **Intermediate** and **DNS** addresses see the [Hypercube Routing](/ton/hypercube-routing) and [DNS: .ton domains](/services/dns) pages respectively. ## Internal addresses From c496f67a0ae67b34993be8d8a8544e3669388e33 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Wed, 17 Sep 2025 16:59:05 +0200 Subject: [PATCH 11/15] Update ton/addresses/addresses-general-info.mdx --- ton/addresses/addresses-general-info.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index 5ce25bd69..ca70fc7a2 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -63,7 +63,7 @@ External addresses are closely related to [External messages](http://localhost:3 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: -``` +```tlb addr_none$00 = MsgAddressExt; addr_extern$01 len:(## 9) external_address:(bits len) = MsgAddressExt. From 71ede19fe03ee914480cc155698ba9fae5d9c2ae Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Wed, 17 Sep 2025 17:01:00 +0200 Subject: [PATCH 12/15] Apply suggestions from code review --- ton/addresses/addresses-general-info.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index ca70fc7a2..1ce252750 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -48,13 +48,13 @@ Both use **256-bit addresses** for accounts. In currently used WorkChains an account ID is defined as the result of applying a hash function to a `state_init` structure that stores initial code and data of a smart contract. ``` -account_id = hash(initial code, initial data) +account_id = hash(initial_code, initial_data) ``` Thus, account IDs and smart contracts are closely linked. For every possible result of hashing, there is a specific address where a smart contract with that hash must be deployed. **Nota bene: although the smart contract code and data may change during its lifetime, its account ID will no longer change.** -Additionally, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during [Hypercube Routing](). +Additionally, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during [Hypercube Routing](/ton/hypercube-routing). ## External addresses From aabbb9001a620f0ec0e1b81ba023a1444944718c Mon Sep 17 00:00:00 2001 From: Alex Date: Wed, 17 Sep 2025 18:58:51 +0300 Subject: [PATCH 13/15] Apply suggestions from Philip --- ton/addresses/addresses-general-info.mdx | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index 1ce252750..b2a0b3ddf 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -29,32 +29,32 @@ As we can see, there are two constructors: And four components: -- `workchain_id`: the WorkChain ID (signed 8- or 32-bit integer). +- `workchain_id`: the WorkChain id (signed 8- or 32-bit integer). - `address`: an address of the account (64-512 bits, depending on the WorkChain). In order not to confuse this field with a whole address, it is usually called `account_id`. - `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's designed to implement [Shard splitting]() of _global_ (or _large_) accounts, which is not implemented at the moment. +- `anycast`: not currently used in the blockchain and is always replaced with a zero bit. It was designed to implement [Shard splitting](https://docs.ton.org/v3/documentation/smart-contracts/shards/shards-intro/) of _global_ (or _large_) accounts, but then was deprecated since [TVM 10](https://github.com/ton-blockchain/ton/blob/master/doc/GlobalVersions.md#anycast-addresses-and-address-rewrite). -### WorkChain ID +### WorkChain id -TON Blockchain supports up to `2^32` unique WorkChains, each with its own rules and even virtual machines. The 32-bit `workchain_id` prefix in smart contract addresses ensures interoperability, allowing contracts to send and receive messages across different WorkChains. +Basicly, a WorkChain is just a blockchain and the TON blockchain is actually a collection of such blockchains. It supports up to `2^32` unique WorkChains, each with its own rules and even virtual machines. The 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`): the central coordinating chain. +- **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 shardchains. - **BaseChain** (`workchain_id = 0`): the default WorkChain for most operations. Both use **256-bit addresses** for accounts. -### Account ID +### Account id -In currently used WorkChains an account ID is defined as the result of applying a hash function to a `state_init` structure that stores initial code and data of a smart contract. +In currently used WorkChains an account id is defined as the result of applying a hash function to a `state_init` structure that stores initial code and data of a smart contract. ``` account_id = hash(initial_code, initial_data) ``` -Thus, account IDs and smart contracts are closely linked. For every possible result of hashing, there is a specific address where a smart contract with that hash must be deployed. +So, for each pair (`initial_code`, `initial_data`), there exists a unique account id to which a smart contract with such code and data can be deployed (this logic may become more complex when [TVM 11](https://github.com/ton-blockchain/ton/blob/master/doc/GlobalVersions.md#version-11) is deployed on the main network.). -**Nota bene: although the smart contract code and data may change during its lifetime, its account ID will no longer change.** +**Nota bene: although the deployed smart contract code and data may change during its lifetime, the address where it's deployed does not change.** -Additionally, a 64-bit prefix of an account ID is crucial for sharding process and delivering messages from one shard to another during [Hypercube Routing](/ton/hypercube-routing). +Additionally, a 64-bit prefix of an account id is crucial for sharding process and delivering messages from one shard to another during [Hypercube Routing](/ton/hypercube-routing). ## External addresses @@ -78,11 +78,11 @@ addr_extern$01 len:(## 9) external_address:(bits len) - **Main internal address fields**: - `workchain_id` (32-bit): identifies the WorkChain. - `account_id` (256-bit): a hash of the contract’s initial code and data. -- **Active WorkChains**: MasterChain and BaseChain, both using 256-bit IDs. +- **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 (64–512 bits). - **External addresses**: may be used by external software for its own purposes but are ignored by the TON Blockchain software. ## Next steps For more technical details, refer to: - [Internal address formats](/ton/addresses/address-formats): encoding rules and practical examples. -- [Account statuses](/ton/statuses): how addresses evolve (active, frozen, etc.). +- [Account statuses](/ton/statuses): how addresses evolve (active, frozen, etc.). \ No newline at end of file From a0fc03cc0a264e64e0959f8c223a2e6b3f12d41a Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Wed, 17 Sep 2025 18:35:38 +0200 Subject: [PATCH 14/15] Update ton/addresses/addresses-general-info.mdx --- ton/addresses/addresses-general-info.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index b2a0b3ddf..416e8957c 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -36,7 +36,7 @@ And four components: ### WorkChain id -Basicly, a WorkChain is just a blockchain and the TON blockchain is actually a collection of such blockchains. It supports up to `2^32` unique WorkChains, each with its own rules and even virtual machines. The 32-bit `workchain_id` prefix in smart contract addresses ensures interoperability, allowing contracts to send and receive messages across different WorkChains. +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 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 shardchains. From ead6078f996a82936c6bf49112aa7ffbfa849fc9 Mon Sep 17 00:00:00 2001 From: Karkarmath <99297870+Karkarmath@users.noreply.github.com> Date: Wed, 17 Sep 2025 20:15:20 +0300 Subject: [PATCH 15/15] Update ton/addresses/addresses-general-info.mdx Co-authored-by: Novus Nota <68142933+novusnota@users.noreply.github.com> --- ton/addresses/addresses-general-info.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/addresses/addresses-general-info.mdx b/ton/addresses/addresses-general-info.mdx index 416e8957c..5f0b2f930 100644 --- a/ton/addresses/addresses-general-info.mdx +++ b/ton/addresses/addresses-general-info.mdx @@ -39,7 +39,7 @@ And four components: 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 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 shardchains. +- **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.