Skip to content

Content standartization #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
azhukov-pixelplex wants to merge 3 commits into from
Closed

Content standartization #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
87058d8
Content standartization, common fixes
Alexey-Ostrovsky Apr 21, 2025
eae3f82
Standartized quick-start content
azhukov-pixelplex Apr 21, 2025
0a7fc5a
Internal review fixes
Alexey-Ostrovsky Apr 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 22 additions & 21 deletions docs/v3/guidelines/quick-start/blockchain-interaction/reading-from-network.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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";
Expand All @@ -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)

<ThemedImage
alt=""
Expand All @@ -212,7 +213,7 @@ A transaction in TON consists of the following:

### Key transaction fields

Transaction obtained from API have the following structure:
A transaction obtained from the API has the following structure:

```json5
{
Expand Down Expand Up @@ -272,7 +273,7 @@ A message is a packet of data exchanged between actors (users, applications, or
- `source`: The address of the sender (the account that initiated the message).
- `destination`: The address of the receiver (the account that will process the message).
- `value`: The amount of TON (in nanoTON) attached to the message.
- `msg_data`: Contains message body and state init.
- `msg_data`: Contains the message body and state initialization.


#### Implementation
Expand Down
40 changes: 20 additions & 20 deletions docs/v3/guidelines/quick-start/blockchain-interaction/writing-to-network.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ In the previous section, you learned how to **read data** from the TON Blockchai

## Introduction

This guide will walk you through writing data from the TON Blockchain. You'll learn how to:
- Make transaction
- Transfer TON/NFT
This guide will walk you through writing data to the TON Blockchain. You'll learn how to:
- Make transactions
- Transfer TON/NFTs

## 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
Expand All @@ -27,7 +27,7 @@ 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
3. Install the required dependencies

Run these commands in your terminal:

Expand All @@ -46,7 +46,7 @@ npx ts-node script.ts

## Sending TON

The simplest interaction between two accounts in TON Blockchain is a TON transfer. The process involves preparing and signing a transaction, and then sending it to the blockchain.
The simplest interaction between two accounts in the TON Blockchain is a TON transfer. The process involves preparing and signing a transaction, and then sending it to the blockchain.

A common transfer would look like this:

Expand All @@ -63,7 +63,7 @@ A common transfer would look like this:
<br></br>

:::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
Expand All @@ -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 });

Expand All @@ -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
Expand Down Expand Up @@ -197,12 +197,12 @@ 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
```

#### 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.
31 changes: 16 additions & 15 deletions ...v3/guidelines/quick-start/developing-smart-contracts/blueprint-sdk-overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::

<Tabs groupId="language">
Expand Down Expand Up @@ -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
```

Loading
Loading