diff --git a/docs/en/manual-ubuntu.md b/docs/en/manual-ubuntu.md index aee1ae72..6e427be6 100644 --- a/docs/en/manual-ubuntu.md +++ b/docs/en/manual-ubuntu.md @@ -7,7 +7,7 @@ Here are the steps to become a validator using mytonctrl. This example is applic 1. Download the installation script. We recommend installing the tool under your local user account, not as Root. In our example, a local user account is used: ```sh - wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/scripts/install.sh + wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/mytonctrl2/scripts/install.sh ``` ![wget output](https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/screens/manual-ubuntu_wget-ls_ru.png) @@ -15,7 +15,7 @@ Here are the steps to become a validator using mytonctrl. This example is applic 2. Run the installation script as an administrator: ```sh - sudo bash install.sh -m full + sudo bash ./install.sh -b mytonctrl2 ``` ## 2. Conduct an Operability Test: diff --git a/docs/en/single-nominator-pool.md b/docs/en/single-nominator-pool.md new file mode 100644 index 00000000..422f07d6 --- /dev/null +++ b/docs/en/single-nominator-pool.md @@ -0,0 +1,386 @@ +# Single Nominator Pool + +[Single Nominator](https://github.com/orbs-network/single-nominator) is a new TON smart contract that enables secure validation for TON blockchain via an air gapped cold wallet.The contract is designed for TON validators that have enough self stake to validate by themselves without relying on third-party nominators. + +The contract provides an alternative simplified implementation for the core team’s Nominator Pool smart contract that supports a single nominator only. The benefit of this implementation is that it's more secure since the attack surface is considerably smaller. This is due to a massive reduction in complexity of the Nominator Pool that has to support multiple third-party nominators. + +## Start using mytonctrl + +Currently [mytonctrl](https://github.com/ton-blockchain/mytonctrl) supports `single_nominator` contracts, but firstly you need to install 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: + +1. Download installation script: + +```bash +wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/mytonctrl2/scripts/install.sh +``` + +2. Run installation script: + +```bash +sudo bash ./install.sh -b mytonctrl2 +``` + +### Set up single-nominator + +After you have [created](/participate/run-nodes/full-node#import-existed-account) and [activated](/participate/run-nodes/full-node#activate-the-wallets) validator's wallet, follow these steps: + +1. Enable single nominator mode + +```bash +MyTonCtrl> enable_mode single-nominator +``` + +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 +``` + +If you have already created pool it's possible to import it: + +```bash +MyTonCtrl> import_pool +``` + +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 +``` + +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. + +## Start without mytonctrl + +#### Prepare launched Validator + +If you have mytonctrl installed and validator running: + +1. Stop validation and withdraw all funds. + +#### Prepare from the beginning +If you had no Validator before, do the following: +1. [Run a Validator](/participate/run-nodes/full-node) and make sure it's synced. +2. Stop validation and withdraw all funds. + + +### 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 for compilers: + +```bash +$ sudo ln -s /usr/bin/ton/crypto/fift /usr/local/bin/fift +$ sudo ln -s /usr/bin/ton/crypto/func /usr/local/bin/func +``` + +5. Run test to make sure everything is set up properly: + +```bash +$ 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 + +1. Get Toncenter API key from a Telegram [@tonapibot](https://t.me/tonapibot) +2. Set env variables: + +```bash +export OWNER_ADDRESS= +export VALIDATOR_ADDRESS= +export TON_ENDPOINT=https://toncenter.com/api/v2/jsonRPC +export TON_API_KEY= +``` + +2. Create deployer address: + +```bash +$ npm run init-deploy-wallet +Insufficient Deployer [EQAo5U...yGgbvR] funds 0 +``` + +3. Topup deployer address with 2.1 TON +4. Deploy pool contract, you will get pool address: `Ef-kC0..._WLqgs`: + +``` +$ npm run deploy +``` + +5. Convert address to .addr: + +``` +$ fift -s ./scripts/fift/str-to-addr.fif Ef-kC0..._WLqgs +``` + +(Saving address to file single-nominator.addr) + +6. Backup deployer private key "./build/deploy.config.json" and "single-nominator.addr" files +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 + +Using wallets to withdraw from Single Nominator +Fift: + +1. Create "withdraw.boc" request with amount: + +```bash +$ fift -s ./scripts/fift/withdraw.fif +``` + +2. Create and sign request from owner's wallet: + +```bash +$ fift -s wallet-v3.fif -B withdraw.boc +``` + +3. Broadcast query: + +```bash +$ lite-client -C global.config.json -c 'sendfile wallet-query.boc' +tons +``` + +1. Create "withdraw.boc" request with amount: + +```bash +$ fift -s ./scripts/fift/withdraw.fif +``` + +2. Send request to single nominator address: + +a. + +```bash +$ tons wallet transfer --body withdraw.boc +tonkeeper +``` + +b. + +``` +npm link typescript +``` + +c. + +``` +npx ts-node scripts/ts/withdraw-deeplink.ts +``` + +d. Open deeplink on the owner's phone + +## Deposit pool + +1. Go to the pool’s page https://tonscan.org/nominator/. + +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. + +You can also make a deposit using mytonctrl, using the following commands: + +```sh +MyTonCtrl> mg +``` + +or + +```sh +MyTonCtrl> deposit_to_pool +``` + +which deposits pool from validation wallet. + +**MyTonCtrl** will automatically join the elections. You can set the stake amount that mytonctrl sends to [Elector contract](/develop/smart-contracts/governance#elector) ~ every 18 hours. + +```sh +MyTonCtrl> set stake 50000 +``` +Minimal stake amount could be found using `status` command. + +![](/img/docs/single-nominator/tetsnet-conf.png) + +## Stop participating (withdraw) + +If user doesn't want to take part in validating anymore it's possible to withdraw all funds from the Single Nominator contract to validators personal wallet. 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. + +You can also withdraw funds using the following command: + +```sh +MyTonCtrl> withdraw_from_pool +``` + +Or you can create and send transaction manually: + + + + +```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 + }); +} +``` + + + + + +```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 +} +``` + + + + + + +## Election process + +1. Check that election has been already started: + +```bash +MyTonCtrl> status +``` + +and for Testnet: + +```bash +MyTonCtrl> status fast +``` + +As example: + +```sh +MyTonCtrl> status fast +===[ TON network status ]=== +Network name: testnet +Number of validators: n/a(15) +Number of shardchains: 4 +Number of offers: 0(0) +Number of complaints: 0(0) +Election status: closed +``` + +2. If the election has been started and Single Nominator Pool is activated, validator should **automatically** send **ElectorNewStake** message to Elector contract. + +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) + +## Delete pool + +It's also possible to delete local pool: + +```bash +MyTonCtrl> delete_pool +``` + +## 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 following [steps](/participate/network-maintenance/single-nominator#set-up-single-nominator).