KYVE has a broad ecosystem of projects archiving their data with KYVE. To standardize different data from different projects KYVE created special runtimes for standards like @kyvejs/evm for all EVM based chains. This has great benefits but also has downsides for protocol node runners in terms of user experience.
Without KYSOR for every pool the node runner has to get the binaries manually. If you want to run on another pool which has a different runtime you again have to manually obtain the binaries. Furthermore, if a pool ever upgrades to a newer protocol node version, you have the same procedure as before. Even worse, you might miss the update and receive a timeout slash for being offline
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
Get the latest release of the KYSOR binaries here
wget https://github.com/KYVENetwork/kyvejs/releases/download/%40kyve%2Fkysor%40$VERSION/kysor-linux-x64.zipunzip kysor-linux-x64.zipmv kysor-linux-x64 kysorchmod 700 kysorAvailable KYSOR binaries for platforms:
linux-arm64
wget https://github.com/KYVENetwork/kyvejs/releases/download/%40kyve%2Fkysor%401.0.0-beta.1/kysor-linux-arm64.ziplinux-x64
wget https://github.com/KYVENetwork/kyvejs/releases/download/%40kyve%2Fkysor%401.0.0-beta.1/kysor-linux-x64.zipmacos-x64
wget https://github.com/KYVENetwork/kyvejs/releases/download/%40kyve%2Fkysor%401.0.0-beta.1/kysor-macos-x64.zipTo verify that the KYSOR runs successfully just run
./kysor versionInitialize KYSOR
Once you have successfully downloaded the KYSOR binary you have to initialize it.
When you init the KYSOR you need to specify the network you should run on and if the KYSOR should automatically download and execute the binaries for you. Since we are in korellia testnet we would recommend initializing with the following properties:
./kysor init --chain-id korellia --rpc https://rpc.korellia.kyve.network/ --rest https://api.korellia.kyve.network/ --auto-download-binariesThis command creates a config.toml under the following directory: $HOME/.kysor/. You can edit this file if you wish to change the chain ID or the auto download feature.
⚠️ IMPORTANT: Since we are in testnet it is okay to leave auto download on, but once KYVE is in mainnet we would highly recommend turning auto download off and compiling the upgrade binaries yourself. You can find more information below for how to upgrade with KYSOR manually.
Create your first valaccount
Now that KYSOR is initialized we move on to the next step. For every pool you run on a valaccount has to be created. In our example, we want to run on the Moonbeam pool with Pool Id 0. A new valaccount with a new mnemonic can be created in the following way:
./kysor valaccounts create \
--name moonbeam \
--pool 0 \
--storage-priv "$(cat path/to/arweave.json)" \
--verbose \
--metricsThis will create a moonbeam.toml file under the kysor home directory in $HOME/.kysor/valaccounts/. There you can view your valaccount config.
If you want to create a valaccount from an existing mnemonic just add the --recover flag like this:
./kysor valaccounts create \
--name moonbeam \
--pool 0 \
--storage-priv "$(cat path/to/arweave.json)" \
--verbose \
--metrics \
--recoverThis will prompt you to enter the mnemonic you want to import. More help on how to manage valaccounts can be found with ./kysor valaccounts --help
ℹ️ INFORMATION: Of course multiple valaccounts can be created for each pool. We would recommend naming the valaccounts after the pool you want to run with this account on like in this case
moonbeamfor example. These names are just used locally for config management. Also, if you have multiple valaccounts running on the same machine you are required to change the port of the metrics server (if enabled of course) so they don't overlap.
Run the KYSOR
After you have created the required valaccounts you can simply start running the KYSOR with the following command:
./kysor start --valaccount moonbeamWhen KYSOR is running, you can proceed with step 3.
You can also start the process in debug mode by adding the --debug flag like this:
./kysor start --valaccount moonbeam --debugRun KYSOR on multiple pools
If you want to run KYSOR with multiple pools you only have to edit one configuration in the valaccounts. The Protocol Nodes starts a metrics prometheus server if the option metrics is enabled. On default the metrics server is available under the following endpoint: http://localhost:8080/metrics. If you start on multiple pools those servers would collide because of the same port. You can solve this by editing the valaccounts config toml and specifying a different port for each valaccount.
Run the KYSOR without auto download
If you want to run the KYSOR without auto download enabled like it would be recommended in mainnet just set the property autoDownloadBinaries to false in the $HOME/.kysor/config.toml. After that you should restart the KYSOR to make changes available.
Before an upgrade you are then required to prebuild the upgrade binaries yourself and place them in the correct path. Once you have the upgrade binary compiled move them to the following directory before the upgrade:
mv kyve-upgrade-binary $HOME/.kysor/upgrades/pool-$POOL/$VERSION/bin$POOL is the pool id where the binary should run on. For example for the Moonbeam pool with pool id 0 and upgrade version 1.0.0-beta.6 you should move the upgrade binary to the following folder:
mv kyve-moonbeam-binary $HOME/.kysor/upgrades/pool-0/1.0.0-beta.6/bin/The upgrade binaries of each version in korellia will be available here: github.com/KYVENetwork/kyvejs/releases
General KYSOR directory structure
Knowing where KYSOR saves its logs and binaries can be helpful. The example below shows the following setup: The KYSOR runs on two pools with pool id 0 and 2. Pool 2 is still running on version 0.8.6 while pool 0 has already upgraded from 1.8.6 to 1.8.7
.kysor
├── config.toml
├── logs
│ └── 2022-09-29T08:38:24.513Z.log
│ └── 2022-09-29T09:29:22.219Z.log
├── upgrades
│ ├── pool-0
│ | ├── 1.8.6
│ | | ├── bin
│ | | │ └── kyve-linux-x64
│ | | ├── cache
| | | │ ├── 234.json
| | | │ └── ...
│ | | └── logs
│ | | ├── 2022-09-29T08:23:02.003Z.log
│ | | └── 2022-09-29T08:23:24.953Z.log
│ | └── 1.8.7
│ | ├── bin
│ | │ └── kyve-linux-x64
│ | ├── cache
| | │ ├── 567.json
| | │ └── ...
│ | └── logs
│ | └── 2022-09-29T08:23:24.953Z.log
│ └── pool-2
│ └── 0.8.6
│ ├── bin
│ │ └── kyve-linux-x64
│ ├── cache
| │ ├── 3847.json
| │ └── ...
│ └── logs
│ └── 2022-09-29T08:23:02.003Z.log
└── valaccounts
├── moonbeam.toml
└── celo.toml
Here the following directories have the following reason:
.kysor- KYSOR home directory, created with init commandconfig.toml- general KYSOR config, created with init commandlogs- logs folder containing KYSOR log files. Each log file is a run from start to end where the date is the starting dateupgrades- most important directory, contains all the binaries for every poolupgrades/pool-$id- holds every binary of every installed version of the specified poolupgrades/pool-$id/$version- acts as a home directory for a specific binary, contains binary cache, logs and actual protocol node binaryupgrades/pool-$id/$version/bin- holds actual node binaryupgrades/pool-$id/$version/cache- contains cached data relevant for the protocol nodeupgrades/pool-$id/$version/logs- logs folder for the protocol node of that version and pool. Each log file is a run from start to end where the date is the starting datevalaccounts- contains all the valaccount config files with which the KYSOR can run on a pool
Run KYSOR with systemd
For the daemon service root-privileges are required during the setup. Create a service file. $USER is the Linux user which runs the process. Replace it before you copy the command.
Since the KYSOR can run on multiple pools on one machine we would recommend naming the daemon service after the valaccount name and with a d appending to it. With that you can create multiple service files and control each of them. This example shows the service file for our valaccount moonbeam
tee <<EOF > /dev/null /etc/systemd/system/moonbeamd.service
[Unit]
Description=KYVE Protocol-Node moonbeam daemon
After=network-online.target
[Service]
User=$USER
ExecStart=/home/$USER/kysor start --valaccount moonbeam
Restart=on-failure
RestartSec=3
LimitNOFILE=infinity
EOFStart the daemon
sudo systemctl enable moonbeamd
sudo systemctl start moonbeamdIt can be stopped using
sudo systemctl stop moonbeamd
You can see its logs with
sudo journalctl -u moonbeamd -f