Validator Commands

All validator operations are under the ika validator subcommand. Use ika validator --help for the full list.

ika validator [--client.config <PATH>] [--json] [-y] <SUBCOMMAND>

Most commands accept optional --gas-budget and --ika-sui-config flags. These are omitted below for brevity.

Setup

make-validator-info

Generate a validator info file with the required metadata.

ika validator make-validator-info \
  <NAME> <DESCRIPTION> <IMAGE_URL> <PROJECT_URL> <HOST_NAME> <GAS_PRICE> <SENDER_SUI_ADDRESS>

Writes protocol.key, network.key, consensus.key, root-seed.key and validator.info into the current directory. Existing key files and an existing root seed are reused, never overwritten; validator.info is rewritten on every run.

root-seed.key is the validator's MPC identity and the only file that cannot be regenerated — back it up before doing anything else. The node derives its full class-groups key material from this seed at boot and announces it to peers off chain; the seed itself is never published.

The mpc_data field inside validator.info is not key material. The on-chain mpc_data_bytes field is deprecated, so make-validator-info writes a fixed two-byte placeholder there. Note the activation precondition under become-candidate before staking a validator built this way.

config-env

Configure the Ika package and system object IDs for the CLI environment.

ika validator config-env \
  --ika-package-id <ID> \
  --ika-common-package-id <ID> \
  --ika-dwallet-2pc-mpc-package-id <ID> \
  --ika-system-package-id <ID> \
  --ika-system-object-id <ID>

Registration

become-candidate

Register as a validator candidate using a validator info file.

ika validator become-candidate <VALIDATOR_INFO_PATH>

The transaction submits a placeholder for the on-chain mpc_data_bytes field. That field is deprecated (ika#2119): a validator's real MPC key material is derived from root-seed.key and distributed off chain, through consensus announcements and peer-to-peer fetches. The placeholder exists only because the Move entry still requires the argument.

remove-candidate

Remove your validator candidacy.

ika validator remove-candidate --validator-cap-id <CAP_ID>

join-committee

Join the active validator committee.

ika validator join-committee --validator-cap-id <CAP_ID>

leave-committee

Leave the active validator committee.

ika validator leave-committee --validator-cap-id <CAP_ID>

Staking

stake-validator

Stake IKA tokens with a validator.

ika validator stake-validator \
  --validator-id <ID> \
  --ika-supply-id <ID> \
  --stake-amount <AMOUNT>

request-withdraw-stake

Request to withdraw staked tokens. The withdrawal is processed at the end of the epoch.

ika validator request-withdraw-stake --staked-ika-id <ID>

withdraw-stake

Withdraw staked tokens after a withdrawal request has been processed.

ika validator withdraw-stake --staked-ika-id <ID>

Commission

set-commission

Set the validator commission rate.

ika validator set-commission \
  --validator-operation-cap-id <CAP_ID> \
  --new-commission-rate <RATE>

collect-commission

Collect accumulated commission rewards.

ika validator collect-commission \
  --validator-commission-cap-id <CAP_ID> \
  [--amount <AMOUNT>]

Pricing

set-pricing-vote

Set the validator's pricing vote for network operations.

ika validator set-pricing-vote \
  --validator-operation-cap-id <CAP_ID> \
  --new-pricing-file-path <PATH>

get-current-pricing-info

Fetch current network pricing information.

ika validator get-current-pricing-info

Metadata

get-validator-metadata

Query validator information.

ika validator get-validator-metadata --validator-id <ID>

set-validator-name

Update the validator display name.

ika validator set-validator-name \
  --validator-operation-cap-id <CAP_ID> \
  --name <NAME>

set-validator-metadata

Update validator metadata (description, image URL, project URL, etc.).

ika validator set-validator-metadata \
  --validator-operation-cap-id <CAP_ID> \
  --metadata <METADATA>

Capability Verification

Verify that capability objects are valid and owned by the caller.

ika validator verify-validator-cap --validator-cap-id <CAP_ID>
ika validator verify-operation-cap --validator-operation-cap-id <CAP_ID>
ika validator verify-commission-cap --validator-commission-cap-id <CAP_ID>

Capability Rotation

Rotate capability objects for security. Generates a new capability and invalidates the old one.

ika validator rotate-operation-cap --validator-cap-id <CAP_ID>
ika validator rotate-commission-cap --validator-cap-id <CAP_ID>

Reporting

report-validator

Report a misbehaving validator.

ika validator report-validator \
  --validator-operation-cap-id <CAP_ID> \
  --reportee-id <ID>

undo-report-validator

Undo a previous validator report.

ika validator undo-report-validator \
  --validator-operation-cap-id <CAP_ID> \
  --reportee-id <ID>

Next Epoch Configuration

Update validator network configuration for the next epoch. All commands require --validator-operation-cap-id.

set-next-epoch-network-address

ika validator set-next-epoch-network-address \
  --validator-operation-cap-id <CAP_ID> \
  --network-address <ADDRESS>

set-next-epoch-p2p-address

ika validator set-next-epoch-p2p-address \
  --validator-operation-cap-id <CAP_ID> \
  --p2p-address <ADDRESS>

set-next-epoch-consensus-address

ika validator set-next-epoch-consensus-address \
  --validator-operation-cap-id <CAP_ID> \
  --consensus-address <ADDRESS>

set-next-epoch-protocol-pubkey

ika validator set-next-epoch-protocol-pubkey \
  --validator-operation-cap-id <CAP_ID> \
  <VALIDATOR_INFO_PATH>

set-next-epoch-network-pubkey

ika validator set-next-epoch-network-pubkey \
  --validator-operation-cap-id <CAP_ID> \
  <VALIDATOR_INFO_PATH>

set-next-epoch-consensus-pubkey

ika validator set-next-epoch-consensus-pubkey \
  --validator-operation-cap-id <CAP_ID> \
  <VALIDATOR_INFO_PATH>

set-next-epoch-mpc-data

ika validator set-next-epoch-mpc-data

Generates a new root-seed.key in the current directory. This command does not submit a Sui transaction — there is no on-chain MPC-data rotation, and the on-chain mpc_data_bytes field is deprecated (ika#2119). Install the new file at the validator's configured root-seed path and restart the validator; the node derives and announces its MPC data through consensus and P2P.

It refuses to run if root-seed.key already exists in the current directory. A root seed cannot be recovered once replaced, so move the old file aside deliberately if you really intend to rotate. To rotate a running validator without a gap in participation, follow Rotating the root seed below.

Rotating the root seed

Every MPC key the validator holds is derived from its root seed, and the network deals a validator's shares of each epoch's key material to the bundle it announced in the previous epoch. So the epoch you restart into still expects the OLD seed, whichever moment you restart in. Rotating at an epoch boundary does not avoid this — the boundary is exactly where the record that expects the old seed is written.

Keep participating through the rotation by telling the node which seed it was running:

1. Generate the new seed in an empty directory (the command refuses to overwrite an existing root-seed.key), then install it at the validator's configured root-seed-key-pair path. Keep the old file — do not delete it yet.
2. Add previous-root-seed-key-pair to the node config, pointing at the OLD seed file. It takes exactly the same form as root-seed-key-pair.
3. Restart the validator.

The node then runs the current epoch's MPC on the previous seed (the one the network dealt its shares to) while announcing the new seed's bundle, so the next reconfiguration deals the following epoch's shares to the new key. There is no gap in participation.

Once the rotation has landed the node logs, at WARN:

seed rotation COMPLETE — the certificate now names the current root seed's mpc_data bundle. Remove `previous-root-seed-key-pair` from the node config

Then, in this order:

1. Remove previous-root-seed-key-pair from the node config.
2. Restart the validator.
3. Only now delete the old seed file.

Nothing breaks if you leave the field in place — the node keeps resolving onto the current seed — but every epoch then re-derives the old seed's bundle, on the boot path, for a comparison that can no longer match; and a later rotation that swaps only root-seed-key-pair would leave this field pointing two seeds back, which is the previous_seed_mismatch state below. The same state is on the metric ika_dwallet_mpc_seed_identity_state{state="rotation_complete"}.

Deleting the file first is not fatal — a previous-root-seed-key-pair that names a file the node cannot read is treated exactly as if the field were absent, with a WARN naming the path and the read error. If the rotation had already completed (the usual case when you are tidying up) that changes nothing at all. If a rotation were still in flight, the validator would fall into the sit-out state below instead: visible on the metric and in the log, and self-healing at the next boundary — never a boot failure.

Rotating without the previous-seed field

The field is optional. If you rotate without it, the validator still starts and still runs consensus, checkpoints and every other duty — but it takes no part in MPC for the rest of the current epoch, because it cannot decrypt shares that were dealt to a key it no longer holds. It announces the new seed as usual, so it rejoins MPC by itself at the next epoch boundary.

While it is in that state it logs once at ERROR (naming the digests involved) and exports:

ika_dwallet_mpc_seed_identity_state{state="awaiting_certification"} 1

To rejoin the current epoch instead of waiting for the boundary, set previous-root-seed-key-pair to the seed that is currently certified — the one you rotated away from — and restart. The resolution runs at every start, so the repair takes effect immediately.

The field name is exactly previous-root-seed-key-pair, and it takes the same form as root-seed-key-pair. A misspelling is silently ignored — the node config deliberately does not reject unknown keys, because a hard parse failure on a fleet upgrade is worse than a typo. The tell is in the same ERROR line: it prints previous = "not configured" whenever the node saw no usable previous seed, whether the field was absent, misspelled, or unreadable.

One rotation per epoch

Rotate at most once per epoch. A second rotation before the first has been certified leaves neither the current nor the previous seed matching what the network expects, and the validator sits out MPC (state previous_seed_mismatch) until the certificate catches up — at most one extra epoch, since it keeps announcing the current seed throughout. The same state covers a wrong seed restored from a backup; the repair is identical: point previous-root-seed-key-pair at the certified seed, or restore that seed as root-seed-key-pair, and restart.