Validator Commands

Validator commands are used to manage, operate, and secure validator nodes. They handle tasks such as node setup, consensus participation, info and key management and governance.

1. Make Validator Info

Generate a validator.info file and 4 key pair files (account, network, authority, protocol). The network, authority and protocol keys will need to be copied over to the validator node and included in the YAML configuration of the node. See Validator Node Configuration

Args:

name - serves as a human-readable identifier for the validator.
description - provides additional context, description about the validator.
image-url - adds a visual identity to the validator, simplify visual regocnition in the explorers.
project-url - specifies where the validator's node is hosted or can be accessed.
host-name - specifies where the validator's node is hosted or can be accessed.

Command structure:

iota validator make-validator-info <name> <description> <image-url> <project-url> <host-name>

2. Become Candidate

Submit an on-chain transaction to become a validator candidate. The parameter is the file path to the validator.info generated by MakeValidatorInfo.

Args:

file - path to the validator.info file.
(Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator become-candidate <validator.info file path>

3. Join Validators

Once you collect enough staking amount, run this command to become a pending validator. A pending validator will become active and be eligible join the committee starting from next epoch.

Args:

(Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator join-validators

4. Leave Validators

Leave the validators (and potentially the committee) starting with the next epoch.

Args:

(Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator leave-validators

5. Display Metadata

Display metadata about the validator.

Args:

validator-address - address of the validator.
json - boolean indicating whether to format the metadata in JSON or not.

Command structure:

iota validator display-metadata $VALIDATOR_ADDRESS  --json true

Example of metadata fields with description in JSON format:

{
  "metadata": {
    "iota_address": "String representing the validator's unique address on the IOTA network.",
    "authority_pubkey_bytes": "Base64-encoded public key for authority purposes.",
    "network_pubkey_bytes": "Base64-encoded public key for network communication.",
    "protocol_pubkey_bytes": "Base64-encoded public key for protocol operations.",
    "proof_of_possession_bytes": "Base64-encoded proof that the validator possesses the private key associated with the public key.",
    "name": "Human-readable name of the validator.",
    "description": "Short description about the validator or its organization.",
    "image_url": "URL to the validator's logo or image.",
    "project_url": "URL to the validator's website.",
    "net_address": "Network address of the validator node.",
    "p2p_address": "P2P communication address for the validator.",
    "primary_address": "Primary address used for network operations.",
    "next_epoch": {
      "authority_pubkey_bytes": "Optional Base64-encoded authority public key for the next epoch.",
      "proof_of_possession": "Optional Base64-encoded proof of possession for the next epoch.",
      "network_pubkey_bytes": "Optional Base64-encoded network public key for the next epoch.",
      "protocol_pubkey_bytes": "Optional Base64-encoded protocol public key for the next epoch.",
      "net_address": "Optional network address for the next epoch.",
      "p2p_address": "Optional P2P address for the next epoch.",
      "primary_address": "Optional primary address for the next epoch."
    }
  },
  "voting_and_gas": {
    "voting_power": "Validator's voting power in the network.",
    "operation-cap-id": "Object ID representing the operation capability of the validator.",
    "gas_price": "Gas price set by the validator for the current epoch.",
    "commission_rate": "Commission rate charged by the validator.",
    "next_epoch": {
      "stake": "Stake amount for the next epoch.",
      "gas_price": "Gas price for the next epoch.",
      "commission_rate": "Commission rate for the next epoch."
    }
  },
  "staking_pool": {
    "staking_pool_id": "ID of the staking pool object associated with the validator.",
    "activation_epoch": "Epoch when the staking pool became active.",
    "deactivation_epoch": "Epoch when the staking pool was deactivated, if applicable.",
    "staking_pool_iota_balance": "Total number of IOTA tokens in the staking pool.",
    "rewards_pool": "Total rewards to be distributed at the end of the epoch.",
    "pool_token_balance": "Total number of pool tokens issued.",
    "pending": {
      "stake": "Pending stake amount for the current epoch.",
      "total_iota_withdraw": "Total IOTA withdrawn during the current epoch.",
      "pool_token_withdraw": "Total pool tokens withdrawn during the current epoch."
    },
    "exchange_rates": {
      "exchange_rates_id": "ID of the exchange rate table object.",
      "exchange_rates_size": "Number of exchange rates in the table."
    }
  }
}

6. Update Metadata

Update the validator metadata.

Submit an on-chain transaction to update name, description, image url, project url, netowork address, primary address, p2p address, network public key, protocol public key, authority public key.

Args:

(Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator update-metadata <key> <new-value>

7. Report Validator

Report or un-report a validator as bad or non-performant. Validator can be reported because of some malicious behavior or performance issues.

Validator reporting succeeds if all the following are satisfied:

both the reporter in cap and the input reportee_addr are active validators.
reporter and reportee not the same address.
the cap object is still valid. This function is idempotent.

Args:

operation-cap-id - validator's ID can be found by using the display-metadata subcommand. Optional when sender is reporter validator itself and it holds the Cap object. Required when sender is not the reporter validator itself.
reportee-address - the Iota Address of the validator is being reported or un-reported/
(Optional)undo-report - if true, undo an existing report.
(Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator report-validator $ADDRESS_OF_NON_PERFORMANT_VALIDATOR

8. Serialize Payload For Pop

Serialize the payload that is used to generate Proof of Possession. Proof of Possession - it's a verification process whereby assurance is obtained that the owner of a key pair actually has the private key associated with the public key. This is allows the signer to take the payload offline for an Authority protocol BLS keypair to sign.

Args:

account-address - authority account address encoded in hex with 0x prefix.
authority-public-key - authority public key encoded in hex.

Command structure:

iota validator serialize-payload-pop --account-address $ACCOUNT_ADDRESS --authority-public-key $BLS_PUBKEY

Command result:

Serialized payload: BQAAgAGZ8l72H4AyuRRjZGCYLFzG8TTvHdrnZlfyy/7B6/yNCXN0CA32/PDcuLxLDY4K9dgOu/8rTFmfVPQtYxLfwxQnYHjBzDR+u77FGYviWFE/OGuTDQLCdJqAPiMwlV69GhARERERFQTpNQ5jXWXNOMzSwClDTGo6SA2JR6m6ahWyFQAAAAAAAAAA

9. List

Get a list of the validators in the network. Use the display-metadata command to see the complete data for a validator.

Command structure:

iota validator list

Example of command result:

╭────────────────────────────────────────────────────────────────────┬───────────────────────────────┬──────────────────────┬───────────────╮
│ iota address                                                       │ name                          │ staking pool balance │ pending stake │
├────────────────────────────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼───────────────┤
│ 0xa276b4c076fff55588255630e9ee35cf0d07e8d80c78991cfd58b43b687b4206 │ IOTA Foundation 2             │ 35656599527382853    │ 0             │
│ 0xc571a9bb5da166b1de54ff90846399ddb63385c769e75cea4dce751e2fd29e55 │ Tangle Ecosystem Association  │ 35659211813708295    │ 10000000000   │
│ 0xb64051fe5048486c0a215ff1ec48dc63214528bcc4d00c27d151404dbd717ba4 │ IOTA Ecosystem DLT Foundation │ 35608690485959502    │ 10000000000   │
│ 0x392316417a23198afeeb80d9fec314c65162ab5ad18f8a4c3375d31deab29670 │ IOTA Foundation 1             │ 35608163183652856    │ 26500000000   │
│ 0x6d6416b3d8978e8821d875ec703daeefe0a2177037b0350bb2f760a426dcae03 │ Validator1                    │ 4356274051328678     │ 25000000000   │
│ 0x2e312d87e22b39d5bc3946060917e8be4a9d2076e7da8da07f016b07ad123d06 │ Validator2                    │ 4304476672123940     │ 25000000000   │
│ 0xdfb52cfe07f7c87f23cc829929797a5509bbc8693e4aa180d0dd8ed034855042 │ Validator3                    │ 3494574866394500     │ 0             │
│ 0xe1a4e6303a75ec1fa70e086368bebc3a615394d83307a056d4eabf729b6f6a5f │ Validator4                    │ 4183319150671519     │ 10000000000   │
╰────────────────────────────────────────────────────────────────────┴───────────────────────────────┴──────────────────────┴───────────────╯

IOTA Rebased Launch Playbook