# Running a protocol node

The protocol nodes are the backbone of a KYVE pool. They are responsible for collecting data from a data source, bundling and uploading them to Arweave and verifying it. This enables KYVE to store any data stream decentralized and permanently.

# Requirements


Minimum hardware requirements

  • 1vCPU
  • 4GB RAM
  • 1GB DISK

# Get some $KYVE

Before continuing, make sure that you have the Keplr (opens new window) or Cosmostation (opens new window) wallet installed in your browser. Head over to the KYVE app (opens new window) and make sure to connect your wallet (this automatically adds and switches to the KYVE network).

Go to the faucet tab and claim some tokens via one of three faucets. The wheel is the easiest option.

IMPORTANT: Make sure that you are on the correct app URL https://app.kyve.network

# Choose a pool

Before you can run a protocol node you have to choose a pool you want to join. You can find an overview of all pools in the KYVE app here (opens new window). Once you have chosen a pool you have to remember the pool id and the pool runtime for later. You can find this information right below the pool name once you have clicked on a pool in the overview. In this example we have chosen the first pool with the pool id 0 and the runtime @kyve/evm.

# Verify that you can claim a validator slot

Due to a limited number of validator slots in each pool only the nodes with the highest stake can claim a validator slot. You can only claim a validator slot if you have more than the minimum staking amount.

To check the minimum staking amount you can click on the tab Validators once you have selected a pool. There you should see something like this:

minimum stake

In this case all validator slots are occupied, but since the minimum staking amount is 300 $KYVE you just need to have more than 300 to claim a slot. If the minimum staking amount is zero you just have to have more than zero $KYVE.

IMPORTANT: If you don't have more $KYVE than the minimum staking amount you can not continue!

This example will show how to run a protocol node on a linux system on the Moonbeam pool with the pool Id 0. More information can be found here (opens new window)

Running nodes with KYSOR has the following benefits:

  • Only use one program to run on every pool
  • Not installing and compiling protocol binaries manually for every pool
  • Getting the new upgrade binaries during a pool upgrade automatically and therefore don't risk timeout slashes
  • Make running protocol nodes standardized and easier

# Installation

Currently, there are no binaries for the KYSOR, therefore it has to be installed and build manually by cloning the repository:

Copy git clone https://github.com/kyve-org/kysor.git cd kysor

# Install dependencies

In order to get started run the following in the project root directory:

Copy yarn install

# Setup

General directory structure and important files:

  • src contains all the source code of KYSOR
  • kysor.conf.ts is the main config file. It is explained in more detail below
  • secrets is the directory where your secrets are stored like arweave.json and mnemonic.txt
  • runtimes will be autogenerated once you start KYSOR and will contain all binaries structured by runtime and version
  • db will be autogenerated once you start KYSOR and will contain all caching data for the protocol nodes
  • logs will be autogenerated once you start KYSOR and will contain all log data for the protocol nodes

In order to setup KYSOR the following secrets need to be added under the secrets directory. If this directory does not exist yet create it in project root.

  • arweave.json this is the Arweave keyfile you need to provide in order to run protocol nodes. This one keyfile will be used for all of your protocol nodes
  • mnemonic.txt this is the file which contains your mnemonic of your validator account. This one mnemonic will be used for all of your protocol nodes

After adding the required secrets you can check the kysor.conf.ts file. When you initially open it, it should look like this:

Copy import { IConfig } from './src/faces'; const config: IConfig = { // target of the host machine, can be either "linux" or "macos" // important for downloading the correct binaries hostTarget: 'linux', // whether KYSOR should auto download new binaries // if set to false, you have to insert the binaries manually autoDownload: true, // whether KYSOR should verify the checksums of downloaded binaries // if autoDownload is false this option can be ignored verifyChecksums: true, // settings for protocol node // notice that mnemonic and keyfile is missing, those need to be files under the secrets directory protocolNode: { // the ID of the pool you want to join as a validator // an overview of all pools can be found here -> https://app.kyve.network poolId: 0, // the network you want to run on // currently only the testnet network "korellia" is available network: 'korellia', // the amount of $KYVE you want to stake // will only get applied if you are not a validator yet // once you are a validator you can manage your stake in the KYVE app initialStake: 100, // the amount of bytes the node can use at max to cache data // 1000000000 equals 1 GB which is usually enough space: 1000000000, // specify verbose logging // is often recommended in order to have a more detailed insight verbose: true, }, }; export default config;

Since this file is commented and explained in detail the info regarding config properties can be found in this file. Every time you edit the config file you have to build the project with yarn build.

After entering your config like the poolId and your initialStake and other settings that are required to run a protocol node on a pool you can start KYSOR by running

Copy yarn build yarn start

When you see logs like this everything should work fine

Copy 2022-05-19 13:54:00.299 INFO Starting KYSOR ... 2022-05-19 13:54:00.299 INFO Validating files ... 2022-05-19 13:54:00.300 INFO Found kysor.conf.ts 2022-05-19 13:54:00.300 INFO Found arweave.json 2022-05-19 13:54:00.300 INFO Found mnemonic.txt 2022-05-19 13:54:00.300 INFO Creating "runtimes" directory ... 2022-05-19 13:54:00.300 INFO Attempting to fetch pool state. 2022-05-19 13:54:00.543 INFO Fetched pool state 2022-05-19 13:54:00.543 INFO Binary of runtime "@kyve/evm" with version 1.0.5 not found locally 2022-05-19 13:54:00.544 INFO Found downloadable binary on pool 2022-05-19 13:54:00.545 INFO Downloading https://github.com/kyve-org/evm/releases/download/v1.0.5/kyve-linux.zip?checksum=8662ddeb3a3e0eaedbbb5a665a4fa0eed12448349218ef0d98afed25cfacd60c ... 2022-05-19 13:54:01.910 INFO Extracting binary to "./runtimes/@kyve/evm/1.0.5/kyve.zip" ... 2022-05-19 13:54:02.315 INFO Deleting kyve.zip ... 2022-05-19 13:54:02.664 INFO Comparing binary checksums ... 2022-05-19 13:54:02.666 INFO Found checksum = 8662ddeb3a3e0eaedbbb5a665a4fa0eed12448349218ef0d98afed25cfacd60c 2022-05-19 13:54:02.666 INFO Local checksum = 8662ddeb3a3e0eaedbbb5a665a4fa0eed12448349218ef0d98afed25cfacd60c 2022-05-19 13:54:02.666 INFO Checksums are equal. Continuing ... 2022-05-19 13:54:02.666 INFO Starting child process ... 2022-05-19 13:54:06.858 INFO Starting node ... 2022-05-19 13:54:06.861 INFO Name = impressed-emerald-spoonbill 2022-05-19 13:54:06.953 INFO Address = kyve1eka2hngntu5r2yeuyz5pd45a0fadarp3zue8gd 2022-05-19 13:54:06.954 INFO Pool Id = 0 2022-05-19 13:54:06.954 INFO @kyve/core = v1.0.8 2022-05-19 13:54:06.954 INFO @kyve/evm = v1.0.5 2022-05-19 13:54:06.955 DEBUG Attempting to fetch pool state. 2022-05-19 13:54:07.245 INFO Running node on runtime @kyve/evm. 2022-05-19 13:54:07.248 INFO Pool version requirements met 2022-05-19 13:54:07.249 INFO Fetched pool state 2022-05-19 13:54:07.349 INFO Node is already staked. Skipping ... 2022-05-19 13:54:07.350 INFO Running node with a stake of 100.0000 $KYVE

# Get the prebuilt binaries

For our case, the prebuilt binaries every operating system can be downloaded here (opens new window) for every operating system. For example on EVM it would be evm-linux, evm-macos.

In general, you can get the binaries by clicking on the Become a validator button and following the steps until you're on the section Get node binaries.

become validator

Once you're there click the button KYVE node which should lead you to the github repository.

protocol binaries

Once you're on releases you can download the latest binary for your operating system. In our case we download the evm-macos.zip and unzip it locally.

protocol binary download

When you have downloaded and unzipped the binary correctly you can proceed to how to verify your binary

# Manually build the binaries

Since we want to run a protocol node on a @kyve/evm runtime pool we have to clone the correct repository. In our case clone the EVM repository (opens new window) and make sure your are on branch main.

Copy git clone https://github.com/KYVENetwork/evm.git cd evm

Now run the following commands to install dependencies and build the binaries

Copy yarn install yarn build:binaries

Once the binaries have been build you should see three binaries (one for every operating system) in the out directory.

# Verify that your binary has been built correctly

Execute the binary using the following command to see the available options (example is on a MacOS machine)

Copy ./evm-macos --help

If everything is set up correctly you should see the following

Copy Usage: @kyve/evm [options] Options: --name <string> The identifier name of the node. [optional, default = auto generated] -p, --poolId <number> The id of the pool you want to run on. -m, --mnemonic <string> Your mnemonic of your account. -k, --keyfile <string> The path to your Arweave keyfile. -s, --initialStake <number> Your initial stake the node should start with. Flag is ignored node is already staked [unit = $KYVE]. -n, --network <string> The chain id of the network. [optional, default = korellia] (default: "alpha") -sp, --space <number> The size of disk space in bytes the node is allowed to use. [optional, default = 1000000000 (1 GB)] (default: "1000000000") -b, --batchSize <number> The batch size of fetching items from datasource. For synchronous fetching enter 1. [optional, default = 1] --metrics Run Prometheus metrics server. [optional, default = false] (default: false) -v, --verbose Run node in verbose mode. [optional, default = false] (default: false) --version output the version number -h, --help display help for command

# Start your node

To run your node, copy your Arweave keyfile into your working directory and fetch the mnemonic from Keplr. Here it is important that you enter the correct --poolId, your --mnemonic and your desired --initialStake. In our case, we initially stake 10,000 $KYVE to ensure that we get a validator slot.

Run the following command with the same binary as above

Copy ./evm-macos --poolId 0 --mnemonic "your mnemonic in here ..." --initialStake 10000 --keyfile ./arweave.json --network korellia

If your node has started correctly, it should print some logs like this:

Copy 2022-04-07 14:43:18.673 INFO Starting node ... 2022-04-07 14:43:18.676 INFO Name = cute-maroon-pinniped 2022-04-07 14:43:18.736 INFO Address = kyve1zpmetvqgeuh6ua4q5cnajay6u4uhuuvnjt85m7 2022-04-07 14:43:18.737 INFO Pool Id = 0 2022-04-07 14:43:18.737 INFO @kyve/core = v1.0.2 2022-04-07 14:43:18.738 INFO @kyve/evm = v1.0.1 2022-04-07 14:43:18.739 DEBUG Attempting to fetch pool state. 2022-04-07 14:43:19.059 INFO Running node on runtime @kyve/evm. 2022-04-07 14:43:19.064 INFO Pool version requirements met 2022-04-07 14:43:19.066 INFO Fetched pool state 2022-04-07 14:43:19.172 DEBUG Staking 100.0000 $KYVE ... 2022-04-07 14:43:19.883 DEBUG Transaction = FA101B41873129D16937947ED1460F48A8EFD693B9CD7F12E65F221B5B7C9556 2022-04-07 14:43:26.243 INFO Successfully staked 100.0000 $KYVE 2022-04-07 14:43:26.246 INFO Running node with a stake of 100.0000 $KYVE 2022-04-07 14:43:26.247 INFO Joining KYVE network ... 2022-04-07 14:43:26.370 DEBUG Attempting to verify node. 2022-04-07 14:43:26.371 INFO Node is running as a validator. 2022-04-07 14:43:26.374 INFO Starting new proposal 2022-04-07 14:43:26.377 INFO Cached to height = 0 2022-04-07 14:43:26.489 INFO Selected as VALIDATOR 2022-04-07 14:43:26.608 INFO Validating bundle sYNwr1BttK_WmIkjXJILjjcn60IHSX64QpBqi2fCyuU 2022-04-07 14:43:26.776 DEBUG Downloading bundle from Arweave ... 2022-04-07 14:43:27.648 DEBUG Successfully downloaded bundle from Arweave ...

# Verify node stake

When you look at your node logs you should then see that the node is starting to verify bundles.

After you have successfully staked you should see your address in the Pool validators table.

verify stake

Also, you can now manage your stake through the app under Manage stake.