Skip to main content

Securing A Validator

Each validator candidate is encouraged to run its operations independently, as diverse setups increase the resilience of the network. Validator candidates should commence their setup phase now in order to be on time for launch.

Key Management - Hardware Wallets & HSM​

It is mission critical that an attacker cannot steal a validator's key. If this is possible, it puts the entire stake delegated to the compromised validator at risk. Hardware security modules and hardware wallets are important strategies for mitigating this risk.

Hardware Wallet Requirements​

Hardware wallets (such as Ledger devices) provide secure key storage where:

  • Private keys are generated and stored in encrypted hardware
  • Transaction signing occurs within the device
  • Private keys never leave the hardware wallet
  • A 24-word mnemonic phrase controls access to all keys
Important Limitations
  • Cannot migrate existing validators: Hardware wallet integration is only possible when creating new validators
  • Backup is critical: Loss of the mnemonic phrase results in permanent loss of validator control
  • Offline storage required: Store mnemonic phrases securely offline in multiple locations

HSM Support​

HSM modules must support ed25519 signatures for CrossFi Chain. The YubiHSM2 supports ed25519 and this yubikey library is available. The YubiHSM can protect a private key but cannot ensure in a secure setting that it won't sign the same block twice.

Ledger Integration​

Ledger devices support CrossFi validator operations through the Cosmos application. The Ledger app can store recent blocks and helps mitigate double signing attacks.

Supported Operations:

  • Account key management (validator operations, rewards, delegation)
  • Transaction signing with hardware confirmation
  • Address verification on device

For detailed setup instructions, see the Hardware Wallet Setup Guide below.

Types of Keys​

CrossFi validators use two distinct types of private keys, each serving different purposes:

Account Key (Validator Operator Key)​

  • Purpose: Controls the validator account for operational tasks
  • Usage:
    • Receiving staking rewards and commissions
    • Updating validator information (description, commission rate)
    • Self-delegation and undelegation operations
    • Validator governance voting
  • Storage: Can be stored on hardware wallets (Ledger) for enhanced security
  • Prefix: Uses mpvaloper and mpvaloperpub prefixes
  • Creation: Generated with crossfid keys add <name> --ledger for hardware wallet integration

Consensus Key (Tendermint Key)​

  • Purpose: Used by Tendermint/CometBFT to sign blocks and consensus votes
  • Usage:
    • Block proposal signing
    • Prevote and precommit signing in consensus rounds
    • Must be available 24/7 for continuous block production
  • Storage: Stored in priv_validator.json file by default
  • Prefix: Associated with public key mpvalconspub
  • Security: Can be isolated using Tendermint KMS for enhanced protection
  • Creation: Generated automatically when node is initialized with crossfid init
Critical Security Warning
  • Never copy priv_validator.json between multiple nodes - this will cause double signing and result in slashing
  • Cannot migrate existing keys to hardware wallets - only possible for new validators
  • Backup both key types securely and separately

Key Relationship: Both keys are essential for validator operations but serve completely different functions. The account key manages the validator entity, while the consensus key handles the actual block signing process.

Sentry Nodes (DDOS Protection)​

Validators are responsible for ensuring that the network can sustain denial of service attacks.

One recommended way to mitigate these risks is for validators to carefully structure their network topology in a so-called sentry node architecture.

Validator nodes should only connect to full-nodes they trust because they operate them themselves or are run by other validators they know socially. A validator node will typically run in a data center. Most data centers provide direct links the networks of major cloud providers. The validator can use those links to connect to sentry nodes in the cloud. This shifts the burden of denial-of-service from the validator's node directly to its sentry nodes, and may require new sentry nodes be spun up or activated to mitigate attacks on existing ones.

Sentry nodes can be quickly spun up or change their IP addresses. Because the links to the sentry nodes are in private IP space, an internet based attacked cannot disturb them directly. This will ensure validator block proposals and votes always make it to the rest of the network.

To setup your sentry node architecture you can follow the instructions below:

Validators nodes should edit their config.toml:


# Comma separated list of nodes to keep persistent connections to

# Do not add private peers to this list if you don't want them advertised
persistent_peers =[list of sentry nodes]

# Set true to enable the peer-exchange reactor
pex = false

Sentry Nodes should edit their config.toml:


# Comma separated list of peer IDs to keep private (will not be gossiped to other peers)

# Example ID: 3e16af0cead27979e1fc3dac57d03df3c7a77acc@3.87.179.235:26656

private_peer_ids = "node_ids_of_private_peers"

How can validators protect themselves from denial-of-service attacks?​

Denial-of-service attacks occur when an attacker sends a flood of internet traffic to an IP address to prevent the server at the IP address from connecting to the internet.

An attacker scans the network, tries to learn the IP address of various validator nodes, and disconnects them from communication by flooding them with traffic.

One recommended way to mitigate these risks is for validators to carefully structure their network topology using a sentry node architecture.

Validator nodes are expected to connect only to full nodes they trust because they operate the full nodes themselves or the trust full nodes are run by other validators they know socially. A validator node is typically run in a data center. Most data centers provide direct links to the networks of major cloud providers. The validator can use those links to connect to sentry nodes in the cloud. This mitigation shifts the burden of denial-of-service from the validator's node directly to its sentry nodes, and can require that new sentry nodes are spun up or activated to mitigate attacks on existing ones.

Sentry nodes can be quickly spun up or change their IP addresses. Because the links to the sentry nodes are in private IP space, an internet-based attack cannot disturb them directly. This strategy ensures that validator block proposals and votes have a much higher chance to make it to the rest of the network.

For more sentry node details, see the Tendermint Documentation or the Sentry Node Architecture Overview on the forum.

Hardware Wallet Setup Guide​

Ledger Hardware Wallet Setup​

This section provides step-by-step instructions for setting up a Ledger device for CrossFi validator operations.

Prerequisites​

  • Ledger Nano S, Nano S Plus, or Nano X device
  • Computer with USB connection
  • Latest version of Ledger Live application
  • CrossFi daemon (crossfid) compiled with Ledger support

Step 1: Prepare Your Ledger Device​

Install Ledger Live

  • Download and install Ledger Live from the official website: https://www.ledger.com/ledger-live
  • Connect your Ledger device and update the firmware through Ledger Live to the latest version.

Install Cosmos Application

  • In Ledger Live:
    • Navigate to Manager section
    • Connect and unlock your Ledger device
    • Search for "Cosmos" application
    • Click Install to add the Cosmos app to your device
    • Note: You may need to enable Developer Mode in Ledger Live settings if the Cosmos app is not visible.

Initialize or Restore Seed Phrase

  • For new devices:
    • Follow the device setup to generate a new 24-word recovery phrase
    • Write down all 24 words in the exact order shown
    • Verify the phrase by entering requested words
  • For existing devices:
    • Use your existing recovery phrase if you already have one
    • Ensure you have secure offline backups of the phrase
  • ⚠️ Critical: Store your recovery phrase in multiple secure, offline locations. Loss of this phrase means permanent loss of your validator!

Step 2: Create Validator Account with Ledger​

Verify CrossFi Daemon Setup

  • Ensure your crossfid binary is compiled with Ledger support: 
    crossfid version --long
  • The output should include Ledger support in the build tags.

Connect and Unlock Ledger

  • Connect your Ledger device to your computer and:
    • Enter your PIN to unlock the device
    • Navigate to and open the Cosmos application
    • The screen should display "Cosmos ready"

Create Validator Key

  • Create a new key using the Ledger device: 
    crossfid keys add <validator-name> --ledger
  • Replace <validator-name> with your chosen validator identifier.
  • The command will:
    • Prompt you to confirm the operation on your Ledger device
    • Display the validator address and public key
    • Store the key reference in your local keyring

Verify Address on Device

  • Always verify the address matches what's displayed on your Ledger: 
    crossfid keys show <validator-name> -d
  • This command will:
    • Display the address in your terminal
    • Prompt address verification on your Ledger device
    • Require you to confirm the address on the device screen
  • Always verify addresses match before proceeding with any transactions.

Step 3: Security Best Practices​

🔐 Mnemonic Security

  • Store recovery phrases offline only
  • Use multiple secure locations
  • Never share with anyone
  • Consider metal backup solutions
  • Test recovery process on spare device

🔄 Operational Security

  • Always verify addresses on device
  • Keep Ledger firmware updated
  • Use unique device PIN
  • Enable auto-lock timeout
  • Monitor for firmware updates

Tendermint KMS Integration​

For additional security of your consensus key (the key used for block signing), consider using Tendermint Key Management System (KMS).

What is Tendermint KMS?​

Tendermint KMS (tmkms) is a key management service that:

  • Isolates consensus keys from validator nodes
  • Prevents double-signing through state tracking
  • Supports hardware security modules (HSM)
  • Provides high availability through redundancy
  • Runs on a separate server for enhanced security

KMS Setup Overview​

Install Dependencies

  • Install required dependencies for KMS compilation: 
    # Ubuntu/Debian
    sudo apt update
    sudo apt install -y gcc clang pkg-config libusb-1.0-0-dev

    # Install Rust
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    source ~/.cargo/env

Install Tendermint KMS

  • Install KMS with Ledger support: 
    # For Ledger support
    cargo install tmkms --features=ledger

    # For YubiHSM2 support
    cargo install tmkms --features=yubihsm

    # Verify installation
    tmkms --help

Initialize KMS Configuration

  • Create KMS configuration directory and files: 
    tmkms init /path/to/kms/home
  • This creates:
    • tmkms.toml - Main configuration file
    • kms-identity.key - KMS identity key
    • secrets/ - Directory for key storage
    • state/ - Directory for consensus state

Configure and Start KMS

  • Edit the tmkms.toml configuration file to:
    • Specify your hardware device (Ledger/YubiHSM)
    • Configure validator connection settings
    • Set up key derivation paths
  • Start the KMS service: 
    tmkms start -c /path/to/kms/home/tmkms.toml

Node Configuration for KMS​

To use KMS with your CrossFi validator node, update your config.toml:

# In ~/.crossfi/config/config.toml
[priv_validator]
# TCP or UNIX socket address for Tendermint to listen on for
# connections from an external PrivValidator process
laddr = "tcp://127.0.0.1:26658"

# Path to the JSON file containing the private key to use as a validator
key_file = ""

# Path to the JSON file containing the last sign state of a validator
state_file = ""
Additional Resources

For detailed KMS configuration examples and advanced setups, refer to:

Creating a New Validator with Hardware Wallet​

Once you have set up your hardware wallet and optionally configured KMS, follow these steps to create your validator:

Fund Your Validator Account

  • Send XFI tokens to your hardware wallet address: 
    # Get your validator address
    crossfid keys show <validator-name> --address

    # You'll need sufficient XFI for:
    # - Minimum self-delegation (check current requirements)
    # - Transaction fees for validator creation
    # - Ongoing operational costs

Sync Your Node

  • Ensure your validator node is fully synced before creating the validator: 
    # Check sync status
    crossfid status | jq .SyncInfo.catching_up

    # Wait until catching_up shows "false"

Create Validator Transaction

  • Create your validator using the hardware wallet: 
    crossfid tx staking create-validator \
      --amount=<stake-amount>xfi \
      --pubkey=$(crossfid tendermint show-validator) \
      --moniker="<validator-name>" \
      --chain-id=<chain-id> \
      --commission-rate="0.05" \
      --commission-max-rate="0.20" \
      --commission-max-change-rate="0.01" \
      --min-self-delegation="1000000" \
      --gas="auto" \
      --gas-prices="0.025xfi" \
      --from=<validator-name>
  • ⚠️ Important: You'll need to confirm this transaction on your Ledger device.

Verify Validator Creation

  • Check that your validator was created successfully: 
    # Find your validator
    crossfid query staking validators | grep -A 10 -B 10 "<validator-name>"

    # Check your validator status
    crossfid query staking validator $(crossfid keys show <validator-name> --bech val -a)
Pro Tip

For enhanced security and automated operations, consider setting up Cosmovisor with systemd for automatic node management and upgrades.