Skip to content

Conversation

Kaladin13
Copy link
Collaborator

Closes #478

@Kaladin13 Kaladin13 requested a review from a team as a code owner October 6, 2025 13:37
Copy link

github-actions bot commented Oct 6, 2025

To fix the formatting issues:

  1. Install necessary dependencies: npm ci
  2. Then, run this command:
npx remark -o --quiet --silently-ignore ton/changing-params.mdx 

Copy link

github-actions bot commented Oct 6, 2025

Thanks for the updates to ton/changing-params.mdx. I did find several high‑severity doc issues that need addressing before merge.

Findings (3)

High (3)

[HIGH] Missing safety callouts for funds and consensus-affecting changes

Location:

To create this proposal, we need to pay 2.3408 Toncoins. It's advisable to add at least 1.5 Toncoins to cover the processing fees. Therefore, we will send a total of 4 Toncoins with the request (any excess Toncoins will be returned). We will then use [`wallet.fif`](https://github.com/ton-blockchain/ton/blob/05bea13375448a401d8e07c6132b7f709f5e3a32/crypto/smartcont/wallet.fif) (or the appropriate Fift script for our wallet) to execute a transfer from our wallet to the configuration smart contract, including the 4 Toncoins and the body from `config-msg-body.boc`. This process typically looks like:
```bash
fift -s wallet.fif my-wallet -1:5555555555555555555555555555555555555555555555555555555555555555 31 4. -B config-msg-body.boc
Transferring GR$4. to account kf9VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVQft = -1:5555555555555555555555555555555555555555555555555555555555555555 seqno=0x1c bounce=-1
Body of transfer message is x{6E5650525E835154000000085E9293944_}

Description:
The doc instructs transferring Toncoin and initiating validator/network/consensus‑affecting operations without required safety callouts. Per the style guide, steps that move funds or change validator/network parameters must include a clearly labeled Warning/Caution covering risk, scope, rollback, and testnet‑first guidance.

Suggestion:
Insert a warning callout immediately before the first funds‑moving/consensus‑affecting step; reuse or tailor it before similar steps.

@@
+ Warning — funds at risk
+ Running the following commands can transfer funds on mainnet and alter validator/network behavior.
+ Scope: configuration smart contract and validator consensus parameters.
+ Rollback: on-chain transfers are final; reversing configuration changes requires a new, accepted proposal.
+ Do first (testnet): verify addresses and amounts on TON Testnet.
+
 To create this proposal, we need to pay 2.3408 Toncoins. It's advisable to add at least 1.5 Toncoins to cover the processing fees. Therefore, we will send a total of 4 Toncoins with the request (any excess Toncoins will be returned). We will then use [`wallet.fif`](https://github.com/ton-blockchain/ton/blob/05bea13375448a401d8e07c6132b7f709f5e3a32/crypto/smartcont/wallet.fif) (or the appropriate Fift script for our wallet) to execute a transfer from our wallet to the configuration smart contract, including the 4 Toncoins and the body from `config-msg-body.boc`. This process typically looks like:

Also add a network/consensus callout at the start of the procedure that proposes/votes on configuration parameters.

 We have acquired the content of an internal message intended for the configuration smart contract, and we will send it from a MasterChain wallet smart contract with an appropriate amount of Toncoin. To find the address of the configuration smart contract, enter the `getconfig 0` command in the Lite Client:
+> Caution — network/consensus changes  
+> These steps propose or vote on configuration parameters that affect validators and consensus.  
+> Scope: validator/elector configuration and related smart contracts.  
+> Rollback: not trivial; reversing requires a new proposal and validator votes.  
+> Do first (testnet): validate procedures on TON Testnet before mainnet.

[HIGH] Commands include prompts and mix command and output in one block

Location:

```bash
crypto/create-state -s create-config-proposal.fif 8 config-param8.boc -x 1100000
Loading new value of configuration parameter 8 from file config-param8.boc
x{C400000001000000000000000E}
Non-critical configuration proposal will expire at 1586779536 (in 1100000 seconds)
Query id is 6810441749056454664
resulting internal message body: x{6E5650525E838CB0000000085E9455904_}
x{F300000008A_}
x{C400000001000000000000000E}
B5EE9C7241010301002C0001216E5650525E838CB0000000085E9455904001010BF300000008A002001AC400000001000000000000000ECD441C3C
(a total of 104 data bits, 0 cell references -> 59 BoC data bytes)
(Saved to file config-msg-body.boc)

Description:
Examples mix commands and output in the same fenced block and include REPL‑style prompts, and some fences lack language tags. This is a copy/paste hazard per the style guide. Similar issues appear at L196–L200, L204–L210, L216–L236, and the indented example at L240–L243.

Suggestion:
Split commands and outputs into separate fenced blocks with language tags and remove prompts. Apply the same pattern to the other cited occurrences.

@@
-```bash
-crypto/create-state -s create-config-proposal.fif 8 config-param8.boc -x 1100000
-
-
-Loading new value of configuration parameter 8 from file config-param8.boc
-x{C400000001000000000000000E}
-
-Non-critical configuration proposal will expire at 1586779536 (in 1100000 seconds)
-Query id is 6810441749056454664
-resulting internal message body: x{6E5650525E838CB0000000085E9455904_}
- x{F300000008A_}
-  x{C400000001000000000000000E}
-
-B5EE9C7241010301002C0001216E5650525E838CB0000000085E9455904001010BF300000008A002001AC400000001000000000000000ECD441C3C
-(a total of 104 data bits, 0 cell references -> 59 BoC data bytes)
-(Saved to file config-msg-body.boc)
-```
+```bash
+crypto/create-state -s create-config-proposal.fif 8 config-param8.boc -x 1100000
+```
+
+Expected output
+
+```text
+Loading new value of configuration parameter 8 from file config-param8.boc
+x{C400000001000000000000000E}
+Non-critical configuration proposal will expire at 1586779536 (in 1100000 seconds)
+Query id is 6810441749056454664
+resulting internal message body: x{6E5650525E838CB0000000085E9455904_}
+ x{F300000008A_}
+  x{C400000001000000000000000E}
+B5EE9C7241010301002C0001216E5650525E838CB0000000085E9455904001010BF300000008A002001AC400000001000000000000000ECD441C3C
+(a total of 104 data bits, 0 cell references -> 59 BoC data bytes)
+(Saved to file config-msg-body.boc)
+```
@@
-```
-> getconfig 0
+```bash
+getconfig 0
+```
+
+Expected output
+
+```text
 ConfigParam(0) = ( config_addr:x5555555555555555555555555555555555555555555555555555555555555555)
 x{5555555555555555555555555555555555555555555555555555555555555555}

Convert the indented snippet to fenced blocks without prompts:

```diff
-    > sendfile wallet-query.boc
-    ....
-    external message status is 1
+```bash
+sendfile wallet-query.boc
+```
+
+```text
+...
+external message status is 1
+```

[HIGH] Silent truncation of addresses and hashes

Location:

We have the address of the configuration smart contract as `-1:5555...5555`. By using appropriate getter methods of this smart contract, we can determine the required payment for creating this configuration proposal:

Description:
Identifiers are truncated (e.g., “-1:5555...5555”, “6465...6321”) without indicating truncation or using a consistent policy. The style guide forbids silent truncation; if truncation is used, it must be explicit and consistent, or full values should be shown.

Suggestion:
Show full values or explicitly label truncation with a consistent pattern.

@@
-We have the address of the configuration smart contract as `-1:5555...5555`. By using appropriate getter methods of this smart contract, we can determine the required payment for creating this configuration proposal:
+We have the address of the configuration smart contract as `-1:5555…5555` (truncated; first 4 / last 4 shown). By using appropriate getter methods of this smart contract, we can determine the required payment for creating this configuration proposal:
@@
-[6465...6321 [1586779536 0 [8 C{FDCD...} -1] 1124...2998 () 8646...209 3 0 0]]
+[6465…6321 (truncated; first 4 / last 4) [1586779536 0 [8 C{FDCD…} -1] 1124…2998 () 8646…209 3 0 0]]

This comment was marked as resolved.

Copy link
Collaborator

@verytactical verytactical left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • This is not the part of documentation it should be in: this is mostly an advice for a node owner.
  • Fift is deprecated, and forcing users to learn it now is a bad idea. Necessary BoCs should be produced with TypeScript.

@hacker-volodya hacker-volodya removed the request for review from a team October 7, 2025 18:59
@Kaladin13
Copy link
Collaborator Author

@verytactical let's reassign it and change the issue them, I am not sure what is next

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Config > Changing params
2 participants