dwallet-labs/ika/ika-operator

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

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

Hardware Requirements (Validator)

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

Connectivity (Validator Ports)

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

Validator Config Essentials

# Mainnet validator must have:
sui-connector-config:
  sui-chain-identifier: mainnet
  # All Sui I/O uses gRPC. Validators MUST also set sui-genesis
  # (see references/configuration.md).
  sui-data-source:
    kind: sui-state-direct
    url: 'http://<your-sui-fullnode>:9000'
    serve-mirror: true
  sui-genesis: '/opt/ika/sui-mainnet-genesis.blob'
  # ika package/object IDs are COMPILED INTO THE BINARY on mainnet/testnet
  # (keyed off sui-chain-identifier) — do not configure them. Only
  # custom/localnet chains set ika-unsafe-identity-override (see
  # references/configuration.md).
 
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

Services by Node Type

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