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
BOLT11 Invoice Encoding: Reconstruct Lightning invoices from JSON data
LNURL Support: Decode and process LNURL strings
Lightning Address: Generate invoices from Lightning addresses ([email protected])
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:

Platform	Features	Notes
Linux x86_64	All hardware wallets	Static binary, works on all distros
macOS x86_64	Core	Intel Macs
macOS ARM64	Core	Apple Silicon (M1/M2/M3)
Windows x86_64	Core	64-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...

# Encode a Lightning invoice from JSON data
cyberkrill ln-encode-invoice invoice.json --private-key <hex_private_key>
# Or from stdin
echo '{"network":"bitcoin","amount_msats":1000000,...}' | cyberkrill ln-encode-invoice --private-key <hex_private_key>

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

# Generate invoice from Lightning address
cyberkrill ln-generate-invoice [email protected] 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:

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

Follow the coding conventions in CONVENTIONS.md
Add tests for new functionality
Run quality checks before submitting PRs
Update documentation for new features

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 110 Commits
.cargo		.cargo
.githooks		.githooks
.github		.github
cyberkrill-core		cyberkrill-core
cyberkrill		cyberkrill
docs		docs
fedimint-lite		fedimint-lite
jade-bitcoin		jade-bitcoin
static		static
.gitignore		.gitignore
.mcp.production.json		.mcp.production.json
CONVENTIONS.md		CONVENTIONS.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
MCP_SETUP.md		MCP_SETUP.md
NIXOS_COLDCARD_SETUP.md		NIXOS_COLDCARD_SETUP.md
README.md		README.md
TREZOR_SUPPORT.md		TREZOR_SUPPORT.md
build.log		build.log
coldcard-nixos-config.nix		coldcard-nixos-config.nix
cyberkrill.sh		cyberkrill.sh
deny.toml		deny.toml
flake.lock		flake.lock
flake.nix		flake.nix
test-bdk-complete.sh		test-bdk-complete.sh
test-hidapi.rs		test-hidapi.rs
test-multipath.sh		test-multipath.sh
test-simple.sh		test-simple.sh
test.psbt		test.psbt
test.sh		test.sh
trezor_address.json		trezor_address.json

License

Licenses found

douglaz/cyberkrill

Folders and files

Latest commit

History

Repository files navigation

cyberkrill

Features

🌩️ Lightning Network

💳 Smartcard Support (NFC/USB)

🔐 Hardware Wallet Support

₿ Bitcoin Operations

Command Structure

Installation

Quick Install (Recommended)

Manual Download

Linux Manual Installation

macOS Manual Installation

Windows Manual Installation

Using Nix

Build from Source

Quick Start

Lightning Operations

Smartcard Operations (Tapsigner/Satscard)

Hardware Wallet Operations

Bitcoin UTXO Operations

Bitcoin Transaction Creation

DCA (Dollar Cost Averaging) Report

Backend Configuration

Bitcoin Core RPC

Electrum

Esplora

Advanced Features

Amount Formats

Output Descriptors

frozenkrill Wallet Files

Documentation

Using as a Library

Architecture

Development

Setup

Git Hooks

Manual Installation (for non-nix users)

Available Hooks

Managing Hooks

Contributing

License

About

Resources

License

Licenses found

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages