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#

BinaryModePurposeKey Configika-nodeAuto-detectSelects mode from configDetects automaticallyika-validatorValidatorConsensus + MPC signingRequires consensus-config``ika-fullnodeFullnodeState sync via P2P, no consensusNo consensus-config, no notifier-client-key-pair``ika-notifierNotifierSubmits checkpoints to SuiRequires notifier-client-key-pair

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

Hardware Requirements (Validator)#

ResourceMinimumCPU16 physical cores / 16 vCPUsMemory128 GBStorage4 TB NVMeNetwork1 GbpsOSLinux Ubuntu/Debian x64 (or Docker on x64 Linux)

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

Connectivity (Validator Ports)#

Protocol/PortDirectionPurposeTCP/8080InboundProtocol / Transaction InterfaceUDP/8081Inbound/OutboundConsensus InterfaceUDP/8084Inbound/OutboundPeer-to-Peer State SyncTCP/8443OutboundMetrics PushingTCP/9184Inbound/OutboundMetrics 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)

bash

./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#

bash

./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#

bash

./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#

bash

./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:

text

/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"

bash

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:

text

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#

KeyTypePurposeRequired ByRecoverable?protocol-key-pairAuthorityKeyPairProtocol signaturesAllYes (rotate on-chain)consensus-key-pairEd25519Consensus communicationAllYes (rotate on-chain)network-key-pairEd25519P2P networkingAllYes (rotate on-chain)account-key-pairSuiKeyPairSui interactionsAllYesroot-seed-key-pairRootSeedMPC cryptographic operationsValidatorsNO - IRREPLACEABLEnotifier-client-key-pairSuiKeyPairSubmit checkpoints to SuiNotifiersYes

Validator Config Essentials#

yaml

# Mainnet validator must have:
sui-connector-config:
  sui-chain-identifier: mainnet
  sui-rpc-url: 'http://<your-sui-fullnode>:9000'
  # 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)#

bash

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#

VariablePurposeDefaultIKA_CONFIG_DIROverride config directory~/.ika/ika_config/``RUST_LOGLog level filter—RUST_LOG_JSONJSON log output ( 1 to enable)—TRACE_FILTERTracing log filter—

Services by Node Type#

ServiceValidatorFullnodeNotifierAuthorityStateYYYConsensusManagerY——DWalletMPCServiceY——SuiConnectorServiceYYYCheckpointServicesYYYP2P + StateSyncYYYDiscoveryYYY

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