feat(nodes): run a validator node guide #1184
Conversation
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
/review |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
I need to wait a few days for the stake value API. Expected ETA next Wednesday. |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore ecosystem/node/run-validator.mdx |
|
/review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Thanks for the detailed validator guide update—I've left several suggestions in ecosystem/node/run-validator.mdx to tighten style, safety callouts, and numeric examples; please apply the inline suggestions. Once updated, the guide should be easier to reuse and safer to follow.
|
|
||
| ## Overview | ||
|
|
||
| This guide explains how to run a validator TON node with MyTonCtrl from scratch. |
There was a problem hiding this comment.
[HIGH] Throat‑clearing introductory sentence
The first sentence in the Overview section describes the document itself (“This guide explains…”) instead of directly stating the action the reader should take. This kind of throat‑clearing delays instructions and adds meta‑noise, which the style guide classifies as a high‑severity issue. A direct, action‑oriented opener improves scannability and makes the page more immediately useful as a procedural reference.
| This guide explains how to run a validator TON node with MyTonCtrl from scratch. | |
| This guide explains how to run a validator TON node with MyTonCtrl from scratch. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```bash | ||
| # Create a non-root validator user | ||
| sudo adduser <USERNAME> | ||
| sudo usermod -aG sudo <USERNAME> | ||
| ``` | ||
|
|
||
| 2. Switch to it by reconnecting to the server via `ssh` | ||
|
|
||
| ```bash reconnect as the new user | ||
| exit | ||
| ssh <USERNAME>@<SERVER_IP> | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Undefined angle‑bracket placeholders in commands
Several command examples introduce placeholders like <USERNAME>, <SERVER_IP>, <pool-name>, <owner-address>, <pool-addr>, and <PORT_NUMBER> without nearby definitions. At L112–L123 the SSH setup commands use <USERNAME> and <SERVER_IP> without explaining what they represent, and similar patterns appear later for pool creation and firewall configuration. The extended style guide requires angle‑bracket placeholders in commands to be explicitly defined on first use to avoid copy/paste errors and misconfiguration. Undefined placeholders are a high‑severity hazard because readers may paste commands verbatim into production systems.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
That Linux part is expected with a limited explanation.
| ```sh | ||
| mytonctrl | ||
| MyTonCtrl> status | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Non‑copy‑pasteable examples due to interactive prompts
Multiple fenced command blocks include the interactive prompt string MyTonCtrl> as part of the command itself, for example at L169–L172 and in later snippets like L240–L241, L262–L263, L307–L308, L337, L351, L361, L383, and L397. The style guide requires examples to be directly copy‑pasteable, which excludes prompts like $ or > from within code fences. Including prompts inside fences forces readers to manually strip them out and increases the chance of errors when copying commands into terminals or scripts.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
In this context, commands are short and easy to type on one side, and it's helpful to distinguish between internal MyTonCtrl commands and server commands.
| <Aside | ||
| type="danger" | ||
| title="Funds at risk" | ||
| > | ||
| Ensure precise handling of operations, carefully verifying the addresses for `single_nominator_pool`, `owner_address`, and `validator_wallet`. Any incorrect deposit processing may result in the permanent and unrecoverable loss of funds. | ||
| </Aside> |
There was a problem hiding this comment.
[HIGH] Safety callouts for funds at risk lack required structure
The “Funds at risk” Aside here warns about irreversible loss but only mentions careful address handling in general terms. It does not clearly separate risk, scope, mitigation steps, and environment (testnet vs mainnet), which the safety callout rules require for any operation that can lock or burn funds. Similar “Funds at risk” Asides later in the document (for test deposits and effective stake deposits) reuse the same pattern without the required structure. This makes it harder for validators to understand exactly when funds are at risk and how to practice safer workflows.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| Insert your address to `SINGLE_NOMINATOR_ADDRESS` and send this message from the owner's wallet. | ||
|
|
||
| ```js | ||
| import { | ||
| Address, | ||
| beginCell, | ||
| internal, | ||
| storeMessageRelaxed, | ||
| toNano, | ||
| } from "@ton/core"; | ||
|
|
||
| async function main() { | ||
| const single_nominator_address = Address.parse("SINGLE_NOMINATOR_ADDRESS"); | ||
| const WITHDRAW_OP = 0x1000; | ||
| const amount = 50000; | ||
|
|
||
| const messageBody = beginCell() | ||
| .storeUint(WITHDRAW_OP, 32) | ||
| .storeUint(0, 64) | ||
| .storeCoins(amount) | ||
| .endCell(); | ||
|
|
||
| const internalMessage = internal({ | ||
| to: single_nominator_address, | ||
| value: toNano("1"), | ||
| bounce: true, | ||
| body: messageBody, | ||
| }); | ||
| } | ||
|
|
||
| ``` |
There was a problem hiding this comment.
[HIGH] Partial JavaScript withdrawal snippet not labeled as not runnable
The JavaScript example for withdrawing via script defines a main function that constructs an internal message but does not call main() or show how to send the message. As written, this block is not runnable as a standalone script, yet it appears without any label indicating that it is partial. The style guide requires clearly labeling partial snippets as “Not runnable” so validators are not misled into expecting fully working code. This is especially important for scripts involved in moving funds from a stake pool.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```json | ||
| "cycle_id" : 1764052744, | ||
| "min_stake": 701812111528562, // ~ 701 812 TON | ||
| "max_stake": 2008570202020000, // ~ 2 008 570 TON | ||
| ``` | ||
|
|
||
| ```json | ||
| "cycle_id" : 1764052744, | ||
| "min_stake": 674810775114391, // ~ 674 811 TON | ||
| "max_stake": 2024432325343173, // ~ 2 024 432 TON | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Trailing inline comments in numeric JSON example
The JSON examples for min_stake and max_stake here include trailing inline comments (for example, // ~ 701 812 TON) on the same lines as the fields. This makes the JSON invalid if readers copy and paste it directly into tools or scripts. The style guide forbids trailing end‑of‑line comments in runnable examples for exactly this reason. The numeric values are correct, but commentary about approximate TON amounts must be moved outside the JSON blocks.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
These are JSON fragments for explanation (not a copy-paste example), and comments help deliver information more easily.
ecosystem/node/run-validator.mdx
Outdated
| ```bash | ||
| // largest within 701 812 TON and 674 811 TON | ||
| av_min_stake = 701812 | ||
| ``` | ||
|
|
||
| ```bash | ||
| // largest within 2 008 570 TON and 2 024 432 TON | ||
| av_max_stake = 2008570 | ||
| ``` | ||
|
|
||
| ### 4.3 Calculate effective stakes | ||
|
|
||
| <Aside type="tip"> | ||
| _Effective_ stands for winning elections for both odd and even cycles. | ||
| </Aside> | ||
|
|
||
| Effective stake for two cycles is a value between doubled maximum and minimum average stakes: | ||
|
|
||
| $$ | ||
| av\_min\_stake * 2 <= effective\_stake <= av\_max\_stake * 2 | ||
| $$ | ||
|
|
||
| For example: | ||
|
|
||
| ```bash | ||
| max_expected_effective_stake = max_cycle_stake * 2 = 2008570 * 2 = 4017140 | ||
| min_expected_effective_stake = min_cycle_stake * 2 = 701812 * 2 = 1403624 | ||
| ``` | ||
|
|
||
| Then, the effective stake is approximately: | ||
|
|
||
| $$ | ||
| 1403624\ TON <= effective\_stake <= 4017140\ TON |
There was a problem hiding this comment.
[HIGH] Incorrect effective stake bounds calculation
The text explains that you should choose the maximum max_stake from two cycles, but the example then sets av_max_stake = 2008570 even though the second cycle’s max_stake (2 024 432 TON) is larger. The subsequent example uses an undefined max_cycle_stake variable and calculates bounds based on the smaller value, producing max_expected_effective_stake = 4 017 140 TON and an upper bound of 4 017 140 TON. This is a correctness bug: it understates the effective stake range and could cause operators to provision too little stake for expected cycles.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
|
/review |
|
|
||
| ## Overview | ||
|
|
||
| This guide explains how to run a validator TON node with MyTonCtrl from scratch. |
There was a problem hiding this comment.
[HIGH] Throat-clearing introduction sentence
Line 11 opens the page with “This guide explains how to run a validator TON node with MyTonCtrl from scratch.” which describes the document instead of starting with the action. The style guide explicitly bans throat‑clearing introductions and requires leading with the task or outcome. This delays the reader from seeing the core operation and conflicts with the action‑first pattern described in §5.9. The rest of the page already assumes a procedural how‑to, so this meta‑introduction is unnecessary.
| This guide explains how to run a validator TON node with MyTonCtrl from scratch. | |
| Run a validator TON node with MyTonCtrl from scratch. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| # Please check your clang version first | ||
| clang --version | ||
| # If it is version 16, you don't need to do the steps below. |
There was a problem hiding this comment.
[HIGH] Use of reader‑addressing pronouns
Lines 56–58 contain “Please check your clang version first” and “you don't need to do the steps below,” directly addressing the reader. Similar second‑person phrasing appears in multiple locations, including lines 295 (“Ensure you have at least 200 TON/month in your validator wallet”), 486, 496, 616, 622, and 651–653. The style guide (§5.8) forbids using “you/your” for readers and “we/I/our” for authors, requiring neutral, impersonal instructions instead. As written, the page repeatedly violates this global tone requirement.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| <Aside | ||
| type="danger" | ||
| title="Funds at risk" | ||
| > | ||
| Ensure precise handling of operations, carefully verifying the addresses for `single_nominator_pool`, `owner_address`, and `validator_wallet`. Any incorrect deposit processing may result in the permanent and unrecoverable loss of funds. | ||
| </Aside> | ||
|
|
||
| Credit validator wallet. Ensure you have at least 200 TON/month in your validator wallet to cover operational fees. |
There was a problem hiding this comment.
[HIGH] Safety callouts for funds and keys omit required elements
The “Funds at risk” callout at lines 288–293 correctly highlights that incorrect handling of single_nominator_pool, owner_address, and validator_wallet can cause permanent loss of funds, but it only states the risk. It omits the required scope, rollback/mitigation guidance, and explicit environment label (testnet vs mainnet). The same issue appears in the private-key caution at lines 254–258, the “Funds at risk” warnings at 329–334 and 416–421, and the deposit‑related danger block at 580–585. The style guide §11.2 mandates that each safety callout include all four elements (risk, scope, mitigation, environment) for operations involving funds, keys, or validator configuration.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| title="Withdraw with script..." | ||
| > | ||
| Insert your address to `SINGLE_NOMINATOR_ADDRESS` and send this message from the owner's wallet. | ||
|
|
||
| ```js | ||
| import { | ||
| Address, |
There was a problem hiding this comment.
[HIGH] Placeholder in withdraw instructions does not use <ANGLE_CASE> format
The withdraw instructions in the accordion on lines 451–457 use the string SINGLE_NOMINATOR_ADDRESS as an inline code placeholder and refer to it with “your address”, which does not follow the <ANGLE_CASE> placeholder convention and also adds an unnecessary second-person pronoun. According to the style guide, placeholders in prose and commands must be clearly marked as values to be replaced using angle-bracket notation such as <SINGLE_NOMINATOR_ADDRESS>. Clarifying this placeholder makes it obvious that the value is user-supplied and keeps the instructions consistent with the global placeholder style.
| title="Withdraw with script..." | |
| > | |
| Insert your address to `SINGLE_NOMINATOR_ADDRESS` and send this message from the owner's wallet. | |
| ```js | |
| import { | |
| Address, | |
| title="Withdraw with script..." | |
| > | |
| Insert the address into `<SINGLE_NOMINATOR_ADDRESS>` and send this message from the owner wallet. | |
| ```js | |
| import { | |
| Address, |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```js | ||
| import { | ||
| Address, | ||
| beginCell, | ||
| internal, | ||
| storeMessageRelaxed, | ||
| toNano, | ||
| } from "@ton/core"; | ||
|
|
||
| async function main() { | ||
| const single_nominator_address = Address.parse("SINGLE_NOMINATOR_ADDRESS"); | ||
| const WITHDRAW_OP = 0x1000; | ||
| const amount = 50000; | ||
|
|
||
| const messageBody = beginCell() | ||
| .storeUint(WITHDRAW_OP, 32) | ||
| .storeUint(0, 64) | ||
| .storeCoins(amount) | ||
| .endCell(); | ||
|
|
||
| const internalMessage = internal({ | ||
| to: single_nominator_address, | ||
| value: toNano("1"), | ||
| bounce: true, | ||
| body: messageBody, | ||
| }); | ||
| } | ||
|
|
||
| ``` |
There was a problem hiding this comment.
[HIGH] Partial JavaScript snippet is not labeled “Not runnable”
The JavaScript example starting at line 455 constructs a message but does not include the code that sends the message or invokes main(), so the snippet is not runnable as shown. The documentation style guide requires that partial, non-runnable snippets be labeled clearly as “Not runnable” above the block. Without that label, readers may attempt to execute the snippet as-is and be confused when it does not work, which reduces the practical usefulness of the example.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```json | ||
| "cycle_id" : 1764052744, | ||
| "min_stake": 701812111528562, // ~ 701 812 TON | ||
| "max_stake": 2008570202020000, // ~ 2 008 570 TON | ||
| ``` | ||
|
|
||
| ```json | ||
| "cycle_id" : 1764052744, | ||
| "min_stake": 674810775114391, // ~ 674 811 TON | ||
| "max_stake": 2024432325343173, // ~ 2 024 432 TON | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Trailing inline comments in JSON examples (invalid JSON)
The json‑labeled examples in lines 518–522 and 524–528 include trailing inline comments on the same lines as fields, such as // ~ 701 812 TON and // ~ 2 024 432 TON. Because these blocks are fenced as JSON, the inline comments make the examples invalid and non‑copy‑pasteable for tools that expect real JSON. The style guide’s comments section (§10.5) forbids trailing end‑of‑line comments in documentation snippets and requires that examples be syntactically valid for their declared language. As written, readers copying these blocks will encounter parse errors.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| **Legend** | ||
|
|
||
| 1. Stake for odd cycle. | ||
| 1. Reward for odd cycle. | ||
| 1. Reinvestment of the odd cycle stake, including the reward in the next odd cycle. |
There was a problem hiding this comment.
[HIGH] Bold‑only labels used as pseudo‑headings
Lines 608–612 use **Legend** as a standalone bold label above a numbered list, effectively acting as a pseudo‑heading. A similar pattern appears later with **Workflow** at line 649. The style guide’s emphasis rules (§6.2) explicitly forbid fully bold sentences, paragraphs, or list items and recommend using proper headings or structural elements instead. These bold‑only labels create redundant heading semantics and reduce structural clarity for readers and tooling.
| **Legend** | |
| 1. Stake for odd cycle. | |
| 1. Reward for odd cycle. | |
| 1. Reinvestment of the odd cycle stake, including the reward in the next odd cycle. | |
| ### Legend | |
| 1. Stake for odd cycle. | |
| 1. Reward for odd cycle. | |
| 1. Reinvestment of the odd cycle stake, including the reward in the next odd cycle. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
I exclude this from headers for a reason: the table of contents looks better in this version.
| ### 5.2 Organize validator backup | ||
|
|
||
| Create a validator backup. Learn about [backups](https://old-docs.ton.org/v3/guidelines/nodes/maintenance-guidelines/mytonctrl-backup-restore). | ||
|
|
There was a problem hiding this comment.
[HIGH] Stub “Learn about / Learn more about” sentences
The backup instruction at line 626 says “Create a validator backup. Learn about backups” and the slashing section at lines 657–659 ends with “Learn more about the slashing policy.” These are classic stub sentences whose only job is to point to a link, which the style guide (§12.1) forbids (“See/Read/Learn more here” stubs). Instead, links must be integrated into substantive sentences that carry information, so the reader gains value even before clicking.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
Closes: #996