Bitcoin Staking Scripts

This directory contains TypeScript scripts for interacting with Bitcoin staking services.

Setup

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env with your private keys

Available Scripts

• pnpm post-stake - Run the delegation script (post-staking flow)
• pnpm pre-stake - Run the pre-stake registration script
• pnpm sign-cosmos-tx - Sign a Cosmos transaction
• pnpm sign-message - Sign a Bitcoin message
• pnpm sign-psbt - Sign a Bitcoin PSBT
• pnpm staking-status - Check the status of a staking transaction
• pnpm unbond - Run the unbonding script
• pnpm withdraw - Run the withdrawal script
• pnpm lint:deps - Check for unused dependencies
• pnpm check:missing - Check for missing dependencies

Command-Line Arguments

All scripts now accept command-line arguments instead of hardcoded values:

Delegate (Post-Staking Flow)

# Show help
pnpm post-stake --help

# Delegate with custom amount and timelock
pnpm post-stake --amount 100000 --timeLock 5000

# Skip waiting for confirmations
pnpm post-stake --skipConfirmationWait

# Use short flags
pnpm post-stake -a 100000 -t 5000

# Resume a previously interrupted process (from confirmation wait)
pnpm post-stake --txid abc123def456 --resumeFrom confirmations

# Resume a previously interrupted process (from delegation stage, after confirmations)
pnpm post-stake --txid abc123def456 --resumeFrom delegation

Note: The confirmation waiting process can take hours on Bitcoin networks. You can safely cancel the process at any time with Ctrl+C and resume later using the provided command.

Pre-Stake (Pre-Staking Flow)

# Show help
pnpm pre-stake --help

# Pre-stake with custom amount and timelock
pnpm pre-stake --amount 100000 --timeLock 5000

# Skip waiting for verification
pnpm pre-stake --skipVerificationWait

# Use short flags
pnpm pre-stake -a 100000 -t 5000

# Resume a previously interrupted process (from verification wait)
pnpm pre-stake --txid abc123def456 --resumeStage verification

# Resume a previously interrupted process (from finalization stage)
pnpm pre-stake --txid abc123def456 --resumeStage finalization

The pre-stake flow allows you to register your stake on Babylon before broadcasting the Bitcoin transaction. This provides additional security by ensuring your stake is valid before committing Bitcoin funds.

New Flow (Updated):

1. Build unsigned staking transaction PSBT
2. Sign the staking transaction locally
3. Get delegation payloads based on the signed transaction
4. Sign delegation payloads
5. Build and submit Babylon registration transaction
6. Wait for verification from Babylon covenants
7. Finalize by broadcasting the Bitcoin transaction

This updated flow ensures consistency between the staking transaction and delegation payloads by signing the staking transaction first, preventing issues that could arise if the wallet modifies the transaction during signing.

Sign Message

# Show help
pnpm sign-message --help

# Sign a specific message
pnpm sign-message --message "Hello, world!"

# Use short flag
pnpm sign-message -m "Hello, world!"

Sign PSBT

# Show help
pnpm sign-psbt --help

# Sign a PSBT and broadcast it
pnpm sign-psbt --psbt "70736274ff01..." --broadcast

# Use short flags
pnpm sign-psbt -p "70736274ff01..." -b

Sign Cosmos Transaction

# Show help
pnpm sign-cosmos-tx --help

# Sign a Cosmos transaction with custom gas settings
pnpm sign-cosmos-tx --message "Base64EncodedMessage" --gasEstimate 200000 --gasPriceMultiplier 2.0

# Use short flags
pnpm sign-cosmos-tx -m "Base64EncodedMessage" -g 200000 -p 2.0

Unbond

# Show help
pnpm unbond --help

# Unbond a specific staking transaction
pnpm unbond --txid abc123def456

# Show verbose output
pnpm unbond --txid abc123def456 --verbose

# Use short flags
pnpm unbond -t abc123def456 -v

Withdraw

# Show help
pnpm withdraw --help

# Withdraw from early unbonded stake (default)
pnpm withdraw --txid abc123def456

# Withdraw from timelock expired stake
pnpm withdraw --txid abc123def456 --type timelock_expired

# Show verbose output
pnpm withdraw --txid abc123def456 --verbose

# Use short flags
pnpm withdraw -t abc123def456 -y early_unbonded -v

Staking Status

# Show help
pnpm staking-status --help

# Check status of a staking transaction
pnpm staking-status --txid abc123def456

# Show detailed JSON output
pnpm staking-status --txid abc123def456 --verbose

# Use short flags
pnpm staking-status -t abc123def456 -v

Staking Details

# Show help
pnpm staking-details --help

# Get staking details for the address from private key (default)
pnpm staking-details

# Get staking details for a specific Bitcoin address
pnpm staking-details --address bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

# Show detailed information with all stakes (using default address)
pnpm staking-details --verbose

# Output raw JSON response
pnpm staking-details --json

# Filter by status
pnpm staking-details --status registration-transaction-confirmed
pnpm staking-details -s staking-transaction-k-deep

# Show only registered stakes
pnpm staking-details --registered
pnpm staking-details -r

# Show only unregistered stakes
pnpm staking-details --unregistered
pnpm staking-details -u

# Combine filters (unregistered stakes with specific status)
pnpm staking-details --unregistered --status staking-transaction-k-deep

# Use short flags with specific address and filters
pnpm staking-details -a bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq -r -v

Development

This project uses:

• SWC for fast TypeScript compilation and execution
• Knip for dependency management
• Yargs for command-line argument parsing

API Health Check

All scripts now automatically check if the API server is running before execution. The check:

1. Makes a request to the /health endpoint
2. Verifies the response is "HEALTHY"
3. Exits with an error if the API server is unavailable

This ensures that scripts fail fast if the API is not available, avoiding confusing errors later in execution.

Dependencies

Some dependencies are marked as ignored in the knip.json file:

• @swc-node/register - Used for running TypeScript files directly
• @swc/core - Core SWC engine
• typescript - Used for type checking

These dependencies are used by the build system but not directly imported in the TypeScript code.

Environment Variables

Required environment variables in .env:

• BTC_PRIVATE_KEY_WIF - Bitcoin private key in WIF format
• COSMOS_MNEMONIC - Cosmos wallet mnemonic
• API_BASE_URL - API base URL (defaults to http://localhost:3000)
• API_KEY - Pier Two API Key