@jpool/bond-cli 1.5.2 → 1.6.0

package/README.md

@@ -1,234 +1,502 @@
 # JBond CLI
 
-A command-line interface for interacting with the JBond Solana program, which manages validator bond collateral.
+Command-line interface for interacting with the JBond Solana program, which manages validator bond collateral.
+
+## Installation
+
+```bash
+# From repository root
+pnpm install
+
+# Run CLI
+pnpm jbond --help
+```
+
+## Environment Setup
+
+Set environment variables for convenience:
+
+```bash
+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
 
-### Initialize Global State
+### Global State
+
+#### Initialize Global State
 
-Initialize Bond Global State and set reserve address.
+Initialize the JBond program's global state (one-time, authority only).
 
 ```bash
-pnpm jbond initialize -k <KEYPAIR_PATH> -r <RESERVE_ADDRESS>
+pnpm jbond init [options]
 
 Options:
-  -k, --keypair <KEYPAIR_PATH>  Path to keypair file (default: ~/.config/solana/id.json)
-  -r, --reserve <RESERVE_ADDRESS> Reserve address
-  -c, --cluster <CLUSTER_NAME> Solana cluster(devnet or mainnet-beta)
+  -a, --authority <pubkey>  Authority (defaults to signer)
 
 Example:
-  pnpm jbond initialize -r 61mS9nEir6jx6cvte6NzQpyrFk3Fj4krMNLuHhi4tjJz -c mainnet-beta
+  pnpm jbond init -a 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
 ```
 
-**Note**: This command should only be run once by the program authority.
+**Note**: This command should only be run once by the program authority during initial deployment.
+
+---
+
+### Bond Management
 
-### Register Validator
+#### Initialize Bond
 
-Register a new validator and deposit initial collateral.
+Initialize a new bond project.
 
 ```bash
-pnpm jbond register-validator <vote-account> <amount> -k <path>
+pnpm jbond bond init <name> [options]
 
 Arguments:
-  vote-account          Vote account public key
-  amount               Initial collateral amount in SOL
+  name                      Bond name
 
 Options:
-  -k, --keypair <KEYPAIR_PATH>  Path to keypair file (default: ~/.config/solana/id.json)
-  -w, Optional withdraw authority
-  -c, --cluster <CLUSTER_NAME> Solana cluster(devnet or mainnet-beta)
+  -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).
+
+```bash
+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.
+
+```bash
+pnpm jbond bond info
 
 Example:
-  pnpm jbond register-validator 686JcEJ98r8fMtUiVuKiz4WRoBpJ2Sm9zMhdc2b6H4bu 1.1 -k ~/.config/solana/id.json -c mainnet-beta
+  pnpm jbond bond info -b performance
 ```
 
-**Requirements**:
+**Displays:**
 
-- Minimum collateral amount is determined by the program (typically 1 SOL)
-- The keypair must have sufficient SOL for collateral + transaction fees
+- Bond name and type
+- Reserve vault address
+- Withdraw authority
+- Collateral type
+- Total validators
 
-### Top Up Collateral
+#### List Bonds
 
-Add additional collateral to an existing validator bond.
+List all bonds for the current bond type.
 
 ```bash
-pnpm jbond topup-collateral <vote-account> <amount> -k <path>
+pnpm jbond bond list
 
-Arguments:
-  vote-account          Vote account public key
-  amount               Amount to add in SOL
+Example:
+  pnpm jbond bond list -t standard
+```
 
-Options:
-  -k, --keypair <KEYPAIR_PATH>  Path to keypair file (default: ~/.config/solana/id.json)
-  -c, --cluster <CLUSTER_NAME> Solana cluster(devnet or mainnet-beta)
+#### Collateral Type Info
+
+Display collateral type information for the bond.
+
+```bash
+pnpm jbond bond collateral-type
 
 Example:
-  pnpm jbond topup-collateral 686JcEJ98r8fMtUiVuKiz4WRoBpJ2Sm9zMhdc2b6H4bu 50 -c mainnet-beta
+  pnpm jbond bond collateral-type -b performance
 ```
 
-### Withdraw Collateral
+---
+
+### Validator Operations
 
-Withdraw collateral from validator bond account.
+#### Register Validator
+
+Register a new validator and create bond account.
 
 ```bash
-pnpm jbond withdraw-collateral <vote-account> <destination> <amount> [options]
+pnpm jbond validator register <vote-account>
 
 Arguments:
-  vote-account          Vote account public key
-  destination          Destination address for withdrawn funds
-  amount               Amount to withdraw in SOL
-
-Options:
-  -k, --keypair <path>  Path to keypair file (default: ~/.config/solana/id.json)
-  -c, --cluster <CLUSTER_NAME> Solana cluster(devnet or mainnet-beta)
+  vote-account              Vote account public key
 
 Example:
-  pnpm jbond withdraw-collateral 686JcEJ98r8fMtUiVuKiz4WRoBpJ2Sm9zMhdc2b6H4bu 3K2coMGaZhrSkyF52wUBUXBeRBRpGLnmB3znzLRKjgiP 25 -c mainnet-beta
+  pnpm jbond validator register GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD
 ```
 
-**Requirements**:
+**Requirements:**
 
-Only the validator identity or withdrawal authority can execute withdrawals. The validator bond account must have sufficient collateral
+- Bond must be initialized first
+- Signer will be set as validator identity
+- `JBOND_BOND` environment variable or `-b` flag required
 
-### Claim Compensation
+#### Top Up Collateral
 
-Claim compensation from a validator's collateral to the reserve (authority only).
+Add collateral to an existing validator bond account.
 
 ```bash
-pnpm jbond claim-compensation <vote-account> <amount> -k <path>
+pnpm jbond validator topup <vote-account> <amount>
 
 Arguments:
-  vote-account          Vote account public key
-  amount               Amount to claim in SOL
-
-Options:
-  -k, --keypair <KEYPAIR_PATH>  Path to keypair file (default: ~/.config/solana/id.json)
-  -c, --cluster <CLUSTER_NAME> Solana cluster(devnet or mainnet-beta)
+  vote-account              Vote account public key
+  amount                    Amount to add in SOL
 
 Example:
-  pnpm jbond claim-compensation GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 10 -k <path> -c mainnet-beta
+  pnpm jbond validator topup GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 50
 ```
 
-**Note**: Only the program authority can execute withdrawals.
+#### Withdraw Collateral
 
-### Update Global Config
+Withdraw collateral from a validator bond account.
 
+```bash
+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
 ```
-pnpm jbond configure [options]
 
-Options:
--k, --keypair <KEYPAIR_PATH> Path to keypair file (default: ~/.config/solana/id.json)
--a, --new-authority <PUBKEY> New authority public key
--r, --new-reserve <PUBKEY> New reserve address
--c, --cluster <CLUSTER_NAME> Solana cluster (devnet or mainnet-beta)
+**Requirements:**
 
-Examples:
+- 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).
+
+```bash
+pnpm jbond validator claim <vote-account> <amount>
+
+Arguments:
+  vote-account              Vote account public key
+  amount                    Amount to claim in SOL
 
-pnpm jbond configure -a 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin -c mainnet-beta
-pnpm jbond configure -r 61mS9nEir6jx6cvte6NzQpyrFk3Fj4krMNLuHhi4tjJz -c mainnet-beta
-pnpm jbond configure \
--a 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin\
--r 61mS9nEir6jx6cvte6NzQpyrFk3Fj4krMNLuHhi4tjJz\
--c mainnet-beta
+Example:
+  pnpm jbond validator claim GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 10
 ```
 
-### Validator Info
+**Note**: Only the bond authority can execute compensation claims.
+
+#### Validator Info
 
 Display information about a validator bond account.
 
 ```bash
-pnpm jbond validator-info <vote-account> [options]
+pnpm jbond validator info <vote-account>
 
 Arguments:
-  vote-account          Vote account public key
-
-Options:
-  -k, --keypair <KEYPAIR_PATH>  Path to keypair file (default: ~/.config/solana/id.json)
-  -v, --validator <pubkey> Validator public key,
-  -c, --cluster <CLUSTER_NAME> Solana cluster(devnet or mainnet-beta)
+  vote-account              Vote account public key
 
 Example:
-  pnpm jbond validator-info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -k <path> -c mainnet-beta
+  pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD
 ```
 
-**Displays**:
+**Displays:**
 
 - Validator identity
 - Vote account
+- Bond name and type
+- Collateral amount
 - Withdrawal authority
-- Active status
+- Session status
 - Creation timestamp
 
-### Global state Info
+#### Set Withdrawal Authority
+
+Set or update the withdrawal authority for a validator bond account.
+
+```bash
+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
 
-Display information about the global state.
+#### Transaction History
+
+View transaction history for a validator bond account.
 
 ```bash
-pnpm jbond state [options]
+pnpm jbond validator history <vote-account> [options]
+
+Arguments:
+  vote-account              Vote account public key
 
 Options:
-  -k, --keypair <KEYPAIR_PATH>  Path to keypair file (default: ~/.config/solana/id.json)
-  -c, --cluster <CLUSTER_NAME> Solana cluster(devnet or mainnet-beta)
+  -l, --limit <number>      Number of transactions to fetch (default: 10)
 
 Example:
-  pnpm jbond state -k <path> -c mainnet-beta
+  pnpm jbond validator history GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -l 20
 ```
 
-**Displays**:
+**Displays:**
+
+- Transaction signatures
+- Timestamps
+- Transaction types (register, topup, withdraw, etc.)
+- Amounts
+
+---
 
-- Authority public key
-- Total number of validators
-- Current epoch
+### Session Management
+
+#### Start Session
+
+Start a new time-locked bond session.
+
+```bash
+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.
+
+```bash
+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 Validator Registration Flow
+### Complete Workflow
 
 ```bash
-# 1. Check current global state
-pnpm jbond global-state-info -c mainnet-beta
+# 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
 
-# 2. Register as a validator with 100 SOL collateral
-pnpm jbond register-validator GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 100  -c mainnet-beta
+# 4. Add collateral
+pnpm jbond validator topup GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 100
 
-# 3. Verify registration
-pnpm jbond validator-info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -c mainnet-beta
+# 5. Check bond info
+pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD
 
-# 4. Top up with additional 50 SOL
-pnpm jbond topup-collateral GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 50 -c mainnet-beta
+# 6. Start session (optional)
+pnpm jbond session start 86400
+
+# 7. View transaction history
+pnpm jbond validator history GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -l 20
 ```
 
 ### Authority Operations
 
 ```bash
-# As authority, withdraw compensation from underperforming validator
-pnpm jbond claim-compensation GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD 5 -c mainnet-beta
+# 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
+
+```bash
+# Devnet operations
+pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -c devnet
 
-# Check pool statistics
-pnpm jbond global-state-info -c mainnet-beta
+# Custom RPC endpoint
+pnpm jbond validator info GHRvDXj9BfACkJ9CoLWbpi2UkMVti9DwXJGsaFT9XDcD -c https://api.mainnet-beta.solana.com
 ```
 
+---
+
 ## Error Handling
 
-Common errors and solutions:
+### Common Errors
+
+#### `Bond is required. Use -b <name>`
+
+Set the `JBOND_BOND` environment variable or use the `-b` flag:
 
-### `Failed to load keypair`
+```bash
+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
 
-### `InsufficientCollateral`
+#### `Invalid amount: must be positive number`
 
-- The collateral amount is below the minimum requirement
-- Check the program's minimum collateral requirement
+- Ensure the amount is a valid positive number
+- Don't include units (SOL) in the amount
 
-### `Unauthorized`
+#### `Unauthorized`
 
-- Only the authority can withdraw compensations
+- 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`
+#### `Account already in use`
 
 - The validator is already registered
-- Use `topup-collateral` to add more funds instead
+- Use `topup` to add more collateral instead
+
+---
+
+## Bond Types
+
+### Standard Bond
+
+Individual validator operations with full control over collateral.
+
+```bash
+pnpm jbond bond init performance -r <reserve> -t standard
+```
+
+### Crowdfunding Bond
+
+Community-backed validator bonds with shared collateral.
+
+```bash
+pnpm jbond bond init performance -r <reserve> -t crowdfunding
+```
+
+---
+
+## Collateral Types
+
+### Native SOL
+
+Direct SOL deposits (default).
+
+```bash
+pnpm jbond bond init performance -r <reserve> -c native
+```
+
+### SPL Token
+
+Custom token collateral.
+
+```bash
+pnpm jbond bond init performance -r <reserve> -c token:7Q2afV64in6N6SeZsAAB81TJzwDoD6zpqmHkzi9Dcavn
+```
+
+### Stake Account
+
+Existing stake account collateral.
+
+```bash
+pnpm jbond bond init performance -r <reserve> -c stakeAccount
+```
+
+---
+
+## Development
+
+### Running from Source
+
+```bash
+# From repository root
+pnpm install
+pnpm cli --help
+
+# Run specific command
+pnpm cli validator info <vote-account>
+```
+
+### Building
+
+```bash
+pnpm cli build
+```