Initia Protocol Testnet Fullnode Setup Guide

This guide will help you set up a full Initia Protocol node on the testnet. Follow these steps carefully to ensure a successful deployment.

Prerequisites

System Requirements

• Operating System: Ubuntu 22.04/24.04 LTS x64
• CPU: 16 cores minimum
• Memory: 32GB RAM minimum
• Storage: 2TB NVMe/SSD Storage with Write Throughput > 1000 MiBps
• Network: 100 Mbps bandwidth minimum
• Access: Root or sudo privileges

Network Information

Component	Value	Description
Network	Initiation-1	Current testnet
Chain ID	initiation-1	Testnet chain identifier
Latest Version	v1.1.0	Current node software version
Native Token	INIT	Native staking token
Consensus	CometBFT	Tendermint-based consensus

tip

The following commands are executed as root by default. If you are not a root user, please prepend the commands with sudo.

Initial Setup

Define Environment Variables

First, let's set up all the variables we'll need throughout the setup process:

# Node configuration
export NODE_DIR="/data/initia"                    # Node data directory
export NODE_MONIKER="your-node-moniker"           # Your node's display name (max 70 chars)
export CHAIN_ID="initiation-1"                    # Testnet chain ID
export VERSION="v1.1.0"                           # Initia version

# Network configuration
export MIN_GAS_PRICES="0.15uinit,0.01uusdc"       # Minimum gas prices
export PORT_PREFIX="2"                            # Port prefix for custom ports

# Create symbolic link for easier access
export HOME_DIR="$HOME/.initia"

info

Variable Explanation:

• NODE_DIR: Where your blockchain data will be stored
• NODE_MONIKER: A friendly name for your node (use only ASCII characters, max 70 chars)
• PORT_PREFIX: Used to avoid port conflicts if running multiple nodes
• MIN_GAS_PRICES: Minimum gas prices for different tokens

Step 1: System Preparation

Update System Packages

# Update package list and install required tools
sudo -i

# Update package list and install required tools
apt update
apt install -y git make git-core libssl-dev pkg-config build-essential protobuf-compiler libudev-dev curl jq wget aria2

Install Go 1.22.0

# Remove any existing Go installation
rm -rf /usr/local/go

# Download and install Go 1.22.0
curl -Ls https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | sudo tar -xzf - -C /usr/local

# Set up environment variables for Go
eval $(echo 'export PATH=$PATH:/usr/local/go/bin' | sudo tee /etc/profile.d/gobinpath.sh)
eval $(echo 'export PATH=$PATH:$HOME/go/bin' | sudo tee /etc/profile.d/gopath.sh)

# Verify Go installation
go version

Step 2: Build Initia

Clone and Build the Software

# Clone the Initia repository
cd /opt
git clone https://github.com/initia-labs/initia.git initia_src
cd initia_src

# Checkout the specified version
git fetch --all
git checkout tags/$VERSION

# Build and install Initia
make install

# Verify installation
initiad version

Step 3: Initialize Node

Set Up Node Directory

# Create data directory and symbolic link
mkdir -pv $NODE_DIR
ln -sfv $NODE_DIR $HOME_DIR

# Initialize the node
initiad init $NODE_MONIKER --chain-id $CHAIN_ID --home $NODE_DIR

Create Custom Port Script

# Create portset.sh script for custom port configuration
cat > portset.sh << 'EOF'
#!/bin/bash
# Custom port configuration script for Initia node

if [ $# -ne 3 ]; then
    echo "Usage: $0 <NODE_DIR> <MIN_GAS_PRICES> <PORT_PREFIX>"
    echo "Example: $0 /data/initia 0.15uinit,0.01uusdc 2"
    exit 1
fi

NODE_DIR=$1
MIN_GAS_PRICES=$2
PORT_PREFIX=$3

# Set custom ports
sed -i.bak -e "s%:1317%:${PORT_PREFIX}317%g; s%:8080%:${PORT_PREFIX}080%g; s%:9090%:${PORT_PREFIX}090%g; s%:9091%:${PORT_PREFIX}091%g; s%:8545%:${PORT_PREFIX}545%g; s%:8546%:${PORT_PREFIX}546%g; s%:6065%:${PORT_PREFIX}065%g" $NODE_DIR/config/app.toml

sed -i.bak -e "s%:26658%:${PORT_PREFIX}6658%g; s%:26657%:${PORT_PREFIX}6657%g; s%:6060%:${PORT_PREFIX}060%g; s%:26656%:${PORT_PREFIX}6656%g; s%:26660%:${PORT_PREFIX}6660%g" $NODE_DIR/config/config.toml

# Set minimum gas prices
sed -i.bak -e "s/^minimum-gas-prices *=.*/minimum-gas-prices = \"$MIN_GAS_PRICES\"/" $NODE_DIR/config/app.toml

echo "Port configuration completed successfully!"
echo "API: ${PORT_PREFIX}317, gRPC: ${PORT_PREFIX}090, P2P: ${PORT_PREFIX}6656, RPC: ${PORT_PREFIX}6657"
EOF

chmod +x portset.sh

info

About portset.sh: This script comes from the cosmos port configuration guide and helps you set custom ports to avoid conflicts when running multiple nodes.

Configure Ports

# Execute port configuration script
bash portset.sh $NODE_DIR $MIN_GAS_PRICES $PORT_PREFIX

Step 4: Network Configuration

Download Genesis File

# Download the official genesis file
curl -Ls https://initia.s3.ap-southeast-1.amazonaws.com/initiation-1/genesis.json > $NODE_DIR/config/genesis.json

# Verify genesis file
initiad validate-genesis --home $NODE_DIR

Configure Seeds and Peers

# Set persistent peers
sed -i -e "s|^persistent_peers *=.*|persistent_peers = \"[email protected]:26656,[email protected]:26019\"|" $NODE_DIR/config/config.toml

# Set seeds
sed -i -e "s|^seeds *=.*|seeds = \"[email protected]:26656,c28827cb96c14c905b127b92065a3fb4cd77d7f6@testnet-seeds.whispernode.com:25756\"|" $NODE_DIR/config/config.toml

Download Address Book

# Download and install address book
wget https://initia.s3.ap-southeast-1.amazonaws.com/initiation-1/addrbook.json
mv addrbook.json $NODE_DIR/config/addrbook.json

Step 5: Install Cosmovisor

Install and Configure Cosmovisor

# Install Cosmovisor for automatic upgrades
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

# Create Cosmovisor directory structure
mkdir -pv $NODE_DIR/cosmovisor/genesis/bin
ln -sfv $NODE_DIR/cosmovisor/genesis $NODE_DIR/cosmovisor/current

# Copy initiad binary to Cosmovisor
cp $(which initiad) $NODE_DIR/cosmovisor/genesis/bin/

# Verify Cosmovisor setup
ls -la $NODE_DIR/cosmovisor/genesis/bin/

info

Cosmovisor Benefits:

• Automatic binary upgrades during chain upgrades
• Backup and rollback functionality
• Minimal downtime during upgrades
• Robust upgrade management

Step 6: Create Systemd Service

Create Service File

# Create systemd service file
cat > /etc/systemd/system/initia.service << EOF
[Unit]
Description=Initia Node Service
After=network-online.target

[Service]
User=$USER
Restart=on-failure
Type=simple
ExecStart=$(which cosmovisor) run start
WorkingDirectory=$NODE_DIR
SyslogIdentifier=initiad
LimitNOFILE=65535
Environment="DAEMON_NAME=initiad"
Environment="DAEMON_HOME=$NODE_DIR"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_LOG_BUFFER_SIZE=512"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="UNSAFE_SKIP_BACKUP=true"

[Install]
WantedBy=multi-user.target
EOF

Start the Service

# Reload systemd and start the service
systemctl daemon-reload
systemctl enable initia.service
systemctl start initia.service

# Check service status
systemctl status initia.service

# Monitor logs
journalctl -u initia.service -f -o cat

Step 7: Monitor Synchronization

Check Sync Status

# Check node sync status
curl -s localhost:${PORT_PREFIX}6657/status | jq .result.sync_info

# Check if node is catching up
curl -s localhost:${PORT_PREFIX}6657/status | jq .result.sync_info.catching_up

# Get current block height
curl -s localhost:${PORT_PREFIX}6657/status | jq .result.sync_info.latest_block_height

Monitor Node Health

# Check node status
initiad status --home $NODE_DIR

# Check peer connections
curl -s localhost:${PORT_PREFIX}6657/net_info | jq .result.n_peers

# Monitor logs for sync progress
journalctl -u initia.service -f | grep -i "executed block"

Directory Structure

After deployment, your node will have this structure:

/data/initia/
├── config/
│   ├── genesis.json            # Genesis configuration
│   ├── config.toml             # Node configuration
│   ├── app.toml                # Application configuration
│   └── addrbook.json           # Address book
├── data/
│   ├── application.db/         # Application state
│   ├── blockstore.db/          # Block storage
│   └── state.db/               # Consensus state
├── cosmovisor/
│   ├── genesis/bin/            # Initial binary
│   ├── current/                # Current binary (symlink)
│   └── upgrades/               # Upgrade binaries
└── keyring-test/               # Test keyring (if used)

Configuration Optimization

Performance Tuning

# Optimize config.toml for better performance
sed -i.bak \
    -e 's/^indexer *=.*/indexer = "null"/' \
    -e 's/^prometheus *=.*/prometheus = true/' \
    -e 's/^max_num_inbound_peers *=.*/max_num_inbound_peers = 100/' \
    -e 's/^max_num_outbound_peers *=.*/max_num_outbound_peers = 40/' \
    $NODE_DIR/config/config.toml

# Optimize app.toml
sed -i.bak \
    -e 's/^pruning *=.*/pruning = "custom"/' \
    -e 's/^pruning-keep-recent *=.*/pruning-keep-recent = "100"/' \
    -e 's/^pruning-keep-every *=.*/pruning-keep-every = "0"/' \
    -e 's/^pruning-interval *=.*/pruning-interval = "10"/' \
    $NODE_DIR/config/app.toml

Snapshot Configuration (Optional)

# Enable state sync snapshots (optional)
sed -i.bak \
    -e 's/^snapshot-interval *=.*/snapshot-interval = 1000/' \
    -e 's/^snapshot-keep-recent *=.*/snapshot-keep-recent = 2/' \
    $NODE_DIR/config/app.toml

Maintenance and Operations

Regular Maintenance Tasks

# Check service status
systemctl status initia.service

# Restart service if needed
systemctl restart initia.service

# Check disk usage
df -h $NODE_DIR

# Monitor resource usage
htop

Log Management

# View recent logs
journalctl -u initia.service -n 100

# Follow logs in real-time
journalctl -u initia.service -f

# Filter logs by time
journalctl -u initia.service --since "1 hour ago"

# Export logs for analysis
journalctl -u initia.service --since "24 hours ago" > initia_logs.txt

Troubleshooting

Common Issues

Service fails to start:

# Check service logs
journalctl -u initia.service -n 50

# Check binary permissions
ls -la $(which cosmovisor)
ls -la $NODE_DIR/cosmovisor/current/bin/

# Verify configuration
initiad validate-genesis --home $NODE_DIR

Node not syncing:

# Check peer connections
curl -s localhost:${PORT_PREFIX}6657/net_info | jq .result.n_peers

# Reset node data (warning: will restart sync)
systemctl stop initia.service
initiad unsafe-reset-all --home $NODE_DIR
systemctl start initia.service

High resource usage:

# Monitor resource usage
htop
iotop
df -h

# Check if pruning is working
ls -la $NODE_DIR/data/application.db/

Performance Optimization

# Check sync speed
journalctl -u initia.service -f | grep "executed block"

# Monitor network connectivity
ping 8.8.8.8
curl -I google.com

# Check disk I/O performance
iostat -x 1

Support Resources

For help and support:

• Initia Documentation: docs.initia.xyz
• Node Documentation: docs.initia.xyz/nodes-and-rollups
• GitHub: github.com/initia-labs/initia
• Discord: discord.gg/initia
• Community Forum: community.initia.xyz

---

info

This setup creates a production-ready Initia node for the testnet. The node will automatically stay synchronized with the network and handle upgrades through Cosmovisor.

warning

Important Notes:

• Initial sync can take several hours depending on hardware and network
• Ensure you have adequate storage space (2TB+ recommended)
• Monitor resource usage during initial sync
• Keep your system updated for security