cyberkrill

A comprehensive Bitcoin and Lightning Network toolkit written in Rust. cyberkrill provides a unified command-line interface and reusable core library for working with Bitcoin, Lightning, and various hardware signing devices.

Features

🌩️ Lightning Network

• BOLT11 Invoice Decoding: Parse and analyze Lightning invoices

• LNURL Support: Decode and process LNURL strings

• Lightning Address: Generate invoices from Lightning addresses (user@domain.com)

• Fedimint Integration: Encode/decode federation invite codes

💳 Smartcard Support (NFC/USB)

Native support for Coinkite smartcards via NFC readers:

• Tapsigner: BIP-32 HD wallet with secure key generation

  • Initialize new cards with secure entropy

  • Generate addresses with custom derivation paths

  • PIN-protected operations

• Satscard: Bearer instrument with 10 independent slots

  • Generate addresses from active slots

  • Track slot usage and history

🔐 Hardware Wallet Support

Integration with popular Bitcoin hardware wallets:

• Coldcard: Air-gapped signing device (USB/SD card)

  • Address generation and verification

  • PSBT signing and export

• Trezor: Full-featured hardware wallet (USB)

  • Extended public key extraction

  • Address generation with custom paths

• Jade: Blockstream's hardware wallet (USB/Bluetooth)

  • Async communication support

  • Address generation and PSBT signing

₿ Bitcoin Operations

Powered by BDK (Bitcoin Development Kit) with multiple backend support:

Blockchain Backends:

• Bitcoin Core RPC: Direct node integration for maximum privacy

• Electrum: Fast SPV operations without full node

• Esplora: RESTful API for lightweight setups

Transaction Features:

• UTXO Management: List and analyze unspent outputs

• PSBT Creation: Three approaches for different use cases:

  • Manual: Full control over inputs/outputs

  • Funded: Automatic coin selection and change

  • Consolidation: Merge multiple UTXOs efficiently

• Smart Coin Selection: Intelligent UTXO selection with amount limits

• Sub-satoshi Precision: Support for fractional fee rates (0.1 sats/vB)

• Descriptor Support: Full output descriptor compatibility

• frozenkrill Integration: Import wallet export files

Command Structure

Commands are organized with logical prefixes for better clarity:

• ln-* - Lightning Network operations

• fm-* - Fedimint operations

• hw-* - Hardware wallet operations

• onchain-* - Bitcoin onchain operations

Installation

Quick Install (Recommended)

Use the bootstrap script for automatic installation and updates:

# Download and run directly
curl -sSfL https://raw.githubusercontent.com/douglaz/cyberkrill/master/cyberkrill.sh | bash -s -- --help

# Or download the script for repeated use
curl -sSfL https://raw.githubusercontent.com/douglaz/cyberkrill/master/cyberkrill.sh -o cyberkrill
chmod +x cyberkrill
./cyberkrill --help

The bootstrap script will:

• Detect your platform automatically (Linux, macOS, Windows)

• Download the latest release if not installed

• Auto-update when new versions are available

Manual Download

Download pre-built binaries directly from the releases page.

Available Binaries:

PlatformFeaturesNotesLinux x86_64All hardware walletsStatic binary, works on all distrosmacOS x86_64CoreIntel MacsmacOS ARM64CoreApple Silicon (M1/M2/M3)Windows x86_64Core64-bit Windows

Linux Manual Installation

# Download the binary with all hardware wallet support
wget https://github.com/douglaz/cyberkrill/releases/download/latest-master/cyberkrill-linux-x86_64.tar.gz

# Extract and install
tar xzf cyberkrill-linux-x86_64.tar.gz
chmod +x cyberkrill-linux-x86_64/cyberkrill
sudo mv cyberkrill-linux-x86_64/cyberkrill /usr/local/bin/

# Verify installation
cyberkrill --help

macOS Manual Installation

# Intel Mac
curl -L https://github.com/douglaz/cyberkrill/releases/download/latest-master/cyberkrill-macos-x86_64.tar.gz | tar xz

# Apple Silicon (M1/M2/M3)
curl -L https://github.com/douglaz/cyberkrill/releases/download/latest-master/cyberkrill-macos-aarch64.tar.gz | tar xz

# Install
chmod +x cyberkrill-macos-*/cyberkrill
sudo mv cyberkrill-macos-*/cyberkrill /usr/local/bin/

Windows Manual Installation

Download cyberkrill-windows-x86_64.zip from the releases page, extract, and add to your PATH.

Using Nix

# Run directly from GitHub
nix run 'git+https://github.com/douglaz/cyberkrill.git'

# Or clone and run locally
git clone https://github.com/douglaz/cyberkrill.git
cd cyberkrill
nix run .

Build from Source

git clone https://github.com/douglaz/cyberkrill.git
cd cyberkrill

# Build with all features (default)
cargo build --release

# Or build minimal version (core features only)
cargo build --release --no-default-features

# The binary will be at ./target/release/cyberkrill
./target/release/cyberkrill --help

Quick Start

Lightning Operations

# Decode a Lightning invoice
cyberkrill ln-decode-invoice lnbc1000n1pn...

# Decode LNURL
cyberkrill ln-decode-lnurl lnurl1dp68gurn8ghj7mr0v...

# Generate invoice from Lightning address
cyberkrill ln-generate-invoice user@getalby.com 100000 --comment "Payment"

Smartcard Operations (Tapsigner/Satscard)

# Initialize Tapsigner (one-time setup)
export TAPSIGNER_CVC=123456  # Your 6-digit PIN
cyberkrill hw-tapsigner-init

# Generate Bitcoin address from Tapsigner
cyberkrill hw-tapsigner-address --path "m/84'/0'/0'/0/0"

# Generate address from Satscard
cyberkrill hw-satscard-address --slot 1

Hardware Wallet Operations

# Coldcard - Generate address
cyberkrill hw-coldcard-address --path "m/84'/0'/0'/0/0" --network mainnet

# Trezor - Get extended public key
cyberkrill hw-trezor-xpub --path "m/84'/0'/0'" --network mainnet

# Jade - Generate address
cyberkrill hw-jade-address --path "m/84'/0'/0'/0/0" --network mainnet

Bitcoin UTXO Operations

# List UTXOs using different backends
# Bitcoin Core (default)
cyberkrill onchain-list-utxos --descriptor "wpkh([fingerprint/84'/0'/0']xpub...)"

# Electrum backend
cyberkrill onchain-list-utxos --descriptor "wpkh([...]xpub...)" \
  --electrum ssl://electrum.blockstream.info:50002

# Esplora backend
cyberkrill onchain-list-utxos --descriptor "wpkh([...]xpub...)" \
  --esplora https://blockstream.info/api

Bitcoin Transaction Creation

# Manual PSBT - Full control
cyberkrill onchain-create-psbt \
  --inputs "txid:0" --inputs "txid:1" \
  --outputs "bc1qaddr:0.001" \
  --fee-rate 10sats

# Funded PSBT - Automatic coin selection
cyberkrill onchain-create-funded-psbt \
  --outputs "bc1qaddr:0.001" \
  --fee-rate 15.5sats

# UTXO Consolidation
cyberkrill onchain-move-utxos \
  --inputs "txid:0" --inputs "txid:1" \
  --destination "bc1qconsolidated" \
  --fee-rate 5sats

DCA (Dollar Cost Averaging) Report

Generate a comprehensive DCA analysis report for your Bitcoin holdings:

# Using Bitcoin Core RPC (default)
cyberkrill onchain-dca-report \
  --descriptor "wpkh([fingerprint/84'/0'/0']xpub...)" \
  --cache-dir ~/.cyberkrill/cache

# Using Electrum
cyberkrill onchain-dca-report \
  --descriptor "wpkh([...]xpub...)" \
  --electrum ssl://electrum.blockstream.info:50002 \
  --currency usd \
  --cache-dir ~/.cyberkrill/cache

# Using Esplora
cyberkrill onchain-dca-report \
  --descriptor "wpkh([...]xpub...)" \
  --esplora https://blockstream.info/api \
  --currency eur \
  -o dca_report.json

The report includes:

• Historical purchase prices for each UTXO

• Average cost basis calculation

• Current value and unrealized profit/loss

• Purchase date range and statistics

• Support for multiple fiat currencies (USD, EUR, GBP, etc.)

• Price data caching to minimize API calls

Backend Configuration

Bitcoin Core RPC

# Using cookie authentication (recommended)
cyberkrill onchain-list-utxos --bitcoin-dir ~/.bitcoin --descriptor "..."

# Using username/password
cyberkrill onchain-list-utxos --rpc-user myuser --rpc-password mypass --descriptor "..."

Electrum

Popular public servers:

• Mainnet: ssl://electrum.blockstream.info:50002

• Testnet: ssl://electrum.blockstream.info:60002

Esplora

Public instances:

• Mainnet: https://blockstream.info/api

• Testnet: https://blockstream.info/testnet/api

Advanced Features

Amount Formats

cyberkrill supports flexible amount inputs:

# Fee rates (supports fractional satoshis)
--fee-rate 0.1sats     # 0.1 sat/vB
--fee-rate 15.5sats    # 15.5 sat/vB
--fee-rate 0.00000020btc  # In BTC

# Output amounts
--outputs "bc1q...:0.001"      # 0.001 BTC
--outputs "bc1q...:0.001btc"   # Explicit BTC
--outputs "bc1q...:100000sats" # In satoshis

Output Descriptors

Full support for Bitcoin output descriptors:

# Single-sig descriptor
"wpkh([fingerprint/84'/0'/0']xpub...)"

# Multi-sig descriptor with change paths
"wsh(sortedmulti(2,[fp1/48'/0'/0'/2']xpub1/<0;1>/*,[fp2/48'/0'/0'/2']xpub2/<0;1>/*))"

frozenkrill Wallet Files

Import frozenkrill wallet export files instead of raw descriptors:

cyberkrill onchain-list-utxos --wallet-file mywallet_pub.json
cyberkrill onchain-create-funded-psbt --wallet-file mywallet_pub.json --outputs "bc1q...:0.001"

Documentation

Detailed documentation for specific topics:

• Hardware Wallet Setup

  • Coldcard Guide

  • Jade Integration

• Development

  • BDK Implementation

Using as a Library

The cyberkrill-core crate can be used as a dependency:

[dependencies]
# Basic functionality
cyberkrill-core = { git = "https://github.com/douglaz/cyberkrill", default-features = false }

# With smartcard support
cyberkrill-core = { git = "https://github.com/douglaz/cyberkrill", features = ["smartcards"] }

# With hardware wallet support
cyberkrill-core = { git = "https://github.com/douglaz/cyberkrill", features = ["coldcard", "trezor", "jade"] }

use cyberkrill_core::{decode_invoice, decode_lnurl, BitcoinRpcClient};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Decode Lightning invoice
    let invoice = decode_invoice("lnbc...")?;
    println!("Amount: {} msat", invoice.amount_msat);
    
    // Bitcoin operations
    let client = BitcoinRpcClient::new_auto(
        "http://127.0.0.1:8332".to_string(),
        Some(std::path::Path::new("~/.bitcoin")),
        None, None,
    )?;
    
    Ok(())
}

Architecture

cyberkrill is organized as a Rust workspace with three main crates:

• cyberkrill: CLI application providing the command-line interface

• cyberkrill-core: Core library with all business logic

• fedimint-lite: Standalone Fedimint invite code handling

Development

Setup

# Enter development environment
nix develop

# Build
cargo build

# Run tests
cargo test

# Format and lint
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings

Git Hooks

This project includes Git hooks for code quality checks that are automatically configured when you enter the development environment:

# Hooks are set up automatically when you run:
nix develop

The hooks will be configured on first entry to the nix shell. You'll see a message confirming the setup.

Manual Installation (for non-nix users)

If you're not using nix, you can manually install the hooks:

# Configure git to use the project's hooks
git config core.hooksPath .githooks

Available Hooks

• pre-commit: Runs cargo fmt --check to ensure code is formatted

• pre-push: Runs both cargo fmt --check and cargo clippy --all-targets --all-features -- -D warnings to catch issues before CI

Managing Hooks

To bypass hooks temporarily (not recommended):

git commit --no-verify
git push --no-verify

To disable hooks completely:

git config --unset core.hooksPath

Contributing

1. Follow the coding conventions in CONVENTIONS.md

2. Add tests for new functionality

3. Run quality checks before submitting PRs

4. Update documentation for new features

License

This project is open source. See the repository for license details.