cdk/misc/README.md

CDK Interactive Regtest Environment

This directory contains scripts for setting up and interacting with a CDK regtest environment for development and testing.

Scripts

1. interactive_regtest_mprocs.sh

Sets up a complete regtest environment with:

• Bitcoin regtest node
• 2 CLN (Core Lightning) nodes with channels
• 2 LND nodes with channels
• 2 CDK mint instances (one connected to CLN, one to LND)

Unlike itests.sh, this script keeps the environment running for interactive use and creates a state file (/tmp/cdk_regtest_env) that allows other terminal sessions to find and interact with the environment.

2. regtest_helper.sh

Helper script providing convenient commands to interact with the running regtest environment. Automatically detects the environment using the state file.

Quick Start

Using just (Recommended)

1. Start the regtest environment:

   just regtest [database_type]
   

   • database_type: Optional, defaults to "sqlite". Can be "sqlite" or "redb"
   • The script will check for mprocs and offer to install it if missing
   • After setup, it will launch mprocs showing logs from all nodes and mints
   • Press 'q' in mprocs to quit and stop the environment

2. In another terminal, interact with Lightning nodes:

   # Get node information
   just ln-cln1 getinfo
   just ln-lnd1 getinfo
   
   # Mine some blocks
   just btc-mine 5
   
   # Check mint status
   just mint-info
   
   # Start mprocs log viewer in another terminal
   just regtest-mprocs
   
   # See all available commands
   just --list
   

Using Scripts Directly

1. Start the regtest environment:

   ./misc/interactive_regtest_mprocs.sh [database_type]
   

   • database_type: Optional, defaults to "sqlite". Can be "sqlite" or "redb"
   • The script will build necessary binaries and set up the full environment
   • Keep this terminal open - the environment runs until you press Ctrl+C

2. In another terminal, use the helper script:

   ./misc/regtest_helper.sh help
   

How It Works

The interactive regtest environment uses a state file (/tmp/cdk_regtest_env) to share environment information between terminal sessions:

1. When you run just regtest or ./misc/interactive_regtest_mprocs.sh, it creates the state file with all necessary environment variables
2. When you run Lightning node commands in other terminals (e.g., just ln-cln1 getinfo), the helper script automatically sources the state file
3. When the environment shuts down (Ctrl+C), it cleans up the state file automatically

This allows you to use just commands from any terminal without needing to export environment variables manually.

Environment Details

When running, the environment provides:

Network Endpoints

• Bitcoin RPC: 127.0.0.1:18443 (user: testuser, pass: testpass)
• CLN Node 1: Unix socket at $CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc
• CLN Node 2: Unix socket at $CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc
• LND Node 1: HTTPS on localhost:10009
• LND Node 2: HTTPS on 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

The following variables are exported for easy access:

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

Usage Examples

Using just Commands (Recommended)

# Start the environment
just regtest

# In another terminal:
# Get Lightning node info
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 description
just ln-lnd1 payinvoice <bolt11>

# Bitcoin operations  
just btc getblockchaininfo
just btc-mine 10
just btc getbalance

# CDK operations
just mint-info
just mint-test
just restart-mints    # Stop, recompile, and restart mints
just regtest-status
just regtest-logs     # Show recent logs
just regtest-mprocs   # Start mprocs TUI log viewer

Using Helper Script Directly

# Lightning Node Operations
./misc/regtest_helper.sh ln-cln1 getinfo
./misc/regtest_helper.sh ln-lnd1 getinfo
./misc/regtest_helper.sh ln-cln1 invoice 1000 label description
./misc/regtest_helper.sh ln-lnd1 payinvoice <bolt11>

# Bitcoin Operations
./misc/regtest_helper.sh btc getblockchaininfo
./misc/regtest_helper.sh btc-mine 10
./misc/regtest_helper.sh btc getbalance

# CDK Mint Operations
./misc/regtest_helper.sh mint-info
./misc/regtest_helper.sh mint-test
./misc/regtest_helper.sh restart-mints
./misc/regtest_helper.sh show-status

Legacy Examples (for reference)

Direct API Access

# Query mint info directly
curl http://127.0.0.1:8085/v1/info | jq

# Get mint keysets
curl http://127.0.0.1:8085/v1/keysets | jq

Development Workflow

# Terminal 1: Start environment
just regtest

# Terminal 2: Development and testing
just ln-cln1 getinfo  # Check CLN status
just mint-info        # Check mint status  
just mint-test        # Run integration tests

# Or use CDK CLI tools directly with the mint URLs
# The environment sets CDK_TEST_MINT_URL and CDK_TEST_MINT_URL_2
cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info

File Locations

All files are stored in a temporary directory ($CDK_ITESTS_DIR):

$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
│       ├── tls.cert
│       └── data/chain/bitcoin/regtest/admin.macaroon
├── cln_mint/         # CLN mint working directory
│   └── mintd.log
└── lnd_mint/         # LND mint working directory
    └── mintd.log

Cleanup

• Press Ctrl+C in the terminal running interactive_regtest_mprocs.sh
• All processes will be terminated and the temporary directory will be cleaned up automatically
• No manual cleanup is required

Troubleshooting

Environment not starting

• Check that ports 8085, 8087, 18443, 19846, 19847, 10009, 10010 are available
• Ensure you have the necessary dependencies (Bitcoin Core, CLN, LND) available
• Check the logs in $CDK_ITESTS_DIR/cln_mint/mintd.log and $CDK_ITESTS_DIR/lnd_mint/mintd.log

Helper script not working

• Ensure the regtest environment is running first
• The CDK_ITESTS_DIR environment variable must be set (done automatically by interactive_regtest_mprocs.sh)

Connection issues

• Use ./misc/regtest_helper.sh show-status to check component health
• Check mint logs with ./misc/regtest_helper.sh show-logs