cdk-mintd

CDK Mintd

Warning This project is in early development, it does however work with real sats! Always use amounts you don't mind losing.

Cashu mint daemon implementation for the Cashu Development Kit (CDK). This binary provides a complete Cashu mint server implementation with support for multiple database backends and Lightning Network integrations.

Features

• Multiple Database Backends: SQLite, PostgreSQL, and ReDB
• Lightning Network Integration: Support for CLN, LND, LNbits, LDK Node, and test backends
• Authentication: Optional user authentication with OpenID Connect
• Management RPC: gRPC interface for mint management
• Docker Support: Ready-to-use Docker configurations

Lightning Backend Documentation

For detailed configuration of each Lightning backend, see:

• LND - Lightning Network Daemon
• CLN - Core Lightning
• LNbits - LNbits API integration

Installation

Option 1: Download Pre-built Binary

Statically-linked x86_64 Linux binaries are published to each GitHub release. These have zero runtime dependencies and run on any x86_64 Linux system.

Available binaries:

• cdk-mintd-{version}-x86_64 -- standard mint with postgres, prometheus, and redis support
• cdk-mintd-ldk-{version}-x86_64 -- mint with built-in ldk-node Lightning backend

Each release also includes a SHA256SUMS file to verify downloads:

# Download the binary and checksums
curl -LO https://github.com/cashubtc/cdk/releases/latest/download/cdk-mintd-{version}-x86_64
curl -LO https://github.com/cashubtc/cdk/releases/latest/download/SHA256SUMS

# Verify the checksum
sha256sum -c SHA256SUMS --ignore-missing

# Make executable and run
chmod +x cdk-mintd-*-x86_64
./cdk-mintd-*-x86_64 --help

To build static binaries locally, see the Static Binaries section in the Development Guide.

Option 2: Build from Source

This project uses Nix to manage development dependencies.

git clone https://github.com/cashubtc/cdk.git
cd cdk

# Enter lean development environment
nix develop

# OR enter full regtest environment (with bitcoind, cln, lnd, postgres)
nix develop .#regtest

# Build binary
cargo build --bin cdk-mintd --release
# Binary will be at ./target/release/cdk-mintd

Configuration

Important: You must create the working directory and configuration file before starting the mint. The mint does not create them automatically.

Setup Steps

1. Create working directory:

   mkdir -p ~/.cdk-mintd

2. Create configuration file:

   # Copy and customize the example config
   cp example.config.toml ~/.cdk-mintd/config.toml
   # Edit ~/.cdk-mintd/config.toml with your settings

3. Start the mint:

   cdk-mintd  # Uses ~/.cdk-mintd/config.toml automatically

Configuration File Locations (in order of precedence)

1. Explicit path: cdk-mintd --config /path/to/config.toml
2. Working directory: ./config.toml (in current directory)
3. Default location: ~/.cdk-mintd/config.toml
4. Environment variables: All config options can be set via environment variables

Alternative Setup Methods

Custom working directory:

mkdir -p /my/custom/path
cp example.config.toml /my/custom/path/config.toml
cdk-mintd --work-dir /my/custom/path

Environment variables only:

export CDK_MINTD_LISTEN_PORT=3000
export CDK_MINTD_LN_BACKEND=fakewallet
export CDK_MINTD_DATABASE=sqlite
cdk-mintd

Keyset Version Management

The mint supports rotating keysets to newer versions (e.g., migrating from V1 to V2).

Policy Configuration: By default, the mint will use V2 (Version01) for new keysets but will preserve existing V1 (Version00) keysets to avoid unnecessary rotation. You can force a specific policy using config.toml or environment variables:

• use_keyset_v2 = true (or CDK_MINTD_USE_KEYSET_V2=true): Forces V2. If the current active keyset is V1, it will be rotated to V2 on startup.
• use_keyset_v2 = false (or CDK_MINTD_USE_KEYSET_V2=false): Forces V1. If the current active keyset is V2, it will be rotated to V1 on startup.
• Unset (Default): Preserves the current keyset version. If no keyset exists, V2 is created.

Manual Rotation: You can manually trigger a rotation to a specific version using the CLI:

mint-cli rotate-next-keyset --use-keyset-v2       # Rotate to V2
mint-cli rotate-next-keyset --use-keyset-v2=false # Rotate to V1

Production Examples

With LDK Node (Recommended for Testing)

[ln]
ln_backend = "ldk-node"

[ldk_node]
bitcoin_network = "signet"  # Use "mainnet" for production
esplora_url = "https://mutinynet.com/api"
rgs_url = "https://rgs.mutinynet.com/snapshot/0"
gossip_source_type = "rgs"
storage_dir_path = "/var/lib/cdk-mintd/ldk-node"

With CLN Lightning Backend

[ln]
ln_backend = "cln"

[cln]
rpc_path = "/home/bitcoin/.lightning/bitcoin/lightning-rpc"
# fee_percent = 0.02      # Optional, defaults to 2%
# reserve_fee_min = 2     # Optional, defaults to 2 sats

With LND Lightning Backend

[ln]
ln_backend = "lnd"

[lnd]
address = "https://localhost:10009"
macaroon_file = "/home/bitcoin/.lnd/data/chain/bitcoin/mainnet/admin.macaroon"
cert_file = "/home/bitcoin/.lnd/tls.cert"
# fee_percent = 0.02      # Optional, defaults to 2%
# reserve_fee_min = 2     # Optional, defaults to 2 sats

With PostgreSQL Database

[database]
engine = "postgres"

[database.postgres]
url = "postgresql://mint_user:password@localhost:5432/cdk_mint"

Directory Structure

After setup and first run, your directory will look like:

~/.cdk-mintd/                    # Working directory (create manually)
├── config.toml                  # Config file (create manually)
├── cdk-mintd.db                # SQLite database (created automatically)
├── logs/                       # Log files (created automatically if enabled)
│   ├── cdk-mintd.2024-01-01.log
│   └── cdk-mintd.2024-01-02.log
└── ldk-node/                   # LDK Node data (if using LDK backend)
    ├── wallet/
    └── graph/

What you must create manually:

• Working directory (e.g., ~/.cdk-mintd/)
• Config file (config.toml)

What gets created automatically:

• Database files
• Log directories and files
• Lightning backend data directories

Docker Usage

CDK Mintd provides ready-to-use Docker images with multiple Lightning backend options.

Quick Start

Standard mint with fakewallet backend (testing only):

docker-compose up

Mint with LDK Node backend:

# Option 1: Use dedicated ldk-node compose file
docker-compose -f docker-compose.ldk-node.yaml up

# Option 2: Use main compose file with profile
docker-compose --profile ldk-node up

Available Images

• cashubtc/mintd:latest - Standard mint with default features
• cashubtc/mintd-ldk-node:latest - Mint with LDK Node support

Configuration via Environment Variables

All configuration can be done through environment variables:

environment:
  - CDK_MINTD_LN_BACKEND=ldk-node
  - CDK_MINTD_DATABASE=sqlite
  - CDK_MINTD_LISTEN_HOST=0.0.0.0
  - CDK_MINTD_LISTEN_PORT=8085
  - CDK_MINTD_LDK_NODE_NETWORK=testnet
  - CDK_MINTD_LDK_NODE_ESPLORA_URL=https://blockstream.info/testnet/api

Monitoring

Both Prometheus metrics and Grafana dashboards are included:

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3011 (admin/admin)

For detailed Docker documentation, see README-ldk-node.md.

Testing Your Mint

1. Verify the mint is running:

   curl http://127.0.0.1:8085/v1/info

2. Get mint keys:

   curl http://127.0.0.1:8085/v1/keys

3. Test with CDK CLI wallet:

   # Download from: https://github.com/cashubtc/cdk/releases
   cdk-cli wallet add-mint http://127.0.0.1:8085
   cdk-cli wallet mint-quote 100

4. For LDK Node backend: Access the management interface at http://127.0.0.1:8091

Command Line Usage

# Start with default configuration
cdk-mintd

# Start with custom config file
cdk-mintd --config /path/to/config.toml

# Start with custom working directory
cdk-mintd --work-dir /path/to/work/dir

# Disable logging
cdk-mintd --enable-logging false

# Show help
cdk-mintd --help

Key Environment Variables

• CDK_MINTD_DATABASE: Database engine (sqlite/postgres/redb)
• CDK_MINTD_DATABASE_URL: PostgreSQL connection string
• CDK_MINTD_LN_BACKEND: Lightning backend (cln/lnd/lnbits/ldk-node/fakewallet)
• CDK_MINTD_LISTEN_HOST: Host to bind to (default: 127.0.0.1)
• CDK_MINTD_LISTEN_PORT: Port to bind to (default: 8085)

For complete configuration options, see the example configuration file.

Documentation

• Configuration Examples - Complete configuration reference
• PostgreSQL Setup Guide - Database setup with Docker Compose
• Development Guide - Contributing and development setup

License

This project is licensed under the MIT License.