Skip to content
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

Blockchain nodes #566

Closed
wants to merge 12 commits into from
Closed

Blockchain nodes #566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
7b99ef8
start to rewrite docs
Full-Hat May 3, 2024
704d459
Rebase updates from origin
Full-Hat May 6, 2024
4891edd
rewrite node docs
Full-Hat May 6, 2024
845f598
fix errors
Full-Hat May 6, 2024
dddb3be
fix links
Full-Hat May 6, 2024
a00e20e
fix linter errors: add spaces
Full-Hat May 6, 2024
7f854c1
add some tips after node testing
Full-Hat May 20, 2024
b057a3e
add comment about mytonctrl2
Full-Hat May 21, 2024
3b7697d
add FAQ from mytonctrl rep
gkaravatski May 31, 2024
9783e34
add mytonctrl init paragraph
gkaravatski May 31, 2024
1743ac0
added mytonctrl articles from appropriate rep
gkaravatski May 31, 2024
51c5055
refactor mytonctrl help menu
Full-Hat Jun 5, 2024
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
118 changes: 118 additions & 0 deletions docs/participate/network-maintenance/nominator-pool.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Nominator Pool

## Running the Validator in Nominator Pool Mode

1. Set up the hardware for the validator - you will need 8 vCPUs, 64GB memory, 1TB SSD, a fixed IP address, and 1Gb/s internet speed.

For maintaining network stability, it's recommended to distribute validator nodes in different geographical locations worldwide rather than concentrating them in a single data center. You can use [this site](https://status.toncenter.com/) to assess the load of various locations. The map indicates high data center utilization in Europe, especially in Finland, Germany, and Paris. Therefore, using providers such as Hetzner and OVH is not recommended.

> Ensure your hardware matches or exceeds the specifications above. Running the validator on insufficient hardware negatively impacts the network and could result in penalties.

> Note that as of May 2021, Hetzner has prohibited mining on its servers, and this ban includes both PoW and PoS algorithms. Even installing a regular node may be considered a violation of their terms of service.

> **Recommended providers include:** [Amazon](https://aws.amazon.com/), [DigitalOcean](https://www.digitalocean.com/), [Linode](https://www.linode.com/), [Alibaba Cloud](https://alibabacloud.com/), [Latitude](https://www.latitude.sh/).

2. Install and synchronize **mytonctrl** as described in the guide [here](/participate/run-nodes/full-node).

You can also refer to this [Video Instruction](https://ton.org/docs/#/nodes/run-node) for additional help.

3. Transfer 1 TON to the validator wallet address shown in the `wl` list.

4. Use the `aw` command to activate your validator wallet.

5. Activate pool mode:

```bash
enable_mode nominator-pool
set stake null
```

6. Create two pools (for even and odd validation rounds):

```bash
new_pool p1 0 1 1000 300000
new_pool p2 0 1 1001 300000
```

where:
* `p1` is the pool name;
* `0` % is the validator's reward share (e.g., use 40 for 40%);
* `1` is the maximum number of nominators in the pool (should be <= 40);
* `1000` TON is the minimum validator stake (should be >= 1K TON);
* `300000` TON is the minimum nominator stake (should be >= 10K TON);

> (!) Pool configurations do not have to be identical, you can add 1 to the minimum stake of one pool to make them different.

> (!) Use https://tonmon.xyz/ to determine the current minimum validator stake.

7. Type `pools_list` to display pool addresses:

```bash
pools_list
Name Status Balance Address
p1 empty 0 0f98YhXA9wnr0d5XRXT-I2yH54nyQzn0tuAYC4FunT780qIT
p2 empty 0 0f9qtmnzs2-PumMisKDmv6KNjNfOMDQG70mQdp-BcAhnV5jL
```

8. Send 1 TON to each pool and activate the pools:

```bash
mg validator_wallet_001 0f98YhXA9wnr0d5XRXT-I2yH54nyQzn0tuAYC4FunT780qIT 1
mg validator_wallet_001 0f9qtmnzs2-PumMisKDmv6KNjNfOMDQG70mQdp-BcAhnV5jL 1
activate_pool p1
activate_pool p2
```

9. Type `pools_list` to display pools:

```bash
pools_list
Name Status Balance Address
p1 active 0.731199733 kf98YhXA9wnr0d5XRXT-I2yH54nyQzn0tuAYC4FunT780v_W
p2 active 0.731199806 kf9qtmnzs2-PumMisKDmv6KNjNfOMDQG70mQdp-BcAhnV8UO
```

10. Open each pool via the link "https://tonscan.org/nominator/<address_of_pool>" and verify pool configurations.

11. Proceed with the validator deposit to each pool:

```bash
deposit_to_pool validator_wallet_001 <address_of_pool_1> 1005
deposit_to_pool validator_wallet_001 <address_of_pool_2> 1005
```

In these commands, `1005` TON is the deposit amount. Be aware that 1 TON will be deducted by the pool for processing the deposit.

12. Proceed with the nominator deposit to each pool:

Visit the pool link (from **Step 9**) and click **ADD STAKE**.
You can also make a deposit using **mytonctrl**, using the following commands:

```bash
mg nominator_wallet_001 <address_of_pool_1> 300001 -C d
mg nominator_wallet_001 <address_of_pool_2> 300001 -C d
```

> (!) The nominator wallet must be initialized in basechain (workchain 0).

> (!) Keep in mind that the validator wallet and nominator wallet must be stored separately! The validator wallet should be stored on the server with the validator node to ensure processing of all system transactions. Meanwhile, the nominator wallet should be stored in your cold cryptocurrency wallet.

> To withdraw a nominator deposit, send a transaction with the comment `w` to the pool address (attach 1 TON to process the transaction). You can also perform this action using **mytonctrl**.

13. Invite nominators to deposit into your pools. The participation in validation will commence automatically.

> (!) Ensure that you have at least 200 TON/month in your validator wallet for operation fees.

## Pool Configuration

If you're intending to lend to yourself, use `new_pool p1 0 1 1000 300000` (maximum of 1 nominator, 0% validator share).

If you're creating a pool for numerous nominators, you might use something like this: `new_pool p1 40 40 10000 10000` (maximum of 40 nominators, 40% validator share, minimum participant stakes of 10K TON).

## Transitioning a Regular Validator to Nominator Pool Mode

1. Input `set stake 0` to discontinue election participation.

2. Await the return of both your stakes from the elector.

3. Proceed with the steps under "Running the Validator in Nominator Pool Mode" from the **4th step** onwards.
4 changes: 3 additions & 1 deletion docs/participate/nodes/node-maintenance-and-security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ This document assumes that a validator is installed using the configuration and
### <a id="database-grooming"></a>Database grooming
TON Node/Validator keeps it's database within the path specified by `--db` flag of `validator-engine`, usually `/var/ton-work/db`, this directory is created and managed by the node but it is recommended to perform a database grooming/cleanup task once a month to remove some artefacts.

**Important**: You **must** stop the validator process before performing the steps outlined below, failure to do that will likely cause database corruption.
:::caution Do not forget to stop validator process
You **must** stop the validator process before performing the steps outlined below, failure to do that will likely cause database corruption.
:::

The procedure takes ~5 minutes to complete and will not cause major service disruption.

Expand Down
80 changes: 44 additions & 36 deletions docs/participate/nodes/node-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@ import Button from '@site/src/components/button'

# TON Node Types

In *simplified terms*, a blockchain `node` is **one of the computers** that **collectively run the blockchain's software**. It enables the blockchain to search and optionally validate transactions and keep the network secure ensuring that the network remains **decentralized**.

When diving into the world of The Open Network (TON), understanding the distinct node types and their functionalities is crucial. This article breaks down each node type to provide clarity for developers wishing to engage with the TON blockchain.

## Full Node

A **Full Node** in TON is a node that maintains synchronization with the blockchain.
A `Full Node` in TON is a node that **maintains synchronization** with the blockchain.

It retains the _current state_ of the blockchain and can house either the entire block history or parts of it. This makes it the backbone of the TON blockchain, facilitating the network's decentralization and security.

Expand All @@ -15,67 +17,73 @@ colorType="primary" sizeType={'sm'}>
Running a Full Node
</Button>

## Validator Node

A **Validator Node** is activated when it holds a necessary amount of Toncoin as a stake. Validator nodes are vital for the network's operability, participating in the validation of new network blocks.

TON operates on a Proof-of-Stake mechanism, where validators are pivotal in maintaining network functionality. Validators are [rewarded in Toncoin](/participate/network-maintenance/staking-incentives) for their contributions, incentivizing network participation and ensuring network security.
## Archive Node

[Running a Full Node as a Validator](/participate/run-nodes/full-node#become-a-validator)
If `Full node` archives the **entire block history** it's called `Archive Node`.

Such nodes are indispensable for creating blockchain explorers or other tools that necessitate a full blockchain history.

## Full Node + Liteserver
<Button href="/participate/run-nodes/archive-node"
colorType="primary" sizeType={'sm'}>
Running an Archive Node
</Button>

When an endpoint is activated on a full node, the node assumes the role of a **Liteserver**. This node type can field and respond to requests from Lite Clients, allowing to seamlessly interract with the TON Blockchain.
## Validator Node

### Lite Clients: the SDKs to interact with TON
TON operates on a **Proof-of-Stake** mechanism, where `validators` are pivotal in maintaining network functionality. `Validators` are [rewarded in Toncoin](/participate/network-maintenance/staking-incentives) for their contributions, incentivizing network participation and ensuring network security.

Liteservers enable swift communication with Lite Clients, facilitating tasks like retrieving balance or submitting transactions without necessitating the full block history.
If `full node` holds a **necessary amount of Toncoin** as a **stake**, it can be used as `Validator Node`.

Each SDK which supports ADNL protocol can be used as a Lite Client with `config.json` file. The `config.json` file contains a list of endpoints that can be used to connect to the TON Blockchain.
<Button href="/participate/run-nodes/enable-liteserver-node"
colorType="primary" sizeType={'sm'}>
Running a Validator Node
</Button>

[Choose a TON SDK](/develop/dapps/apis/sdk)
## Liteserver

Each SDK without ADNL support usually uses HTTP middleware to connect to the TON Blockchain. It's less secure and slower than ADNL, but it's easier to use.
`Full Node` can be used as `Liteserver`. This node type can field and respond to requests from `Lite Clients`, allowing to seamlessly interact with the TON Blockchain.

### Interaction with TON: Public Liteservers (endpoints)
`Liteservers` enable swift communication with Lite Clients, facilitating tasks like retrieving balance or submitting transactions without necessitating the full block history.

The TON Foundation provides several public Liteservers, integrated into the global config, which are accessible for universal use. These endpoints, such as those used by standard wallets, ensure that even without setting up a personal liteserver, interaction with the TON Blockchain remains possible.
Actually, there are two public `Liteservers`, that already have been provided by the TON Foundation. They are accessible for universal use.

- [Public Liteserver Configurations - mainnet](https://ton.org/global-config.json)
- [Public Liteserver Configurations - testnet](https://ton.org/testnet-global.config.json)

Use the downloaded `config.json` file in your application with [TON SDK](/participate/nodes/node-types#lite-clients-the-sdks-to-interact-with-ton).

#### Troubleshooting
These endpoints, such as those used by standard wallets, ensure that even without setting up a personal liteserver, interaction with the TON Blockchain remains possible.

##### Timed out after 3 seconds

If you see this error this means that the liteserver you are trying to connect to is not available. The correct way to solve this issue for public liteservers is as follows:

1. Download the config.json file from the tontech link:
If your project requires a high level of _security_, you can run your own `Liteserver`. To run a `full node` as a `Liteserver`, simply enable the `Liteserver` mode in your node's configuration file.

```bash
wget https://api.tontech.io/ton/wallet-mainnet.autoconf.json -O /usr/bin/ton/global.config.json
```
<Button href="/participate/run-nodes/full-node#enable-liteserver-mode"
colorType="primary" sizeType={'sm'}>
Enable Liteserver in your Node
</Button>

It removes slow liteservers from the configuration file.
## Lite Clients: the SDKs to interact with TON

2. Use the downloaded config.json file in your application with [TON SDK](/participate/nodes/node-types#lite-clients-the-sdks-to-interact-with-ton).
Each SDK which supports ADNL protocol can be used as a `Lite Client` with `config.json` file (find how to download it [here](/participate/nodes/node-types#troubleshooting)). The `config.json` file contains a list of endpoints that can be used to connect to the TON Blockchain.

Each SDK without ADNL support usually uses HTTP middleware to connect to the TON Blockchain. It's less secure and slower than ADNL, but it's easier to use.

### Running a Full Node as a Liteserver
<Button href="/develop/dapps/apis/sdk"
colorType="primary" sizeType={'sm'}>
Choose a TON SDK
</Button>

If your project requires a high level of _security_, you can run your own Liteserver. To run a full node as a Liteserver, simply enable the Liteserver mode in your node's configuration file:
### Troubleshooting

[Enable Liteserver in your Node](/participate/run-nodes/full-node#enable-liteserver-mode)
Below you can find approaches how to fix common nowed issues with `light clients`

### Timed out after 3 seconds

## Archive Node
If you see this error this means that the liteserver you are trying to connect to is not available. The correct way to solve this issue for public liteservers is as follows:

An **Archive Node** is essentially a full node that archives the entire block history.
1. Download the config.json file from the tontech link:

Such nodes are indispensable for creating blockchain explorers or other tools that necessitate a full blockchain history.
```bash
wget https://api.tontech.io/ton/wallet-mainnet.autoconf.json -O /usr/bin/ton/global.config.json
```

[Running an Archive Node](/participate/run-nodes/archive-node)
It removes slow liteservers from the configuration file.

2. Use the downloaded config.json file in your application with [TON SDK](/develop/dapps/apis/sdk).
29 changes: 9 additions & 20 deletions docs/participate/run-nodes/archive-node.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,20 @@
# Running an Archive Node
# Archive Node

## Overview

:::caution System Administrator Required
For running nodes basic knowledge of Linux/Ubuntu system administration is required.
:::info
Read about [Full Node](/participate/run-nodes/full-node) before this article
:::

An Archive Node is a type of [Full Node](/participate/run-nodes/full-node) that stores extended historical data of a blockchain. If you are creating a blockchain explorer or a similar application that requires access to historical data, using an Archive Node as an indexer is recommended.
## Overview

An Archive Node is a type of Full Node that stores extended historical data of a blockchain. If you are creating a blockchain explorer or a similar application that requires access to historical data, using an Archive Node as an indexer is recommended.

## Prerequisites
## OS requirements

We highly recommend install mytonctrl using the supported operating systems:
* Ubuntu 20.04
* Ubuntu 22.04
* Debian 11

Please, use a [non-root user with sudo privileges](/participate/run-nodes/full-node#prerequisites-1) to install and run mytonctrl.

## Hardware requirements

* 16 x Cores CPU
Expand All @@ -31,15 +29,6 @@ __Note__: 4TB assumes usage of zfs volume with compression enabled

## Installation

In general, you need the following steps to run an Archive Node:

1. Install ZFS and Prepare Volume
2. Install MyTonCtrl
3. Run a Full Node on your server and stop validator process
4. Download and restore dump data from https://archival-dump.ton.org
5. Run Full Node with Configuring DB specs for Archive Node


### Install ZFS and Prepare Volume

Dumps come in form of ZFS Snapshots compressed using plzip, you need to install zfs on your host and restore the dump, see [Oracle Documentation](https://docs.oracle.com/cd/E23824_01/html/821-1448/gavvx.html#scrolltoc) for more details.
Expand All @@ -63,7 +52,7 @@ sudo zfs set compression=lz4 data

### Install MyTonCtrl

Please, use a [Running Full Node](/participate/run-nodes/full-node) to install mytonctrl.
Please, use a [Running Full Node](/participate/run-nodes/full-node) to **install** and **run** mytonctrl.

### Run an Archive Node

Expand Down Expand Up @@ -176,7 +165,7 @@ systemctl start validator.service
## Troubleshooting and backups
If for some reason something does not work / breaks you can always [roll back](https://docs.oracle.com/cd/E23824_01/html/821-1448/gbciq.html#gbcxk) to @archstate snapshot on your ZFS filesystem, this is the original state from dump.

1. Stop validator process (Never skip this!)
1. Stop validator process (**Never skip this!**)
```shell
sudo -s
systemctl stop validator.service
Expand Down
54 changes: 54 additions & 0 deletions docs/participate/run-nodes/become-validator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Validator Node

:::info
Read about [Full Node](/participate/run-nodes/full-node) before this article
:::

## View the List of Wallets

Check out the list of available wallets in the **MyTonCtrl** console using the `wl` command:

```sh
wl
```

During the installation of **mytonctrl**, the **validator_wallet_001** wallet is created:

![wallet list](https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/screens/manual-ubuntu_mytonctrl-wl_ru.png)


## Activate the Wallets

1. Send the necessary number of coins to the wallet and activate it.

Recently (_at the end of 2023_), the approximate figures have been a minimum stake of around __340K TON__ and a maximum of about __1M TON__.

Check current stakes with [tonscan.com](https://tonscan.com/validation) to understand necessary amount of coins.

Read more [how maximum and minimum stakes calculated](/participate/network-maintenance/staking-incentives#values-of-stakes-max-effective-stake).

2. Use the `vas` command to display the history of transfers:

```sh
vas [wallet name]
```

3. Activate the wallet using the `aw` command (`wallet name` is optional, if no arguments provided it will activate all available)

```sh
aw [wallet name]
```

![account history](https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/screens/manual-ubuntu_mytonctrl-vas-aw_ru.png)

## Your Validator is Now Ready

**mytoncore** will automatically join the elections. It divides the wallet balance into two parts and uses them as a stake to participate in the elections. You can also manually set the stake size:

```sh
set stake 50000
```

`set stake 50000` — this sets the stake size to 50k coins. If the bet is accepted and our node becomes a validator, the bet can only be withdrawn in the second election (according to the rules of the electorate).

![setting stake](https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/screens/manual-ubuntu_mytonctrl-set_ru.png)
Loading