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

Create working directory:
```
mkdir -p ~/.cdk-mintd
```

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

Start the mint:

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

Configuration File Locations (in order of precedence)

Explicit path: cdk-mintd --config /path/to/config.toml
Working directory: ./config.toml (in current directory)
Default location: ~/.cdk-mintd/config.toml
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

Fake Wallet Custom Payment Methods

The fake wallet backend can advertise custom payment methods for testing NUT-04 and NUT-05 custom payment flows. Configure methods in config.toml with one entry per method and unit:

[[ln]]
ln_backend = "fakewallet"
unit = "sat"

[[ln]]
ln_backend = "fakewallet"
unit = "usd"

[fake_wallet]
custom_payment_methods = [
    { method = "paypal", unit = "sat" },
    { method = "venmo", unit = "usd" },
]

For a single fake wallet unit, the legacy [ln] table is still accepted and defaults to unit = "sat". For multiple fake wallet units, use one [[ln]] entry per unit.

For Docker or env-only setups, set CDK_MINTD_FAKE_WALLET_SUPPORTED_UNITS to register multiple fake wallet units:

export CDK_MINTD_LN_BACKEND=fakewallet
export CDK_MINTD_FAKE_WALLET_SUPPORTED_UNITS=sat,usd
export CDK_MINTD_FAKE_WALLET_CUSTOM_PAYMENT_METHODS=paypal:sat,venmo:usd

Bare method names are enabled for every fake wallet unit:

custom_payment_methods = ["paypal"]

Disable fake custom methods with:

custom_payment_methods = []

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"

With Multiple Lightning Backends

A single mint can serve more than one currency unit by configuring a separate backend per unit. Replace the single [ln] block with one [[ln]] block per backend/unit, and keep the existing per-backend config sections ([cln], [lnbits], etc.) as-is.

[[ln]]
ln_backend = "cln"
unit = "sat"

[[ln]]
ln_backend = "lnbits"
unit = "msat"

[cln]
rpc_path = "/home/bitcoin/.lightning/bitcoin/lightning-rpc"

[lnbits]
admin_api_key = "..."
invoice_api_key = "..."
lnbits_api = "https://lnbits.example.com"

Each [[ln]] block carries its own min_mint, max_mint, min_melt, max_melt if you want different limits per unit. The configured unit must match the backend's reported unit, except for the supported sat/msat conversion pair. If two configured backends expose the same (unit, method) pair, startup is rejected.

The legacy single [ln] form is still accepted; it's equivalent to one [[ln]] entry with unit = "sat" (the default). CDK_MINTD_LN_* environment variables only apply when there is exactly one (or zero) [[ln]] entry — multi-backend setups must be configured via the file.

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=fakewallet
  - CDK_MINTD_DATABASE=sqlite
  - CDK_MINTD_LISTEN_HOST=0.0.0.0
  - CDK_MINTD_LISTEN_PORT=8085
  - CDK_MINTD_FAKE_WALLET_SUPPORTED_UNITS=sat,usd
  - CDK_MINTD_FAKE_WALLET_CUSTOM_PAYMENT_METHODS=paypal:sat,venmo:usd

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

Verify the mint is running:
```
curl http://127.0.0.1:8085/v1/info
```
Get mint keys:
```
curl http://127.0.0.1:8085/v1/keys
```

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

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

# Start with the mint and active payment backend seed phrase read from a file
cdk-mintd --seed-file /path/to/seed

# 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_FAKE_WALLET_CUSTOM_PAYMENT_METHODS: Comma-separated fake wallet custom methods, optionally scoped as method:unit
CDK_MINTD_LISTEN_HOST: Host to bind to (default: 127.0.0.1)
CDK_MINTD_LISTEN_PORT: Port to bind to (default: 8085)
CDK_MINTD_MNEMONIC: Mint seed phrase

--seed-file reads a BIP-39 seed phrase from a file and applies it to the mint and to active mnemonic-backed payment backends such as BDK. It overrides configured raw mint seeds and mint mnemonics.

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.

cdk-mintd 0.17.1