Merge branch 'ton-community:main' into react-doc-wrappers

Author: mlikhtar

README.md

@@ -76,6 +76,16 @@ Use Gitpod (a free, online VS code-like IDE) for contributing. It will launch a
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
+## Contributors Wall
+<a href="https://github.com/ton-community/ton-docs/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=ton-community/ton-docs&max=204" />
+</a>
+
+<p align="right" style="font-size: 14px; color: #555; margin-top: 20px;">
+  <a href="#readme-top" style="text-decoration: none; color: blue; font-weight: bold;">
+    ↑ Back to Top ↑
+  </a>
+</p>
 ## License
 
 [GPL-3.0](https://choosealicense.com/licenses/gpl-3.0/)

docs/develop/dapps/ton-connect/tg-bot-integration-py.md renamed to docs/develop/archive/tg-bot-integration-py.md

@@ -2,6 +2,10 @@ import Button from '@site/src/components/button'
 
 # TON Connect for Telegram Bots - Python
 
+:::warning deprecated
+This tutorial describes an outdated approach to integrating TON Connect with Telegram bots. We strongly recommend using [Telegram Mini Apps](/develop/dapps/telegram-apps) for a more modern and secure integration.
+:::
+
 In this tutorial, we’ll create a sample telegram bot that supports TON Connect 2.0 authentication using Python TON Connect SDK [pytonconnect](https://github.com/XaBbl4/pytonconnect).
 We will analyze connecting a wallet, sending a transaction, getting data about the connected wallet, and disconnecting a wallet.
 

docs/develop/dapps/ton-connect/tg-bot-integration.mdx renamed to docs/develop/archive/tg-bot-integration.mdx

@@ -2,6 +2,10 @@ import Button from '@site/src/components/button'
 
 # TON Connect for Telegram Bots
 
+:::warning deprecated
+This tutorial describes an outdated approach to integrating TON Connect with Telegram bots. We strongly recommend using [Telegram Mini Apps](/develop/dapps/telegram-apps) for a more modern and secure integration.
+:::
+
 In this tutorial, we’ll create a sample telegram bot that supports TON Connect 2.0 authentication using Javascript TON Connect SDK.
 We will analyze connecting a wallet, sending a transaction, getting data about the connected wallet, and disconnecting a wallet.
 
@@ -206,7 +210,7 @@ import { IStorage } from '@tonconnect/sdk';
 const storage = new Map<string, string>(); // temporary storage implementation. We will replace it with the redis later
 
 export class TonConnectStorage implements IStorage {
-  constructor(private readonly chatId: number) {} // we need to have different stores for different users 
+  constructor(private readonly chatId: number) {} // we need to have different stores for different users
 
   private getKey(key: string): string {
     return this.chatId.toString() + key; // we will simply have different keys prefixes for different users
@@ -269,7 +273,7 @@ Let's analyze what we are doing here. Firstly we fetch the wallets list and crea
 After that we subscribe to wallet change. When user connects a wallet, bot will send a message `${wallet.device.appName} wallet connected!`.
 Next we find the Tonkeeper wallet and create connection link. In the end we generate a QR code with the link and send it as a photo to the user.
 
-Now you can run the bot (`npm run compile` and `npm run start` then) and send `/connect` message to the bot. Bot should reply with the QR. Scan it with the Tonkeeper wallet. You will see a message `Tonkeeper wallet connected!` in the chat. 
+Now you can run the bot (`npm run compile` and `npm run start` then) and send `/connect` message to the bot. Bot should reply with the QR. Scan it with the Tonkeeper wallet. You will see a message `Tonkeeper wallet connected!` in the chat.
 
 
 We will use connector in many places, so let's move connector creating code to a separate file:
@@ -351,17 +355,17 @@ We will implement following UX for wallet connection:
 ```text
 First screen:
 <Unified QR>
-<Open @wallet>, <Choose a wallet button (opens second screen)>, <Open wallet unified link> 
+<Open @wallet>, <Choose a wallet button (opens second screen)>, <Open wallet unified link>
 
 Second screen:
 <Unified QR>
 <Back (opens first screen)>
-<@wallet button (opens third screen)>, <Tonkeeper button (opens third screen)>, <Tonhub button (opens third screen)>, <...> 
+<@wallet button (opens third screen)>, <Tonkeeper button (opens third screen)>, <Tonhub button (opens third screen)>, <...>
 
 Third screen:
 <Selected wallet QR>
 <Back (opens second screen)>
-<Open selected wallet link> 
+<Open selected wallet link>
 ```
 
 Let's start with adding inline keyboard to the `/connect` command handler in the `main.ts`
@@ -408,7 +412,7 @@ bot.onText(/\/connect/, async msg => {
 We need to wrap TonConnect deeplink as https://ton-connect.github.io/open-tc?connect=${encodeURIComponent(link)} because only `http` links are allowed in the Telegram inline keyboard.
 Website https://ton-connect.github.io/open-tc just redirects user to link passed in the `connect` query param, so it's only workaround to open `tc://` link in the Telegram.
 
-Note that we replaced `connector.connect` call arguments. Now we are generating a unified link for all wallets. 
+Note that we replaced `connector.connect` call arguments. Now we are generating a unified link for all wallets.
 
 Next we tell Telegram to call `callback_query` handler with `{ "method": "chose_wallet" }` value when user clicks to the `Choose a Wallet` button.
 
@@ -461,7 +465,7 @@ export const walletMenuCallbacks = { // Define buttons callbacks
     chose_wallet: onChooseWalletClick
 };
 
-bot.on('callback_query', query => { // Parse callback data and execute corresponing function 
+bot.on('callback_query', query => { // Parse callback data and execute corresponing function
     if (!query.data) {
         return;
     }
@@ -485,14 +489,14 @@ bot.on('callback_query', query => { // Parse callback data and execute correspon
 async function onChooseWalletClick ...
 ```
 
-Here we define buttons handlers list and `callback_query` parser. Unfortunately callback data is always string, so we have to pass JSON to the `callback_data` and parse it later in the `callback_query` handler. 
+Here we define buttons handlers list and `callback_query` parser. Unfortunately callback data is always string, so we have to pass JSON to the `callback_data` and parse it later in the `callback_query` handler.
 Then we are looking for the requested method and call it with passed parameters.
 
 Now we should add `conenct-wallet-menu.ts` import to the `main.ts`
 ```ts
 // src/main.ts
 
-// ... other imports 
+// ... other imports
 
 import './connect-wallet-menu';
 
@@ -675,7 +679,7 @@ export const walletMenuCallbacks = {
     universal_qr: onOpenUniversalQRClick
 };
 
-bot.on('callback_query', query => { // Parse callback data and execute corresponing function 
+bot.on('callback_query', query => { // Parse callback data and execute corresponing function
     if (!query.data) {
         return;
     }
@@ -830,7 +834,7 @@ async function editQR(message: TelegramBot.Message, link: string): Promise<void>
 
 Compile and run the bot to check how wallet connection works now.
 
-You may note that we haven't considered QR code expiration and stopping connectors yet. We will handle it later. 
+You may note that we haven't considered QR code expiration and stopping connectors yet. We will handle it later.
 
 
 At the moment we have the following files structure:
@@ -951,7 +955,7 @@ export const walletMenuCallbacks = {
 };
 
 async function onChooseWalletClick(query: CallbackQuery, _: string): Promise<void> {
-    
+
 // ... other code
 ```
 
@@ -1121,8 +1125,8 @@ bot.onText(/\/my_wallet/, handleShowMyWalletCommand);
 Compile and run the bot to check that commands above works correctly.
 
 ## Optimisation
-We've done all basic commands. But it is important to keep in mind that each connector keeps SSE connection opened until it is paused. 
-Also, we didn't handle case when user calls `/connect` multiple times, or calls `/connect` or `/send_tx` and doesn't scan the QR. We should set a timeout and close the connection to save server resources. 
+We've done all basic commands. But it is important to keep in mind that each connector keeps SSE connection opened until it is paused.
+Also, we didn't handle case when user calls `/connect` multiple times, or calls `/connect` or `/send_tx` and doesn't scan the QR. We should set a timeout and close the connection to save server resources.
 Then we should notify user that QR / transaction request is expired.
 
 ### Send transaction optimisation
@@ -1339,10 +1343,10 @@ export function getConnector(
 
 </details>
 
-This code may look a little tricky, but here we go. 
+This code may look a little tricky, but here we go.
 Here we store a connector, it's cleaning timeout and list of callback that should be executed after the timeout for each user.
 
-When `getConnector` is called we check if there is an existing connector for this `chatId` (user) it the cache. If it exists we reset the cleaning timeout and return the connector. 
+When `getConnector` is called we check if there is an existing connector for this `chatId` (user) it the cache. If it exists we reset the cleaning timeout and return the connector.
 That allows keep active users connectors in cache. It there is no connector in the cache we create a new one, register a timeout clean function and return this connector.
 
 To make it works we have to add a new parameter to the `.env`
@@ -1396,7 +1400,7 @@ export async function handleConnectCommand(msg: TelegramBot.Message): Promise<vo
         const connectedName =
             (await getWalletInfo(connector.wallet!.device.appName))?.name ||
             connector.wallet!.device.appName;
-        
+
         await bot.sendMessage(
             chatId,
             `You have already connect ${connectedName} wallet\nYour address: ${toUserFriendlyAddress(
@@ -1465,9 +1469,9 @@ export async function handleConnectCommand(msg: TelegramBot.Message): Promise<vo
 
 </details>
 
-We defined `newConnectRequestListenersMap` to store cleanup callback for the last connect request for each user. 
-If user calls `/connect` multiple times, bot will delete previous message with QR. 
-Also, we subscribed to the connector expiration timeout to delete the QR-code message when it is expired.  
+We defined `newConnectRequestListenersMap` to store cleanup callback for the last connect request for each user.
+If user calls `/connect` multiple times, bot will delete previous message with QR.
+Also, we subscribed to the connector expiration timeout to delete the QR-code message when it is expired.
 
 
 Now we should remove `connector.onStatusChange` subscription from the `connect-wallet-menu.ts` functions,
@@ -1641,7 +1645,7 @@ export async function buildUniversalKeyboard(
 }
 ```
 
-Here we are adding separate button for @wallet to the First screen (Universal QR screen). All that remains is to use this function in 
+Here we are adding separate button for @wallet to the First screen (Universal QR screen). All that remains is to use this function in
 connect-wallet-menu and command-handlers:
 
 
@@ -1825,7 +1829,7 @@ async function onWalletClick(query: CallbackQuery, data: string): Promise<void>
 
 </details>
 
-Note that we place different links to the QR and button-link (`qrLink` and `buttonLink`), 
+Note that we place different links to the QR and button-link (`qrLink` and `buttonLink`),
 because we don't need redirection when user scans QR by @wallet, and at the same time we need redirect back to the bot when user connects @wallet using button-link.
 
 
@@ -1917,7 +1921,7 @@ export async function handleSendTXCommand(msg: TelegramBot.Message): Promise<voi
 
 </details>
 
-That is it. Now user is able to connect @wallet using special button on the main screen, also we have provided proper return strategy for TG links. 
+That is it. Now user is able to connect @wallet using special button on the main screen, also we have provided proper return strategy for TG links.
 
 ## Add a permanent storage
 At this moment we store TonConnect sessions in the Map object. But you may want to store it to the database or other permanent storage to save the sessions when you restart the server.

docs/develop/blockchain/sharding-lifecycle.mdx

@@ -14,6 +14,75 @@ ISP underpins the TON Blockchain's design, treating each account as part of its
 
 Each shardchain, or more precisely, each shardchain block, is identified by a combination of `workchain_id` and a binary prefix `s` of the account_id.
 
+## Algorithm for deciding whether to split or merge
+
+Validators decide whether to split or merge shards in the following way:
+1. For each block, block size, gas consumption and lt delta are calculated.
+2. Using these values, blocks can be considered overloaded or underloaded.
+3. Each shard keeps underload and overload history. If enough recent blocks were underloaded or overloaded, `want_merge` or `want_split` flag is set.
+4. Validators merge or split shards using these flags.
+
+### 1. Assessment of the current state of the block
+
+Each block has the following parameters. They are used to determine overload and underload.
+1. *Block size estimation* - not an actual block size, but an estimation calculated during collation.
+2. *Gas consumption* - total gas consumed in all transactions (excluding ticktock and mint/recover special transactions).
+3. *Lt delta* - difference between start and end lt of the block.
+
+### 2. Block limits and classification
+
+Block limits are loaded from the [configuration parameters 22 and 23](/develop/howto/blockchain-configs#param-22-and-23).
+Each of the three parameters has three limits: underload, soft, hard:
+1. *Block size*: `128/256/512 KiB`.
+2. *Gas consumption*: `2M/10M/20M` in basechain, `200K/1M/2.5M` in masterchain.
+3. *Lt delta*: `1000/5000/10000`.
+Also, there is a medium limit, which is equal to `(soft + hard) / 2`.
+
+We classify the three parameters (size, gas, and lt delta) into categories:
+- `0` - underload limit is not reached.
+- `1` - underload limit is exceeded.
+- `2` - soft limit is exceeded.
+- `3` - medium limit is exceeded.
+- `4` - hard limit is exceeded.
+
+Block classification is max(`Classification of size`, `Classification of gas`, `Classification of lt delta`). For example: if classification of size is 2, classification of gas is 3, classification of lt delta is 1, then the final block classification is 3.
+
+- When classification of the block is 0 (underload), the block is inclined to merge with its sibling.
+- When classification of the block is 2 (soft limit reached), collator stops processing internal messages. The block is inclined to split.
+- When classification of the block is 3 (medium limit reached), collator stops processing external messages.
+
+### 3. Determination of overload or underload
+
+After classifying the block, collator checks overload and underload conditions.
+Size of the outbound message queue and status of dispatch queue processing is also taken into consideration.
+- If the block class is ≥ `2` (soft) and message queue size ≤ `SPLIT_MAX_QUEUE_SIZE = 100000` then the block is overloaded.
+- If limit for total processed messages from dispatch queue was reached and message queue size ≤ `SPLIT_MAX_QUEUE_SIZE = 100000` then the block is overloaded.
+- If the block class is `0` (underload) and message queue size ≤ `MERGE_MAX_QUEUE_SIZE = 2047` then the block is underloaded.
+- If message queue size is ≥ `FORCE_SPLIT_QUEUE_SIZE = 4096` and ≤ `SPLIT_MAX_QUEUE_SIZE = 100000` then the block is overloaded.
+
+### 4. Deciding whether to split or merge
+
+Each block keeps underload and overload history - it is a 64-bit mask of the underload/overload status of the last 64 blocks.
+It is used to decide whether to split or merge.
+
+Underload and overload history has a weight, which is calculated as follows:
+`one_bits(mask & 0xffff) * 3 + one_bits(mask & 0xffff0000) * 2 + one_bits(mask & 0xffff00000000) - (3 + 2 + 1) * 16 * 2 / 3`
+(here `one_bits` is the number of `1`-bits in a mask, and the lower bits correspond to the most recent blocks).
+
+When underload or overload history has a non-negative weight, the flag `want_merge` or `want_split` is set.
+
+### 5. Final decision
+
+Validators decide to split or merge shards using `want_split` and `want_merge` flags and [workchain configuration parameters](/develop/howto/blockchain-configs#param-12).
+
+- If the shard has depth < `min_split` then it will split.
+- If the shard has depth > `max_split` then it will merge.
+- Shards with depth `min_split` cannot merge, shards with depth `max_split` cannot split.
+- If the block has `want_split` flag, the shard will split.
+- If the block and its sibling have `want_merge` flag, the shards will merge.
+
+Shards split and merge in `split_merge_delay = 100` seconds after the decision is made.
+
 ## Messages and Instant Hypercube Routing (Instant Hypercube Routing)
 
 In the infinite sharding paradigm, each account (or smart-contract) is treated as if it were itself in a separate shardchain.

docs/develop/companies/auditors.mdx

@@ -8,18 +8,19 @@ Test your software with the following quality assurance providers.
 
 ## Primary TON Blockchain SAP
 
+* [certik.com](certik.com)
 * [quantstamp.com](https://quantstamp.com/)
+* [trailofbits.com](https://www.trailofbits.com/)
 * [zellic.io](https://www.zellic.io/)
 
 ## TON Ecosystem SAP
 
+* [beosin.com](https://beosin.com/)
 * [hackenproof.com](https://hackenproof.com/)
 * [hexens.io](https://hexens.io/)
 * [scalebit](https://www.scalebit.xyz/)
-* [skynet.certik.com](https://skynet.certik.com/)
 * [slowmist.com](https://slowmist.com/)
 * [softstack.io formerly Chainsulting](https://softstack.io/)
-* [trailofbits.com](https://www.trailofbits.com/)
 * [vidma.io](https://vidma.io/)
 
 

docs/develop/dapps/apis/sdk.mdx

@@ -29,7 +29,7 @@ There are different ways to connect to blockchain:
 
 ### Python
 
-<!-- tonsdk dropped due to invalid cells serialization -->
+<!-- tonsdk dropped due to invalid cells serialization, it is deprecated now -->
 
 | Library |	Blockchain connection |	Description |
 |---------|------------------|--------------|

docs/develop/dapps/asset-processing/overview.md

@@ -8,7 +8,7 @@ Here you can find a **short overview** on [how TON transfers work](/develop/dapp
 
 ## Overview on messages and transactions
 
-Embodying a fully asynchronous approach, TON Blockchain involves a few concepts which are uncommon to traditional blockchains. Particularly, each interaction of any actor with the blockchain consists of a graph of asynchronously transferred [messages](/develop/smart-contracts/guidelines/message-delivery-guarantees) between smart contracts and/or the external world. Each transaction consists of one incoming message and up to 512 outgoing messages.
+Embodying a fully asynchronous approach, TON Blockchain involves a few concepts which are uncommon to traditional blockchains. Particularly, each interaction of any actor with the blockchain consists of a graph of asynchronously transferred [messages](/develop/smart-contracts/guidelines/message-delivery-guarantees) between smart contracts and/or the external world. Each transaction consists of one incoming message and up to 255 outgoing messages.
 
 There are 3 types of messages, that are fully described [here](/develop/smart-contracts/messages#types-of-messages). To put it briefly:
 * [external message](/develop/smart-contracts/guidelines/external-messages):