chore: some docs (#1083)

README.md

@@ -36,22 +36,6 @@ The project is split up into several crates in the `crates/` directory:
 
 For a guide to settings up a development environment see [DEVELOPMENT.md](./DEVELOPMENT.md)
 
-## LDK Node Network Configuration
-
-For detailed configuration examples for running CDK with LDK Node on different Bitcoin networks (Mutinynet, Testnet, Mainnet), see [LDK Node Network Guide](./crates/cdk-ldk-node/NETWORK_GUIDE.md).
-
-**Quick Start with Mutinynet (Recommended for Testing):**
-```toml
-[ln]
-ln_backend = "ldk-node"
-
-[ldk_node]
-bitcoin_network = "signet"
-esplora_url = "https://mutinynet.com/api"
-rgs_url = "https://rgs.mutinynet.com/snapshot/0"
-gossip_source_type = "rgs"
-```
-
 ## Implemented [NUTs](https://github.com/cashubtc/nuts/):
 
 ### Mandatory

crates/cdk-cli/README.md

@@ -1,14 +1,189 @@
+# CDK CLI
+
+[![crates.io](https://img.shields.io/crates/v/cdk-cli.svg)](https://crates.io/crates/cdk-cli)
+[![Documentation](https://docs.rs/cdk-cli/badge.svg)](https://docs.rs/cdk-cli)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cashubtc/cdk/blob/main/LICENSE)
+
 > **Warning**
 > This project is in early development, it does however work with real sats! Always use amounts you don't mind losing.
 
-cdk-cli is a CLI wallet implementation using of CDK(../cdk)
+A command-line Cashu wallet implementation built with the Cashu Development Kit (CDK). This tool allows you to interact with Cashu mints from the terminal, performing operations like minting, melting, and transferring ecash tokens.
+
+## Features
+
+- **Multiple Mint Support**: Connect to and manage multiple Cashu mints
+- **Token Operations**: Mint, melt, send, and receive Cashu tokens
+- **Wallet Management**: Create and manage multiple wallets
+- **Lightning Integration**: Pay Lightning invoices and receive payments
+- **Token Storage**: Secure local storage of tokens and mint configurations
+
+## Installation
+
+### Option 1: Download Pre-built Binary
+Download the latest release from the [GitHub releases page](https://github.com/cashubtc/cdk/releases).
+
+### Option 2: Build from Source
+```bash
+git clone https://github.com/cashubtc/cdk.git
+cd cdk
+cargo build --bin cdk-cli --release
+# Binary will be at ./target/release/cdk-cli
+```
+
+## Quick Start
+
+### 1. Add a Mint
+```bash
+# Add a mint (use a real mint URL or start your own with cdk-mintd)
+cdk-cli wallet add-mint http://127.0.0.1:8085
+```
+
+### 2. Mint Tokens
+```bash
+# Create a mint quote for 100 sats
+cdk-cli wallet mint-quote 100
+
+# Pay the Lightning invoice shown, then mint the tokens
+cdk-cli wallet mint <quote_id>
+```
+
+### 3. Send Tokens
+```bash
+# Send 50 sats as a token
+cdk-cli wallet send 50
+```
+
+### 4. Receive Tokens
+```bash
+# Receive a token from someone else
+cdk-cli wallet receive <cashu_token>
+```
+
+### 5. Check Balance
+```bash
+# View your current balance
+cdk-cli wallet balance
+```
+
+## Basic Usage
+
+### Wallet Operations
+```bash
+# List all wallets
+cdk-cli wallet list
+
+# Create a new wallet
+cdk-cli wallet new --name my-wallet
+
+# Set default wallet
+cdk-cli wallet set-default my-wallet
+
+# Show wallet info
+cdk-cli wallet info
+```
+
+### Mint Management
+```bash
+# List connected mints
+cdk-cli wallet list-mints
+
+# Remove a mint
+cdk-cli wallet remove-mint <mint_url>
+
+# Get mint information
+cdk-cli wallet mint-info <mint_url>
+```
+
+### Payment Operations
+```bash
+# Pay a Lightning invoice
+cdk-cli wallet pay-invoice <lightning_invoice>
+
+# Create melt quote for an invoice
+cdk-cli wallet melt-quote <lightning_invoice>
+
+# Execute the melt
+cdk-cli wallet melt <quote_id>
+```
+
+### Token Management
+```bash
+# List all tokens
+cdk-cli wallet list-tokens
+
+# Check token states
+cdk-cli wallet check-tokens
+
+# Restore wallet from seed
+cdk-cli wallet restore --seed <seed_words>
+```
+
+## Configuration
+
+The CLI stores its configuration and wallet data in:
+- **Linux/macOS**: `~/.config/cdk-cli/`
+- **Windows**: `%APPDATA%\cdk-cli\`
+
+## Examples
+
+### Complete Workflow Example
+```bash
+# 1. Start a test mint (in another terminal)
+cdk-mintd
+
+# 2. Add the mint
+cdk-cli wallet add-mint http://127.0.0.1:8085
+
+# 3. Create a mint quote
+cdk-cli wallet mint-quote 1000
+
+# 4. Pay the Lightning invoice (if using real Lightning backend)
+# or wait a few seconds if using fake wallet
+
+# 5. Mint the tokens
+cdk-cli wallet mint <quote_id>
+
+# 6. Check balance
+cdk-cli wallet balance
+
+# 7. Send some tokens
+cdk-cli wallet send 100
+
+# 8. The recipient can receive with:
+cdk-cli wallet receive <cashu_token_string>
+```
+
+### Working with Multiple Wallets
+```bash
+# Create wallets for different purposes
+cdk-cli wallet new --name savings
+cdk-cli wallet new --name daily
+
+# Switch between wallets
+cdk-cli wallet set-default savings
+cdk-cli wallet balance
+
+cdk-cli wallet set-default daily
+cdk-cli wallet balance
+```
+
+## Help and Documentation
+
+```bash
+# General help
+cdk-cli --help
+
+# Help for specific commands
+cdk-cli wallet --help
+cdk-cli wallet mint-quote --help
+```
 
 ## License
 
-Code is under the [MIT](../../LICENSE)
+Code is under the [MIT License](../../LICENSE)
 
 ## Contribution
 
-All contributions welcome.
+All contributions are welcome.
 
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.

crates/cdk-mintd/README.md

@@ -4,176 +4,226 @@
 [![Documentation](https://docs.rs/cdk-mintd/badge.svg)](https://docs.rs/cdk-mintd)
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cashubtc/cdk/blob/main/LICENSE)
 
-**ALPHA** This library is in early development, the API will change and should be used with caution.
+> **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 and PostgreSQL
-- **Lightning Network Integration**: Support for CLN, LND, LNbits, and test backends  
+- **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
 
 ## Installation
 
-From crates.io:
-```bash
-cargo install cdk-mintd
-```
+### Option 1: Download Pre-built Binary
+Download the latest release from the [GitHub releases page](https://github.com/cashubtc/cdk/releases).
 
-From source:
+### Option 2: Build from Source
 ```bash
-cargo install --path .
+git clone https://github.com/cashubtc/cdk.git
+cd cdk
+cargo build --bin cdk-mintd --release
+# Binary will be at ./target/release/cdk-mintd
 ```
 
 ## Quick Start
 
-### Using SQLite (Default)
-```bash
-# Start with SQLite (no additional setup required)
-cdk-mintd
-```
+The fastest way to get started for testing:
 
-### Using PostgreSQL
 ```bash
-# Set environment variables
-export CDK_MINTD_DATABASE=postgres
-export CDK_MINTD_DATABASE_URL="postgresql://postgres:password@localhost:5432/cdk_mint"
+# Create working directory and copy example config
+mkdir -p ~/.cdk-mintd
+cp example.config.toml ~/.cdk-mintd/config.toml
 
-# Start the mint
+# Start the mint (uses SQLite + fake wallet by default)
 cdk-mintd
 ```
 
-### Using Docker
+The mint will be available at `http://127.0.0.1:8085`. Test it with:
 ```bash
-# SQLite
-docker-compose up
-
-# PostgreSQL
-docker-compose -f docker-compose.postgres.yaml up
+curl http://127.0.0.1:8085/v1/info
 ```
 
 ## Configuration
 
-The mint can be configured through environment variables or a configuration file. See `example.config.toml` for all available options.
+> **Important**: You must create the working directory and configuration file before starting the mint. The mint does not create them automatically.
 
-### Database Configuration
+### Setup Steps
 
-#### SQLite (Default)
-```toml
-[database]
-engine = "sqlite"
+1. **Create working directory**:
+   ```bash
+   mkdir -p ~/.cdk-mintd
+   ```
+
+2. **Create configuration file**:
+   ```bash
+   # 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**:
+   ```bash
+   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**:
+```bash
+mkdir -p /my/custom/path
+cp example.config.toml /my/custom/path/config.toml
+cdk-mintd --work-dir /my/custom/path
 ```
 
-#### PostgreSQL  
-```toml
-[database]
-engine = "postgres"
+**Environment variables only**:
+```bash
+export CDK_MINTD_LISTEN_PORT=3000
+export CDK_MINTD_LN_BACKEND=fakewallet
+export CDK_MINTD_DATABASE=sqlite
+cdk-mintd
 ```
-Set `CDK_MINTD_DATABASE_URL` environment variable for connection string.
 
-#### ReDB
+## Production Examples
+
+### With LDK Node (Recommended for Testing)
 ```toml
-[database]
-engine = "redb"
+[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"
 ```
 
-### Lightning Backend Configuration
 
+### With CLN Lightning Backend
 ```toml
 [ln]
-ln_backend = "fakewallet"  # Options: cln, lnd, lnbits, fakewallet
-```
+ln_backend = "cln"
 
-### Logging Configuration
+[cln]
+rpc_path = "/home/bitcoin/.lightning/bitcoin/lightning-rpc"
+fee_percent = 0.01
+reserve_fee_min = 10
+```
 
-You can configure where mintd outputs its logs using the `[info.logging]` section in your config file or environment variables:
+### With LND Lightning Backend
+```toml
+[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.01
+reserve_fee_min = 10
+```
 
-**Config file:**
+### With PostgreSQL Database
 ```toml
-[info.logging]
-# Where to output logs: "stdout", "file", or "both" (default: "both")
-output = "both"
-# Log level for console output (default: "info")
-console_level = "info"  
-# Log level for file output (default: "debug")
-file_level = "debug"
+[database]
+engine = "postgres"
+
+[database.postgres]
+url = "postgresql://mint_user:password@localhost:5432/cdk_mint"
 ```
 
-**Environment variables:**
-```bash
-# Where to output logs: "stdout", "file", or "both" (default: "both")
-export CDK_MINTD_LOGGING_OUTPUT="both"
-# Log level for console output (default: "info")
-export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug"
-# Log level for file output (default: "debug")
-export CDK_MINTD_LOGGING_FILE_LEVEL="debug"
+## 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/
 ```
 
-**Available logging outputs:**
-- `"stdout"` - Output logs only to console/terminal (stderr)
-- `"file"` - Output logs only to rotating daily log files in `<work_dir>/logs/`
-- `"both"` - Output logs to both console and files (default behavior)
+**What you must create manually:**
+- Working directory (e.g., `~/.cdk-mintd/`)
+- Config file (`config.toml`)
 
-**Available log levels:** `error`, `warn`, `info`, `debug`, `trace`
+**What gets created automatically:**
+- Database files
+- Log directories and files
+- Lightning backend data directories
 
-**Examples:**
+## Testing Your Mint
 
-Console only with debug level:
-```bash
-export CDK_MINTD_LOGGING_OUTPUT="stdout"
-export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug"
-```
+1. **Verify the mint is running**:
+   ```bash
+   curl http://127.0.0.1:8085/v1/info
+   ```
 
-File only with debug level:
-```toml
-[info.logging]
-output = "file"
-file_level = "debug"
-```
+2. **Get mint keys**:
+   ```bash
+   curl http://127.0.0.1:8085/v1/keys
+   ```
 
-Both console (warn) and file (debug):
-```bash
-export CDK_MINTD_LOGGING_OUTPUT="both"
-export CDK_MINTD_LOGGING_CONSOLE_LEVEL="warn"
-export CDK_MINTD_LOGGING_FILE_LEVEL="debug"
-```
+3. **Test with CDK CLI wallet**:
+   ```bash
+   # 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>
 
-## Usage
+## Command Line Usage
 
 ```bash
-# Start the mint with default configuration
+# Start with default configuration
 cdk-mintd
 
 # Start with custom config file
 cdk-mintd --config /path/to/config.toml
 
-# Start with specific work directory
+# Start with custom working directory
 cdk-mintd --work-dir /path/to/work/dir
-# Disable logging entirely
+
+# Disable logging
 cdk-mintd --enable-logging false
 
 # Show help
 cdk-mintd --help
 ```
 
-## Environment Variables
+## Key Environment Variables
 
-Key environment variables:
-
-- `CDK_MINTD_DATABASE`: Database engine (sqlite/postgres/redb)
+- `CDK_MINTD_DATABASE`: Database engine (`sqlite`/`postgres`/`redb`)
 - `CDK_MINTD_DATABASE_URL`: PostgreSQL connection string
-- `CDK_MINTD_LN_BACKEND`: Lightning backend type
-- `CDK_MINTD_LISTEN_HOST`: Host to bind to
-- `CDK_MINTD_LISTEN_PORT`: Port to bind to
+- `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](./example.config.toml).
 
 ## Documentation
 
-- [Configuration Examples](./example.config.toml)
-- [PostgreSQL Setup Guide](../../POSTGRES.md)
-- [Development Guide](../../DEVELOPMENT.md)
+- **[Configuration Examples](./example.config.toml)** - Complete configuration reference
+- **[PostgreSQL Setup Guide](../../POSTGRES.md)** - Database setup instructions
+- **[Development Guide](../../DEVELOPMENT.md)** - Contributing and development setup
 
 ## License