diff --git a/docs/index.md b/docs/index.md index 81db4e3..97a8792 100755 --- a/docs/index.md +++ b/docs/index.md @@ -27,6 +27,7 @@ Get familiar with KYVE and explore its main concepts. ## Explore the Stack - **[KYVE](https://www.kyve.network/datalake)** - The Web3 data lake for fetching, storing, and validating data +- **[KSYNC](https://github.com/KYVENetwork/ksync)** - Rapidly sync validated blocks and snapshots from KYVE to every Tendermint based Blockchain Application - **[Data Pipeline](https://www.kyve.network/datapipeline)** - An ELT pipeline for accessing KYVE data - More products coming soon ... diff --git a/docs/tools/KSYNC/examples.md b/docs/tools/KSYNC/examples.md deleted file mode 100644 index 5108225..0000000 --- a/docs/tools/KSYNC/examples.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Examples - -### 1. Sync Cosmos Hub with AUTO-SYNC - -Cosmos Hub requires a start with P2P sync due to the >100MB genesis file. -To simplify the syncing process, we can use AUTO-SYNC to let KSYNC manage both processes independently. - -To start successfully, you need to download and set up the correct binary with the version `v.4.2.1`. You can download them [here](https://github.com/cosmos/gaia/releases/tag/v4.2.1) or build them from source: -[https://github.com/cosmos/gaia](https://github.com/cosmos/gaia) - -Verify installation with - -```bash -./gaiad version -4.2.1 -``` - -After the installation init the project - -```bash -./gaiad init --chain-id cosmoshub-4 -``` - -download the genesis - -```bash -wget https://raw.githubusercontent.com/cosmos/mainnet/master/genesis/genesis.cosmoshub-4.json.gz -gzip -d genesis.cosmoshub-4.json.gz -mv genesis.cosmoshub-4.json ~/.gaia/config/genesis.json -``` - -Don't include an addrbook.json and KSYNC will manage your config file itself. -It should only connect to our peer. The supervised KSYNC process can be started with - -```bash - ksync start --daemon-path //gaiad --home /Users//.gaia --pool-id 0 --chain-id=kyve-1 -``` - -### 2. Sync Osmosis with DB-SYNC - -To sync osmosis you have to download and set up the correct osmosis binary. To sync from genesis the version `v3.1.0` has -to be used. You can download them [here](https://github.com/osmosis-labs/osmosis/releases/tag/v3.1.0) or build them from source: [https://github.com/osmosis-labs/osmosis](https://github.com/osmosis-labs/osmosis) - -Verify installation with - -```bash -./osmosisd version -3.1.0 -``` - -After the installation init the config - -```bash -./osmosisd init --chain-id osmosis-1 -``` - -download the genesis - -```bash -wget -O ~/.osmosisd/config/genesis.json https://github.com/osmosis-labs/networks/raw/main/osmosis-1/genesis.json -``` - -Important: Don't include an addrbook.json and make sure persistent_peers and etc. (e.g. unconditional_peer_ids, private_peer_ids -and seeds) are empty for now or else the node will connect to other peers. It should only connect to our peer. - -when the config is done the node can be started - -```bash -./osmosisd start --with-tendermint=false -``` - -After you see that the node is waiting for incoming connections you can open a **new** terminal and start -the sync. - -```bash -ksync start --mode=db --home="/Users//.osmosisd" --pool-id=1 --chain-id=kyve-1 -``` - -You should see KSYNC connecting to Osmosis and applying the blocks against the app. You can exit anytime with CMD+C -if you wish to abort the syncing process. - -When you want to continue to sync normally you can now add an addrbook or add peers in `persistent_peers`. When you start -the node again with the normal start command `./osmosisd start` the node should continue normally and tries to sync the remaining blocks. - -### 3. Sync Cosmos Hub with P2P-SYNC - -Since we want to sync Cosmos Hub from genesis and the genesis file is bigger than 100MB we have to use P2P sync. - -To sync cosmos you have to download and set up the correct gaia binary. To sync from genesis the version `v4.2.1` has -to be used. You can download them [here](https://github.com/cosmos/gaia/releases/tag/v4.2.1) or build them from source: -[https://github.com/cosmos/gaia](https://github.com/cosmos/gaia) - -Verify installation with - -```bash -./gaiad version -4.2.1 -``` - -After the installation init the project - -```bash -./gaiad init --chain-id cosmoshub-4 -``` - -download the genesis - -```bash -wget https://raw.githubusercontent.com/cosmos/mainnet/master/genesis/genesis.cosmoshub-4.json.gz -gzip -d genesis.cosmoshub-4.json.gz -mv genesis.cosmoshub-4.json ~/.gaia/config/genesis.json -``` - -and edit the following in `~/.gaia/config/config.toml`. - -```toml -pex = false -allow_duplicate_ip = true -``` - -Important: Don't include an addrbook.json and make sure persistent_peers and etc. (e.g. unconditional_peer_ids, private_peer_ids -and seeds) are empty for now or else the node will connect to other peers. It should only connect to our peer. - -When the config is done the node can be started. - -:::info -This can take a while (~5mins) since the genesis file is -quite big. You can skip invariants checks to boot even faster, but it still takes a long time until the gaia node starts. - -```bash -./gaiad start --x-crisis-skip-assert-invariants -``` - -::: - -After you see that the node is searching for peers you can start the tool. For testing KYVE has archived the first -5000 blocks of Cosmos Hub, so after that height is reached the sync will be done. - -```bash -ksync start --mode=p2p --home="/Users//.gaia" --pool-id=0 --chain-id=kyve-1 -``` - -You should see the peer connecting and sending over blocks to the gaia node. After all the blocks have been applied -the tool shows _Done_ and you can safely exit the process with CMD+C. - -When you want to continue to sync normally you can now add an addrbook or add peers in `persistent_peers`. -When you start the node again the node should continue normally and tries to sync the remaining blocks. diff --git a/docs/tools/KSYNC/installation.md b/docs/tools/KSYNC/installation.md index 4f45cdb..943c285 100644 --- a/docs/tools/KSYNC/installation.md +++ b/docs/tools/KSYNC/installation.md @@ -4,6 +4,8 @@ sidebar_position: 1 # Installation +## Install with Go (recommended) + To install the latest version of `ksync`, run the following command: ```bash @@ -13,10 +15,12 @@ go install github.com/KYVENetwork/ksync/cmd/ksync@latest To install a previous version, you can specify the version. ```bash -go install github.com/KYVENetwork/ksync/cmd/ksync@v0.1.0 +go install github.com/KYVENetwork/ksync/cmd/ksync@v0.5.0 ``` -Run `ksync version` to check the ksync version. +Run `ksync version` to verify the installation. + +## Install from source You can also install from source by pulling the ksync repository and switching to the correct version and building as follows: @@ -28,9 +32,9 @@ git checkout tags/vx.x.x -b vx.x.x make ksync ``` -This will build ksync in `/build` directory. Afterwards you may want to put it into your machine's PATH like +This will build ksync in `/build` directory. Afterwards, you may want to put it into your machine's PATH like as follows: ```bash cp build/ksync ~/go/bin/ksync -``` +``` \ No newline at end of file diff --git a/docs/tools/KSYNC/overview.md b/docs/tools/KSYNC/overview.md index 4c1d29a..8f56245 100644 --- a/docs/tools/KSYNC/overview.md +++ b/docs/tools/KSYNC/overview.md @@ -4,9 +4,16 @@ sidebar_position: 0 # Overview +### Rapidly sync validated blocks and snapshots from KYVE to every Tendermint based Blockchain Application. + ## What is KSYNC? -Since KYVE is validating and archiving blocks from several blockchains permanently this data can be used to bootstrap nodes. This is especially helpful since most nodes today are pruning nodes and therefore finding peers which have the requested blocks becomes harder each day. With KSYNC nodes can retrieve the data from KYVE and directly feed the blocks into every Tendermint based Blockchain Application in order to sync blocks and join the network. +Since KYVE is validating and archiving blocks and state-sync snapshots from several blockchains permanently this data can be +used to bootstrap nodes. This is especially helpful since most nodes today are pruning nodes and therefore +finding peers which have the requested blocks becomes harder each day. With KSYNC nodes can retrieve +the data from KYVE and directly feed the blocks into every Tendermint based Blockchain Application in order +to sync blocks and join the network. Furthermore, any Tendermint based application can rapidly join the network by +applying state-sync snapshots which are permanently archived on Arweave. :::info You can find the source code and additional docs in the GitHub repository [here](https://github.com/KYVENetwork/ksync). @@ -14,6 +21,19 @@ You can find the source code and additional docs in the GitHub repository [here] ## How does it work? -KSYNC comes with three sync modes which can be applied depending on the type of application. There is DB-SYNC which syncs blocks by directly communicating with the app and writing the data directly to the database and then there P2P-SYNC where KSYNC mocks a peer in the network which has all the required blocks, streaming them over the dedicated block channels over to the node. +KSYNC basically replaces the inbuilt tendermint process and communicates with the app directly over the Tendermint +Socket Protocol (TSP) with the [ABCI](https://github.com/tendermint/spec/blob/master/spec/abci/abci.md) interface. +Once KSYNC has retrieved the requested blocks for the application from a permanent storage provider like Arweave it +executes them against the app and stores all relevant information in the blockstore and state.db databases directly. The +same applies to _state-sync_ snapshots, where KSYNC offers the snapshots over the ABCI methods against the app. + +After a node has been successfully synced with KSYNC the node simply can fetch remaining blocks and switch to live mode +like it would have if synced normally. This makes operating nodes way cheaper and even may make archival nodes +obsolete since blocks archived by KYVE can then be safely dropped in the nodes and synced again once needed +with this tool. + +Overview of how KSYNC interacts with the tendermint application: -After a node has been successfully synced with KSYNC the node simply can fetch remaining blocks and switch to live mode like it would have if synced normally. This makes operating nodes way cheaper and even may make archival nodes obsolete since blocks archived by KYVE can then be safely dropped in the nodes and synced again once needed with this tool. +

+ +

\ No newline at end of file diff --git a/docs/tools/KSYNC/protocol_validators.md b/docs/tools/KSYNC/protocol_validators.md new file mode 100644 index 0000000..9672a09 --- /dev/null +++ b/docs/tools/KSYNC/protocol_validators.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 3 +--- + +# For KYVE Protocol Validators +This section includes all commands used by KYVE Protocol Validators to participate in _state-sync_ data pools. + +## SERVE-SNAPSHOTS + +This command is essential for running as a protocol node in a _state-sync_ pool since this will serve the snapshots to the +protocol node. Basically, KSYNC will sync the blocks with _block-sync_ and waits for the ABCI app to create the snapshots, +once created they are exposed over a REST API server which the protocol node can then query. + +To start with default settings serve the snapshots with: + +```bash +ksync serve-snapshots --binary="/path/to/" --home="/path/to/." --snapshot-pool-id= --block-pool-id= +``` + +Once you see that KSYNC is syncing blocks you can open `https://localhost:7878/list_snapshots`. In the beginning it should +return an empty array, but after the first snapshot height is reached (check the interval in the data pool settings) you +should see a first snapshot object in the response. + +### Changing snapshot api server port + +You can change the snapshot api server port with the flag `--snapshot-port=` + +### Enabling metrics server and manage port + +You can enable a metrics server running by default on `http://localhost:8080/metrics` by add the flag `--metrics`. +Furthermore, can you change the port of the metrics server by adding the flag `--metrics-port=` + +### Manage pruning + +By default, pruning is enabled. That means that all blocks, states and snapshots prior to the snapshot pool height +are automatically, deleted, saving a lot of disk space. If you want to disable it add the flag `--pruning=false` + diff --git a/docs/tools/KSYNC/settings.md b/docs/tools/KSYNC/settings.md new file mode 100644 index 0000000..5d5a253 --- /dev/null +++ b/docs/tools/KSYNC/settings.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 4 +--- + +# Settings + +## Backups + +Even with the right setup and careful maintenance, it's possible to encounter app-hash errors or other unexpected problems that can lead to node collisions and resyncs from Genesis. Especially when you're dealing with syncing an archival node, it's a good idea to create periodic backups of the node's data. + +KSYNC offers precisely this option for creating backups. There are two different methods to utilize this: + +### 1. BLOCK-SYNC-Backups + +With _block-sync_, nodes can be synced by KSYNC from any height up to the latest height available by the storage pool. +Backups can be created automatically at an interval, with the following parameters: + +```bash +--home string 'home directory of the node (e.g. ~/.osmosisd)' +--backup-interval int 'block interval to write backups of data directory (set 0 to disable backups)' +--backup-keep-recent int 'number of latest backups to be keep (0 to keep all backups)' +--backup-compression string 'compression type used for backups ("tar.gz","zip"), if not compression given the backup will be stored uncompressed' +--backup-dest string 'path where backups should be stored [default = ~/.ksync/backups]' +``` + +When the specified `backup-interval` is reached (`height % backup-interval = 0`), KSYNC temporarily pauses the sync process and creates a backup. +These backups are duplicates of the node's data directory (e.g. `~/.osmosisd/data`). If compression is enabled (e.g. using `--backup-compression="tar.gz"`), the backup is compressed and the original uncompressed version is deleted after successful compression in a parallel process. + +#### Usage + +Because backups are disabled by default, it's only required to set ``backup-interval``, whereas the other flags are optional. +Since the creation of a backup takes steadily longer as the data size grows, it is recommended to choose an interval of more than `20000` blocks. + +Example command to run _block-sync_ with compressed backups: +```bash +ksync block-sync --binary="/path/to/" --home="/path/to/." --block-pool-id= --target-height= + --backup-interval=50000 --backup-compression="tar.gz" +``` + +### 2. Backup-Command + +The backup functionality can of course also be used with a standalone command. In this case everything runs in one process +where the following flags can be used: + +```bash +--home string 'home directory of the node (e.g. ~/.osmosisd)' +--backup-keep-recent int 'number of latest backups to be keep (0 to keep all backups)' +--backup-compression string 'compression type used for backups ("tar.gz","zip"), if not compression given the backup will be stored uncompressed' +--backup-dest string 'path where backups should be stored [default = ~/.ksync/backups]' +``` + +#### Usage + +```bash +ksync backup --home="/Users/christopher/.osmosisd" --compression="tar.gz" +``` + +## Overwrite default endpoints + +KSYNC retrieves data from different sources, including a KYVE chain and a storage provider endpoint. Depending on the specified `chain-id`, the default KYVE **chain endpoints** are: + +- **Mainnet (`kyve-1`)**: https://api-eu-1.kyve.network +- **Testnet (`kaon-1`)**: https://api-eu-1.kaon.kyve.network +- **Devnet (`korellia`)**: https://api.korellia.kyve.network + +Whereas the default **storage provider endpoints** are: +- **Arweave (`1`)**: https://arweave.net +- **Bundlr (`2`)**: https://arweave.net +- **KYVE Storage Provider (`3`)**: https://storage.kyve.network _(shouldn't be overwritten)_ + +For several reasons, you can overwrite the default endpoints with your preferred ones. For this purpose, only add the following flags to all commands that are using the listed endpoints: + +```bash +--chain-rest string overwrite KYVE chain rest endpoint +--storage-rest string overwrite storage provider rest endpoint +``` + +### Example + +Use the KYVE chain US endpoint to _block_sync_ your Osmosis node: + +```bash +ksync block-sync --chain-rest="https://api-us-1.kyve.network" --binary="/Users/alice/osmosisd" --home="/Users/alice/.osmosisd" --block-pool-id=1 --target-height=42000 +``` + +## Metrics + +You can enable useful metrics through the `--metrics` flag for all syncing commands. By default, it's exposed on ``http://localhost:8080/metrics`` and you can specify a custom port with ``--metrics-port``. + +The exposed metrics include the following information: + +```json +{ + "latest_block_hash": "A6C59D5F7487B95B32B71EB97F8FE0EE7BE7B512044FC53B6C4A706594167AF9", + "latest_app_hash": "6BF3787314EC5C1B8FF08334193A31EF562CFE6700C3E6B604C31FD053F7FAF4", + "latest_block_height": "180", + "latest_block_time": "2021-06-18T22:03:40.861352885Z", + "earliest_block_hash": "C8DC787FAAE0941EF05C75C3AECCF04B85DFB1D4A8D054A463F323B0D9459719", + "earliest_app_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", + "earliest_block_height": "1", + "earliest_block_time": "2021-06-18T17:00:00Z", + "catching_up": true +} +``` \ No newline at end of file diff --git a/docs/tools/KSYNC/usage.md b/docs/tools/KSYNC/usage.md index c4c2b9f..9457b64 100644 --- a/docs/tools/KSYNC/usage.md +++ b/docs/tools/KSYNC/usage.md @@ -4,190 +4,132 @@ sidebar_position: 2 # Usage -Depending on the blockchain application you are trying to sync the following sync modes can be used. +Depending on what you want to achieve with KSYNC there are three sync modes available. A quick summary of what they do +and when to use them can be found below: -Whichever sync mode you're using, you still have to make sure that the blocks for your node are actually available. -You can check out available storage pools for every KYVE network below: - -- **KYVE (Mainnet)**: https://app.kyve.network/#/pools -- **Kaon (Testnet)**: https://app.kaon.kyve.network/#/pools -- **Korellia (Devent)**: https://app.korellia.kyve.network/#/pools +| | Description | Recommendation | +|---------------------------------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| [**BLOCK-SYNC**](#block-sync) | Syncs blocks from the node's current height up to a specified target height. | Generally recommended for archival node runners, who want to have a full node containing all blocks. | +| [**STATE-SYNC**](#state-sync) | Applies a state-sync snapshot to the node. After the snapshot is applied, the node can continue block-syncing from the applied snapshot height. | Generally recommended for new node runners, who want to join a network in minutes without wanting to sync the entire blockchain. | +| [**HEIGHT-SYNC**](#height-sync) | Finds the quickest way out of state-sync and height-sync to get to the specified target height. | Generally recommended for users who want to check out a historical state within minutes at the specified target height for analysis. | ### Limitations -If you want to sync a node from genesis and the genesis file is bigger than 100MB you have to use P2P because of a -message size limitation in the Tendermint Socket Protocol (TSP). - -Currently, P2P-SYNC is only supported for nodes using `github.com/tendermint/tendermint`. If nodes use CometBFT, DB-SYNC -has to be used. CometBFT support will be added in the future. +Because KSYNC uses the blocks and snapshots archived by the KYVE storage pools you first have to check if those pools +are available in the first place for your desired chain and block height. -:::info -[AUTO-SYNC](#auto-sync) wil manage the P2P or DB decision on its own. -::: +Depending on the KYVE network, you can find all available data pools here: -### AUTO-SYNC +- **Mainnet (KYVE)**: https://app.kyve.network/#/pools +- **Testnet (Kaon)**: https://app.kaon.kyve.network/#/pools +- **Devnet (Korellia)**: https://app.korellia.kyve.network/#/pools -Due to the 100MB limitation, [P2P-SYNC](#p2p-sync) was implemented to support KSYNC for any type of Tendermint blockchain. -However, in comparison to [DB-SYNC](#db-sync) it has some disadvantages, which is why it's recommended to use P2P-Sync only as long as the first block was synced successfully before switching back to DB-SYNC. -On top of that, you need to run the node to be synced and KSYNC in two different terminals, which isn't that comfortable for developers. -AUTO-SYNC consists of a process manager, running P2P-Sync or DB-Sync on the one hand and the node to be synced on the other hand. -Based on the requirements, the process manager will manage which syncing process is required, thereby enabling the best way of syncing the node with the validated blocks. -If the node is completely synced with the corresponding KYVE pool, it will start normally to find peers through the provided seeds. -This resolves in the ability to sync a node completely with KYVE data requiring just one command. +Depending on the sync mode you use, the data pools need to run on the following runtimes: -#### AUTO-SYNC requirements +- **block-sync**: `@kyvejs/tendermint` or `@kyvejs/tendermint-bsync` +- **state-sync**: `@kyvejs/tendermint-ssync` +- **height-sync**: `@kyvejs/tendermint` or `@kyvejs/tendermint-bsync` and `@kyvejs/tendermint-ssync` -The requirements are similar to the [DB-SYNC requirements](#db-requirements). Everything else will be set up automatically. +## BLOCK-SYNC -#### Sync node with AUTO-SYNC +### Syncing to latest available height -To start the syncing process, simply run +Depending on your current node height (can be also 0 if you start syncing from genesis) you can sync up to the latest +height available by the storage pool. KSYNC will automatically exit once that height is reached. -````bash -ksync start --home="/Users//." --daemon-path="/Users//" --pool-id= --chain-id= --seeds -```` - -:::info -Since AUTO-SYNC is the default syncing mode you don't have to specify with a flag. -::: +```bash +ksync block-sync --binary="/path/to/" --home="/path/to/." --block-pool-id= +``` -### P2P-SYNC +### Syncing to specified target height -In this sync mode this tool mocks a peer which has all the blocks the actual peer node needs. The -blocks are then streamed over the dedicated block channels and storing them is handled by the node itself. +Depending on your current node height (can be also 0 if you start syncing from genesis) you can sync up to your desired +target height. KSYNC will automatically exit once that height is reached. -

- -

+```bash +ksync block-sync --binary="/path/to/" --home="/path/to/." --block-pool-id= --target-height= +``` -#### P2P Requirements +### Example -It does not matter if you want to sync a node from genesis or from an existing height, the following settings have -to be changed in order to run p2p sync. +Use _block-sync_ to sync your Osmosis node with validated KYVE data to height ``42,000``: -Make sure that `persistent_peers` are empty in the `config.toml` config file: +To _block-sync_ Osmosis you have to download and set up the correct Osmosis binary. To sync from genesis the version `v3.1.0` has +to be used. You can download them [here](https://github.com/osmosis-labs/osmosis/releases/tag/v3.1.0) or build them from source: [https://github.com/osmosis-labs/osmosis](https://github.com/osmosis-labs/osmosis) -`~/./config/config.toml` -```toml -[p2p] +Verify installation with: -persistent_peers = "" +```bash +./osmosisd version +3.1.0 ``` -Make sure that your `addrbook.json` is empty or delete it entirely: +After the installation, init the config: ```bash -rm ~/./config/addrbook.json +./osmosisd init --chain-id osmosis-1 ``` -And finally make the following settings: - -`~/./config/config.toml` -```toml -[p2p] - -pex = false +Download the genesis: -allow_duplicate_ip = true +```bash +wget -O ~/.osmosisd/config/genesis.json https://github.com/osmosis-labs/networks/raw/main/osmosis-1/genesis.json ``` -#### Sync node with P2P - -Now you can start your node simply with the `start` command like you would start the node normally. +Now that the binary is properly installed, KSYNC can already be started: ```bash -./ start +ksync block-sync --binary="/Users/alice/osmosisd" --home="/Users/alice/.osmosisd" --block-pool-id=1 --target-height=42000 ``` -When you see that the node is trying to search for peers but is unable to find any you can start KSYNC. +## STATE-SYNC -:::caution -If the node actually finds peers the configuration is wrong, in this case double-check the settings -above. -::: +### Syncing to latest available snapshot height -You can then start KSYNC in a **new** terminal with the following command. Please make sure to replace `` and -`` with your specific values. This of course is also true for `` and ``. +You can _state-sync_ a node if it has no height (either node has to be just initialized or reset with `ksync unsafe-reset-all`) +to the latest available snapshot archived by the pool with the following command. If the storage pool has synced with the live +height this can be used to rapidly join this network. ```bash -ksync start mode=p2p --home="/Users//." --pool-id= --chain-id= +ksync state-sync --binary="/path/to/" --home="/path/to/." --snapshot-pool-id= ``` -Available chain ids are `kyve-1` for Mainnet, `kaon-1` for Kaon Testnet and `korellia` for Korellia Devnet - -:::info -If you want to use your own rest endpoint for syncing, because you are running your own KYVE node -for example or want to use a different geolocated endpoint, simply overwrite it by adding the `--rest-endpoint=https://api-us-1.kyve.network` -::: +### Syncing to specified snapshot height -Once KSYNC starts it automatically continues from the latest height found in the node and starts downloading -the blocks from the storage provider and validates the checksum. You should see blocks streaming over and the node -committing those blocks. If you run this command without a `--target-height` it will sync all blocks which are -available in the pool. You can simply exit the sync process by killing KSYNC with CMD+C. +You can _state-sync_ a node if it has no height (either node has to be just initialized or reset with `ksync unsafe-reset-all`) +to your desired target height. The target height has to be the exact height of the archived snapshot. If the specified +height can not be found it prints out the nearest available snapshot height you can use. -### DB-SYNC - -In this sync mode this tool mocks the tendermint process which communicates directly with the -blockchain application over ABCI and replays the blocks against the app and manually writes the results -to the DB directly. - -

- -

- -#### DB Requirements +```bash +ksync state-sync --binary="/path/to/" --home="/path/to/." --snapshot-pool-id= --target-height= +``` -It does not matter if you want to sync a node from genesis or from an existing height, the following settings have -to be changed in order to run DB sync. +### Example -Make sure that `persistent_peers` are empty in the `config.toml` config file: +Will be added when the Archway State-Sync pool on Kaon is live. -`~/./config/config.toml` -```toml -[p2p] +## HEIGHT-SYNC -persistent_peers = "" -``` +### Syncing to latest available block height -Make sure that your `addrbook.json` is empty or delete it entirely: +You can _height-sync_ a node if it has no height (either node has to be just initialized or reset with `ksync unsafe-reset-all`) +to the latest available height. This is especially useful for joining a new network if the user wants to join as quick as +possible. ```bash -rm ~/./config/addrbook.json +ksync height-sync --binary="/path/to/" --home="/path/to/." --snapshot-pool-id= --block-pool-id= ``` -Make sure that `proxy_app` and `abci` have the following default values in the `config.toml` config file: +### Syncing to specified target height -`~/./config/config.toml` -```toml -####################################################################### -### Main Base Config Options ### -####################################################################### - -proxy_app = "tcp://127.0.0.1:26658" -abci = "socket" -``` - -#### Sync node with DB - -Now you can start your node with a special flag, so it does not start with tendermint as an embedded process: +You can _height-sync_ a node if it has no height (either node has to be just initialized or reset with `ksync unsafe-reset-all`) +to your desired target height. The target height can be any height (but the block data pool must have archived it), then +it will use available _state-sync_ snapshots and _block-sync_ to get to the target height as quickly as possible ```bash -./ start --with-tendermint=false +ksync height-sync --binary="/path/to/" --home="/path/to/." --snapshot-pool-id= --block-pool-id= --target-height= ``` -If you see that the abci server is waiting for new connections you can proceed with starting KSYNC in a **new** -terminal with the following command. Please make sure to replace `` and -`` with your specific values. This of course is also true for `` and ``. - -Available chain ids are `kyve-1` for Mainnet, `kaon-1` for Kaon Testnet and `korellia` for Korellia Devnet - -:::info -If you want to use your own rest endpoint for syncing, because you are running your own KYVE node -for example or want to use a different geolocated endpoint, simply overwrite it by adding the `--rest-endpoint=https://api-us-1.kyve.network` -::: +### Example -Once KSYNC starts it automatically continues from the latest height found in the node and starts downloading -the blocks from the storage provider and validates the checksum. You should KSYNC committing blocks against the app. -If you run this command without a `--target-height` it will sync all blocks which are -available in the pool. KSYNC will automatically exit once a target height is reached, or you can simply exit the sync -process by killing KSYNC with CMD+C. \ No newline at end of file +Will be added when the Archway State-Sync pool on Kaon is live. \ No newline at end of file diff --git a/docs/validators/protocol_nodes/pools/archway/introduction.md b/docs/validators/protocol_nodes/pools/archway/introduction.md index b65739c..e61d4cb 100644 --- a/docs/validators/protocol_nodes/pools/archway/introduction.md +++ b/docs/validators/protocol_nodes/pools/archway/introduction.md @@ -7,10 +7,6 @@ sidebar_position: 1 This data pool validates and archives all blocks and block results from Archway and makes them permanently available with Arweave and Bundlr. -:::info -**INFO**: The Archway pool is currently **not** live on Mainnet, only on Kaon and Korellia. -::: - ## Overview - **Runtime**: @kyvejs/tendermint @@ -25,7 +21,7 @@ available with Arweave and Bundlr. - 4 or more physical CPU cores - 32 GB RAM - 1 TB DISK - - 50mbps network bandwidth + - 100mbps network bandwidth ## General Setup diff --git a/docs/validators/protocol_nodes/pools/archway/upgrade.md b/docs/validators/protocol_nodes/pools/archway/upgrade.md index 358f98a..8f04174 100644 --- a/docs/validators/protocol_nodes/pools/archway/upgrade.md +++ b/docs/validators/protocol_nodes/pools/archway/upgrade.md @@ -82,7 +82,6 @@ To make sure the installation was successful you can print the version which sho .kysor/upgrades/pool-0/1.0.0-beta.1/bin/kyve-macos-x64 version ``` -TODO ```bash @kyvejs/tendermint version: 1.0.0-beta.0 @kyvejs/protocol version: 1.0.0-beta.24 @@ -106,8 +105,6 @@ if you have installed the correct version by executing the version command. ./kyve-macos-x64 version ``` -TODO - ```bash @kyvejs/tendermint version: 1.0.0-beta.1 @kyvejs/protocol version: 1.0.0-beta.24 diff --git a/docs/validators/protocol_nodes/pools/archway_state-sync/_category_.json b/docs/validators/protocol_nodes/pools/archway_state-sync/_category_.json new file mode 100644 index 0000000..bf126cf --- /dev/null +++ b/docs/validators/protocol_nodes/pools/archway_state-sync/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Archway // State-Sync", + "position": 4, + "link": null +} diff --git a/docs/validators/protocol_nodes/pools/archway_state-sync/installation.md b/docs/validators/protocol_nodes/pools/archway_state-sync/installation.md new file mode 100644 index 0000000..8f1c902 --- /dev/null +++ b/docs/validators/protocol_nodes/pools/archway_state-sync/installation.md @@ -0,0 +1,363 @@ +--- +sidebar_position: 4 +--- + +# Installation + +This section will deal with the installation for the KYVE protocol validator. + +## Install KYVE protocol validator + +### Install KYSOR + +Get the latest release of the KYSOR binaries [here](https://github.com/KYVENetwork/kyvejs/releases?q=kysor&expanded=true) + +Once you have the latest version for you operating system simply +pull them down: + +```bash +wget https://github.com/KYVENetwork/kyvejs/releases/download/%40kyve%2Fkysor%401.0.0-/kysor-linux-x64.zip +unzip kysor-linux-x64.zip +mv kysor-linux-x64 kysor +chmod 700 kysor +``` + +To verify that the KYSOR runs successfully just run + +```bash +./kysor version +``` + +### Initialize KYSOR + +After the successful installation of KYSOR it now needs to be initialized. Depending on the network you want to join a different +configuration needs to be passed to the init options. + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +Official Mainnet endpoints: + +```bash +EU RPC: 'https://rpc-eu-1.kyve.network' +EU API: 'https://api-eu-1.kyve.network' + +US RPC: 'https://rpc-us-1.kyve.network' +US API: 'https://api-us-1.kyve.network' +``` + +Depending on your geolocation certain endpoints can be used as a primary and secondary endpoints. +Primary endpoints are used by default, secondary ones only when the primary fails and so on. It is also possible +to only use one or more than two. It is important that the number of endpoints used for rpc and api are equal. + +```bash +./kysor init \ +--chain-id 'kyve-1' \ +--rpc ',,...' \ +--rest ',,...' +``` + + + + +Official Kaon endpoints: + +```bash +EU RPC: 'https://rpc-eu-1.kaon.kyve.network' +EU API: 'https://api-eu-1.kaon.kyve.network' + +US RPC: 'https://rpc-us-1.kaon.kyve.network' +US API: 'https://api-us-1.kaon.kyve.network' +``` + +Depending on your geolocation certain endpoints can be used as a primary and secondary endpoints. +Primary endpoints are used by default, secondary ones only when the primary fails and so on. It is also possible +to only use one or more than two. It is important that the number of endpoints used for rpc and api are equal. + +```bash +./kysor init \ +--chain-id 'kaon-1' \ +--rpc ',,...' \ +--rest ',,...' +``` + + + + +```bash +./kysor init \ +--chain-id 'korellia' \ +--rpc 'https://rpc-eu-1.korellia.kyve.network' \ +--rest 'https://api-eu-1.korellia.kyve.network' \ +--auto-download-binaries +``` + + + + +Once you have initialized KYSOR you can verify the successful initialization by printing out the home directory: + +```bash +ls ~/.kysor +``` + +There should be a `config.toml` file where the configurations you just defined are saved. You can change those at any time if you want. + +### Create the 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. A new valaccount with a new mnemonic can be created in the following way: + + + + +```bash +./kysor valaccounts create \ +--name 'archway-ssync' \ +--pool 4 \ +--storage-priv "$(cat path/to/arweave.json)" \ +--metrics +``` + +This will create a `archway.toml` file under the KYSOR home directory in `~/.kysor/valaccounts/` where all the other valaccounts are stored. 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: + +```bash +./kysor valaccounts create \ +--name archway-ssync \ +--pool 4 \ +--storage-priv "$(cat path/to/arweave.json)" \ +--metrics \ +--recover +``` + +This 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` + + + + +```bash +./kysor valaccounts create \ +--name 'archway-ssync' \ +--pool 4 \ +--storage-priv "$(cat path/to/arweave.json)" \ +--metrics +``` + +This will create a `archway.toml` file under the KYSOR home directory in `~/.kysor/valaccounts/` where all the other valaccounts are stored. 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: + +```bash +./kysor valaccounts create \ +--name archway-ssync \ +--pool 4 \ +--storage-priv "$(cat path/to/arweave.json)" \ +--metrics \ +--recover +``` + +This 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` + + + + +```bash +./kysor valaccounts create \ +--name 'archway-ssync' \ +--pool 34 \ +--storage-priv "$(cat path/to/arweave.json)" \ +--metrics +``` + +This will create a `archway.toml` file under the KYSOR home directory in `~/.kysor/valaccounts/` where all the other valaccounts are stored. 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: + +```bash +./kysor valaccounts create \ +--name archway-ssync \ +--pool 34 \ +--storage-priv "$(cat path/to/arweave.json)" \ +--metrics \ +--recover +``` + +This 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` + + + + +:::danger +**ATTENTION**: Since the valaccount config files store the valaccount's mnemonic and the wallet keyfile for the storage provider you should **never** share this file with anyone. +::: + +Loosing the mnemonic of the valaccount can cause a timeout slash. If a third party ever gets hold of the mnemonic an upload slash can be the worst case since they have control over the vote and upload behaviour of the node. Loosing the private keyfile of the storage provider means loosing your funds. + +### Install Pool Binaries + +In the last step of the installation process of KYSOR the actual pool runtime +binaries need to be installed in KYSOR. + +#### General KYSOR Directory Structure + +Knowing where KYSOR saves it's 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 + ├── cosmoshub.toml + └── osmosis.toml + └── archway.toml +``` + +Here the following directories have the following reason: + +- `.kysor` - KYSOR home directory, created with init command +- `config.toml` - general KYSOR config, created with init command +- `logs` - logs folder containing KYSOR log files. Each log file is a run from start to end where the date is the starting date +- `upgrades` - most important directory, contains all the binaries for every pool +- `upgrades/pool-$id` - holds every binary of every installed version of the specified pool +- `upgrades/pool-$id/$version` - acts as a home directory for a specific binary, contains binary cache, logs and actual protocol validator binary +- `upgrades/pool-$id/$version/bin` - holds actual node binary +- `upgrades/pool-$id/$version/cache` - contains cached data relevant for the protocol validator +- `upgrades/pool-$id/$version/logs` - logs folder for the protocol validator of that version and pool. Each log file is a run from start to end where the date is the starting date +- `valaccounts` - contains all the valaccount config files with which the KYSOR can run on a pool + +#### Binary Installation + +If you run with KYSOR and have auto download enabled (which is not recommended for Mainnet and Kaon) you can skip the manual binary installation. If you want to run the binaries with or without KYSOR you have to install them manually. + +Depending on the runtime the binary installation differs. For Archway we have to install the binary from the +@kyvejs/tendermint runtime. + +#### Build from source + +The first option to install the binary is to build it from source. For that you have to execute the following +commands: + +```bash +git clone git@github.com:KYVENetwork/kyvejs.git +cd kyvejs +``` + +If you want to build a specific version you can checkout the tag and continue from the version branch. +If you want to build the latest version you can skip this step. + +```bash +git checkout tags/@kyvejs/tendermint-ssync@x.x.x -b x.x.x +``` + +After you have cloned the project and have the desired version the dependencies can be installed and the project build: + +```bash +yarn install +yarn setup +``` + +Finally, you can build the runtime binaries. + +**INFO**: During the binary build log warnings can occur. You can safely ignore them. + +```bash +cd integrations/tendermint-ssync +yarn build:binaries +``` + +You can verify the installation with printing the version: + +```bash +./out/kyve-linux-x64 version +``` + +After the build succeeded you can find the binaries in the `out` folder where you can move them to use +desired location (like KYSOR). + +Move binary to KYSOR + +```bash +mv ./out/kyve-linux-x64 ~/.kysor/upgrades/pool-//bin/ +``` + +#### Download prebuilt binary + +You can find all prebuilt binaries in the releases of the kyvejs repository. For this specific runtime they +can be found [here](https://github.com/KYVENetwork/kyvejs/releases?q=tendermint). + +You can verify the installation with printing the version: + +```bash +./kyve-linux-64 version +``` + +Once you have downloaded the binary for the correct platform and version you can simply unzip them and move them +to your desired location (like KYSOR). + +After you have installed the binary you can proceed to move it to the correct location so KYSOR can use it: + +```bash +mkdir -p ~/.kysor/upgrades/pool-//bin +``` + +```bash +cd ~/.kysor/upgrades/pool-//bin +``` + +```bash +wget https://github.com/KYVENetwork/kyvejs/releases/download/%40kyvejs%2F%40/kyve-linux-x64.zip +``` + +```bash +unzip kyve-linux-x64.zip +``` + +```bash +rm kyve-linux-x64.zip +``` + +To verify the version and the runtime of the binary simply call the version command: + +```bash +./kyve-linux-x64 version +``` + +Move binary to KYSOR + +```bash +mv ./out/kyve-linux-x64 ~/.kysor/upgrades/pool-//bin/ +``` diff --git a/docs/validators/protocol_nodes/pools/archway_state-sync/introduction.md b/docs/validators/protocol_nodes/pools/archway_state-sync/introduction.md new file mode 100644 index 0000000..59125a0 --- /dev/null +++ b/docs/validators/protocol_nodes/pools/archway_state-sync/introduction.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 1 +--- + +# Introduction + +This data pool validates and archives state-sync snapshots from Archway and makes them permanently +available with Arweave and Bundlr. + +## Overview + +- **Runtime**: @kyvejs/tendermint-ssync +- **Data Source**: Self hosted KSYNC/Archway node +- **Data**: Snapshot every 3,000 blocks from Genesis ongoing +- **Storage Provider**: Bundlr +- **Networks** + - [Mainnet](https://app.kyve.network/#/pools/4) (Pool Id: 4) + - [Kaon](https://app.kaon.kyve.network/#/pools/4) (Pool Id: 4) + - [Korellia](https://app.korellia.kyve.network/#/pools/34) (Pool Id: 34) +- **Min Hardware Requirements** + - 4 or more physical CPU cores + - 32 GB RAM + - 150 GB DISK + - 100mbps network bandwidth + +## General Setup + +If you want to participate in the Archway // State-Sync pool you will have to run KSYNC with a set up Archway node which will act as the +data source for the KYVE protocol validator. + +This is required because KSYNC enables the requesting of deterministic state-sync snapshots in order to validate +and archive them. Therefore, KSYNC is using already validated Archway data of the [Archway Mainnet pool](https://app.kyve.network/#/pools/2) +to feed the node with blocks and serves the created snapshots through an implemented server. With that setup, a user who wants to join this pool first has to sync +his Archway node with KSYNC to the current height of the latest created snapshot and then start the +actual KYVE protocol validator. + +This architecture diagram summarizes the setup of the Archway // State-Sync integration on KYVE: + +

+ +

+ +Here, the tendermint-ssync runtime is responsible for communicating with the tendermint application (purple) - in this case KSYNC, and forwarding the data to the KYVE core protocol. The KYVE core then handles the communication with the pool. This entire process (yellow) is the KYVE protocol validator. The resulting +data are the state-sync snapshots from the tendermint application - validated and permanently stored on a storage provider like Arweave. + +## Goal + +The goal of this pool is to validate and archive state-sync snapshots from Archway permanently and decentralized. With this +data, we want to make it possible for other nodes to state-sync the data from KYVE, making expensive archival nodes +on Archway obsolete in the long run. More information on how to perform state-sync with KYVE visit the documentation about +KSYNC [here](https://github.com/KYVENetwork/ksync). diff --git a/docs/validators/protocol_nodes/pools/archway_state-sync/requirements.md b/docs/validators/protocol_nodes/pools/archway_state-sync/requirements.md new file mode 100644 index 0000000..32a48d2 --- /dev/null +++ b/docs/validators/protocol_nodes/pools/archway_state-sync/requirements.md @@ -0,0 +1,117 @@ +--- +sidebar_position: 2 +--- + +# Requirements + +Before you can run protocol validators on the Archway // State-Sync pool, there are some basic requirements that have to be met, ranging from simple hardware specs to owning a certain amount of $KYVE and other currencies. + +## Supported OS + +We officially support macOS and Linux in the following architectures: + +- `macos-x64` +- `linux-x64` +- `linux-arm64` + +## Minimum Hardware Requirements + +To run mainnet or testnet protocol validators, you will need a machine with the following minimum hardware requirements: + +- 8 or more physical CPU cores +- At least 150 GB of disk storage +- At least 32 GB of memory (RAM) +- At least 100mbps network bandwidth + +## Pool Delegation Requirements + +### Verify if you have enough $KYVE to participate + +Due to a limited number of validator slots in each pool, only the nodes with the highest delegation can claim +a validator slot. You can only claim a validator slot if you have **more than the minimum delegation amount**. + +To check the minimum delegation amount you can click on the tab `Validators` once you have selected a pool. There you should see something like this: + +![min delegation](/img/min_delegation.png) + +In this case, there are still 45 free validator slots, so you just have to have more than 0 $KYVE of delegation in order to participate. If the slots would be full and the minimum delegation would be, for example, +300 $KYVE, you have to have **more** than 300 $KYVE delegated in your validator. + +:::caution +**IMPORTANT**: If you don't have more $KYVE than the minimum delegation amount, you can not continue +::: + +## Storage Provider Requirements + +Because a data pool is always archiving the data on a web3 storage provider, the protocol validator +must have access to a funded wallet in order to be able to actually upload data to those storage providers. + +Depending on which storage provider the pool runs, on you have to setup a wallet with which you can upload +data with. Currently, there are two available storage providers: + +- [Arweave](https://arweave.org) +- [Bundlr](https://bundlr.network/) + +On the pool overview, it is clearly listed which storage provider a pool uses. + +### Setting up an Arweave Wallet + +Arweave is a truly decentralized, permanent data storage solution. + +In order to setup an Arweave wallet which is also required if you want to setup a Bundlr wallet you need a keyfile which will be the private key of Arweave. +You can generate an Arweave wallet [here](https://arweave.app/). You can exchange $AR on common exchanges. We would recommend an amount of ~1 AR which is more than enough for a few weeks or even months. + +Store the keyfile in a secure location you will need it again later in the installation process. + +### Setting up a Bundlr Wallet + +Bundlr is a layer 2 solution for Arweave, bundling transactions and therefore making it much more scalable +with guaranteed transaction finality. + +In order to setup a Bundlr wallet follow the exact same steps as in **Setting up an Arweave wallet**. After +completing the above steps the easiest way to setup the Bundlr wallet is to install the Bundlr CLI: + +```bash +npm install -g @bundlr-network/client +``` + +In order to fund the Bundlr node simply execute the following, where `arweave.json` is your Arweave keyfile +which holds some funds: + +:::caution +**IMPORTANT**: Always use `https://node1.bundlr.network` as the host to fund your bundlr account since KYVE uses this by default +::: + +```bash +$ bundlr fund 1000000000000 -h https://node1.bundlr.network -w arweave.json -c arweave + +> ? Confirmation: send 1000000000000 Winston to dev.bundlr.network (35jqt51H71Tf4YmZfoGvN9FLw62a4aPnLgZa9KLdwLo)? +> Y / N y +> Funding receipt: +> Amount: 1000000000000 with Fee: 1379016 to 35jqt51H71Tf4YmZfoGvN9FLw62a4aPnLgZa9KLdwLo +> ID: 7cI6jpfpx6A2z8F5AoVHvZn9Az_BWPgvKzBCoE5w07A +``` + +In this example we funded Bundlr with 1 $AR which should be more than enough. After about ~30 minutes +you can view your balance with: + +```bash +$ bundlr balance 35jqt51H71Tf4YmZfoGvN9FLw62a4aPnLgZa9KLdwLo -h https://node1.bundlr.network -c arweave + +> Balance: 1000000000000 Winston (1AR) +``` + +In order to withdraw your funds from Bundlr simply execute: + +```bash +$ bundlr withdraw 500000000000 -h https://node1.bundlr.network -w arweave.json -c arweave + +> ? Confirmation: withdraw 500000000000 winston from node1.bundlr.network (35jqt51H71Tf4YmZfoGvN9FLw62a4aPnLgZa9KLdwLo)? +> Y / N y +> Withdrawal request for 500000000000 winston successful +> Transaction ID: xcmxJmHyNS502fzqiT66rNeIOSldKGDWR8XsL9auDfs with network fee 1379016 for a total cost of 2858032 +``` + +More information about the Bundlr CLI can be found [here](https://docs.bundlr.network/docs/client/cli). + +Store the keyfile in a secure location you will need it again later in the installation process. diff --git a/docs/validators/protocol_nodes/pools/archway_state-sync/run_ksync.md b/docs/validators/protocol_nodes/pools/archway_state-sync/run_ksync.md new file mode 100644 index 0000000..ac245f6 --- /dev/null +++ b/docs/validators/protocol_nodes/pools/archway_state-sync/run_ksync.md @@ -0,0 +1,93 @@ +--- +sidebar_position: 3 +--- + +# Run KSYNC + +KSYNC will provide the snapshot of an Archway Node, which will act as the source for the KYVE protocol validator and is **required**. + +## Install Archway node + +The Archway binary with the version `v1.0.0` has to be installed. You can +- follow the official installation instructions [here](https://docs.archway.io/validators/running-a-node/join-a-network/sync-from-genesis) or +- download the binary directly from [here](https://github.com/archway-network/archway/releases/tag/v1.0.0). + +You can verify the successful installation with + +``` +./archwayd version +1.0.0 +``` + +After the successful installation, you need to set up the archwayd config. First choose a moniker and initialize everything: + +```bash +./archwayd init --chain-id archway-1 +``` + +To download and setup the genesis file execute the following command: + +```bash +wget -qO- https://github.com/archway-network/networks/raw/main/archway-1/genesis/genesis.json.gz | zcat > ~/.archway/config/genesis.json +``` + +## Install KSYNC + +### Install with Go (recommended) + +To install the required version of `ksync`, run the following command: + +```bash +go install github.com/KYVENetwork/ksync/cmd/ksync@v1.0.0-beta.0 +``` + +Run `ksync version` to verify the installation. + +### Install from source + +You can also install from source by pulling the ksync repository and switching to the correct version and building +as follows: + +```bash +git clone git@github.com:KYVENetwork/ksync.git +cd ksync +git checkout tags/v1.0.0-beta.0 -b v1.0.0-beta.0 +make ksync +``` + +This will build ksync in `/build` directory. Afterwards, you may want to put it into your machine's PATH like +as follows: + +```bash +cp build/ksync ~/go/bin/ksync +``` + +## Start KSYNC + +This command is essential for running as a protocol node in a _state-sync_ pool since this will serve the snapshots to the +protocol node. Basically, KSYNC will sync the blocks with _block-sync_ and waits for the ABCI app to create the snapshots, +once created they are exposed over a REST API server which the protocol node can then query. + +To start with default settings serve the snapshots with: + +```bash +ksync serve-snapshots --binary="/path/to/archwayd" --home="/path/to/.archway" --snapshot-pool-id=4--block-pool-id=2 +``` + +Once you see that KSYNC is syncing blocks you can open `https://localhost:7878/list_snapshots`. In the beginning it should +return an empty array, but after the first snapshot height is reached (check the interval in the data pool settings) you +should see a first snapshot object in the response. + +### Changing snapshot api server port + +You can change the snapshot api server port with the flag `--snapshot-port=` + +### Enabling metrics server and manage port + +You can enable a metrics server running by default on `http://localhost:8080/metrics` by add the flag `--metrics`. +Furthermore, can you change the port of the metrics server by adding the flag `--metrics-port=` + +### Manage pruning + +By default, pruning is enabled. That means that all blocks, states and snapshots prior to the snapshot pool height +are automatically, deleted, saving a lot of disk space. If you want to disable it add the flag `--pruning=false` \ No newline at end of file diff --git a/docs/validators/protocol_nodes/pools/archway_state-sync/run_protocol_node.md b/docs/validators/protocol_nodes/pools/archway_state-sync/run_protocol_node.md new file mode 100644 index 0000000..7df2542 --- /dev/null +++ b/docs/validators/protocol_nodes/pools/archway_state-sync/run_protocol_node.md @@ -0,0 +1,119 @@ +--- +sidebar_position: 5 +--- + +# Run a Protocol node + +With KSYNC in place and the KYVE node also installed you can finally start the protocol node. + +## Start Node + +Finally the protocol validator can be started. In order to start it, execute the following command. Since we named our valaccount `archway` we select the this valaccount to start the KYSOR. + +```bash +./kysor start --valaccount 'archway-ssync' +``` + +You can also start the process in debug mode by adding the `--debug` flag like this: + +```bash +./kysor start --valaccount 'archway-ssync' --debug +``` + +After the node successfully started you should see the following logs: + +```log +2023-02-13 08:46:00.618 INFO Starting node ... + +2023-02-13 08:46:00.624 INFO Starting metric server on: http://localhost:8080/metrics +2023-02-13 08:46:00.828 INFO Checking account balance on StorageProvider:Bundlr +2023-02-13 08:46:00.872 INFO Account has available funds on StorageProvider:Bundlr + +2023-02-13 08:46:00.873 INFO Chain ID = kyve-1 +2023-02-13 08:46:00.873 INFO Pool ID = 4 +2023-02-13 08:46:00.873 INFO Runtime = @kyvejs/tendermint-ssync +2023-02-13 08:46:00.873 INFO Valaddress = kyve1887l27uwn5r6u9gxw7dg9wt0kqh7uk23suumzc + +2023-02-13 08:46:00.873 INFO @kyvejs/tendermint-ssync = v1.0.0-beta.1 +2023-02-13 08:46:00.873 INFO @kyvejs/protocol = v1.0.0-beta.14 + +2023-02-13 08:46:00.876 INFO Valaccount has not joined the pool with id 4 yet +2023-02-13 08:46:00.876 INFO Visit https://app.kyve.network and join the pool from your validator account: + +2023-02-13 08:46:00.876 INFO Valaddress: kyve1887l27uwn5r6u9gxw7dg9wt0kqh7uk23suumzc +2023-02-13 08:46:00.876 INFO Valname: causal-chocolate-sparrow + +2023-02-13 08:46:00.876 INFO The node will not continue until the account is authorized +``` + +With this information (`Valaddress` and `Valname`) you can head over the KYVE app and join the pool. + +Now that the node is already running it just needs the authorization from it's main validator account in order to run for this validator and generate rewards. For that visit your validator page and click on `Join existing pool`. + +A dialog should open where you should select the pool you want to join (here Archway). After that enter the valaddress that needs to be authorized and the valname, which just serves as a security that the node has actually been started. (If you join a pool without having the node running you are in danger of receiving a timeout slash because once you join a pool you are expected to validate and upload data). + +For the last option you can do a one time transfer so that the valaccount has some $KYVE to pay for transaction fees. We would recommend sending 100 $KYVE for the start which typically lasts for about 1 month. + +:::caution +**IMPORTANT**: Make sure that the valaccount always has enough $KYVE to pay for transaction fees, otherwise you are again in danger of receiving a timeout slash. +::: + +Once you have joined the pool the node should continue in about ~10 seconds. After that you are successfully participating in a pool. + +## Start node with systemd + +If you want to start the nodes as a background process you can use `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 `archway` + +:::info +You might have to execute this command with `sudo` +::: + +```bash +tee < /dev/null /etc/systemd/system/archwayd.service +[Unit] +Description=KYVE Protocol-Node archway daemon +After=network-online.target + +[Service] +User=$USER +ExecStart=/home/$USER/kysor start --valaccount archway +Restart=on-failure +RestartSec=3 +LimitNOFILE=infinity +EOF +``` + +:::info +Don't forget to change the filename and the valaccount in the service file if you join a different pool +::: + +Start the daemon + +```bash +sudo systemctl enable archway +sudo systemctl start archway +``` + +It can be stopped using + +``` +sudo systemctl stop archway +``` + +You can see its logs with + +``` +sudo journalctl -u archway -f -o cat +``` + +## Start node on multiple pools + +This step is optional, but the more pools you participate in the higher the rewards. If you want to join another pool just repeat the previous steps (Install pool binaries). For that you have to create a new valaccount, because a valaccount can only run on one data pool. Once you have setup the second valaccount you can start it. You can see all the pools you are participating in your validator page. + +:::caution +**WARNING**: Joining for example a second pool might double your rewards, but it also doubles the danger of getting slashed. +::: diff --git a/docs/validators/protocol_nodes/pools/archway_state-sync/upgrade.md b/docs/validators/protocol_nodes/pools/archway_state-sync/upgrade.md new file mode 100644 index 0000000..b3a1a35 --- /dev/null +++ b/docs/validators/protocol_nodes/pools/archway_state-sync/upgrade.md @@ -0,0 +1,118 @@ +--- +sidebar_position: 6 +--- + +# How to upgrade + +Upgrading a protocol node can be difficult, learn here how to prepare and execute an upgrade. + +## Upgrade with KYSOR + +### Autodownload enabled + +If the node is managed by KYSOR and autodownload is **enabled** nothing has to be prepared for the upgrade. KYSOR will automatically +download the new upgrade binary, place it in the correct path and restart the validation process. + +Although this is quite handy it is +**not recommended** for mainnet since node operators should always build the binaries from source to avoid malicious binaries +from being executed. If you run on a testnet like Korellia or Kaon you can safely enable autodownload. + +:::tip +**INFO**: You can enable/disable autodownload in KYSOR's main config file under `~/.kysor/config.toml`: + +```toml +# can be either "true" or "false" +autoDownloadBinaries = true +``` + +::: + +### Autodownload disabled + +If the node is managed by KYSOR and autodownload is **disabled** you have to manually install the binary and place it in under the +correct path **prior** to the update. + +The first step is to check if the upgrade proposal has passed and when it will go into effect. An upgrade proposal can look like this: + +```json +{ + "@type": "/kyve.pool.v1beta1.MsgScheduleRuntimeUpgrade", + "authority": "kyve10d07y265gmmuvt4z0w9aw880jnsr700jdv7nah", + "runtime": "@kyvejs/tendermint-ssync", + "version": "1.0.0-beta.1", + "scheduled_at": "1684749600", + "duration": "600", + "binaries": "{\"kyve-linux-arm64\":\"https://github.com/KYVENetwork/kyvejs/releases/download/%40kyvejs%2Ftendermint%401.0.0-beta.1/kyve-linux-arm64.zip\",\"kyve-linux-x64\":\"https://github.com/KYVENetwork/kyvejs/releases/download/%40kyvejs%2Ftendermint%401.0.0-beta.1/kyve-linux-x64.zip\",\"kyve-macos-x64\":\"https://github.com/KYVENetwork/kyvejs/releases/download/%40kyvejs%2Ftendermint%401.0.0-beta.1/kyve-macos-x64.zip\"}" +} +``` + +Here **every** pool which is running on the _@kyvejs/tendermint-ssync_ runtime gets upgraded with the new version of _1.0.0-beta.1_. The upgrade will go into effect +at the _scheduled_at_ time (UNIX time format). Once the upgrade goes into effect the pool will halt during the upgrade is getting applied. The length of the upgrade +is determined by the _duration_ (here 600 seconds -> 10 mins). The reason behind an upgrade duration where the pool halts is to give node operators some time to perform +the upgrade (restart the node or manually switch out the binaries during that time). After the duration has completed the pool will continue automatically. Finally, the +_binaries_ are important for KYSOR if node operators have autodownload enabled. It points to the prebuilt binaries which can directly be downloaded. + +The next step is to install the new upgrade binary in KYSOR. For that either download the prebuilt binary from the upgrade proposal or build it from source. If you +build from source be sure to checkout the right version. + +:::tip +**INFO**: Checkout the correct version in kyvejs like this: `git checkout tags/@kyvejs/tendermint-ssync@x.x.x -b x.x.x`. More info on building binaries from source can be found [here](/validators/protocol_nodes/pools/archway/installation.md#build-from-source) +::: + +Once you have either downloaded or build the binaries you have to place them in the correct path. For that create the following directories and move the binary there: + +```bash +mkdir -r ~/.kysor/upgrades/pool-0/x.x.x/bin/ +mv kyve-linux-x64 ~/.kysor/upgrades/pool-0/x.x.x/bin/ +``` + +:::caution +**IMPORTANT**: The version _x.x.x_ has to match with the version in the upgrade proposal, so for the example proposal above it would be: + +```bash +mkdir -r ~/.kysor/upgrades/pool-0/1.0.0-beta.1/bin/ +mv kyve-linux-x64 ~/.kysor/upgrades/pool-0/1.0.0-beta.1/bin/ +``` + +::: + +To make sure the installation was successful you can print the version which should match with the version in the path: + +```bash +.kysor/upgrades/pool-0/1.0.0-beta.1/bin/kyve-macos-x64 version +``` + +```bash +@kyvejs/tendermint-ssync version: 1.0.0-beta.0 +@kyvejs/protocol version: 1.0.0-beta.24 +Node version: v18.5.0 + +Platform: linux +Arch: x64 +``` + +After that the installation is ready and when the upgrade is executed KYSOR will automatically restart with the new binary so now nothing has to be prepared anymore. + +## Upgrade without KYSOR + +If you run your node without KYSOR you have to manually switch out the upgrade binary during the upgrade duration. For that the node operator has to be online during the upgrade +to do this. For this reason we recommend running with KYSOR where the upgrade binary can be installed before the upgrade and KYSOR will do this automatically during the upgrade. + +To upgrade the binary has to either be downloaded from the gov proposal or build from source. Both is described in the section above. Once the binary is installed you can double check +if you have installed the correct version by executing the version command. + +```bash +./kyve-macos-x64 version +``` + +```bash +@kyvejs/tendermint-ssync version: 1.0.0-beta.1 +@kyvejs/protocol version: 1.0.0-beta.24 +Node version: v18.5.0 + +Platform: linux +Arch: x64 +``` + +The version of _@kyvejs/tendermint-ssync_ should match with the version in the upgrade proposal. Once the upgrade executed the old binary will automatically stop with an error since +the version upgraded. Now simply restart the process with the new binary and the node will continue to validate bundles once the upgrade duration has passed. diff --git a/docs/validators/protocol_nodes/pools/axelar/_category_.json b/docs/validators/protocol_nodes/pools/axelar/_category_.json index e7581c4..53f00b3 100644 --- a/docs/validators/protocol_nodes/pools/axelar/_category_.json +++ b/docs/validators/protocol_nodes/pools/axelar/_category_.json @@ -1,5 +1,5 @@ { "label": "Axelar", - "position": 4, + "position": 5, "link": null } diff --git a/static/img/tendermint-ssync-archway.png b/static/img/tendermint-ssync-archway.png new file mode 100644 index 0000000..c2fd445 Binary files /dev/null and b/static/img/tendermint-ssync-archway.png differ