diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d314b906c7..abfdd4b2c7 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,12 +1,13 @@ - -## Why is it important? +## Description - +<--Brief description of the changes introduced in this pull request. Include any relevant issue numbers or links.--> -## Related Issue +Closes <--link to issue]-->. - - - - \ No newline at end of file +## Checklist + +- [ ] I have created an issue. +- [ ] I am working on content that aligns with the [Style guide](https://docs.ton.org/v3/contribute/style-guide/). +- [ ] I have reviewed and formatted the content according to [Content standardization](https://docs.ton.org/v3/contribute/content-standardization/). +- [ ] I have reviewed and formatted the text in the article according to [Typography](https://docs.ton.org/v3/contribute/typography/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e389331bce..331ef37b8c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,4 +5,4 @@ ### Thank you for your interest in contributing! -Please see [our contributing guide on documentation](/v3/contribute/) for the latest information on how to contribute! +Please see [our contributing guide on documentation](https://docs.ton.org/v3/contribute) for the latest information on how to contribute! diff --git a/README.md b/README.md index 44b3f80943..edb9677602 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,10 @@ -## TON Blockchain Documentation 📚 +## TON documentation 📚 This is the official repository for The Open Network documentation. Latest documentation release: [docs.ton.org](https://docs.ton.org) - -The mission of this documentation is to collect all available information and knowledge that can help TON developers. - -You can improve the documentation by following steps below. --- @@ -30,29 +26,28 @@ Join TON Docs Club chat in Telegram to join contributors party: ## How to Contribute? 🦄 -If you are a developer and faced some difficulties, successfully overcoming them - share this knowledge with future developers! - — Have an issue? [Prepare a solution with TON Docs Wizard](https://t.me/ton_docs_bot). — Have an idea? [Submit a Feature Request](https://github.com/ton-community/ton-docs/issues/new/choose). -— Want to contribute? [Setup your environment](https://github.com/ton-community/ton-docs#set-up-your-environment-%EF%B8%8F). +— Want to contribute? [How to contribute](https://docs.ton.org/v3/contribute). +— Want to translate? [Localization](https://docs.ton.org/v3/contribute/localization-program/how-to-contribute) + -Contributing best practices: [docs/contribute](/v3/contribute) --- -## Set up your Environment ☁️ +## Set up your environment ☁️ -If you are changing the sidebar or adding media-files, please check that your submission will not break production. +If you're changing the sidebar or adding media-files, links, please make sure that your submission won't break production. You can do this in two ways: -### Cloud (quick way) +### Cloud -Use Gitpod (a free, online VS code-like IDE) for contributing. It will launch a workspace with a single click: +Use Gitpod for contributing. It'll launch a workspace with a single click: [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/ton-community/ton-docs) -### Local (default way) +### Local 1. Download repository from GitHub with its submodules @@ -81,14 +76,14 @@ 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. -## Install Recursive Module +## Install recursive module -If you cloned the repository from GitHub without step 1, you will need to install the submodules to enable local execution. +If you cloned the repository from GitHub without step 1, you'll need to install the submodules to enable local execution. ``` git submodule update --init --recursive ``` -## Contributors Wall +## Contributors wall diff --git a/cspell.json b/cspell.json index 99075fd128..9bacb6679c 100644 --- a/cspell.json +++ b/cspell.json @@ -116,6 +116,9 @@ "Tolk", "Toncoin", "Toncoins", + "Tonhub", + "Tonkeeper", + "Tonkey", "Underload", "Uninit", "WAGMI", diff --git a/docs/v3/concepts/dive-into-ton/go-from-ethereum/blockchain-services.md b/docs/v3/concepts/dive-into-ton/go-from-ethereum/blockchain-services.md index e25368383c..c3414fe3ce 100644 --- a/docs/v3/concepts/dive-into-ton/go-from-ethereum/blockchain-services.md +++ b/docs/v3/concepts/dive-into-ton/go-from-ethereum/blockchain-services.md @@ -1,10 +1,10 @@ -# Blockchain Services +# Blockchain services -## Domain Name Systems +## Domain name systems -In Ethereum, users use the Ethereum Name Service (ENS), which is a decentralized naming system built on top of the Ethereum blockchain. +In Ethereum, users use the **Ethereum Name Service (ENS)**, which is a decentralized naming system built on top of the Ethereum blockchain. -The TON blockchain includes an embedded domain name system known as the TON DNS. It is a decentralized service that allows users to register human-readable domain names for their smart contracts, websites, or any other online content. Such a device facilitates interaction with decentralized applications (dApps) and other resources on the TON blockchain. The DNS system in TON functions similarly to traditional Internet DNS systems, but its decentralized nature eliminates the need for a centralized authority to control and manage domain names, thereby reducing the risks of censorship, fraud, and domain name hijacking. +The TON blockchain includes an embedded domain name system known as the TON DNS. It's a decentralized service that allows users to register human-readable domain names for their smart contracts, websites, or any other online content. Such a device facilitates interaction with decentralized applications (dApps) and other resources on the TON blockchain. The DNS system in TON functions similarly to traditional Internet DNS systems, but its decentralized nature eliminates the need for a centralized authority to control and manage domain names, thereby reducing the risks of censorship, fraud, and domain name hijacking. ## WWW diff --git a/docs/v3/concepts/dive-into-ton/go-from-ethereum/difference-of-blockchains.md b/docs/v3/concepts/dive-into-ton/go-from-ethereum/difference-of-blockchains.md index 9000b67042..ea88f4f9d3 100644 --- a/docs/v3/concepts/dive-into-ton/go-from-ethereum/difference-of-blockchains.md +++ b/docs/v3/concepts/dive-into-ton/go-from-ethereum/difference-of-blockchains.md @@ -1,4 +1,4 @@ -# The Difference of Blockchains +# The difference of blockchains In this chapter, we will examine the key differences between the Ethereum blockchain compared to the TON blockchain. The analysis will include an overview of the network architectures, highlight their unique features, and evaluate the advantages and disadvantages of each. @@ -46,7 +46,7 @@ The result of scripts is always the creation of a transaction. The transactions We have already discussed that in Ethereum, a user's wallet is generated based on their address, which is in a 1-to-1 relationship with their public key. But in TON, all wallets are smart contracts that must be deployed by the user himself. Since smart contracts can be configured in different ways and have different features, there are several versions of wallets, which you can read about [here](/v3/documentation/smart-contracts/contracts-specs/wallet-contracts). Due to the fact that wallets are smart contracts, a user can have multiple wallets with different addresses and initial parameters. To send a transaction, the user must sign the message with his private key and send it to his wallet contract, which in turn forwards it to the smart contract of a particular DApp application. This approach greatly increases flexibility in wallet design and developers can add new versions of the wallet in the future. In Ethereum at the moment developers are actively using multi-sig wallets (smart contracts) like gnosis and are just starting to introduce so-called `account-abstractions' like ERC-4337, where wallets will be filled with such functionality as sending transactions without a native token, account recovery, after its loss, etc., but it's worth noting, wallet accounts are much more expensive to use in terms of gas fees compared to EOA in Ethereum. -## Messages and Transactions +## Messages and transactions What happens between two contracts is called a message - a small number of tokens and arbitrary data are sent to a specified address. When the message arrives at the contract, it is processed by the contract code, the contract updates its state and optionally sends a new message. All these actions on the contract are recorded as transactions. Let's imagine an example, we have a chain of messages, from contract `A` to contract `B`, from contract `B`, to contract `C`, then we will have two messages and three transactions. But initially, to change the state of the blockchain, you need an outside signal. To invoke a smart contract, you need to send an external message that goes to the validators and they apply it to the smart contract. And we already discussed in the last subsection that a wallet is a smart contract, so this external message usually first goes to the wallet's smart contract, which records them as the first transaction and that first transaction usually contains an embedded message for the actual destination contract. When the wallet smart contract receives the message, it processes it and delivers it to the destination contract (in our example, contract `A` could be a wallet and when it receives the external message, it will have the first transaction). The sequence of transactions forms a chain. So you can see that each smart contract has its own transactions, which means that each contract has its own `little blockchain` (you can read more about it [here](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains)), so the network can process the transactions due to this completely independent of each other diff --git a/docs/v3/concepts/dive-into-ton/go-from-ethereum/solidity-vs-func.md b/docs/v3/concepts/dive-into-ton/go-from-ethereum/solidity-vs-func.md index 9b6b0359c5..74f600bb8a 100644 --- a/docs/v3/concepts/dive-into-ton/go-from-ethereum/solidity-vs-func.md +++ b/docs/v3/concepts/dive-into-ton/go-from-ethereum/solidity-vs-func.md @@ -37,9 +37,9 @@ In case of FunC, the main data types are: Currently, FunC has no support for defining custom types. -### See Also +### See also -- [Statements](/v3/documentation/smart-contracts/func/docs/statements) +- [Statements](/v3/documentation/smart-contracts/func/docs/statements/) ## Declaring and using variables @@ -58,9 +58,9 @@ FunC is a more abstract and function-oriented language, it supports dynamic typi var z = x + y; // Dynamic variable declaration ``` -### See Also +### See also -- [Statements](/v3/documentation/smart-contracts/func/docs/statements) +- [Statements](/v3/documentation/smart-contracts/func/docs/statements/) ## Loops @@ -88,9 +88,9 @@ repeat(10) { ;; x = 1024 ``` -### See Also +### See also -- [Statements](/v3/documentation/smart-contracts/func/docs/statements) +- [Statements](/v3/documentation/smart-contracts/func/docs/statements/) ## Functions @@ -114,9 +114,9 @@ Transitioning to FunC, FunC program is essentially a list of function declaratio } ``` -### See Also +### See also -- [Functions](/v3/documentation/smart-contracts/func/docs/functions) +- [Functions](/v3/documentation/smart-contracts/func/docs/functions/) ## Flow control structures @@ -124,9 +124,9 @@ Most of the control structures known from curly-braces languages are available i FunC supports classic `if-else` statements, as well as `ifnot`, `repeat`, `while` and `do/until` loops. Also since v0.4.0 `try-catch` statements are supported. -### See Also +### See also -- [Statements](/v3/documentation/smart-contracts/func/docs/statements) +- [Statements](/v3/documentation/smart-contracts/func/docs/statements/) ## Dictionaries @@ -134,13 +134,13 @@ Dictionary (hashmap/mapping) data structure is very important for Solidity and F Mapping is a hash table in Solidity that stores data as key-value pairs, where the key can be any of the built-in data types, excluding reference types, and the value of the data type can be any type. Mappings are most typically used in Solidity and the Ethereum blockchain to connect a unique Ethereum address to a corresponding value type. In any other programming language, a mapping is equivalent to a dictionary. -In Solidity, mappings do not have a length, nor do they have the concept of setting a key or a value. Mappings are only applicable to state variables that serve as store reference types. When mappings are initialised, they include every possible key, and are mapped to values whose byte-representations are all zeros. +In Solidity, mappings don't have a length, nor do they have the concept of setting a key or a value. Mappings are only applicable to state variables that serve as store reference types. When mappings are initialised, they include every possible key, and are mapped to values whose byte-representations are all zeros. An analogy of mappings in FunC are dictionaries, or TON hashmaps. In the context of TON, a hashmap is a data structure represented by a tree of cells. Hashmap maps keys to values ​​of arbitrary type so that quick lookup and modification are possible. The abstract representation of a hashmap in TVM is a Patricia tree, or a compact binary trie. Working with potentially large cell trees can create several problems. Each update operation builds an appreciable number of cells (each cell built costs 500 gas), which means that these operations can run out of resource if used carelessly. To avoid exceeding the gas limit, limit the number of dictionary updates in a single transaction. Also, a binary tree for `N` key-value pairs contains `N-1` forks, which means a total of at least `2N-1` cells. The storage of a smart contract is limited to `65536` unique cells, so the maximum number of entries in the dictionary is `32768`, or slightly more if there are repeating cells. -### See Also +### See also -- [Dictionaries in TON](/v3/documentation/smart-contracts/func/docs/dictionaries) +- [Dictionaries in TON](/v3/documentation/smart-contracts/func/docs/dictionaries/) ## Smart-contract communication @@ -208,15 +208,15 @@ var msg = begin_cell() send_raw_message(msg, mode); ``` Let's discuss in more detail what it looks like for our smart contract to send a message to our recipient: -1. Initially, we need to build our message. The full structure of the send can be found [here](/v3/documentation/smart-contracts/message-management/sending-messages). We won't go into detail on how to assemble it here, you can read about that at the link. +1. Initially, we need to build our message. The full structure of the send can be found [here](/v3/documentation/smart-contracts/message-management/sending-messages/). We won't go into detail on how to assemble it here, you can read about that at the link. 2. The body of the message represents a cell. In `msg_body_cell` we do: `begin_cell()` - creates `Builder` for the future cell, first `store_uint` - stores the first uint into `Builder` (1 - this is our `op`), second `store_uint` - stores the second uint into `Builder` (num - this is our number that we will manipulate in the receiving contract), `end_cell()` - creates the cell. 3. To attach the body that will come in `recv_internal` in the message, we reference the collected cell in the message itself with `store_ref`. 4. Sending a message. This example presented how smart contracts can communicate with each other. -### See Also +### See also -- [Internal Messages](/v3/documentation/smart-contracts/message-management/internal-messages) -- [Sending Messages](/v3/documentation/smart-contracts/message-management/sending-messages) -- [Non-bouncable messages](/v3/documentation/smart-contracts/message-management/non-bounceable-messages) +- [Internal Messages](/v3/documentation/smart-contracts/message-management/internal-messages/) +- [Sending Messages](/v3/documentation/smart-contracts/message-management/sending-messages/) +- [Non-bouncable messages](/v3/documentation/smart-contracts/message-management/non-bounceable-messages/) diff --git a/docs/v3/concepts/dive-into-ton/go-from-ethereum/tvm-vs-evm.md b/docs/v3/concepts/dive-into-ton/go-from-ethereum/tvm-vs-evm.md index 9f52e64271..4d0d9e0e83 100644 --- a/docs/v3/concepts/dive-into-ton/go-from-ethereum/tvm-vs-evm.md +++ b/docs/v3/concepts/dive-into-ton/go-from-ethereum/tvm-vs-evm.md @@ -1,10 +1,10 @@ # TVM vs EVM -Ethereum Virtual Machine (EVM) and TON Virtual Machine (TVM) are both stack-based virtual machines developed for running smart contract code. Although they have common features, there are notable distinctions between them. +**Ethereum Virtual Machine (EVM)** and **TON Virtual Machine (TVM)** are both stack-based virtual machines developed for running smart contract code. Although they have common features, there are notable distinctions between them. ## Data presentation -### Ethereum Virtual Machine (EVM) +### EVM 1. Fundamental Data Units - The EVM operates primarily on 256-bit integers, reflecting its design around Ethereum's cryptographic functions (e.g., Keccak-256 hashing and elliptic curve operations). - Data types are limited mainly to integers, bytes, and occasionally arrays of these types, but all must conform to 256-bit processing rules. @@ -15,7 +15,7 @@ Ethereum Virtual Machine (EVM) and TON Virtual Machine (TVM) are both stack-base - The simplification to 256-bit word constraints means that the EVM is not inherently designed to handle complex or custom data structures directly. - Developers often need to implement additional logic within smart contracts to simulate more complex data structures, which can lead to increased gas costs and complexity. -### TON Virtual Machine (TVM) +### TVM 1. Cell-Based Architecture - TVM uses a unique "bag of cells" model to represent data. Each cell can contain up to 128 data bytes and can have up to 4 references to other cells. - This structure allows the TVM to natively support arbitrary algebraic data types and more complex constructions such as trees or directed acyclic graphs (DAGs) directly within its storage model. @@ -28,12 +28,12 @@ Ethereum Virtual Machine (EVM) and TON Virtual Machine (TVM) are both stack-base ## Stack machine -### Ethereum Virtual Machine (EVM) +### EVM - The EVM operates as a traditional stack-based machine, where it uses a last-in, first-out (LIFO) stack to manage computation. - It processes operations by pushing and popping 256-bit integers, which are the standard size for all elements in the stack. -### TON Virtual Machine (TVM) +### TVM - TVM also functions as a stack-based machine but with a key distinction: it supports both 257-bit integers and references to cells. - This allows TVM to push and pop these two distinct types of data onto/from the stack, providing enhanced flexibility in direct data manipulation. @@ -75,41 +75,41 @@ It’s essential to note that the EVM supports complex data structures by levera ## Arithmetic operations -### Ethereum Virtual Machine (EVM) +### EVM - The Ethereum Virtual Machine (EVM) handles arithmetic using 256-bit integers, meaning operations such as addition, subtraction, multiplication, and division are tailored to this data size. -### TON Virtual Machine (TVM) +### TVM - The TON Virtual Machine (TVM) supports a more diverse range of arithmetic operations, including 64-bit, 128-bit, and 256-bit integers, both unsigned and signed, as well as modulo operations. TVM further enhances its arithmetic capabilities with operations like multiply-then-shift and shift-then-divide, which are particularly useful for implementing fixed-point arithmetic. This variety allows developers to select the most efficient arithmetic operations based on the specific requirements of their smart contracts, offering potential optimizations based on data size and type. ## Overflow checks -### Ethereum Virtual Machine (EVM) +### EVM - In the EVM, overflow checks are not inherently performed by the virtual machine itself. With the introduction of Solidity 0.8.0, automatic overflow and underflow checks were integrated into the language to enhance security. These checks help prevent common vulnerabilities related to arithmetic operations but require newer versions of Solidity, as earlier versions necessitate manual implementation of these safeguards. -### TON Virtual Machine (TVM) +### TVM - In contrast, TVM automatically performs overflow checks on all arithmetic operations, a feature built directly into the virtual machine. This design choice simplifies the development of smart contracts by inherently reducing the risk of errors and enhancing the overall reliability and security of the code. ## Cryptography and hash functions -### Ethereum Virtual Machine (EVM) +### EVM - EVM has support for the Ethereum-specific cryptography scheme, such as the secp256k1 elliptic curve and the keccak256 hash function. Also, EVM does not have built-in support for Merkle proofs, which are cryptographic proofs used to verify the membership of an element in a set. -### TON Virtual Machine (TVM) +### TVM - TVM offers support for 256-bit Elliptic Curve Cryptography (ECC) for predefined curves, like Curve25519. It also supports Weil pairings on some elliptic curves, which are useful for fast implementation of zk-SNARKs (zero-knowledge proofs). Popular hash functions like sha256 are also supported, providing more options for cryptographic operations. In addition, TVM can work with Merkle proofs, providing additional cryptographic features that can be beneficial for certain use cases, such as verifying the inclusion of a transaction in a block. ## High-level languages -### Ethereum Virtual Machine (EVM) +### EVM - EVM primarily uses Solidity as its high-level language, which is an object-oriented, statically-typed language similar to JavaScript and C++. Also, there are other languages for writing Ethereum smart-contracts such as Vyper, Yul, etc. -### TON Virtual Machine (TVM) +### TVM - TVM uses FunC as a high-level language designed for writing TON smart contracts. It is a procedural language with static types and support for algebraic data types. FunC compiles to Fift, which in turn compiles to TVM bytecode. diff --git a/docs/v3/concepts/dive-into-ton/introduction.mdx b/docs/v3/concepts/dive-into-ton/introduction.mdx index 48f8673efa..6602904644 100644 --- a/docs/v3/concepts/dive-into-ton/introduction.mdx +++ b/docs/v3/concepts/dive-into-ton/introduction.mdx @@ -5,20 +5,20 @@ import Button from '@site/src/components/button' # The Open Network -__The Open Network (TON)__ is a decentralized and open internet platform made up of several components. These include TON Blockchain, TON DNS, TON Storage, TON Sites, and TON Proxy. TON Blockchain is the core protocol connecting TON’s underlying infrastructure to form the greater TON Ecosystem. +**The Open Network (TON)** is a decentralized and open internet platform comprising several components. These include TON Blockchain, TON DNS, TON Storage, TON Sites, and TON Proxy. TON Blockchain is the core protocol connecting TON’s underlying infrastructure to form the greater TON Ecosystem. -TON is focused on achieving widespread cross-chain interoperability while operating in a highly scalable and secure framework. TON is designed to process millions of transactions per second, with the goal of eventually reaching hundreds of millions of users moving forward. +TON focuses on achieving widespread cross-chain interoperability while operating within a highly scalable and secure framework. It aims to process millions of transactions per second and eventually reach hundreds of millions of users. -__TON Blockchain__ is designed as a distributed supercomputer, or “_superserver_,” intended to provide a variety of products and services to contribute to the development of the decentralized vision for the new internet. +__TON Blockchain__, designed as a distributed supercomputer, serves as the heart of TON. It aims to provide various products and services that contribute to developing the decentralized vision for the new internet. To understand the true vision for the decentralized internet and how TON contributes to this inevitability, consider taking a deep dive into the video below: -* To learn more about the technical aspects of TON Blockchain, review the [Blockchain of Blockchains](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains) -* Learn more about the development of all things TON by reviewing this section: [Getting Started](/v3/documentation/ton-documentation) +* To learn more about the technical aspects of TON Blockchain, review the [Blockchain of Blockchains](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains/) +* Learn more about the development of all things TON by reviewing this section: [Getting Started](/v3/documentation/ton-documentation/) -## Blockchain Basics with TON +## Blockchain basics with TON This course introduces blockchain basics, focusing on practical skills in the TON ecosystem. You will understand how blockchain functions and its diverse applications. You will also acquire crucial TON-related skills, including wallet setup, crypto asset management, and creation. The course will also equip you with critical knowledge about cryptocurrency threats and fraud and give practical tips on protecting your crypto assets. @@ -46,7 +46,7 @@ Russian -## TON Blockchain Development +## TON Blockchain development __TON Blockchain Course__ is a comprehensive TON Blockchain guide. The course is designed for developers who want to learn how to create smart contracts and decentralized applications (dApps) on the TON Blockchain. @@ -78,7 +78,7 @@ Russian -## New to Blockchain +## New to blockchain If you're new to blockchain and don’t understand what makes the technology so revolutionary — consider taking a deep dive into these important resources: @@ -90,7 +90,6 @@ If you're new to blockchain and don’t understand what makes the technology so ## Migration from Ethereum For those familiar with Ethereum development, we wrote two introductory articles to help you understand what sets TON apart in this regard: -* [The Difference of Blockchains](/v3/concepts/dive-into-ton/go-from-ethereum/difference-of-blockchains) +* [The Difference of Blockchains](/v3/concepts/dive-into-ton/go-from-ethereum/difference-of-blockchains/) * [Six unique aspects of TON Blockchain that will surprise Solidity developers](https://blog.ton.org/six-unique-aspects-of-ton-blockchain-that-will-surprise-solidity-developers) * [It’s time to try something new: Asynchronous smart contracts](https://telegra.ph/Its-time-to-try-something-new-Asynchronous-smart-contracts-03-25) -* [Comparison of Blockchains](https://ton.org/comparison_of_blockchains.pdf) diff --git a/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-comparison.md b/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-comparison.md index 3813b7705f..38f1d21b01 100644 --- a/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-comparison.md +++ b/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-comparison.md @@ -1,4 +1,4 @@ -# Comparison of Blockchains +# Comparison of blockchains This document provides a comparative analysis of TON against Ethereum and Solana. @@ -6,5 +6,5 @@ This document provides a comparative analysis of TON against Ethereum and Solana |----------------------------|------------------------|------------------|-------------| | **Consensus** | Proof of Stake | Proof of History | BFT PoS | | **TPS** | 100,000 TPS | 59,400 TPS | 104,715 TPS | -| **Block Time** | 12 sec | < 1 sec | 5 sec | -| **Time to Finalize Block** | 10-15 min | ~6.4 sec | < 6 sec | +| **Block Time** | 12 sec | < 1 sec | < 1 sec | +| **Time to Finalize Block** | 10-15 min | ~13 sec | < 3 sec | diff --git a/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains.md b/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains.md index d8551b03a1..4393b1c800 100644 --- a/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains.md +++ b/docs/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains.md @@ -1,4 +1,4 @@ -# Blockchain of Blockchains +# Blockchain of blockchains :::tip @@ -11,64 +11,69 @@ Let's consider one smart contract. In TON, it is a _thing_ with properties like `address`, `code`, `data`, `balance` and others. In other words, it is an object with some _storage_ and _behavior_. That behavior has the following pattern: -* something happens (the most common situation is that a contract gets a message) -* contract handles that event according to its own properties by executing its `code` in TON Virtual Machine. -* contract modifies its own properties (`code`, `data`, and others) +* contract receives a message +* contract handles that event according to its properties by executing its `code` in TON Virtual Machine +* contract modifies its properties consisting of `code`, `data`, and others * contract optionally generates outgoing messages * contract goes into standby mode until the next event occurs -A combination of these steps is called a **transaction**. It is important that events are handled one by one, thus _transactions_ are strictly ordered and cannot interrupt each other. +A combination of these steps is called a **transaction**. Since it is essential to handle events one by one, transactions follow a strict order and cannot interrupt each other. -This behavior pattern is well known and called 'Actor'. +This behavior pattern is well known and called **actor**. ### The lowest level: AccountChain -A sequence of _transactions_ `Tx1 -> Tx2 -> Tx3 -> ....` may be called a **chain**. And in the considered case it is called **AccountChain** to emphasize that it is _the chain_ of a single account of transactions. +A sequence of transactions `Tx1 -> Tx2 -> Tx3 -> ....` may be called a **chain**. When considering a single account, we call the chain of transactions an **AccountChain**. -Now, since nodes that process transactions need from time to time to coordinate the state of the smart contract (to reach a _consensus_ about the state) those _transactions_ are batched: +Now, since nodes that process transactions need from time to time to coordinate the state of the smart contract to reach a consensus about the state, those transactions are batched: `[Tx1 -> Tx2] -> [Tx3 -> Tx4 -> Tx5] -> [] -> [Tx6]`. -Batching does not intervene in sequencing, each transaction still has only one 'prev tx' and at most one 'next tx', but now this sequence is cut into the **blocks**. +Batching does not intervene in sequencing; each transaction still has only one 'prev tx' and at most one 'next tx', but now this sequence is cut into the blocks. -It is also expedient to include queues of incoming and outgoing messages in _blocks_. In that case, a _block_ will contain a full set of information that determines and describes what happened to the smart contract during that block. +It is also expedient to include queues of incoming and outgoing messages in blocks. In that case, the block will contain a full set of information that determines and describes what happened to the smart contract during that block. ## Many AccountChains: Shards -Now let's consider many accounts. We can get a few _AccountChains_ and store them together, such a set of _AccountChains_ is called a **ShardChain**. In the same way, we can cut **ShardChain** into **ShardBlocks**, which are an aggregation of individual _AccountBlocks_. +Now let's consider many accounts. We can get a few AccountChains and store them together; such a set of AccountChains is called a **ShardChain**. In the same way, we can cut ShardChain into **ShardBlocks**, which are an aggregation of individual AccountBlocks. ### Dynamic splitting and merging of ShardChains -Note that since a _ShardChain_ consists of easily distinguished _AccountChains_, we can easily split it. That way if we have 1 _ShardChain_ which describes events that happen with 1 million accounts and there are too many transactions per second to be processed and stored in one node, so we just divide (or **split**) that chain into two smaller _ShardChains_ with each chain accounting for half a million accounts and each chain processed on a separate subset of nodes. +Note that since a ShardChain consists of easily distinguished AccountChains, we can easily split it. That way, if we have one ShardChain that describes events that happen with one million accounts and there are too many transactions per second to be processed and stored in one node, so we just **split** that chain into two smaller ShardChains with each chain accounting for half a million accounts and each chain processed on a separate subset of nodes. -Analogously, if some shards become too unoccupied, they can be **merged** into one bigger shard. +Analogously, if some shards become too unoccupied, they can be **merged** into one more enormous shard. -There are obviously two limiting cases: when the shard contains only one account (and thus cannot be split further) and when the shard contains all accounts. +There are two limiting cases: when the shard contains only one account (and thus cannot be split further) and when the shard contains all accounts. -Accounts can interact with each other by sending messages. There is a special mechanism of routing which move messages from outgoing queues to corresponding incoming queues and ensures that 1) all messages will be delivered 2) messages will be delivered consecutively (the message sent earlier will reach the destination earlier). +Accounts can interact with each other by sending messages. A unique routing mechanism moves messages from outgoing queues to corresponding incoming queues and ensures: +1. The delivery of all messages +2. Consecutive delivery of messages — a message sent earlier will reach the destination earlier :::info SIDE NOTE -To make splitting and merging deterministic, an aggregation of AccountChains into shards is based on the bit-representation of account addresses. For example, address looks like `(shard prefix, address)`. That way, all accounts in the shardchain will have exactly the same binary prefix (for instance, all addresses will start with `0b00101`). +An aggregation of AccountChains into shards is based on the bit-representation of account addresses to make splitting and merging deterministic. For example, an address looks like `(shard prefix, address)`. That way, all accounts in the ShardChain will have the same binary prefix (for instance, all addresses will start with `0b00101`). ::: ## Blockchain -An aggregation of all shards, which contains all accounts behaving by one set of rules, is called a **Blockchain**. +An aggregation of all shards, which contains all accounts behaving according to one set of rules, is called a Blockchain. -In TON, there can be many sets of rules, and thus, many blockchains which operate simultaneously and can interact with each other by sending messages cross-chain in the same way that accounts of one chain can interact with each other. +In TON, there can be many sets of rules, and thus, many blockchains operate simultaneously and can interact with each other by sending messages cross-chain in the same way that accounts of one chain can interact with each other. -### WorkChain: Blockchain with your own rules +### WorkChain: a blockchain with your own rules -If you want to customize rules of the group of ShardChains, you could create a **WorkChain**. A good example is to make a workchain that works on the base of EVM to run Solidity smart contracts on it. +If you want to customize the rules of the ShardChains group, you could create a **WorkChain**. A good example is to make a workchain that works on the base of EVM to run Solidity smart contracts on it. -Theoretically, everyone in community can create own workchain. In fact, it's pretty complicated task to build it, after that to pay (expensive) price of creating it and receive 2/3 of votes from validators to approve creation of your Workchain. +Theoretically, everyone in the community can create their own WorkChain. Building it isn't very easy, and then you have to pay a high price and receive 2/3 of votes from validators to approve it. -TON allows creation of up to `2^32` workchains, each subdivided into up to `2^60` shards. +TON allows creating up to `2^32` workchains, subdivided into `2^60` shards. Nowadays, there are only two workchains in TON: MasterChain and BaseChain. -BaseChain is used for everyday transactions between actors because it's pretty cheap, while MasterChain has a crucial function for TON. +BaseChain is used for everyday transactions between actors because it's cheap, while MasterChain has a crucial function for TON. -### MasterChain: Blockchain of Blockchains +### MasterChain: blockchain of blockchains -There is a necessity for the synchronization of message routing and transaction execution. In other words, nodes in the network need a way to fix some 'point' in a multichain state and reach a consensus about that state. In TON, a special chain called **MasterChain** is used for that purpose. Blocks of _MasterChain_ contain additional information (latest block hashes) about all other chains in the system, thus any observer unambiguously determines the state of all multichain systems at a single MasterChain block. +There is a necessity for the synchronization of message routing and transaction execution. In other words, nodes in the network need a way to fix some 'point' in a multichain state and reach a consensus about that state. In TON, a special chain called **MasterChain** is used for that purpose. Blocks of MasterChain contain additional information, like the latest block hashes, about all other chains in the system, thus any observer unambiguously determines the state of all multichain systems at a single MasterChain block. + +## See also +- [Smart contract addresses](/v3/concepts/dive-into-ton/ton-blockchain/smart-contract-addresses/) \ No newline at end of file diff --git a/docs/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage.md b/docs/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage.md index 58f613ff16..af1061a817 100644 --- a/docs/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage.md +++ b/docs/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage.md @@ -1,7 +1,7 @@ import ConceptImage from '@site/src/components/conceptImage'; import ThemedImage from '@theme/ThemedImage'; -# Cells as Data Storage +# Cells as data storage Everything in TON is stored in cells. A cell is a data structure containing: @@ -55,6 +55,6 @@ TL-B for cells is the same as TL or ProtoBuf for byte-streams. If you want to know more details about cell (de)serialization, you could read [Cell & Bag of Cells](/v3/documentation/data-formats/tlb/cell-boc) article. -## See Also +## See also * [TL-B Language](/v3/documentation/data-formats/tlb/tl-b-language) diff --git a/docs/v3/concepts/dive-into-ton/ton-blockchain/security-measures.md b/docs/v3/concepts/dive-into-ton/ton-blockchain/security-measures.md index 19102e4000..6c4300d922 100644 --- a/docs/v3/concepts/dive-into-ton/ton-blockchain/security-measures.md +++ b/docs/v3/concepts/dive-into-ton/ton-blockchain/security-measures.md @@ -1,4 +1,4 @@ -# Security Audits +# Security audits The security of the TON Blockchain ecosystem is of utmost importance. Below is a summary of completed audits for key components of the TON Blockchain, conducted by renowned auditing firms. @@ -13,7 +13,7 @@ The core blockchain modules were audited to ensure the robustness and security. - [CertiK: TON Blockchain Audit Report](https://docs.ton.org/audits/TON_Blockchain_CertiK.pdf) - [CertiK: TON Masterchain Contracts Formal Verification](https://docs.ton.org/audits/TON_Blockchain_Formal_Verification_CertiK.pdf) -## TON Blockchain Library (tonlib) +## TON blockchain library (tonlib) Zellic conducted a security assessment for TON from October 16th to November 17th, 2023. During this engagement, Zellic reviewed Tonlib’s code for security vulnerabilities, design issues, and general weaknesses in security posture. @@ -39,5 +39,5 @@ TVM Upgrade 2023.07 were analyzed for security and potential vulnerabilities. --- -## Bug Bounty Program +## Bug bounty program To further enhance the security of the TON ecosystem, we encourage security researchers and developers to participate in the [TON Blockchain Bug Bounty Program](https://github.com/ton-blockchain/bug-bounty). diff --git a/docs/v3/concepts/dive-into-ton/ton-blockchain/sharding.md b/docs/v3/concepts/dive-into-ton/ton-blockchain/sharding.md index e534b5fd95..706747d5d9 100644 --- a/docs/v3/concepts/dive-into-ton/ton-blockchain/sharding.md +++ b/docs/v3/concepts/dive-into-ton/ton-blockchain/sharding.md @@ -1,6 +1,4 @@ -# Sharding in the TON Blockchain - -[//]: # (TODO, this is from gpt) +# Sharding in TON The TON Blockchain employs advanced sharding mechanisms to enhance scalability and performance, allowing it to efficiently process a massive number of transactions. 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. @@ -19,7 +17,7 @@ These accountchains are then aggregated into shardchain blocks, facilitating eff 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. -## See Also +## See also * [Shards Dive In](/v3/documentation/smart-contracts/shards/shards-intro) * [# Infinity Sharding Paradigm](/v3/documentation/smart-contracts/shards/infinity-sharding-paradigm) diff --git a/docs/v3/concepts/dive-into-ton/ton-blockchain/smart-contract-addresses.md b/docs/v3/concepts/dive-into-ton/ton-blockchain/smart-contract-addresses.md index 719c4f6b7d..6c580a353d 100644 --- a/docs/v3/concepts/dive-into-ton/ton-blockchain/smart-contract-addresses.md +++ b/docs/v3/concepts/dive-into-ton/ton-blockchain/smart-contract-addresses.md @@ -1,55 +1,83 @@ -# Smart Contract Addresses - -[//]: # (TODO, this is gpt) +# Smart contract addresses 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**. -## Address Components +## Address components Each address on TON consists of two main components: - **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). - **Account ID**: A unique identifier for the contract, generally 256 bits in length for the Masterchain and Basechain. -## Raw vs. User-Friendly Addresses +## Address states -### Raw Address -A **raw address** contains only the basic elements: -- **Workchain ID** (e.g., `-1` for Masterchain) -- **Account ID**: A 256-bit unique identifier +Each address on TON can be in one of the following states: +- **Nonexist**: The address has no data (initial state for all addresses). +- **Uninit**: The address has a balance but no smart contract code. +- **Active**: The address is live with smart contract code and balance. +- **Frozen**: The address is locked due to storage costs exceeding its balance. -Example: -`-1:fcb91a3a3816d0f7b8c2c76108b8a9bc5a6b7a55bd79f8ab101c52db29232260` +## Address formats -However, raw addresses have two main issues: -1. They lack built-in error checking, meaning a mistake in copying can lead to loss of funds. -2. They do not support additional features like bounceable/non-bounceable flags. +A TON address uniquely identifies a contract in the blockchain, indicating its workchain and original state hash. [Two standard formats](/v3/documentation/smart-contracts/addresses#raw-and-user-friendly-addresses) are used: **raw** (workchain and HEX-encoded hash separated by the ":" character) and **user-friendly** (base64-encoded with certain flags). + +``` +User-friendly: EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF +Raw: 0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e +``` -### User-Friendly Address +## User-friendly address -A **user-friendly address** solves these problems by incorporating: -1. **Flags**: Indicates if the address is bounceable (for contracts) or non-bounceable (for wallets). -2. **Checksum**: A 2-byte error-checking mechanism (CRC16) that helps detect errors before sending. +A **user-friendly address** designed for blockchain users with features: +1. **Flags**: Indicates if the address is bounceable for contracts or non-bounceable for wallets. +2. **Checksum**: A 2-byte error-checking mechanism CRC16 that helps detect errors before sending. 3. **Encoding**: Transforms the raw address into a readable, compact form using base64 or base64url. -For example, the same raw address can be converted into a user-friendly address like: -`kf/8uRo6OBbQ97jCx2EIuKm8Wmt6Vb15+KsQHFLbKSMiYIny` (base64) +Example: `EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF` (base64) User-friendly addresses make transactions safer by preventing errors and allowing the return of funds in case of failed transactions. -## Address States +### User-friendly address flags -Each address on TON can be in one of the following states: -- **Nonexist**: The address has no data (initial state for all addresses). -- **Uninit**: The address has a balance but no smart contract code. -- **Active**: The address is live with smart contract code and balance. -- **Frozen**: The address is locked due to storage costs exceeding its balance. +Two flags are defined: **bounceable**/**non-bounceable** and **testnet**/**any-net**. They can be easily detected by looking at the first letter of the address because it stands for the first 6 bits in address encoding, and flags are located there according to [TEP-2](https://github.com/ton-blockchain/TEPs/blob/master/text/0002-address.md#smart-contract-addresses): + +| Address beginning | Binary form | Bounceable | Testnet-only | +|:-----------------:|:-----------:|:----------:|:------------:| +| E... | 000100.01 | yes | no | +| U... | 010100.01 | no | no | +| k... | 100100.01 | yes | yes | +| 0... | 110100.01 | no | yes | + +:::tip +The Testnet-only flag doesn't have representation in blockchain at all. The non-bounceable flag makes a difference only when used as the destination address for a transfer: in this case, it [disallows bounce](/v3/documentation/smart-contracts/message-management/non-bounceable-messages) for a message sent; the address in blockchain, again, does not contain this flag. +::: + +``` +default bounceable: EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF +urlSafe: EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff+W72r5gqPrHF +non-bounceable: UQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPuwA +Testnet: kQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPgpP +non-bounceable, Testnet: 0QDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPleK +``` + +## Raw address +A **raw address** contains only the basic elements: +- **Workchain ID** (e.g., `-1` for Masterchain) +- **Account ID**: A 256-bit unique identifier + +Example: +`-1:fcb91a3a3816d0f7b8c2c76108b8a9bc5a6b7a55bd79f8ab101c52db29232260` + +However, raw addresses have two main issues: +1. They lack built-in error checking, meaning a mistake in copying can lead to loss of funds. +2. They don't support additional features like bounceable/non-bounceable flags. -## Converting Between Address Formats +## Converting between address formats -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. +Convert between raw and user-friendly addresses use [ton.org/address](https://ton.org/address/). -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](/v3/documentation/smart-contracts/addresses). +For more details refhandlingl guide in [Addresses Documentation](/v3/documentation/smart-contracts/a/). -## See Also +## See also -* [Smart Contracts Addresses Documentation](/v3/documentation/smart-contracts/addresses) +- [Explorers in TON](/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton/) +- [Smart contracts addresses documentation](/v3/documentation/smart-contracts/addresses/) diff --git a/docs/v3/concepts/dive-into-ton/ton-blockchain/ton-networking.md b/docs/v3/concepts/dive-into-ton/ton-blockchain/ton-networking.md index a8e96ff815..a740fa6623 100644 --- a/docs/v3/concepts/dive-into-ton/ton-blockchain/ton-networking.md +++ b/docs/v3/concepts/dive-into-ton/ton-blockchain/ton-networking.md @@ -1,4 +1,4 @@ -# TON Networking +# TON networking The TON Project uses its own peer-to-peer network protocols. @@ -19,9 +19,9 @@ The TON Project uses its own peer-to-peer network protocols. blockchain itself, thus providing more possibilities and flexibility for creating new services in the TON Ecosystem. -## See Also +## See also -* [ADNL Protocol](/v3/documentation/network/protocols/adnl/overview) -* [Overlay Subnetworks](/v3/documentation/network/protocols/overlay) -* [RLDP Protocol](/v3/documentation/network/protocols/rldp) -* [TON DHT Service](/v3/documentation/network/protocols/dht/ton-dht) +* [ADNL Protocol](/v3/documentation/network/protocols/adnl/overview/) +* [Overlay Subnetworks](/v3/documentation/network/protocols/overlay/) +* [RLDP Protocol](/v3/documentation/network/protocols/rldp/) +* [TON DHT Service](/v3/documentation/network/protocols/dht/ton-dht/) diff --git a/docs/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton.mdx b/docs/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton.mdx index ab64fa1b97..48e64ea829 100644 --- a/docs/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton.mdx +++ b/docs/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton.mdx @@ -2,11 +2,11 @@ import Player from '@site/src/components/player' # Explorers in TON -In this article, we will consider TON explorers, their capabilities and features from the point of view of the developer. +This article will consider TON explorers and their capabilities and features from the user's perspective. ## What is an explorer? -An explorer is a website that allows you to view information in a blockchain, such as the account balance, transaction history, blocks, etc. +An explorer is a website that allows you to view information in a blockchain, such as the account balance, transaction history, and blocks. @@ -18,153 +18,143 @@ Among TON explorers, you can distinguish several categories: - With extended information for developers - Specialized -This division into categories is largely conditional and one explorer can belong to several categories at the same time. So let's not pay too much attention to this. - - -## Address Alias in Explorers - -Make your service address more user-friendly by using an address alias. Create Pull Requests (PRs) according to the provided guidelines: - -- [tonkeeper/ton-assets](https://github.com/tonkeeper/ton-assets) - Tonviewer.com alias -- [catchain/address-book](https://github.com/catchain/address-book)- Tonscan.org alias +This division into categories is mainly conditional, and one explorer can belong to several categories simultaneously. So let's not pay too much attention to this. ## General functionality -Let's start with the general functionality that is present in all explorers. +Blockchain explorers allow you to view and search the blockchain, similarly to how you might use a banking app to check transaction history and account balances. They provide a user-friendly interface to access real-time data about blockchain transactions, blocks, and addresses. -Almost all explorers have the ability to find out information about balances, transaction history and information about the smart contract, if deployed on the address. +Just as you use a banking app to track where your money goes, who sends you payments, and when transactions occur, blockchain explorers let you see this information for digital assets on the blockchain. They are essential for transparency, allowing anyone to verify transactions independently, see the flow of cryptocurrency, and analyze the activity on the blockchain. -Next, we will consider several explorers that can be attributed to each of these categories. +Typically, an explorer allows you to find a transaction or an account by its identifier. Some explorers also support DNS extensions or their own [address book](/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton#address-alias-in-explorers), which adds a human-readable label to a specific account. Example: [TON Foundation](https://tonviewer.com/UQAFmjUoZUqKFEBGYFEMbv-m61sFStgAfUR8J6hJDwUU04VW). -## TON Scan.org +## Native explorers -Good explorer for everyday use. It provides a comprehensive view of the TON Blockchain, allowing users to search for transactions, addresses, blocks, and more. Any search is performed against the public [address book](https://github.com/catchain/tonscan/blob/master/src/addrbook.json) (TON Foundation, OKX and etc.) +### Tonscan -### Features +It is a good explorer for everyday use. It provides a comprehensive view of the TON Blockchain, allowing users to search for transactions, addresses, blocks, and more. -- **Convenient for everyday use** -- Convenient for developers -- TON DNS support -- Contract types -- Contract disassembler - -### Links +- Mainnet: [tonscan.org](https://tonscan.org/) +- Testnet: [testnet.tonscan.org](https://testnet.tonscan.org/) -- URL: https://tonscan.org/ -- Testnet URL: https://testnet.tonscan.org/ +#### Features -## TON Scan.com +- Convenient for everyday use and developers +- Advanced jetton and nominator pools pages for users +- Contract types and disassembler +- User-friendly search uses DNS and [address book](https://github.com/catchain/address-book) labels. -### Features -- Transaction aggregation analytics -- Transaction Traces +### Tonviewer -### Links +It is a good explorer for everyday use with a balanced UI for users and developers. -- URL: https://tonscan.com/ +- Mainnet: [tonviewer.com](https://tonviewer.com/) +- Testnet: [testnet.tonviewer.com](https://testnet.tonviewer.com/) -## Ton Whales Explorer +#### Features -This explorer is more oriented towards developers than ordinary users. +- Convenient for everyday use and developers +- Advanced information for developers with traces +- Contract types and disassembler +- User-friendly search uses DNS and [tonkeeper/ton-assets](https://github.com/tonkeeper/ton-assets) labels. -### Features +### Tonscan by Bastion -- **Convenient for developers** -- Contract types -- Contract disassembler +- Mainnet: [tonscan.com](https://tonscan.com/) -### Links +#### Features -- URL: https://tonwhales.com/explorer +- Transaction aggregation analytics +- Transaction traces -## Tonviewer Explorer -This explorer is the newest and has its own unique features. -For example, Trace. This feature allows you to see the entire sequence of transactions between smart contracts, even if subsequent transactions do not contain your address. +### DTON -Transaction information is not as detailed as, for example, on TON Whales. +DTON is another explorer for developers. It provides a lot of information about transactions in a convenient form. -### Features +It also has a feature that allows you to see the computation phase of the transaction step by step. -- Convenient for developers -- Convenient for everyday use -- Jetton transaction history -- **Trace** -- TON DNS support +- Mainnet: [dton.io](https://dton.io/) -### Links +#### Features -- URL: https://tonviewer.com/ -- Testnet URL: https://testnet.tonviewer.com/ +- Convenient for developers +- Extended information about the computation phase +- Contract types and disassembler -## TON NFT EXPLORER +### Ton Whales explorer -This explorer specializes in NFTs, but it can also be used as a regular explorer. + Explorer for developers. -When viewing the wallet address, you can find out which NFT it stores and, when viewing the NFT, you can find out the metadata, collection address, owner and transaction history. +- Mainnet: [tonwhales.com/explorer](https://tonwhales.com/explorer) -### Features +#### Features - Convenient for developers -- Contract types -- **Specialized in NFT** +- Contract types and disassembler +- Simple and convenient validator details -### Links -- URL: https://explorer.tonnft.tools/ -- Testnet URL: https://testnet.explorer.tonnft.tools/ +### TON NFT EXPLORER -## DTON +This explorer specializes in NFTs but is also suitable as a regular explorer. -DTON is another explorer for developers. It provides a lot of information about transactions in a convenient form. +- Mainnet: [explorer.tonnft.tools](https://explorer.tonnft.tools/) +- Testnet: [testnet.explorer.tonnft.tools](https://testnet.explorer.tonnft.tools/) -Also, it has a feature that allows you to see the computation phase of the transaction step by step. +When viewing the wallet address, you can find out which NFT it stores, and when viewing the NFT, you can find the metadata, collection address, owner, and transaction history. -### Features +#### Features - Convenient for developers -- Extended information about the computation phase +- Specialized in NFT - Contract types -- Contract disassembler -### Links +## Crosschain explorers -- URL: https://dton.io/ +### TON NFTscan -## TON NFTscan + This explorer is designed explicitly for Non-Fungible Tokens (NFTs) on the TON Blockchain. It allows users to explore, track, and verify NFT transactions, contracts, and metadata. -This explorer is specifically designed for Non-Fungible Tokens (NFTs) on the TON Blockchain. It allows users to explore, track, and verify NFT transactions, contracts, and metadata. +- Mainnet: [ton.nftscan.com](https://ton.nftscan.com/) -### Features +#### Features - Convenient for regular users -- Useful information for traders, such as daily volume - NFT collection ranking +- Useful information for traders, such as daily volume + -### Links +## Analytics explorers -- URL: https://ton.nftscan.com/ +### TonStat -## TonStat +- Mainnet: [tonstat.com](https://www.tonstat.com/) -Displays various statistics such as number of registered network addresses and wallets, volume of Toncoin burned, volume of Toncoin staked, volume of NFTs issued, number of validators and a number of other metrics. +It displays various statistics, such as the number of registered network addresses and wallets, the volume of Toncoin burned, the volume of Toncoin staked, the volume of NFTs issued, the number of validators, and other metrics. -### Features +#### Features - Convenient for regular users -- Useful information for traders, such as daily volume - DeFi information +- Useful information for traders, such as daily volume -### Links +## Address alias in explorers + +Make your service address more user-friendly by using an address alias. Create Pull Requests (PRs) according to the provided guidelines: + +- [tonkeeper/ton-assets](https://github.com/tonkeeper/ton-assets) - Tonviewer.com alias +- [catchain/address-book](https://github.com/catchain/address-book)- Tonscan.org alias +- [ton-labels](https://github.com/ton-studio/ton-labels) - Public dataset of labeled TON blockchain addresses -- URL: https://www.tonstat.com/ -## Want to be in this list? +## Want to be on this list? -Please, write to one of the [maintainers](/v3/contribute/maintainers). +Please write to one of the [maintainers](/v3/contribute/maintainers). -## References +## See also +- [TON wallet apps](/v3/concepts/dive-into-ton/ton-ecosystem/wallet-apps/) - [ton.app/explorers](https://ton.app/explorers) - [Awesome TON repository](https://github.com/ton-community/awesome-ton) diff --git a/docs/v3/concepts/dive-into-ton/ton-ecosystem/nft.md b/docs/v3/concepts/dive-into-ton/ton-ecosystem/nft.md index e661ad6aef..21157eb144 100644 --- a/docs/v3/concepts/dive-into-ton/ton-ecosystem/nft.md +++ b/docs/v3/concepts/dive-into-ton/ton-ecosystem/nft.md @@ -1,80 +1,89 @@ --- --- -# NFT Use Cases +# NFT use cases -NFTs, or non-fungible tokens, are a type of digital asset that is unique, and cannot be replaced by another identical asset. This article describes the approaches and already implemented use cases of NFTs in TON Blockchain. +After reading this article, you'll understand why NFTs are helpful and how to use them in real life. -After reading this article, you will understand why are NFTs helpful and how you can use them in one of your projects. +## Introduction -## Item ownership +**Non-fungible token (NFT)** is a type of unique digital asset that can't be replaced by another identical asset. This article describes the approaches and use cases of NFTs already implemented in TON Blockchain. -Non-fungible tokens are mostly known as cool pictures that you can buy and sell on NFT marketplaces like OpenSea or [getgems.io](https://getgems.io). +### Item ownership -NFT pictures and collections are funny and help people understand the concept of blockchain-based ownership. However, in the long-term, the NFT focus should shift beyond this to illustrate their wide variety of potential use cases. +Non-fungible tokens are mostly known as cool pictures that can be bought and sold on NFT marketplaces like OpenSea or [getgems.io](https://getgems.io). -## Support an artist +NFT pictures and collections are funny and help people understand the concept of blockchain-based ownership. However, in the long term, the NFT focus should shift beyond this to illustrate its wide variety of potential use cases. + +In 2024, Telegram introduced [gifts as NFT items](https://telegram.org/blog/wear-gifts-blockchain-and-more#move-gifts-to-the-blockchain). + +### Support an artist One of the initial motivations behind the development of NFTs was finding a way to support artists by buying their works packed as collections of NFTs stored in the blockchain. -In this way, artists could make money from selling new works and also from the royalties they would receive after the NFT was later resold on the market. +In this way, artists could make money by selling new works and receiving royalties from subsequent resales of the NFT on the market. -This is one of the most common reasons why marketplaces like getgems.io or OpenSea are part of the essential infrastructure of any blockchain nowadays. +This use case is one of the most common reasons why marketplaces like getgems.io or OpenSea are part of the essential infrastructure of any blockchain nowadays. -## Accounts as NFTs +### Accounts as NFTs -In November, the Telegram team launched [Fragment](https://fragment.com/) marketplace, where anyone can buy and sell Telegram usernames or Anonymous Numbers backed by an NFT on the TON Blockchain. +In November, the Telegram team launched the [Fragment](https://fragment.com/) marketplace. This marketplace allows anyone to buy and sell Telegram usernames or Anonymous Numbers backed by an NFT on the TON Blockchain. -Moreover, in December the Telegram team released [No-SIM sign-up](https://telegram.org/blog/ultimate-privacy-topics-2-0#sign-up-without-a-sim-card). You can buy a **virtual phone number** as an NFT to sign up in the Telegram Messenger and ensure that your privacy is secured by the TON Blockchain. +Moreover, in 2022, the Telegram team released [No-SIM sign-up](https://telegram.org/blog/ultimate-privacy-topics-2-0#sign-up-without-a-sim-card). You can buy a virtual phone number as an NFT to sign up in Telegram Messenger and ensure that your privacy is secured by the TON Blockchain. -## Domain as an NFT +### Domain as an NFT -The TON DNS service works fully on-chain. If you want to own a domain in the decentralized web backed by TON like `mystore.ton` you need to buy the NFT domain on [DNS marketplace](https://dns.ton.org/) for your wallet and pay renting fee for storing and processing data in the blockchain. +The TON DNS service works fully on-chain. If you want to own a domain in the decentralized web backed by TON like `mystore.ton` you need to buy the NFT domain on [DNS marketplace](https://dns.ton.org/) for your wallet and pay a rental fee for storing and processing data in the blockchain. -The NFT usernames bought on Fragment can also be used for TON DNS to bind them to your wallet and use your username.t.me NFT as a wallet address. +You can also use the NFT usernames bought on Fragment for TON DNS to bind them to your wallet and use your `username.t.me` NFT as a wallet address. ### NFT as an address for your wallet -Everyone in crypto understands the idea of unique address of wallet like `Egbt...Ybgx`. +Everyone in crypto understands the idea of a unique wallet address like `Egbt...Ybgx`. But if you want to receive money from your mom, it's a useless approach to blockchain mass adoption! That's why a wallet backed by the domain `billy.ton` would work better for users outside of crypto. -The [Tonkeeper](https://tonkeeper.com/) wallet has already implemented this approach. You can check it out now. +Various TON wallet apps, like [Tonkeeper](https://tonkeeper.com/) wallet, have already implemented this approach. You can go ahead and check it out now. -## Ticket as an NFT +### Ticket as an NFT NFT tickets provide an excellent solution for verifying access to events, like concerts or conferences. Owning an NFT ticket offers several unique advantages: -First and foremost, NFT tickets cannot be forged or copied, eliminating the possibility of fraudulent sale of fake tickets. This ensures that buyers can trust the authenticity of the ticket and the legitimacy of the seller, giving them confidence in what they're paying for. +First and foremost, NFT tickets cannot be forged or copied, eliminating the possibility of fraudulently selling fake tickets. This NFT property ensures that buyers can trust the ticket's authenticity and the seller's legitimacy, giving them confidence in what they're paying for. -Secondly, NFT tickets open up exciting opportunities for collecting. As the owner of an NFT ticket, you can store it in your digital wallet and have access to a whole collection of tickets from various events. This creates a new form of aesthetic and financial satisfaction for music and art lovers. +Secondly, NFT tickets open up exciting opportunities for collecting. As the owner of an NFT ticket, you can store it in your digital wallet and have access to a whole collection of tickets from various events. This opportunity creates a new aesthetic and financial satisfaction for music and art lovers. -Thirdly, NFT tickets provide accessibility and convenience. They can be easily transferred using digital wallets, freeing users from the hassle of physically receiving or sending tickets. The process of exchanging tickets with friends or purchasing them on the secondary market becomes simpler and more convenient. +Thirdly, NFT tickets provide accessibility and convenience. Users can quickly transfer NFTs using digital wallets, which eliminates the hassle of physically receiving or sending tickets. The process of exchanging tickets with friends or purchasing them on the secondary market becomes simpler and more convenient. -Additionally, owning an NFT ticket can come with extra benefits and special privileges. Some artists or organizers may offer NFT ticket holders exclusive backstage access, meet-and-greets with artists, or other bonuses, adding to the unique cultural experience for NFT ticket holders. +Additionally, owning an NFT ticket can include extra benefits and special privileges. Some artists or organizers may offer NFT ticket holders exclusive backstage access, meet-and-greets with artists, or other bonuses, adding to the unique cultural experience for NFT ticket holders. -## Authorization token as an NFT +### Authorization token as an NFT Using NFTs as authorization tokens introduces a revolutionary approach to granting access rights and permissions. -NFT tokens ensure elevated security and cannot be easily copied or forged. This eliminates the risk of unauthorized access or fake authentication, providing reliable authentication. +NFT tokens ensure elevated security and cannot be easily copied or forged. This eliminates the risk of unauthorized access or fake authentication and provides reliable authentication. + +Furthermore, thanks to their transparency and traceability, the authenticity and ownership of an NFT authorization token unlock easy verification. This feature ensures convenient access to various platforms, services, or restricted content. + +It's also worth mentioning that NFTs provide flexibility and adaptability in managing permissions. Since you can programmatically encode NFTs with specific access rules or attributes, they can adapt to different authorization requirements. This flexibility allows for fine-grained control over access levels, granting or revoking permissions as needed, which can be particularly valuable in scenarios that require hierarchical access or temporary authorization restrictions. -Furthermore, thanks to their transparency and traceability, the authenticity and ownership of an NFT authorization token can be easily verified. This enables quick and efficient verification, ensuring convenient access to various platforms, services, or restricted content. +One of the services currently offering NFT authentication is [Playmuse](https://playmuse.org/), a media service built on the TON blockchain. This service aims to attract Web3 musicians and other creators. -It is also worth mentioning that NFTs provide flexibility and adaptability in managing permissions. Since NFTs can be programmatically encoded with specific access rules or attributes, they can adapt to different authorization requirements. This flexibility allows for fine-grained control over access levels, granting or revoking permissions as needed, which can be particularly valuable in scenarios that require hierarchical access or temporary authorization restrictions. +Owners of NFTs from Playmuse gain access to the holders' chat. Participating in this chat allows you to influence the service's development direction, vote on various initiatives, and receive early access to presales and NFT auctions featuring renowned creators. -One of the services currently offering NFT authentication is [Playmuse](https://playmuse.org/), a media service built on the TON blockchain. This service aims to attract Web3 musicians as well as other creators. +A Telegram bot facilitates access to the chat by verifying the presence of a Playmuse NFT in the user's wallet. -Owners of NFTs from Playmuse gain access to the holders chat. Being a participant in this chat provides opportunity to influence the development direction of the service, vote on various initiatives, and receive early access to presales and NFT auctions featuring renowned creators. +It is important to note that this is just one example. As TON Ecosystem evolves, new services and technologies for authentication via NFTs may emerge. Keeping up with the latest developments in the TON space can help identify other platforms or open-source projects that provide similar authentication capabilities. -Access to the chat is facilitated through a Telegram bot, which verifies the presence of a Playmuse NFT in the user's wallet. +### NFT as a virtual asset in games -It is important to note that this is just one example, and as the TON ecosystem evolves, new services and technologies for authentication via NFTs may emerge. Keeping up with the latest developments in the TON space can help identify other platforms or open-source projects that provide similar authentication capabilities. +NFT integrated into a game allows players to own and trade in-game items in a verifiable and secure way, which adds an extra layer of value and excitement to the game. -## NFT as a Virtual Asset in Games +## See also -NFT integrated to a game allows players to own and trade in-game items in a way that is verifiable and secure, which adds an extra layer of value and excitement to the game. +- [TON wallet apps](/v3/concepts/dive-into-ton/ton-ecosystem/wallet-apps/) +- [Explorers in TON](/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton/) diff --git a/docs/v3/concepts/dive-into-ton/ton-ecosystem/wallet-apps.mdx b/docs/v3/concepts/dive-into-ton/ton-ecosystem/wallet-apps.mdx index 616d4d0ec3..5f81f54f62 100644 --- a/docs/v3/concepts/dive-into-ton/ton-ecosystem/wallet-apps.mdx +++ b/docs/v3/concepts/dive-into-ton/ton-ecosystem/wallet-apps.mdx @@ -1,6 +1,6 @@ import Player from '@site/src/components/player' -# Wallet Apps +# Wallet apps ## Overview @@ -10,75 +10,51 @@ This article describes wallets from a developmental perspective. The end goal is

-If you want to find a wallet to install, open [ton.org/wallets](https://ton.org/wallets). +Learn a [ton.org/wallets](https://ton.org/wallets) catalog for more wallet apps. -## Non-Custodial Software (Hot) Wallets +## Non-custodial software wallets (hot) -:::info -A Software wallet, more often known as a hot wallet, operates as software on a host device and they store your private keys within its interface. Mostly, these wallets are non-custodial, meaning they give you custody of your keys. -::: +Non-custodial wallets provide users with complete control over their assets. The private keys are stored exclusively by the wallet owner, and access is secured through a seed phrase—a unique set of 12 or 24 words. -Here are some non-custodial wallets for TON Blockchain: +A software wallet, often known as a hot wallet, operates as software on a host device and stores your private keys in a device storage, such as a smartphone or laptop. -* [TON Wallet](https://chrome.google.com/webstore/detail/ton-wallet/nphplpgoakhhjchkkhmiggakijnkhfnd) — Multiplatform (iOS, Android, macOS, Linux, Windows) classic wallets of TON Ecosystem developed by TON Foundation. -* [Tonkeeper](https://tonkeeper.com/) — an open-source multi-platform (iOS, Android, Firefox, Chrome) wallet with a great user base. -* [MyTonWallet](https://mytonwallet.io/) — an open-source browser web wallet and a browser extension wallet for TON. -* [Tonhub](https://tonhub.com/) — an open-source (iOS, Android) alternative mobile phone wallet with advanced features (TON Whales Staking UI). -* [OpenMask](https://www.openmask.app/) — an open-source Chrome extension wallet with biometric authentication. - -### TON Wallet -TON Wallet was the first step in mass-adoption blockchain technology available to ordinary users. It demonstrates how a wallet should work on TON Blockchain. +Here are some non-custodial wallets for TON Blockchain. -| | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|              ![TON wallet](/img/docs/wallet-apps/TonWallet.png?raw=true)                                 | +#### For users: +* [Tonkeeper](https://tonkeeper.com/) — an open-source multiplatform wallet with a great user base. Platforms: iOS, Android, Firefox, Chrome. +* [MyTonWallet](https://mytonwallet.io/) — an open-source multiplatform wallet for TON. Platforms: iOS, Android, Firefox, Chrome. +* [Tonhub](https://tonhub.com/) — an open-source alternative mobile phone wallet with advanced banking features. Platforms: iOS, Android. - -#### Pros and Cons -- ✅ The original wallet developed by TON Foundation. TON Wallet works according to the vision of TON Blockchain's core developers. -- ✅ ADNL connection implemented. -- ✅ Multi-platform architecture support. It works in Linux, Windows, macOS, iOS, Android and as well as a Chrome plugin. -- ✅ [Bug bounty program](https://github.com/ton-blockchain/bug-bounty) -- ❌ Rarely updates. This wallet does not have not all up-to-date features (TON DNS addresses, and the wallet-v4 contract isn't supported). -- ❌ The current UI is outdated and is worse than alternative wallets. - -#### Ton Wallet test environment - -To switch TON classic wallet to test environment, you should to open in browser with testnet parameter: - -#### Links -- [GitHub*](https://github.com/ton-blockchain/wallet-ios) - - > *TON Wallet clients for every supported OS placed in nearby repositories. +#### For developers: +* [TONDevWallet](https://github.com/TonDevWallet/TonDevWallet) - an open-source wallet for developers. +* [TON Wallet](https://chrome.google.com/webstore/detail/ton-wallet/nphplpgoakhhjchkkhmiggakijnkhfnd) — Classic wallet of TON Ecosystem developed by TON Foundation. Platforms: iOS, Android, macOS, Linux, Windows. +* [OpenMask](https://www.openmask.app/) — an open-source Chrome extension wallet. ### Tonkeeper -[Tonkeeper](https://tonkeeper.com/) - is the most downloaded and popular wallet, developed by the Tonkeeper team, and has active support from both users and developers. +[Tonkeeper](https://tonkeeper.com/) is a central wallet in the TON Ecosystem. The Tonkeeper team developed it and has active support from both users and developers. -| | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|              ![Tonkeeper](/img/docs/wallet-apps/Tonkeeper.png?raw=true)                                 | +Tonkeeper -#### Pros and Cons -- ✅ This app is most popular with users. -- ✅ Supports all up-to-date features including native NFT transfer between user wallets. -- ✅ Supports all major platforms, such as iOS and Android, but also works in popular browsers, such as Firefox or Chrome. -- ❌ Requires advanced skills to contribute to its source code. +#### Highlights +- This app is most popular with users. +- Supports all up-to-date features, including NFT and Token transfer between user wallets. +- It supports all major platforms, such as iOS and Android, but it also works on popular browsers like Firefox or Chrome. #### Tonkeeper test environment -##### Tonkeeper Mobile App +##### Tonkeeper mobile app -1. Create new regular wallet to claim Recovery Phrase, the 24 key words. +1. Create a new regular wallet to claim Recovery Phrase, the 24 keywords. 2. Go back to the Tonkeeper main screen. 3. Click on your wallet name at the top of the screen. -4. Push Add Wallet button in the bottom of screen. +4. Push the Add Wallet button at the bottom of the screen. 4. Select the Testnet Account option. 8. Enter the Recovery Phrase from step 1. -Now your testnet wallet is created and connected to your mainnet wallet. +Now, your Testnet wallet is created and connected to your Mainnet wallet. #### Links @@ -88,22 +64,16 @@ Now your testnet wallet is created and connected to your mainnet wallet. ### MyTonWallet +[MyTonWallet](https://mytonwallet.io/) is a feature-rich web wallet and browser extension for TON that supports tokens, NFT, TON DNS, TON Sites, TON Proxy, and TON Magic. -[MyTonWallet](https://mytonwallet.io/) - is the most feature-rich web wallet and browser extension for TON – with support of tokens, NFT, TON DNS, TON Sites, TON Proxy, and TON Magic. - - -| | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|               ![MyTonWallet](/img/docs/wallet-apps/MyTonWallet.png?raw=true)                                 | +Tonkeeper +#### Highlights - -#### Pros and Cons -- ✅ Has all basic features implemented. -- ✅ Unique feature - management of the official [Nominator Pool contract](https://github.com/ton-blockchain/nominator-pool) from the wallet UI. -- ✅ Multichain wallet that supports TRON Blockchain. -- ✅ Supports all major platforms (such as macOS, Linux and Windows) and also runs in Chrome as an extension. -- ❌ Requires advanced skills to contribute to its source code. +- Has all basic features implemented. +- Focus on the best UI for users. +- Multichain wallet that supports TRON Blockchain. +- Supports all major platforms and runs in Chrome as an extension. #### MyTonWallet test environment (browser, desktop, and mobile application) @@ -111,73 +81,98 @@ Now your testnet wallet is created and connected to your mainnet wallet. 2. Scroll down and click on the MyTonWallet application version. 3. In the pop-up window, select the environment. - #### Links - [GitHub](https://github.com/mytonwalletorg/mytonwallet) - [MyTonWallet Telegram](https://t.me/MyTonWalletRu) - - - ### Tonhub -[Tonhub](https://tonhub.com/) - is another fully-fledged TON wallet, that has basic up-to-date features support. Ton Whales are rapidly increasing the capabilities of the wallet. - -| | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|               ![Tonhub](/img/docs/wallet-apps/Tonhub.png?raw=true)                                 | +[Tonhub](https://tonhub.com/) is another fully-fledged TON wallet with basic, up-to-date features and banking. +Tonkeeper -#### Pros and Cons +#### Highlights -- ✅ Has own custom [Ton Nominator](https://github.com/tonwhales/ton-nominators) contract supported with Tonhub UI. -- ✅ Open-source wallet from the beginning of the existing application. -- ✅ [Bug bounty program](https://tonwhales.com/bounty). -- ❌ Doesn't have any kind of support for desktop platforms. -- ❌ Requires advanced skills to contribute to its source code. +- Has own custom [Ton Nominator](https://github.com/tonwhales/ton-nominators) contract supported with Tonhub UI. +- Open-source wallet from the beginning of the existing app. +- [Bug bounty program](https://tonwhales.com/bounty). #### Tonhub test environment -You will need to download separate application to connect to the Testnet. +You must download a separate Sandbox application to connect to the Testnet. #### Links - [GitHub](https://github.com/tonwhales/wallet) - [Sandbox iOS](https://apps.apple.com/app/ton-development-wallet/id1607857373) - [Sandbox Android](https://play.google.com/store/apps/details?id=com.tonhub.wallet) +### TONDevWallet + +TonDevWallet is a wallet designed to simplify the development process for the TON Blockchain. It provides extensive tools and features to streamline your TON development experience. + +#### Highlights +TonConnect Integration: TonDevWallet seamlessly integrates with TonConnect, allowing you to connect your wallet to TON-compatible websites easily. +- Store and manage multiple private keys within TonDevWallet, giving you the flexibility to access and control various accounts. +- Create multiple wallets to organize and manage different accounts for your TON development projects. +- Local transaction emulation lets you preview transaction results before executing them on the TON Blockchain. This feature helps you ensure the correctness of your transactions before submitting them to the blockchain. + +#### Links +- [GitHub](https://github.com/TonDevWallet/TonDevWallet) + +### TON Wallet + +TON Wallet was the first step in massively adopting blockchain technology, and it's now available to ordinary users. It demonstrates for developers how a wallet should work on the TON Blockchain. + +TON wallet + +#### Highlights +TON Wallet is the original wallet developed by the TON Core team. It demonstrates a development approach that corresponds to the TON Blockchain architecture. +- ADNL connection implemented. +- Multiplatform architecture support. It works in Linux, Windows, macOS, iOS, Android, and a Chrome plugin. +- [Bug bounty program](https://github.com/ton-blockchain/bug-bounty) + +#### Ton Wallet test environment + +To switch TON Wallet to the Testnet environment, you should open in the browser with the Testnet parameter: + +#### Links +- [GitHub](https://github.com/ton-blockchain/wallet-ios) + +:::info +TON Wallet clients for every supported OS placed in nearby repositories. +::: + ### OpenMask -[OpenMask](https://www.openmask.app/) - is the trailblazing tool enabling user interactions and experience in Web3 as a browser extension. +[OpenMask](https://www.openmask.app/) is a trailblazing tool that enables user interactions and experiences in Web3 as a browser extension. + +Tonkeeper -| | -|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|               ![OpenMask](/img/docs/wallet-apps/OpenMask.png?raw=true)                                 | +#### Highlights -#### Pros and Cons -- ✅ Convenient for developers to learn and create dApps via desktop without mobile devices. -- ✅ Unique functions such as multiple wallets, with detailed descriptions and examples in its documentation. -- ❌ Has almost no integration with dApps at the moment. -- ❌ Supports only browser extension platform. +- Convenient for developers to learn and create dApps via desktop without mobile devices. +- Unique functions, such as multiple wallets, with detailed descriptions and examples in its documentation. #### OpenMask test environment -To switch OpenMask between Mainnet and Testnet: you need to click on "mainnet/testnet" button on the top of the OpenMask's main screen and choose the network you need. +To switch OpenMask between Mainnet and Testnet, click the **mainnet/testnet** button at the top of the main screen and choose the network you need. #### Links - [GitHub](https://github.com/OpenProduct/openmask-extension) - [Documentation](https://www.openmask.app/docs/introduction) -## Non-Custodial Hardware (Cold) Wallets +## Non-custodial hardware wallets (cold) + +Non-custodial wallets provide users with complete control over their assets. The private keys are stored exclusively by the wallet owner, and access is secured through a seed phrase—a unique set of 12 or 24 words. -:::info A hardware wallet is a physical device that stores the private keys to your cryptocurrency funds away from the internet. Even if you make transactions with it, the wallet confirms the transactions in an offline environment. This process helps keep your private keys away from the risks of the internet at all times. -::: + ### Ledger -[Ledger](https://www.ledger.com/) hardware wallets with Ledger Live app. +[Ledger](https://www.ledger.com/) is a hardware wallet with a Ledger Live app. #### Links @@ -194,29 +189,20 @@ A hardware wallet is a physical device that stores the private keys to your cryp ## Custodial wallets -:::info -With a custodial wallet, user trusts somebody else to hold the wallet's private key. -::: +In custodial wallets, private keys are managed by a third party, such as a cryptocurrency exchange. This means that users delegate the storage and management of their assets to a trusted entity. + ### @wallet [@wallet](https://t.me/wallet) — a bot to send and receive or trade TON for real money using P2P in Telegram. Supports Telegram Mini App UI. - -| | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|               ![wallet](/img/docs/wallet-apps/Wallet.png?raw=true)                                 | - +Tonkeeper ### @cryptobot [@cryptobot](https://t.me/cryptobot) — A Telegram bot wallet for storing, sending and exchanging TON. - -| | -|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|               ![CryptoBot](/img/docs/wallet-apps/CryptoBot.png?raw=true)                                 | - +Tonkeeper #### Links for 3d-party integrations @@ -224,13 +210,10 @@ With a custodial wallet, user trusts somebody else to hold the wallet's private ### @tonRocketBot -[@tonRocketBot](https://t.me/tonRocketBot) - A Telegram bot wallet for storing, sending and exchanging TON. Supports Jetton trading as well. - +[@tonRocketBot](https://t.me/tonRocketBot) - A Telegram bot wallet for storing, sending, and trading TON assets. -| | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|               ![tonrocketbot](/img/docs/wallet-apps/tonrocketbot.png?raw=true)                                 | +Tonkeeper #### Links for 3d-party integrations @@ -238,7 +221,7 @@ With a custodial wallet, user trusts somebody else to hold the wallet's private - [Rocket pay docs](https://pay.ton-rocket.com/api/) -## Multi signature Wallets +## Multi-signature wallets ### Tonkey @@ -248,7 +231,8 @@ Tonkey is an advanced project that introduces multi-signature functionality to T - https://tonkey.app/ - [GitHub](https://github.com/tonkey-app) -## See Also +## See also +- [Explorers in TON](/v3/concepts/dive-into-ton/ton-ecosystem/explorers-in-ton/) - [What is blockchain? What is a smart contract? What is gas?](https://blog.ton.org/what-is-blockchain) -- [Types of Wallet Contracts](/v3/documentation/smart-contracts/contracts-specs/wallet-contracts) +- [Types of Wallet Contracts](/v3/documentation/smart-contracts/contracts-specs/wallet-contracts/) diff --git a/docs/v3/concepts/educational-resources.mdx b/docs/v3/concepts/educational-resources.mdx index 750318cd5f..d61b824079 100644 --- a/docs/v3/concepts/educational-resources.mdx +++ b/docs/v3/concepts/educational-resources.mdx @@ -1,10 +1,10 @@ import Button from '@site/src/components/button' -# Educational Resources +# Educational resources ### Courses -#### Blockchain Basics +#### Blockchain basics This course introduces blockchain basics, focusing on practical skills in the TON ecosystem. You will understand how blockchain functions and its diverse applications. @@ -34,9 +34,9 @@ Russian -#### TON Blockchain Development +#### TON Blockchain development -We're proud to present the __TON Blockchain Course__, which is a comprehensive guide to the TON Blockchain. The course is designed for developers who want to learn how to create smart contracts and decentralized applications on the TON Blockchain in engaging and interactive ways. +We're proud to present the __TON Blockchain course__, which is a comprehensive guide to the TON Blockchain. The course is designed for developers who want to learn how to create smart contracts and decentralized applications on the TON Blockchain in engaging and interactive ways. It consists of __9 modules__ and covers the basics of the TON Blockchain, the FunC programming language, and the TON Virtual Machine (TVM). @@ -66,8 +66,8 @@ Russian -## See Also +## See also * [TON Hello World](https://tonhelloworld.com/01-wallet/) * [TON Dev Study YouTube Channel](https://www.youtube.com/@TONDevStudy) -* [TON Dev Study YouTube Channel RU](https://www.youtube.com/@WikiMar) + diff --git a/docs/v3/concepts/glossary.md b/docs/v3/concepts/glossary.md index 474e15fe8c..53f0979db2 100644 --- a/docs/v3/concepts/glossary.md +++ b/docs/v3/concepts/glossary.md @@ -272,9 +272,9 @@ __________ **Mainnet** — the main network of a blockchain. -### Market cap (capitalization) +### Market cap -**Market cap (capitalization)** — the total value of a cryptocurrency’s combined number of tokens. +**Market capitalization (Market cap)** — the total value of a cryptocurrency’s combined number of tokens. ### Masterchain @@ -407,7 +407,7 @@ ________ ### TEP -**TEP** — [TON Enhancement Proposals](https://github.com/ton-blockchain/TEPs), a standard set of ways to interact with various parts of the TON ecosystem. +**TON Enhancement Proposals (TEP)**—a [standard set](https://github.com/ton-blockchain/TEPs) of ways to interact with various parts of the TON ecosystem. ### Testnet diff --git a/docs/v3/concepts/qa-outsource/auditors.mdx b/docs/v3/concepts/qa-outsource/auditors.mdx index 599a9463f5..90acb3b30e 100644 --- a/docs/v3/concepts/qa-outsource/auditors.mdx +++ b/docs/v3/concepts/qa-outsource/auditors.mdx @@ -1,6 +1,6 @@ import Button from '@site/src/components/button' -# Security Assurance Providers (SAP) +# Security assurance providers :::info Test your software with the following quality assurance providers. @@ -20,5 +20,5 @@ Find more TON Ecosystem auditors on [ton.app/audit](https://ton.app/audit). ## See Also * [TON Ecosystem Auditors](https://ton.app/audit) -* [Outsource Development](/v3/concepts/qa-outsource/outsource) * [TON Jobs](https://jobs.ton.org/jobs) +* [TON Talents](https://ton.org/en/talents) diff --git a/docs/v3/concepts/qa-outsource/outsource.mdx b/docs/v3/concepts/qa-outsource/outsource.mdx index 7125639aed..6efdb70827 100644 --- a/docs/v3/concepts/qa-outsource/outsource.mdx +++ b/docs/v3/concepts/qa-outsource/outsource.mdx @@ -1,8 +1,14 @@ import Button from '@site/src/components/button' -# Outsource Development -## Outsource Teams List + +# Outsource development + +:::danger +This page is outdated and will be deleted soon. Please, learn ecosystem developers on the [ton.org/en/talents](https://ton.org/en/talents). +::: + +## Outsource teams list Discover 3rd party development teams for your TON project @@ -146,28 +152,6 @@ Softstack is a leading service provider of comprehensive Web3 solutions, since 2 - [softstack.io](https://softstack.io/) - Telegram [@yannikheinze](https://t.me/yannikheinze) -## Add your team - -If you are fully prepared to become an outsourced agent for TON Ecosystem, you can promote your company by filling out our form or submitting a pull request. - - - - - - - -



- - -## See Also -* [Security Assurance Providers](/v3/concepts/qa-outsource/auditors) +## See also +* [Security Assurance Providers](/v3/concepts/qa-outsource/auditors/) diff --git a/docs/v3/contribute/README.md b/docs/v3/contribute/README.md index ccc40b4b70..4496caf08f 100644 --- a/docs/v3/contribute/README.md +++ b/docs/v3/contribute/README.md @@ -31,7 +31,9 @@ This documentation is written in English. Please refer to [localization program] ## Description -Please provide a brief description of the changes introduced in this pull request. Include any relevant issue numbers or links. +Brief description of the changes introduced in this pull request. Include any relevant issue numbers or links. + +Closes [link to issue]. ## Checklist diff --git a/docs/v3/contribute/content-standardization.mdx b/docs/v3/contribute/content-standardization.mdx index 0255bb33ad..412b4ed1f0 100644 --- a/docs/v3/contribute/content-standardization.mdx +++ b/docs/v3/contribute/content-standardization.mdx @@ -97,6 +97,23 @@ Read more about [smart contracts](/v3/documentation/smart-contracts/overview/) Read more about [smart contracts](/v3/documentation/smart-contracts/overview) ``` +### Article authors + +When citing articles by a specific author or organization, use the article's name as a link, followed by a dash and the author's name italicized. + + +#### Correct description: +```md +- [How to shard your TON smart contract and why](https://blog.ton.org/how-to-shard-your-ton-smart-contract-and-why-studying-the-anatomy-of-tons-jettons) — _Tal Kol_ +- [TON Teleport BTC Whitepaper](https://tgbtc.gitbook.io/docs/whitepaper/abstract) – _RSquad Blockchain Lab_ +``` + +#### Incorrect description: +```md +- [How to shard your TON smart contract and why](https://blog.ton.org/how-to-shard-your-ton-smart-contract-and-why-studying-the-anatomy-of-tons-jettons) +- [TON Teleport BTC Whitepaper](https://tgbtc.gitbook.io/docs/whitepaper/abstract) by RSquad Blockchain Lab +``` + ### See also links section Include related resources on your page in an H2 section titled `## See also`. @@ -171,8 +188,8 @@ If the transaction order isn't essential, omit their labels. This approach simpl

@@ -436,23 +453,6 @@ When using the abbreviated form of zero-knowledge rollup you should shorten zero - zK rollup - zk rollup -### Article authors - -When citing articles by a specific author or organization, use the article's name as a link, followed by a dash and the author's name italicized. - - -#### Correct description: -```md -- [How to shard your TON smart contract and why](https://blog.ton.org/how-to-shard-your-ton-smart-contract-and-why-studying-the-anatomy-of-tons-jettons) — _Tal Kol_ -- [TON Teleport BTC Whitepaper](https://tgbtc.gitbook.io/docs/whitepaper/abstract) – _RSquad Blockchain Lab_ -``` - -#### Incorrect description: -```md -- [How to shard your TON smart contract and why](https://blog.ton.org/how-to-shard-your-ton-smart-contract-and-why-studying-the-anatomy-of-tons-jettons) -- [TON Teleport BTC Whitepaper](https://tgbtc.gitbook.io/docs/whitepaper/abstract) by RSquad Blockchain Lab -``` - ## See also - [How to contribute](/v3/contribute/) - [Content standardization](/v3/contribute/content-standardization/) diff --git a/docs/v3/contribute/localization-program/how-it-works.md b/docs/v3/contribute/localization-program/how-it-works.md index 31ccf07486..bc76661ddb 100644 --- a/docs/v3/contribute/localization-program/how-it-works.md +++ b/docs/v3/contribute/localization-program/how-it-works.md @@ -2,46 +2,46 @@ ![how it works](/img/localizationProgramGuideline/localization-program.png) -The **TownSquare Labs Localization Program** comprises several key components. This chapter will provide an overview of how the program operates, helping you understand its workings and how to use it effectively. +The TownSquare Labs Localization Program comprises several key components. This chapter provides an overview of localization, helping you understand how it works and how to use it effectively. Within this system, we integrate several applications to function seamlessly as a unified program: - **GitHub**: Hosts the documentation, synchronizes docs from the upstream repository, and syncs translations to specific branches. - **Crowdin**: Manages translation processes, including translating, proofreading, and setting language preferences. - **AI Systems**: Utilizes advanced AI to assist translators, ensuring smooth workflow. -- **Customized Glossary**: Guides translators and ensures AI generates accurate translations based on the project’s context. Users can also upload their glossaries as needed. +- **Customized Glossary**: This glossary guides translators and ensures AI generates accurate translations based on the project’s context. Users can also upload their glossaries as needed. :::info -This guide won't cover the entire process in detail, but it will highlight the key components that make the TownSquare Labs Localization Program unique. You can explore the program further on your own. +This guide won't cover the entire process but will highlight the key components that make the TownSquare Labs Localization Program unique. You can explore the program further on your own. ::: -## GitHub Synchronization for Documentation and Translations +## GitHub synchronization for documentation and translations -Our repository utilizes several branches for managing documentation and translations. Below is a detailed explanation of the purpose and function of each special branch: +Our repository utilizes several branches to manage documentation and translations. Below is a detailed explanation of the purpose and function of each special branch: -### Branches Overview +### Branches overview - **`dev`** The `dev` branch runs GitHub Actions to handle synchronization tasks. You can find the workflow configurations in the [**`.github/workflows`**](https://github.com/TownSquareXYZ/ton-docs/tree/dev/.github/workflows) directory: - **`sync-fork.yml`**: This workflow synchronizes documentation from the upstream repository. It runs daily at 00:00. - - **`sync-translations.yml`**: This workflow synchronizes updated translations to the respective language branches for preview purposes on the corresponding language websites. + - **`sync-translations.yml`**: This workflow synchronizes updated translations to the respective language branches for preview purposes on the corresponding websites. - **`main`** - This branch stays in sync with the upstream repository through GitHub Actions running on the `dev` branch. It is also used for updating certain codes that we intend to propose to the original repository. + This branch stays in sync with the upstream repository through GitHub Actions, which runs on the `dev` branch. It also updates specific codes we intend to propose to the original repository. - **`l10n_main`** - This branch includes all changes from the `main` branch and translations from Crowdin. All modifications in this branch are periodically committed to the upstream repository by using a new sub-branch named `l10n_main_[some data]`. + This branch includes all changes from the `main` branch and translations from Crowdin. All modifications in this branch are periodically committed to the upstream repository using a new sub-branch named `l10n_main_[some data]`. - **`l10n_feat` or `l10n_feat_[specific functions]`** - This branch will include changes to code or documentation related to the translation system. Once all content is finalized, the changes in this branch will be merged into `l10_main`. + This branch will include changes to code or documentation related to the translation system. Once you finalize all content, the changes in this branch will be merged into `l10_main`. - **`[lang]_preview`** These branches are designated for specific language previews, such as `ko_preview` for Korean and `ja_preview` for Japanese. They allow us to preview the website in different languages. By maintaining these branches and using GitHub Actions, we efficiently manage the synchronization of our documentation and translation updates, ensuring that our multilingual content is always up to date. -## How to Set Up a New Crowdin Project +## How to set up a new crowdin project 1. Log in to your [**Crowdin account**](https://accounts.crowdin.com/login). 2. Click `Create new project` in the menu. @@ -69,41 +69,41 @@ By maintaining these branches and using GitHub Actions, we efficiently manage th - **preserve_hierarchy**: Maintains the GitHub directory structure on the Crowdin server. - **source** and **translation**: Specify the paths for the files to upload to Crowdin and where the translated files should be output. - Refer to [**our official config file**](https://github.com/TownSquareXYZ/ton-docs/blob/localization/crowdin.yml) for an example. - More details can be found in the [**Crowdin configuration documentation**](https://developer.crowdin.com/configuration-file/). + For an example, refer to the [**config file**](https://github.com/TownSquareXYZ/ton-docs/blob/localization/crowdin.yml). + Find more in the [**Crowdin configuration documentation**](https://developer.crowdin.com/configuration-file/). 6. Configure Crowdin to connect to your GitHub repo: 1. Click `Add Repository` and select `Source and translation files mode`. ![select-integration-mode](/img/localizationProgramGuideline/howItWorked/select-integration-mode.png) 2. Connect your GitHub account and search for the repo you want to translate. ![search-repo](/img/localizationProgramGuideline/howItWorked/search-repo.png) - 3. Select the branch on the left, which will generate a new branch where Crowdin will post the translations. + 3. Select the branch on the left to generate a new branch where Crowdin will post the translations. ![setting-branch](/img/localizationProgramGuideline/howItWorked/setting-branch.png) - 4. Choose the frequency for updating translations to your GitHub branch. Default settings can be kept for other configurations, then click save to enable the integration. + 4. Choose the frequency for updating translations to your GitHub branch, then click save to enable the integration. ![frequency-save](/img/localizationProgramGuideline/howItWorked/frequency-save.png) -Refer to the [**GitHub integration documentation**](https://support.crowdin.com/github-integration/) for more details. +Find more details in the [**GitHub integration documentation**](https://support.crowdin.com/github-integration/). 7. Finally, you can click the `Sync Now` button to sync the repo and translations whenever needed. ## Glossary -### What is a Glossary? +### What is a glossary? -Sometimes, AI translators can't recognize specific terms that shouldn't be translated. For instance, we don't want "Rust" translated when referring to the programming language. To prevent such mistakes, we use a glossary to guide translations. +Sometimes, AI translators can't recognize untranslatable and specific terms. For instance, we don't want "Rust" translated when referring to the programming language. To prevent such mistakes, we use a glossary to guide translations. -A **glossary** allows you to create, store, and manage project-specific terminology in one place, ensuring terms are translated correctly and consistently. +A **glossary** allows you to create, store, and manage project-specific terminology in one place, ensuring that terms are translated correctly and consistently. -You can check our [**ton-i18n-glossary**](https://github.com/TownSquareXYZ/ton-i18n-glossary) for reference. +You can reference our [**ton-i18n-glossary**](https://github.com/TownSquareXYZ/ton-i18n-glossary). ![ton-i18n-glossary](/img/localizationProgramGuideline/howItWorked/ton-i18n-glossary.png) -### How to Set Up a Glossary for a New Language? +### How to set up a glossary for a new language? Most translation platforms support glossaries. In Crowdin, after setting up a glossary, each term appears as an underlined word in the Editor. Hover over the term to see its translation, part of speech, and definition (if provided). ![github-glossary](/img/localizationProgramGuideline/howItWorked/github-glossary.png) ![crowdin-glossary](/img/localizationProgramGuideline/howItWorked/crowdin-glossary.png) -In DeepL, simply upload your glossary, and it will be used automatically during AI translation. +In DeepL, upload your glossary, which will be used automatically during AI translation. We have created [**a program for glossary**](https://github.com/TownSquareXYZ/ton-i18n-glossary) that auto-uploads updates. @@ -111,22 +111,24 @@ To add a term to the glossary: 1. If the English term already exists in the glossary, find the corresponding line and column for the language you want to translate, input the translation, and upload it. 2. To upload a new glossary, clone the project and run: - - `npm i` - - `npm run generate -- ` +```bash +npm i +``` +```bash +npm run generate -- +``` Repeat step 1 to add the new term. -**Simple and efficient, isn’t it?** - -## How to Take Advantage of AI Translation Copilot? +## How to take advantage of AI translation copilot? AI translation copilot helps break down language barriers with several advantages: - **Enhanced Consistency**: AI translations are based on up-to-date information, providing the most accurate and current translations. - **Speed and Efficiency**: AI translation is instantaneous, handling large volumes of content in real-time. -- **Robust Scalability**: AI systems continuously learn and improve, enhancing translation quality over time. With the provided glossary, AI translations can be tailored to the specific needs of different repositories. +- **Robust Scalability**: AI systems continuously learn and improve, enhancing translation quality over time. -To use AI translation in Crowdin (we use DeepL in our project): +We use DeepL for AI translation in our Crowdin project: 1. Select Machine Translation in the Crowdin menu and click edit on the DeepL line. ![select-deepl](/img/localizationProgramGuideline/howItWorked/select-deepl.png) 2. Enable DeepL support and input the DeepL Translator API key. @@ -138,7 +140,7 @@ To use AI translation in Crowdin (we use DeepL in our project): 4. In the repo, click Pre-translation and select via Machine Translation. ![pre-translation](/img/localizationProgramGuideline/howItWorked/pre-translation.png) -5. Choose DeepL as the Translation Engine, select the target languages, and select the files to translate. +5. Choose DeepL as the Translation Engine, select the target languages, and select the translated files. ![pre-translate-config](/img/localizationProgramGuideline/howItWorked/pre-translate-config.png) -That's it! Now you can take a break and wait for the pre-translation to complete. \ No newline at end of file +That's it! Now, you can take a break and wait for the pre-translation to complete. diff --git a/docs/v3/contribute/localization-program/how-to-contribute.md b/docs/v3/contribute/localization-program/how-to-contribute.md index caa9ca7885..dbc51eb0d9 100644 --- a/docs/v3/contribute/localization-program/how-to-contribute.md +++ b/docs/v3/contribute/localization-program/how-to-contribute.md @@ -1,58 +1,57 @@ # How to contribute -:::info -This page explains how to participate in localization program for TON documentation. -::: +This page explains how to participate in the localization program for TON documentation. ## Prerequisites -The **TownSquare Labs Localization Program** is open to everyone! Here are a few steps you need to take before you start contributing: +Localization contribution is open to everyone. Here are a few steps you need to take before you start contributing: -1. Log in to your [**Crowdin**](https://crowdin.com) account or sign up. +1. Log in to your [Crowdin](https://crowdin.com) account or sign up. 2. Select the language you want to contribute to. -3. Familiarize yourself with the [**How to Use Crowdin**](/v3/contribute/localization-program/how-to-contribute) guide and the [**Translation Style Guide**](/v3/contribute/localization-program/translation-style-guide) for tips and best practices. -4. Use machine translations to aid your work but do not rely solely on them. -5. All translation results can be previewed on the website one hour after they have been proofread. +3. Familiarize yourself with the [How to use crowdin](/v3/contribute/localization-program/how-to-contribute/) guide and the [Translation style guide](/v3/contribute/localization-program/translation-style-guide/) for tips and best practices. +4. Use machine translations to aid your work, but do not rely solely on them. +5. Preview all translation results on the website after proofreading. + +:::info +Before contributing, read the guidelines below to ensure standardization and quality, speeding up the review process. +::: + +## Side-by-side mode + +All tasks are performed in **side-by-side** mode in the Crowdin Editor. To enable this, click a file you want to work on. At the top right of the page, click the **Editor view** button and select **side-by-side** mode for a clearer editor view. +![side-by-side mode](/img/localizationProgramGuideline/side-by-side.png) ## Roles Here are the **roles** you can assume in the system: - **Language Coordinator** – Manages project features within assigned languages. -- **Developer** – Uploads files, edits translatable text, connects integrations, and uses the API. +- **Developer** – Uploads files, edits translatable text, connects integrations and uses the API. - **Proofreader** – Translates and approves strings. - **Translator** (in-house or community) – Translates strings and votes on translations added by others. -Our localization project is hosted on [Crowdin](https://crowdin.com/project/ton-docs). - -:::info -Before you start contributing, **read the guidelines below** to ensure standardization and quality, making the review process much faster. - -## Side-by-Side Mode +The localization project is hosted on [Crowdin](https://crowdin.com/project/ton-docs). -All tasks are performed in **side-by-side** mode in the Crowdin Editor. To enable this, click a file you want to work on. At the top right of the page, click the **Editor view** button and select **side-by-side** mode for a clearer editor view. -![side-by-side mode](/img/localizationProgramGuideline/side-by-side.png) -::: -### Language Coordinator -- **Translate and approve strings** -- **Pre-translate project content** -- **Manage project members and join requests** +### Language coordinator guidelines +- Translate and approve strings +- Pre-translate project content +- Manage project members and join requests ![manage-members](/img/localizationProgramGuideline/manage-members.png) -- **Generate project reports** +- Generate project reports ![generate-reports](/img/localizationProgramGuideline/generate-reports.png) -- **Create tasks** +- Create tasks ![create-tasks](/img/localizationProgramGuideline/create-tasks.png) -### Developer -- **Update Footer Configuration for Your Language :** - 1. Fork our [**repository**](https://github.com/TownSquareXYZ/ton-docs/tree/i18n_feat). +### Developer guidelines +- **Update footer configuration for your language:** + 1. Fork our [repository](https://github.com/TownSquareXYZ/ton-docs/tree/i18n_feat). 2. Locate the file [**`src/theme/Footer/config.ts`**](https://github.com/TownSquareXYZ/ton-docs/blob/main/src/theme/Footer/config.ts). 3. Copy the value of the variable **`FOOTER_COLUMN_LINKS_EN`** to **`FOOTER_COLUMN_LINKS_[YOUR_LANG]`**. 4. Translate the values of the keys **`headerLangKey`** and **`langKey`** to your language, as we did for Mandarin in **`FOOTER_COLUMN_LINKS_CN`**. 5. Add a new property to **`FOOTER_LINKS_TRANSLATIONS`**: - Set **the key** as your [**ISO language code**](https://www.andiamo.co.uk/resources/iso-language-codes/) (**two letters**, **lowercase**). - - **The value** should be the new variable you just created for your language. + - **The value** should be the new variable you created for your language. 6. Run the command **`yarn start:local [YOUR_IOS_LANG_CODE]`** to preview the new footer in your language. (e.g., **`yarn start:local ru`** for a preview of the **Russian** footer) 7. If everything looks good, create a pull request to the **`i18n_feat`** branch. @@ -62,13 +61,13 @@ All tasks are performed in **side-by-side** mode in the Crowdin Editor. To enabl ![install-github-integration](/img/localizationProgramGuideline/howItWorked/install-github-integration.png) - **Use the [Crowdin API](https://developer.crowdin.com/api/v2/)** -### Proofreader +### Proofreader guidelines As a **Proofreader**, you'll work on files with a **blue progress bar**. ![proofread step1](/img/localizationProgramGuideline/proofread-step1.png) Click on a file to enter the editing interface. -#### Let's Start Contributing +#### Contribution flow 1. Make sure you're in [**side-by-side mode**](#side-by-side-mode). Filter by **Not Approved** translations to see strings needing proofreading. ![proofread filter](/img/localizationProgramGuideline/proofread-filter.png) @@ -81,23 +80,23 @@ Click on a file to enter the editing interface. ![proofread approved](/img/localizationProgramGuideline/proofread-approved.png) :::info -You can also review approved lines: +You can also review the approved lines: 1. Filter by **Approved**. 2. If an approved line has issues, click the ☑️ button to revert it to needing proofreading. ::: -3. To move to the next file, click the file name at the top, select the new file from the pop-up window, and continue proofreading. +3. To move to the following file, click the file name at the top, select the new file from the pop-up window, and continue proofreading. ![to next](/img/localizationProgramGuideline/redirect-to-next.png) -#### Previewing Your Work -Every approved content will be deployed to a preview website within one hour. Check [**our repo**](https://github.com/TownSquareXYZ/ton-docs/pulls) for the **preview** link in the newest PR. +#### Previewing your work +The preview website displays all approved content within one hour. Check [**our repo**](https://github.com/TownSquareXYZ/ton-docs/pulls) for the **preview** link in the newest PR. ![preview link](/img/localizationProgramGuideline/preview-link.png) -### Translator +### Translator guidelines -As a **Translator**, your goal is to ensure translations are faithful and expressive, making them as close to the original meaning and as understandable as possible. Your mission is to make the **blue progress bar** reach 100%. +As a translator, you aim to ensure that translations are faithful and expressive, keeping them as close to the original meaning and as understandable as possible. Your mission is to make the blue progress bar reach 100%. -#### Let's Start Translating +#### Translation flow Follow these steps for a successful translation process: @@ -118,15 +117,15 @@ Follow these steps for a successful translation process: 5. To move to the next file, click the file name at the top and select the new file from the pop-up window. ![to next](/img/localizationProgramGuideline/redirect-to-next.png) -## How to Add Support for a New Language +## How to add support for a new language -Currently, we have all desired languages in Crowdin. If you are a community manager, follow these steps: +If you are a community manager, follow these steps: 1. Add a new branch named `[lang]_localization` (e.g., `ko_localization` for Korean) on [TownSquareXYZ/ton-docs](https://github.com/TownSquareXYZ/ton-docs). 2. **Contact the Vercel owner of this repo** to add the new language to the menu. 3. Create a PR request to the dev branch. **Do not merge to dev**; this is for preview purposes only. -Once these steps are completed, you can see the preview of your language in the PR request. +Once you complete these steps, you can see the preview of your language in the PR request. ![ko preview](/img/localizationProgramGuideline/ko_preview.png) When your language is ready for the TON docs, create an issue, and we'll set your language into the production environment. diff --git a/docs/v3/contribute/localization-program/overview.md b/docs/v3/contribute/localization-program/overview.md index 78e794e375..9b58329a4c 100644 --- a/docs/v3/contribute/localization-program/overview.md +++ b/docs/v3/contribute/localization-program/overview.md @@ -1,22 +1,22 @@ -# Localization program +# Localization -The Translation Program is a collaborative effort to translate various documents related to TON into multiple languages, making the website more accessible to billions of non-English speakers worldwide. +The localization is a collaborative effort to translate various TON-related documents into multiple languages, making the website accessible to billions of non-English speakers worldwide. -## System Design Philosophy +## System design philosophy ![how it works](/img/localizationProgramGuideline/localization-program.png) -The localization program is **launched** and **actively maintained** by [**TownSquare Labs**](https://github.com/TownSquareXYZ), one of the closest partners of **TON**. +The localization process is fully maintained by [TownSquare Labs](https://github.com/TownSquareXYZ). -We are committed to creating an open infrastructure for multilingual community collaboration to **advance TON to a better phase**, which includes: +TownSquare is committed to creating an open infrastructure for multilingual community collaboration to advance TON to a better phase, which includes: * **Suitable for multilingual communities** The program supports multiple languages, ensuring inclusivity and ease of access for users from diverse linguistic backgrounds. * **Automate development, integration, and deployment** - Through automation tools, the program simplifies development, integration, and deployment, reducing manual efforts and enhancing efficiency and consistency across localization efforts. + The program simplifies development, integration, and deployment through automation tools, reducing manual efforts and enhancing efficiency and consistency across localization efforts. * **Separation of roles for developer, translator, and verifier** - Our approach divides the responsibilities of developers, translators, and verifiers, allowing each role to focus on their tasks, ensuring high-quality translations and seamless collaboration without role conflicts. + Our approach divides the responsibilities of developers, translators, and verifiers, allowing each role to focus on their tasks and ensuring high-quality translations and seamless collaboration without role conflicts. * **Incentives for community contributions** We offer incentives for community members who contribute to localization efforts. This fosters active participation, rewards contributors, and promotes a sense of ownership and community engagement. @@ -24,13 +24,13 @@ We are committed to creating an open infrastructure for multilingual community c * **Advanced AI system integration** AI systems improve translation accuracy and efficiency by offering intelligent suggestions and automating repetitive tasks, ensuring high-quality outcomes with reduced effort. -This project is designed to support speakers of multiple languages, with the goal of serving the global developer ecosystem. +This project is designed to support speakers of multiple languages and serve the global developer ecosystem. ## Acknowledgments -We sincerely appreciate the thousands of community members who are integral to the Translation Program. We aim to acknowledge our translators and support their career growth. In the future, we plan to create leaderboards and a list of all contributors to the program. +We sincerely appreciate the thousands of community members integral to the Translation Program. We aim to acknowledge our translators and support their career growth. In the future, we plan to create leaderboards and a list of all contributors. -## Guides and Resources +## Guides and resources If you are participating in or considering joining the Translation Program, refer to the translation guides below: -* [**Translation Style Guide**](/v3/contribute/localization-program/translation-style-guide) – Instructions and tips for translators. -* [**Crowdin Online Editor Guide**](https://support.crowdin.com/online-editor/) – An in-depth guide to using the Crowdin online editor and some of Crowdin's advanced features. +* [Translation style guide](/v3/contribute/localization-program/translation-style-guide) – Instructions and tips for translators. +* [Crowdin online editor guide](https://support.crowdin.com/online-editor/) – An in-depth guide to using the Crowdin online editor and some of Crowdin's advanced features. diff --git a/docs/v3/contribute/localization-program/translation-style-guide.md b/docs/v3/contribute/localization-program/translation-style-guide.md index 1285dbd949..c126cf59b6 100644 --- a/docs/v3/contribute/localization-program/translation-style-guide.md +++ b/docs/v3/contribute/localization-program/translation-style-guide.md @@ -1,45 +1,43 @@ # Translation style guide -This translation style guide contains some of the most important guidelines, instructions, and tips for translators, helping us localize the website. +This translation style guide contains essential guidelines, instructions, and tips for translators, helping us localize the website. -This document serves as a general guide and is not specific to any one language. +This document serves as a general guide and is not specific to any language. ## Capturing the essence of the message When translating TON docs content, avoid literal translations. -It is important that the translations capture the essence of the message. This could mean rephrasing certain phrases, or using descriptive translations instead of translating the content word for word. +The translations must capture the essence of the message. This approach means rephrasing specific phrases or using descriptive translations instead of translating the content word for word. -Different languages have different grammar rules, conventions and word order. When translating, please be mindful of how sentences are structured in the target languages, and avoid literally translating the English source, as this can lead to poor sentence structure and readability. +Different languages have different grammar rules, conventions, and word order. When translating, please be mindful of structuring sentences in the target languages, and avoid word-for-word translation of the English source, as this can lead to poor sentence structure and readability. -Instead of translating the source text word for word, it is recommended you read the entire sentence and adapt it to fit the conventions of the target language. +Instead of translating the source text word for word, you should read the entire sentence and adapt it to fit the conventions of the target language. ## Formal vs. informal We use the formal form of address, which is always polite and appropriate for all visitors. -Using the formal address allows us to avoid sounding unofficial or offensive, and works regardless of the visitor’s age and gender. +Using the formal address allows us to avoid sounding unofficial or offensive and works regardless of the reader’s age and gender. -Most Indo-European and Afro-Asiatic languages use gender-specific second-person personal pronouns, which distinguish between male and female. When addressing the user or using possessive pronouns, we can avoid assuming the visitor’s gender, as the formal form of address is generally applicable and consistent, regardless of how they identify. +Most Indo-European and Afro-Asiatic languages use gender-specific second-person personal pronouns, distinguishing between males and females. When addressing the user or using possessive pronouns, we can avoid assuming the reader’s gender, as the formal address is generally applicable and consistent, regardless of how they identify. -## Simple and clear vocabulary and meaning +## Straightforward vocabulary and meaning Our goal is to make content on the website understandable to as many people as possible. -In most cases, this can be easily achieved by using short and simple words that are easily understandable. If there are multiple possible translations for a certain word in your language with the same meaning, the best option is most often the shortest word that clearly reflects the meaning. +In most cases, contributors can achieve this result by using short and simple words that are easily understandable. If multiple possible translations exist for a word in your language with the same meaning, the best option is often the shortest word reflecting the meaning. ## Writing system -All of the content should be translated using the correct writing system for your language, and should not include any words, written using Latin characters. +All of the content should be translated using the correct writing system for your language and should not include any words written using Latin characters. When translating the content, you should ensure that the translations are consistent and do not include any Latin characters. -**The above doesn’t apply to languages, where proper names shouldn’t be translated as a rule.** +**Do not translate proper names defined by glossary** ## Translating page metadata -Some pages contain metadata on the page, like 'title', 'lang', 'description', 'sidebar', etc. +Some pages contain metadata, such as 'title', 'lang', 'description', 'sidebar', etc. -We hide the content that translators should never translate when uploading new pages to Crowdin, meaning that all the metadata visible to translators in Crowdin should get translated. +When uploading new pages to Crowdin, we hide content that translators should never translate. This feature makes visible to translators in Crowdin only the text that should be translated. -Please be especially mindful when translating any strings where the source text is 'en'. This represents the language that the page is available in and should be translated to the [ISO language code for your language](https://www.andiamo.co.uk/resources/iso-language-codes/). These strings should always be translated using Latin characters, not the writing script, native to the target language. - -If you are unsure which language code to use, you can check the translation memory in Crowdin or find the language code for your language in the URL of the page in the Crowdin online editor. +Please be especially careful when translating strings where the source text is 'en'. This represents the language page, which is available and should be translated to the [ISO language code for your language](https://www.andiamo.co.uk/resources/iso-language-codes/). These strings should always be translated using Latin characters, not the writing script, native to the target language. Some examples of language codes for the most widely spoken languages: @@ -51,55 +49,55 @@ Some examples of language codes for the most widely spoken languages: * Ukrainian - uk ## Titles of external articles -Some strings contain titles of external articles. Most of our developer documentation pages contain links to external articles for further reading. The strings containing titles of articles need to be translated, regardless of the article's language, to ensure a more consistent user experience for the visitors viewing the page in their language. +Some strings contain titles of external articles. Most of our developer documentation pages contain links to external articles for further reading. The strings containing article titles need to be translated, regardless of the article's language, to ensure a more consistent user experience for visitors viewing the page in their language. ## Crowdin warnings -Crowdin has a built-in feature that warns translators when they are about to make a mistake. Crowdin will automatically warn you of this before saving your translation if you forget to include a tag from the source, translate elements that should not be translated, add several consecutive spaces, forget end punctuation, etc. If you see a warning like this, please go back and double-check the suggested translation. +Crowdin has a built-in feature that warns translators when they are about to make a mistake. Crowdin will automatically alert you before saving your translation if you forget to include a tag from the source, translate elements that should not be translated, add several consecutive spaces, forget end punctuation, etc. If you see a warning like this, please double-check the suggested translation. :::warning -Never ignore these warnings, as they usually mean that something is wrong, or that the translation is missing a key part of the source text. +Never ignore these warnings, as they usually mean something is wrong or the translation lacks a key part of the source text. ::: -## Short vs. full forms/abbreviations -There are a lot of abbreviations used on the website, e.g. dapps, NFT, DAO, DeFi, etc. These abbreviations are commonly used in English and most visitors to the website are familiar with them. +## Short vs. complete forms and abbreviations +The website uses many abbreviations, such as apps, DApps, NFT, DAO, DeFi, etc. These abbreviations are standard in English, and most visitors are familiar with them. -Since they usually don’t have established translations in other languages, the best way to approach these and similar terms is to provide a descriptive translation of the full form, and add the English abbreviation in brackets. +Since they usually don’t have established translations in other languages, the best approach to these and similar terms is to provide a descriptive translation of the entire form and add the English abbreviation in brackets. -Do not translate these abbreviations, since most people wouldn’t be familiar with them, and the localized versions would not make much sense to most visitors. +Do not translate these abbreviations since most people are unfamiliar with them, and the localized versions would not make much sense to most visitors. -Example of how to translate dapps: +Example of how to translate DApps: -* Decentralized applications (dapps) → Translated full form (English abbreviation in brackets) +* Decentralized applications (DApps) → Translated in complete form (English abbreviation in brackets) ## Terms without established translations -Some terms might not have established translations in other languages, and are widely known by the original English term. Such terms mostly include newer concepts, like proof-of-work, proof-of-stake, Beacon Chain, staking, etc. +Some terms might not have established translations in other languages but are widely known by their original English names. Such terms include newer concepts, like proof-of-work, proof-of-stake, Beacon Chain, staking, etc. -While translating these terms can sound unnatural, since the English version is commonly used in other languages as well, it is highly recommended that they are translated. +While translating these terms can sound unnatural, since the English version is a basis for other languages, it is highly recommended that they be translated. -When translating them, feel free to get creative, use descriptive translations, or simply translate them literally. +Feel free to get creative, use descriptive translations, or translate them literally. -The reason why most terms should be translated, instead of leaving some in English, is the fact that this new terminology will become more widespread in the future, as more people start using TON and related technologies. If we want to onboard more people from all over the world to this space, we need to provide understandable terminology in as many languages as possible, even if we need to create it ourselves. +Most terms should be translated instead of leaving some in English, as this new terminology will become more widespread as more people start using TON and related technologies. To onboard more people to TON, we must provide understandable terminology in as many languages as possible, even if we need to create it ourselves. ## Buttons & CTAs -The website contains numerous buttons, which should be translated differently than other content. +Do not translate the website's contents, such as buttons. -Button text can be identified by viewing the context screenshots, connected with most strings, or by checking the context in the editor, which includes the phrase ‘’button’’. +You may identify button text by viewing the context screenshots connected with most strings or by checking the context in the editor, which includes the phrase ‘’button’’. -The translations for buttons should be as short as possible, to prevent formatting mismatches. Additionally, button translations should be imperative, i.e. present a command or request. +Button translations should be as short as possible to prevent formatting mismatches. Additionally, button translations, i.e., presenting a command or request, should be imperative. ## Translating for inclusivity -TON docs visitors come from all over the world and from different backgrounds. The language on the website should therefore be neutral, welcoming to everyone and not exclusive. +TON docs visitors come from all over the world and from different backgrounds. Therefore, the language on the website should be neutral, welcoming to everyone, and not exclusive. -An important aspect of this is gender neutrality. This can be easily achieved by using the formal form of address, and avoiding any gender-specific words in the translations. +Gender neutrality is an essential aspect of this. Use the formal address form and avoid gender-specific words in the translations. -Another form of inclusivity is trying to translate for a global audience, not specific to any country, race or region. +Another form of inclusivity is trying to translate for a global audience, not specific to any country, race, or region. Finally, the language should be suitable for all audiences and ages. ## Language-specific translations -When translating, it is important to follow the grammar rules, conventions and formatting, used in your language, as opposed to copying from the source. The source text follows English grammar rules and conventions, which is not applicable to many other languages. +When translating, it is crucial to follow the grammar rules, conventions, and formatting used in your language instead of copying from the source. The source text follows English grammar rules and conventions, which do not apply to many other languages. -You should be aware of the rules for your language and translate accordingly. If you need help, reach out to us and we will help you find some resources on how these elements should be used in your language. +You should be aware of the rules for your language and translate accordingly. If you need help, contact us; we will help you with resources on translating elements for your language. Some examples of what to be particularly mindful of: @@ -109,22 +107,22 @@ Some examples of what to be particularly mindful of: * There are vast differences in capitalization in different languages. * In English, it is common to capitalize all words in titles and names, months and days, language names, holidays, etc. In many other languages, this is grammatically incorrect, as they have different capitalization rules. -* Some languages also have rules about capitalizing personal pronouns, nouns, and certain adjectives, which are not capitalized in English. +* Some languages also have rules about capitalizing personal pronouns, nouns, and adjectives that you shouldn't capitalize in English. #### Spacing * Orthography rules define the use of spaces for each language. Because spaces are used everywhere, these rules are some of the most distinct, and spaces are some of the most mistranslated elements. * Some common differences in spacing between English and other languages: - * Space before units of measure and currencies (e.g. USD, EUR, kB, MB) - * Space before degree signs (e.g. °C, ℉) - * Space before some punctuation marks, especially the ellipsis (…) - * Space before and after slashes (/) + * Space before units of measure and currencies. Example: USD, EUR, kB, MB + * Space before degree signs. Example: °C, ℉ + * Space before some punctuation marks, especially the ellipsis. Example: Then… in summary + * Space before and after slashes. Example: if / else #### Lists -* Every language has a diverse and complex set of rules for writing lists. These can be significantly different to English. -* In some languages, the first word of each new line needs to be capitalized, while in others, new lines should start with lower-case letters. Many languages also have different rules about capitalization in lists, depending on the length of each line. -* The same applies to punctuation of line items. The end punctuation in lists can be a period (.), comma (,), or semicolon (;), depending on the language. +* Every language has a diverse and complex set of rules for writing lists. These can be significantly different from English. +* In some languages, the first word of each new line needs to be capitalized, while in others, new lines should start with lowercase letters. Many languages also have different rules about capitalization in lists, depending on the length of each line. +* The same applies to the punctuation of line items. The end punctuation in lists can be a period (.), comma (,), or semicolon (;), depending on the language. #### Quotation marks @@ -139,24 +137,27 @@ Some examples of what to be particularly mindful of: #### Hyphens and dashes -* In English, a hyphen (-) is used to join words or different parts of a word, while a dash (–) is used to indicate a range or a pause. +* In English, a hyphen `-` is used to join words or different parts of a word, while a dash `—` indicates a range or a pause. + * Example: TON — is ... proof-of-stake. * Many languages have different rules for using hyphens and dashes that should be observed. ### Formats #### Numbers -* The main difference in writing numbers in different languages is the separator used for decimals and thousands. For thousands, this can be a period, comma or space. Similarly, some languages use a decimal point, while others use a decimal comma. - * Some examples of large numbers: +* The main difference in writing numbers in different languages is the separator for decimals and thousands. For thousands, this can be a period, comma, or space. Similarly, some languages use a decimal point, while others use a decimal comma. + * Example: * English – **1,000.50** * Spanish – **1.000,50** * French – **1 000,50** -* Another important consideration when translating numbers is the percent sign. It can be written in different ways: **100%**, **100 %** or **%100**. -* Finally, negative numbers can be displayed differently, depending on the language: -100, 100-, (100) or [100]. +* The percent sign is another critical consideration when translating numbers. Write numbers in the typical format for the corresponding language. + * Example: **100%**, **100 %**, or **%100**. +* Finally, negative numbers can be displayed differently, depending on the language + * Example: -100, 100-, (100) or [100]. #### Dates -* When translating dates, there are a number of considerations and differences based on the language. These include the date format, separator, capitalization and leading zeros. There are also differences between full-length and numerical dates. +* When translating dates, there are several considerations and differences based on the language. These include the date format, separator, capitalization, and leading zeros. There are also differences between full-length and numerical dates. * Some examples of different date formats: * English UK (dd/mm/yyyy) – 1st January, 2022 * English US (mm/dd/yyyy) – January 1st, 2022 @@ -167,7 +168,7 @@ Some examples of what to be particularly mindful of: #### Currencies -* Translating currencies can be challenging, due to the different formats, conventions and conversions. As a general rule, please keep currencies the same as the source. You can add your local currency and conversion in brackets, for the benefit of the reader. +* Translating currencies can be challenging due to the different formats, conventions, and conversions. As a general rule, please keep currencies the same as the source. You can add your local currency and conversion in brackets for the reader's benefit. * The main differences in writing currencies in different languages include symbol placement, decimal commas vs. decimal points, spacing, and abbreviations vs. symbols. * Symbol placement: $100 or 100$ * Decimal commas vs. decimal points: 100,50$ or 100.50$ @@ -176,11 +177,11 @@ Some examples of what to be particularly mindful of: #### Units of measure -* As a general rule, please keep the units of measure as per the source. If your country uses a different system, you can include the conversion in brackets. -* Aside from the localization of units of measure, it is also important to note the differences in how languages approach these units. The main difference is the spacing between the number and unit, which can be different, based on the language. Examples of this include 100kB vs. 100 kB or 50ºF vs. 50 ºF. +* As a general rule, please keep the units of measure as per the source. You can include the conversion in brackets if your country uses a different system. +* Aside from the localization of units of measure, it is also important to note the differences in how languages approach these units. The main difference is the spacing between the number and unit, which can differ based on the language. Examples of this include 100kB vs. 100 kB or 50ºF vs. 50 ºF. ## Conclusion When translating, try not to rush. Take it easy and have fun! -Thank you for being involved with the Translation Program and helping us make the website accessible to a wider audience. The TON community is global, and we are happy you are a part of it! \ No newline at end of file +Thank you for helping us localize the website and make it accessible to a wider audience. The TON community is global, and we are happy you are a part of it! diff --git a/docs/v3/documentation/data-formats/tlb/cell-boc.mdx b/docs/v3/documentation/data-formats/tlb/cell-boc.mdx index 52564ff670..755fcee2a7 100644 --- a/docs/v3/documentation/data-formats/tlb/cell-boc.mdx +++ b/docs/v3/documentation/data-formats/tlb/cell-boc.mdx @@ -66,7 +66,7 @@ sources={{ } } ``` -In this example we have a 1-bit size root cell that has 2 links: the first to a 24-bit cell and the second to a 7-bit cell which possesses 1 link to a 24-bit cell. +In this example we have a 0-bit size root cell that has 2 links: the first to a 24-bit cell and the second to a 7-bit cell which possesses 1 link to a 24-bit cell. For this framework to work as intended, it’s necessary to turn the cells into a single sequence of bytes. To accomplish this, first, we leverage only unique cell types, below 3 out of 4 are presented as follows: ```json diff --git a/docs/v3/documentation/smart-contracts/contracts-specs/examples.md b/docs/v3/documentation/smart-contracts/contracts-specs/examples.md index a67263e5e9..db72848a3d 100644 --- a/docs/v3/documentation/smart-contracts/contracts-specs/examples.md +++ b/docs/v3/documentation/smart-contracts/contracts-specs/examples.md @@ -11,61 +11,61 @@ Make sure you have thoroughly tested contracts before using them in a production ### Production-Used Contracts | Contracts | Description | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [wallet-contract](https://github.com/ton-blockchain/wallet-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/wallet-contract&name=wallet-contract) | Wallet v4 is the proposed version of the wallet to replace v3 or older wallets | -| [liquid-staking-contract](https://github.com/ton-blockchain/liquid-staking-contract/)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/liquid-staking-contract/&name=liquid-staking-contract) | Liquid Staking (LSt) is a protocol that connects TON holders of all calibers with hardware node operators to participate in TON Blockchain validation through asset pooling. | -| [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/EmelyanenkoK/modern_jetton&name=modern_jetton) | Implementation of standard jetton with additional withdraw_tons and withdraw_jettons. | +| [wallet-contract](https://github.com/ton-blockchain/wallet-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/wallet-contract&name=wallet-contract) | Wallet v4 is the proposed version of the wallet to replace v3 or older wallets | +| [liquid-staking-contract](https://github.com/ton-blockchain/liquid-staking-contract/)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/liquid-staking-contract/&name=liquid-staking-contract) | Liquid Staking (LSt) is a protocol that connects TON holders of all calibers with hardware node operators to participate in TON Blockchain validation through asset pooling. | +| [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/EmelyanenkoK/modern_jetton&name=modern_jetton) | Implementation of standard jetton with additional withdraw_tons and withdraw_jettons. | | [highloadwallet-v3](https://github.com/ton-blockchain/highload-wallet-contract-v3) | This wallet is designed for those who need to send transactions at very high rates, such as crypto exchanges. | | [stablecoin-contract](https://github.com/ton-blockchain/stablecoin-contract) | Jetton-with-governance FunC smart contracts, used for stablecoins such as USDt. | -| [governance-contract](https://github.com/ton-blockchain/governance-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/governance-contract&name=governance-contract) | Core TON Blockchain contracts `elector-code.fc` and `config-code.fc`. | -| [bridge-func](https://github.com/ton-blockchain/bridge-func)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/bridge-func&name=bridge-func) | TON-EVM Toncoin Bridge. | -| [token-bridge-func](https://github.com/ton-blockchain/token-bridge-func)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/token-bridge-func&name=token-bridge-func) | TON-EVM token bridge - FunC smart contracts. | -| [lockup-wallet-contract/universal](https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/universal)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/universal&name=lockup-wallet-contract/universal) | The universal lockup wallet is a contract that can store locked and restricted coins. | -| [lockup-wallet-contract/vesting](https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/vesting)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/vesting&name=lockup-wallet-contract/vesting) | Vesting wallet smart-contract | -| [multisig-contract](https://github.com/ton-blockchain/multisig-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/multisig-contract&name=multisig-contract) | `(n, k)`-multisig wallet is a wallet with `n` private keys holders, which accepts requests to send messages if the request collects at least `k` signatures of the holders. | -| [token-contract](https://github.com/ton-blockchain/token-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/token-contract&name=token-contract) | Fungible, Non-Fungible, Semi-Fungible Tokens Smart Contracts | -| [dns-contract](https://github.com/ton-blockchain/dns-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/dns-contract&name=dns-contract) | Smart contracts of `.ton` zone. | -| [nominator-pool](https://github.com/ton-blockchain/nominator-pool)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/nominator-pool&name=nominator-pool) | Nominator Pool smart contract | -| [single-nominator-pool](https://github.com/orbs-network/single-nominator)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/nominator-pool&name=nominator-pool) | Single Nominator Pool smart contract | -| [vesting-contract](https://github.com/ton-blockchain/vesting-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/vesting-contract&name=vesting-contract) | The Vesting contract allows you to lock a certain amount of Toncoin for a specified time and gradually unlock them. | -| [storage](https://github.com/ton-blockchain/ton/tree/master/storage/storage-daemon/smartcont)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-blockchain/ton/tree/master/storage/storage-daemon/smartcont&name=storage) | TON Storage provider and fabric contracts | +| [governance-contract](https://github.com/ton-blockchain/governance-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/governance-contract&name=governance-contract) | Core TON Blockchain contracts `elector-code.fc` and `config-code.fc`. | +| [bridge-func](https://github.com/ton-blockchain/bridge-func)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/bridge-func&name=bridge-func) | TON-EVM Toncoin Bridge. | +| [token-bridge-func](https://github.com/ton-blockchain/token-bridge-func)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/token-bridge-func&name=token-bridge-func) | TON-EVM token bridge - FunC smart contracts. | +| [lockup-wallet-contract/universal](https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/universal)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/universal&name=lockup-wallet-contract/universal) | The universal lockup wallet is a contract that can store locked and restricted coins. | +| [lockup-wallet-contract/vesting](https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/vesting)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/lockup-wallet-contract/tree/main/vesting&name=lockup-wallet-contract/vesting) | Vesting wallet smart-contract | +| [multisig-contract](https://github.com/ton-blockchain/multisig-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/multisig-contract&name=multisig-contract) | `(n, k)`-multisig wallet is a wallet with `n` private keys holders, which accepts requests to send messages if the request collects at least `k` signatures of the holders. | +| [token-contract](https://github.com/ton-blockchain/token-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/token-contract&name=token-contract) | Fungible, Non-Fungible, Semi-Fungible Tokens Smart Contracts | +| [dns-contract](https://github.com/ton-blockchain/dns-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/dns-contract&name=dns-contract) | Smart contracts of `.ton` zone. | +| [nominator-pool](https://github.com/ton-blockchain/nominator-pool)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/nominator-pool&name=nominator-pool) | Nominator Pool smart contract | +| [single-nominator-pool](https://github.com/orbs-network/single-nominator)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/nominator-pool&name=nominator-pool) | Single Nominator Pool smart contract | +| [vesting-contract](https://github.com/ton-blockchain/vesting-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/vesting-contract&name=vesting-contract) | The Vesting contract allows you to lock a certain amount of Toncoin for a specified time and gradually unlock them. | +| [storage](https://github.com/ton-blockchain/ton/tree/master/storage/storage-daemon/smartcont)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-blockchain/ton/tree/master/storage/storage-daemon/smartcont&name=storage) | TON Storage provider and fabric contracts | ### Ecosystem Contracts | Contracts | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| [telemint](https://github.com/TelegramMessenger/telemint)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/TelegramMessenger/telemint&name=telemint) | Telegram Usenames(`nft-item.fc`) and Telegram Numbers(`nft-item-no-dns.fc`) contracts. | -| [capped-fungible-token](https://github.com/TonoxDeFi/capped-fungible-token)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/TonoxDeFi/capped-fungible-token&name=capped-fungible-token) | Basic implementation of smart contracts for Jetton Wallet and Jetton Minter | +| [telemint](https://github.com/TelegramMessenger/telemint)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/TelegramMessenger/telemint&name=telemint) | Telegram Usenames(`nft-item.fc`) and Telegram Numbers(`nft-item-no-dns.fc`) contracts. | +| [capped-fungible-token](https://github.com/TonoxDeFi/capped-fungible-token)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/TonoxDeFi/capped-fungible-token&name=capped-fungible-token) | Basic implementation of smart contracts for Jetton Wallet and Jetton Minter | | [gusarich-airdrop](https://github.com/Gusarich/airdrop/tree/main/contracts) | Implementation of a Scalable Airdrop System for the TON blockchain. It can be used to distribute Jettons on-chain to any number of wallets. | -| [getgems-io/nft-contracts](https://github.com/getgems-io/nft-contracts/tree/main/packages/contracts/sources)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/getgems-io/nft-contracts/tree/main/packages/contracts/sources&name=getgems-io/nft-contracts) | Getgems NFT Contracts | -| [lockup-wallet-deployment](https://github.com/ton-defi-org/lockup-wallet-deployment)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-defi-org/lockup-wallet-deployment&name=lockup-wallet-deployment) | Deploy and run lockup Contract end to end | -| [WTON](https://github.com/TonoxDeFi/WTON)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/TonoxDeFi/WTON&name=WTON) | This smart contract provides an implementation of wrapped Toncoin, called WTON | -| [wton-contract](https://github.com/ton-community/wton-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-community/wton-contract&name=wton-contract) | wTON contracts | -| [contract-verifier-contracts](https://github.com/ton-community/contract-verifier-contracts)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-community/contract-verifier-contracts&name=contract-verifier-contracts) | Sources registry contracts which stores an on-chain proof per code cell hash. | -| [vanity-contract](https://github.com/ton-community/vanity-contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-community/vanity-contract&name=vanity-contract) | Smart contract that allows to "mine" any suitable address for any contract. | -| [ton-config-smc](https://github.com/ton-foundation/ton-config-smc)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-foundation/ton-config-smc&name=ton-config-smc) | Simple contract for storing versioned data in TON Blockchain. | -| [ratelance](https://github.com/ProgramCrafter/ratelance/tree/main/contracts/func)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ProgramCrafter/ratelance/tree/main/contracts/func&name=ratelance) | Ratelance is freelance platform that seeks to remove barriers between potential employers and workers. | -| [logger.fc](https://github.com/tonwhales/ton-contracts/blob/master/contracts/logger.fc)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/tonwhales/ton-contracts/blob/master/contracts/logger.fc&name=logger.fc) | Contract that saves data in the local storage. | -| [ton-nominators](https://github.com/tonwhales/ton-nominators)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/tonwhales/ton-nominators&name=ton-nominators) | Ton Whales Nominator pool source code. | -| [ton-link-contract-v3](https://github.com/ton-link/ton-link-contract-v3)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-link/ton-link-contract-v3&name=ton-link-contract-v3) | Ton-link allows smart contracts to access data outside of the blockchain while maintaining data security. | -| [delab-team/fungible-token](https://github.com/delab-team/contracts/tree/main/fungible-token)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/delab-team/contracts/tree/main/fungible-token&name=delab-team/fungible-token) | DeLab TON fungible-token implementation | -| [whitelisted-wallet.fc](https://github.com/tonwhales/ton-contracts/blob/master/contracts/whitelisted-wallet.fc)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/tonwhales/ton-contracts/blob/master/contracts/whitelisted-wallet.fc&name=whitelisted-wallet.fc) | Simple Whitelisted Wallet Contract | -| [delab-team/jetton-pool](https://github.com/delab-team/contracts/tree/main/jetton-pool)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/delab-team/contracts/tree/main/jetton-pool&name=delab-team/jetton-pool) | The Jetton Pool TON smart contract is designed to create farming pools. | -| [ston-fi/contracts](https://github.com/ston-fi/dex-core/tree/main/contracts)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ston-fi/dex-core/tree/main/contracts&name=ston-fi/contracts) | Stonfi DEX core contracts | -| [onda-ton](https://github.com/0xknstntn/onda-ton)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/0xknstntn/onda-ton&name=onda-ton) | Onda Lending Pool - Core smart contracts of the first lending protocol on TON | -| [ton-stable-timer](https://github.com/ProgramCrafter/ton-stable-timer)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ProgramCrafter/ton-stable-timer&name=ton-stable-timer) | TON Stable Timer contract | -| [HipoFinance/contract](https://github.com/HipoFinance/contract)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/HipoFinance/contract&name=HipoFinance) | hTON is a decentralized, permission-less, open-source liquid staking protocol on TON Blockchain | +| [getgems-io/nft-contracts](https://github.com/getgems-io/nft-contracts/tree/main/packages/contracts/sources)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/getgems-io/nft-contracts/tree/main/packages/contracts/sources&name=getgems-io/nft-contracts) | Getgems NFT Contracts | +| [lockup-wallet-deployment](https://github.com/ton-defi-org/lockup-wallet-deployment)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-defi-org/lockup-wallet-deployment&name=lockup-wallet-deployment) | Deploy and run lockup Contract end to end | +| [WTON](https://github.com/TonoxDeFi/WTON)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/TonoxDeFi/WTON&name=WTON) | This smart contract provides an implementation of wrapped Toncoin, called WTON | +| [wton-contract](https://github.com/ton-community/wton-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-community/wton-contract&name=wton-contract) | wTON contracts | +| [contract-verifier-contracts](https://github.com/ton-community/contract-verifier-contracts)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-community/contract-verifier-contracts&name=contract-verifier-contracts) | Sources registry contracts which stores an on-chain proof per code cell hash. | +| [vanity-contract](https://github.com/ton-community/vanity-contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-community/vanity-contract&name=vanity-contract) | Smart contract that allows to "mine" any suitable address for any contract. | +| [ton-config-smc](https://github.com/ton-foundation/ton-config-smc)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-foundation/ton-config-smc&name=ton-config-smc) | Simple contract for storing versioned data in TON Blockchain. | +| [ratelance](https://github.com/ProgramCrafter/ratelance/tree/main/contracts/func)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ProgramCrafter/ratelance/tree/main/contracts/func&name=ratelance) | Ratelance is freelance platform that seeks to remove barriers between potential employers and workers. | +| [logger.fc](https://github.com/tonwhales/ton-contracts/blob/master/contracts/logger.fc)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/tonwhales/ton-contracts/blob/master/contracts/logger.fc&name=logger.fc) | Contract that saves data in the local storage. | +| [ton-nominators](https://github.com/tonwhales/ton-nominators)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/tonwhales/ton-nominators&name=ton-nominators) | Ton Whales Nominator pool source code. | +| [ton-link-contract-v3](https://github.com/ton-link/ton-link-contract-v3)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-link/ton-link-contract-v3&name=ton-link-contract-v3) | Ton-link allows smart contracts to access data outside of the blockchain while maintaining data security. | +| [delab-team/fungible-token](https://github.com/delab-team/contracts/tree/main/fungible-token)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/delab-team/contracts/tree/main/fungible-token&name=delab-team/fungible-token) | DeLab TON fungible-token implementation | +| [whitelisted-wallet.fc](https://github.com/tonwhales/ton-contracts/blob/master/contracts/whitelisted-wallet.fc)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/tonwhales/ton-contracts/blob/master/contracts/whitelisted-wallet.fc&name=whitelisted-wallet.fc) | Simple Whitelisted Wallet Contract | +| [delab-team/jetton-pool](https://github.com/delab-team/contracts/tree/main/jetton-pool)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/delab-team/contracts/tree/main/jetton-pool&name=delab-team/jetton-pool) | The Jetton Pool TON smart contract is designed to create farming pools. | +| [ston-fi/contracts](https://github.com/ston-fi/dex-core/tree/main/contracts)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ston-fi/dex-core/tree/main/contracts&name=ston-fi/contracts) | Stonfi DEX core contracts | +| [onda-ton](https://github.com/0xknstntn/onda-ton)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/0xknstntn/onda-ton&name=onda-ton) | Onda Lending Pool - Core smart contracts of the first lending protocol on TON | +| [ton-stable-timer](https://github.com/ProgramCrafter/ton-stable-timer)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ProgramCrafter/ton-stable-timer&name=ton-stable-timer) | TON Stable Timer contract | +| [HipoFinance/contract](https://github.com/HipoFinance/contract)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/HipoFinance/contract&name=HipoFinance) | hTON is a decentralized, permission-less, open-source liquid staking protocol on TON Blockchain | ### Learning Contracts | Contracts | Description | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| -| [counter.fc](https://github.com/ton-community/blueprint/blob/main/example/contracts/counter.fc)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-community/blueprint/blob/main/example/contracts/counter.fc&name=counter.fc) | Counter smart contract with comments. | -| [simple-distributor](https://github.com/ton-community/simple-distributor)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/ton-community/simple-distributor&name=simple-distributor) | Simple TON distributor. | -| [ping-pong.fc](https://github.com/tonwhales/ton-nft/blob/main/packages/nft/ping-pong/ping-pong.fc)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/tonwhales/ton-nft/blob/main/packages/nft/ping-pong/ping-pong.fc&name=ping-pong.fc) | Simple contract to test sending Toncoin in different modes. | -| [ton-random](https://github.com/puppycats/ton-random)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/puppycats/ton-random&name=ton-random) | Two contracts that will help you in generating random numbers on-chain. | -| [Blueprint simple contract](https://github.com/liminalAngel/1-func-project/blob/master/contracts/main.fc)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/liminalAngel/1-func-project/blob/master/contracts/main.fc&name=simple_contract) | Example smart contract | -| [Blueprint jetton_minter.fc](https://github.com/liminalAngel/func-blueprint-tutorial/blob/master/6/contracts/jetton_minter.fc)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/liminalAngel/func-blueprint-tutorial/blob/master/6/contracts/jetton_minter.fc&name=jetton_minter.fc) | Smart contract example to mint Jettons on-chain. | -| [Simple TON DNS Subdomain manager](https://github.com/Gusarich/simple-subdomain)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/Gusarich/simple-subdomain&name=Simple_TON_DNS_Subdomain_manager) | TON DNS subdomains manager. | -| [disintar/sale-dapp](https://github.com/disintar/sale-dapp/tree/master/func)
🪄 [Run in WebIDE](https://ide.nujan.io/?importURL=https://github.com/disintar/sale-dapp/tree/master/func&name=disintar/sale-dapp) | React + NFT sale DApp with FunC | +| [counter.fc](https://github.com/ton-community/blueprint/blob/main/example/contracts/counter.fc)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-community/blueprint/blob/main/example/contracts/counter.fc&name=counter.fc) | Counter smart contract with comments. | +| [simple-distributor](https://github.com/ton-community/simple-distributor)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/ton-community/simple-distributor&name=simple-distributor) | Simple TON distributor. | +| [ping-pong.fc](https://github.com/tonwhales/ton-nft/blob/main/packages/nft/ping-pong/ping-pong.fc)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/tonwhales/ton-nft/blob/main/packages/nft/ping-pong/ping-pong.fc&name=ping-pong.fc) | Simple contract to test sending Toncoin in different modes. | +| [ton-random](https://github.com/puppycats/ton-random)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/puppycats/ton-random&name=ton-random) | Two contracts that will help you in generating random numbers on-chain. | +| [Blueprint simple contract](https://github.com/liminalAngel/1-func-project/blob/master/contracts/main.fc)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/liminalAngel/1-func-project/blob/master/contracts/main.fc&name=simple_contract) | Example smart contract | +| [Blueprint jetton_minter.fc](https://github.com/liminalAngel/func-blueprint-tutorial/blob/master/6/contracts/jetton_minter.fc)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/liminalAngel/func-blueprint-tutorial/blob/master/6/contracts/jetton_minter.fc&name=jetton_minter.fc) | Smart contract example to mint Jettons on-chain. | +| [Simple TON DNS Subdomain manager](https://github.com/Gusarich/simple-subdomain)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/Gusarich/simple-subdomain&name=Simple_TON_DNS_Subdomain_manager) | TON DNS subdomains manager. | +| [disintar/sale-dapp](https://github.com/disintar/sale-dapp/tree/master/func)
🪄 [Run in WebIDE](https://ide.ton.org/?importURL=https://github.com/disintar/sale-dapp/tree/master/func&name=disintar/sale-dapp) | React + NFT sale DApp with FunC | ### TON Smart Challenges diff --git a/docs/v3/documentation/smart-contracts/message-management/message-modes-cookbook.mdx b/docs/v3/documentation/smart-contracts/message-management/message-modes-cookbook.mdx index 677a9bbcde..2e0bacc828 100644 --- a/docs/v3/documentation/smart-contracts/message-management/message-modes-cookbook.mdx +++ b/docs/v3/documentation/smart-contracts/message-management/message-modes-cookbook.mdx @@ -1,34 +1,39 @@ -# Message Modes Cookbook +import ConceptImage from "@site/src/components/conceptImage"; +import ThemedImage from "@theme/ThemedImage"; -Understanding the different modes and flags available for sending messages is crucial to ensure that your smart contracts behave as intended. -While [message modes](/v3/documentation/smart-contracts/message-management/sending-messages#message-modes) section provided detailed descriptions of these modes and flags, in this section we will illustrate their practical application through specific examples. +# Message modes cookbook + +Understanding the modes and flags available for sending messages is crucial to ensure your smart contracts behave as intended. +This section will illustrate their practical application through specific examples. :::info IMPORTANT -You can check [this example](https://testnet.tonviewer.com/transaction/42ed45726e4fe994b7fd6dbf953a2ac24ecd77753858abeda9d6755c664a537a) as a real-world validation. +You can check [this example](https://testnet.tonviewer.com/transaction/42ed45726e4fe994b7fd6dbf953a2ac24ecd77753858abeda9d6755c664a537a) as a real‐world validation. ::: #### Message value and account balance -Please check how [get_balance](/v3/documentation/smart-contracts/func/docs/stdlib/#get_balance) works to better understand the transaction state. +Please check how [get_balance](/v3/documentation/smart-contracts/func/docs/stdlib/#get_balance) works to better understand `balance` inside TVM. -There are two ways to pay for blockchain action: +All TON tokens held by a contract are reflected in the contract `balance`. Some of these tokens are also assigned to the currently processed incoming `message`. This mechanism is effective because any TON transaction involving a [non‐system contract](/v3/documentation/smart-contracts/contracts-specs/governance) processes exactly one incoming message at a time. -- From the [message value](/v3/documentation/data-formats/tlb/msg-tlb#commonmsginfo) -- From the [contract balance](https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/block.tlb#L263C1-L265C20) +Therefore, any blockchain payment may come either: -Typically, it is charged from the contract `balance`, but in specific cases, it will use part of the message `value`. +- From the incoming message's `value`. + Contracts pay computation fees this way unless they call [accept_message](/v3/documentation/smart-contracts/transaction-fees/accept-message-effects), which prevents malicious actors from spending the contract's balance to process their data +- From the contract's `balance`, which leaves the incoming TON amount untouched during the transaction + This approach currently applies to storage fees in workchains 0 and -1, along with most common actions #### Fees -Actual transaction fees will vary depending on the blockchain configuration, the smart contract code and other factors. When a message is received, part of the contract `balance` will be consumed by [storage fees](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee) and gas_fees if the message `value` [is above certain amount](/v3/documentation/tvm/tvm-overview#compute-phase-skipped). +Actual transaction fees will vary depending on the blockchain configuration, the smart contract code, and other factors. When a message is received, part of the contract `balance` will be consumed by storage and gas fees if the message `value` [is above a certain amount](/v3/documentation/tvm/tvm-overview#compute-phase-skipped). -According to the [transaction flow](/v3/documentation/tvm/tvm-overview#transactions-and-phases) there are 5 phases: +According to the [transaction flow](/v3/documentation/tvm/tvm-overview#transactions-and-phases), there are five distinct phases: -- Storage, consisting of [account storage](https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/transaction.cpp#L651-L675) and [in_msg import](https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/transaction.cpp#L783-L816) -- [Credit](https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/transaction.cpp#L959-L981), where in_msg `value` is added to the `balance` -- Compute, where the actual smart contract code is executed in TVM -- Action, where actions like `SENDRAWMSG` are performed -- Bounce, where everything about bouncing is handled +1. **Storage**: This phase includes both account storage and in_msg import. +2. **Credit**: In this phase, the `value` of `in_msg` [is added](https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/transaction.cpp#L959-L981) to the `balance`. +3. **Compute**: The TVM executes the smart contract code. +4. **Action**: This phase involves performing actions such as `SENDRAWMSG`. +5. **Bounce**: This phase manages everything related to bouncing. The order is: storage_fee -> import_fee -> gas_fee -> action_fee + fwd_fee @@ -36,243 +41,393 @@ The order is: storage_fee -> import_fee -> gas_fee -> action_fee + fwd_fee The table is populated based on [this example](https://tonviewer.com/transaction/b5e14a9c4a4e982fda42d6079c3f84fa48e76497a8f3fca872f9a3737f1f6262). You can check the [**live calculator**](/v3/documentation/smart-contracts/transaction-fees/fees#basic-fees-formula). ::: -| Fee in Explorer | Value | How it's obtained | -| :------------------------------------------------------------------------------------------------ | :---------- | :------------------------------ | -| Total fee | 0,001982134 | gas + storage + action + import | -| total_fwd_fees | 0,001 | fwd_fee + action_fee + ihr_fee | -| gas_fees | 0,0011976 | compute phase, gas used | -| storage_fees | 0,000000003 | storage phase, account only | -| total_action_fees | 0,000133331 | action phase, cost per action | -| import_fee (hidden) | 0,0006512 | cost of import of ext_msg | -| [fwd_fee](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#formula-1) (each msg) | 0,000266669 | cost of fwd of in_msg | -| [ihr_fee](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#ihr) (each msg) | 0.0006 | cost of ihr fwd of in_msg | +| Fee in Explorer | Value | How it's obtained | +| :---------------------------------------------------------------------------------------------------- | :---------- | :------------------------------ | +| Total fee | 0,001982134 | gas + storage + action + import | +| Fwd. fee | 0,001 | fwd_fee + action_fee + ihr_fee | +| Gas fee | 0,0011976 | compute phase, gas used | +| Storage fee | 0,000000003 | storage phase, account only | +| Action fee | 0,000133331 | action phase, cost per action | +| Import fee (hidden) | 0,0006512 | cost of import of ext_msg | +| [Forward fee](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#formula-1) (each msg) | 0,000266669 | cost of fwd of in_msg | +| [IHR fee](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#ihr) (each msg) | 0.0006 | cost of ihr fwd of in_msg | :::info -The transaction fees used in these examples are hypothetical and are for illustrative purposes only. Any fees other than message forwarding are out of scope of this article. +The transaction fees used in these examples are hypothetical and for illustrative purposes only. Any fees other than message forwarding are outside the scope of this article. +Funds included with an ignored message will still be [credited to the receiving address](https://testnet.tonviewer.com/transaction/8a388731812c80ab9b0ea9531108425488af5def854e4bd6f0ed47362b56d557). ::: -## 1. Send a regular message +## 1. (Mode 0, Flag 0) Basic message {#mode0} State before transaction: Account A has 1 TON, Account B has 1 TON -**A** sent 0.1 TON to **B**, [msg_fwd_fees](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#forward-fees) are 0.004 TON, actual received value will be 0.096 TON, `fwd_fee` and `action_fee` deducted from `value`. +**A** sent 0.1 TON to **B**, [msg_fwd_fees](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#forward-fees) are 0.004 TON, actual received value will be 0.096 TON, `fwd_fee` and `action_fee` are deducted from `value`. -State after transaction: Account A has 0.9 TON, Account B has 1.096 TON +State after the transaction: Account A has 0.9 TON, Account B has 1.096 TON -![](/img/docs/message-modes-cookbook/send_regular_message_1.png) +

+
+ +
+

-| Mode and Flags | Code | -| :-------------------- | :------------------------- | -| `mode` = 0, no `flag` | `send_raw_message(msg, 0)` | - -## 2. Send a regular message, no bounce the message on error and ignore it +## 2. (Mode 0, Flag 2) Error‐silent message {#mode2} State before transaction: Account A has 1 TON, Account B has 1 TON -**A** sent 0.1 TON to **B**, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.096 TON, `fwd_fee` and `action_fee` deducted from `value`. -In case of an error during transaction processing, the message will not bounce and will be ignored. +**A** sent 0.1 TON to **B**. The `msg_fwd_fees` are 0.004 TON, and the actual received value will be 0.096 TON. The `fwd_fee` and `action_fee` are deducted from `value`. +In case of an error during [action phase](/v3/documentation/smart-contracts/message-management/sending-messages#message-modes), the message will be skipped instead of throwing an [exit code](/v3/documentation/tvm/tvm-exit-codes#standard-exit-codes). -State after transaction: Account A has 0.9 TON, Account B has 1.096 TON +State after the transaction: Account A has 0.9 TON, Account B has 1.096 TON :::info tip -Funds included with an ignored message will still be [credited to the receiving address](https://testnet.tonviewer.com/transaction/8a388731812c80ab9b0ea9531108425488af5def854e4bd6f0ed47362b56d557). -If no errors occur, the result is the same as [`mode = 0`](#1-send-a-regular-message). +If no errors occur, the result is the same as [mode = 0](#mode0). ::: -![](/img/docs/message-modes-cookbook/send_regular_message_2.png) - -| Mode and Flags | Code | -| :--------------------- | :------------------------- | -| `mode` = 0, `flag` = 2 | `send_raw_message(msg, 2)` | - -## 3. Send a regular message, and bounce the message in case of an action error +

+
+ +
+

+ +## 3. (Mode 0, Flag 16) Bounce on action error {#mode16} State before transaction: Account A has 1 TON, Account B has 1 TON -**A** sent 0.1 TON to **B**, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.096 TON, `fwd_fee` and `action_fee` deducted from `value`. +**A** sent 0.1 TON to **B**. The `msg_fwd_fees` are 0.004 TON, and the actual received value will be 0.096 TON. The `fwd_fee` and `action_fee` are deducted from `value`. In case of an error during [action phase](https://retracer.ton.org/?tx=e9dccba82badc0d742f14eff41c203280f380e87180b5314fcfd742856e598f7&testnet=true), the message will bounce and `total_fee` + `fwd_fee` will be deducted from `value`. -State after transaction with error: Account A has 1 - ([total_fee](/v3/documentation/smart-contracts/transaction-fees/fees#basic-fees-formula) + `fwd_fee`) TON, Account B has 1 TON - -![](/img/docs/message-modes-cookbook/send_regular_message_3_error.png) +State after the transaction with error: Account A has 1 - ([total_fee](/v3/documentation/smart-contracts/transaction-fees/fees#basic-fees-formula) + `fwd_fee`) TON, Account B has 1 TON + +

+
+ +
+

:::info tip -If no errors occur the result is the same as [`mode = 0`](#1-send-a-regular-message). -::: +If no errors occur, the result is the same as [mode = 0](#mode0). + +The key difference is that `flag 16` creates bounces for [action phase errors](/v3/documentation/tvm/tvm-exit-codes#standard-exit-codes). In contrast, the message's [built‐in bounce flag](https://docs.ton.org/v3/guidelines/smart-contracts/howto/wallet#internal-message-creation) handles protocol‐level failures like: -![](/img/docs/message-modes-cookbook/send_regular_message_3_noerror.png) +- The destination contract does not exist. +- The destination contract throws an unhandled exception. + ::: -| Mode and Flags | Code | -| :---------------------- | :-------------------------- | -| `mode` = 0, `flag` = 16 | `send_raw_message(msg, 16)` | +

+
+ +
+

-## 4. Send a regular message with separate fees +## 4. (Mode 0, Flag 1) Separate fees {#mode1} State before the transaction: Account A has 1 TON, Account B has 1 TON -**A** sent 0.1 TON to **B**, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.1 TON, `fwd_fee` and `action_fee` deducted from `balance`. +**A** sent 0.1 TON to **B**. The `msg_fwd_fees` are 0.004 TON, and the actual received value will be 0.1 TON. The `fwd_fee` and `action_fee` are deducted from the `balance`. State after the transaction: Account A has 0.896 TON, Account B has 1.1 TON -![](/img/docs/message-modes-cookbook/send_regular_message_4.png) - -| Mode and Flags | Code | -| :--------------------- | :------------------------- | -| `mode` = 0, `flag` = 1 | `send_raw_message(msg, 1)` | - -## 5. Send a regular message with separate fees and bounce the message on error +

+
+ +
+

+ +## 5. (Mode 0, Flag 17) Separate fees and bounce on action error {#mode17} State before the transaction: Account A has 1 TON, Account B has 1 TON -**A** sent 0.1 TON to **B**, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.1 TON, `fwd_fee` and `action_fee` deducted from `balance`. -In case of an error [during action phase](https://retracer.ton.org/?tx=e9dccba82badc0d742f14eff41c203280f380e87180b5314fcfd742856e598f7&testnet=true), the message will bounce and `total_fee` + `fwd_fee` will be deducted from `value`. +**A** sent 0.1 TON to **B**. The `msg_fwd_fees` are 0.004 TON, and the actual received value will be 0.1 TON. The `fwd_fee` and `action_fee` are deducted from the `balance`. +In case of an error [during the action phase](https://retracer.ton.org/?tx=e9dccba82badc0d742f14eff41c203280f380e87180b5314fcfd742856e598f7&testnet=true), the message will bounce and `total_fee` + `fwd_fee` will be deducted from `value`. State after the transaction with an error: Account A has 1 - ([total_fee](/v3/documentation/smart-contracts/transaction-fees/fees#basic-fees-formula) + `fwd_fee`) TON, Account B has 1 TON -![](/img/docs/message-modes-cookbook/send_regular_message_5_error.png) +

+
+ +
+

:::info tip -If no errors occur the result is the same as [`mode = 1`](#4-send-a-regular-message-with-separate-fees). +If no errors occur, the result is the same as [mode = 1](#mode1). ::: -![](/img/docs/message-modes-cookbook/send_regular_message_5_noerror.png) - -| Mode and Flags | Code | -| :------------------------------- | :-------------------------- | -| `mode` = 0, `flag` = 1 + 16 = 17 | `send_raw_message(msg, 17)` | - -## 6. Carry remaining value with new message +

+
+ +
+

+ +## 6. (Mode 64, Flag 0) Carry forward the remaining value {#mode64} State before the transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON -**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 64, `msg_fwd_fees` are 0.004 TON, actual received `value` will be 0.6 TON, total_fee + `fwd_fee` deducted from `value`. +**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 64, `msg_fwd_fees` are 0.004 TON, actual received `value` will be 0.6 TON, total_fee + `fwd_fee` are deducted from `value`. State after the transaction: Account A has 0.896 TON, Account B has 0.5 TON, Account C has 1.6 - (total_fee + `fwd_fee`) TON :::info -You might check [this example](https://retracer.ton.org/?tx=4340b5ecbd83227cc64e10b1ca7628352133cda1d608081fb2ed58d299f00936&testnet=true). -Please note that `storage_fee` is included in `total_fee` but it is always paid from contract `balance`. +You might check [this example](https://testnet.tonviewer.com/transaction/f63ab35f34e342cdd249f13018d5034ce3d80c488628d5a4db0a43163fa50adb). +Please note that `storage_fee` is included in `total_fee` but is always paid from the contract `balance`. ::: :::warning -Please note that `SENDRAWMSG` doesn't update balance. +Please note that `SENDRAWMSG` doesn't update the balance. -If you try to send multiple messages (i.e. mode 0 **and** mode 64) you'll get exit code 37. +If you try to send multiple messages (e.g., mode 0 **and** mode 64), you'll get exit code 37. ::: -![](/img/docs/message-modes-cookbook/carry_remaining_value_6.png) - -| Mode and Flags | Code | -| :--------------------- | :-------------------------- | -| `mode` = 64, no `flag` | `send_raw_message(msg, 64)` | - -## 7. Carry remaining value with a new message with separate fees +

+
+ +
+

+ +## 7. (Mode 64, Flag 1) Carry forward with separate fees {#mode65} State before the transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON -**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 65, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.6 TON, total_fee + `fwd_fee` deducted from `balance`. +**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 65, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.6 TON, total_fee + `fwd_fee` are deducted from `balance`. State after the transaction: Account A has 0.896 TON, Account B has 0.5 - (total_fee + `fwd_fee`) TON, Account C has 1.6 TON :::info -You might check [this example](https://retracer.ton.org/?tx=5c2525feeb3b93db594b7b11f3250430f02dd8616595cf2b1583ebc7da79d15b&testnet=true). -Please note that `storage_fee` is included in `total_fee` but it is always paid from contract `balance`. +You might check [this example](https://testnet.tonviewer.com/transaction/ad93e784453b573d737d9d928b4377ff3779177753e05629e54f6629556568ad). +Please note that `storage_fee` is included in `total_fee` but is always paid from the contract `balance`. ::: -![](/img/docs/message-modes-cookbook/carry_remaining_value_7.png) - -| Mode and Flags | Code | -| :---------------------- | :-------------------------- | -| `mode` = 64, `flag` = 1 | `send_raw_message(msg, 65)` | - -## 8. Carry remaining value and bounce the message on error +

+
+ +
+

+ +## 8. (Mode 64, Flag 16) Bounce‐protected carry forward {#mode80} State before the transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON -**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 80, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.6 TON, total_fee + `fwd_fee` deducted from `value`. -In case of an error during the action phase, the message will bounce and `total_fee` + `fwd_fee` will be deducted from `value`. +**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 80, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.6 TON, total_fee + `fwd_fee` are deducted from `value`. +If an error occurs during the action phase, the message will bounce, and `total_fee` + `fwd_fee` will be deducted from the `value`. State after the transaction with an error: Account A has 1 - (total_fee + `fwd_fee`) TON, Account B has 1 TON, Account C has 1 TON -![](/img/docs/message-modes-cookbook/carry_remaining_value_8_error.png) +

+
+ +
+

:::info tip -If no errors occur the result is the same as [`mode = 64`](#6-carry-remaining-value-with-new-message). This mode is widely used in TON for jetton transfers. You can [check it in C5 action list](https://retracer.ton.org/?tx=6489d60d9197c0be7ee64b0812139d82221e8f94c6e378c356acc10f9067310c) of the jetton wallet. +If no errors occur, the result is the same as [mode = 64, flag 0](#mode64). This mode is widely used in TON for jetton transfers. You can [check it in the C5 action list](https://retracer.ton.org/?tx=6489d60d9197c0be7ee64b0812139d82221e8f94c6e378c356acc10f9067310c) of the jetton wallet. ::: -![](/img/docs/message-modes-cookbook/carry_remaining_value_8_noerror.png) - -| Mode and Flags | Code | -| :----------------------- | :-------------------------- | -| `mode` = 64, `flag` = 16 | `send_raw_message(msg, 80)` | - -## 9. Carry the remaining value with a new message with separate fees and bounce the message on error +

+
+ +
+

+ +## 9. (Mode 64, Flag 17) Bounce‐protected carry forward with separate fees {#mode81} State before the transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON -**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 80, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.6 TON, total_fee + `fwd_fee` deducted from `balance`. -In case of an error during the action phase, the message will bounce and `total_fee` + `fwd_fee` will be deducted from `value`. +**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 81, `msg_fwd_fees` are 0.004 TON, actual received value will be 0.6 TON, total_fee + `fwd_fee` are deducted from `balance`. +If an error occurs during the action phase, the message will bounce, and `total_fee` + `fwd_fee` will be deducted from the `value`. -State after transaction with an error: Account A has 1 - (total_fee + `fwd_fee`) TON, Account B has 1 TON, Account C has 1 TON +State after the transaction with an error: Account A has 1 - (total_fee + `fwd_fee`) TON, Account B has 1 TON, Account C has 1 TON -![](/img/docs/message-modes-cookbook/carry_remaining_value_9_error.png) +

+
+ +
+

:::info tip -If no errors occur the result is the same as [`mode = 65`](#7-carry-remaining-value-with-new-message-with-separate-fees). +If no errors occur, the result is the same as [mode = 65](#mode65). ::: -![](/img/docs/message-modes-cookbook/carry_remaining_value_9_noerror.png) - -| Mode and Flags | Code | -| :--------------------------- | :-------------------------- | -| `mode` = 64, `flag` = 16 + 1 | `send_raw_message(msg, 81)` | - -## 10. Send all received tokens along with the contract balance +

+
+ +
+

+ +## 10. (Mode 128, Flag 0) Send whole balance {#mode128} State before the transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON -**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 128, `msg_fwd_fees` are 0.004 TON, actual received value will be 1.1 - total_fee TON, total_fee deducted from `value`. +**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 128, `msg_fwd_fees` are 0.004 TON, the actual received value will be 1.1 - total_fee TON, total_fee is deducted from `value`. State after the transaction: Account A has 0.896 TON, Account B has 0 TON, Account C has 2.1 - (total_fee + `fwd_fee`) TON -![](/img/docs/message-modes-cookbook/carry_remaining_value_10.png) - -| Mode and Flags | Code | -| :---------------------- | :--------------------------- | -| `mode` = 128, no `flag` | `send_raw_message(msg, 128)` | - -## 11. Send all received tokens along with the contract balance and bounce the message on error +

+
+ +
+

+ +## 11. (Mode 128, Flag 16) Send the whole balance bounce‐protected {#mode144} State before the transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON -**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 144, `msg_fwd_fees` are 0.004 TON, actual received value will be 1.1 - total_fee TON, total_fee deducted from `value`. +**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 144, `msg_fwd_fees` are 0.004 TON, the actual received value will be 1.1 - total_fee TON, total_fee is deducted from `value`. State after the transaction with an error: Account A has 1 - (total_fee + `fwd_fee`) TON, Account B has 1 TON, Account C has 1 TON -![](/img/docs/message-modes-cookbook/carry_remaining_value_11_error.png) +

+
+ +
+

:::info tip -If no errors occur the result is the same as [`mode = 128`](#10-send-all-received-tokens-together-with-the-contract-balance). This mode is widely used in TON for jetton transfers, you can [check it in C5 action list](https://retracer.ton.org/?tx=e4f31e37eec74a8cfcecdad9246a6bbf3da20c4edb3635150cb0fa54b9def558) of the jetton wallet. +If no errors occur, the result is the same as [mode = 128](#mode128). This mode is widely used in TON for jetton transfers. You can [check it in the C5 action list](https://retracer.ton.org/?tx=e4f31e37eec74a8cfcecdad9246a6bbf3da20c4edb3635150cb0fa54b9def558) of the jetton wallet. ::: -![](/img/docs/message-modes-cookbook/carry_remaining_value_11_noerror.png) - -| Mode and Flags | Code | -| :------------------------ | :--------------------------- | -| `mode` = 128, `flag` = 16 | `send_raw_message(msg, 144)` | - -## 12. Send all received tokens along with the contract balance and destroy the smart contract +

+
+ +
+

+ +## 12. (Mode 128, Flag 32) Send the whole balance and destroy the contract {#mode160} State before the transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON -**A** sent 0.1 TON to **B** after that **B** sent 0.5 TON to **C** with `mode` = 160, `msg_fwd_fees` are 0.004 TON, actual received value will be 1.1 - total_fee TON, total_fee deducted from `value`. +**A** sent 0.1 TON to **B**, and after that, **B** sent 0.5 TON to **C** with `mode` = 160. The `msg_fwd_fees` are 0.004 TON. The actual received value will be 1.1 - total_fee TON, with total_fee deducted from `value`. State after the transaction: Account A has 0.896 TON, Account B has 0 TON and `nonexist`, Account C has 2.1 - (total_fee + `fwd_fee`) TON When the balance reaches 0 TON, destroy the contract. -![](/img/docs/message-modes-cookbook/carry_remaining_value_12.png) - -| Mode and Flags | Code | -| :------------------------ | :--------------------------- | -| `mode` = 128, `flag` = 32 | `send_raw_message(msg, 160)` | +

+
+ +
+

+ +[cb]: https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/block.tlb#L263C1-L265C20 +[msg]: /v3/documentation/data-formats/tlb/msg-tlb#commonmsginfo +[storage_fee]: /v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee +[account_storage]: https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/transaction.cpp#L651-L675 +[in_msg_import]: https://github.com/ton-blockchain/ton/blob/7151ff26279fef6dcfa1f47fc0c5b63677ae2458/crypto/block/transaction.cpp#L783-L816 diff --git a/docs/v3/documentation/smart-contracts/tolk/changelog.md b/docs/v3/documentation/smart-contracts/tolk/changelog.md index 9b872301d6..f3f62f0da3 100644 --- a/docs/v3/documentation/smart-contracts/tolk/changelog.md +++ b/docs/v3/documentation/smart-contracts/tolk/changelog.md @@ -3,6 +3,12 @@ When new versions of Tolk are released, they will be mentioned here. +## v0.8 + +1. Syntax `tensorVar.0` and `tupleVar.0` (both for reading and writing) +2. Allow `cell`, `slice`, etc. to be valid identifiers (not keywords) + + ## v0.7 1. Under the hood: refactor compiler internals; AST-level semantic analysis kernel @@ -11,8 +17,6 @@ When new versions of Tolk are released, they will be mentioned here. 4. Generic functions `fun f(...)` and instantiations like `f(...)` 5. The `bool` type; type casting via `value as T` -More details [on GitHub](todo). - ## v0.6 diff --git a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx index c3a413c6f9..1ecfeee6c0 100644 --- a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx +++ b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx @@ -59,6 +59,8 @@ In Tolk, spaces are not mandatory. `2+2` is 4, as expected. `3+~x` is `3 + (~ x) More precisely, an identifier can start from {'[a-zA-Z$_]'} and be continued with {'[a-zA-Z0-9$_]'}. Note, that `?`, `:`, and others are not valid symbols, `found?` and `op::increase` are not valid identifiers. +Note, that `cell`, `slice`, etc. are valid identifiers: `var cell = ...` or even `var cell: cell = ...` is okay. (like in TypeScript, `number` is a valid identifier) + You can use backticks to surround an identifier, and then it can contain any symbols (similar to Kotlin and some other langs). Its potential usage is to allow keywords be used as identifiers, in case of code generation by a scheme, for example. @@ -324,7 +326,7 @@ We have the following types: - `int`, `bool`, `cell`, `slice`, `builder`, untyped `tuple` - typed tuple `[T1, T2, ...]` - tensor `(T1, T2, ...)` -- callables `fun(TArgs) -> TResult` +- callables `(TArgs) -> TResult` - `void` (more canonical to be named `unit`, but `void` is more reliable) - `self`, to make chainable methods, described below; actually it's not a type, it can only occur instead of return type of a function @@ -458,7 +460,7 @@ duplicate((1, 2)); // duplicate<(int, int)> Or even functions, it also works: ```tolk -fun callAnyFn(f: fun(TObj) -> TResult, arg: TObj) { +fun callAnyFn(f: TObj -> TResult, arg: TObj) { return f(arg); } @@ -973,6 +975,55 @@ Keywords `ifnot` and `elseifnot` were removed, since now we have logical not (fo Remember, that a boolean `true`, transformed `as int`, is -1, not 1. It's a TVM representation. +

+ ✅ Indexed access `tensorVar.0` and `tupleVar.0` +

+ +Use `tensorVar.{i}` to access i-th component of a tensor. Modifying it will change the tensor. +```tolk +var t = (5, someSlice, someBuilder); // 3 stack slots +t.0 // 5 +t.0 = 10; // t is now (10, ...) +t.0 += 1; // t is now (11, ...) +increment(mutate t.0); // t is now (12, ...) +t.0.increment(); // t is now (13, ...) + +t.1 // slice +t.100500 // compilation error +``` + +Use `tupleVar.{i}` to access i-th element of a tuple (does INDEX under the hood). Modifying it will change the tuple (does SETINDEX under the hood). +```tolk +var t = [5, someSlice, someBuilder]; // 1 tuple on a stack with 3 items +t.0 // "0 INDEX", reads 5 +t.0 = 10; // "0 SETINDEX", t is now [10, ...] +t.0 += 1; // also works: "0 INDEX" to read 10, "0 SETINDEX" to write 11 +increment(mutate t.0); // also, the same way +t.0.increment(); // also, the same way + +t.1 // "1 INDEX", it's slice +t.100500 // compilation error +``` + +It also works for untyped tuples, though the compiler can't guarantee index correctness. +```tolk +var t = createEmptyTuple(); +t.tuplePush(5); +t.0 // will head 5 +t.0 = 10 // t will be [10] +t.100500 // will fail at runtime +``` + +It works for nesting `var.{i}.{j}`. It works for nested tensor, nested tuples, tuples nested into tensors. +It works for `mutate`. It works for globals. +```tolk +t.1.2 = 10; // "1 INDEX" + "2 SETINDEX" + "1 SETINDEX" +t.1.2 += 10; // "1 INDEX" + "2 INDEX" + sum + "2 SETINDEX" + "1 SETINDEX" + +globalTuple.1.2 += 10; // "GETGLOB" + ... + "SETGLOB" +``` + +

✅ No tilda `~` methods, `mutate` keyword instead

diff --git a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md index 1442122fac..d79a87a8e9 100644 --- a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md +++ b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md @@ -22,7 +22,7 @@ get currentCounter(): int { ... } ``` 2. No `impure`, it's by default, compiler won't drop user function calls 3. Not `recv_internal` and `recv_external`, but `onInternalMessage` and `onExternalMessage` -4. `2+2` is 4, not an identifier; identifiers are alpha-numeric; use naming `const OP_INCREASE` instead of `const op::increase` +4. `2+2` is 4, not an identifier; identifiers are alpha-numeric; use naming `const OP_INCREASE` instead of `const op::increase`; `cell` and `slice` are valid identifiers (not keywords) 5. Logical operators AND `&&`, OR `||`, NOT `!` are supported 6. Syntax improvements: - `;; comment` → `// comment` @@ -46,6 +46,7 @@ get currentCounter(): int { ... } 9. No `~` tilda methods; `cs.loadInt(32)` modifies a slice and returns an integer; `b.storeInt(x, 32)` modifies a builder; `b = b.storeInt()` also works, since it not only modifies, but returns; chained methods work identically to JS, they return `self`; everything works exactly as expected, similar to JS; no runtime overhead, exactly same Fift instructions; custom methods are created with ease; tilda `~` does not exist in Tolk at all; [more details here](/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability) 10. Clear and readable error messages on type mismatch 11. `bool` type support +12. Indexed access `tensorVar.0` and `tupleVar.0` support #### Tooling around - JetBrains plugin exists diff --git a/docs/v3/documentation/tvm/tvm-exit-codes.md b/docs/v3/documentation/tvm/tvm-exit-codes.md index 183e20544f..0fcb8ec4f6 100644 --- a/docs/v3/documentation/tvm/tvm-exit-codes.md +++ b/docs/v3/documentation/tvm/tvm-exit-codes.md @@ -1,43 +1,499 @@ -# TVM Exit codes +--- +title: Exit codes +--- -If TVM exits with an arbitrary 16-bit unsigned integer `exit_code`. `exit_code` higher than 1, it is considered an _error code_. Therefore, an exit with such a code may cause the transaction to revert or bounce. +Each transaction on the TON Blockchain comprises [multiple phases](/v3/documentation/tvm/tvm-overview#transactions-and-phases). An _exit code_ is a 32-bit signed integer that indicates whether the [compute](#compute) or [action](#action) phase succeeded. When unsuccessful, it contains the exception code that occurred. Each exit code represents a specific exception or transaction outcome. -## Standard exit codes +Exit codes 0 and 1 indicate standard (successful) execution of the [compute phase](#compute). Exit (or [result](#action)) code 0 indicates the standard (successful) execution of the [action phase](#action). Any other exit code indicates that a specific exception has occurred and that the transaction wasn't successful in one way or another, i.e., the transaction was reverted or the inbound message has bounced back. -:::info -The list of standard exit codes contains all universal TVM exit codes defined for the TON Blockchain. Alternative exit codes should be sought in the source code of the corresponding contract. +> TON Blockchain reserves exit code values from 0 to 127, while Tact utilizes exit codes from 128 to 255. Note that exit codes used by Tact indicate contract errors, which can occur when using Tact-generated FunC code and are therefore thrown in the transaction's [compute phase](#compute) and not during the compilation. + +The range from 256 to 65535 is free for developer-defined exit codes. + +:::note +While exit codes are 32-bit signed integers in the TON, attempting to throw an exit code outside the 16-bit unsigned integer range (0-65535) will trigger an error with [exit code 5](#5). This intentionally prevents the artificial generation of specific exit codes like [-14](#-14). ::: -| Exit Code | TVM Phase | Description | -|-----------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `0` | Compute Phase | Standard successful execution exit code. | -| `1` | Compute Phase | Alternative successful execution exit code. | -| `2` | Compute Phase | Stack underflow. The last op-code consumed more elements than there are on the stacks. 1 | -| `3` | Compute Phase | Stack overflow. More values have been stored on a stack than are allowed by this version of TVM. | -| `4` | Compute Phase | Integer overflow. Integer does not fit into −2256 ≤ x < 2256 or a division by zero has occurred. | -| `5` | Compute Phase | Integer is out of expected range. | -| `6` | Compute Phase | Invalid opcode. The instruction is unknown in the current TVM version. | -| `7` | Compute Phase | Type check error. An argument to a primitive has an incorrect value type. 1 | -| `8` | Compute Phase | Cell overflow. Writing to the builder is not possible since after operation there would be more than 1023 bits or 4 references. | -| `9` | Compute Phase | Cell underflow. The read operation from slice primitive tried to read more bits or references than available. | -| `10` | Compute Phase | Dictionary error. An error during manipulation with the dictionary (hashmaps). | -| `11` | Compute Phase | Most often caused by trying to call get-method whose id wasn't found in the code (missing `method_id` modifier or wrong get-method name specified when trying to call it). In [TVM docs](https://ton.org/tvm.pdf) its described as "Unknown error, may be thrown by user programs". | -| `12` | Compute Phase | Thrown by TVM in situations considered impossible. | -| `13` | Compute Phase | Out of gas error. Thrown by TVM when the remaining gas turns negative. | -| `-14` | Compute Phase | This indicates an out of gas error, the same as code `13`. It is negative because it [cannot be faked](https://github.com/ton-blockchain/ton/blob/20758d6bdd0c1327091287e8a620f660d1a9f4da/crypto/vm/vm.cpp#L492) | -| `32` | Action Phase | Action list is invalid. Set during the action phase if c5 register after execution contains unparsable object. | -| `-32` | Action Phase | (the same as prev 32) - Method ID not found. Returned by TonLib during an attempt to execute non-existent get method. | -| `33` | Action Phase | The action list is too long. | -| `34` | Action Phase | Action is invalid or not supported. Set during the action phase if current action cannot be applied. | -| `35` | Action Phase | Invalid Source address in the outbound message. | -| `36` | Action Phase | Invalid Destination address in the outbound message. | -| `37` | Action Phase | Not enough TON. The message sends too much TON, or there isn't enough TON remaining after deducting fees. | -| `38` | Action Phase | Not enough extra-currencies. | -| `40` | Action Phase | Not enough funds to process the message. This error is thrown when there is only enough gas to partially cover the message, but not enough to cover it completely. | -| `43` | Action Phase | The maximum number of cells in the library has been exceeded, or the maximum depth of the Merkle tree has been surpassed. | - -1 If you encounter such exception in a func contract it probably means a type error in asm declarations. - -:::info -Often you can see the exit code `0xffff` (65535 in decimal form). This usually means that the received opcode is unknown to the contract. When writing contracts, this code is set by the developer himself. +## Table of exit codes {#standard-exit-codes} + +The following table lists exit codes with an origin (where it can occur) and a short description. The table doesn't list the exit codes from contracts. To see such exit codes, refer to the source code of the specific contract. + +| Exit code | Origin | Brief description | +| :-------- | :------------------------------------- | :----------------------------------------------------------------------------------------------------- | +| 0 | [Compute][c] and [action][a] phases | Standard successful execution exit code. | +| 1 | [Compute phase][c] | Alternative successful execution exit code. Reserved, but doesn't occur. | +| 2 | [Compute phase][c] | Stack underflow. | +| 3 | [Compute phase][c] | Stack overflow. | +| 4 | [Compute phase][c] | Integer overflow. | +| 5 | [Compute phase][c] | Range check error — some integer is out of its expected range. | +| 6 | [Compute phase][c] | Invalid [TVM][tvm] opcode. | +| 7 | [Compute phase][c] | Type check error. | +| 8 | [Compute phase][c] | Cell overflow. | +| 9 | [Compute phase][c] | Cell underflow. | +| 10 | [Compute phase][c] | Dictionary error. | +| 11 | [Compute phase][c] | As described in [TVM][tvm] documentation: "Unknown error, may be thrown by user programs" | +| 12 | [Compute phase][c] | Fatal error thrown by [TVM][tvm] in unexpected situations | +| 13 | [Compute phase][c] | Out of gas error. | +| -14 | [Compute phase][c] | Equivalent to code 13. A negative value prevents [imitation](#13) | +| 14 | [Compute phase][c] | VM virtualization error (reserved but unused) | +| 32 | [Action phase][a] | Action list is invalid. | +| 33 | [Action phase][a] | Action list is too long. | +| 34 | [Action phase][a] | Action is invalid or not supported. | +| 35 | [Action phase][a] | Invalid source address in outbound message. | +| 36 | [Action phase][a] | Invalid destination address in outbound message. | +| 37 | [Action phase][a] | Not enough Toncoin. | +| 38 | [Action phase][a] | Not enough extra currencies. | +| 39 | [Action phase][a] | Outbound message does not fit into a cell after rewriting. | +| 40 | [Action phase][a] | Cannot process a message — not enough funds, the message is too large, or its Merkle depth is too big. | +| 41 | [Action phase][a] | Library reference is null during library change action. | +| 42 | [Action phase][a] | Library change action error. | +| 43 | [Action phase][a] | Exceeded the maximum number of cells in the library or the maximum depth of the Merkle tree. | +| 50 | [Action phase][a] | Account state size exceeded limits. | +| 128 | Tact compiler ([Compute phase][c]) | Null reference exception. Configurable since Tact 1.6 (not released yet). | +| 129 | Tact compiler ([Compute phase][c]) | Invalid serialization prefix. | +| 130 | Tact compiler ([Compute phase][c]) | Invalid incoming message — there's no receiver for the opcode of the received message. | +| 131 | Tact compiler ([Compute phase][c]) | Constraints error. Reserved, but never thrown. | +| 132 | Tact compiler ([Compute phase][c]) | Access denied — someone other than the owner sent a message to the contract. | +| 133 | Tact compiler ([Compute phase][c]) | Contract stopped. Reserved, but never thrown. | +| 134 | Tact compiler ([Compute phase][c]) | Invalid argument. | +| 135 | Tact compiler ([Compute phase][c]) | Code of a contract was not found. | +| ~~136~~ | ~~Tact compiler ([Compute phase][c])~~ | ~~Invalid address.~~ Removed since Tact 1.6 (not released yet) | +| ~~137~~ | ~~Tact compiler ([Compute phase][c])~~ | ~~Masterchain support is not enabled for this contract.~~ Removed since Tact 1.6 (not released yet) | + +:::note +The exit code 65535 (`0xffff`) typically indicates the same issue as exit code `130` - an unrecognized message opcode. It is assigned manually when developing contracts rather than generated by [TVM][tvm] or the Tact compiler. ::: + +## Exit codes in Blueprint projects {#blueprint} + +In [Blueprint][bp] tests, exit codes from the [compute phase](#compute) are specified in the `exitCode` field of the object argument for the `toHaveTransaction()` method of the `expect()` matcher. The field for the result codes (exit codes from the [action phase](#action)) in the same `toHaveTransaction()` method is called `actionResultCode`. + +Note that to do so, you'll have to do a couple of type checks before that: + +```typescript +it('tests something, you name it', async () => { + // Send a specific message to our contract and store the results + const res = await your_contract_name.send(…); + + // Now, we have access to an array of executed transactions, + // with the second one (index 1) being the one that we look for + const tx = res.transactions[1]!; + + // To do something useful with it, let's ensure that its type is 'generic' + // and that the compute phase wasn't skipped + if (tx.description.type === "generic" + && tx.description.computePhase.type === "vm") { + // Finally, we're able to peek into the transaction for general details freely, + // such as printing out the exit code of the compute phase if we so desire + console.log(tx.description.computePhase.exitCode); + } + + // ... +}); +``` + +## Compute phase {#compute} + +The [TVM][tvm] initialization and all computations occur during the [compute phase][c]. If this phase fails (resulting in an exit code other than 0 or 1), the transaction skips the [action phase](#action) and proceeds to generate bounce messages for transactions initiated by inbound messages. + +### 0: Normal termination {#0} + +This exit (or [result](#action)) code indicates a successful completion of the [compute](#compute) (or [action](#action)) phase of the transaction. + +### 1: Alternative termination {#1} + +This is an alternative exit code for successfully executing the [compute phase](#compute). Reserved, but never occurs. + +### 2: Stack underflow {#2} + +If some operation consumed more elements than there were on the stack, the error with exit code 2 is thrown: `Stack underflow`. + +```tact +asm fun drop() { DROP } + +contract Loot { + receive("I solemnly swear that I'm up to no good") { + try { + // Removes 100 elements from the stack, causing an underflow + repeat (100) { drop() } + } catch (exitCode) { + // exitCode is 2 + } + } +} +``` + +### 3: Stack overflow {#3} + +When you copy too many elements into a closure continuation, the system throws an error with exit code 3: `Stack overflow`. This error rarely occurs unless you work deep in [Fift and TVM assembly][fift] trenches. + +```tact +// Remember, kids, don't try to overflow the stack at home! +asm fun stackOverflow() { + x{} SLICE // s + BLESS // c + 0 SETNUMARGS // c' + 2 PUSHINT // c' 2 + SWAP // 2 c' + 1 -1 SETCONTARGS // ← this blows up +} + +contract ItsSoOver { + receive("I solemnly swear that I'm up to no good") { + try { + stackOverflow(); + } catch (exitCode) { + // exitCode is 3 + } + } +} +``` + +### 4: Integer overflow {#4} + +If the value in calculation goes beyond the range from `-2^{256} to 2^{256} - 1` inclusive, or there's an attempt to divide or modulo by zero, an error with exit code 4 is thrown: `Integer overflow`. + +```tact +let x = -pow(2, 255) - pow(2, 255); // -2^{256} + +try { + -x; // integer overflow by negation + // since the max positive value is 2^{256} - 1 +} catch (exitCode) { + // exitCode is 4 +} + +try { + x / 0; // division by zero! +} catch (exitCode) { + // exitCode is 4 +} + +try { + x * x * x; // integer overflow! +} catch (exitCode) { + // exitCode is 4 +} + +// There can also be an integer overflow when doing: +// addition (+), +// subtraction (-), +// division (/) by a negative number or modulo (%) by zero +``` + +### 5: Integer out of expected range {#5} + +Range check error — some integers are out of their expected range. Any attempt to store an unexpected amount of data or specify an out-of-bounds value throws an error with exit code 5: `Integer out of expected range`. + +Examples of specifying an out-of-bounds value: + +```tact +try { + // Repeat only operates on an inclusive range from 1 to 2^{31} - 1 + // and any valid integer value greater than that causes an error with exit code 5 + repeat (pow(2, 55)) { + dump("smash. logs. I. must."); + } +} catch (exitCode) { + // exitCode is 5 +} + +try { + // Builder.storeUint() function can only use up to 256 bits, so 512 is too much: + let s: Slice = beginCell().storeUint(-1, 512).asSlice(); +} catch (exitCode) { + // exitCode is 5 +} +``` + +### 6: Invalid opcode {#6} + +If you specify an instruction that the current [TVM][tvm] version does not define or try to set an unsupported [code page](/v3/documentation/tvm/tvm-overview#tvm-state), the system throws an error with exit code 6: `Invalid opcode`. + +```tact +// There's no such codepage, and attempt to set it fails +asm fun invalidOpcode() { 42 SETCP } + +contract OpOp { + receive("I solemnly swear that I'm up to no good") { + try { + invalidOpcode(); + } catch (exitCode) { + // exitCode is 6 + } + } +} +``` + +### 7: Type check error {#7} + +If an argument to a primitive is of an incorrect value type or there's any other mismatch in types during the [compute phase](#compute), an error with exit code 7 is thrown: `Type check error`. + +```tact +// The actual returned value type doesn't match the declared one +asm fun typeCheckError(): map { 42 PUSHINT } + +contract VibeCheck { + receive("I solemnly swear that I'm up to no good") { + try { + // The 0th index doesn't exist + typeCheckError().get(0)!!; + } catch (exitCode) { + // exitCode is 7 + } + } +} +``` + +### 8: Cell overflow {#8} + +> `Cell` is a [primitive][p] and a data structure, which ordinarly consists of up to 1023 continuously laid out bits and up to 4 references (refs) to other cells. + +A 'Builder' is utilized to create a 'Cell'. If you attempt to store more than 1023 bits of data or exceed 4 references to other cells, an error with exit code 8 is thrown: 'Cell overflow'. + +```tact +// Too much bits +try { + let data = beginCell() + .storeInt(0, 250) + .storeInt(0, 250) + .storeInt(0, 250) + .storeInt(0, 250) + .storeInt(0, 24) // 1024 bits! + .endCell(); +} catch (exitCode) { + // exitCode is 8 +} + +// Too much refs +try { + let data = beginCell() + .storeRef(emptyCell()) + .storeRef(emptyCell()) + .storeRef(emptyCell()) + .storeRef(emptyCell()) + .storeRef(emptyCell()) // 5 refs! + .endCell(); +} catch (exitCode) { + // exitCode is 8 +} +``` + +### 9: Cell underflow {#9} + +> `Cell` is a [primitive][p] and a data structure, which ordinarly consists of up to 1023 continuously laid out bits and up to 4 references (refs) to other cells. + +To parse a `Cell`, a `Slice` is used. If you try to load more data or references than `Slice` contains, an error with exit code 9 is thrown: `Cell underflow`. + +```tact +// Too few bits +try { + emptySlice().loadInt(1); // 0 bits! +} catch (exitCode) { + // exitCode is 9 +} + +// Too few refs +try { + emptySlice().loadRef(); // 0 refs! +} catch (exitCode) { + // exitCode is 9 +} +``` + +### 10: Dictionary error {#10} + +In Tact, the `map` type is an abstraction over the ["hash" map dictionaries of FunC](/v3/documentation/smart-contracts/func/docs/dictionaries#hashmap) and underlying [`HashmapE` type](/v3/documentation/data-formats/tlb/tl-b-types#hashmap) of [TL-B][tlb] and [TVM][tvm]. + +If there is an incorrect manipulation of dictionaries, such as improper assumptions about their memory layout, an error with exit code 10 is thrown: `Dictionary error`. Note that Tact prevents you from getting this error unless you do [Fift and TVM assembly][fift] work yourself: + +```tact +/// Pre-computed Int to Int dictionary with two entries — 0: 0 and 1: 1 +const cellWithDictIntInt: Cell = cell("te6cckEBBAEAUAABAcABAgPQCAIDAEEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAQQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMLMbT1U="); + +/// Tries to preload a dictionary from a Slice as a map +asm fun toMapIntCell(x: Slice): map { PLDDICT } + +contract DictPic { + receive("I solemnly swear that I'm up to no good") { + try { + // The code misinterprets the Int to Int dictionary as a map + let m: map = toMapIntCell(cellWithDictIntInt.beginParse()); + + //The error happens only when we touch it + m.get(0)!!; + } catch (exitCode) { + // exitCode is 10 + } + } +} +``` + +### 11: "Unknown" error {#11} + +Described in [TVM][tvm] docs as "Unknown error, may be thrown by user programs", although most commonly used for problems with queueing a message send or problems with [get-methods](/v3/guidelines/smart-contracts/get-methods). + +```tact +try { + // Unlike nativeSendMessage, which uses SENDRAWMSG, this one uses SENDMSG, + // and therefore fails in the Compute phase when the message is ill-formed + nativeSendMessageReturnForwardFee(emptyCell(), 0); +} catch (exitCode) { + // exitCode is 11 +} +``` + +### 12: Fatal error {#12} + +Fatal error. Thrown by TVM in situations deemed impossible. + +### 13: Out of gas error {#13} + +If there isn't enough gas to end computations in the [compute phase](#compute), the error with exit code 13 is thrown: `Out of gas error`. + +But this code isn't immediately shown as is. Instead, the bitwise NOT operation is applied, changing the value from `13` to `-14`. Only then is the code shown. + +This design prevents user contracts from artificially producing the `-14` code since all functions that throw exit codes can only specify integers ranging from `0 to 65535` inclusive. + +```tact +try { + repeat (pow(2, 31) - 1) {} +} catch (exitCode) { + // exitCode is -14 +} +``` + +### -14: Out of gas error {#-14} + +See [exit code 13](#13). + +### 14: Virtualization error {#14} + +Virtualization error related to [prunned branch cells](/v3/documentation/data-formats/tlb/exotic-cells#pruned-branch). Reserved, but never thrown. + +## Action phase {#action} + +The [action phase][a] is processed after the successful execution of the [compute phase](#compute). It attempts to perform the actions stored in the action list by [TVM][tvm] during the compute phase. + +Some actions may fail during processing, in which case the system may skip them or revert the entire transaction, depending on the action modes. Developers call the code that indicates the resulting state of the [action phase][a] a _result code_. Since this code serves the same purpose as the compute phase's exit code, developers commonly refer to it as an exit code too. + +### 32: Action list is invalid {#32} + +If the list of actions contains [exotic cells][exotic], an action entry cell does not have references, or some action entry cell couldn't be parsed, an error with exit code 32 is thrown: `Action list is invalid`. + +Aside from this exit code, there's a boolean flag `valid`, which you can find under `description.actionPhase.valid` in the transaction results when working with [Sandbox and Blueprint](#blueprint). The transaction can set this flag to `false` even when the action phase throws some other exit code. + +### 33: Action list is too long {#33} + +If you queue more than 255 actions for execution, the [action phase](#action) throws an error with exit code 33: `Action list is too long`. + +```tact +// For example, let's attempt to queue reservations of a specific amount of nanoToncoins +// This won't fail in the compute phase but will result in exit code 33 in the action phase +repeat (256) { + nativeReserve(ton("0.001"), ReserveAtMost); +} +``` + +### 34: Invalid or unsupported action {#34} + +Currently, only four actions are supported: changing the contract code, sending a message, reserving a specific amount of `nanoToncoins`, and changing the library cell. If there's any issue with the specified action (invalid message, unsupported action, etc.), an error with exit code 34 is thrown: `Invalid or unsupported action`. + +```tact +// For example, let's try to send an ill-formed message: +nativeSendMessage(emptyCell(), 0); // won't fail in compute phase, + // but will result in exit code 34 in the action phase +``` + +### 35: Invalid source address in outbound message {#35} + +If the source address in the outbound message isn't equal to [`addr_none`](/v3/documentation/data-formats/tlb/msg-tlb#addr_none00) or to the address of the contract that initiated this message, an error with exit code 35 is thrown: `Invalid source address in the outbound message`. + +### 36: Invalid destination address in outbound message {#36} + +Suppose the destination address in the outbound message is invalid. In that case, e.g., it doesn't conform to the relevant [TL-B][tlb] schemas, contains an unknown workchain ID, or has an invalid length for the given workchain, an error with exit code 36 is thrown: `Invalid destination address in the outbound message`. + +:::note +If the [optional flag +2][flag2] is set, this error will not be thrown, and the given message will not be sent. +::: + +### 37: Not enough Toncoin {#37} + +If all funds of the inbound message with [mode 64](/v3/documentation/smart-contracts/message-management/message-modes-cookbook#mode64) had been already consumed and there's not enough funds to pay for the failed action, or the [TL-B][tlb] layout of the provided value ([`CurrencyCollection`](/v3/documentation/data-formats/tlb/msg-tlb#currencycollection)) is invalid, or there are not enough funds to pay forward fees or not enough funds after deducting fees, an error with exit code 37 is thrown: `Not enough Toncoin`. + +:::note +If the [optional flag +2][flag2] is set, this error will not be thrown, and the given message will not be sent. +::: + +### 38: Not enough extra currencies {#38} + +Besides the native currency, Toncoin, TON Blockchain supports up to 2^{32} extra currencies. They differ from making new jettons because extra currencies are natively supported — one can potentially specify an extra [`HashmapE`](/v3/documentation/data-formats/tlb/tl-b-types#hashmap) of extra currency amounts in addition to the Toncoin amount in the internal message to another contract. Unlike Jettons, extra currencies can only be stored and transferred and do not have any other functionality. + +Currently, **there are no extra currencies** on TON Blockchain, but the exit code 38 is reserved for cases when there is not enough extra currency to send the specified amount: `Not enough extra currencies`. + +:::note +[Extra currencies](/v3/documentation/dapps/defi/coins) in TON Docs. + +[Extra currency mining](/v3/documentation/infra/minter-flow) in TON Docs. +::: + +### 39: Outbound message doesn't fit into a cell {#39} + +When processing the message, TON Blockchain tries to pack it according to the [relevant TL-B schemas](/v3/documentation/data-formats/tlb/msg-tlb). If it cannot, an error with exit code 39 is thrown: `Outbound message doesn't fit into a cell`. + +:::note +If the [optional flag +2][flag2] is set, this error will not be thrown, and the given message will not be sent. +::: + +### 40: Cannot process a message {#40} + +If there are insufficient funds to process all the cells in a message, the message is too large, or its Merkle depth is too big, an error with exit code 40 is thrown: `Cannot process a message`. + +:::note +If the [optional flag +2][flag2] is set, this error will not be thrown, and the given message will not be sent. +::: + +### 41: Library reference is null {#41} + +If the library reference was required during the library change action but was null, an error with exit code 41 is thrown: `Library reference is null`. + +### 42: Library change action error {#42} + +If an error occurs during an attempt to perform a library change action, an error with exit code 42 is thrown: `Library change action error`. + +### 43: Library limits exceeded {#43} + +Suppose the maximum number of cells in the library or the maximum depth of the Merkle tree is exceeded. In that case, an error with exit code 43 is thrown: `Library limits exceeded`. + +### 50: Account state size exceeded limits {#50} + +If the account state (contract storage, essentially) exceeds any of the limits specified in [config param 43 of TON Blockchain](/v3/documentation/network/configs/blockchain-configs#param-43) by the end of the [action phase](#action), an error with exit code `50` is thrown: `Account state size exceeded limits`. + +If the configuration is absent, the default values are: + +- `max_msg_bits` equals `2^{21}` — maximum message size in bits. +- `max_msg_cells` equals `2^{13}` — maximum number of cells a message can occupy. +- `max_library_cells` equals `1000` — maximum number of cells that can be used as [library reference cells][lib]. +- `max_vm_data_depth` equals `2^{9}` — maximum cells depth in messages and account state. +- `ext_msg_limits.max_size` equals `65535` — maximum external message size in bits. +- `ext_msg_limits.max_depth` equals `2^{9}` — maximum external message depth. +- `max_acc_state_cells` equals `2^{16}` — maximum number of cells an account state can occupy. +- `max_acc_state_bits` equals `2^{16} * 1023` — maximum account state size in bits. +- `max_acc_public_libraries` equals `2^{8}` — maximum number of [library reference cells][lib] that an account state can use on the masterchain. +- `defer_out_queue_size_limit` equals `2^{8}` — maximum number of outbound messages to be queued (regards validators and collators). + +## Tact compiler + +Tact utilizes exit codes from `128` to `255`. Note that exit codes used by Tact indicate contract errors that can occur when using Tact-generated FunC code and are therefore thrown in the transaction's [compute phase](#compute) and not during the compilation. + +The list of exit codes for the Tact compiler is in the [Tact docs](https://docs.tact-lang.org/book/exit-codes/#tact-compiler). + +[c]: /v3/documentation/tvm/tvm-overview#compute-phase +[a]: /v3/documentation/tvm/tvm-overview#transactions-and-phases +[flag2]: /v3/documentation/smart-contracts/message-management/message-modes-cookbook#mode2 +[tlb]: /v3/documentation/data-formats/tlb/tl-b-language +[lib]: /v3/documentation/data-formats/tlb/exotic-cells#library-reference +[p]: /v3/documentation/smart-contracts/func/docs/types#atomic-types +[tvm]: /v3/documentation/tvm/tvm-overview +[bp]: https://github.com/ton-org/blueprint +[fift]: /v3/documentation/fift/fift-and-tvm-assembly diff --git a/docs/v3/guidelines/dapps/asset-processing/payments-processing.md b/docs/v3/guidelines/dapps/asset-processing/payments-processing.md index a6ca079f67..6c767930cd 100644 --- a/docs/v3/guidelines/dapps/asset-processing/payments-processing.md +++ b/docs/v3/guidelines/dapps/asset-processing/payments-processing.md @@ -5,47 +5,46 @@ import TabItem from '@theme/TabItem'; # Payments Processing -This page **explains how to process** (send and accept) `digital assets` on the TON blockchain. -It **mostly** describes how to work with `TON coins`, but **theoretical part** is **important** even if you want to process only `jettons`. +This page **explains how to process** (send and accept) digital assets on TON Blockchain. While it primarily focuses on handling TON coins, the **theoretical concepts** are also relevant for processing `jettons`. :::tip -It's recommended to get acquainted with [Asset Processing Overview](/v3/documentation/dapps/assets/overview) before reading this tutorial. +It's recommended to review the [Asset Processing Overview](/v3/documentation/dapps/assets/overview) before reading this tutorial. ::: ## Wallet smart contract -Wallet smart contracts on the TON Network allow external actors to interact with blockchain entities. -* Authenticates the owner: Rejects requests that attempt to process or pay fees on behalf of non-owners. -* Provides replay protection: Prevents the repeated execution of the same request, such as sending assets to another smart contract. -* Initiates arbitrary interactions with other smart contracts. +Wallet smart contracts on the TON Network allow external actors to interact with blockchain entities. They serve the following purposes:* Authenticates the owner: +* Authenticating the owner: Rejects requests that attempt to process transactions or pay fees on behalf of unauthorized users. +* Providing replay protection: Prevents the repeated execution of the same request, such as sending assets to another smart contract multiple times. +* Initiating arbitrary interactions with other smart contracts. -Standard solution for the first challenge is public-key cryptography: `wallet` stores the public key and checks that an incoming message with a request is signed by the corresponding private key which is known only by the owner. +The standard solution for authentication relies on public-key cryptography. The `wallet` stores the public key and verifies that any incoming request is signed by the corresponding private key, which is known only to the owner. -The solution to the third challenge is also common; generally, a request contains a fully formed inner message that the `wallet` sends to the network. However, for replay protection, there are a few different approaches. +The solution for replay protection varies. Generally, a request contains a fully formed inner message that the `wallet` sends to the network. However, different approaches exist for preventing replay attacks. ### Seqno-based wallets -Seqno-based wallets use the simplest approach to sequencing messages. Each message has a special `seqno` integer that must coincide with the counter stored in the `wallet` smart contract. `wallet` updates its counter on each request, thus ensuring that one request will not be processed twice. There are a few `wallet` versions that differ in publicly available methods: the ability to limit requests by expiration time, and the ability to have multiple wallets with the same public key. However, an inherent requirement of that approach is to send requests one by one, since any gap in `seqno` sequence will result in the inability to process all subsequent requests. +Seqno-based wallets use a simple `seqno` method to process messages. Each message includes a special seqno integer that must match the counter stored in the wallet smart contract. The `wallet` updates this counter with each request, ensuring that no request is processed twice. There are multiple versions of seqno-based wallets, which may differ in publicly available methods. These variations include: the ability to limit requests by expiration time and the ability to operate multiple wallets with the same public key. However, this approach has a limitation: requests must be sent sequentially. Any gap in the `seqno` sequence will prevent the processing of all subsequent requests. ### High-load wallets -This `wallet` type follows an approach based on storing the identifier of the non-expired processed requests in smart-contract storage. In this approach, any request is checked for being a duplicate of an already processed request and, if a replay is detected, dropped. Due to expiration, the contract may not store all requests forever, but it will remove those that cannot be processed due to the expiration limit. Requests to this `wallet` can be sent in parallel without interference, but this approach requires more sophisticated monitoring of request processing. +High-load wallets take a different approach by storing the identifiers of non-expired processed requests in the smart contract’s storage. Each new request is checked against previously processed ones, and any detected duplicates are dropped. Since expired requests are removed over time, the contract does not store all requests indefinitely. This method allows multiple requests to be processed in parallel without interference. However, it requires more sophisticated monitoring to track request processing. ### Wallet deployment -To deploy a wallet via TonLib, one needs to: -1. Generate a private/public key pair via [createNewKey](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L244) or its wrapper functions (example in [tonlib-go](https://github.com/mercuryoio/tonlib-go/tree/master/v2#create-new-private-key)). Note that the private key is generated locally and does not leave the host machine. -2. Form [InitialAccountWallet](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L62) structure corresponding to one of the enabled `wallets`. Currently `wallet.v3`, `wallet.v4`, `wallet.highload.v1`, `wallet.highload.v2` are available. -3. Calculate the address of a new `wallet` smart contract via the [getAccountAddress](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L283) method. We recommend using a default revision `0` and also deploying wallets in the basechain `workchain=0` for lower processing and storage fees. -4. Send some Toncoin to the calculated address. Note that you need to send them in `non-bounce` mode, as this address has no code yet and cannot process incoming messages. `non-bounce` flag indicates that even if processing fails, money should not be returned with a bounce message. We do not recommend using the `non-bounce` flag for other transactions, especially when carrying large sums, since the bounce mechanism provides some degree of protection against mistakes. -5. Form the desired [action](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L154), for instance `actionNoop` for deploy only. Then use [createQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L292) and [sendQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L300) to initiate interactions with the blockchain. -6. Check the contract in a few seconds with [getAccountState](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L288) method. +To deploy a wallet via TonLib, follow these steps: +1. Generate a private/public key pair using [createNewKey](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L244) or its wrapper functions (example in [tonlib-go](https://github.com/mercuryoio/tonlib-go/tree/master/v2#create-new-private-key)). The private key is generated locally and never leaves the host machine. +2. Form [InitialAccountWallet](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L62) structure corresponding to one of the available wallet versions. Currently, the supported `wallets` are: `wallet.v3`, `wallet.v4`, `wallet.highload.v1`, `wallet.highload.v2` are available. +3. Calculate the address of the new `wallet` smart contract using the [getAccountAddress](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L283) method. It is recommended to use revision 0 by default. Deploy wallets in the basechain `workchain=0` to minimize processing and storage fees. +4. Send some Toncoin to the calculated address. The transfer should be made in `non-bounce` mode since the wallet address has no code yet and cannot process incoming messages. The `non-bounce` flag ensures that if processing fails, the funds are not returned via a bounce message. Warning: Avoid using the non-bounce flag for other transactions, especially when transferring large sums, as the bounce mechanism provides protection against mistakes. +5. Form the desired [action](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L154), such as `actionNoop` for deploy only. Then use [createQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L292) and [sendQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L300) to initiate interactions with the blockchain. +6. Check the contract’s status after a few seconds using the [getAccountState](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L288) method. :::tip Read more in the [Wallet Tutorial](/v3/guidelines/smart-contracts/howto/wallet#-deploying-a-wallet) ::: -### Check the validity of wallet address +### Checking wallet address validity -Most SDKs force you to verify address (most verify it during wallet creation or transaction preparation process), so, usually, it's not require any additional complex steps from you. +Most SDKs automatically verify a wallet address during creation or transaction preparation, so additional manual validation is usually unnecessary. @@ -103,17 +102,20 @@ Full Address description on the [Smart Contract Addresses](/v3/documentation/sma ::: -## Work with transfers +## Working with transfers ### Check contract's transactions -A contract's transactions can be obtained using [getTransactions](https://toncenter.com/api/v2/#/accounts/get_transactions_getTransactions_get). This method allows to get 10 transactions from some `last_transaction_id` and earlier. To process all incoming transactions, the following steps should be followed: -1. The latest `last_transaction_id` can be obtained using [getAddressInformation](https://toncenter.com/api/v2/#/accounts/get_address_information_getAddressInformation_get) -2. List of 10 transactions should be loaded via the `getTransactions` method. -3. Process transactions with not empty source in incoming message and destination equals to account address. -4. The next 10 transactions should be loaded and steps 2,3,4,5 should be repeated until you processed all incoming transactions. - -### Retrieve Incoming/Outgoing Transactions -It's possible to track messages flow during transaction processing. Since the message flow is a DAG it's enough to get current transaction using [getTransactions](https://toncenter.com/api/v2/#/transactions/get_transactions_getTransactions_get) method and find incoming transaction by `out_msg` with [tryLocateResultTx](https://testnet.toncenter.com/api/v2/#/transactions/get_try_locate_result_tx_tryLocateResultTx_get) or outgoing transactions by `in_msg` with [tryLocateSourceTx](https://testnet.toncenter.com/api/v2/#/transactions/get_try_locate_source_tx_tryLocateSourceTx_get). +To retrieve a smart contract's transactions, use the [getTransactions](https://toncenter.com/api/v2/#/accounts/get_transactions_getTransactions_get). method. This method fetches up to 10 transactions starting from a specified `last_transaction_id` and earlier. To process all incoming transactions, follow these steps: +1. Obtain the latest `last_transaction_id` using [getAddressInformation](https://toncenter.com/api/v2/#/accounts/get_address_information_getAddressInformation_get) +2. Load 10 transactions using the `getTransactions` method. +3. Process transactions where the source field in the incoming message is not empty and the destination field matches the account address. +4. Retrieve the next 10 transactions and repeat steps 2 and 3 until all incoming transactions are processed. + +### Retrieve incoming/outgoing transactions +It is possible to track message flows during transaction processing. Since the message flow forms a DAG (Directed Acyclic Graph), follow these steps: +1. Use the [getTransactions](https://toncenter.com/api/v2/#/transactions/get_transactions_getTransactions_get) to obtain the current transaction. +2. Identify incoming transactions by checking out_msg with [tryLocateResultTx](https://testnet.toncenter.com/api/v2/#/transactions/get_try_locate_result_tx_tryLocateResultTx_get). +3. Identify outgoing transactions by checking in_msg with [tryLocateSourceTx](https://testnet.toncenter.com/api/v2/#/transactions/get_try_locate_source_tx_tryLocateSourceTx_get). @@ -175,53 +177,55 @@ main(); ### Send payments :::tip -Learn on basic example of payments processing from [TMA USDT Payments demo](https://github.com/ton-community/tma-usdt-payments-demo) +Learn the basics of payment processing from the [TMA USDT Payments demo](https://github.com/ton-community/tma-usdt-payments-demo) ::: -1. Service should deploy a `wallet` and keep it funded to prevent contract destruction due to storage fees. Note that storage fees are generally less than 1 Toncoin per year. -2. Service should get from the user `destination_address` and optional `comment`. Note that for the meantime, we recommend either prohibiting unfinished outgoing payments with the same (`destination_address`, `value`, `comment`) set or proper scheduling of those payments; that way, the next payment is initiated only after the previous one is confirmed. -3. Form [msg.dataText](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L103) with `comment` as text. -4. Form [msg.message](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L113) which contains `destination_address`, empty `public_key`, `amount` and `msg.dataText`. -5. Form [Action](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L154) which contains a set of outgoing messages. -6. Use [createQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L292) and [sendQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L300) queries to send outgoing payments. -7. Service should regularly poll the [getTransactions](https://toncenter.com/api/v2/#/transactions/get_transactions_getTransactions_get) method for the `wallet` contract. Matching confirmed transactions with the outgoing payments by (`destination_address`, `value`, `comment`) allows to mark payments as finished; detect and show the user the corresponding transaction hash and lt (logical time). -8. Requests to `v3` of `high-load` wallets have an expiration time equal to 60 seconds by default. After that time unprocessed requests can be safely resent to the network (see steps 3-6). +1. The service must deploy a `wallet` and keep it funded to prevent contract destruction due to storage fees. Storage fees are typically less than 1 Toncoin per year. +2. The service should collect the `destination_address` and an optional `comment` from the user. To avoid duplicate outgoing payments with the same (`destination_address`, `value`, `comment`), either prohibit unfinished payments with identical parameters or schedule payments so that a new payment starts only after the previous one is confirmed. +3. Create [msg.dataText](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L103) with `comment` as text. +4. Create [msg.message](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L113) which includes `destination_address`, empty `public_key`, `amount`, and `msg.dataText`. +5. Create the [Action](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L154) that should contain a set of outgoing messages. +6. Use [createQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L292) and [sendQuery](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L300) to submit the payment to the blockchain. +7. The service should regularly poll the [getTransactions](https://toncenter.com/api/v2/#/transactions/get_transactions_getTransactions_get) method of the `wallet` contract. By matching confirmed transactions with outgoing payments (`destination_address`, `value`, `comment`) the service can mark payments as finished and retrieve and display the transaction hash and logical time (lt) to the user. +8. Requests sent to `v3` of `high-load` have a 60-second expiration time by default. After expiration, unprocessed requests can be safely resent following steps 3-6. :::caution -If `value` attached is too small transaction can get aborted with error `cskip_no_gas`. In this case Toncoins will be transferred successfully but no logic on other side will be executed (TVM won't even launch). About gas limits you can read more [here](/v3/documentation/network/configs/blockchain-configs#param-20-and-21). +If the attached `value` is too small, the transaction may fail with the error `cskip_no_gas`. n this case, Toncoins will be transferred, but no logic will be executed on the recipient's side (the TVM will not launch). Read more [here](/v3/documentation/network/configs/blockchain-configs#param-20-and-21). ::: -### Get transaction id +### Get the transaction ID -It can be unclear that to get more information on transaction user must scan blockchain through [getTransactions](https://toncenter.com/api/v2/#/transactions/get_transactions_getTransactions_get) function. -It is impossible to retrieve the transaction ID immediately after sending a message, as the transaction must first be confirmed by the blockchain network. -To understand required pipeline read [Send payments](/v3/guidelines/dapps/asset-processing/payments-processing/#send-payments) carefully, especially 7th point. +It may be confusing that to get more information about a transaction, the user must scan the blockchain via the [getTransactions](https://toncenter.com/api/v2/#/transactions/get_transactions_getTransactions_get) function. +It is not possible to get the transaction ID immediately after sending the message, as the transaction must first be confirmed by the blockchain network. +To understand the required pipeline, carefully read [Send Payments](/v3/guidelines/dapps/asset-processing/payments-processing/#send-payments), especially the 7th point. ## Invoice-based approach -To accept payments based on attached comments, the service should +To accept payments based on attached comments, the service should: 1. Deploy the `wallet` contract. -2. Generate a unique `invoice` for each user. String representation of uuid32 will be enough. -3. Users should be instructed to send Toncoin to the service's `wallet` contract with an attached `invoice` as a comment. +2. Generate a unique `invoice` for each user. A uuid32 string is sufficient for invoice identification. +3. Users should send payments to the service’s `wallet` contract with the `invoice` as a comment. 4. Service should regularly poll the [getTransactions](https://toncenter.com/api/v2/#/transactions/get_transactions_getTransactions_get) method for the `wallet` contract. -5. For new transactions, the incoming message should be extracted, `comment` matched against the database, and the **incoming message value** deposited to the user's account. +5. For each new transaction extract the incoming message, match the comment against stored invoice data, and deposit the Toncoin value into the user's account. -To calculate the **incoming message value** that the message brings to the contract, one needs to parse the transaction. It happens when the message hits the contract. A transaction can be obtained using [getTransactions](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L268). For an incoming wallet transaction, the correct data consists of one incoming message and zero outgoing messages. Otherwise, either an external message is sent to the wallet, in which case the owner spends Toncoin, or the wallet is not deployed and the incoming transaction bounces back. +To calculate the **incoming message value** that a message brings to a contract, we need to analyze the transaction. This happens when a message enters the contract. The transaction can be retrieved using [getTransactions](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl#L268). For an incoming wallet transaction, the correct data consists of one incoming message and zero outgoing messages. Otherwise, either an outgoing message is sent to the wallet, in which case the owner spends the Toncoin, or the wallet is not deployed and the incoming transaction is returned. -Anyway, in general, the amount that a message brings to the contract can be calculated as the value of the incoming message minus the sum of the values of the outgoing messages minus the fee: `value_{in_msg} - SUM(value_{out_msg}) - fee`. Technically, transaction representation contains three different fields with `fee` in name: `fee`, `storage_fee`, and `other_fee`, that is, a total fee, a part of the fee related to storage costs, and a part of the fee related to transaction processing. Only the first one should be used. +In any case, in general, the amount a message brings to a contract can be calculated as the incoming message value minus the sum of the outgoing message values ​​minus the fee: `value_{in_msg} - SUM(value_{out_msg}) - fee`. Technically, the transaction view contains three different fields with `fee` in the name: `fee`, `storage_fee` and `other_fee`, i.e. the total fee, the portion of the fee related to storage costs, and the portion of the fee related to processing the transaction. Only the first one should be used. ### Invoices with TON Connect -Best suited for dApps that need to sign multiple payments/transactions within a session or need to maintain a connection to the wallet for some time. +Best for dApps that require multiple transactions within a session or a persistent wallet connection. -- ✅ There's a permanent communication channel with the wallet, information about the user's address -- ✅ Users only need to scan a QR code once -- ✅ It's possible to find out whether the user confirmed the transaction in the wallet, track the transaction by the returned BOC -- ✅ Ready-made SDKs and UI kits are available for different platforms +**Advantages** +- ✅ Permanent communication channel with the wallet. +- ✅ Users only scan a QR code once. +- ✅ Can track transaction confirmation via the returned BOC. +- ✅ Ready-made SDKs and UI kits for various platforms. -- ❌ If you only need to send one payment, the user needs to take two actions: connect the wallet and confirm the transaction -- ❌ Integration is more complex than the ton:// link +**Disadvantages** +- ❌ If only one payment is needed, users must connect the wallet and confirm the transaction +- ❌ More complex integration than a ton:// link.