Ika Operator

---

name: ika-operator version: 1.0.0 description: Guide for operating Ika network nodes - validators, fullnodes, and notifiers. Use when deploying, configuring, monitoring, or troubleshooting Ika infrastructure. Triggers on tasks involving ika-node, ika-validator, ika-fullnode, ika-notifier, NodeConfig, consensus setup, P2P networking, validator registration, or Ika node operations. metadata: openclaw: requires: bins: - ika - sui emoji: "🖥️" homepage: "https://ika.xyz" tags: - infrastructure - validator - node-operator - sui - dwallet - devops

---

Ika Node Operator Guide

Deploy and operate Ika network nodes (validators, fullnodes, notifiers).

References (detailed configuration and operations)

references/configuration.md - Complete NodeConfig YAML reference, all fields with defaults

references/operations.md - Deployment, monitoring, admin API, recovery, metrics proxy

references/validator-setup.md - Step-by-step mainnet validator setup with CLI commands

Node Types

| Binary | Mode | Purpose | Key Config | |---|---|---|---| | ika-node | Auto-detect | Selects mode from config | Detects automatically | | ika-validator | Validator | Consensus + MPC signing | Requires consensus-config | | ika-fullnode | Fullnode | State sync via P2P, no consensus | No consensus-config, no notifier-client-key-pair | | ika-notifier | Notifier | Submits checkpoints to Sui | Requires notifier-client-key-pair |

Auto-detection order: consensus-config present → Validator; else notifier-client-key-pair present → Notifier; else → Fullnode.

Hardware Requirements (Validator)

| Resource | Minimum | |---|---| | CPU | 16 physical cores / 16 vCPUs | | Memory | 128 GB | | Storage | 4 TB NVMe | | Network | 1 Gbps | | OS | Linux Ubuntu/Debian x64 (or Docker on x64 Linux) |

Warning: Hetzner has strict crypto ToS and may close validators without notice.

Connectivity (Validator Ports)

| Protocol/Port | Direction | Purpose | |---|---|---| | TCP/8080 | Inbound | Protocol / Transaction Interface | | UDP/8081 | Inbound/Outbound | Consensus Interface | | UDP/8084 | Inbound/Outbound | Peer-to-Peer State Sync | | TCP/8443 | Outbound | Metrics Pushing | | TCP/9184 | Inbound/Outbound | Metrics Scraping (both Sui fullnode and Ika node) |

Critical: Ports 8080-8084 and 9184 must be open with correct protocols (TCP/UDP).

Prerequisites

DNS address for your validator (e.g., ika-mainnet-1.)

Your own Sui fullnode on Sui mainnet, fully synced (at least 2 latest epochs). Use separate DNS for Sui node.

Sui CLI installed, configured for mainnet, active address with at least 10 SUI

Minimum 40 million IKA stake to join the committee

Quick Start: Mainnet Validator

Download binaries from: https://github.com/dwallet-labs/ika/releases

Step 1: Configure Ika Environment

Get the latest package/object IDs from the canonical source:

Mainnet: deployed_contracts/mainnet/address.yaml (GitHub)

Testnet: deployed_contracts/testnet/address.yaml (GitHub)

./ika validator config-env \
  --ika-package-id                     \
  --ika-common-package-id              \
  --ika-dwallet-2pc-mpc-package-id     \
  --ika-system-package-id              \
  --ika-system-object-id              
Creates: ~/.ika/ika_config/ika_sui_config.yaml
Note: ika-dwallet-coordinator-object-id is not set at this stage (defaults to zero);
it must be configured later in the node's validator.yaml under sui-connector-config.

Step 2: Generate Validator Info & Keys

./ika validator make-validator-info \
  "My Validator" "Description" \
  "https://example.com/image.png" "https://example.com" \
  "ika-mainnet-1.example.com" \
  10000 \
  
Generates: protocol.key, network.key, consensus.key, root-seed.key, validator.info

CRITICAL: Back up ALL generated keys. root-seed.key is SECRET and IRREPLACEABLE. If lost, it cannot be updated via contract. Other keys (protocol, network, consensus) can be rotated on-chain.

Step 3: Register as Validator Candidate

./ika validator become-candidate ./validator.info
Returns: Validator ID, Validator Cap ID, Validator Operation Cap ID, and Validator Commission Cap ID

Step 4: Stake into Validator

Stake at least 40 million IKA via: https://ika-mainnet-validators-staking.pages.dev/

Verify your Validator ID matches the CLI output.

Step 5: Join Committee

./ika validator join-committee --validator-cap-id 

You become a pending validator and join the committee at the next epoch.

Step 6: Run the Validator Node

Directory structure:

/opt/ika/
├── bin/ika-node
├── config/validator.yaml
├── key-pairs/
│   ├── protocol.key
│   ├── network.key
│   ├── consensus.key
│   └── root-seed.key
└── db/                        # Created at runtime
    ├── authorities_db/
    └── consensus_db/

Before running, edit validator.yaml:

Set ika-dwallet-coordinator-object-id to the value from deployed_contracts/mainnet/address.yaml

Ensure: sui-chain-identifier: mainnet

Set metrics: push-url: "https://mainnet.metrics.ika-network.net:8443/publish/metrics"

ika-node --config-path /opt/ika/config/validator.yaml

Logging: Set RUST_LOG for log levels, RUST_LOG_JSON=1 for JSON output.

Step 7: Verify

Wait a couple minutes, check logs for:

ika_core::checkpoints: Creating checkpoint(s) for 0 messages next_checkpoint_seq=1

This confirms the node is running. Additional checkpoints appear only during/after MPC sessions.

Package & Object IDs

Always get the latest IDs from the canonical source files in the repo:

Mainnet: deployed_contracts/mainnet/address.yaml (GitHub)

Testnet: deployed_contracts/testnet/address.yaml (GitHub)

Keypairs

| Key | Type | Purpose | Required By | Recoverable? | |---|---|---|---|---| | protocol-key-pair | AuthorityKeyPair | Protocol signatures | All | Yes (rotate on-chain) | | consensus-key-pair | Ed25519 | Consensus communication | All | Yes (rotate on-chain) | | network-key-pair | Ed25519 | P2P networking | All | Yes (rotate on-chain) | | account-key-pair | SuiKeyPair | Sui interactions | All | Yes | | root-seed-key-pair | RootSeed | MPC cryptographic operations | Validators | NO - IRREPLACEABLE | | notifier-client-key-pair | SuiKeyPair | Submit checkpoints to Sui | Notifiers | Yes |

Validator Config Essentials

# Mainnet validator must have:
sui-connector-config:
  sui-chain-identifier: mainnet
  sui-rpc-url: 'http://:9000'
  # Get all IDs from deployed_contracts/mainnet/address.yaml
  ika-package-id: ''
  ika-dwallet-coordinator-object-id: ''
  # ... other package/object IDs
consensus-config:                         # Presence triggers validator mode
  db-path: '/opt/ika/consensus_db'
  db-retention-epochs: 0
  db-pruner-period-secs: 3600
  max-pending-transactions: 20000
root-seed-key-pair:
  path: /opt/ika/key-pairs/root-seed.key
metrics:
  push-url: "https://mainnet.metrics.ika-network.net:8443/publish/metrics"

Admin API (localhost only)

curl http://127.0.0.1:1337/logging                    # View log filter
curl -X POST 'http://127.0.0.1:1337/enable-tracing?filter=debug&duration=10s'
curl -X POST http://127.0.0.1:1337/reset-tracing      # Reset to env var
curl http://127.0.0.1:1337/node-config                 # View config (keys masked)
curl http://127.0.0.1:1337/capabilities                # View capabilities

Environment Variables

| Variable | Purpose | Default | |---|---|---| | IKA_CONFIG_DIR | Override config directory | ~/.ika/ika_config/ | | RUST_LOG | Log level filter | — | | RUST_LOG_JSON | JSON log output (1 to enable) | — | | TRACE_FILTER | Tracing log filter | — |

Services by Node Type

| Service | Validator | Fullnode | Notifier | |---|---|---|---| | AuthorityState | Y | Y | Y | | ConsensusManager | Y | — | — | | DWalletMPCService | Y | — | — | | SuiConnectorService | Y | Y | Y | | CheckpointServices | Y | Y | Y | | P2P + StateSync | Y | Y | Y | | Discovery | Y | Y | Y |

Key Operational Notes

Release mode required: Always build with --release for crypto operations

Sui fullnode required: Run your own Sui fullnode, fully synced (2+ latest epochs)

Package IDs must match: Contract IDs in config must match deployed contracts

Minimum stake: 40 million IKA to join the committee

Root seed is sacred: Back it up securely. Cannot be regenerated or rotated on-chain.

Updates: Monitor #nodes-updates-mainnet channel for new releases

Recovery: Use --run-with-range-epoch or --run-with-range-checkpoint for disaster recovery

Checkpoint pinning: Use pinned-dwallet-checkpoints in state-sync config for fork recovery

Graceful shutdown: Send SIGTERM or SIGINT

DNS address for your validator (e.g., ika-mainnet-1.)

Your own Sui fullnode on Sui mainnet, fully synced (at least 2 latest epochs). Use separate DNS for Sui node.

Sui CLI installed, configured for mainnet, active address with at least 10 SUI

Minimum 40 million IKA stake to join the committee