diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e389331bce4..331ef37b8ce 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 44b3f80943a..edb9677602a 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/docs/v3/concepts/qa-outsource/auditors.mdx b/docs/v3/concepts/qa-outsource/auditors.mdx index 599a9463f53..90acb3b30e2 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 7125639aede..a747f507aed 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 @@ -169,5 +175,5 @@ Request with PR -## 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 ccc40b4b708..4496caf08f4 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 0255bb33ad9..412b4ed1f05 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 31ccf07486c..bc76661ddb1 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 caa9ca7885b..dbc51eb0d9f 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 78e794e3750..9b58329a4cd 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 1285dbd9490..c126cf59b62 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/smart-contracts/contracts-specs/examples.md b/docs/v3/documentation/smart-contracts/contracts-specs/examples.md index a67263e5e99..db72848a3db 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 677a9bbcde3..2e0bacc828b 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 9b872301d67..f3f62f0da36 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 c3a413c6f97..1ecfeee6c0f 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 1442122fac8..d79a87a8e9c 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 183e20544f4..0fcb8ec4f61 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/overview.mdx b/docs/v3/guidelines/dapps/overview.mdx index b3ef322797d..dde38682556 100644 --- a/docs/v3/guidelines/dapps/overview.mdx +++ b/docs/v3/guidelines/dapps/overview.mdx @@ -1,12 +1,11 @@ import Button from '@site/src/components/button' # Getting Started -Before diving into DApps, make sure you understand the underlying blockchain principles. You might find our [The Open Network](/v3/concepts/dive-into-ton/introduction) and [Blockchain of Blockchains](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains) articles useful. +Before diving into DApps, make sure you understand blockchain fundamentals. You may find our [The Open Network](/v3/concepts/dive-into-ton/introduction) and [Blockchain of Blockchains](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains) articles useful. -TON DApps are applications without backend, which interact with the blockchain. In most cases, they interact with custom [smart contracts](/v3/documentation/smart-contracts/overview); this documentation provides ways to process standard assets available in TON, both as an example and for quicker DApps development. - -DApps generally can be written in any programming language having SDK for TON. Actually, the most frequent choice is a website, followed by Telegram mini-apps. +TON DApps are applications without a backend that interact with the blockchain. In most cases, they work with custom [smart contracts](/v3/documentation/smart-contracts/overview). This documentation explains how to process standard assets available in TON, both as examples and to accelerate DApp development. +You can write DApps in any programming language that has an SDK for TON. Most developers build them as websites, followed by Telegram Mini Apps.