Run a Node

This guide provides comprehensive instructions for running a DChain node, whether you're joining a testnet or running a local development network.

System Requirements

Hardware Specifications

Minimum Requirements:

8 GB RAM
1 vCPU (x64 1.4 GHz or equivalent)
10 GB SSD storage (with state-sync)

Recommended Configuration:

4-8 GB RAM
2-4 vCPU (x64 2.0 GHz or equivalent)
100 GB SSD storage (without state-sync)
625 GB SSD storage (for archive node with historical data)

Storage Recommendations

Important: Mount your blockchain data on an expandable volume/partition separate from your root partition. This allows independent scaling of storage without requiring CPU/RAM upgrades.

Default data location: $HOME/.dchain

Operating System

Recommended: Ubuntu 20.04 LTS or later
Alternative: Any Linux distribution with Docker support

Network Requirements

P2P Port: 26656 (default, must be accessible)
RPC Port: 26657 (default, optional for public nodes)

Installation

Build from Source

# Update system packages
sudo apt update
sudo apt install git make gcc

# Install Go 1.23.2
wget https://go.dev/dl/go1.23.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.23.2.linux-amd64.tar.gz

# Configure Go environment
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile
source ~/.profile

# Verify Go installation
go version # Should show: go version go1.23.2 linux/amd64

# Clone and build DChain (v0.8.2 is the version for Theodoric-2 testnet genesis)
git clone --branch v0.8.2 --depth 1 git@repos.gayadeed.it:d-foundation/protocol.git
cd protocol
make build

# Install binary
sudo mv ./dchain /usr/local/bin

# Verify installation
dchain version --long

Expected output should include:

commit: 349c164f3cdc124daf10e062d583823102f5e497
cosmos_sdk_version: v0.53.4-dchain-v3
go: go version go1.23.12 darwin/arm64
name: dchain
server_name: dchain
version: HEAD-349c164f3cdc124daf10e062d583823102f5e497

Syncing with an existing network

Current only Theodoric-2 (Testnet) is running.

Initial Setup

# Set chain ID (replace with current testnet chain-id)
dchain config set client chain-id test-theodoric-2

# Initialize node (replace <your-node-name> with your moniker)
dchain init <your-node-name> --chain-id test-theodoric-2

Download Genesis File

# Download genesis file from the networks repository
# For test-theodoric-2:
curl -o $HOME/.dchain/config/genesis.json https://raw.githubusercontent.com/d-foundation/networks/main/testnets/test-theodoric-2/genesis.json

Configure Persistent Peers

Edit $HOME/.dchain/config/config.toml and add persistent peers:

persistent_peers = "<node-id>@<ip>:<port>,<node-id>@<ip>:<port>"

Find current peer information in the networks repository under the specific testnet directory.

Add Verifiable Presentation

Required for validators only. The verifiable presentation must be for your consensus address:

# Get your consensus address
dchain cometbft show-address
# Should output: dchainvalcons1...

# Add verifiable presentation (obtain from D-Foundation)
dchain vp add <your-verifiable-presentation>

Syncing Options

You have two options for syncing your node with the network:

Option A: State Sync (Fast - Recommended)

State sync allows rapid node initialization by downloading snapshots from peers. This reduces initial storage requirements and sync time significantly.

1. Configure State Sync

Edit $HOME/.dchain/config/config.toml in the [statesync] section:

[statesync]
enable = true
rpc_servers = "https://rpc.dfoundation.io"
trust_height = <recent-height>
trust_hash = "<block-hash-at-trust-height>"
trust_period = "168h0m0s"

2. Obtain Trust Values

You need to fetch a recent block height and hash. Use one of the RPC servers:

# Get latest block height
LATEST_HEIGHT=$(curl -s https://rpc.dfoundation.io/block | jq -r .result.block.header.height)

# Calculate trust height (100 blocks before latest)
TRUST_HEIGHT=$((LATEST_HEIGHT - 100 ))

# Get block hash at trust height
TRUST_HASH=$(curl -s "https://rpc.dfoundation.io/block?height=$TRUST_HEIGHT" | jq -r .result.block_id.hash)

echo "trust_height = $TRUST_HEIGHT"
echo "trust_hash = \"$TRUST_HASH\""

Option B: Full Sync from Genesis

If you prefer to sync from genesis or state-sync is not available:

1. Ensure State Sync is Disabled

Edit $HOME/.dchain/config/config.toml:

[statesync]
enable = false

2. Configure Pruning (Optional)

To reduce storage requirements, configure pruning in $HOME/.dchain/config/app.toml:

[pruning]
pruning = "custom"
pruning-keep-recent = "100"
pruning-interval = "10"

Running the Node with Cosmovisor

Cosmovisor is a process manager for Cosmos SDK applications that handles automatic upgrades.

Install Cosmovisor

# Install cosmovisor
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.6.0

# Move to system path
sudo mv ~/go/bin/cosmovisor /usr/local/bin

Setup Cosmovisor Directory Structure

# Create directory structure
mkdir -p ~/.dchain/cosmovisor/genesis/bin
cp /usr/local/bin/dchain ~/.dchain/cosmovisor/genesis/bin/

Create Systemd Service

# Create systemd service file
sudo tee /etc/systemd/system/dchain.service > /dev/null <<EOF
[Unit]
Description=DChain Node
After=network-online.target

[Service]
User=$USER
ExecStart=/usr/local/bin/cosmovisor run start
Restart=always
RestartSec=3
LimitNOFILE=65535
Environment="DAEMON_NAME=dchain"
Environment="DAEMON_HOME=$HOME/.dchain"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"

[Install]
WantedBy=multi-user.target
EOF

Start the Node

# Reload systemd daemon
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable dchain

# Start the node
sudo systemctl start dchain

# Check status
sudo systemctl status dchain

# View logs
journalctl -u dchain -f

# Stop the node
sudo systemctl stop dchain

Running a Local Development Network

For local development and testing, you can run a single-node network.

Prerequisites

# Install dchain binary
cd protocol
make install

# This will build and install dchain to $GOPATH/bin

Initialize Local Network

# Initialize local single-node network
# This script:
# - Cleans existing configuration
# - Creates genesis accounts
# - Configures validator with test VP
# - Sets up genesis transaction
make init-local-single

Start Local Node

# Start the local node
dchain start

Default Local Configuration

The local network is configured with:

Chain ID: local-theodoric-1
Keyring Backend: test
Default Denom: udt
Data Directory: $HOME/.dchain
RPC Server: http://localhost:26657
API Server: http://localhost:1317
gRPC Server: localhost:9090

Useful Local Commands

# Query account balance
dchain query bank balances $(dchain keys show validator -a)

# Send tokens
dchain tx bank send validator <recipient-address> 1000udt --chain-id local-theodoric-1

# Query validator information
dchain query staking validators

# Show node information
dchain status

Useful Commands

Node Management

# Check node sync status
dchain status | jq .sync_info

# Check if node is catching up
dchain status | jq .sync_info.catching_up

# Get node info
dchain status | jq .node_info

# Show validtor consensus address
dchain cometbft show-address

# Show node ID
dchain cometbft show-node-id

# Show validator controller public key
dchain cometbft show-validator

Key Management

# Create new key
dchain keys add <key-name>

# Recover key from mnemonic
dchain keys add <key-name> --recover

# List all keys
dchain keys list

# Show key address
dchain keys show <key-name> -a

# Export private key
dchain keys export <key-name>

Simple Monitoring

# Check logs in real-time
journalctl -u dchain -f

# Check logs with line limit
journalctl -u dchain -n 100

For different types of log level see the Cosmos SDK logging documentation.

Troubleshooting

Common Issues

Issue: Node fails to start with "Address already in use"

# Check if another process is using the ports
sudo lsof -i :26656
sudo lsof -i :26657

# Kill the conflicting process or change ports in config.toml

Issue: State sync fails

# Ensure your trust_height and trust_hash are recent
# Try using different RPC servers
# Disable state sync and try full sync instead

Issue: Node falls behind in syncing

# Check your internet connection
# Ensure sufficient resources (CPU/RAM)
# Check peer connectivity: dchain status | jq .sync_info
# Try restarting the node

Issue: Cannot find peers

# Verify persistent_peers in config.toml
# Check firewall settings for port 26656
# Ensure you're using the correct genesis file

System Requirements​

Hardware Specifications​

Storage Recommendations​

Operating System​

Network Requirements​

Installation​

Build from Source​

Syncing with an existing network​

Initial Setup​

Download Genesis File​

Configure Persistent Peers​

Add Verifiable Presentation​

Syncing Options​

Option A: State Sync (Fast - Recommended)​

1. Configure State Sync​

2. Obtain Trust Values​

Option B: Full Sync from Genesis​

1. Ensure State Sync is Disabled​

2. Configure Pruning (Optional)​

Running the Node with Cosmovisor​

Install Cosmovisor​

Setup Cosmovisor Directory Structure​

Create Systemd Service​

Start the Node​

Running a Local Development Network​

Prerequisites​

Initialize Local Network​

Start Local Node​

Default Local Configuration​

Useful Local Commands​

Useful Commands​

Node Management​

Key Management​

Simple Monitoring​

Troubleshooting​

Common Issues​

Additional Resources​