Merge pull request #589 from gleb498/single-nominator

Single nominator pool clarification

Author: reveloper

docs/participate/network-maintenance/single-nominator.mdx

@@ -1,10 +1,15 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Single Nominator Pool
 
-## Using mytonctrl
+[Single Nominator](https://github.com/orbs-network/single-nominator) is a TON smart contract that enables secure validation for TON blockchain. The contract is designed for TON validators that have enough self stake to validate by themselves without relying on third-party nominators stakes. The contract provides an alternative simplified implementation for the Nominator Pool smart contract that supports a Single Nominator only.
+
+## Start using mytonctrl
 
 Currently [mytonctrl](https://github.com/ton-blockchain/mytonctrl) supports `single_nominator` contracts, but firstly you need to install mytonctrl 2.0.
 
-### mytonctrl 2.0
+### Launch mytonctrl 2.0
 
 If you already have installed mytonctrl just use command `update mytonctrl2`. If you have no mytonctrl installed, follow these steps:
 
@@ -22,31 +27,63 @@ sudo bash ./install.sh -b mytonctrl2
 
 ### Set up single-nominator
 
-After you have created and activated validator's wallet, follow these steps:
+After you have [created](/participate/run-nodes/full-node#import-existed-account) and [activated](/participate/run-nodes/full-node#activate-the-wallets) the validator's wallet, follow these steps:
 
 1. Enable single nominator mode
 
 ```bash
 MyTonCtrl> enable_mode single-nominator
 ```
 
-2. Create pool
+2. Check if single-nominator mode is enabled.
+
+```bash
+MyTonCtrl> status_modes
+Name              Status             Description                                                                                                                                                                                                                                     
+single-nominator  enabled   Orbs's single nominator pools.                                                                                                            
+```
+
+3. Create pool
 
 ```bash
 MyTonCtrl> new_single_pool <pool-name> <owner_address>
 ```
 
-3. Type `pools_list` to display pool addresses
+If you have already created pool it's possible to import it:
 
-4. Send 1 TON to the pool and activate it
+```bash
+MyTonCtrl> import_pool <pool-name> <pool-addr>
+```
+
+4. Type `pools_list` to display pool addresses
+
+```bash
+MyTonCtrl> pools_list
+Name       Status  Balance  Version   Address                                           
+test-pool  empty   0.0      spool_r2  kf_JcC5pn3etTAdwOnc16_tyMmKE8-ftNUnf0OnUjAIdDJpX  
+```
+
+5. Send 1 TON to the pool and activate it
 
 ```bash
 MyTonCtrl> activate_single_pool <pool-name>
 ```
 
+After successfully activated wallet:
+
+```bash
+MyTonCtrl> pools_list
+Name       Status  Balance  Version   Address                                           
+test-pool  active  0.99389  spool_r2  kf_JcC5pn3etTAdwOnc16_tyMmKE8-ftNUnf0OnUjAIdDJpX  
+```
+
 Now you can work with this pool via mytonctrl like with a standard nominator pool.
 
-## Without mytonctrl
+:::info
+If the pool's balance is enough to participate in both rounds (`balance > min_stake_amount * 2`) then MyTonCtrl will automatically participate in both rounds using `stake = balance / 2`, unless user sets stake manually using command `set stake`. This behaviour is different from using a nominator pool but similar to staking using validator wallet.
+:::
+
+## Start without mytonctrl
 
 #### Prepare launched Validator
 
@@ -60,19 +97,19 @@ Now you can work with this pool via mytonctrl like with a standard nominator poo
    2. Stop validation and withdraw all funds.
 
 
-## Prepare single_nominator
+### Prepare Single Nominator
 
 
 1. Install [nodejs](https://nodejs.org/en) v.16 and later and npm  ([detailed instructions](https://github.com/nodesource/distributions#debian-and-ubuntu-based-distributions))
+
 2. Install `ts-node` and `arg` module
 
 ```bash
 $ sudo apt install ts-node
 $ sudo npm i arg -g
 ```
 
-
-4. Create symlinks:
+4. Create symlinks for compilers:
 
 ```bash
 $ sudo ln -s /usr/bin/ton/crypto/fift /usr/local/bin/fift
@@ -87,9 +124,7 @@ $ npm run test
 
 6. Replace mytonctrl nominator-pool scripts: https://raw.githubusercontent.com/orbs-network/single-nominator/main/mytonctrl-scripts/install-pool-scripts.sh
 
-
-
-## Create single_nominator Pool
+### Create Single Nominator Pool
 
 1. Get Toncenter API key from a Telegram [@tonapibot](https://t.me/tonapibot)
 2. Set env variables:
@@ -127,9 +162,9 @@ $ fift -s ./scripts/fift/str-to-addr.fif Ef-kC0..._WLqgs
 7. Copy "single-nominator.addr" to "mytoncore/pools/single-nominator-1.addr"
 8. Send stake from owner address to single nominator address
 
-## Withdrawals from Single Nominator
+### Withdrawals from Single Nominator
 
-Using wallets to withdraw from single_nominator
+Using wallets to withdraw from Single Nominator
 Fift:
 
 1. Create "withdraw.boc" request with amount:
@@ -180,6 +215,213 @@ npx ts-node scripts/ts/withdraw-deeplink.ts <single-nominator-addr> <withdraw-am
 
 d. Open deeplink on the owner's phone
 
+## Deposit pool
+
+You can make a deposit using **MyTonCtrl**, using the following commands:
+
+```sh
+MyTonCtrl> mg <from-wallet-name> <pool-account-addr> <amount>
+```
+
+or
+
+```sh
+MyTonCtrl> deposit_to_pool <pool-addr> <amount>
+```
+
+which deposits pool from validator wallet.
+
+Or use the following steps:
+
+1. Go to the pool’s page https://tonscan.org/nominator/<pool_address>.
+
+2. Make sure that the information about the pool is fully displayed, if the pool has the wrong smart contract, there will be no information.
+
+3. Press the `ADD STAKE` button or scan the QR-code using Tonkeeper or any other TON Wallet.
+
+4. After you are transferred to the wallet, please, enter the amount of TON and then send the transaction. After that TON coins will be added to staking.
+
+If the wallet does not open automatically, you can send the transaction manually by copying the pool address. Send it through any TON wallet. From the sent transaction, 1 TON will be debited as a commission for processing the deposit.
+
+
+## Withdraw funds
+
+To get coins back after staking, send 1 TON to the pool’s address, add a comment **w** (small letter) to the transaction. This 1 TON minus commission will be returned, and a smart-contract will understand that you want to bring the coins back and it will send them back right after the end of the validator’s work cycle. It usually takes up to 18 hours on Mainnet and 2 hours on Testnet.
+
+You can also withdraw funds using the following command:
+
+```sh
+MyTonCtrl> withdraw_from_pool <pool-addr> <amount>
+```
+
+Or you can create and send transaction manually:
+
+<Tabs groupId="code-examples">
+<TabItem value="toncore" label="JS (@ton)">
+
+```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) // op code for withdrawal
+        .storeUint(0, 64)           // query_id
+        .storeCoins(amount)         // amount to withdraw
+        .endCell();
+
+    const internalMessage = internal({
+        to: single_nominator_address,
+        value: toNano('1'),
+        bounce: true,
+        body: messageBody
+    });
+}
+```
+
+</TabItem>
+
+<TabItem value="tonconnect" label="Golang">
+
+```go
+func WithdrawSingleNominatorMessage(single_nominator_address string, query_id, amount uint64) (*tonconnect.Message, error) {
+
+	const WITHDRAW_OP = 0x1000
+
+	payload, _ := cell.BeginCell().
+		MustStoreUInt(WITHDRAW_OP, 32). // op code for withdrawal
+		MustStoreUInt(query_id, 64).    // query_id
+		MustStoreCoins(amount).         // amount to withdraw
+		EndCell().MarshalJSON()
+
+	msg, err := tonconnect.NewMessage(
+		single_nominator_address,
+		tlb.MustFromTON("1").Nano().String(), // nanocoins to transfer/compute message
+		tonconnect.WithPayload(payload))
+
+	if err != nil {
+		return nil, err
+	}
+
+	return msg, nil
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+
+## Election process
+
+### Set up a Single Nominator Pool
+
+Configure the Single Nominator Pool contract using the [following]((/participate/network-maintenance/single-nominator#set-up-single-nominator)) instructions.
+
+### Join the elections
+
+[Deposit](/participate/network-maintenance/single-nominator#deposit-pool) minimum stake amount to the Single Nominator Pool.
+
+**MyTonCtrl** will automatically join the elections. You can set the stake amount that mytonctrl sends to the [Elector contract](/develop/smart-contracts/governance#elector) ~ every 18 hours on Mainnet and 2 hours on Testnet.
+
+```sh
+MyTonCtrl> set stake 90000
+```
+
+**Minimum stake** amount could be found using `status` command.
+
+![](/img/docs/single-nominator/tetsnet-conf.png)
+
+You can set `stake` as `null` and it will be calculated according to the `stakePercent` value (could be checked with `status_settings` command).
+
+It's possible to check is election has already been started:
+
+```bash
+MyTonCtrl> status
+```
+
+and for Testnet:
+
+```bash
+MyTonCtrl> status fast
+```
+
+As example:
+
+![](/img/docs/single-nominator/election-status.png)
+
+
+If the election has been started and Single Nominator Pool is activated, validator should **automatically** send **ElectorNewStake** message to the Elector contract at the beginning of the next round.
+
+Check validator wallet:
+
+```sh
+MyTonCtrl> wl
+Name                  Status  Balance           Ver  Wch  Address                                           
+validator_wallet_001  active  995.828585374     v1   -1   kf_dctjwS4tqWdeG4GcCLJ53rkgxZOGGrdDzHJ_mxPkm_Xct  
+```
+
+Then check it transaction history:
+
+```sh
+MyTonCtrl> vas kf_dctjwS4tqWdeG4GcCLJ53rkgxZOGGrdDzHJ_mxPkm_Xct
+Address                                           Status  Balance        Version  
+kf_dctjwS4tqWdeG4GcCLJ53rkgxZOGGrdDzHJ_mxPkm_Xct  active  995.828585374  v1r3     
+
+Code hash                                                         
+c3b9bb03936742cfbb9dcdd3a5e1f3204837f613ef141f273952aa41235d289e  
+
+Time                 Coins   From/To                                           
+39 minutes ago  >>>  1.3     kf_hz3BIXrn5npis1cPX5gE9msp1nMTYKZ3l4obzc8phrBfF  
+```
+
+This **ElectorNewStake** transaction in Single Nominator contract history in Tonviewer:
+
+![](/img/docs/single-nominator/new-stake.png)
+
+On the above example **MyTonCtrl** automatically stake `90000` Toncoins on the Elector contract.
+
+### Checking Validator Status
+
+At the beginning of the next round check **MyTonCtrl** validator status with `status` command (`status fast` on Testnet).
+
+![](/img/docs/single-nominator/status-validator.png)
+
+You can confirm if your node has become a full validator by checking the following conditions:
+
+1. **Validator Efficiency** - An efficiency of the local validator should be green and not `n/a`.
+2. **Validator Index** - The validator index should be greater than -1.
+
+
+### Checking profit
+
+At the end of the round **MyTonCtrl** sends **ElectorRecoverStakeRequest** message to the Elector contract. It responses with `stake + profit` amount of Toncoins to your Single Nominator Pool.
+
+![](/img/docs/single-nominator/validator-profit.png)
+
+You can also check transactions history of your pool with `vas` command:
+
+![](/img/docs/single-nominator/validator-profit-vas.png)
+
+### Stop participating
+
+If user doesn't want to take part in validating anymore:
+
+1. Disable validator mode:
+
+```bash
+MyTonCtrl> disable_mode validator
+2. [Withdraw](/participate/network-maintenance/single-nominator#withdraw-funds) all funds from the Single Nominator contract to the owner wallet.
+
+## Transitioning a Regular Validator to Nominator Pool Mode
+
+1. Disable `validator` mode to discontinue election participation.
+2. Await the return of both your stakes from the elector.
+3. Proceed with the following [steps](/participate/network-maintenance/single-nominator#set-up-single-nominator).
+
 
 ## See Also
 

docs/participate/run-nodes/full-node.mdx

@@ -224,6 +224,17 @@ Wait until `Local validator out of sync` becomes less than 20 seconds.
 
 ## Become a Validator
 
+### Import existed account
+
+It is possible to import existed account to **MyTonCtrl** using `iw` command:
+
+```sh
+iw <wallet-addr> <wallet-secret-key>
+```
+
+During the execution, the wallet_001 wallet is created:
+
+![](\img\docs\full-node\import-acc.png)
 
 ### View the List of Wallets
 
@@ -689,6 +700,15 @@ If validatorWalletName is null then execute the following:
 mytonctrl> set validatorWalletName validator_wallet_001
 ```
 
+### Status error on Testnet
+
+![](\img\docs\full-node\status-error.jpg)
+
+This error could be seen on Testnet network on `status` command. Use the following instead:
+
+```bash
+mytonctrl> status fast
+```
 
 ### Transfer a Validator on the new Server