From a97eb84db6b79fee3657e47e36a0471cb491ab85 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 8 Jul 2025 11:09:20 +0100 Subject: [PATCH] chore: update docs --- DEVELOPMENT.md | 23 ++++ MPROCS_INTEGRATION.md | 147 ----------------------- MPROCS_MODES.md | 132 --------------------- REGTEST_GUIDE.md | 267 ++++++++++++++++++++++++++++++++++++++++++ REGTEST_QUICKSTART.md | 125 -------------------- misc/README.md | 218 ---------------------------------- 6 files changed, 290 insertions(+), 622 deletions(-) delete mode 100644 MPROCS_INTEGRATION.md delete mode 100644 MPROCS_MODES.md create mode 100644 REGTEST_GUIDE.md delete mode 100644 REGTEST_QUICKSTART.md delete mode 100644 misc/README.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 1306fbc9..0d24c69d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -69,6 +69,29 @@ If the Nix installation is in multi-user mode, don’t forget to restart the nix nix develop -c $SHELL ``` +## Regtest Environment + +For testing and development, CDK provides a complete regtest environment with Bitcoin, Lightning Network nodes, and CDK mints. + +### Quick Start +```bash +just regtest # Starts full environment with mprocs TUI +``` + +This provides: +- Bitcoin regtest node +- 4 Lightning Network nodes (2 CLN + 2 LND) +- 2 CDK mints (one connected to CLN, one to LND) +- Real-time log monitoring via mprocs +- Helper commands for testing Lightning payments and CDK operations + +### Comprehensive Guide +See [REGTEST_GUIDE.md](REGTEST_GUIDE.md) for complete documentation including: +- Detailed setup and usage instructions +- Development workflows and testing scenarios +- mprocs TUI interface guide +- Troubleshooting and advanced usage + ## Common Development Tasks ### Building the Project diff --git a/MPROCS_INTEGRATION.md b/MPROCS_INTEGRATION.md deleted file mode 100644 index 79aee0fe..00000000 --- a/MPROCS_INTEGRATION.md +++ /dev/null @@ -1,147 +0,0 @@ -# mprocs Integration for CDK Regtest - -The CDK regtest environment now integrates with `mprocs` to provide a beautiful TUI (Terminal User Interface) for monitoring all component logs in real-time. - -## What is mprocs? - -`mprocs` is a TUI for running multiple processes and monitoring their output. Perfect for development environments where you need to watch logs from multiple services simultaneously. - -## Features - -### Automatic Setup -- The regtest script checks for `mprocs` and offers to install it if missing -- Creates a dynamic mprocs configuration with all relevant log files -- Handles missing log files gracefully (waits for them to be created) - -### Components Monitored -- **cln-mint**: CDK mint connected to CLN -- **lnd-mint**: CDK mint connected to LND -- **bitcoind**: Bitcoin regtest node -- **cln-one**: Core Lightning node #1 -- **cln-two**: Core Lightning node #2 -- **lnd-one**: LND node #1 -- **lnd-two**: LND node #2 - -### Key Benefits -- **Real-time log monitoring** for all components -- **Side-by-side view** of related services -- **Easy navigation** between different logs -- **Scrollback** to review history -- **Search functionality** within logs -- **Process management** (start/stop/restart individual processes) - -## Usage - -### Automatic (Recommended) - Log Tailing Mode -```bash -just regtest -# After setup completes, mprocs launches automatically -# Mints start and log to files, mprocs shows log contents -``` - -### Direct Process Management Mode -```bash -just regtest-mprocs -# After setup, mprocs starts with mint processes stopped -# Use 's' key to start individual mints -# Full process control from within mprocs -``` - -### Manual Launch -```bash -# Start environment without mprocs -just regtest - -# In another terminal, launch mprocs -just regtest-logs -``` - -### Commands Available -```bash -just regtest # Starts environment and mprocs (log tailing mode) -just regtest-mprocs # Starts environment with direct process management -just regtest-logs # Manual mprocs launch (adapts to current mode) -``` - -## mprocs Controls - -### Direct Process Management Mode: -- **Arrow keys**: Navigate between processes -- **s**: Start the selected process -- **k**: Kill the selected process -- **r**: Restart the selected process -- **Enter**: Focus on selected process -- **Tab**: Switch between process list and log view -- **?**: Show help -- **q**: Quit mprocs (stops all managed processes) - -### Log Tailing Mode: -- **Arrow keys**: Navigate between processes -- **Enter**: Focus on selected process -- **Tab**: Switch between process list and log view -- **PageUp/PageDown**: Scroll through logs -- **Ctrl+C**: Interrupt current process -- **q**: Quit mprocs (processes continue running) - -## Installation - -If `mprocs` is not installed: -```bash -# Automatic installation prompt when running regtest -just regtest - -# Manual installation -cargo install mprocs - -# Or via package manager (varies by OS) -# Ubuntu/Debian: apt install mprocs -# macOS: brew install mprocs -``` - -## Configuration - -The mprocs configuration is automatically generated at `$CDK_ITESTS_DIR/mprocs.yaml`. It includes: - -- Proper log file paths for all components -- Graceful handling of missing files -- Optimized UI settings for development -- Auto-start for all monitoring processes - -## Development Workflow - -### Before mprocs: -- Start regtest environment -- Open multiple terminals to `tail -f` different log files -- Manually manage multiple windows/panes -- Switch between terminals to see different components - -### With mprocs: -- Start regtest environment → automatic log monitoring -- Single TUI shows all component logs -- Easy navigation between components -- Professional development experience - -## Example View - -``` -┌─Processes─────────┬─Output───────────────────────────────────────┐ -│ ● cln-mint │ 2024-07-08T08:30:12 INFO cdk_mintd: Starting │ -│ ● lnd-mint │ mint server on 127.0.0.1:8085 │ -│ ● bitcoind │ 2024-07-08T08:30:13 INFO: New invoice │ -│ ● cln-one │ received for 1000 sats │ -│ ● cln-two │ 2024-07-08T08:30:14 INFO: Payment │ -│ ● lnd-one │ successful │ -│ ● lnd-two │ │ -│ │ │ -└───────────────────┴──────────────────────────────────────────────┘ -``` - -## Fallback - -If mprocs is not available or fails: -- Environment continues to work normally -- Falls back to simple wait loop -- All `just` commands work as expected -- Logs still accessible via `just regtest-logs` - -This integration makes CDK development much more pleasant by providing professional-grade log monitoring out of the box! 🎉 diff --git a/MPROCS_MODES.md b/MPROCS_MODES.md deleted file mode 100644 index 06faea0e..00000000 --- a/MPROCS_MODES.md +++ /dev/null @@ -1,132 +0,0 @@ -# mprocs Process Management Modes - -The CDK regtest environment now supports two different modes for managing processes with mprocs: - -## Mode 1: Log Tailing (Default) -**Command**: `just regtest` - -### How it works: -- Mints are started by the bash script and run in the background -- Mints write their output to log files (`mintd.log`) -- mprocs uses `tail -f` to follow these log files -- Log files persist even after mprocs exits - -### Pros: -- ✅ Log files are preserved for later analysis -- ✅ Simple setup -- ✅ Works even if mprocs crashes - -### Cons: -- ❌ Cannot restart mints from within mprocs -- ❌ Must use external commands to control mints -- ❌ mprocs shows file contents, not live processes - -## Mode 2: Direct Process Management -**Command**: `just regtest-mprocs` - -### How it works: -- mprocs directly manages the mint processes -- Mints are started/stopped by mprocs itself -- Output goes directly to mprocs (no log files by default) -- Full process control from within mprocs - -### Pros: -- ✅ Start/stop/restart mints directly from mprocs -- ✅ Live process output -- ✅ Better development workflow -- ✅ Process status indicators - -### Cons: -- ❌ Output not saved to files (unless configured) -- ❌ If mprocs crashes, you lose the processes - -## mprocs Controls - -### Direct Process Management Mode: -- **Arrow keys**: Navigate between processes -- **s**: Start the selected process -- **k**: Kill the selected process -- **r**: Restart the selected process -- **Enter**: Focus on a process (see its output) -- **Tab**: Switch between process list and output -- **?**: Show help -- **q**: Quit mprocs (stops all managed processes) - -### Log Tailing Mode: -- **Arrow keys**: Navigate between log sources -- **Enter**: Focus on a log source -- **Tab**: Switch between process list and log view -- **PageUp/PageDown**: Scroll through logs -- **q**: Quit mprocs (processes continue running) - -## Usage Examples - -### Start with Log Tailing (Original Mode) -```bash -just regtest -# Mints start automatically and log to files -# mprocs shows log contents -# Use Ctrl+C or 'q' to exit mprocs -# Processes continue running in background -``` - -### Start with Direct Process Management -```bash -just regtest-mprocs -# Only Lightning network starts automatically -# In mprocs, navigate to "cln-mint" and press 's' to start it -# Navigate to "lnd-mint" and press 's' to start it -# Use 'r' to restart mints after code changes -# Use 'q' to exit and stop all processes -``` - -### Switch Between Modes - -If you started with log tailing mode, you can access the direct management: -```bash -# In another terminal -source /tmp/cdk_regtest_env -just regtest-logs # This will detect the mode and adapt -``` - -## Development Workflow Comparison - -### Traditional (Log Tailing): -1. `just regtest` -2. Make code changes -3. In another terminal: `just restart-mints` -4. Check logs in mprocs - -### Direct Management: -1. `just regtest-mprocs` -2. Press 's' to start mints -3. Make code changes -4. In mprocs: press 'r' on each mint to restart -5. Watch live output directly - -## Technical Details - -### Project Root Handling -The direct process management mode ensures that: -- Startup scripts change to the correct project root directory -- Cargo commands run from where the `Cargo.toml` file is located -- Environment variables are properly set before starting processes - -### File Structure -``` -$CDK_ITESTS_DIR/ -├── start_cln_mint.sh # Sets PROJECT_ROOT and runs cargo from there -├── start_lnd_mint.sh # Sets PROJECT_ROOT and runs cargo from there -└── mprocs.yaml # Points to the startup scripts -``` - -Each startup script: -1. Changes to the project root directory (`cd "$PROJECT_ROOT"`) -2. Sets all required environment variables -3. Executes `cargo run --bin cdk-mintd` from the correct location - -The environment variables and helper commands work the same in both modes: -- `just ln-cln1 getinfo` -- `just btc-mine 5` -- `just mint-info` -- etc. diff --git a/REGTEST_GUIDE.md b/REGTEST_GUIDE.md new file mode 100644 index 00000000..91958648 --- /dev/null +++ b/REGTEST_GUIDE.md @@ -0,0 +1,267 @@ +# 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 +```bash +# 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 +```bash +# 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 + +# Check balances and channels +just ln-cln1 listfunds +just ln-lnd1 listchannels +``` + +### Bitcoin Operations +```bash +just btc getblockchaininfo # Blockchain status +just btc getbalance # Wallet balance +just btc-mine 5 # Mine 5 blocks +``` + +### CDK Mint Operations +```bash +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 +```bash +# Terminal 1: Start environment +just regtest + +# Terminal 2: Create invoice and pay +just ln-cln1 invoice 1000 test "Test payment" +just ln-lnd1 payinvoice +just ln-cln1 listinvoices +just ln-lnd1 listpayments +``` + +### Developing Mint Code +```bash +# 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 +```bash +# 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 +```bash +# 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: +```bash +# 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 +```bash +# 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" +```bash +# Find and kill processes using ports +sudo lsof -ti:8085 | xargs kill -9 +sudo lsof -ti:8087 | xargs kill -9 +``` + +### "Environment not found" +```bash +# Clean up and restart +rm -f /tmp/cdk_regtest_env +just regtest +``` + +### "Binary not found" +```bash +# Rebuild binaries +just build +just regtest +``` + +This environment provides everything needed for CDK development and testing in a single, easy-to-use interface! 🎉 diff --git a/REGTEST_QUICKSTART.md b/REGTEST_QUICKSTART.md deleted file mode 100644 index f02bedf6..00000000 --- a/REGTEST_QUICKSTART.md +++ /dev/null @@ -1,125 +0,0 @@ -# CDK Interactive Regtest - Quick Start - -A simple guide to get up and running with the interactive regtest environment. - -## Start Environment - -```bash -# Terminal 1: Start regtest with default sqlite database -just regtest - -# Or with redb database -just regtest redb -``` - -The script will: -1. Check for `mprocs` and offer to install it if missing -2. Set up the regtest environment (Bitcoin + Lightning nodes + CDK mints) -3. Launch `mprocs` showing logs from all components -4. Press 'q' in mprocs to quit and stop the environment - -## Use Lightning Nodes (in any other terminal) - -The `just` commands work from any terminal - they automatically find the running environment. - -### Get Node Information -```bash -just ln-cln1 getinfo # CLN node 1 -just ln-cln2 getinfo # CLN node 2 -just ln-lnd1 getinfo # LND node 1 -just ln-lnd2 getinfo # LND node 2 -``` - -### Create and Pay Invoices -```bash -# Create 1000 sat invoice on CLN -just ln-cln1 invoice 1000 test_label "Test payment" - -# Pay invoice with LND (use the bolt11 from above) -just ln-lnd1 payinvoice lnbcrt10u1... - -# Check balances -just ln-cln1 listfunds -just ln-lnd1 listchannels -``` - -## Bitcoin Operations - -```bash -just btc getblockchaininfo # Blockchain status -just btc getbalance # Wallet balance -just btc-mine 5 # Mine 5 blocks -``` - -## CDK Mint Operations - -```bash -just mint-info # Show both mints' info -just mint-test # Run integration tests -just restart-mints # Stop, recompile, and restart mints -just regtest-status # Check all components -just regtest-logs # Show recent logs -just regtest-mprocs # Start mprocs TUI (if not already running) -``` - -## Stop Environment - -Press `Ctrl+C` in the terminal running `just regtest`. Everything will be cleaned up automatically. - -## Available Endpoints - -- **CLN Mint**: http://127.0.0.1:8085 -- **LND Mint**: http://127.0.0.1:8087 -- **Bitcoin RPC**: 127.0.0.1:18443 (testuser/testpass) - -## Common Workflows - -### Test Lightning Payment Flow -```bash -# Terminal 1 -just regtest - -# Terminal 2 -just ln-cln1 invoice 1000 test "Test payment" -# Copy the bolt11 invoice - -just ln-lnd1 payinvoice -just ln-cln1 listinvoices -just ln-lnd1 listpayments -``` - -### Test CDK Integration -```bash -# Terminal 1 -just regtest - -# Terminal 2 -just mint-test # Run all tests -cargo test -p cdk-integration-tests # Or specific tests -``` - -### Development with CDK CLI -```bash -# Terminal 1 -just regtest - -# Terminal 2 - use environment variables -echo $CDK_TEST_MINT_URL # CLN mint URL -echo $CDK_TEST_MINT_URL_2 # LND mint URL - -# Use with CDK CLI -cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info -``` - -### Development Workflow (Mint Code Changes) -```bash -# Terminal 1: Keep regtest running -just regtest - -# Terminal 2: Make changes to mint code, then -just restart-mints # Recompiles and restarts both mints -just mint-info # Test the changes -just mint-test # Run integration tests -``` - -That's it! The environment provides a full Lightning Network with CDK mints for testing and development. diff --git a/misc/README.md b/misc/README.md deleted file mode 100644 index a61e3242..00000000 --- a/misc/README.md +++ /dev/null @@ -1,218 +0,0 @@ -# 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:** - ```bash - 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:** - ```bash - # 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:** - ```bash - ./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:** - ```bash - ./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) - -```bash -# 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 - -# 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 - -```bash -# 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 - -# 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 -```bash -# 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 -```bash -# 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`