Install and Configure 0G Storage KV Node

Overview

The 0G Storage KV (Key-Value) service provides an interface for efficient data retrieval within the 0G ecosystem. This guide covers the end-to-end installation process, from compiling the source code to managing the service with systemd.

Prerequisites

Before proceeding, ensure your system meets the hardware requirements for 0G infrastructure and that you have a functional 0G Storage Node running.

Verify Rust Installation

The 0G Storage KV node is written in Rust. Verify your installation:

rustc --version

If Rust is not installed, use the official installer:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build Storage KV from Source

Clone the official repository and compile the binary. This process may take several minutes depending on your CPU performance.

git clone https://github.com/0glabs/0g-storage-kv.git
cd 0g-storage-kv
git submodule update --init
cargo build --release

Configuration

The node requires a config.toml file to define network endpoints and contract addresses.

Initialize Configuration File

Copy the provided example configuration to the active run directory:

cp $HOME/0g-storage-kv/run/config_example.toml $HOME/0g-storage-kv/run/config.toml

Extract Environment Variables

To ensure compatibility with your existing 0G Storage Node, extract the necessary parameters directly from your local configuration files:

STORAGE_PORT=$(grep -oP '(?<=rpc_listen_address = "0.0.0.0:)\d+(?=")' $HOME/0g-storage-node/run/config.toml)
ZGS_LOG_SYNC_BLOCK=$(grep -oP '(?<=log_sync_start_block_number = )\d+' $HOME/0g-storage-node/run/config.toml)
STORAGE_RPC_ENDPOINT=http://$(wget -qO- eth0.me):$STORAGE_PORT
BLOCKCHAIN_RPC_ENDPOINT=$(sed -n 's/blockchain_rpc_endpoint = "\([^"]*\)"/\1/p' $HOME/0g-storage-node/run/config.toml)
LOG_CONTRACT_ADDRESS=$(sed -n 's/log_contract_address = "\([^"]*\)"/\1/p' $HOME/0g-storage-node/run/config.toml)
MINE_CONTRACT_ADDRESS=$(sed -n 's/mine_contract_address = "\([^"]*\)"/\1/p' $HOME/0g-storage-node/run/config.toml)
JSON_PORT=$(sed -n '/\[json-rpc\]/,/^address/ s/address = "0.0.0.0:\([0-9]*\)".*/\1/p' $HOME/.0gchain/config/app.toml)
JSON_RPC_ENDPOINT=http://$(wget -qO- eth0.me):$JSON_PORT

Update Configuration File

Apply the extracted variables to the config.toml file using sed:

sed -i "s|rpc_listen_address = .*|rpc_listen_address = \"0.0.0.0:6789\"|" $HOME/0g-storage-kv/run/config.toml
sed -i "s|zgs_node_urls = .*|zgs_node_urls = \"$STORAGE_RPC_ENDPOINT\"|" $HOME/0g-storage-kv/run/config.toml
sed -i "s|log_config_file = .*|log_config_file = \"$HOME/0g-storage-kv/run/log_config\"|" $HOME/0g-storage-kv/run/config.toml
sed -i "s|blockchain_rpc_endpoint = .*|blockchain_rpc_endpoint = \"$BLOCKCHAIN_RPC_ENDPOINT\"|" $HOME/0g-storage-kv/run/config.toml
sed -i "s|log_contract_address = .*|log_contract_address = \"$LOG_CONTRACT_ADDRESS\"|" $HOME/0g-storage-kv/run/config.toml
sed -i "s|log_sync_start_block_number = .*|log_sync_start_block_number = $ZGS_LOG_SYNC_BLOCK|" $HOME/0g-storage-kv/run/config.toml

Service Management

Using systemd ensures the KV node runs in the background and restarts automatically upon failure.

Create Systemd Service

Create the service file using the following block:

sudo tee /etc/systemd/system/zgs-kv.service > /dev/null <<EOF
[Unit]
Description=0G Storage KV Node
After=network.target

[Service]
User=$USER
WorkingDirectory=$HOME/0g-storage-kv/run
ExecStart=$HOME/0g-storage-kv/target/release/zgs_kv --config $HOME/0g-storage-kv/run/config.toml
Restart=on-failure
RestartSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

Launch the Node

Reload the daemon and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable zgs-kv
sudo systemctl start zgs-kv

Monitoring and Maintenance

Check Node Logs

Monitor the real-time output of your KV node to verify synchronization and connection status:

sudo journalctl -u zgs-kv.service -f

Service Controls

Action	Command
Stop Node	sudo systemctl stop zgs-kv
Start Node	sudo systemctl start zgs-kv
Restart Node	sudo systemctl restart zgs-kv
Check Status	sudo systemctl status zgs-kv