Skip to main content

Generate Keypairs

This guide explains how to generate and manage the keypairs required for running a BBAChain validator node.

Table of Contents​

Overview​

A BBAChain validator requires three keypairs to operate:

  1. Identity Keypair: Identifies your validator on the network
  2. Vote Account Keypair: Used for voting on consensus
  3. Withdrawer Keypair: Controls withdrawals from the vote account
warning

Security Warning: The withdrawer keypair is highly sensitive. Never store it on the validator machine. Keep it in a secure, offline location.

Required Keypairs​

Identity Keypair​

  • Purpose: Identifies your validator on the network
  • Storage: Can be stored on the validator machine
  • Usage: Used for validator identity and transaction fees

Vote Account Keypair​

  • Purpose: Used for voting on consensus decisions
  • Storage: Can be stored on the validator machine
  • Usage: Required for validator voting operations

Withdrawer Keypair​

  • Purpose: Controls withdrawals from the vote account
  • Storage: MUST NOT be stored on the validator machine
  • Usage: Used to withdraw staking rewards
  • Security: Most sensitive keypair - keep offline and secure

Generating Keypairs​

Step 1: Create Keypair Directory​

On your local computer, create a directory to store your keypairs:

mkdir ~/keypairs

This directory will contain all three keypairs.

Step 2: Generate Identity Keypair​

Generate the identity keypair:

bbachain-keygen new -o ~/keypairs/identity.json

This creates the identity keypair and saves it to ~/keypairs/identity.json.

Step 3: Generate Vote Account Keypair​

Generate the vote account keypair:

bbachain-keygen new -o ~/keypairs/vote-account.json

This creates the vote account keypair and saves it to ~/keypairs/vote-account.json.

Step 4: Generate Withdrawer Keypair​

Generate the withdrawer keypair:

bbachain-keygen new -o ~/keypairs/withdrawer.json

This creates the withdrawer keypair and saves it to ~/keypairs/withdrawer.json.

danger

IMPORTANT: The withdrawer.json keypair should be treated as highly sensitive information. The withdrawer keypair should always be stored securely and should NOT be stored on the validator machine.

Complete Command Sequence​

You can generate all three keypairs in sequence:

mkdir ~/keypairs

bbachain-keygen new -o ~/keypairs/identity.json

bbachain-keygen new -o ~/keypairs/vote-account.json

bbachain-keygen new -o ~/keypairs/withdrawer.json

Creating a Vote Account​

Before you can create your vote account, you need to fund your identity keypair with some BBA tokens to pay for transaction fees.

Step 1: Fund Identity Keypair​

Request an airdrop to fund your identity keypair:

bbachain airdrop 2 ~/keypairs/identity.json

This requests 2 BBA tokens (on Testnet) to be sent to your identity keypair. The tokens are used to pay for transaction fees.

info

On Testnet, you can request airdrops. On Mainnet, you'll need to acquire BBA tokens through other means.

Step 2: Create Vote Account​

Once your identity keypair is funded, create the vote account:

bbachain create-vote-account --fee-payer ~/keypairs/identity.json \
  ~/keypairs/vote-account.json \
  ~/keypairs/identity.json \
  ~/keypairs/withdrawer.json

This command:

  • Uses the identity keypair to pay transaction fees (--fee-payer)
  • Creates a vote account using the vote account keypair
  • Sets the identity keypair as the validator identity
  • Sets the withdrawer keypair as the withdrawal authority

Step 3: Verify Vote Account​

Verify that your vote account was created successfully:

bbachain vote-account ~/keypairs/vote-account.json

This displays information about your vote account.

Security Best Practices​

Keypair Storage​

  1. Identity Keypair: Can be stored on the validator machine
  2. Vote Account Keypair: Can be stored on the validator machine
  3. Withdrawer Keypair: MUST be stored offline, never on the validator machine

File Permissions​

Set restrictive file permissions on your keypairs:

chmod 600 ~/keypairs/identity.json
chmod 600 ~/keypairs/vote-account.json
chmod 600 ~/keypairs/withdrawer.json

This ensures only the owner can read and write the keypair files.

Backup Strategy​

  1. Identity Keypair: Backup to secure location
  2. Vote Account Keypair: Backup to secure location
  3. Withdrawer Keypair: Create multiple secure backups in different locations

Offline Storage​

For maximum security, store the withdrawer keypair:

  • On an encrypted USB drive
  • In a secure physical location
  • In a hardware wallet (if supported)
  • Never on any internet-connected device

Backup and Recovery​

Creating Backups​

Create secure backups of all keypairs:

# Create backup directory
mkdir ~/keypairs-backup

# Copy keypairs to backup location
cp ~/keypairs/identity.json ~/keypairs-backup/
cp ~/keypairs/vote-account.json ~/keypairs-backup/
cp ~/keypairs/withdrawer.json ~/keypairs-backup/

Encrypting Backups​

Encrypt your backups before storing them:

# Encrypt backup (example using GPG)
gpg -c ~/keypairs-backup/withdrawer.json

Recovery​

If you lose a keypair:

  • Identity Keypair: Can be regenerated, but you'll need to reconfigure your validator
  • Vote Account Keypair: Can be recovered from backup
  • Withdrawer Keypair: CRITICAL - If lost, you cannot withdraw rewards. Always maintain secure backups.

Keypair Management​

Viewing Keypair Information​

View information about a keypair:

bbachain-keygen pubkey ~/keypairs/identity.json

This displays the public key associated with the keypair.

Verifying Keypairs​

Verify that your keypairs are valid:

bbachain-keygen verify ~/keypairs/identity.json

Next Steps: After generating your keypairs, you're ready to start your validator node. See the next guide for starting and running your validator.