Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions foundations/addresses/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ title: "Overview"

import { Aside } from '/snippets/aside.jsx';

TON implements **Actor model**, where all entities, including wallets, are smart contracts. Each actor:
TON implements **Actor model**. In it, every entity (smart contract), including even wallets, is a program which manages its own balance and persistent storage and is identified by its address. Each actor:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Contract doesn't manage its balance in the same way it manages its storage. While it can put arbitrary data into its storage, it cannot put arbitrary value into the balance.

In some sense, balance is managed by the blockchain. The word "manage" is too ambiguous here.


- processes incoming messages;
- updates its internal state;
- generates outgoing messages.
- processes incoming messages, one at a time, and for each:
- updates its internal state, and;
- 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 can be multiple contracts which have the same code, but each program only manages its own storage and balance. To uphold this separation, every actor must have a unique address. This section explains how these addresses are structured and why they are fundamental to the TON architecture.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There can be multiple contracts which have the same code, but each program only manages its own storage and balance. To uphold this separation, every actor must have a unique address. This section explains how these addresses are structured and why they are fundamental to the TON architecture.
There can be multiple contracts which have the same code, but each contract only manages its own storage and balance. To uphold this separation, every actor must have a unique address. This section explains how these addresses are structured and why they are fundamental to the TON architecture.


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**.
Every account in the TON blockchain has an internal address. External addresses are intended to be used by off-chain software.
Expand All @@ -34,7 +34,7 @@ As we can see, there are two constructors:
And four components:

- `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`.
- `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` 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 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).

Expand All @@ -51,19 +51,23 @@ Both use **256-bit addresses** for accounts.

### Account id

In the currently used workchains, an account id is defined as the result of applying a hash function to a [`StateInit`](/foundations/messages/deploy) structure that stores initial code and data of a smart contract.
In the currently used workchains, account id is defined as the hash of contract's initial state ([`StateInit`](/foundations/messages/deploy)) structure which holds its code and data.

```
account_id = hash(initial_code, initial_data)
account_id = StateInit {code: initial_code, data: initial_data}.toCell().hash()
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a page on Tolk. The math/pseudolanguage formula was intentionally there, as it's considerably more concise.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem being, account_id is not hash of exclusively code and data but also those additional parameters (libraries - not sure if contract can be deployed having them immediately - and also non-compared prefix length).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ProgramCrafter fun fact not related to this PR. It can be can be deployed having them immediately. But only to basechain. It is now allowed for the masterchain

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ProgramCrafter but your change also does not mention any libraries

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the overview it's ok to be a bit informal and imprecise and even lie a little bit, as long as there are links to the part of the docs where these simplified explanations refined into rigorous ones: it's a common educational strategy.

```

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.).
An uninitialized contract can only be deployed by providing `StateInit` which matches hash part of its address; so, for each pair (`initial_code`, `initial_data`), there exists a specific set of account ids to which a smart contract with such code and data can be deployed (it isn't only one ID, as [TVM 11](https://github.com/ton-blockchain/ton/blob/master/doc/GlobalVersions.md#version-11) and onwards allows rewriting a short prefix to put contract in another shard).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
An uninitialized contract can only be deployed by providing `StateInit` which matches hash part of its address; so, for each pair (`initial_code`, `initial_data`), there exists a specific set of account ids to which a smart contract with such code and data can be deployed (it isn't only one ID, as [TVM 11](https://github.com/ton-blockchain/ton/blob/master/doc/GlobalVersions.md#version-11) and onwards allows rewriting a short prefix to put contract in another shard).
An uninitialized contract can only be deployed by providing `StateInit` which matches hash part of its address; so, for each pair (`initial_code`, `initial_data`), there exists a specific set of account IDs to which a smart contract with such code and data can be deployed (it isn't only one ID, as [TVM 11](https://github.com/ton-blockchain/ton/blob/master/doc/GlobalVersions.md#version-11) and onwards allows rewriting a short prefix to put contract in another shard).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • The sentence is too long.
  • The description can be simplified by linking relevant docs page, i.e. /foundations/messages/deploy#deploying-to-specific-shard

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also the sentence was incorrect before, because it happened in version 10, and are "not compared", not "rewritten".


<Aside type="tip">
Although the deployed smart contract code and data may change during its lifetime, the address where it's deployed does not change.
</Aside>

Additionally, a 64-bit prefix of an account id is crucial for the sharding process and delivering messages from one shard to another during [Hypercube Routing](/foundations/shards).
<Aside type="tip">
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no need to highlight this text, or break it out of the flow of the article. It should be a regular paragraph of text.

The tip above is there to highlight the fact that hash of code and data might change over time, as it's not obvious.

There are contracts which, as their first action, transform into another contract with specified code and data. They are called "vanity contracts" as they, by expanding set of possible account ids, allow to find a subjectively prettier address for the new contract.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There are contracts which, as their first action, transform into another contract with specified code and data. They are called "vanity contracts" as they, by expanding set of possible account ids, allow to find a subjectively prettier address for the new contract.
There are contracts which, as their first action, transform into another contract with specified code and data. They are called [vanity](/contract-dev/vanity) contracts as they, by expanding set of possible account ids, allow to find a subjectively prettier address for the new contract.

</Aside>

Additionally, a 64-bit prefix of account id is considered in the sharding process and delivering messages from one shard to another during [Hypercube Routing](/foundations/shards).

## External addresses

Expand Down