Skip to content

Commit 2c9f88a

Browse files
committed
feat: improve concepts
1 parent 293c204 commit 2c9f88a

File tree

13 files changed

+154
-87
lines changed

13 files changed

+154
-87
lines changed

docs/develop/network/overlay.md

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Overlay subnetworks
22

3+
Implementation:
4+
* https://github.com/ton-blockchain/ton/tree/master/overlay
5+
6+
## Overview
7+
38
The architecture of TON is built in such a way that a lot of chains can exist simultaneously and independently in it - they can be both private or public.
49
Nodes have the ability to choose which shards and chains they store and process.
510
At the same time, the communication protocol remains unchanged due to its universality. Protocols such as DHT, RLDP and Overlays allow this to be achieved.
@@ -11,6 +16,21 @@ All chains in TON, including the masterchain, communicate using their own overla
1116
To join it, you need to find the nodes that are already in it, and start exchanging data with them.
1217
For the public overlays you can find nodes using DHT.
1318

19+
## ADNL vs Overlay networks
20+
21+
In contrast to ADNL, the TON overlay networks usually do not support
22+
sending datagrams to other arbitrary nodes. Instead, some “semi-permanent
23+
links” are established between certain nodes (called “neighbors” with respect to
24+
the overlay network under consideration) and messages are usually forwarded
25+
along these links (i.e. from a node to one of its neighbors).
26+
27+
Each overlay subnetwork has a 256-bit network identifier usually equal
28+
to a SHA256 of the description of the overlay network—a TL-serialized object.
29+
30+
Overlay subnetworks can be public or private.
31+
32+
Overlay subnetworks work according to a special [gossip](https://en.wikipedia.org/wiki/Gossip_protocol) protocol.
33+
1434
## Interaction with overlay nodes
1535

1636
We have already analyzed an example with finding overlay nodes in an article about DHT,
@@ -70,4 +90,4 @@ Thus, we can receive information directly from the nodes.
7090

7191
## References
7292

73-
_Here a [link to the original article](https://github.com/xssnick/ton-deep-doc/blob/master/Overlay-Network.md) by [Oleg Baranov](https://github.com/xssnick)._
93+
_Here a [link to the original article](https://github.com/xssnick/ton-deep-doc/blob/master/Overlay-Network.md) by [Oleg Baranov](https://github.com/xssnick)._

docs/develop/network/rldp.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# RLDP
22

3+
Implementation:
4+
* https://github.com/ton-blockchain/ton/tree/master/rldp
5+
* https://github.com/ton-blockchain/ton/tree/master/rldp2
6+
* https://github.com/ton-blockchain/ton/tree/master/rldp-http-proxy
7+
8+
## Overview
9+
310
RLDP - Reliable Large Datagram Protocol - is a protocol that runs on top of ADNL UDP, which is used to transfer large data blocks and
411
includes Forward Error Correction (FEC) algorithms as a replacement of acknowledgment packets on the other side.
512
This makes it possible to transfer data between network components more efficiently, but with more traffic consumption.
@@ -179,4 +186,4 @@ If `last` = true, then we have reached the end, we can put all the pieces togeth
179186

180187
## References
181188

182-
_Here a [link to the original article](https://github.com/xssnick/ton-deep-doc/blob/master/RLDP.md) by [Oleg Baranov](https://github.com/xssnick)._
189+
_Here a [link to the original article](https://github.com/xssnick/ton-deep-doc/blob/master/RLDP.md) by [Oleg Baranov](https://github.com/xssnick)._

docs/learn/networking/overlay-subnetworks.md

Lines changed: 0 additions & 33 deletions
This file was deleted.

docs/learn/networking/overview.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,9 @@ The TON Project uses its own peer-to-peer network protocols.
1919
blockchain itself, thus providing more possibilities and flexibility for creating
2020
new services in the TON Ecosystem.
2121

22+
## See Also
23+
24+
* [ADNL Protocol](/learn/networking/adnl)
25+
* [Overlay Subnetworks](/learn/networking/overlay-subnetworks)
26+
* [RLDP Protocol](/learn/networking/rldp)
27+
* [TON DHT Service](/learn/networking/ton-dht)

docs/learn/networking/rldp.md

Lines changed: 0 additions & 17 deletions
This file was deleted.

docs/learn/overviews/addresses.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Smart Contract Addresses
1+
# Smart Contract Addresses Documentation
22

33
This section will describe the specifics of smart contract addresses on TON Blockchain. It will also explain how actors are synonymous with smart contracts on TON.
44

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Overview: Sharding and Split Merge in the TON Blockchain
2+
3+
[//]: # (TODO, this is from gpt)
4+
5+
The TON Blockchain employs advanced sharding mechanisms to enhance scalability and performance, allowing it to efficiently process a massive number of transactions.
6+
The core concept is splitting the blockchain into smaller, independent pieces called **shards**. These shards can handle transactions in parallel, ensuring high throughput even as the network grows.
7+
8+
In TON, sharding is highly dynamic. Unlike other blockchains, which have a fixed number of shards, TON can create new shards on demand.
9+
As the transaction load increases, shards split, and as the load decreases, they merge.
10+
This flexibility ensures that the system can adapt to varying workloads while maintaining efficiency.
11+
12+
The **Masterchain** plays a crucial role, maintaining the network configuration and the final state of all **workchains** and **shardchains**.
13+
While the masterchain is responsible for overall coordination, **workchains** operate under their specific rules, each of which can be split further into shardchains.
14+
Currently, only one workchain (the **Basechain**) operates on TON.
15+
16+
At the heart of TON's efficiency is the **Infinity Sharding Paradigm**, which treats each account as part of its own "accountchain."
17+
These accountchains are then aggregated into shardchain blocks, facilitating efficient transaction processing.
18+
19+
In addition to the dynamic creation of shards, TON uses **Split Merge** functionality, which allows the network to efficiently respond to changing transaction loads. This system enhances scalability and interaction within the blockchain network, exemplifying TON's approach to resolving common blockchain challenges with a focus on efficiency and global consistency.
20+
21+
22+
## See Also
23+
24+
* [Shards Dive In](/develop/blockchain/shards)
25+
* [# Infinity Sharding Paradigm](/develop/blockchain/sharding-lifecycle)
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Smart Contract Addresses
2+
3+
[//]: # (TODO, this is gpt)
4+
5+
On the TON Blockchain, every actor, including wallets and smart contracts, is represented by an address. These addresses are critical for receiving and sending messages and transactions. There are two main formats for smart contract addresses: **raw addresses** and **user-friendly addresses**.
6+
7+
## Address Components
8+
9+
Each address on TON consists of two main components:
10+
- **Workchain ID**: A signed 32-bit integer that denotes which workchain the contract belongs to (e.g., `-1` for the Masterchain and `0` for the Basechain).
11+
- **Account ID**: A unique identifier for the contract, generally 256 bits in length for the Masterchain and Basechain.
12+
13+
## Raw vs. User-Friendly Addresses
14+
15+
### Raw Address
16+
A **raw address** contains only the basic elements:
17+
- **Workchain ID** (e.g., `-1` for Masterchain)
18+
- **Account ID**: A 256-bit unique identifier
19+
20+
Example:
21+
`-1:fcb91a3a3816d0f7b8c2c76108b8a9bc5a6b7a55bd79f8ab101c52db29232260`
22+
23+
However, raw addresses have two main issues:
24+
1. They lack built-in error checking, meaning a mistake in copying can lead to loss of funds.
25+
2. They do not support additional features like bounceable/non-bounceable flags.
26+
27+
### User-Friendly Address
28+
29+
A **user-friendly address** solves these problems by incorporating:
30+
1. **Flags**: Indicates if the address is bounceable (for contracts) or non-bounceable (for wallets).
31+
2. **Checksum**: A 2-byte error-checking mechanism (CRC16) that helps detect errors before sending.
32+
3. **Encoding**: Transforms the raw address into a readable, compact form using base64 or base64url.
33+
34+
For example, the same raw address can be converted into a user-friendly address like:
35+
`kf/8uRo6OBbQ97jCx2EIuKm8Wmt6Vb15+KsQHFLbKSMiYIny` (base64)
36+
37+
User-friendly addresses make transactions safer by preventing errors and allowing the return of funds in case of failed transactions.
38+
39+
## Address States
40+
41+
Each address on TON can be in one of the following states:
42+
- **Nonexist**: The address has no data (initial state for all addresses).
43+
- **Uninit**: The address has a balance but no smart contract code.
44+
- **Active**: The address is live with smart contract code and balance.
45+
- **Frozen**: The address is locked due to storage costs exceeding its balance.
46+
47+
## Converting Between Address Formats
48+
49+
To convert between raw and user-friendly addresses, you can use TON APIs or developer tools like [ton.org/address](https://ton.org/address). These utilities allow seamless conversion and ensure proper formatting before sending transactions.
50+
51+
For more details on how to handle these addresses, including encoding examples and transaction security, you can refer to the full guide in [Addresses Documentation](/learn/overviews/addresses).
52+
53+
## See Also
54+
55+
* [Smart Contracts Addresses Documentation](/learn/overviews/addresses)

navbar.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ module.exports = {
2222
label: 'Blockchain of Blockchains',
2323
},
2424
{
25-
to: '/learn/overviews/addresses',
25+
to: '/v3/concepts/ton-blockchain/smart-contract-addresses',
2626
label: 'Smart Contract Addresses',
2727
},
2828
{

sidebars/develop.js

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ module.exports = [
1313
'value': '<span class=\'menu__link\'><b><small> Smart Contracts Documentation </small></b></span>',
1414
},
1515
'develop/smart-contracts/README',
16+
'learn/overviews/addresses',
17+
'develop/blockchain/shards',
18+
'develop/blockchain/sharding-lifecycle',
1619
{
1720
type: 'category',
1821
label: 'Getting Started',
@@ -147,7 +150,6 @@ module.exports = [
147150
label: 'Oracles',
148151
items: [
149152
'develop/oracles/about_blockchain_oracles',
150-
151153
{
152154
type: 'category',
153155
label: 'Oracles in TON',
@@ -157,6 +159,11 @@ module.exports = [
157159
},
158160
],
159161
},
162+
{
163+
type: 'link',
164+
label: 'Open-Source and Decentralization in TON',
165+
href: 'https://defi.org/ton/',
166+
},
160167
{
161168
'type': 'html',
162169
'value': '<hr/>',
@@ -232,10 +239,32 @@ module.exports = [
232239
type: 'category',
233240
label: 'Network Protocols',
234241
items: [
235-
'learn/networking/low-level-adnl', // TODO: MERGE ADNL
236-
'develop/network/adnl-tcp',
237-
'develop/network/adnl-udp',
238-
'develop/network/dht',
242+
{
243+
type: 'category',
244+
label: 'ADNL',
245+
items: [
246+
{
247+
type: 'doc',
248+
label: 'Overview',
249+
id: 'learn/networking/adnl',
250+
},
251+
'learn/networking/low-level-adnl', // TODO: MERGE ADNL
252+
'develop/network/adnl-tcp',
253+
'develop/network/adnl-udp',
254+
],
255+
},
256+
{
257+
type: 'category',
258+
label: 'DHT',
259+
items: [
260+
{
261+
type: 'doc',
262+
label: 'Overview',
263+
id: 'learn/networking/ton-dht',
264+
},
265+
'develop/network/dht',
266+
]
267+
},
239268
'develop/network/rldp',
240269
'develop/network/overlay',
241270
],

sidebars/guidelines.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,7 @@ module.exports = [
224224
},
225225
{
226226
'type': 'html',
227-
'value': '<span class=\'menu__link\'><b><small> TON Integration Guidelines </small></b></span>',
227+
'value': '<span class=\'menu__link\'><b><small> Integrate TON </small></b></span>',
228228
},
229229
'develop/dapps/ton-connect/overview',
230230
{

sidebars/learn.js

Lines changed: 2 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -18,36 +18,11 @@ module.exports = [
1818
label: 'TON Blockchain',
1919
items: [
2020
'learn/overviews/ton-blockchain',
21-
'learn/overviews/addresses',
21+
'v3/concepts/ton-blockchain/smart-contract-addresses',
2222
'learn/overviews/cells',
23-
{
24-
type: 'category',
25-
label: 'TON Networking',
26-
items: [
27-
{
28-
type: 'doc',
29-
label: 'Overview',
30-
id: 'learn/networking/overview',
31-
},
32-
{
33-
type: 'doc',
34-
label: 'ADNL Protocol',
35-
id: 'learn/networking/adnl',
36-
},
37-
'learn/networking/overlay-subnetworks',
38-
'learn/networking/rldp',
39-
'learn/networking/ton-dht',
23+
'learn/networking/overview',
4024

41-
],
42-
},
43-
'develop/blockchain/shards',
44-
'develop/blockchain/sharding-lifecycle',
4525
'learn/overviews/blockchain-comparison',
46-
{
47-
type: 'link',
48-
label: 'Open-Source and Decentralization in TON',
49-
href: 'https://defi.org/ton/',
50-
},
5126
],
5227
},
5328
{

0 commit comments

Comments
 (0)