sui validator

The sui validator command provides tools for managing validator operations on the Sui network.

Synopsis

sui validator [OPTIONS] <COMMAND>

Global Options

path

Path to client configuration file

string

The Sui environment to use

boolean

Return command outputs in JSON format

Commands

make-validator-info

Create validator information and generate key files.

sui validator make-validator-info <NAME> <DESCRIPTION> <IMAGE_URL> <PROJECT_URL> <HOST_NAME> <GAS_PRICE>

string

required

Validator name

string

required

Validator description

string

required

URL to validator image/logo

string

required

Validator project/website URL

string

required

Hostname for the validator

u64

required

Gas price in MIST

Example:

sui validator make-validator-info \
  "My Validator" \
  "A reliable Sui validator" \
  "https://example.com/logo.png" \
  "https://example.com" \
  "validator.example.com" \
  1000

Generated Files:

protocol.key - Protocol keypair (BLS12381)
account.key - Account keypair (from active address)
network.key - Network keypair (Ed25519)
worker.key - Worker keypair (Ed25519)
validator.info - Validator information YAML file

become-candidate

Request to become a validator candidate.

sui validator become-candidate [OPTIONS] <VALIDATOR_INFO_PATH>

path

required

Path to validator.info file generated by make-validator-info

u64

Gas budget for this transaction (default: 200000000 MIST)

boolean

Serialize transaction instead of executing it

Example:

sui validator become-candidate \
  ./validator.info \
  --gas-budget 200000000

join-committee

Request to join the active validator set.

sui validator join-committee [OPTIONS]

u64

Gas budget for this transaction (default: 200000000 MIST)

boolean

Serialize transaction instead of executing it

Prerequisites:

Must already be a validator candidate
Must meet stake requirements

Example:

sui validator join-committee --gas-budget 200000000

leave-committee

Request to leave the active validator set.

sui validator leave-committee [OPTIONS]

u64

Gas budget for this transaction (default: 200000000 MIST)

boolean

Serialize transaction instead of executing it

Prerequisites:

Must be an active validator

Example:

sui validator leave-committee --gas-budget 200000000

display-metadata

Display validator metadata.

sui validator display-metadata [OPTIONS]

SuiAddress

Validator address to query. Uses active address if not specified

boolean

Output in JSON format (default: true)

Example:

# Display metadata for active address
sui validator display-metadata

# Display metadata for specific validator
sui validator display-metadata \
  --validator-address 0xVALIDATOR_ADDRESS

Output includes:

Validator status (Active/Pending)
Name, description, URLs
Network addresses
Public keys
Gas price
Commission rate
Staking pool information
Operation cap ID

update-metadata

Update validator metadata.

sui validator update-metadata <METADATA_TYPE> [OPTIONS]

Metadata Types

name - Update validator name (effective immediately):

sui validator update-metadata name "New Name" --gas-budget 10000000

description - Update description (effective immediately):

sui validator update-metadata description "New description" --gas-budget 10000000

image-url - Update image URL (effective immediately):

sui validator update-metadata image-url "https://example.com/new-logo.png" --gas-budget 10000000

project-url - Update project URL (effective immediately):

sui validator update-metadata project-url "https://newsite.example.com" --gas-budget 10000000

network-address - Update network address (effective next epoch):

sui validator update-metadata network-address "/dns/validator.example.com/tcp/8080/http" --gas-budget 10000000

primary-address - Update primary address (effective next epoch):

sui validator update-metadata primary-address "/dns/validator.example.com/udp/8081" --gas-budget 10000000

worker-address - Update worker address (effective next epoch):

sui validator update-metadata worker-address "/dns/validator.example.com/udp/8082" --gas-budget 10000000

p2p-address - Update P2P address (effective next epoch):

sui validator update-metadata p2p-address "/dns/validator.example.com/udp/8084" --gas-budget 10000000

network-pub-key - Update network public key (effective next epoch):

sui validator update-metadata network-pub-key --network-key-path ./new-network.key --gas-budget 10000000

worker-pub-key - Update worker public key (effective next epoch):

sui validator update-metadata worker-pub-key --worker-key-path ./new-worker.key --gas-budget 10000000

protocol-pub-key - Update protocol public key and proof of possession (effective next epoch):

sui validator update-metadata protocol-pub-key --protocol-key-path ./new-protocol.key --gas-budget 10000000

update-gas-price

Update the gas price used to calculate Reference Gas Price.

sui validator update-gas-price [OPTIONS] <GAS_PRICE>

u64

required

New gas price in MIST

ObjectID

Validator’s OperationCap ID. Required if sender is not the validator itself

u64

Gas budget for this transaction (default: 200000000 MIST)

boolean

Serialize transaction instead of executing it

Example:

# Update as validator
sui validator update-gas-price 1000 --gas-budget 10000000

# Update using operation cap
sui validator update-gas-price 1000 \
  --operation-cap-id 0xCAP_ID \
  --gas-budget 10000000

report-validator

Report or un-report a validator.

sui validator report-validator [OPTIONS] <REPORTEE_ADDRESS>

SuiAddress

required

Sui address of the validator being reported

ObjectID

Reporter validator’s OperationCap ID. Required if sender is not the reporter validator

boolean

If true, undo an existing report

u64

Gas budget for this transaction (default: 200000000 MIST)

boolean

Serialize transaction instead of executing it

Prerequisites:

Reporter must be an active validator

Example:

# Report a validator
sui validator report-validator 0xREPORTEE_ADDRESS --gas-budget 10000000

# Undo a report
sui validator report-validator \
  0xREPORTEE_ADDRESS \
  --undo-report \
  --gas-budget 10000000

serialize-payload-pop

Serialize the payload for generating Proof of Possession.

sui validator serialize-payload-pop [OPTIONS]

SuiAddress

required

Authority account address (hex with 0x prefix)

AuthorityPublicKeyBytes

required

Authority protocol public key (hex encoded)

Example:

sui validator serialize-payload-pop \
  --account-address 0xACCOUNT \
  --protocol-public-key 0xPROTOCOL_KEY

Use case: Take the payload offline to sign with an Authority protocol keypair.

display-gas-price-update-raw-txn

Display the serialized data of a gas price update transaction.

sui validator display-gas-price-update-raw-txn [OPTIONS]

SuiAddress

required

Address of the transaction sender

ObjectID

required

Object ID of validator’s OperationCap

u64

required

Gas price to be set

u64

Gas budget for this transaction (default: 200000000 MIST)

Example:

sui validator display-gas-price-update-raw-txn \
  --sender-address 0xSENDER \
  --operation-cap-id 0xCAP_ID \
  --new-gas-price 1000 \
  --gas-budget 10000000

register-bridge-committee

sui validator register-bridge-committee [OPTIONS]

path

required

Path to Bridge Authority Key file (secp256k1)

string

required

Bridge authority URL for signature collection

boolean

default:"false"

Only print unsigned transaction without executing (for offline signing)

SuiAddress

Must be present if —print-only is true

u64

Gas budget for this transaction (default: 200000000 MIST)

Prerequisites:

Must be an active validator
URL must use http or https scheme

Example:

# Register and execute
sui validator register-bridge-committee \
  --bridge-authority-key-path ./bridge.key \
  --bridge-authority-url "https://bridge.example.com" \
  --gas-budget 200000000

# Generate unsigned transaction for offline signing
sui validator register-bridge-committee \
  --bridge-authority-key-path ./bridge.key \
  --bridge-authority-url "https://bridge.example.com" \
  --print-only \
  --validator-address 0xVALIDATOR

update-bridge-committee-node-url

Update Sui native bridge committee node URL.

sui validator update-bridge-committee-node-url [OPTIONS]

string

required

New node URL to register

boolean

default:"false"

Only print unsigned transaction without executing

SuiAddress

Must be present if —print-only is true

u64

Gas budget for this transaction (default: 200000000 MIST)

Prerequisites:

Must be a bridge committee member

Example:

sui validator update-bridge-committee-node-url \
  --bridge-authority-url "https://new-bridge.example.com" \
  --gas-budget 200000000

Validator Lifecycle

Becoming a Validator

# 1. Generate validator information
sui validator make-validator-info \
  "My Validator" \
  "Reliable Sui validator" \
  "https://example.com/logo.png" \
  "https://example.com" \
  "validator.example.com" \
  1000

# 2. Become a candidate
sui validator become-candidate ./validator.info

# 3. Stake sufficient SUI (via staking transactions)
# ... stake transactions ...

# 4. Join the committee
sui validator join-committee

Operating a Validator

# Check validator status
sui validator display-metadata

# Update gas price
sui validator update-gas-price 1000

# Update metadata
sui validator update-metadata name "Updated Name"

# Report misbehaving validators
sui validator report-validator 0xBAD_VALIDATOR

Leaving the Validator Set

# 1. Request to leave
sui validator leave-committee

# 2. Wait for next epoch
# Your validator will be removed from the active set

# 3. Optionally unstake and withdraw
# ... unstaking transactions ...

Validator Metadata Updates

Immediate vs Next Epoch

Some metadata updates take effect immediately, while others take effect in the next epoch: Immediate:

Name
Description
Image URL
Project URL

Next Epoch:

Network address
Primary address
Worker address
P2P address
Network public key
Worker public key
Protocol public key

Key Rotation

# 1. Generate new keys
sui keytool generate ed25519
# Save as new-network.key

# 2. Update network key (effective next epoch)
sui validator update-metadata network-pub-key \
  --network-key-path ./new-network.key

# 3. Update your validator node configuration
# Replace network.key with new-network.key

# 4. Restart validator after epoch boundary

Bridge Committee

Joining Bridge Committee

# 1. Generate secp256k1 key for bridge
sui keytool generate secp256k1
# Save as bridge-authority.key

# 2. Set up bridge authority service
# Configure bridge service to use the key and listen on the URL

# 3. Register with the network
sui validator register-bridge-committee \
  --bridge-authority-key-path ./bridge-authority.key \
  --bridge-authority-url "https://bridge.validator.example.com"

Updating Bridge URL

sui validator update-bridge-committee-node-url \
  --bridge-authority-url "https://new-bridge.validator.example.com"

Gas Price Management

The Reference Gas Price (RGP) is calculated based on all active validators’ gas prices. As a validator:

# Check current gas price
sui validator display-metadata --json | jq '.gasPrice'

# Update gas price based on network conditions
sui validator update-gas-price 1000

# The RGP will be recalculated at the next epoch

Gas Price Considerations:

Set competitive rates to attract stake
Consider operational costs
Monitor network RGP trends
Updates take effect in the next epoch

Validator Reporting

Validators can report peers for misbehavior:

# Report a validator
sui validator report-validator 0xMISBEHAVING_VALIDATOR

# Undo a report if it was made in error
sui validator report-validator \
  0xVALIDATOR \
  --undo-report

Reporting impacts:

Accumulating reports may affect validator reputation
Severe misbehavior can lead to removal from the active set
Only active validators can report

Offline Transaction Signing

For enhanced security, generate transactions on an online machine and sign offline:

# Online machine: generate unsigned transaction
sui validator update-gas-price 1000 \
  --serialize-unsigned-transaction

# Copy TX_BYTES to offline machine

# Offline machine: sign transaction
sui keytool sign \
  --address validator_address \
  --data <TX_BYTES>

# Copy signature to online machine

# Online machine: execute
sui client execute-signed-tx \
  --tx-bytes <TX_BYTES> \
  --signatures <SIGNATURE>

Best Practices

Secure key storage: Use hardware security modules (HSM) for protocol keys
Backup keys: Maintain secure, offline backups of all validator keys
Monitor uptime: Ensure high availability to avoid penalties
Test updates: Use testnet to validate metadata and key updates
Gradual gas price changes: Avoid sudden price changes
Regular metadata review: Keep validator information current
Bridge security: Secure bridge authority endpoints

Troubleshooting

Cannot Join Committee

# Check validator status
sui validator display-metadata

# Verify you're a candidate
# Verify sufficient stake
# Check epoch timing

Metadata Update Not Applying

# Check transaction status
sui client tx-block <DIGEST>

# For next-epoch updates, wait for epoch boundary
# Check current epoch: sui client chain-identifier

Key Rotation Issues

# Verify key file format
sui keytool show ./new-key.key

# Ensure update transaction succeeded
# Wait for next epoch before using new keys

​Synopsis

​Global Options

​Commands

​make-validator-info

​become-candidate

​join-committee

​leave-committee

​display-metadata

​update-metadata

​Metadata Types

​update-gas-price

​report-validator

​serialize-payload-pop

​display-gas-price-update-raw-txn

​register-bridge-committee

​update-bridge-committee-node-url

​Validator Lifecycle

​Becoming a Validator

​Operating a Validator

​Leaving the Validator Set

​Validator Metadata Updates

​Immediate vs Next Epoch

​Key Rotation

​Bridge Committee

​Joining Bridge Committee

​Updating Bridge URL

​Gas Price Management

​Validator Reporting

​Offline Transaction Signing

​Best Practices

​Troubleshooting

​Cannot Join Committee

​Metadata Update Not Applying

​Key Rotation Issues

Synopsis

Global Options

Commands

make-validator-info

become-candidate

join-committee

leave-committee

display-metadata

update-metadata

Metadata Types

update-gas-price

report-validator

serialize-payload-pop

display-gas-price-update-raw-txn

register-bridge-committee

update-bridge-committee-node-url

Validator Lifecycle

Becoming a Validator

Operating a Validator

Leaving the Validator Set

Validator Metadata Updates

Immediate vs Next Epoch

Key Rotation

Bridge Committee

Joining Bridge Committee

Updating Bridge URL

Gas Price Management

Validator Reporting

Offline Transaction Signing

Best Practices

Troubleshooting

Cannot Join Committee

Metadata Update Not Applying

Key Rotation Issues