JBond CLI

Command-line interface for interacting with the JBond Solana program, which manages validator bond collateral.

Installation

# From repository root
pnpm install

# Run CLI
pnpm jbond --help

Environment Setup

Set environment variables for convenience:

export JBOND_BOND=performance          # Your bond name (required for most commands)
export CLUSTER=mainnet-beta            # Solana cluster: mainnet-beta, devnet, testnet, or custom RPC URL
export SOLANA_KEYPAIR=~/.config/solana/id.json  # Optional: custom keypair path

Global Options

All commands support these options:

• -c, --cluster <cluster> - Solana cluster (mainnet-beta, devnet, testnet) or custom RPC URL (default: mainnet-beta)
• -k, --keypair <path> - Path to Solana keypair file
• -b, --bond <name> - Bond name (or set JBOND_BOND env var)
• -t, --bond-type <type> - Bond type: standard or crowdfunding (default: standard)

Commands

Global State

Initialize Global State

Initialize the JBond program's global state (one-time, authority only).

pnpm jbond init [options]

Options:
  -a, --authority <pubkey>  Authority (defaults to signer)

Example:
  pnpm jbond init -a 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin

Note: This command should only be run once by the program authority during initial deployment.

Bond Management

Initialize Bond

Initialize a new bond project.

pnpm jbond bond init <name> [options]

Arguments:
  name                      Bond name

Options:
  -r, --reserve <address>   Reserve vault address (defaults to signer)
  -c, --collateral <type>   Collateral type: native | token:<mint> | stakeAccount (default: native)
  -a, --authority <pubkey>  Withdraw authority (defaults to signer)

Examples:
  # Initialize bond with native SOL collateral
  pnpm jbond bond init performance -r 61mS9nEir6jx6cvte6NzQpyrFk3Fj4krMNLuHhi4tjJz

  # Initialize with SPL token collateral
  pnpm jbond bond init performance -r <reserve> -c token:7Q2afV64in6N6SeZsAAB81TJzwDoD6zpqmHkzi9Dcavn

Update Bond Configuration

Update bond configuration (authority only).

pnpm jbond bond config [options]

Options:
  -r, --reserve <address>   New reserve vault address
  -a, --authority <pubkey>  New withdraw authority

Example:
  pnpm jbond bond config -r 61mS9nEir6jx6cvte6NzQpyrFk3Fj4krMNLuHhi4tjJz

Bond Info

Display information about a bond.

pnpm jbond bond info

Example:
  pnpm jbond bond info -b performance

Displays:

• Bond name and type
• Reserve vault address
• Withdraw authority
• Collateral type
• Total validators

List Bonds

List all bonds for the current bond type.

pnpm jbond bond list

Example:
  pnpm jbond bond list -t standard

Collateral Type Info

Display collateral type information for the bond.

pnpm jbond bond collateral-type

Example:
  pnpm jbond bond collateral-type -b performance

Validator Operations

Register Validator

Register a new validator and create bond account.

pnpm jbond validator register <vote-account>

Arguments:
  vote-account              Vote account public key

Example:
  pnpm jbond validator register GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD

Requirements:

• Bond must be initialized first
• Signer will be set as validator identity
• JBOND_BOND environment variable or -b flag required

Top Up Collateral

Add collateral to an existing validator bond account.

pnpm jbond validator topup <vote-account> <amount>

Arguments:
  vote-account              Vote account public key
  amount                    Amount to add in SOL

Example:
  pnpm jbond validator topup GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 50

Withdraw Collateral

Withdraw collateral from a validator bond account.

pnpm jbond validator withdraw <vote-account> <amount> <destination>

Arguments:
  vote-account              Vote account public key
  amount                    Amount to withdraw in SOL
  destination               Destination address for withdrawn funds

Example:
  pnpm jbond validator withdraw GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 25 3K2coMGaZhrSkyF52wUBUXBeRBRpGLnmB3znzLRKjgiP

Requirements:

• Only validator identity or withdrawal authority can execute
• Bond account must have sufficient collateral
• Session must not be active (or must be finished)

Claim Compensation

Claim collateral from validator to reserve (authority only).

pnpm jbond validator claim <vote-account> <amount>

Arguments:
  vote-account              Vote account public key
  amount                    Amount to claim in SOL

Example:
  pnpm jbond validator claim GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 10

Note: Only the bond authority can execute compensation claims.

Validator Info

Display information about a validator bond account.

pnpm jbond validator info <vote-account>

Arguments:
  vote-account              Vote account public key

Example:
  pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD

Displays:

• Validator identity
• Vote account
• Bond name and type
• Collateral amount
• Withdrawal authority
• Session status
• Creation timestamp

Set Withdrawal Authority

Set or update the withdrawal authority for a validator bond account.

pnpm jbond validator set-authority <vote-account> [options]

Arguments:
  vote-account              Vote account public key

Options:
  -a, --authority <pubkey>  New withdrawal authority (omit to remove authority)

Examples:
  # Set a withdrawal authority
  pnpm jbond validator set-authority GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -a 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin

  # Remove withdrawal authority (revert to identity-only)
  pnpm jbond validator set-authority GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD

Requirements:

• Only the validator identity can set or update the withdrawal authority
• When set, only that authority (or validator identity) can withdraw collateral

Transaction History

View transaction history for a validator bond account.

pnpm jbond validator history <vote-account> [options]

Arguments:
  vote-account              Vote account public key

Options:
  -l, --limit <number>      Number of transactions to fetch (default: 10)

Example:
  pnpm jbond validator history GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -l 20

Displays:

• Transaction signatures
• Timestamps
• Transaction types (register, topup, withdraw, etc.)
• Amounts

Session Management

Start Session

Start a new time-locked bond session.

pnpm jbond session start <duration>

Arguments:
  duration                  Session duration in seconds

Example:
  pnpm jbond session start 86400  # 1 day

Common durations:

• 1 hour: 3600
• 1 day: 86400
• 1 week: 604800
• 30 days: 2592000

Purpose:

• Time-locks collateral withdrawals
• Demonstrates validator commitment
• Enhances security for delegators

Finish Session

Finish the active bond session.

pnpm jbond session finish

Example:
  pnpm jbond session finish -b performance

Requirements:

• Session must be active
• Session duration must have elapsed
• Only validator identity can finish session

Usage Examples

Complete Workflow

# 1. Set environment
export JBOND_BOND=performance
export CLUSTER=mainnet-beta

# 2. Initialize bond (first time only)
pnpm jbond bond init performance -r 61mS9nEir6jx6cvte6NzQpyrFk3Fj4krMNLuHhi4tjJz

# 3. Register as validator
pnpm jbond validator register GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD

# 4. Add collateral
pnpm jbond validator topup GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 100

# 5. Check bond info
pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD

# 6. Start session (optional)
pnpm jbond session start 86400

# 7. View transaction history
pnpm jbond validator history GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -l 20

Authority Operations

# Update bond configuration
pnpm jbond bond config -r <new-reserve>

# Claim compensation from underperforming validator
pnpm jbond validator claim GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 5

# Check bond statistics
pnpm jbond bond info

Multiple Clusters

# Devnet operations
pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -c devnet

# Custom RPC endpoint
pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -c https://api.mainnet-beta.solana.com

Error Handling

Common Errors

Bond is required. Use -b <name>

Set the JBOND_BOND environment variable or use the -b flag:

export JBOND_BOND=performance
# or
pnpm jbond validator info <vote> -b performance

Failed to load keypair

• Ensure the keypair file exists at the specified path
• Check file permissions
• Verify the keypair file is in valid JSON format
• Try specifying the path explicitly with -k

Validator bond account not found

• Ensure the validator is registered first
• Verify the vote account address is correct
• Check that you're using the correct cluster

Invalid amount: must be positive number

• Ensure the amount is a valid positive number
• Don't include units (SOL) in the amount

Unauthorized

• Only the authority can claim compensation
• Only the validator identity can set withdrawal authority
• Ensure you're using the correct authority keypair

Account already in use

• The validator is already registered
• Use topup to add more collateral instead

Bond Types

Standard Bond

Individual validator operations with full control over collateral.

pnpm jbond bond init performance -r <reserve> -t standard

Crowdfunding Bond

Community-backed validator bonds with shared collateral.

pnpm jbond bond init performance -r <reserve> -t crowdfunding

Collateral Types

Native SOL

Direct SOL deposits (default).

pnpm jbond bond init performance -r <reserve> -c native

SPL Token

Custom token collateral.

pnpm jbond bond init performance -r <reserve> -c token:7Q2afV64in6N6SeZsAAB81TJzwDoD6zpqmHkzi9Dcavn

Stake Account

Existing stake account collateral.

pnpm jbond bond init performance -r <reserve> -c stakeAccount

Development

Running from Source

# From repository root
pnpm install
pnpm cli --help

# Run specific command
pnpm cli validator info <vote-account>

Building

pnpm cli build