From 87058d8ab6fb3fa1e8180319c5e829e3510a0538 Mon Sep 17 00:00:00 2001 From: Alexey Ostrovsky Date: Mon, 21 Apr 2025 11:01:43 +0300 Subject: [PATCH 1/3] Content standartization, common fixes --- .../writing-to-network.mdx | 2 +- .../blueprint-sdk-overview.mdx | 31 +++--- .../processing-messages.mdx | 29 +++--- .../setup-environment.mdx | 40 ++++---- .../storage-and-get-methods.mdx | 64 ++++++------ .../quick-start/getting-started.mdx | 97 ++++++++++--------- 6 files changed, 135 insertions(+), 128 deletions(-) diff --git a/docs/v3/guidelines/quick-start/blockchain-interaction/writing-to-network.mdx b/docs/v3/guidelines/quick-start/blockchain-interaction/writing-to-network.mdx index a5ad5005781..6f0264b0b4b 100644 --- a/docs/v3/guidelines/quick-start/blockchain-interaction/writing-to-network.mdx +++ b/docs/v3/guidelines/quick-start/blockchain-interaction/writing-to-network.mdx @@ -88,7 +88,7 @@ async function main() { const { publicKey, secretKey } = await mnemonicToWalletKey(mnemonic); // Creating wallet depending on version (v5r1 or v4 or V3R2), uncomment which version do you have - const walletContract = WalletContractV5R1.create({ walletId: { networkGlobalId: -3 }, publicKey }); // networkGlobalId: -3 for testnet, -239 for mainnet + const walletContract = WalletContractV5R1.create({ walletId: { networkGlobalId: -3 }, publicKey }); // networkGlobalId: -3 for Testnet, -239 for Mainnet //const walletContract = WalletContractV4.create({ workchain: 0, publicKey }); //const walletContract = WalletContractV3R2.create({ workchain: 0, publicKey }); diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview.mdx index 22327139098..e5fff84b0e4 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview.mdx @@ -3,14 +3,14 @@ import TabItem from '@theme/TabItem'; # Blueprint SDK overview -> **Summary:** In previous steps we installed and configured all tools required for TON smart contract development and created our first project template. +> **Summary:** In the previous steps, we installed and configured all the tools required for TON smart contract development and created our first project template. -Before we proceed to actual smart contract development let's briefly describe project structure and explain how to use **`Blueprint SDK`**. +Before we proceed to actual smart contract development, let's briefly describe the project structure and explain how to use the **`Blueprint SDK`**. ## Project structure :::warning -If you didn't choose proposed names in previous steps, source code file names and some of the in-code entities may differ. +If you didn't choose the proposed names in the previous steps, source code file names and some of the in-code entities may differ. ::: @@ -54,48 +54,49 @@ This folder contains your smart contract source code written in one of the avail ### `/wrappers` -To interact with your smart contract off-chain you need to serialize and desirialize messages sended to it. `Wrapper` classes developed to mirror your smart contract implementation making it simple to use it's functionality. +To interact with your smart contract off-chain, you need to serialize and deserialize messages sent to it. `Wrapper` classes are developed to mirror your smart contract implementation, making it simple to use its functionality. ### `/tests` -This directory contains test files for your smart contracts. Testing contracts directly in TON network is not the best option because deployment requires some amount of time and may lead to losing funds. This testing playground allow you to execute multiple smart contracts and even send messages between them in your **"local network"**. Tests are crucial for ensuring your smart contracts behave as expected before deployment to the network. +This directory contains test files for your smart contracts. Testing contracts directly on the TON network is not the best option because deployment requires some amount of time and may lead to losing funds. This testing playground allows you to execute multiple smart contracts and even send messages between them in your **"local network"**. Tests are crucial for ensuring your smart contracts behave as expected before deployment to the network. ### `/scripts` -The scripts directory contains `TypeScript` files that help you deploy and interact with your smart contracts on-chain using previously implemented wrappers. +The `scripts` directory contains `TypeScript` files that help you deploy and interact with your smart contracts on-chain using previously implemented wrappers. ## Development flow -Almost any smart contract project development consist of five simple steps: +Almost any smart contract project development consists of five simple steps: - 1. Edit smart contract code in `/contracts` folder and build it by running build script: +1. Edit the smart contract code in the `/contracts` folder and build it by running the build script: ```bash npx blueprint build ``` - 2. Update smart contract wrapper in `/wrapper` folder corresponding to changes in contract. - 3. Update test's in `/tests` folder to ensure correctness of new functionality and run test script: +2. Update the smart contract wrapper in the `/wrappers` folder to correspond to changes in the contract. + +3. Update tests in the `/tests` folder to ensure the correctness of the new functionality and run the test script: ```bash npx blueprint test ``` - 4. Repeat steps 1-3 until you get desired result. +4. Repeat steps 1-3 until you achieve the desired result. - 5. Update deployment script in `/scripts` folder and run it using this command: +5. Update the deployment script in the `/scripts` folder and run it using this command: ```bash npx blueprint run ``` :::tip -All examples in this guide follow sequnce of this **1-3 steps** with corresponding code samples. **Step 5**, deployment process, is covered in last section of the guide: [Deploying to network](/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network/). +All examples in this guide follow the sequence of these **1-3 steps** with corresponding code samples. **Step 5**, the deployment process, is covered in the last section of the guide: [Deploying to network](/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network/). ::: -Also, you can always generate same structure for another smart contract if, for example, you want to create multiple contracts interacting with each other, by using following command: +Also, you can always generate the same structure for another smart contract if, for example, you want to create multiple contracts interacting with each other, by using the following command: ```bash -npx blueprint create PascalCase #dont forget to name contract in PascalCase +npx blueprint create PascalCase # Don't forget to name the contract in PascalCase ``` diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx index 01b3e115cfd..947c83af532 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx @@ -1,31 +1,30 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Processing Messages +# Processing messages -> **Summary:** In previous steps we modified our smart contract interaction with `storage`, `get methods` and learned basic smart contract development flow. - -Now we are ready to move on to the main functionality of smart contracts - **sending and receiving messages**. In TON messages not only used for sending currency, but also as data-exchange mechanism between smart contracts making them crucial for smart contract development. +> **Summary:** In previous steps, we modified our smart contract interaction with `storage`, `get methods`, and learned the basic smart contract development flow. +Now we are ready to move on to the main functionality of smart contracts - **sending and receiving messages**. In TON, messages are not only used for sending currency, but also as a data-exchange mechanism between smart contracts, making them crucial for smart contract development. :::tip -If you are stuck on some of the examples you can find original template project with all modifications performed during this guide [here](https://github.com/ton-community/ton-onboarding-sandbox/tree/main/quick-start/smart-contracts/Example/). +If you are stuck on some of the examples, you can find the original template project with all modifications performed during this guide [here](https://github.com/ton-community/onboarding-sandbox/tree/main/quick-start/smart-contracts/Example/contracts). ::: --- ## Internal messages -Before we proceed to implementation let's briefly describe main ways and patterns that we can use to process internal messages. +Before we proceed to implementation, let's briefly describe the main ways and patterns that we can use to process internal messages. -### Actors and roles +### Actors and Roles -Since TON implements [actor](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains/#single-actor/) model it's natural to think about smart contracts relations in terms of `roles`, determining who can access smart contract functionality or not. The most common examples of roles are: +Since TON implements the [actor](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains/#single-actor/) model, it's natural to think about smart contract relations in terms of `roles`, determining who can access smart contract functionality or not. The most common examples of roles are: - - `anyone`: any contract that don't have distinct role. - - `owner`: contract that has exclusive access to some crucial parts of functionality. +- `anyone`: any contract that doesn't have a distinct role. +- `owner`: a contract that has exclusive access to some crucial parts of the functionality. -Let's examine `recv_internal` function signature to understand how we could use that: +Let's examine the `recv_internal` function signature to understand how we could use that: @@ -48,11 +47,11 @@ fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: sli -:::info -You can find comprehensive description of sending messages in this [section](/v3/documentation/smart-contracts/message-management/sending-messages#message-layout/). +:::info +You can find a comprehensive description of sending messages in this [section](/v3/documentation/smart-contracts/message-management/sending-messages#message-layout/). ::: -What we specifically are interested in is the source address of message that we could extract from `msg_full` cell, by obtaining that address and comparing to stored one, that we previously saved, for example, during deployment, we can open crucial part of our smart contract functionality. Common approach looks like this: +What we are specifically interested in is the source address of the message, which we can extract from the `msg_full` cell. By obtaining that address and comparing it to a stored one—saved previously, for example, during deployment—we can conditionally allow access to crucial parts of our smart contract functionality. A common approach looks like this: @@ -111,7 +110,7 @@ fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: sli ### Operations -Common pattern in TON contracts is to include a **32-bit operation code** in message bodies which tells your contract what action to perform: +A common pattern in TON contracts is to include a **32-bit operation code** in message bodies, which tells your contract what action to perform: diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx index 727b800c37f..5c357651b17 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx @@ -1,66 +1,66 @@ # Setup development environment -> **Summary:** In previous steps we learned concept of smart contract and basic ways of interacting with TON Blockchain through **wallet apps** and **explorers**. +> **Summary:** In the previous steps, we learned the concept of a smart contract and basic ways of interacting with TON Blockchain through **wallet apps** and **explorers**. -This guide covers basic steps of setting up your smart contract development environment using **`Blueprint SDK`** and creating basic project template. +This guide covers the basic steps of setting up your smart contract development environment using **`Blueprint SDK`** and creating a basic project template. ## Prerequisites - - Basic programming skills. - - Familiarity with Command-line interface. +- Basic programming skills. +- Familiarity with the command-line interface. ## Setup development environment -For this guide we will rely on [Blueprint SDK](https://github.com/ton-org/blueprint/) and [Node.js](https://nodejs.org/en)/TypeScript stack for writing wrappers, tests and deployments scripts for your smart contract, because its provides easiest, ready to use environment for smart contracts developing. +For this guide, we will rely on the [Blueprint SDK](https://github.com/ton-org/blueprint/) and [Node.js](https://nodejs.org/en)/TypeScript stack for writing wrappers, tests, and deployment scripts for your smart contract, because it provides the easiest, ready-to-use environment for smart contract development. :::info -Using native instruments and language-dependent SDK's for smart contract development covered in more advanced sections here: - - [Compile and build smart contracts on TON](/v3/documentation/archive/compile#ton-compiler/). - - [Creating State Init for Deployment](/v3/guidelines/smart-contracts/howto/wallet#creating-the-state-init-for-deployment/). +Using native instruments and language-dependent SDKs for smart contract development is covered in more advanced sections here: +- [Compile and build smart contracts on TON](/v3/documentation/archive/compile#ton-compiler/). +- [Creating State Init for Deployment](/v3/guidelines/smart-contracts/howto/wallet#creating-the-state-init-for-deployment/). ::: ### Step 1: Install Node.js -First, visit [installation page](https://nodejs.org/en/download) and execute download commands in `PowerShell` or `Bash` corresponding to your operating system Windows/Linux. +First, visit the [installation page](https://nodejs.org/en/download) and execute the download commands in `PowerShell` or `Bash` corresponding to your operating system (Windows/Linux). -Check that `npm` and `node` installed by executing following command: +Check that `npm` and `node` are installed by executing the following command: ```bash npm -v node -v ``` -### Step 2: Choose smart contract development language +### Step 2: Choose a smart contract development language -During guide we provide example on: `Func`, `Tolk` and `Tact`. You can choose from any of them and even combine smart contracts on different languages. To proceed through guide there is now need of deep understanding of choosed one, basic programming skills will be enought. +During the guide, we provide examples in `Func`, `Tolk`, and `Tact`. You can choose any of them and even combine smart contracts in different languages. To proceed through the guide, there is no need for a deep understanding of the chosen language—basic programming skills will be enough. :::info -You can find breaf overview of languages here: [Programming languages](/v3/documentation/smart-contracts/overview#programming-languages/) +You can find a brief overview of the languages here: [Programming languages](/v3/documentation/smart-contracts/overview#programming-languages/) ::: ### Step 3: Setup Blueprint SDK -Change directory to parent folder of your future project and run following command: +Change the directory to the parent folder of your future project and run the following command: ```bash npm create ton@latest ``` -This will run interactive script for creating project template, you can enter anything you want, but if you want to have same paths as this guide choose following: +This will run an interactive script to create the project template. You can enter anything you want, but if you want to follow the same paths as in this guide, choose the following: 1. Project name: `Example`. 2. First created contract name: `HelloWorld`. -3. Choose the project template: A **simple counter contract** on `FunC` or `Tolk`. +3. Choose the project template: A **simple counter contract** in `FunC` or `Tolk`. -And finally, change your current directory to generated project template folder, and install all required dependencies: +Finally, change your current directory to the generated project template folder, and install all required dependencies: ```bash cd ./Example npm install ``` -### Step 4(optional): IDE and editors support +### Step 4 (optional): IDE and Editor Support -Ton community developed plugins providing syntax support for several IDE's and code editors. You can find them here: [Plugin List](https://docs.ton.org/v3/documentation/smart-contracts/getting-started/ide-plugins/). +TON Community has developed plugins providing syntax support for several IDEs and code editors. You can find them here: [Plugin List](https://docs.ton.org/v3/documentation/smart-contracts/getting-started/ide-plugins/). -Also consider installing plugins providing support for **JavaScript/TypeScript** tools for your preferred IDE or code editor and, specifically, `Jest` for debugging smart contract tests. +Also, consider installing plugins that provide support for **JavaScript/TypeScript** tools for your preferred IDE or code editor, and specifically, `Jest` for debugging smart contract tests. diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx index 23b9a3743e5..63d79ff67cb 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx @@ -3,20 +3,20 @@ import TabItem from '@theme/TabItem'; # Storage and Get Methods -> **Summary:** In previous steps we learned how to use `Blueprint SDK` and it's project structure. +> **Summary:** In the previous steps, we learned how to use `Blueprint SDK` and its project structure. :::tip -If you are stuck on some of the examples you can find original template project with all modifications performed during this guide [here](https://github.com/ton-community/ton-onboarding-sandbox/tree/main/quick-start/smart-contracts/Example/). +If you are stuck on some of the examples, you can find the original template project with all modifications performed during this guide [here](https://github.com/ton-community/onboarding-sandbox/tree/main/quick-start/smart-contracts/Example/contracts). ::: -Almost all smart contracts need to store their `data` between transactions. This guide explains standard ways of managing `storage` of smart contract and using `get methods` to obtain it from outside the blockchain. +Almost all smart contracts need to store their `data` between transactions. This guide explains standard ways of managing `storage` for smart contracts and using `get methods` to obtain it from outside the blockchain. ## Smart contract storage operations -There are two main instructions that provide access to smart contract storage: +There are two main instructions that provide access to smart contract storage: - `get_data()` returning current storage cell. - `set_data()` setting storage cell. @@ -31,17 +31,17 @@ There are two main instructions that provide access to smart contract storage: -Lets examine [Cell](/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage) entity structure to understand how we could manage contract storage: +Let's examine the [Cell](/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage) entity structure to understand how we could manage contract storage: -## Cell structure +## Cell Structure -TON blockchain uses a data structure called **`Cell`** as the fundamental unit for storing data. `Cells` are the building blocks of the smart contract data and have those characteristics: +TON Blockchain uses a data structure called **`Cell`** as the fundamental unit for storing data. `Cells` are the building blocks of smart contract data and have the following characteristics: -- `Cell` can store up to 1023 bits (approximately 128 bytes) of data -- `Cell` can reference up to 4 other `Cells` (children's) -- `Cell` is immutable once created +- A `Cell` can store up to 1023 bits (approximately 128 bytes) of data. +- A `Cell` can reference up to 4 other `Cells` (children). +- A `Cell` is immutable once created. -You can think of `Cell` as the following structure: +You can think of a `Cell` as the following structure: ```typescript // Conceptual representation of a Cell @@ -53,11 +53,11 @@ interface Cell { ## Implementation -Let's try to modify our smart contract folowing standard steps decsribed in previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. +Let's try to modify our smart contract following the standard steps described in the previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. ### Step 1: Edit smart contract code -In case it's inconvenient to always serialize and deserialize storage cell, there is a pretty standard practice to define two wrapper methods that provide corresponding logic. If you didn't change smart contract code it should contain following lines: +In case it's inconvenient to always serialize and deserialize the storage cell, there is a common practice to define two wrapper methods that provide the corresponding logic. If you didn't change the smart contract code, it should contain the following lines: @@ -113,13 +113,13 @@ fun saveData() { -#### Managing storage +#### Managing Storage -Let's try to modify our example a little bit. First, let's examine different approach of managing storage, widely used in smart contract development: +Let's try to modify our example a little bit. First, let's examine a different approach to managing storage, widely used in smart contract development: -Instead of initializing global variables we will pass storage members as parameters to `save_data(members...)` and retrieve them as `(members...) get_data()` moving global variables `ctx_id` and `ctx_counter` to methods bodies. Also, let's add additional integer of 256-bit size into our storage. +Instead of initializing global variables, we will pass storage members as parameters to `save_data(members...)` and retrieve them as `(members...) get_data()`, moving global variables `ctx_id` and `ctx_counter` to the method bodies. Additionally, let's add an extra 256-bit integer into our storage. -Result of our modifications should look like this: +The result of our modifications should look like this: @@ -179,7 +179,7 @@ fun saveData(ctxID: int, ctxCounter: int, ctxCounterExt: int) { -Don't forget to delete global variables `ctx_id`, `ctx_counter` and modify usage of the function like this, copying storage members locally: +Don't forget to delete the global variables `ctx_id` and `ctx_counter`, and modify the usage of the function like this, copying the storage members locally: @@ -225,9 +225,9 @@ get get_counters(): (int, int) { -And that's it! In practice all **get methods** follow this simple flow and don't require anything more. Note that you can omit values returned from functions using `_` syntax. +And that's it! In practice, all **get methods** follow this simple flow and don't require anything more. Note that you can omit values returned from functions using the `_` syntax. -Final smart contract code should look like this: +The final smart contract code should look like this: @@ -376,7 +376,7 @@ Don't forget to check the correctness of your changes by compiling the smart con npx blueprint build ``` -Expected output should look like this: +The expected output should look like this: ```bash Build script running, compiling HelloWorld @@ -394,7 +394,7 @@ Build script running, compiling HelloWorld ### Step 2: Update wrapper -Now lets update our wrapper class corresponding to new storage layout and new `get method`. First, let's modify `helloWorldConfigToCell` function and `HelloWorldConfig` type to properly initialize our storage during samrt-contract creation with 256-bit `ctxCounterExt` field that we previously added to `smart contract`: +Now, let's update our wrapper class to correspond to the new storage layout and the new `get method`. First, let's modify the `helloWorldConfigToCell` function and the `HelloWorldConfig` type to properly initialize our storage during smart contract creation, including the 256-bit `ctxCounterExt` field that we previously added to the smart contract: ```typescript title="/wrappers/HelloWorld.ts" export type HelloWorldConfig = { @@ -411,7 +411,8 @@ export function helloWorldConfigToCell(config: HelloWorldConfig): Cell { .endCell(); } ``` -Second, add a method to perform a request for the newly created smart contract method `get_counters` that will retrieve both counters at once: + +Second, add a method to perform a request for the newly created smart contract method `get_counters`, which will retrieve both counters at once: ```typescript title="/HelloWorld.ts" async getCounters(provider: ContractProvider) : Promise<[number, bigint]> { @@ -423,15 +424,14 @@ async getCounters(provider: ContractProvider) : Promise<[number, bigint]> { } ``` -### Step 3: Update tests - -And finally, let's test our new functionality through previously updated wrapper: - - Create and initialize smart contract storage members with some value through `helloWorldConfig`. - - Call each of get methods and retrieve storage members. - - Verify that they have stayed the same as during creation. +### Step 3: Update Tests -Here is an example of such implementation: +And finally, let's test our new functionality through the previously updated wrapper: +- Create and initialize smart contract storage members with some value through `helloWorldConfig`. +- Call each of the `get` methods and retrieve storage members. +- Verify that they have stayed the same as during creation. +Here is an example of such an implementation: ```typescript title="/tests/HelloWorld.spec.ts" import { Blockchain, SandboxContract, TreasuryContract } from '@ton/sandbox'; @@ -512,13 +512,13 @@ describe('HelloWorld', () => { }); ``` -And now run your new test script by executing the following command: +And now, run your new test script by executing the following command: ```bash npx blueprint test ``` -Expected output should look like this: +The expected output should look like this: ```bash # "custom log messages" diff --git a/docs/v3/guidelines/quick-start/getting-started.mdx b/docs/v3/guidelines/quick-start/getting-started.mdx index c0f76163767..6f32b03751c 100644 --- a/docs/v3/guidelines/quick-start/getting-started.mdx +++ b/docs/v3/guidelines/quick-start/getting-started.mdx @@ -3,42 +3,42 @@ import MnemonicGenerator from "@site/src/components/MnemonicGenerator"; # Getting started -Welcome to TON quick start guide! This guide will give you a starting point for further research of TON concepts and basic practical experience of developing applications with the TON Ecosystem. +Welcome to the TON Quick Start Guide! This guide will give you a starting point for further research into TON concepts and basic practical experience in developing applications with TON Ecosystem. ## Prerequisites - Basic programming knowledge. - Around __30 minutes__ of your time. -> **Note**: We will provide a short explanation of core concepts during the guide, but if you prefer a more theoretical approach, you can check out core concepts of [TON Blockchain](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains/) first. +> **Note**: We will provide a short explanation of core concepts during the guide, but if you prefer a more theoretical approach, you can check out the core concepts of [TON Blockchain](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains/) first. ## What You'll Learn - Interact with TON Ecosystem: Wallets and Explorers. -- Setup development environment: use Blueprint SDK for developing `smart contracts` using `FunC`, `Tact`, and `Tolk` programming languages. -- Send transactions and read from TON Blockchain using your preferred programming language and available **SDKs**. -- Core concepts of TON Blockchain: `messages`, `smart contracts`, `addresses` and etc. -- Basic templates ready for implementation of your project logic. +- Set up the development environment: use the Blueprint SDK for developing `smart contracts` using `FunC`, `Tact`, and `Tolk` programming languages. +- Send transactions and read from TON Blockchain using your preferred programming language and available `SDKs`. +- Core concepts of the TON Blockchain: `messages`, `smart contracts`, `addresses`, etc. +- Basic templates ready for implementing your project logic. ## Concept of smart contract -You can think of smart contracts in TON as a program running on blockchain following well known behavior concept of [actor](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains#single-actor/). +You can think of smart contracts in TON as a program running on the blockchain, following the well-known behavioral concept of [Actor](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains#single-actor/). :::info -In contrast to some other blockchains where you can call in synchronous way other contracts code, smart contract in TON is a thing in itself, and communicates with other smart contracts on equal basis sending asynchronous messages between each other. +In contrast to some other blockchains, where you can call other contract codes synchronously, a smart contract in TON is a standalone entity that communicates with other smart contracts on an equal basis by sending asynchronous messages between them. ::: -Each processing of message by receiver smart contract is considered a transaction resulting in following actions: - - Sending further messages. - - Changing internal data or even code of smart contract itself. - - Changing it's balance. +Each processing of a message by the receiver smart contract is considered a transaction, resulting in the following actions: +- Sending further messages. +- Changing internal data or even the code of the smart contract itself. +- Changing its balance. -Available interfaces of smart contract are: - - Receiving **`internal messages`** from other smart contract. - - Receiving **`external messages`** from outside the blockchain. - - Receiving **`get methods`** request from outside the blockchain. +The available interfaces of a smart contract are: +- Receiving **`internal messages`** from another smart contract. +- Receiving **`external messages`** from outside the blockchain. +- Receiving **`get methods`** requests from outside the blockchain. -In contrast to `internal` and `external` messages, `get methods` are not what you can consider as a **transaction**. Those are special functions of smart contract that cannot change contract internal state or proceed any other action except querying specific data from contract state. +In contrast to `internal` and `external` messages, `get methods` are not considered a **transaction**. These are special functions of the smart contract that cannot change the contract's internal state or perform any other action except querying specific data from the contract's state. :::info Contrary to what might seem intuitive, invoking `get methods` from other contracts **is not possible**. @@ -46,37 +46,37 @@ Contrary to what might seem intuitive, invoking `get methods` from other contrac ## Interacting with TON Ecosystem -Before we step on our way of becoming a TON developer, we should become an advanced user of TON! Let's create your own `wallet`, send a few transactions, and see how our actions are reflected on the blockchain using `explorers`. +Before we start our journey to becoming a TON developer, we should become advanced users of TON! Let's create your own `wallet`, send a few transactions, and see how our actions are reflected on the blockchain using `explorers`. ### Step 1: Create a new wallet using an app -The simplest way to create a `wallet` is to visit https://ton.org/wallets and choose one of the wallet apps from the list. They are all pretty similar, let's choose [Tonkeeper](https://tonkeeper.com/). Go ahead, install and run it. +The simplest way to create a `wallet` is to visit https://ton.org/wallets and choose one of the wallet apps from the list. They are all pretty similar, so let's choose [Tonkeeper](https://tonkeeper.com/). Go ahead, install, and run it. ### Step 2: Mainnet and Testnet -In the TON there is two different networks called `Mainnet` and `Testnet`, that have distinct roles: - - The `Mainnet` is the primary network where actual transactions take place, carrying real economic value as they involve real cryptocurrency. - - The `Testnet` is a testing version of the TON **Blockchain** designed for development and testing purposes. It's a risk-free zone for developers to test without financial implications. It's mainly used for development, testing `smart contracts`, and trying new features. +In TON, there are two different networks called `Mainnet` and `Testnet`, each with distinct roles: +- `Mainnet` is the primary network where actual transactions take place, carrying real economic value as they involve real cryptocurrency. +- `Testnet` is a testing version of the TON **Blockchain** designed for development and testing purposes. It's a risk-free zone for developers to test without financial implications. It's mainly used for development, testing `smart contracts`, and trying new features. #### Getting funds -Transactions in TON always require some amount of funds, since executing smart contracts code requires [fee](/v3/documentation/smart-contracts/transaction-fees/fees/) payment. TON basic transactions are very cheap, about 1 cent per transaction, getting euqivalent to $5 amount of [Toncoin](/v3/documentation/dapps/defi/coins/) will be enough for hundreds of them. Here is how you can get them: +Transactions in TON always require some amount of funds, as executing smart contract code requires a [fee](/v3/documentation/smart-contracts/transaction-fees/fees/) payment. TON basic transactions are very cheap, about 1 cent per transaction. Getting an equivalent of $5 worth of [Toncoin](/v3/documentation/dapps/defi/coins/) will be enough for hundreds of them. Here’s how you can get them: - - For `Mainnet` you can get `Toncoins` by simply pressing the buy button in the user interface, or ask someone to send them to your `address`, which you can copy from the wallet app somewhere near your balance. +- For `Mainnet`, you can get `Toncoins` by simply pressing the buy button in the user interface, or ask someone to send them to your `address`, which you can copy from the wallet app, usually located near your balance. :::warning - Don't worry, sharing your `address` is **totally safe**, unless you don't want it to be associated with you. +Don't worry, sharing your `address` is **totally safe**, unless you don't want it to be associated with you. ::: - - For the `Testnet` version, you can request funds from the [Testgiver Ton Bot](https://t.me/testgiver_ton_bot/) **completly for free**! After a short wait, you will receive 2 `Toncoins` that will appear in your wallet app. + - For `Testnet` version, you can request funds from the [Testgiver Ton Bot](https://t.me/testgiver_ton_bot/) **completely for free**! After a short wait, you will receive 2 `Toncoins` that will appear in your wallet app. -### Step 3: Creating Testnet wallet +### Step 3: Creating a Testnet wallet -If you decide to use the `Testnet` version, you can do to it by following guide below. +If you decide to use the `Testnet` version, you can do so by following the guide below. -#### Generating mnemonic +#### Generating a mnemonic -To create your first Testnet wallet in Tonkeeper you should obtain mnemonic using the button below. Do not forget to save this phrase! +To create your first Testnet wallet in Tonkeeper, you should obtain a mnemonic using the button below. Do not forget to save this phrase! @@ -100,15 +100,15 @@ To create Testnet wallet click *`Wallet`* -> *`Add Wallet`* - *`TestnetAccount`* ### Step 4: Exploring TON Blockchain -Congratulations! We created our first wallet and received some funds on it. Now let's take a look at how our actions are reflected in the `blockchain`. We can do this by using various [explorers](https://ton.app/explorers/). +Congratulations! We created our first wallet and received some funds in it. Now let's take a look at how our actions are reflected in the blockchain. We can do this by using various [explorers](https://ton.app/explorers/). -An `explorer` is a tool that allows you to query data from the chain, investigate TON `smart contracts`, and transactions. For our examples, we are going to use [TonViewer](https://tonviewer.com/). +An `explorer` is a tool that allows you to query data from the chain, investigate TON `smart contracts`, and view transactions. For our examples, we are going to use [Tonviewer](https://tonviewer.com/). :::tip -Note that in case of using `Testnet`, you should manually change the explorer mode to the `Testnet` version. Don't forget that these are different networks not sharing any transactions or smart contracts, so your `Testnet` wallet would not be visible in `Mainnet` mode and vice versa. +Note that when using the `Testnet`, you should manually change the explorer mode to the `Testnet` version. Don't forget that these are different networks, not sharing any transactions or smart contracts. Therefore, your `Testnet` wallet would not be visible in `Mainnet` mode and vice versa. ::: -Let's take a look at our newly created wallet using the `explorer`: copy your wallet address from the app and insert it into the search line of the explorer like this: +Let's take a look at our newly created wallet using the `explorer`: copy your wallet address from the app and insert it into the search bar of the explorer like this:
Screenshot of explorer search interface @@ -116,55 +116,62 @@ Let's take a look at our newly created wallet using the `explorer`: copy your wa #### Address state -First, let't examine common [address state](/v3/documentation/smart-contracts/addresses/#addresses-state/) of our smart contract: +First, let's examine the common [address state](/v3/documentation/smart-contracts/addresses/#addresses-state/) of our smart contract: - - `Nonexisting`: If you still didn't receive funds to your `address` you can see the default state for any address that has not been used before, and therefore don't have any data. +- `Nonexisting`: If you haven't received funds to your `address` yet, you will see the default state for any address that has not been used before and therefore has no data.
Screenshot of nonexistent wallet state
- - `Uninit`: stands for an address that has some metadata such as funds, but hasn't been initialized by deployed `smart contract` code or data. +- `Uninit`: Stands for an address that has some metadata, such as funds, but hasn't been initialized by deployed `smart contract` code or data..
Screenshot of uninitialized wallet state
:::info +<<<<<<< Updated upstream This might seem unintuitive, why is your wallet in `uninit` state when you already created it? There is little difference between `wallet app` and `wallet smart contract`: - `wallet app` is your off-chain client for `wallet smart contract` - `wallet smart contract` is contract itself, since its deployment requires some fees most `wallet apps` don't actually deploy the wallet `smart contract` until you receive funds on your address and try to make your first transaction. +======= +This might seem unintuitive: why is your wallet in the `uninit` state when you’ve already created it? There is a small difference between the `wallet app` and the `wallet smart contract`: + +- The `wallet app` is your off-chain client for the `wallet smart contract`. +- The `wallet smart contract` is the contract itself. Since its deployment requires some fees, most `wallet apps` don’t actually deploy the wallet `smart contract` until you receive funds on your address and try to make your first transaction. +>>>>>>> Stashed changes ::: -- `Active`: state of deployed `smart contract` with positive balance. To deploy our wallet let's send first transaction to someone special - **ourselves**. And see how it looks on the `blockchain`. Enter the send menu in your wallet app and transfer some funds to your own address that you have copied before. In the explorer, our contract should start looking something like this: +- `Active`: This is the state of a deployed `smart contract` with a positive balance. To deploy our wallet, let's send the first transaction to someone special—**ourselves**. And see how it looks on the `blockchain`. Enter the send menu in your wallet app and transfer some funds to your own address that you’ve copied before. In the explorer, our contract should start looking something like this:
Screenshot of active wallet state
:::info -There is also fourth state called [frozen](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee/) standing for smart contract with [storage charge](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee/) that exceeds it's balance. In this state smart contract cannot perform any operations. +There is also a fourth state called [frozen](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee/), which stands for a smart contract with a [storage charge](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee/) that exceeds its balance. In this state, the smart contract cannot perform any operations. ::: -And here we are, our wallet contract is deployed and ready to use. Let's examine provided user interface: +And here we are, our wallet contract is deployed and ready to use. Let's examine the provided user interface: #### Metadata Section - **Address**: Your account's unique ID (e.g., `QQB...1g6VdFEg`) - **Balance**: Current TON amount - **Type**: Contract version (e.g., `wallet_v5r1` – detected automatically by code) -- **State**: address state. Maybe `nonexisting`, `uninit`, `active` or `frozen` +- **State**: Address state. It may be `nonexisting`, `uninit`, `active`, or `frozen`. #### Navigation Tabs -- **History/Transactions**: Displays recent activity (e.g., received funds, contract deployments) +- **History/Transactions**: Displays recent activity (e.g., received funds, contract deployments). - **Code**: Shows raw smart contract code compiled from `Func`/`Tact`/`Tolk`. - **Methods**: Allows execution of `get methods` to retrieve persistent contract data. ## Next Steps: - - Try to experiment with `wallet app` and `wallet smart contract`: create another wallet contract in your wallet app and try to send transactions between them. - - Continue to [Blockchain interaction](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network/) if you want to learn how to interact with `smart contracts` from outside the blockchain. - - Or dive into [Developing smart contracts](/v3/guidelines/quick-start/developing-smart-contracts/setup-environment/) to learn how to develop `smart contracts` by yourself! +- Try experimenting with the `wallet app` and `wallet smart contract`: create another wallet contract in your wallet app and try sending transactions between them. +- Continue to [Blockchain interaction](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network/) if you want to learn how to interact with `smart contracts` from outside the blockchain. +- Or dive into [Developing smart contracts](/v3/guidelines/quick-start/developing-smart-contracts/setup-environment/) to learn how to develop `smart contracts` by yourself! **Happy creating on TON!** From eae3f8244c60e0d57d7c41516f4f6a7b3369fdff Mon Sep 17 00:00:00 2001 From: Andrey Zhukov Date: Mon, 21 Apr 2025 15:31:12 +0300 Subject: [PATCH 2/3] Standartized quick-start content --- .../reading-from-network.mdx | 43 ++++++----- .../writing-to-network.mdx | 38 ++++----- .../deploying-to-network.mdx | 61 ++++++++------- .../processing-messages.mdx | 71 ++++++++--------- .../setup-environment.mdx | 27 ++++--- .../storage-and-get-methods.mdx | 77 +++++++++++-------- .../quick-start/getting-started.mdx | 51 ++++++------ 7 files changed, 185 insertions(+), 183 deletions(-) diff --git a/docs/v3/guidelines/quick-start/blockchain-interaction/reading-from-network.mdx b/docs/v3/guidelines/quick-start/blockchain-interaction/reading-from-network.mdx index 613f87e7a30..5ff083b52d8 100644 --- a/docs/v3/guidelines/quick-start/blockchain-interaction/reading-from-network.mdx +++ b/docs/v3/guidelines/quick-start/blockchain-interaction/reading-from-network.mdx @@ -4,16 +4,16 @@ import ThemedImage from "@theme/ThemedImage"; ## Introduction -This guide will walk you through reading data from the TON Blockchain. You'll learn how to: +This guide will walk you through reading data from TON Blockchain. You'll learn how to: - Fetch account information -- Call get methods +- Call `get methods` - Retrieve account transactions -By the end, you'll understand how to interact with [TON HTTP-based APIs](/v3/guidelines/dapps/apis-sdks/ton-http-apis/). Particularly, in this guide [TON Center](https://toncenter.com/) is used, a fast and reliable HTTP API for TON. +By the end, you'll understand how to interact with [TON HTTP-based APIs](/v3/guidelines/dapps/apis-sdks/ton-http-apis/). In this guide, [TON Center](https://toncenter.com/) is used—a fast and reliable HTTP API for TON. -## Setup environment +## Set up environment -First, visit installation pages and install [NodeJS and npm](https://nodejs.org/en/download/) for your OS. Check that installation is correct by running those commands: +First, visit the installation pages and install [Node.js and npm](https://nodejs.org/en/download/) for your OS. Check that the installation is correct by running the following commands: ```bash node -v @@ -26,9 +26,9 @@ Version of `node` and `npm` should be at least `v20` and `v10` correspondingly. Let's set up our project structure: -1. Create a new directory for your project -2. Initialize a Node.js project -3. Install required dependencies +1. Create a new directory for your project +2. Initialize a Node.js project +3. Install the required dependencies Run these commands in your terminal: @@ -57,7 +57,7 @@ Account information includes the `balance`, `state`, `code`, and `data`. - `code`: The contract's code in raw format. - `data`: Serialized contract data stored in a [*Cell*](/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage/). -Account state may be obtained using [`getContractState`](https://testnet.toncenter.com/api/v2/#/accounts/get_address_information_getAddressInformation_get/) method. +Account state may be obtained using the [`getContractState`](https://testnet.toncenter.com/api/v2/#/accounts/get_address_information_getAddressInformation_get/) method. #### Implementation @@ -105,9 +105,9 @@ Code: b5ee9c7241021401000...c9ed54696225e5 ## Calling get methods -Get methods are special functions in smart contracts that allow you to observe current state of smart contract. Their execution doesn't cost any fees and can't change smart contract storage. +Get methods are special functions in smart contracts that allow you to observe the current state of a smart contract. Their execution doesn't cost any fees and can't change the smart contract's storage. -Result of calling get method from TON HTTP API comes in *stack* format and may be deserialized one by one using `readNumber()` or similar function. +The result of calling a get method from the TON HTTP API comes in *stack* format and may be deserialized one by one using `readNumber()` or a similar function. #### Implementation @@ -157,16 +157,17 @@ npx ts-node 2-call-get-method.ts ``` Get methods may also be called using Tonviewer: -1. Navigate to [get methods section](https://testnet.tonviewer.com/kQD0GKBM8ZbryVk2aESmzfU6b9b_8era_IkvBSELujFZPsyy?section=method). + +1. Navigate to the [get methods section](https://testnet.tonviewer.com/kQD0GKBM8ZbryVk2aESmzfU6b9b_8era_IkvBSELujFZPsyy?section=method). 2. Select `get_wallet_address`. -3. Insert address from example *0QD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje04A-* to slice section. +3. Insert the address from the example *0QD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje04A-* into the slice section. 4. Press **Execute**. -You will end up with same address you got from console. +You will end up with the same address you got from the console. ### Using wrappers for simplicity -Wrappers are classes that simplify interactions with smart contracts by turning complex blockchain operations into simple functions calls - instead of manually serializing cells and transactions, you can just call methods like `jettonMaster.getWalletAddress()` that already performs it for you. Here's an example of using a wrapper functionally equivalent to previous code snippet: +Wrappers are classes that simplify interactions with smart contracts by turning complex blockchain operations into simple function calls. Instead of manually serializing cells and transactions, you can just call methods like `jettonMaster.getWalletAddress()` that already perform these tasks for you. Here's an example of using a wrapper functionally equivalent to the previous code snippet: ```typescript import { Address, JettonMaster, TonClient } from "@ton/ton"; @@ -192,14 +193,14 @@ main(); ## Fetching account transactions -Interaction within account on blockchain happens due to [messages and transactions](/v3/documentation/smart-contracts/message-management/messages-and-transactions/). +Interaction within an account on the blockchain happens due to [messages and transactions](/v3/documentation/smart-contracts/message-management/messages-and-transactions/). ### What is a transaction? A transaction in TON consists of the following: -- the incoming message that initially triggers the contract (special ways to trigger exist) -- contract actions caused by the incoming message, such as an update to the contract's storage (optional) -- outgoing messages generated and sent to other actors (optional) +- The incoming message that initially triggers the contract (special ways to trigger exist) +- Contract actions caused by the incoming message, such as an update to the contract's storage (optional) +- Outgoing messages generated and sent to other actors (optional)
:::caution -Unlike in the [Reading from the Network](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network/) section, a Toncenter API key is mandatory in the following examples. It may be retrieved using [following guide](/v3/guidelines/dapps/apis-sdks/api-keys/). +Unlike in the [Reading from the Network](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network/) section, a Toncenter API key is mandatory in the following examples. It may be retrieved using [the following guide](/v3/guidelines/dapps/apis-sdks/api-keys/). ::: #### Implementation @@ -114,34 +114,34 @@ async function main() { main(); ``` -Using `API_KEY` in this case allows to have access to TON functionality by itself through `endpoint`. By running those script we authntificate to our wallet through `public/private key` pair generated through `mnemonic phrase` and, after preparing a transaction, send it TON, resulting in message that wallet sends to itself with *'Hello from wallet!'* message. +Using `API_KEY` in this case allows you to access TON functionality through the `endpoint`. By running this script, we authenticate to our wallet through a `public/private key` pair generated from the `mnemonic phrase`. After preparing a transaction, we send it to TON, resulting in a message that the wallet sends to itself with the *'Hello from wallet!'* message. :::caution Advanced Level In most scenarios, `SendMode.PAY_GAS_SEPARATELY | SendMode.IGNORE_ERRORS` will work, but if you want a deeper understanding, continue reading in the [message modes cookbook](/v3/documentation/smart-contracts/message-management/message-modes-cookbook/). ::: -Run this example using following command: +Run this example using the following command: ```bash npx ts-node 1-send-ton.ts ``` -#### Expected result +#### Expected Result -Navigate to [Tonviewer](https://testnet.tonviewer.com/) and paste your address into search bar. You should see TON transfer with *'Hello from wallet!'* comment. +Navigate to [Tonviewer](https://testnet.tonviewer.com/) and paste your address into the search bar. You should see a TON transfer with the *'Hello from wallet!'* comment. ## Sending NFTs [Non-fungible tokens](/v3/guidelines/dapps/asset-processing/nft-processing/nfts/) (NFTs) are assets like a piece of art, digital content, or video that have been tokenized via a blockchain. In TON, NFTs are represented via a collection of smart contracts: -- **NFT Collection**: stores information about the NFT collection. -- **NFT Item**: stores information about the NFT item that the user owns. +- **NFT Collection**: Stores information about the NFT collection. +- **NFT Item**: Stores information about the NFT item that the user owns. -To send NFT we should first acquire one. The easiest way to do that is to create and deploy your own NFT through [TON Tools](https://ton-collection-edit.vercel.app/deploy-nft-single). Note that `owner` addresses of your NFT must be your wallet address to be able to perform operations on it. +To send an NFT, we should first acquire one. The easiest way to do that is to create and deploy your own NFT through [TON Tools](https://ton-collection-edit.vercel.app/deploy-nft-single). Note that the `owner` addresses of your NFT must be your wallet address to be able to perform operations on it. -Basic operation of [NFT standard](https://github.com/ton-blockchain/TEPs/blob/master/text/0062-nft-standard.md) in TON is `transfer`. What is actually performed is changing adress of `owner` in NFT storage to `new owner`, which is address of another contract that is able to perform operations with `NFT Item` now. +The basic operation of the [NFT standard](https://github.com/ton-blockchain/TEPs/blob/master/text/0062-nft-standard.md) in TON is `transfer`. What is actually performed is changing the address of the `owner` in NFT storage to the `new owner`, which is the address of another contract that is now able to perform operations with the `NFT Item`. :::tip -See [Actors and roles](/v3/guidelines/quick-start/developing-smart-contracts/processing-messages#actors-and-roles/) to get more conceptual description. +See [Actors and Roles](/v3/guidelines/quick-start/developing-smart-contracts/processing-messages#actors-and-roles/) for a more conceptual description. ::: #### Implementation @@ -197,7 +197,7 @@ async function main() { main(); ``` -Run this example using following command: +Run this example using the following command: ```bash npx ts-node 2-send-nft.ts @@ -205,4 +205,4 @@ npx ts-node 2-send-nft.ts #### Expected result -Navigate to [Tonviewer](https://testnet.tonviewer.com/) and paste your address into search bar. You should see NFT transfer with *'Hello from NFT!'* comment. +Navigate to [Tonviewer](https://testnet.tonviewer.com/) and paste your address into the search bar. You should see an NFT transfer with the *'Hello from NFT!'* comment. diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx index 08d33021032..d1378760ad9 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx @@ -1,36 +1,36 @@ # Deploying to network -> **Summary:** In previous steps we developed and tested our smart contracts ensuring their correctness. +> **Summary:** In previous steps, we developed and tested our smart contracts, ensuring their correctness. -In this part of the guide we will proceed to deployment of previously developed smart contracts and cover interaction with them on-chain. +In this part of the guide, we will proceed with the deployment of previously developed smart contracts and cover interaction with them on-chain. ## Address and initial state -We already know that [address](/v3/documentation/smart-contracts/addresses/) is unique identifier of `smart contract` in network which is used to send transactions and verify their sender upon receive, but we still didn't discussed how it's created. The common formula of smart contract address looks like that: +We already know that [address](/v3/documentation/smart-contracts/addresses/) is a unique identifier of a `smart contract` on the network, used to send transactions and verify the sender upon receiving. However, we still haven't discussed how it's created. The common formula for a smart contract address looks like this: -***address=hash(state_init(code, data))*** +***address = hash(state_init(code, data))*** -Address of smart contract is a hash of aggregated initial code and data of smart contracts upon deployment. This simple mechanism have few important consequences: +The address of a smart contract is a hash of the aggregated initial code and data of the smart contract upon deployment. This simple mechanism has a few important consequences: ### You already know the address -In TON any address that don't have any data is considered in `nonexistent` state, nevertheless when we created a wallet using wallet app in [Getting started](/v3/guidelines/quick-start/getting-started) section we still was able to get address of our **future** wallet smart contract from wallet app before it's deployment and examine it in explorer. +In TON, any address that doesn't have any data is considered in the `nonexistent` state. Nevertheless, when we created a wallet using the wallet app in the [Getting Started](/v3/guidelines/quick-start/getting-started) section, we were still able to get the address of our **future** wallet smart contract from the wallet app before its deployment and examine it in the explorer. -The reason behind that is because creating your **private** and **public** key pair through **mnemonic phrase**, where second key is part of initial data of smart contract makes `state_init` of our contract fully determent: - - **code** is one of the standard wallet implementation, like `v5r1`. - - **data** is `public_key` with other default initialized fields. +The reason behind this is that creating your **private** and **public** key pair through a **mnemonic phrase**, where the second key is part of the initial data of the smart contract, makes the `state_init` of our contract fully determined: +- **code** is one of the standard wallet implementations, like `v5r1`. +- **data** is the `public_key` along with other default initialized fields. -Which makes it possible to calculate future wallet smart contract address. +This makes it possible to calculate the future wallet smart contract address. ### Magic storage member -In previous steps we deliberately didn't explain the purpose of `ctxID` and `ID` stored in our smart contracts state and remaining untouched in all smart contracts functionality. Now their purpose should start to be more clear. +In previous steps, we deliberately didn't explain the purpose of `ctxID` and `ID` stored in our smart contract's state, and how they remained untouched in all the smart contract functionality. Now, their purpose should start to become clearer. -Since we can't deploy smart contract with the same `state_init` the only way to provide same initial code and **"same"** initial data is to create separate filed in it ensuring additional uniqueness. Which in case of wallet gives you opportunity to have same key pair to several wallet smart contracts. +Since we can't deploy a smart contract with the same `state_init`, the only way to provide the same initial code and **"same"** initial data is to create a separate field in it, ensuring additional uniqueness. This, in the case of a wallet, gives you the opportunity to have the same key pair for several wallet smart contracts. ### One to rule them all -If you already considered that `ID` field is a must-have for any smart contract, there is another opportunity that could change your mind. Let's examine previously developed `CounterInternal` smart contract init section: +If you've already considered that the `ID` field is a must-have for any smart contract, there is another opportunity that could change your mind. Let's examine the previously developed `CounterInternal` smart contract's init section: ```tact init(id: Int, owner: Address) { @@ -40,19 +40,19 @@ init(id: Int, owner: Address) { } ``` -If we remove `id` field from its initial storage we can ensure that **only one** `CounterInternal` smart-cotnract could exzist for a particular owner. +If we remove the `id` field from its initial storage, we can ensure that **only one** `CounterInternal` smart contract can exist for a particular owner. :::info Tokens -This mechanism plays cruicial role in [Jetton Processing](/v3/guidelines/dapps/asset-processing/jettons/), each non-native(jetton) token requires it's own `Jetton Wallet` for a particular owner and therefore provides a calculatable address from it, creating a **star scheme** with basic wallet in center. +This mechanism plays a crucial role in [Jetton Processing](/v3/guidelines/dapps/asset-processing/jettons/). Each non-native (jetton) token requires its own `Jetton Wallet` for a particular owner and therefore provides a calculable address for it, creating a **star scheme** with the basic wallet in the center. ::: ## Implementation -Now, when our smart contracts is fully tested, we are ready to deploy them into the TON. In `Blueprint SDK` this process is the same for both `Mainnet` and `Testnet` and any of the presented languages in guide: `FunC`, `Tact`, `Tolk`. +Now that our smart contracts are fully tested, we are ready to deploy them to TON. In `Blueprint SDK`, this process is the same for both `Mainnet` and `Testnet` and for any of the presented languages in the guide: `FunC`, `Tact`, or `Tolk`. ### Step 1: Update deployment script -Deploy scripts relays on the same wrappers that you have used in testing scripts, we will use one common script to deploy both of previously deployed smart contracts, update `deployHelloWorld.ts` with this code: +Deployment scripts rely on the same wrappers that you have used in testing scripts. We will use one common script to deploy both of the previously deployed smart contracts. Update `deployHelloWorld.ts` with this code: ```typescript title="/scripts/deployHelloWorld.ts" import { toNano } from '@ton/core'; @@ -98,15 +98,15 @@ export async function run(provider: NetworkProvider) { ### Step 2: Run deploy script -You can run scripts by entering following command: +You can run the script by entering the following command: ```bash npx blueprint run # deployHelloWorld # optionally directly pass script ``` -### Step 3: choose network +### Step 3: Choose network -After that you will see interactive menu allowing to choose network: +After that, you will see an interactive menu allowing you to choose a network: ```bash ? Which network do you want to use? (Use arrow keys) @@ -116,12 +116,13 @@ After that you will see interactive menu allowing to choose network: ``` :::danger -Before deployment to the `Mainnet` ensure that your smart contracts correspond to [Security Measures](/v3/guidelines/smart-contracts/security/overview/), as we sad before, `HelloWorld` smart contract **don't**. +Before deployment to the `Mainnet`, ensure that your smart contracts correspond to [Security Measures](/v3/guidelines/smart-contracts/security/overview/). As we said before, the `HelloWorld` smart contract **doesn't**. ::: -### Step 4: choose wallet app +### Step 4: Choose wallet app + +Next, choose the way to access your wallet. The easiest way to do that is using [TON Connect](/v3/guidelines/ton-connect/overview/) for the most popular wallet apps: `TonKeeper`, `MyTonWallet`, or `Tonhub`. -Next, choose the way to access your wallet, the easiest way to do that is using [TON Connect](/v3/guidelines/ton-connect/overview/) for most popular wallet apps: `TonKeeper`, `MyTonWallet` or `Tonhub`. ```bash ? Which wallet are you using? (Use arrow keys) ❯ TON Connect compatible mobile wallet (example: Tonkeeper) @@ -134,23 +135,21 @@ Next, choose the way to access your wallet, the easiest way to do that is using Tonhub ``` -Finally scan QR code in the terminal through your wallet app and connect the wallet. After you done that for the first time in project this step will be skipped. +Finally, scan the QR code in the terminal through your wallet app and connect the wallet. After you've done that for the first time in the project, this step will be skipped. -You will recieve a transaction request in your wallet app each time your code require currency for transaction. +You will receive a transaction request in your wallet app each time your code requires currency for a transaction. -### Step 5: observe your smart contract in network +### Step 5: Observe your smart contract in network - After confirming request in your wallet and awaiting for deployment you will see corresponding message with the reference to your newly deployed smart contract view in explorer: +After confirming the request in your wallet and awaiting deployment, you will see a corresponding message with a reference to your newly deployed smart contract view in the explorer: ```bash Contract deployed at address EQBrFHgzSwxVYBXjIYAM6g2RHbeFebJA8QUDwg4IX8CPDPug You can view it at https://testnet.tonscan.org/address/EQBrFHgzSwxVYBXjIYAM6g2RHbeFebJA8QUDwg4IX8CPDPug ``` -**Congratulations!** Your custom `smart contracts` is ready to execute `get methods` same way as your wallet in [Getting started](/v3/guidelines/quick-start/getting-started#navigation-tabs/) section and execute `transactions` same as in [Blockchain Interaction](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network) section - consider it's reading to understand how to interact with `smart contracts` off-chain if you still don't. +**Congratulations!** Your custom `smart contract` is ready to execute `get methods` the same way as your wallet in the [Getting started](/v3/guidelines/quick-start/getting-started#navigation-tabs/) section and execute `transactions` the same as in the [Blockchain Interaction](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network) section — consider reading it to understand how to interact with `smart contracts` off-chain if you haven't already. :::tip -Using `Blueprint SDK` and wallet apps is not the only option, you can create message with [state_init](/v3/documentation/smart-contracts/message-management/sending-messages#message-layout/) by yourself, moreover you can do it even through smart contract [internal message](/v3/documentation/smart-contracts/message-management/sending-messages#message-layout/). +Using `Blueprint SDK` and wallet apps is not the only option. You can create a message with [state_init](/v3/documentation/smart-contracts/message-management/sending-messages#message-layout/) by yourself. Moreover, you can do it even through a smart contract's [internal message](/v3/documentation/smart-contracts/message-management/sending-messages#message-layout/). ::: - - diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx index 947c83af532..eb4f79d60f8 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx @@ -17,7 +17,7 @@ If you are stuck on some of the examples, you can find the original template pro Before we proceed to implementation, let's briefly describe the main ways and patterns that we can use to process internal messages. -### Actors and Roles +### Actors and roles Since TON implements the [actor](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains/#single-actor/) model, it's natural to think about smart contract relations in terms of `roles`, determining who can access smart contract functionality or not. The most common examples of roles are: @@ -176,7 +176,7 @@ fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: sli -By combining both of these patterns you can achieve a comprehensive description of your smart contract's systems ensuring secure interaction between them and unleash full potential of TON actors model. +By combining both of these patterns, you can achieve a comprehensive description of your smart contract's systems, ensuring secure interaction between them and unleashing the full potential of the TON actors model. ## Implementation in Tact @@ -186,11 +186,11 @@ Tact is a high-level programming language for the TON Blockchain, focused on eff For more details, refer to the [Tact documentation](https://docs.tact-lang.org/#start/) and [Tact By Example](https://tact-by-example.org/00-hello-world/). ::: -Let's create and modify our smart contract folowing standard steps decsribed in previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. +Let's create and modify our smart contract following the standard steps described in the previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. ### Step 1: Creating and modifying Tact contract -First, let's create Tact contract in the same directory as previous one. +First, let's create the Tact contract in the same directory as the previous one. ```bash npx blueprint create CounterInternal --type tact-counter @@ -285,7 +285,7 @@ contract CounterInternal { #### Contract storage -A contract may store its state variables as follows. They may be accessed with [`Self reference`](https://docs.tact-lang.org/book/contracts/#self) +A contract may store its state variables as follows. They may be accessed with [`Self reference`](https://docs.tact-lang.org/book/contracts/#self). ```tact id: Int as uint32; @@ -325,7 +325,7 @@ receive(msg: Add) { } ``` -For accepting messages with empty body you can add `recieve` function with no arguments: +For accepting messages with an empty body, you can add a `receive` function with no arguments: ```tact title="/contracts/counter_internal.tact" receive() { @@ -335,8 +335,7 @@ receive() { #### Restricting access - -Tact also provides handy ways to share same logic through [traits](https://docs.tact-lang.org/book/types/#traits). To ensure that only the contract owner can send messages use the `Ownable` trait, which provides built-in ownership checks: +Tact also provides handy ways to share the same logic through [traits](https://docs.tact-lang.org/book/types/#traits). To ensure that only the contract owner can send messages, use the `Ownable` trait, which provides built-in ownership checks: ```tact title="/contracts/counter_internal.tact" // Import library to use trait @@ -364,7 +363,7 @@ contract CounterInternal with Ownable { Tact supports [getter functions](https://docs.tact-lang.org/book/functions/#getter-functions) for retrieving contract state off-chain: :::note -Get function cannot be called from another contract. +The get function cannot be called from another contract. ::: ```tact title="/contracts/counter_internal.tact" @@ -373,7 +372,7 @@ get fun counter(): Int { } ``` -Note, that the `owner` getter is automatically defined via the `Ownable` trait. +Note that the `owner` getter is automatically defined via the `Ownable` trait. #### Complete contract @@ -427,7 +426,7 @@ contract CounterInternal with Ownable { } ``` -Verify that smart contract code is correct by running build script: +Verify that the smart contract code is correct by running the build script: ```bash npx blueprint build @@ -457,12 +456,12 @@ export * from '../build/CounterInternal/tact_CounterInternal'; ### Step 3: Updating tests -Now let's ensure that our smart contract code fails when we try to send `add` message from non-owner: +Now let's ensure that our smart contract code fails when we try to send the `add` message from a non-owner: - Create `CounterInternal` with some owner. - - Create another smart contract that will have different address - `nonOwner`. - - Try to send an internal message to `CounterInternal` and enusre that it fails with expected `exitCode` and counter field remains the same. + - Create another smart contract that will have a different address - `nonOwner`. + - Try to send an internal message to `CounterInternal` and ensure that it fails with the expected `exitCode` and the counter field remains the same. -Implementation of test should look like this: +The implementation of the test should look like this: ```typescript title="/tests/CounterInternal.spec.ts" import { Blockchain, SandboxContract, TreasuryContract} from '@ton/sandbox'; @@ -537,7 +536,7 @@ describe('CounterInternal', () => { ``` -Don't forget to verify that all examples is correct by running test script: +Don't forget to verify that all examples are correct by running the test script: ```bash npx blueprint test @@ -561,21 +560,21 @@ Ran all test suites matching /CounterInternal/i. ## External Messages -`External messages` are your only way of toggling smart contract logic from outside the blockchain. Usually, there is no need for implementation of them in smart contracts because in most cases you don't want external entry points to be accessible to anyone except you. If this is all functionality that you want from external section - standard way is to delegate this responsibility to separate actor - [wallet](v3/documentation/smart-contracts/contracts-specs/wallet-contracts#basic-wallets/), which is practically the main reason they were designed for. +`External messages` are your only way of toggling smart contract logic from outside the blockchain. Usually, there is no need for implementation of them in smart contracts because, in most cases, you don't want external entry points to be accessible to anyone except you. If this is all the functionality that you want from the external section, the standard way is to delegate this responsibility to a separate actor - [wallet](v3/documentation/smart-contracts/contracts-specs/wallet-contracts#basic-wallets/), which is practically the main reason they were designed for. -Developing external endpoint includes several standard [approuches](/v3/documentation/smart-contracts/message-management/external-messages/) and [security measures](/v3/guidelines/smart-contracts/security/overview/) that might be overwhelming at this point. Therefore in this guide we will realize incrementing previously added to `hello_world` contract `ctxCounterExt` number and add send message to out `Tact` contract. +Developing external endpoints includes several standard [approaches](/v3/documentation/smart-contracts/message-management/external-messages/) and [security measures](/v3/guidelines/smart-contracts/security/overview/) that might be overwhelming at this point. Therefore, in this guide, we will implement incrementing the previously added `ctxCounterExt` number and add a send message to our `Tact` contract. :::danger -This implementation is **unsafe** and may lead to loosing your contract funds. Don't deploy it to `Mainnet`, especially with high smart contract balance. +This implementation is **unsafe** and may lead to losing your contract funds. Don't deploy it to `Mainnet`, especially with a high smart contract balance. ::: ## Implementation -Let's modify our smart contract to recieve external messages folowing standard steps decsribed in previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. +Let's modify our smart contract to receive external messages following the standard steps described in the previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. -### Step1 : Edit smart contract code +### Step 1: Edit smart contract code -Add `recv_external` function to `HelloWorld` smart contract: +Add the `recv_external` function to the `HelloWorld` smart contract: @@ -640,16 +639,15 @@ fun onExternalMessage(inMsg: slice) { -This function upon recieving an external message will increment our `ctxCounter` and also send an internal message to specified address with `increase` operation that we will use to increment counter on our `CounterInternal` smart contract. - +This function, upon receiving an external message, will increment our `ctxCounter` and also send an internal message to the specified address with the `increase` operation, which we will use to increment the counter on our `CounterInternal` smart contract. -Verify that smart contract code is correct by running: +Verify that the smart contract code is correct by running: ```bash npx blueprint build ``` -Expected should look like this: +Expected output should look like this: ```bash ✅ Compiled successfully! Cell BOC result: @@ -663,9 +661,9 @@ Expected should look like this: ✅ Wrote compilation artifact to build/HelloWorld.compiled.json ``` -### Step 2: Update Wrapper +### Step 2: Update Wrapper -And add wrapper method to call it through our wrapper class for sending external message: +Add a wrapper method to call it through our wrapper class for sending external messages: ```typescript title="/wrappers/HelloWorld.ts" async sendExternalIncrease( @@ -688,9 +686,9 @@ async sendExternalIncrease( } ``` -### Step 3: Update test +### Step 3: Update Test -Update test to ensure that `HelloWorld` contract recieved external message, sended internal message to `CounterInternal` contract and both updated their counters: +Update the test to ensure that the `HelloWorld` contract received the external message, sent an internal message to the `CounterInternal` contract, and both updated their counters: ```typescript title="/tests/HelloWorld.spec.ts" import { Blockchain, SandboxContract, TreasuryContract } from '@ton/sandbox'; @@ -789,19 +787,18 @@ describe('HelloWorld', () => { // ... previous tests }); ``` +This test describes the common transaction flow of any `multi-contract` system: +1. Send an external message to toggle the smart contract logic from outside the blockchain. +2. Trigger one or more internal messages to be sent to other contracts. +3. Upon receiving an internal message, change the contract state and repeat **step 2** if required. -This test describes common trascantion flow of any `multi-contract` system: - 1. Send external message to toggle smart contracts logic from outside the blockchain. - 2. Provoke one or more sending of internal messages to other contracts. - 3. Upon recieving an internal message change contract state and repeat **step 2** if required. - -Since resulting sequence of transactions might be overwhelming for understanding, it's a good practice to make a `sequence diagram` describing your system, here is an example of our case: +Since the resulting sequence of transactions might be overwhelming for understanding, it's a good practice to create a `sequence diagram` describing your system. Here is an example of our case:
Multi-contract scheme
-Verify that all examples is correct by running test script: +Verify that all examples are correct by running the test script: ```bash npx blueprint test diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx index 5c357651b17..96ace9f43c7 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/setup-environment.mdx @@ -11,11 +11,11 @@ This guide covers the basic steps of setting up your smart contract development ## Setup development environment -For this guide, we will rely on the [Blueprint SDK](https://github.com/ton-org/blueprint/) and [Node.js](https://nodejs.org/en)/TypeScript stack for writing wrappers, tests, and deployment scripts for your smart contract, because it provides the easiest, ready-to-use environment for smart contract development. +For this guide, we will rely on the [Blueprint SDK](https://github.com/ton-org/blueprint/) and [Node.js](https://nodejs.org/en)/TypeScript stack for writing wrappers, tests, and deployment scripts for your smart contract, as it provides the easiest, ready-to-use environment for smart contract development. :::info -Using native instruments and language-dependent SDKs for smart contract development is covered in more advanced sections here: -- [Compile and build smart contracts on TON](/v3/documentation/archive/compile#ton-compiler/). +Using native tools and language-dependent SDKs for smart contract development is covered in more advanced sections here: +- [Compile and Build Smart Contracts on TON](/v3/documentation/archive/compile#ton-compiler/). - [Creating State Init for Deployment](/v3/guidelines/smart-contracts/howto/wallet#creating-the-state-init-for-deployment/). ::: @@ -32,13 +32,13 @@ node -v ### Step 2: Choose a smart contract development language -During the guide, we provide examples in `Func`, `Tolk`, and `Tact`. You can choose any of them and even combine smart contracts in different languages. To proceed through the guide, there is no need for a deep understanding of the chosen language—basic programming skills will be enough. +During the guide, we provide examples in `FunC`, `Tolk`, and `Tact`. You can choose any of them and even combine smart contracts in different languages. To proceed through the guide, there is no need for a deep understanding of the chosen language—basic programming skills will be enough. :::info You can find a brief overview of the languages here: [Programming languages](/v3/documentation/smart-contracts/overview#programming-languages/) ::: -### Step 3: Setup Blueprint SDK +### Step 3: Set up Blueprint SDK Change the directory to the parent folder of your future project and run the following command: @@ -47,20 +47,19 @@ npm create ton@latest ``` This will run an interactive script to create the project template. You can enter anything you want, but if you want to follow the same paths as in this guide, choose the following: -1. Project name: `Example`. -2. First created contract name: `HelloWorld`. -3. Choose the project template: A **simple counter contract** in `FunC` or `Tolk`. -Finally, change your current directory to the generated project template folder, and install all required dependencies: +1. **Project name**: `Example` +2. **First contract name**: `HelloWorld` +3. **Project template**: A **simple counter contract** in `FunC` or `Tact` + +Finally, change your current directory to the generated project template folder and install all required dependencies: ```bash cd ./Example npm install ``` +### Step 4 (Optional): IDE and Editor Support -### Step 4 (optional): IDE and Editor Support - -TON Community has developed plugins providing syntax support for several IDEs and code editors. You can find them here: [Plugin List](https://docs.ton.org/v3/documentation/smart-contracts/getting-started/ide-plugins/). - -Also, consider installing plugins that provide support for **JavaScript/TypeScript** tools for your preferred IDE or code editor, and specifically, `Jest` for debugging smart contract tests. +The TON community has developed plugins that provide syntax support for several IDEs and code editors. You can find them here: [Plugin List](https://docs.ton.org/v3/documentation/smart-contracts/getting-started/ide-plugins/). +Also, consider installing plugins that support **JavaScript/TypeScript** tools for your preferred IDE or code editor, specifically `Jest` for debugging smart contract tests. diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx index 63d79ff67cb..e60f6da62bf 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx @@ -1,16 +1,15 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Storage and Get Methods +# Storage and get methods -> **Summary:** In the previous steps, we learned how to use `Blueprint SDK` and its project structure. +> **Summary:** In the previous steps, we learned how to use the `Blueprint SDK` and its project structure. :::tip -If you are stuck on some of the examples, you can find the original template project with all modifications performed during this guide [here](https://github.com/ton-community/onboarding-sandbox/tree/main/quick-start/smart-contracts/Example/contracts). +If you're stuck on any of the examples, you can find the original template project with all modifications made during this guide [here](https://github.com/ton-community/onboarding-sandbox/tree/main/quick-start/smart-contracts/Example/contracts). ::: -Almost all smart contracts need to store their `data` between transactions. This guide explains standard ways of managing `storage` for smart contracts and using `get methods` to obtain it from outside the blockchain. - +Almost all smart contracts need to store their `data` between transactions. This guide explains standard ways to manage `storage` for smart contracts and how to use `get methods` to access it from outside the blockchain. ## Smart contract storage operations @@ -31,17 +30,17 @@ There are two main instructions that provide access to smart contract storage: -Let's examine the [Cell](/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage) entity structure to understand how we could manage contract storage: +Let's examine the [Cell](/v3/concepts/dive-into-ton/ton-blockchain/cells-as-data-storage) structure to understand how to manage contract storage: -## Cell Structure +## Cell structure -TON Blockchain uses a data structure called **`Cell`** as the fundamental unit for storing data. `Cells` are the building blocks of smart contract data and have the following characteristics: +TON Blockchain uses a data structure called **Cell** as the fundamental unit for storing data. Cells are the building blocks of smart contract data and have the following characteristics: -- A `Cell` can store up to 1023 bits (approximately 128 bytes) of data. -- A `Cell` can reference up to 4 other `Cells` (children). -- A `Cell` is immutable once created. +- A Cell can store up to 1023 bits (approximately 128 bytes) of data +- A Cell can reference up to 4 other Cells (children) +- A Cell is immutable once created -You can think of a `Cell` as the following structure: +You can think of a Cell as the following structure: ```typescript // Conceptual representation of a Cell @@ -53,11 +52,11 @@ interface Cell { ## Implementation -Let's try to modify our smart contract following the standard steps described in the previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. +Let's modify our smart contract by following the standard steps described in the previous [Blueprint SDK overview](/v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview/) section. ### Step 1: Edit smart contract code -In case it's inconvenient to always serialize and deserialize the storage cell, there is a common practice to define two wrapper methods that provide the corresponding logic. If you didn't change the smart contract code, it should contain the following lines: +If manually serializing and deserializing the storage cell becomes inconvenient, a common practice is to define two wrapper methods that handle this logic. If you haven't modified the smart contract code, it should include the following lines: @@ -113,13 +112,17 @@ fun saveData() { -#### Managing Storage +#### Managing storage -Let's try to modify our example a little bit. First, let's examine a different approach to managing storage, widely used in smart contract development: +Let's modify our example slightly by exploring another common storage management approach in smart contract development: -Instead of initializing global variables, we will pass storage members as parameters to `save_data(members...)` and retrieve them as `(members...) get_data()`, moving global variables `ctx_id` and `ctx_counter` to the method bodies. Additionally, let's add an extra 256-bit integer into our storage. +Rather than initializing global variables, we'll: +1. Pass storage members as parameters via `save_data(members...)` +2. Retrieve them using `(members...) = get_data()` +3. Move the global variables `ctx_id` and `ctx_counter` into method bodies +4. Add an additional 256-bit integer to our storage -The result of our modifications should look like this: +The modified implementation should appear as follows: @@ -179,7 +182,9 @@ fun saveData(ctxID: int, ctxCounter: int, ctxCounterExt: int) { -Don't forget to delete the global variables `ctx_id` and `ctx_counter`, and modify the usage of the function like this, copying the storage members locally: +Remember to: +1. Remove the global variables `ctx_id` and `ctx_counter` +2. Update function usage by copying storage members locally as shown: @@ -204,7 +209,7 @@ saveData(ctxID, ctxCounter, ctxCounterExt); #### Get methods -The primary use of `get methods` is reading our storage data from outside the blockchain using a convenient interface, primarily to extract data that is required to prepare a **transaction**. +The main purpose of `get methods` is to provide external read access to storage data through a convenient interface, primarily for extracting information needed to prepare **transactions**. @@ -225,9 +230,9 @@ get get_counters(): (int, int) { -And that's it! In practice, all **get methods** follow this simple flow and don't require anything more. Note that you can omit values returned from functions using the `_` syntax. +And that's all! In practice, all **get methods** follow this straightforward pattern and require no additional complexity. Remember you can ignore return values using the `_` placeholder syntax. -The final smart contract code should look like this: +Here's the final smart contract implementation: @@ -370,7 +375,7 @@ get get_counters(): (int, int) { -Don't forget to check the correctness of your changes by compiling the smart contract: +Before proceeding, verify your changes by compiling the smart contract: ```bash npx blueprint build @@ -394,7 +399,14 @@ Build script running, compiling HelloWorld ### Step 2: Update wrapper -Now, let's update our wrapper class to correspond to the new storage layout and the new `get method`. First, let's modify the `helloWorldConfigToCell` function and the `HelloWorldConfig` type to properly initialize our storage during smart contract creation, including the 256-bit `ctxCounterExt` field that we previously added to the smart contract: +Next, we'll update our wrapper class to align with the new storage layout and `get method`. We need to: + +1. Modify the `helloWorldConfigToCell` function +2. Update the `HelloWorldConfig` type +3. Ensure proper storage initialization during contract creation +4. Include the 256-bit `ctxCounterExt` field we added earlier + +These changes will maintain consistency with our smart contract modifications. ```typescript title="/wrappers/HelloWorld.ts" export type HelloWorldConfig = { @@ -412,7 +424,7 @@ export function helloWorldConfigToCell(config: HelloWorldConfig): Cell { } ``` -Second, add a method to perform a request for the newly created smart contract method `get_counters`, which will retrieve both counters at once: +Next, implement a method to call the new `get_counters` smart contract function, which retrieves both counter values in a single request: ```typescript title="/HelloWorld.ts" async getCounters(provider: ContractProvider) : Promise<[number, bigint]> { @@ -424,14 +436,15 @@ async getCounters(provider: ContractProvider) : Promise<[number, bigint]> { } ``` -### Step 3: Update Tests +### Step 3: Update tests + +Finally, let's test the new functionality using our updated wrapper: -And finally, let's test our new functionality through the previously updated wrapper: -- Create and initialize smart contract storage members with some value through `helloWorldConfig`. -- Call each of the `get` methods and retrieve storage members. -- Verify that they have stayed the same as during creation. +1. Initialize contract storage by creating a `helloWorldConfig` with test values +2. Execute each `get` method to retrieve stored data +3. Validate that values match the initial configuration -Here is an example of such an implementation: +Example implementation: ```typescript title="/tests/HelloWorld.spec.ts" import { Blockchain, SandboxContract, TreasuryContract } from '@ton/sandbox'; @@ -512,7 +525,7 @@ describe('HelloWorld', () => { }); ``` -And now, run your new test script by executing the following command: +Now you can run the new test script with this command: ```bash npx blueprint test diff --git a/docs/v3/guidelines/quick-start/getting-started.mdx b/docs/v3/guidelines/quick-start/getting-started.mdx index 6f32b03751c..77ba9e8d3d6 100644 --- a/docs/v3/guidelines/quick-start/getting-started.mdx +++ b/docs/v3/guidelines/quick-start/getting-started.mdx @@ -15,20 +15,20 @@ Welcome to the TON Quick Start Guide! This guide will give you a starting point ## What You'll Learn - Interact with TON Ecosystem: Wallets and Explorers. -- Set up the development environment: use the Blueprint SDK for developing `smart contracts` using `FunC`, `Tact`, and `Tolk` programming languages. +- Set up the development environment: use the Blueprint SDK for developing `smart contracts` using the `FunC`, `Tact`, and `Tolk` programming languages. - Send transactions and read from TON Blockchain using your preferred programming language and available `SDKs`. -- Core concepts of the TON Blockchain: `messages`, `smart contracts`, `addresses`, etc. +- Core concepts of TON Blockchain: `messages`, `smart contracts`, `addresses`, etc. - Basic templates ready for implementing your project logic. ## Concept of smart contract -You can think of smart contracts in TON as a program running on the blockchain, following the well-known behavioral concept of [Actor](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains#single-actor/). +You can think of smart contracts in TON as programs running on the blockchain, following the well-known behavioral concept of the [Actor](/v3/concepts/dive-into-ton/ton-blockchain/blockchain-of-blockchains#single-actor/) model. :::info In contrast to some other blockchains, where you can call other contract codes synchronously, a smart contract in TON is a standalone entity that communicates with other smart contracts on an equal basis by sending asynchronous messages between them. ::: -Each processing of a message by the receiver smart contract is considered a transaction, resulting in the following actions: +Each processing of a message by the receiving smart contract is considered a transaction, resulting in the following actions: - Sending further messages. - Changing internal data or even the code of the smart contract itself. - Changing its balance. @@ -50,27 +50,27 @@ Before we start our journey to becoming a TON developer, we should become advanc ### Step 1: Create a new wallet using an app -The simplest way to create a `wallet` is to visit https://ton.org/wallets and choose one of the wallet apps from the list. They are all pretty similar, so let's choose [Tonkeeper](https://tonkeeper.com/). Go ahead, install, and run it. +The simplest way to create a `wallet` is to visit https://ton.org/wallets and choose one of the wallet apps from the list. They are all pretty similar, so let's choose [Tonkeeper](https://tonkeeper.com/). Go ahead, install it, and run it. ### Step 2: Mainnet and Testnet In TON, there are two different networks called `Mainnet` and `Testnet`, each with distinct roles: - `Mainnet` is the primary network where actual transactions take place, carrying real economic value as they involve real cryptocurrency. -- `Testnet` is a testing version of the TON **Blockchain** designed for development and testing purposes. It's a risk-free zone for developers to test without financial implications. It's mainly used for development, testing `smart contracts`, and trying new features. +- `Testnet` is a testing version of TON Blockchain designed for development and testing purposes. It's a risk-free zone for developers to test without financial implications. It's mainly used for development, testing `smart contracts`, and trying new features. #### Getting funds -Transactions in TON always require some amount of funds, as executing smart contract code requires a [fee](/v3/documentation/smart-contracts/transaction-fees/fees/) payment. TON basic transactions are very cheap, about 1 cent per transaction. Getting an equivalent of $5 worth of [Toncoin](/v3/documentation/dapps/defi/coins/) will be enough for hundreds of them. Here’s how you can get them: +Transactions in TON always require some amount of funds, as executing smart contract code requires a [fee](/v3/documentation/smart-contracts/transaction-fees/fees/) payment. TON basic transactions are very cheap—about 1 cent per transaction. Getting the equivalent of $5 worth of [Toncoin](/v3/documentation/dapps/defi/coins/) will be enough for hundreds of them. Here’s how you can get them: -- For `Mainnet`, you can get `Toncoins` by simply pressing the buy button in the user interface, or ask someone to send them to your `address`, which you can copy from the wallet app, usually located near your balance. +- For `Mainnet`, you can get `Toncoins` by simply pressing the buy button in the user interface or asking someone to send them to your `address`, which you can copy from the wallet app, usually located near your balance. :::warning Don't worry, sharing your `address` is **totally safe**, unless you don't want it to be associated with you. ::: - - For `Testnet` version, you can request funds from the [Testgiver Ton Bot](https://t.me/testgiver_ton_bot/) **completely for free**! After a short wait, you will receive 2 `Toncoins` that will appear in your wallet app. +- For the `Testnet` version, you can request funds from the [Testgiver Ton Bot](https://t.me/testgiver_ton_bot/) **completely for free**! After a short wait, you will receive 2 `Toncoins` that will appear in your wallet app. -### Step 3: Creating a Testnet wallet +### Step 3: Creating a testnet wallet If you decide to use the `Testnet` version, you can do so by following the guide below. @@ -82,7 +82,7 @@ To create your first Testnet wallet in Tonkeeper, you should obtain a mnemonic u #### Creating wallet -To create Testnet wallet click *`Wallet`* -> *`Add Wallet`* - *`TestnetAccount`*. Then import seed phrase generated in previous step. +To create a Testnet wallet, click *`Wallet`* -> *`Add Wallet`* -> *`TestnetAccount`*. Then import the seed phrase generated in the previous step.

@@ -100,12 +100,12 @@ To create Testnet wallet click *`Wallet`* -> *`Add Wallet`* - *`TestnetAccount`* ### Step 4: Exploring TON Blockchain -Congratulations! We created our first wallet and received some funds in it. Now let's take a look at how our actions are reflected in the blockchain. We can do this by using various [explorers](https://ton.app/explorers/). +Congratulations! We’ve created our first wallet and received some funds in it. Now let's take a look at how our actions are reflected in the blockchain. We can do this by using various [explorers](https://ton.app/explorers/). An `explorer` is a tool that allows you to query data from the chain, investigate TON `smart contracts`, and view transactions. For our examples, we are going to use [Tonviewer](https://tonviewer.com/). :::tip -Note that when using the `Testnet`, you should manually change the explorer mode to the `Testnet` version. Don't forget that these are different networks, not sharing any transactions or smart contracts. Therefore, your `Testnet` wallet would not be visible in `Mainnet` mode and vice versa. +Note that when using the `Testnet`, you should manually change the explorer mode to the `Testnet` version. Don't forget that these are different networks, not sharing any transactions or smart contracts. Therefore, your `Testnet` wallet will not be visible in `Mainnet` mode and vice versa. ::: Let's take a look at our newly created wallet using the `explorer`: copy your wallet address from the app and insert it into the search bar of the explorer like this: @@ -124,27 +124,20 @@ First, let's examine the common [address state](/v3/documentation/smart-contract Screenshot of nonexistent wallet state
-- `Uninit`: Stands for an address that has some metadata, such as funds, but hasn't been initialized by deployed `smart contract` code or data.. +- `Uninit`: Stands for an address that has some metadata, such as funds, but hasn't been initialized by deployed `smart contract` code or data.
Screenshot of uninitialized wallet state
:::info -<<<<<<< Updated upstream -This might seem unintuitive, why is your wallet in `uninit` state when you already created it? There is little difference between `wallet app` and `wallet smart contract`: - -- `wallet app` is your off-chain client for `wallet smart contract` -- `wallet smart contract` is contract itself, since its deployment requires some fees most `wallet apps` don't actually deploy the wallet `smart contract` until you receive funds on your address and try to make your first transaction. -======= This might seem unintuitive: why is your wallet in the `uninit` state when you’ve already created it? There is a small difference between the `wallet app` and the `wallet smart contract`: - The `wallet app` is your off-chain client for the `wallet smart contract`. - The `wallet smart contract` is the contract itself. Since its deployment requires some fees, most `wallet apps` don’t actually deploy the wallet `smart contract` until you receive funds on your address and try to make your first transaction. ->>>>>>> Stashed changes ::: -- `Active`: This is the state of a deployed `smart contract` with a positive balance. To deploy our wallet, let's send the first transaction to someone special—**ourselves**. And see how it looks on the `blockchain`. Enter the send menu in your wallet app and transfer some funds to your own address that you’ve copied before. In the explorer, our contract should start looking something like this: +- `Active`: This is the state of a deployed `smart contract` with a positive balance. To deploy our wallet, let's send the first transaction to someone special—**ourselves**—and see how it looks on the `blockchain`. Enter the send menu in your wallet app and transfer some funds to your own address that you’ve copied before. In the explorer, our contract should start looking something like this:
Screenshot of active wallet state @@ -154,24 +147,24 @@ This might seem unintuitive: why is your wallet in the `uninit` state when you There is also a fourth state called [frozen](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee/), which stands for a smart contract with a [storage charge](/v3/documentation/smart-contracts/transaction-fees/fees-low-level#storage-fee/) that exceeds its balance. In this state, the smart contract cannot perform any operations. ::: -And here we are, our wallet contract is deployed and ready to use. Let's examine the provided user interface: +And here we are — our wallet contract is deployed and ready to use. Let's examine the provided user interface: -#### Metadata Section +#### Metadata section - **Address**: Your account's unique ID (e.g., `QQB...1g6VdFEg`) - **Balance**: Current TON amount - **Type**: Contract version (e.g., `wallet_v5r1` – detected automatically by code) - **State**: Address state. It may be `nonexisting`, `uninit`, `active`, or `frozen`. -#### Navigation Tabs +#### Navigation tabs - **History/Transactions**: Displays recent activity (e.g., received funds, contract deployments). -- **Code**: Shows raw smart contract code compiled from `Func`/`Tact`/`Tolk`. +- **Code**: Shows raw smart contract code compiled from `FunC`/`Tact`/`Tolk`. - **Methods**: Allows execution of `get methods` to retrieve persistent contract data. -## Next Steps: +## Next steps: - Try experimenting with the `wallet app` and `wallet smart contract`: create another wallet contract in your wallet app and try sending transactions between them. -- Continue to [Blockchain interaction](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network/) if you want to learn how to interact with `smart contracts` from outside the blockchain. -- Or dive into [Developing smart contracts](/v3/guidelines/quick-start/developing-smart-contracts/setup-environment/) to learn how to develop `smart contracts` by yourself! +- Continue to [Blockchain Interaction](/v3/guidelines/quick-start/blockchain-interaction/reading-from-network/) if you want to learn how to interact with `smart contracts` from outside the blockchain. +- Or dive into [Developing Smart Contracts](/v3/guidelines/quick-start/developing-smart-contracts/setup-environment/) to learn how to develop `smart contracts` yourself! **Happy creating on TON!** From 0a7fc5a0b572909b40c87236ce90b19e7eaaca37 Mon Sep 17 00:00:00 2001 From: Alexey Ostrovsky Date: Tue, 22 Apr 2025 10:30:12 +0300 Subject: [PATCH 3/3] Internal review fixes --- .../developing-smart-contracts/deploying-to-network.mdx | 2 +- .../developing-smart-contracts/processing-messages.mdx | 4 ++-- .../developing-smart-contracts/storage-and-get-methods.mdx | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx index d1378760ad9..0664a6420d2 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/deploying-to-network.mdx @@ -24,7 +24,7 @@ This makes it possible to calculate the future wallet smart contract address. ### Magic storage member -In previous steps, we deliberately didn't explain the purpose of `ctxID` and `ID` stored in our smart contract's state, and how they remained untouched in all the smart contract functionality. Now, their purpose should start to become clearer. +In previous steps, we deliberately didn't explain the purpose of `ctxID` and `ID` stored in our smart contract's state, and why they remained untouched in all the smart contract functionality. Now, their purpose should start to become clearer. Since we can't deploy a smart contract with the same `state_init`, the only way to provide the same initial code and **"same"** initial data is to create a separate field in it, ensuring additional uniqueness. This, in the case of a wallet, gives you the opportunity to have the same key pair for several wallet smart contracts. diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx index eb4f79d60f8..008016cc0d1 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/processing-messages.mdx @@ -51,7 +51,7 @@ fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: sli You can find a comprehensive description of sending messages in this [section](/v3/documentation/smart-contracts/message-management/sending-messages#message-layout/). ::: -What we are specifically interested in is the source address of the message, which we can extract from the `msg_full` cell. By obtaining that address and comparing it to a stored one—saved previously, for example, during deployment—we can conditionally allow access to crucial parts of our smart contract functionality. A common approach looks like this: +What we are specifically interested in is the source address of the message, which we can extract from the `msg_full` cell. By obtaining that address and comparing it to a stored one — we can conditionally allow access to crucial parts of our smart contract functionality. A common approach looks like this: @@ -639,7 +639,7 @@ fun onExternalMessage(inMsg: slice) { -This function, upon receiving an external message, will increment our `ctxCounter` and also send an internal message to the specified address with the `increase` operation, which we will use to increment the counter on our `CounterInternal` smart contract. +This function, upon receiving an external message, will increment our `ctxCounterExt` and also send an internal message to the specified address with the `increase` operation, which we will use to increment the counter on our `CounterInternal` smart contract. Verify that the smart contract code is correct by running: diff --git a/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx b/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx index e60f6da62bf..b0dc2e1520d 100644 --- a/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx +++ b/docs/v3/guidelines/quick-start/developing-smart-contracts/storage-and-get-methods.mdx @@ -120,9 +120,9 @@ Rather than initializing global variables, we'll: 1. Pass storage members as parameters via `save_data(members...)` 2. Retrieve them using `(members...) = get_data()` 3. Move the global variables `ctx_id` and `ctx_counter` into method bodies -4. Add an additional 256-bit integer to our storage -The modified implementation should appear as follows: +Also lets add an additional **256-bit integer** to our storage. The modified implementation should appear as follows: + @@ -424,7 +424,7 @@ export function helloWorldConfigToCell(config: HelloWorldConfig): Cell { } ``` -Next, implement a method to call the new `get_counters` smart contract function, which retrieves both counter values in a single request: +Next, implement a method to call the new `get_counters` smart contract get method, which retrieves both counter values in a single request: ```typescript title="/HelloWorld.ts" async getCounters(provider: ContractProvider) : Promise<[number, bigint]> {