IOTA Validator CLI
The IOTA CLI validator command provides command-level access to validator features of the IOTA network.
Commands
Typing iota validator --help into your terminal or console displays the following information on available commands.
A tool for validators and validator candidates
Usage: iota validator [OPTIONS] [COMMAND]
Commands:
make-validator-info Generate a `validator.info` file and 4 key pair files (account, network, authority, protocol)
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`
join-validators Once you collect enough staking amount, run this command to become an active validator. It will become active and eligible to join the committee starting from next epoch
leave-validators Leave active validators (and possibly the committee) starting with the next epoch
display-metadata Display metadata about the validator
update-metadata Update the validator metadata
report-validator Report or un-report a validator as bad or non-performant
serialize-payload-pop Serialize the payload that is used to generate Proof of Possession. This is useful to take the payload offline for an Authority protocol keypair to sign
register-bridge-committee IOTA native bridge committee member registration
update-bridge-committee-node-url Update IOTA native bridge committee node url
list Get a list of the validators in the network. Use the `display-metadata` command to see the complete data for a validator
help Print this message or the help of the given subcommand(s)
Options:
--client.config <CONFIG> Sets the file storing the state of our user accounts (an empty one will be created if missing)
--json Return command outputs in json format
-y, --yes
-h, --help Print help
Examples
The following examples demonstrate some of the most often used commands.
Display the validator information
$ iota validator display-metadata 0x8359fff1dc629bad933cf1781564a6d98a7277ac391e70bd0af7e050b3927573 --json true
Toggle output
0x8359fff1dc629bad933cf1781564a6d98a7277ac391e70bd0af7e050b3927573's validator status: Active
{
"iotaAddress": "0x8359fff1dc629bad933cf1781564a6d98a7277ac391e70bd0af7e050b3927573",
"authorityPubkeyBytes": "lUhBLNuc6bosReVt+jv+BXZboiOjZQyT5tfJbMS1StEyBmPmF7TTuGl2vy/S8zKWGSEbPKPapz46phPZgFRy7TjXEdt6XjBHf/bkEg1atucEzAMPT/6cIx2G5We7wlXK",
"networkPubkeyBytes": "1JiYHZHJFtuxim7woWhPGdBIe4QPoyvLVgpCRRZwUWg=",
"protocolPubkeyBytes": "XhjH8q+isy4LP4GS1txLJYl+KQ9kV7b5dnu6C2x4XIk=",
"proofOfPossessionBytes": "ovRMD5206HPBOoTfx+TgB5NXIKpbra4AuJRVGFSaaFbP2hAAZBDWpP1OD0Nyackf",
"name": "validator-2.r.iota-rebased-testnet",
"description": "validator-2.r.iota-rebased-testnet",
"imageUrl": "",
"projectUrl": "",
"netAddress": "/dns/validator-2.r.iota-rebased-testnet.iota.cafe/tcp/8080/http",
"p2pAddress": "/dns/validator-2.r.iota-rebased-testnet.iota.cafe/udp/8084",
"primaryAddress": "/dns/validator-2.r.iota-rebased-testnet.iota.cafe/udp/8081",
"nextEpochAuthorityPubkeyBytes": null,
"nextEpochProofOfPossession": null,
"nextEpochNetworkPubkeyBytes": null,
"nextEpochProtocolPubkeyBytes": null,
"nextEpochNetAddress": null,
"nextEpochP2pAddress": null,
"nextEpochPrimaryAddress": null,
"votingPower": "2500",
"operationCapId": "0xa88b6ac306932c77f7bc228690c35104ab8b4cd4a174ace5296d01581ae4f2d5",
"gasPrice": "1000",
"commissionRate": "200",
"nextEpochStake": "2958750000000000",
"nextEpochGasPrice": "1000",
"nextEpochCommissionRate": "200",
"stakingPoolId": "0x4fb963ec2cb115ae2e13818e38f71d3ec8c6c2b892000fe6c119bf518b9b1a85",
"stakingPoolActivationEpoch": "0",
"stakingPoolDeactivationEpoch": null,
"stakingPoolIotaBalance": "2958750000000000",
"rewardsPool": "939575000000000",
"poolTokenBalance": "2015128472804164",
"pendingStake": "0",
"pendingTotalIotaWithdraw": "0",
"pendingPoolTokenWithdraw": "0",
"exchangeRatesId": "0x456fd6d5a041d8c5de2998b4bf8a0cff2217132ae5de0c7017975fa82470ed43",
"exchangeRatesSize": "6"
}
Update validator metadata
iota validator update-metadata <key> <new-value>
iota validator update-metadata name new-validator-name
Toggle output
----- Transaction Digest ----
HyVwvTSdHVFibs3du6S89mQ5kNC6FvaMeczAPguNYjss
----- Transaction Data ----
╭─────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Transaction Data │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Sender: 0x111111111504e9350e635d65cd38ccd2c029434c6a3a480d8947a9ba6a15b215 │
│ Gas Owner: 0x111111111504e9350e635d65cd38ccd2c029434c6a3a480d8947a9ba6a15b215 │
│ Gas Budget: 200000000 NANOS │
│ Gas Price: 1000 NANOS │
│ Gas Payment: │
│ ┌── │
│ │ ID: 0x2ed4692a6b32266c21955db5fe4ed85fa1478c17cee9744c68cebdc034344181 │
│ │ Version: 26 │
│ │ Digest: 7EWayTrApAUjaGNTvS77H7tUPeuHxQ1RFZ4rnxpej633 │
│ └── │
│ │
│ Transaction Kind: Programmable │
│ ╭─────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Input Objects │ │
│ ├─────────────────────────────────────────────────────── ──────────────────────────────────────┤ │
│ │ 0 Shared Object ID: 0x0000000000000000000000000000000000000000000000000000000000000005 │ │
│ │ 1 Pure Arg: Type: vector<u8>, Value: "new-validator-name" │ │
│ ╰─────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭──────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Commands │ │
│ ├──────────────────────────────────────────────────────────────────────────────────┤ │
│ │ 0 MoveCall: │ │
│ │ ┌ │ │
│ │ │ Function: update_validator_name │ │
│ │ │ Module: iota_system │ │
│ │ │ Package: 0x0000000000000000000000000000000000000000000000000000000000000003 │ │
│ │ │ Arguments: │ │
│ │ │ Input 0 │ │
│ │ │ Input 1 │ │
│ │ └ │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────╯ │
│ │
│ Signatures: │
│ 79tpsgiXFX65rUIFHhqlhBTj6Us59adQXfTdKhhCLuo1OvG6oyJkXzx4VEA17u/yqSVxFkaGYp1LuMbFL4cNCQ== │
│ │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
----- Transaction Effects ----
╭───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Transaction Effects │
├────────────────────────────────────────────────── ─────────────────────────────────────────────────┤
│ Digest: HyVwvTSdHVFibs3du6S89mQ5kNC6FvaMeczAPguNYjss │
│ Status: Success │
│ Executed Epoch: 39 │
│ Mutated Objects: │
│ ┌── │
│ │ ID: 0x0000000000000000000000000000000000000000000000000000000000000005 │
│ │ Owner: Shared │
│ │ Version: 112 │
│ │ Digest: 5BoJQhssNo5smzUddV8rRvaDCGiWvZotVmx3cbh26q4K │
│ └── │
│ ┌── │
│ │ ID: 0x2ed4692a6b32266c21955db5fe4ed85fa1478c17cee9744c68cebdc034344181 │
│ │ Owner: Account Address ( 0x111111111504e9350e635d65cd38ccd2c029434c6a3a480d8947a9ba6a15b215 ) │
│ │ Version: 112 │
│ │ Digest: DNZiGcn27ByW5QY3ZbSpX2CjwQyRkVxX6R7i8CKTZ55h │
│ └── │
│ ┌── │
│ │ ID: 0x5b890eaf2abcfa2ab90b77b8e6f3d5d8609586c3e583baf3dccd5af17edf48d1 │
│ │ Owner: Object ID: ( 0x0000000000000000000000000000000000000000000000000000000000000005 ) │
│ │ Version: 112 │
│ │ Digest: 3aYHFk32MvmVmC3EoBkxFCxUAQaoNUd2LNRBYy4DYTDq │
│ └── │
│ Shared Objects: │
│ ┌── │
│ │ ID: 0x0000000000000000000000000000000000000000000000000000000000000005 │
│ │ Version: 111 │
│ │ Digest: 7BxrwgHL3v2WEzt1Fxa93HL27n7e5fhckCMmuhdeHra7 │
│ └── │
│ Gas Object: │
│ ┌── │
│ │ ID: 0x2ed4692a6b32266c21955db5fe4ed85fa1478c17cee9744c68cebdc034344181 │
│ │ Owner: Account Address ( 0x111111111504e9350e635d65cd38ccd2c029434c6a3a480d8947a9ba6a15b215 ) │
│ │ Version: 112 │
│ │ Digest: DNZiGcn27ByW5QY3ZbSpX2CjwQyRkVxX6R7i8CKTZ55h │
│ └── │
│ Gas Cost Summary: │
│ Storage Cost: 35697200 NANOS │
│ Computation Cost: 1000000 NANOS │
│ Storage Rebate: 35636400 NANOS │
│ Non-refundable Storage Fee: 0 NANOS │
│ │
│ Transaction Dependencies: │
│ 2QvVh6TYRBLgsB2PT3388hEvAoRmNsYkLsjyz2KnG6fH │
│ 6grSKcoWbjpzH8xD1rrqPzLqkccf5NW9t1nV4McEsXbE │
│ HHRccKiYZ9HP9dDdDv4bNQRUtuw8P9e3ZFPpr3X6c9Zb │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
Report a bad / non-performant validator
$ iota validator report-validator 0xf...3d9
Toggle output
----- Transaction Digest ----
8jVYrpuRBmdSLP37MsQGRqUqE3kE2m8XiSS4TG4aJwXf
----- Transaction Data ----
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Transaction Data │
├──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Sender: 0xf...3d9 │
│ Gas Owner: 0xf...3d9 │
│ Gas Budget: 200000000 NANOS │
│ Gas Price: 1000 NANOS │
│ Gas Payment: │
│ ┌── │
│ │ ID: 0x8...19e │
│ │ Version: 16 │
│ │ Digest: 4WQp6FYctutMFzf6f2EX68xut71AMubewJ6c7GxpzX7e │
│ └── │
│ │
│ Transaction Kind : Programmable │
│ Inputs: [Object(SharedObject { object_id: 0x0...005, initial_shared_version: SequenceNumber(1), mutable: true }), Object(ImmOrOwnedObject { object_id: 0x4...dbe, version: SequenceNumber(16), digest: o#4yDkecsKPe8SnacWdECmq1yVDt7MzvpXCxbRGs74PGaB }), Pure(IOTAPureValue { value_type: Some(Address), value: "0xf...3d9" })] │
│ Commands: [ │
│ MoveCall(0x0...003::iota_system::report_validator(Input(0),Input(1),Input(2))), │
│ ] │
│ │
│ │
│ Signatures: │
│ 7lJ9ezA1qjGk7nyFCESgLlg/tkVSy46dDkRgJzwgWP3qA+kAjJV8YVWFjJf2r6aLgWgCZCKnka9bkcp1V5jBAA== │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
----- Transaction Effects ----
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Transaction Effects │
├───────────── ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Digest: 8jVYrpuRBmdSLP37MsQGRqUqE3kE2m8XiSS4TG4aJwXf │
│ Status: Failure { error: "MoveAbort(MoveLocation { module: ModuleId { address: 0000000000000000000000000000000000000000000000000000000000000003, name: Identifier(\"iota_system_state_inner\") }, function: 16, instruction: 12, function_name: Some(\"report_validator_impl\") }, 3) in command 0" } │
│ Executed Epoch: 8 │
│ │
│ Mutated Objects: │
│ ┌── │
│ │ ID: 0x0...005 │
│ │ Owner: Shared │
│ │ Version: 25 │
│ │ Digest: 5N5zyTyFCqAkyz44FGrpr6cYdXcwk4eUCHKzyAZqehMB │
│ └── │
│ ┌── │
│ │ ID: 0x4...dbe │
│ │ Owner: Account Address ( 0xf...3d9 ) │
│ │ Version: 25 │
│ │ Digest: HCEr5bcJhKo5jfRx2gsXxGSkpcq6tm8nFGSxxwoPpkNz │
│ └── │
│ ┌── │
│ │ ID: 0x8...19e │
│ │ Owner: Account Address ( 0xf...3d9 ) │
│ │ Version: 25 │
│ │ Digest: BTzMmVABwEKXoiLsTZ79Li97Eo6HPtNtWTvib8Eq1yrH │
│ └── │
│ │
│ Shared Objects: │
│ ┌── │
│ │ ID: 0x0...005 │
│ │ Version: 24 │
│ │ Digest: BiS4pKAX3KGXbJrk4oZijy6ggKHDZJd9qPUDWxLEoNR1 │
│ └── │
│ │
│ Gas Object: │
│ ┌── │
│ │ ID: 0x8...19e │
│ │ Owner: Account Address ( 0xf...3d9 ) │
│ │ Version: 25 │
│ │ Digest: BTzMmVABwEKXoiLsTZ79Li97Eo6HPtNtWTvib8Eq1yrH │
│ └── │
│ │
│ Gas Cost Summary: │
│ Storage Cost: 4195200 │
│ Computation Cost: 1000000 │
│ Storage Rebate: 31164408 │
│ Non-refundable Storage Fee: 314792 │
│ │
│ Transaction Dependencies: │
│ 2gqHgPZbjTkDWM9GnVuWU5kT9z2SWN2ggwK3ryxf8aUX │
│ A8z83EqjmgwRNFV6sme6A5tTTTQPjiLgiW76neyvhLud │
│ B8p4pVC5pzFQRVpZ73nZfAWMt7sL4iH4x4AbDviYWuzF │
╰────────────────────────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Generate the Payload To Create PoP
Serialize the payload that is used to generate Proof of Possession. This allows the signer to take the payload offline for an Authority BLS keypair to sign.
$ iota validator serialize-payload-pop --account-address $ACCOUNT_ADDRESS --authority-public-key $BLS_PUBKEY
Serialized payload: BQAAgAGZ8l72H4AyuRRjZGCYLFzG8TTvHdrnZlfyy/7B6/yNCXN0CA32/PDcuLxLDY4K9dgOu/8rTFmfVPQtYxLfwxQnYHjBzDR+u77FGYviWFE/OGuTDQLCdJqAPiMwlV69GhARERERFQTpNQ5jXWXNOMzSwClDTGo6SA2JR6m6ahWyFQAAAAAAAAAA
Help
Each command has its own help section. For example iota validator report-validator --help will display the following prompt:
$ iota validator report-validator --help
Report or un-report a validator as bad or non-performant
Usage: iota validator report-validator [OPTIONS] <reportee-address>
Arguments:
<reportee-address> The IOTA Address of the validator is being reported or un-reported
Options:
--operation-cap-id <operation-cap-id> Optional when sender is reporter validator itself and it holds the Cap object. Required when sender is not the reporter validator itself. Validator's
OperationCap ID can be found by using the `display-metadata` subcommand
--undo-report <undo-report> If true, undo an existing report [possible values: true, false]
--json Return command outputs in json format
-h, --help Print help
-V, --version Print version