Home/docs/network

Network & Node Setup

Umotu runs CometBFT for consensus (2s blocks) and an ABCI app that embeds a Geth EVM. The ABCI app exposes a minimal JSON‑RPC shim for EVM compatibility.

Chain Overview

Consensus: CometBFT; Finality gated by phone‑QCs.
Execution: Embedded Geth EVM via ABCI++ FinalizeBlock.
AppHash: EVM state root returned to CometBFT.
Block time: ~2s; Chain ID: Testnet 9601; Mainnet 9600 (planned).

See UMOTU-CHAIN-OVERVIEW.md for details.

Quick Start Guide

Follow these steps to set up your Umotu node and connect to the network:

Step 1: Install CometBFT v0.38.12

Download and install CometBFT, then initialize it:

# Linux (amd64)
curl -LO https://github.com/cometbft/cometbft/releases/download/v0.38.12/cometbft_0.38.12_linux_amd64.tar.gz
tar xzf cometbft_0.38.12_linux_amd64.tar.gz && sudo mv cometbft*/cometbft /usr/local/bin/
cometbft init --home ~/.umotu/cometbft

# macOS (arm64)
curl -LO https://github.com/cometbft/cometbft/releases/download/v0.38.12/cometbft_0.38.12_darwin_arm64.tar.gz
tar xzf cometbft_0.38.12_darwin_arm64.tar.gz && sudo mv cometbft*/cometbft /usr/local/bin/
cometbft init --home ~/.umotu/cometbft

# Windows (PowerShell)
$ver = '0.38.12'
Invoke-WebRequest https://github.com/cometbft/cometbft/releases/download/v$ver/cometbft_$ver_windows_amd64.zip -OutFile cometbft.zip
Expand-Archive -Path cometbft.zip -DestinationPath C:\Tools\cometbft -Force
[Environment]::SetEnvironmentVariable('Path', $env:Path + ';C:\Tools\cometbft', 'Machine')
cometbft init --home C:\umotu\cometbft

Step 2: Download Network Configuration

Download the optimized CometBFT config with seed nodes, and update your genesis with network parameters:

# Linux/macOS
curl -o ~/.umotu/cometbft/config/config.toml https://umotu.com/api/network/config-toml

# Update genesis parameters (preserving your local validator key)
python3 << 'EOF'
import json, urllib.request

# Load your local genesis (created by cometbft init)
with open('/home/solcal/.umotu/cometbft/config/genesis.json', 'r') as f:
    local_genesis = json.load(f)

# Download network parameters
network = json.loads(urllib.request.urlopen('https://umotu.com/api/network/cometbft-genesis').read())

# Update network params while keeping your validator entry
local_genesis['chain_id'] = network['chain_id']
local_genesis['genesis_time'] = network['genesis_time']
local_genesis['consensus_params'] = network['consensus_params']

# Save updated genesis
with open('/home/solcal/.umotu/cometbft/config/genesis.json', 'w') as f:
    json.dump(local_genesis, f, indent=2)
print("✓ Genesis updated with network parameters")
EOF

# Windows (PowerShell)
Invoke-WebRequest -Uri https://umotu.com/api/network/config-toml -OutFile C:\umotu\cometbft\config\config.toml

# Update genesis (PowerShell)
$genesis = Get-Content C:\umotu\cometbft\config\genesis.json | ConvertFrom-Json
$network = Invoke-RestMethod https://umotu.com/api/network/cometbft-genesis
$genesis.chain_id = $network.chain_id
$genesis.genesis_time = $network.genesis_time
$genesis.consensus_params = $network.consensus_params
$genesis | ConvertTo-Json -Depth 10 | Set-Content C:\umotu\cometbft\config\genesis.json
Write-Host "✓ Genesis updated with network parameters"

Note: The config.toml includes seed nodes to connect to the network. Your genesis keeps your local validator key but uses network parameters (chain_id, consensus rules). You'll run as a full node - to become an active validator requires separate governance approval.

Step 3: Open Firewall Port (Linux)

If running on Linux with UFW firewall, allow CometBFT P2P connections:

sudo ufw allow 26656/tcp comment 'CometBFT P2P'

Skip this step if you're not running a firewall or using macOS/Windows.

Step 4: Download & Start Umotu Node

Download the native bundle and start both CometBFT and the ABCI app. The umotu-node launcher will automatically use the config.toml from Step 2:

# Linux (amd64)
curl -LO https://downloads.umotu.com/releases/umotu-node-v0.3.2-linux_amd64.tar.gz
mkdir -p umotu && tar xzf umotu-node-v0.3.2-linux_amd64.tar.gz -C umotu --strip-components=1
cd umotu
./bin/umotu-node --dev start

# macOS (arm64)
curl -LO https://downloads.umotu.com/releases/umotu-node-v0.3.2-darwin_arm64.tar.gz
mkdir -p umotu && tar xzf umotu-node-v0.3.2-darwin_arm64.tar.gz -C umotu --strip-components=1
cd umotu
./bin/umotu-node --dev start

# Windows (amd64, PowerShell)
$ver = "v0.3.2"
Invoke-WebRequest https://downloads.umotu.com/releases/umotu-node-$ver-windows_amd64.tar.gz -OutFile umotu-node.tar.gz
New-Item -ItemType Directory -Force -Path umotu
tar -xzf umotu-node.tar.gz -C umotu --strip-components=1
cd umotu
./bin/umotu-node.exe --dev start

Step 5 (Optional): Custom Environment Variables

If you want to customize your node configuration, download the complete environment template from Configuration Downloads below, or create a minimal custom environment file:

# Download the complete template (recommended):
curl -fsSL https://umotu.com/api/network/abci-env -o umotu-node.env

# Or create a minimal custom env file:
cat > umotu-node.env <<'EOF'
UMOTU_GENESIS=/var/lib/umotu/genesis.json
UMOTU_RPC_INDEX=/var/lib/umotu/abci-data/rpc-index.json
UMOTU_QC_ENFORCE=false
UMOTU_PBS_REQUIRED=false
UMOTU_ALLOW_BUILDER_FALLBACK=true
# See Configuration Downloads for the complete list of available variables
EOF

# Load the environment and start
set -a
source umotu-node.env
set +a
./bin/umotu-node --dev start

Step 6 (Optional): Run as systemd Service

For production deployments on Linux, set up as a systemd service (see systemd section below).

JSON‑RPC

The ABCI app exposes a lightweight JSON‑RPC shim for EVM methods used by wallets and tools.

# Same-origin proxy (explorer) or direct to ABCI :8080/rpc
curl -s -X POST http://localhost:8080/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Supported: eth_chainId, eth_blockNumber, eth_getBlockByNumber, eth_getTransactionByHash, eth_getLogs, eth_sendRawTransaction, etc.
WebSocket: /ws supports eth_subscribe for newHeads and logs.
Helper: umotu_getConsensusKey returns your CometBFT consensus key (also available via /consensus-key).

systemd Service (Linux)

Install the native launcher as a systemd service for auto‑start and journald logs.

# Create user and data dir
sudo useradd --system --home /var/lib/umotu --shell /usr/sbin/nologin umotu || true
sudo mkdir -p /var/lib/umotu

# IMPORTANT: Move CometBFT data from Step 1-2 to systemd directory
# This preserves your node identity (node_key.json) and validator key
sudo cp -r ~/.umotu/cometbft /var/lib/umotu/
sudo chown -R umotu:umotu /var/lib/umotu

# Install binaries from the tarball
sudo install -m 755 bin/umotu-node /usr/local/bin/umotu-node
sudo install -m 755 bin/umotu-abci /usr/local/bin/umotu-abci

# Environment file - download the complete template (recommended)
curl -fsSL https://umotu.com/api/network/abci-env -o /tmp/umotu-node.env
sudo mv /tmp/umotu-node.env /etc/default/umotu-node
sudo chown root:root /etc/default/umotu-node
sudo chmod 644 /etc/default/umotu-node

# Or create a minimal env file for dev/testing:
# sudo tee /etc/default/umotu-node >/dev/null <<'EOF'
# UMOTU_GENESIS=/var/lib/umotu/genesis.json
# UMOTU_RPC_INDEX=/var/lib/umotu/abci-data/rpc-index.json
# UMOTU_QC_ENFORCE=false
# UMOTU_PBS_REQUIRED=false
# UMOTU_ALLOW_BUILDER_FALLBACK=true
# See https://umotu.com/api/network/abci-env for all available variables
# EOF

# Install service (download from Configuration Downloads section or use from repo)
sudo cp ops/systemd/umotu-node.service /etc/systemd/system/
# Or download directly:
# curl -fsSL https://umotu.com/api/network/umotu-node-service -o umotu-node.service
# sudo mv umotu-node.service /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now umotu-node
sudo systemctl status umotu-node

See ops/systemd/README.md in the repo for details, or download the service file from the Configuration Downloads section below.

Configuration Downloads

Download optimized configuration files for your Umotu node:

genesis.json - EVM genesis file with initial state
system-addresses.json - System contract addresses
cometbft-config.toml - CometBFT config with performance tuning and seed nodes
cometbft-genesis.json - CometBFT genesis file with validator set, consensus params etc
umotu-node.service - systemd service file for Linux installations
umotu-node.env - Complete ABCI environment variable template with all available options documented

These files are pre-configured for the Umotu testnet. The config.toml includes seed nodes for automatic peer discovery. The umotu-node.env file contains all available environment variables with descriptions - customize it for your deployment needs.