The sui validator command provides tools for managing validator operations on the Sui network.
Synopsis
sui validator [OPTIONS] <COMMAND>
Global Options
Path to client configuration file
The Sui environment to use
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>
URL to validator image/logo
Validator project/website URL
Hostname for the validator
sui validator make-validator-info \
"My Validator" \
"A reliable Sui validator" \
"https://example.com/logo.png" \
"https://example.com" \
"validator.example.com" \
1000
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 to validator.info file generated by make-validator-info
Gas budget for this transaction (default: 200000000 MIST)
--serialize-unsigned-transaction
Serialize transaction instead of executing it
sui validator become-candidate \
./validator.info \
--gas-budget 200000000
join-committee
Request to join the active validator set.
sui validator join-committee [OPTIONS]
Gas budget for this transaction (default: 200000000 MIST)
--serialize-unsigned-transaction
Serialize transaction instead of executing it
- 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]
Gas budget for this transaction (default: 200000000 MIST)
--serialize-unsigned-transaction
Serialize transaction instead of executing it
- Must be an active validator
Example:
sui validator leave-committee --gas-budget 200000000
sui validator display-metadata [OPTIONS]
Validator address to query. Uses active address if not specified
Output in JSON format (default: true)
# Display metadata for active address
sui validator display-metadata
# Display metadata for specific validator
sui validator display-metadata \
--validator-address 0xVALIDATOR_ADDRESS
- Validator status (Active/Pending)
- Name, description, URLs
- Network addresses
- Public keys
- Gas price
- Commission rate
- Staking pool information
- Operation cap ID
Update validator metadata.
sui validator update-metadata <METADATA_TYPE> [OPTIONS]
sui validator update-metadata name "New Name" --gas-budget 10000000
sui validator update-metadata description "New description" --gas-budget 10000000
sui validator update-metadata image-url "https://example.com/new-logo.png" --gas-budget 10000000
sui validator update-metadata project-url "https://newsite.example.com" --gas-budget 10000000
sui validator update-metadata network-address "/dns/validator.example.com/tcp/8080/http" --gas-budget 10000000
sui validator update-metadata primary-address "/dns/validator.example.com/udp/8081" --gas-budget 10000000
sui validator update-metadata worker-address "/dns/validator.example.com/udp/8082" --gas-budget 10000000
sui validator update-metadata p2p-address "/dns/validator.example.com/udp/8084" --gas-budget 10000000
sui validator update-metadata network-pub-key --network-key-path ./new-network.key --gas-budget 10000000
sui validator update-metadata worker-pub-key --worker-key-path ./new-worker.key --gas-budget 10000000
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>
Validator’s OperationCap ID. Required if sender is not the validator itself
Gas budget for this transaction (default: 200000000 MIST)
--serialize-unsigned-transaction
Serialize transaction instead of executing it
# 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>
Sui address of the validator being reported
Reporter validator’s OperationCap ID. Required if sender is not the reporter validator
If true, undo an existing report
Gas budget for this transaction (default: 200000000 MIST)
--serialize-unsigned-transaction
Serialize transaction instead of executing it
- 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]
Authority account address (hex with 0x prefix)
--protocol-public-key
AuthorityPublicKeyBytes
required
Authority protocol public key (hex encoded)
sui validator serialize-payload-pop \
--account-address 0xACCOUNT \
--protocol-public-key 0xPROTOCOL_KEY
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]
Address of the transaction sender
Object ID of validator’s OperationCap
Gas budget for this transaction (default: 200000000 MIST)
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
Register as a Sui native bridge committee member.
sui validator register-bridge-committee [OPTIONS]
--bridge-authority-key-path
Path to Bridge Authority Key file (secp256k1)
Bridge authority URL for signature collection
Only print unsigned transaction without executing (for offline signing)
Must be present if —print-only is true
Gas budget for this transaction (default: 200000000 MIST)
- 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]
Only print unsigned transaction without executing
Must be present if —print-only is true
Gas budget for this transaction (default: 200000000 MIST)
- 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 ...
- 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
- 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
- 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
# 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