Bitcoin CLI Wallet in Rust

A secure, feature-rich Bitcoin wallet implementation in Rust with support for wallet creation, address generation, transaction signing, and UTXO management.

🚀 Features

BIP39 Mnemonic Support: Create and recover wallets using standard mnemonic phrases
BIP44 HD Wallet: Hierarchical deterministic address generation
Gap Limit Implementation: Efficient address scanning with configurable gap limits
P2PKH Transaction Signing: Secure ECDSA signing for legacy Bitcoin addresses
SegWit Support: Native P2WPKH (bech32) addresses with witness transaction signing
Multi-signature Wallets: Create and manage 2-of-3, 3-of-5, etc. multi-signature wallets with native SegWit P2WSH
Multi-signature Transaction Signing: Sign transactions with multiple cosigners and duplicate detection
Transaction Broadcasting: Finalize and broadcast multi-signature transactions to the network
UTXO Management: Real-time balance tracking and UTXO validation
Blockchain Integration: Direct integration with Bitcoin testnet via Blockstream API
Secure Key Management: Private keys stored in WIF format with proper cryptographic handling
Lightning Node (Testnet): Start a Lightning node via LDK Node and print your Node ID

SegWit variants supported

Native SegWit (P2WPKH/P2WSH): Bech32 addresses (testnet: tb1q... / tb1p...). Witness data goes in the witness; empty scriptSig.
Wrapped SegWit (P2SH-P2WPKH): Base58 P2SH addresses (testnet: 2...). The segwit witness program (redeemScript) is placed in scriptSig; signatures are still carried in the witness. Useful for legacy compatibility.

🛠️ Technical Highlights

Cryptographic Security: Uses bitcoin-rs library for all cryptographic operations
Memory Safety: Leverages Rust's ownership system for secure memory management
Async/Await: Non-blocking blockchain API calls for better performance
Error Handling: Comprehensive error handling with custom error types
Serialization: JSON-based wallet persistence with serde

📋 Prerequisites

Rust 1.70+ (install via rustup)
Internet connection for blockchain API access
Bitcoin testnet for safe testing

🔧 Installation

Clone the repository:

git clone https://github.com/leepl37/rust_cli_wallet.git
cd rust_cli_wallet

Build the project:
```
cargo build --release
```
Run the wallet:
```
cargo run
```

⚡ Quickstart: Lightning Node (Testnet)

Start a Lightning node using LDK Node and print your Node ID:

cargo run
# In the menu, choose:
# 7) LDK Node Quickstart (Testnet)

What happens:

A testnet Lightning node starts using Esplora as the chain source (mempool.space testnet API)
The node listens on port 9735 (local by default)
Your Node ID (public key) is printed, e.g. Node ID: 02abcd...
State is stored under ./ldk_data/ so the node survives restarts

Tip: Keep the menu running to keep the node online. Share node_id@host:9735 with peers to connect or open channels (testnet).

🏗️ Architecture

Core Components

Wallet: Main wallet structure managing addresses and state
WalletAddress: Individual address with private key and UTXOs
UTXO: Unspent transaction output representation
Transaction Signing: ECDSA signing with secp256k1 curve

Key Algorithms

Gap Limit Scanning

The wallet implements BIP44 gap limit scanning to efficiently discover used addresses:

1. Scan addresses sequentially (index 0, 1, 2...)
2. Count consecutive unused addresses
3. Stop when gap limit (20) is reached
4. This prevents infinite scanning while finding all used addresses

Address Derivation

Addresses are derived using BIP44 path: m/44'/1'/0'/0/{index}

44' - BIP44 standard
1' - Bitcoin testnet coin type
0' - Account number
0 - Change address type (receiving)
{index} - Sequential address index

Transaction Creation

UTXO Selection: Smart coin selection algorithm
Fee Calculation: Based on transaction size and fee rate (optimized for SegWit)
Input Creation: References to spent UTXOs
Output Creation: Destination + change addresses
Signing: ECDSA signatures for each input (P2PKH) or witness data (P2WPKH)

SegWit Implementation

The wallet supports native SegWit (P2WPKH) addresses with the following features:

Address Format: Bech32 encoded addresses (tb1q... for testnet)
Witness Data: Proper witness structure with signatures and public keys
Fee Optimization: SegWit inputs use ~68 vbytes vs ~148 vbytes for legacy
Mixed Transactions: Support for combining P2PKH and P2WPKH inputs
Multi-signature: Native P2WSH multi-signature wallets

🔒 Security Considerations

Private Key Management

Private keys stored in WIF (Wallet Import Format)
Mnemonic phrases enable deterministic key generation
All cryptographic operations use bitcoin-rs library

Network Security

Uses Bitcoin testnet for safe testing
Validates all blockchain data before use
Implements proper error handling for network failures

Memory Safety

Leverages Rust's ownership system
No unsafe code blocks
Automatic memory management prevents common vulnerabilities

🧪 Testing

Run the test suite:

cargo test

Run with verbose output:

cargo test -- --nocapture

🔧 Configuration

Network Selection

Currently supports Bitcoin testnet. To switch to mainnet:

Change Network::Testnet to Network::Bitcoin
Update BIP44 coin type from 1' to 0'
Use mainnet blockchain APIs

Gap Limit Configuration

The gap limit is set to 20 by default. To modify:

const GAP_LIMIT: u32 = 20; // Change this value

🚀 Future Enhancements

SegWit support (P2WPKH) - ✅ COMPLETED
P2SH-P2WPKH support
Lightning Node (Testnet) via LDK Node
Advanced multi-signature features (time-locks, threshold signatures)

📝 Recent Updates

v1.3.1 - Enhanced Multi-signature Security (Latest)

✅ Duplicate Private Key Validation: Prevents accidental overwriting of existing private keys
✅ Smart Key Management: Warns users when different private keys exist for the same public key
✅ User Confirmation Prompts: Asks for explicit confirmation before overwriting existing keys
✅ Data Integrity Protection: Maintains wallet consistency and prevents data loss
✅ Enhanced User Feedback: Clear messaging for duplicate detection and key validation

v1.3.0 - SegWit Support

✅ Native SegWit P2WPKH: Full support for bech32 addresses (tb1q...)
✅ Witness Transaction Signing: Proper SegWit transaction creation and signing
✅ Mixed Input Support: Handle both P2PKH and P2WPKH inputs in same transaction
✅ SegWit Fee Optimization: Accurate fee calculation for SegWit transactions
✅ Multi-signature SegWit: Native P2WSH multi-signature wallets
✅ Enhanced Address Generation: Automatic SegWit address creation

v1.2.0 - Multi-signature Feature

✅ Multi-signature Wallet Creation: Create 2-of-3, 3-of-5, etc. multi-signature wallets
✅ Transaction Signing: Sign transactions with multiple cosigners and duplicate detection
✅ CLI Interface: Complete menu system for multi-signature operations
✅ Transaction Broadcasting: Finalize and broadcast multi-signature transactions
✅ File Management: Save/load transaction files for sharing between cosigners
✅ Enhanced Error Handling: Clear user feedback and validation

v1.1.0 - Basic Wallet Features

✅ Basic wallet creation and address generation
✅ Transaction sending and receiving
✅ UTXO management and balance tracking
✅ BIP39 mnemonic support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This is educational software. Use at your own risk. Never use this wallet for storing significant amounts of Bitcoin without thorough testing and security review.

🙏 Acknowledgments

bitcoin-rs for the Bitcoin library
BIP39 for mnemonic phrase support
Blockstream for the blockchain API

📞 Support

For questions or issues:

Open an issue on GitHub
Check the documentation
Review the test cases for usage examples

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
ldk_data		ldk_data
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md

leepl37/rust_cli_wallet

Folders and files

Latest commit

History

Repository files navigation