Accueil Explorer Aide
Connexion
cesar
/
cdk
1
0
Fork 0
Fichiers Tickets 0 Pull Requests 0 Wiki
Branche: main
Branches Tags
cdk
/
REGTEST_GUIDE.md

REGTEST_GUIDE.md 6.9 KB
Lien permanent Historique Raw

CDK Regtest Environment Guide

A comprehensive guide for setting up and using the CDK regtest environment for development and testing.

Quick Start

Start the Environment

# Start regtest with SQLite database (default)
just regtest

# Or with REDB database
just regtest redb

The script will:

  1. Check for mprocs and offer to install it if missing
  2. Build necessary binaries
  3. Set up Bitcoin regtest + 4 Lightning nodes + 2 CDK mints
  4. Launch mprocs TUI showing all component logs
  5. Both mints start automatically

Stop the Environment

Press q in mprocs or Ctrl+C in the terminal. Everything cleans up automatically.

Network Components

When running, you get a complete Lightning Network environment:

Bitcoin Network

  • Bitcoin RPC: 127.0.0.1:18443 (user: testuser, pass: testpass)

Lightning Nodes

  • CLN Node 1: $CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc
  • CLN Node 2: $CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc
  • LND Node 1: https://localhost:10009
  • LND Node 2: https://localhost:10010

CDK Mints

  • CLN Mint: http://127.0.0.1:8085 (connected to CLN node 1)
  • LND Mint: http://127.0.0.1:8087 (connected to LND node 2)

Environment Variables

Available in all terminals automatically:

  • CDK_TEST_MINT_URL: CLN mint URL
  • CDK_TEST_MINT_URL_2: LND mint URL
  • CDK_ITESTS_DIR: Temporary directory with all data

Using the Environment

All commands work from any terminal - they automatically find the running environment.

Lightning Node Operations

# Get node information
just ln-cln1 getinfo
just ln-cln2 getinfo
just ln-lnd1 getinfo
just ln-lnd2 getinfo

# Create and pay invoices
just ln-cln1 invoice 1000 label "Test payment"
just ln-lnd1 payinvoice <bolt11>

# Check balances and channels
just ln-cln1 listfunds
just ln-lnd1 listchannels

Bitcoin Operations

just btc getblockchaininfo    # Blockchain status
just btc getbalance          # Wallet balance
just btc-mine 5              # Mine 5 blocks

CDK Mint Operations

just mint-info        # Show both mints' info
just mint-test        # Run integration tests
just restart-mints    # Recompile and restart mints
just regtest-status   # Check all components
just regtest-logs     # Show recent logs

mprocs TUI Interface

The mprocs interface shows all component logs in real-time:

Controls

  • Arrow keys: Navigate between processes
  • Enter: Focus on a process to see its output
  • Tab: Switch between process list and output view
  • s: Start a process (if stopped)
  • k: Kill a process
  • r: Restart a process
  • PageUp/PageDown: Scroll through logs
  • ?: Show help
  • q: Quit and stop environment

Process List

  • cln-mint: CDK mint connected to CLN (auto-started)
  • lnd-mint: CDK mint connected to LND (auto-started)
  • bitcoind: Bitcoin regtest node logs
  • cln-one: CLN node 1 logs
  • cln-two: CLN node 2 logs
  • lnd-one: LND node 1 logs
  • lnd-two: LND node 2 logs

Development Workflows

Testing Lightning Payment Flow

# Terminal 1: Start environment
just regtest

# Terminal 2: Create invoice and pay
just ln-cln1 invoice 1000 test "Test payment"
just ln-lnd1 payinvoice <bolt11_from_above>
just ln-cln1 listinvoices
just ln-lnd1 listpayments

Developing Mint Code

# Terminal 1: Keep regtest running
just regtest

# Terminal 2: After making code changes
just restart-mints    # Recompiles and restarts both mints
just mint-info       # Test the changes
just mint-test       # Run integration tests

Using CDK CLI Tools

# Terminal 1: Start environment
just regtest

# Terminal 2: Use environment variables
cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info
cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL_2 mint-info

Direct API Testing

# Query mint info directly
curl $CDK_TEST_MINT_URL/v1/info | jq
curl $CDK_TEST_MINT_URL/v1/keysets | jq

# Test both mints
curl http://127.0.0.1:8085/v1/info | jq
curl http://127.0.0.1:8087/v1/info | jq

File Structure

All components run in a temporary directory:

$CDK_ITESTS_DIR/
├── bitcoin/              # Bitcoin regtest data
├── cln/
│   ├── one/             # CLN node 1 data
│   └── two/             # CLN node 2 data
├── lnd/
│   ├── one/             # LND node 1 data
│   │   ├── tls.cert
│   │   └── data/chain/bitcoin/regtest/admin.macaroon
│   └── two/             # LND node 2 data
├── cln_mint/            # CLN mint working directory
├── lnd_mint/            # LND mint working directory
├── start_cln_mint.sh    # Mint startup scripts
├── start_lnd_mint.sh
└── mprocs.yaml         # mprocs configuration

Installation Requirements

mprocs (TUI Interface)

If not installed, the script will offer to install it:

# Automatic installation during regtest setup
just regtest

# Manual installation
cargo install mprocs

# Or via package manager
# Ubuntu/Debian: apt install mprocs
# macOS: brew install mprocs

System Dependencies

Managed automatically via Nix development shell:

  • Bitcoin Core
  • Core Lightning (CLN)
  • LND (Lightning Network Daemon)
  • Rust toolchain

Advanced Usage

Manual mprocs Launch

# If you need to restart just the mprocs interface
source /tmp/cdk_regtest_env
just regtest-logs

Environment State

The environment creates a state file at /tmp/cdk_regtest_env that:

  • Shares environment variables between terminals
  • Allows just commands to work from anywhere
  • Automatically cleaned up when environment stops

Process Management

From within mprocs:

  • Restart individual mints after code changes
  • Monitor specific component logs
  • Start/stop services for testing scenarios

Troubleshooting

Environment Not Starting

  • Check that ports are available: 8085, 8087, 18443, 19846, 19847, 10009, 10010
  • Ensure the Nix development shell is active: nix develop
  • Check individual component logs in mprocs

Helper Commands Not Working

  • Ensure the regtest environment is running
  • Check that /tmp/cdk_regtest_env file exists
  • Verify environment variables are set: echo $CDK_TEST_MINT_URL

Connection Issues

  • Use just regtest-status to check component health
  • Check mint logs with just regtest-logs
  • Verify Lightning node status with just ln-cln1 getinfo

mprocs Issues

  • If mprocs crashes, processes continue running
  • Use Ctrl+C in the original terminal to clean up
  • Restart with just regtest-logs

Common Error Solutions

"Port already in use"

# Find and kill processes using ports
sudo lsof -ti:8085 | xargs kill -9
sudo lsof -ti:8087 | xargs kill -9

"Environment not found"

# Clean up and restart
rm -f /tmp/cdk_regtest_env
just regtest

"Binary not found"

# Rebuild binaries
just build
just regtest

This environment provides everything needed for CDK development and testing in a single, easy-to-use interface! 🎉