Ika 节点运营商指南

部署并运行 Ika 网络节点（验证者、全节点、通知器）。

参考文档（详细配置与操作说明）

• references/configuration.md — 完整的 NodeConfig YAML 配置参考，包含所有字段及其默认值
• references/operations.md — 部署、监控、管理 API、恢复、指标代理
• references/validator-setup.md — 使用 CLI 命令逐步完成主网验证者搭建的完整流程

节点类型

自动识别顺序：若存在 consensus-config → 启动为 Validator；否则若存在 notifier-client-key-pair → 启动为 Notifier；否则 → 启动为 Fullnode。

硬件要求（验证者）

警告：Hetzner 对加密相关服务有严格的使用条款（ToS），可能在无通知情况下关停验证者节点。

连通性（验证者端口）

关键要求：端口 8080–8084 及 9184 必须开放，并确保协议类型（TCP/UDP）配置正确。

前置条件

• 验证者的 DNS 地址（例如：ika-mainnet-1.）
• 您自建的、已完全同步至 Sui 主网的 Sui 全节点（至少同步至最近两个 epoch）。Sui 节点应使用独立 DNS 地址。
• 已安装并配置好 Sui CLI，且已设置为主网环境，同时对应地址中至少持有 10 SUI
• 加入委员会所需的最低质押量为 4000 万 IKA

快速开始：主网验证者

从以下地址下载二进制文件：https://github.com/dwallet-labs/ika/releases

步骤 1：配置 Ika 运行环境

请从权威来源获取最新 package/object ID：

• 主网：deployed_contracts/mainnet/address.yaml（GitHub）
• 测试网：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              
# 将生成：~/.ika/ika_config/ika_sui_config.yaml
# 注意：此时未设置 ika-dwallet-coordinator-object-id（默认为零）；
# 该值必须在节点的 validator.yaml 文件中，于 sui-connector-config 下另行配置。

步骤 2：生成验证者信息与密钥对

./ika validator make-validator-info 
  "My Validator" "Description" 
  "https://example.com/image.png" "https://example.com" 
  "ika-mainnet-1.example.com" 
  10000 
  
# 将生成：protocol.key、network.key、consensus.key、root-seed.key、validator.info

至关重要：请务必备份所有生成的密钥。其中 root-seed.key 是**机密且不可替代**的；一旦丢失，无法通过合约更新。其余密钥（protocol、network、consensus）可在链上轮换。

步骤 3：注册为验证者候选人

./ika validator become-candidate ./validator.info
# 返回：Validator ID、Validator Cap ID、Validator Operation Cap ID 和 Validator Commission Cap ID

步骤 4：向验证者质押 IKA

请通过以下链接完成至少 4000 万 IKA 的质押：https://ika-mainnet-validators-staking.pages.dev/

请确认您的 Validator ID 与 CLI 输出一致。

步骤 5：加入委员会

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

您将成为待定验证者，并于下一个 epoch 正式加入委员会。

步骤 6：运行验证者节点

目录结构示例：

/opt/ika/
├── bin/ika-node
├── config/validator.yaml
├── key-pairs/
│   ├── protocol.key
│   ├── network.key
│   ├── consensus.key
│   └── root-seed.key
└── db/                        # 运行时自动创建
    ├── authorities_db/
    └── consensus_db/

启动前，请编辑 validator.yaml 文件：

• 将 ika-dwallet-coordinator-object-id 设置为 deployed_contracts/mainnet/address.yaml 中对应值
• 确认配置项：sui-chain-identifier: mainnet
• 配置指标推送地址：push-url: "https://mainnet.metrics.ika-network.net:8443/publish/metrics"

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

日志输出：可通过设置 RUST_LOG 控制日志级别，设置 RUST_LOG_JSON=1 启用 JSON 格式日志输出。

步骤 7：验证运行状态

等待数分钟后，检查日志中是否出现如下内容：

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

该日志表明节点已正常运行。其余检查点仅在 MPC 会话期间或之后生成。

Package 与 Object ID

请始终从代码仓库中的权威源文件获取最新 ID：

• 主网：deployed_contracts/mainnet/address.yaml（GitHub）
• 测试网：deployed_contracts/testnet/address.yaml（GitHub）

密钥对

验证者核心配置要点

# 主网验证者必须包含：
sui-connector-config:
  sui-chain-identifier: mainnet
  sui-rpc-url: 'http://:9000'
  # 所有 ID 均需从 deployed_contracts/mainnet/address.yaml 获取
  ika-package-id: ''
  ika-dwallet-coordinator-object-id: ''
  # ... 其他 package/object ID

consensus-config:                         # 存在该配置项即触发验证者模式
  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"

管理 API（仅限 localhost）

curl http://127.0.0.1:1337/logging                    # 查看日志过滤器
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      # 恢复为环境变量设定值
curl http://127.0.0.1:1337/node-config                 # 查看配置（密钥字段已屏蔽）
curl http://127.0.0.1:1337/capabilities                # 查看节点能力

环境变量

各节点类型所启用的服务

关键运维注意事项

• 必须使用发布模式构建：涉及密码学操作时，务必使用 --release 参数构建
• 必须运行自有 Sui 全节点：需自行部署并确保其已完全同步（至少同步至最近两个 epoch）
• Package ID 必须严格匹配：配置文件中指定的合约 ID 必须与实际已部署合约一致
• 最低质押要求：需质押至少 4000 万 IKA 才能加入委员会
• 根种子密钥至关重要：请安全备份 root-seed.key；该密钥无法重新生成，亦不支持链上轮换
• 关注版本更新：请持续关注 #nodes-updates-mainnet 频道以获取新版本发布信息
• 灾难恢复机制：可使用 --run-with-range-epoch 或 --run-with-range-checkpoint 参数执行恢复
• 检查点固定（Checkpoint Pinning）：在 state-sync 配置中使用 pinned-dwallet-checkpoints 支持分叉恢复
• 优雅关闭：发送 SIGTERM 或 SIGINT 信号实现安全退出