Validator Node Tools

Use the Sui CLI validator commands to become a validator candidate, join or leave the committee, stake to your validator staking pool, display and update validator metadata, update your gas price, and report validator peers.

info

This tool supports only pending validators and active validators.

Prerequisites

• Complete all Sui installation prerequisites.

• Build the sui binary, which you need for the genesis ceremony. You can do this on any computer.

Click to open

View sui binary installation details.

1. Clone the git repo:

   $ git clone git@github.com:MystenLabs/sui.git && cd sui

2. Check out the commit to use for Testnet:

   $ git checkout testnet

3. Build sui binary

   $ cargo build --bin sui

4. Remember the path to your binary:

   $ export SUI_BINARY="$(pwd)/target/debug/sui"

• Set up your Sui account and CLI environment.

Click to open

View Sui account and CLI environment instructions.

• If this is the first time running this program, it asks you to provide a Sui full node server URL and a meaningful environment alias. It also generates a random key pair in sui.keystore and a config client.yaml. Swap in your validator account key if you already have one.

  By default, the client.yaml and sui.keystore files are located in ~/.sui/sui_config. For more information, refer to the Sui client CLI tutorial.

  $ sui client

• If you already set it up, just make sure:

  • rpc is correct in client.yaml.
  • active_address is correct in client.yaml.
  • sui.keystore contains your account key pair.

• Test your network connection and configuration by displaying your validator information:

$ sui validator display-metadata

Using Sui CLI

Use the Sui CLI to perform validator tasks.

Print help information

$ sui validator --help

How do I become a validator or join the committee?

To become a validator candidate, first run:

$ sui validator make-validator-info <name> <description> <image-url> <project-url> <host-name> <gas_price>

This generates a validator.info file and key pair files. The output of this command includes:

1. Four key pair files. a. If you follow this guide thoroughly, this key pair is actually copied from your sui.keystore file.
2. validator.info file that contains your validator information. Double-check that all information is correct.

caution

Set the permissions of the key pair files with the minimal visibility (chmod 600, for example) and store them securely. You need them when running the validator node.

Then run:

$ sui validator become-candidate path/to/validator.info

This submits an onchain transaction for you to become a validator candidate. The parameter is the file path to the validator.info file you generated in the previous step. Make sure the transaction succeeds (printed in the output).

At this point, you are a validator candidate and can start to accept self-staking and delegated staking.

If you have not already, start a full node now to catch up with the network. When you officially join the committee but are not fully up-to-date, you cannot make meaningful contributions to the network and might be subject to peer reporting. This imposes the risk of reduced staking rewards for you and your delegators.

Then, you must acquire 30M SUI and stake it to the validator staking pool. You can add Sui to the validator staking pool with the command:

$ sui client call --package 0x3 --module sui_system --function request_add_stake --args 0x5 <sui-object-id> <validator-address>

This creates a stake object (of type 0x3::staking_pool::StakedSui). You can withdraw this object with the following command:

$ sui client call --package 0x3 --module sui_system --function request_withdraw_stake --args 0x5 <stake-object-id>

tip

You cannot withdraw non-activated stake from an inactive validator. If that is the case, you can withdraw after the next epoch change when the stake becomes active.

After you have staked enough, run:

$ sui validator join-committee

Joining the committee makes you a pending validator. A pending validator becomes active and joins the committee starting from the next epoch.

To join the committee from start to finish, follow this sequence:

1. Run make-validator-info to generate your validator.info file and key pair files.
2. Run become-candidate to become a validator candidate.
3. Start a full node to catch up with the network.
4. Stake 30M SUI to your validator staking pool.
5. Run join-committee to become a pending validator.
6. Wait for the next epoch, when your pending validator becomes an active validator.

How do I leave the committee?

To leave the committee, run:

$ sui validator leave-committee

The network removes you from the committee starting from the next epoch.

Proof of possession: Generate the payload

Serialize the payload that you use to generate proof of possession. This allows the signer to take the payload offline for an authority protocol BLS key pair to sign.

$ sui validator serialize-payload-pop --account-address <account-address> --protocol-public-key <bls-public-key>

Serialized payload: <payload-to-sign>

Display validator metadata

Display metadata about your local validator:

$ sui validator display-metadata

Display metadata about another validator through its validator address:

$ sui validator display-metadata <validator-address>

How do I update validator metadata?

Run the following to see how to update each metadata field. Read the description carefully about when the change takes effect.

$ sui validator update-metadata --help

You can update the following onchain metadata:

• Name
• Description
• Image URL
• Project URL
• Network address
• P2P address
• Primary address
• Worker address
• Protocol public key
• Network public key
• Worker public key

info

Only the first four metadata listed above take effect immediately. The others change only after the next epoch. For those, restart the validator program immediately after the next epoch, with the new key files and updated validator.yaml config.

Make sure the new address is not behind a firewall.

Operation Cap

Operation Cap allows a validator to authorize another account to perform certain actions on behalf of this validator. Learn more about Operation Cap.

The Operation Cap holder (either the validator itself or the delegatee) updates its gas price and reports validator peers with the Operation Cap.

How do I update the gas price?

If your account is a validator and holds the Operation Cap, update the gas price with:

$ sui validator update-gas-price <gas-price>

If your account is a delegatee:

$ sui validator update-gas-price --operation-cap-id <operation-cap-id> <gas-price>

How do I report a validator?

If your account is a validator and holds the Operation Cap, report validator peers with:

$ sui validator report-validator <reportee-address>

Add the --undo-report false argument if you intend to undo an existing report.

Similarly, if your account is a delegatee, add the --operation-cap-id <operation-cap-id> option to the command.

If your account is a delegatee, run:

$ sui validator report-validator --operation-cap-id <operation-cap-id> <reportee-address>