mirror of
https://github.com/aljazceru/cdk.git
synced 2025-12-27 17:45:08 +01:00
268 lines
6.9 KiB
Markdown
268 lines
6.9 KiB
Markdown
# 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 <bolt11>
|
|
|
|
# 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 <bolt11_from_above>
|
|
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! 🎉
|