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-domain>)
• 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_package_id> \
  --ika-common-package-id             <ika_common_package_id> \
  --ika-dwallet-2pc-mpc-package-id    <ika_dwallet_2pc_mpc_package_id> \
  --ika-system-package-id             <ika_system_package_id> \
  --ika-system-object-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 \
  <YOUR_SUI_ADDRESS>
# 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 <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
  # NEW-STYLE gRPC (replaces deprecated sui-rpc-url). A validator on this path
  # MUST also set sui-trusted-anchor (see references/configuration.md).
  sui-data-source:
    kind: sui-state-direct
    url: 'http://<your-sui-fullnode>:9000'
    serve-mirror: true
  sui-trusted-anchor: '<end-of-epoch checkpoint digest from a trusted fullnode>'
  # Get all IDs from deployed_contracts/mainnet/address.yaml
  ika-package-id: '<from address.yaml>'
  ika-dwallet-coordinator-object-id: '<from address.yaml>'
  # ... 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