diff --git a/pages/operate-icon/how-to-run-a-validator-node.mdx b/pages/operate-icon/how-to-run-a-validator-node.mdx index 9f7364b..e676b33 100644 --- a/pages/operate-icon/how-to-run-a-validator-node.mdx +++ b/pages/operate-icon/how-to-run-a-validator-node.mdx @@ -1,12 +1,21 @@ # How to run a Validator node -### Prerequisites +Registering and running a validator node requires a few steps to be followed. -Install [Docker](https://www.docker.com/get-started/) +* Create a wallet for the validator +* Set up a node to run the validator +* Register a validator on the chain +* Register a validator node public key -Install [Docker Engine](https://docs.docker.com/engine/install/) +This guide will help you set up a validator node using Docker. -Install [docker-compose](https://github.com/docker/compose) as well if it is not installed with Docker by default +## Prerequisites + +* Install [Docker](https://www.docker.com/get-started/) + +* Install [Docker Engine](https://docs.docker.com/engine/install/) + +* Install [docker-compose](https://github.com/docker/compose) as well if it is not installed with Docker by default Get the official Docker Image: `iconloop/icon2-node` @@ -15,7 +24,7 @@ System Requirements CPU: minimum 4core, recommend 8core + RAM: minimum 16GB, recommend 32GB + -DISK : minimum SSD 1.5TB, recommend SSD 2TB + +DISK : minimum SSD 2.5TB, recommend SSD 3TB + Network: minimum 1Gbps, recommend 2Gbps + External Communications @@ -23,7 +32,47 @@ TCP 7100: TCP port used for peer-to-peer connection between peer nodes. TCP 9000: JSON-RPC or RESTful API port serving application requests.P-Rep must allow TCP connections to port 7100 and 9000 of an external host. ( Use 0.0.0.0/0 for a source from any network ) ``` -### Getting started +## Creating a wallet for the validator + +The first step is to create a wallet and keystore file. You can follow the instructions in this [guide](./how-to-create-a-wallet-account.mdx) to create a wallet. + +This wallet needs to be funded with enough ICX to be able to register as a validator, the registration fee is 2,000 ICX and you will also need a small amount of ICX to pay for the transaction fees. + +## Setting up the node + +Setup the node validator and wait for it to fully sync up before registering the validator wallet as a validator on the ICON network. + +Create a working folder in your server on a disk with enough space as detailed in the system requirements previsouly mentioned. + +For this tutorial we will use the following folder structure: + +``` +mkdir ~/icon-node +``` + +Change to the newly created directory + +``` +cd ~/icon-node +``` + +Create inside the folder the following directories and files: + +``` +mkdir config +touch docker-compose.yml +``` + +Save the keystore file (wallet) that was previously createdfor the validator in the `config` directory. + +At this point your folder structure should look like this: + +``` +. +├── config +│ └── keystore.json +└── docker-compose.yml +``` Open docker-compose.yml in a text editor and add the following content: @@ -38,8 +87,7 @@ services: environment: SERVICE: "MainNet" # MainNet, SejongNet ## network type GOLOOP_LOG_LEVEL: "debug" # trace, debug, info, warn, error, fatal, panic - KEY_STORE_FILENAME: "INPUT_YOUR_KEY_STORE_FILENAME" # e.g. keystore.json read a config/keystore.json - # e.g. "/goloop/config/keystore.json" read a "config/keystore.json" of host machine + KEY_STORE_FILENAME: "keystore.json" KEY_PASSWORD: "INPUT_YOUR_KEY_PASSWORD" FASTEST_START: "true" # It can be restored from latest Snapshot DB. @@ -57,13 +105,13 @@ services: - 7100:7100 ``` -Start up +Run the following command to start the ICON2 node and wait for the entire ledger to locally sync up. ``` $ docker-compose pull && docker-compose up -d ``` -To see the logs of the ICON2 node you can execute +you can monitor the process by checking the logs file that are created in the `logs` directory. ``` $ tail -f logs/booting.log @@ -72,13 +120,13 @@ $ tail -f logs/booting.log $ tail -f logs/goloop.log ``` -The directories(data, config, icon, logs …) are created by docker engine, but config directory needs to importing your keystore file. +The following folder structure will be created: ``` . ├── docker-compose.yml -├── config # configuration files -│ └── keystore.json # Import the your keystore file +├── config # configuration files +│ └── keystore.json # Import your keystore file ├── data # block data │ ├── 1 @@ -86,16 +134,14 @@ The directories(data, config, icon, logs …) are created by docker engine, but │ ├── cli.sock │ ├── ee.sock │ └── rconfig.json +├── logs # log files +│ ├── booting.log +│ ├── health.log # health check log +│ ├── chain.log # goloop chain action logs +│ ├── dowload.log +│ └── dowload_error.log +│ └── goloop.log -├── icon # icon1 data for migrate. If a migration is completed, it will be auto-remove -│ └── migrator_bm -└── logs # log files - ├── booting.log - ├── health.log # health state log - ├── chain.log # goloop chain action logs - ├── download.log - ├── download_error.log # download - └── goloop.log # goloop's log file ``` ### Docker environments settings @@ -124,6 +170,80 @@ The directories(data, config, icon, logs …) are created by docker engine, but | GOLOOP\_LOG\_LEVEL | debug | str | false | Log Level - (trace,debug,info,warn,error,fatal,panic | | LOG\_OUTPUT\_TYPE | file | str | false | sec - check interval for monitoring | +## Registering a validator on chain + + +### Registering a validator node by calling the registerPrep function + +Once the wallet is funded you can register as a validator node using the [registerPrep](https://github.com/icon-project/goloop/blob/master/doc/icon_chainscore_api.md#registerprep) function from the JSON-RPC API. + +This can be done directly from the tracker, using goloop or calling the RPC method directly. + +#### Using the tracker + +The easiest way to sign this transaction is to load up the keystore in a browser wallet ([Hana Wallet](https://hanawallet.io/)) and sign the transaction directly from the tracker by login in first with your wallet and then going to the contract page and calling the `registerPrep` function. + +https://tracker.icon.community/contract/cx0000000000000000000000000000000000000000#contract + +![registerPrep](/images/registering-validator-with-tracker.png) + +#### Using goloop cli or preptools + +Goloop CLI and the preptools are 2 command line utilities that can be used to interact with the ICON blockchain. + +These can be used to sign the transaction and call the `registerPrep` function. + +https://github.com/icon-project/goloop/blob/master/doc/goloop_cli.md#goloop-rpc-sendtx-call + +https://github.com/icon-project/preptools/blob/master/README.md#registerprep + +#### Using the JSON-RPC API + +Calling the method from the JSON-RPC API directly requires sending a signed transaction with the following parameters: + +> Request + +```javascript +{ + "jsonrpc": "2.0", + "id": 1234, + "method": "icx_sendTransaction", + "params": { + "value": "0x6c6b935b8bbd400000", + "data": { + "method": "registerPRep", + "params": { + "name": "ABC Node", + "country": "KOR", + "city": "Seoul", + "email": "abc@example.com", + "website": "https://abc.example.com/", + "details": "https://abc.example.com/details/", + "p2pEndpoint": "abc.example.com:7100", + "nodeAddress": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb" + } + }, + ... + } +} +``` + +#### Parameters + +| Key | VALUE Type | Required | Description | +| :--- | :--- | :--- | :--- | +| name | T\_STRING | true | P-Rep name "ABC Node" | +| email | T\_STRING | true | P-Rep email "abc@example.com" | +| country | T\_STRING | true | [ISO 3166-1 ALPHA-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) "KOR", "USA", "CHN" | +| city | T\_STRING | true | "Seoul", "New York", "Paris" | +| website | T\_STRING | true | P-Rep homepage url "[https://abc.example.com](https://abc.example.com)" | +| detailes | T\_STRING | true | Url including P-Rep detail information "[https://abc.example.com/details/](https://abc.example.com/details/)" | +| p2pEndpoint | T\_STRING | true | Network info used for connecting among P-Rep nodes "123.45.67.89:7100", "node.example.com:7100" | +| nodeAddress | T\_STRING | False | Node Key for only consensus "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb" | + + +The following guide explains how to interact with the ICON JSON-RPC API: [ICON JSON-RPC API](./how-to-use-the-json-rpc-api.mdx) + ### Node Grades Node grades are another term for node levels. @@ -138,6 +258,13 @@ There are 3 node grades, detailed below. You can also check the `grade` return p | 0x1 | Sub-Validator | Register your node as a sub-validator for block production and validation and network governance delegate | | 0x0 | Main Validator | Register your node as a validator for block production and validation and network governance delegate | -### Further Resources +## Registering a validator node public key + +After the node is up and running, you can register the public key of the node by following the instructions in this [guide](./how-to-run-a-validator-node/register-prep-node-public-key.mdx). + + +## Final steps + +After completing the above steps your validator node should become an active validator on the ICON network after 48 hours of being registered. -[Delegate tools](https://github.com/icon-project/preptools/) +If you need any help or assistance during the process you can reach out to the ICON community in our discord channel: [ICON Discord](/contact) diff --git a/pages/operate-icon/how-to-run-an-api-endpoint.mdx b/pages/operate-icon/how-to-run-an-api-endpoint.mdx index 0015be6..81e6db0 100644 --- a/pages/operate-icon/how-to-run-an-api-endpoint.mdx +++ b/pages/operate-icon/how-to-run-an-api-endpoint.mdx @@ -1,12 +1,18 @@ # How to run an API Endpoint -### Prerequisites +Running an API Endpoint is a similar process as setting up a validator node. -Install [Docker](https://www.docker.com/get-started/) +The only differences are the `ROLE` environment variable. The `ROLE` environment variable should be set to `0` for an API Endpoint. -Install [Docker Engine](https://docs.docker.com/engine/install/) +We also dont need to register a wallet as a validator and pay registration fee. -Install [docker-compose](https://github.com/docker/compose) as well if it is not installed with Docker by default +## Prerequisites + +* Install [Docker](https://www.docker.com/get-started/) + +* Install [Docker Engine](https://docs.docker.com/engine/install/) + +* Install [docker-compose](https://github.com/docker/compose) as well if it is not installed with Docker by default Get the official Docker Image: `iconloop/icon2-node` @@ -15,7 +21,7 @@ System Requirements CPU: minimum 4core, recommend 8core + RAM: minimum 16GB, recommend 32GB + -DISK : minimum SSD 1.5TB, recommend SSD 2TB + +DISK : minimum SSD 2.5TB, recommend SSD 3TB + Network: minimum 1Gbps, recommend 2Gbps + External Communications @@ -23,7 +29,27 @@ TCP 7100: TCP port used for peer-to-peer connection between peer nodes. TCP 9000: JSON-RPC or RESTful API port serving application requests.P-Rep must allow TCP connections to port 7100 and 9000 of an external host. ( Use 0.0.0.0/0 for a source from any network ) ``` -### Getting started +## Getting started + +Create a working folder in your server on a disk with enough space as detailed in the system requirements. + +For this guide we will use the following structure: + +``` +mkdir ~/icon-api-endpoint +``` + +Change to the working directory + +``` +cd ~/icon-api-endpoint +``` + +Create a `docker-compose.yml` file in the working directory. + +``` +touch docker-compose.yml +``` Open docker-compose.yml in a text editor and add the following content: @@ -38,14 +64,11 @@ services: environment: SERVICE: "MainNet" # MainNet, SejongNet ## network type GOLOOP_LOG_LEVEL: "debug" # trace, debug, info, warn, error, fatal, panic - KEY_STORE_FILENAME: "INPUT_YOUR_KEY_STORE_FILENAME" # e.g. keystore.json read a config/keystore.json - # e.g. "/goloop/config/keystore.json" read a "config/keystore.json" of host machine - KEY_PASSWORD: "INPUT_YOUR_KEY_PASSWORD" + KEY_STORE_FILENAME: "INPUT_YOUR_KEY_STORE_FILENAME" # optional, a wallet will be generated for you if you don't have one + KEY_PASSWORD: "INPUT_YOUR_KEY_PASSWORD" # optional, a wallet will be generated for you if you don't have one FASTEST_START: "true" # It can be restored from latest Snapshot DB. - # You must enter your ICON1 node address. Recent blocks that are not in the backup DB are synchronized from your ICON1 node. - MIG_ENDPOINT: "http://YOUR_ICON1_SERVER_IPADDR:9000" - ROLE: 3 # Validator = 3, API Endpoint = 0 + ROLE: 0 # Validator = 3, API Endpoint = 0 cap_add: - SYS_TIME @@ -56,7 +79,7 @@ services: - ./logs:/goloop/logs ``` -Start up +Run the following command to start the ICON2 node and wait for the entire ledger to locally sync. ``` $ docker-compose pull && docker-compose up -d @@ -70,13 +93,13 @@ $ tail -f logs/booting.log $ tail -f logs/goloop.log ``` -The directories(data, config, icon, logs …) are created by docker engine, but config directory needs to importing your keystore file. +The following folder structure will be created: ``` . ├── docker-compose.yml -├── config # configuration files -│ └── keystore.json # Import the your keystore file +├── config # configuration files +│ └── keystore.json # Import your keystore file ├── data # block data │ ├── 1 @@ -85,8 +108,6 @@ The directories(data, config, icon, logs …) are created by docker engine, but │ ├── ee.sock │ └── rconfig.json -├── icon # icon1 data for migrate. If a migration is completed, it will be auto-remove -│ └── migrator_bm └── logs # log files ├── booting.log ├── health.log # health state log @@ -96,7 +117,7 @@ The directories(data, config, icon, logs …) are created by docker engine, but └── goloop.log # goloop's log file ``` -### Docker environments settings +## Docker environments settings | Name | default | type | required | description | | -------------------- | ----------------------- | ---- | -------- | -------------------------------------------------------------------------------- | diff --git a/public/images/registering-validator-with-tracker.png b/public/images/registering-validator-with-tracker.png new file mode 100644 index 0000000..2d44847 Binary files /dev/null and b/public/images/registering-validator-with-tracker.png differ