Skip to content

README.md

Latest commit

 

History

History
330 lines (234 loc) · 8.93 KB

README.md

File metadata and controls

330 lines (234 loc) · 8.93 KB
Raw

FractionKangaroo - Linux Edition

Advanced Bitcoin Private Key Recovery Tool

A high-performance implementation combining fractional key space division with Pollard's Kangaroo algorithm for efficient ECDLP solving on the secp256k1 curve.

License Platform CUDA

🚀 Features

  • Fractional Key Space Division: Divides large search ranges into manageable fractions
  • GPU Acceleration: Full CUDA support for NVIDIA GPUs (10-100x faster than CPU)
  • Automatic Checkpointing: Resume interrupted searches seamlessly
  • Optimized Algorithm: Fixed all critical bugs from original implementation
  • Flexible Configuration: Customizable parameters for different range sizes
  • Production Ready: Thoroughly tested with known test vectors

📋 Quick Start

Prerequisites

  • Linux OS (Ubuntu/Debian/WSL2)
  • NVIDIA GPU with CUDA support
  • CMake 3.10+, GCC/G++ with C++17
  • Kangaroo-256 binary

Installation

# 1. Clone repository
git clone <your-repo-url>
cd fraction-kangaroo-linux

# 2. Build
mkdir build && cd build
cmake ..
make -j$(nproc)

# 3. Configure Kangaroo-256 path (if needed)
# Edit src/Config.h or create symlink to your kangaroo-256 binary

Basic Usage

./FractionKangaroo \
  -pk 800000000000000 \
  -pke fffffffffffffff \
  -pb 0348e843dc5b1bd246e6309b4924b81543d02b16c8083df973a89ce2c7eb89a10d \
  -dbit 6 \
  -t 0 -gpu -dp 10

📖 Full Documentation

🎯 How It Works

FractionKangaroo employs a sophisticated divide-and-conquer strategy:

  1. Division: Splits the target range by 2^dbit (e.g., dbit=6 creates 64 positions)
  2. Transformation: For each position, computes a transformed public key
  3. Search: Uses Kangaroo-256 to search the divided range
  4. Reconstruction: Recovers the full private key when found
Original Range: [0x800000000000000, 0xfffffffffffffff]
                          ↓ (divide by 2^6 = 64)
Divided Range:  [0x20000000000000, 0x3ffffffffffff]
                          ↓ (64 positions)
Position 0x00: Search for transformed_pubkey_0
Position 0x01: Search for transformed_pubkey_1
    ...
Position 0x3E: ✓ FOUND! → Reconstruct full key

Algorithm Advantages

  • Parallelizable: Different positions can run on different machines
  • Efficient: Reduces effective search space complexity
  • Resumable: Checkpoints allow graceful interruption
  • Proven: Based on established Pollard's Kangaroo method

📊 Performance

Benchmark: RTX 4060 Laptop GPU

Range Size dbit Positions Time per Position Total Time (worst case)
2^53 (60-bit) 6 64 ~15 sec ~15 min
2^56 (63-bit) 7 128 ~30 sec ~60 min
2^59 (66-bit) 8 256 ~60 sec ~4 hours

Actual time depends on key position (may be found early)

🔧 Configuration

Choosing the Right Parameters

dbit Selection Guide:

Range Size (bits) Recommended dbit Number of Positions
40-50 5-6 32-64
51-60 6-7 64-128
61-70 7-9 128-512

Rule of Thumb:

divided_range_width = original_range_width / 2^dbit
Should be between 2^45 and 2^55 for optimal performance

Changing Kangaroo-256 Path

Edit src/Config.h:

// Line ~30
std::string kangaroo_path = "/path/to/your/kangaroo-256";

Then rebuild:

cd build && make

📝 Command Reference

Required Parameters

Parameter Description Example
-pk Range start (hex) 800000000000000
-pke Range end (hex) fffffffffffffff
-pb Target public key 0348e843dc5b1bd...

Optional Parameters

Parameter Description Default
-dbit Divisor bits (2^n positions) 6
-pos Starting position 0
-dp Distinguished point bits auto
-t CPU threads 0
-gpu Enable GPU off
-wl Load checkpoint file -
-wt Checkpoint interval (sec) 180

See full parameter guide →

🐛 Bug Fixes

This implementation includes critical fixes from the original:

Fixed Issues

  1. ✅ Position 0 Initialization: Properly handles infinity point
  2. ✅ Incremental State Updates: Per-position recomputation eliminates bugs
  3. ✅ Immutable Base State: Prevents divided_pubkey corruption
  4. ✅ Simplified Checkpoints: Only saves position, recomputes state
  5. ✅ Mathematical Formulas: Correct use of divided range in transformations
  6. ✅ Reconstruction Formula: Proper key recovery from Kangaroo solution
  7. ✅ Collision Detection: Removed erroneous error on valid Kangaroo output

See detailed bug fix documentation →

📂 Project Structure

fraction-kangaroo-linux/
├── src/
│   ├── main.cpp              # Entry point
│   ├── FractionKangaroo.cpp  # Core algorithm
│   ├── FractionKangaroo.h    # Class definition
│   ├── Config.h              # Configuration
│   ├── Checkpoint.cpp        # Save/load functionality
│   ├── Secp256k1.cpp         # Elliptic curve operations
│   ├── BigInt256.cpp         # 256-bit integer arithmetic
│   └── Utils.cpp             # Utility functions
├── build/                    # Build directory (created by cmake)
├── CMakeLists.txt            # Build configuration
├── README.md                 # This file
├── HOW_TO_USE.md            # Comprehensive usage guide
├── BUGFIX_SUMMARY.md        # Algorithm fix details
└── COLLISION_BUG_FIX.md     # Collision detection fix

🧪 Testing

Test with Known Key

# Private key: 0xfc07a1825367bbe
./FractionKangaroo \
  -pk 800000000000000 \
  -pke fffffffffffffff \
  -pb 0348e843dc5b1bd246e6309b4924b81543d02b16c8083df973a89ce2c7eb89a10d \
  -dbit 6 -pos 3e \
  -t 0 -gpu -dp 10

Expected output:

****************************
*** SOLUTION FOUND ***
KEY: 0x0000000000000000000000000000000000000000000000000fc07a1825367bbe
PUB: 0348e843dc5b1bd246e6309b4924b81543d02b16c8083df973a89ce2c7eb89a10d
****************************

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Submit a pull request

Areas for Improvement

  • Multi-GPU support
  • Network distributed search
  • Web dashboard for monitoring
  • Additional curve support (P-256, etc.)
  • Performance profiling and optimization

⚠️ Disclaimer

This tool is for educational and authorized security research only.

  • Only use on Bitcoin addresses you own or have explicit permission to test
  • Unauthorized access to others' private keys is illegal
  • The authors are not responsible for misuse of this software

Ethical Use Guidelines:

  • ✅ Recovering your own lost keys
  • ✅ Security research with permission
  • ✅ Academic study and learning
  • ❌ Unauthorized access attempts
  • ❌ Theft or fraud

📜 License

[Specify your license - MIT, GPL, etc.]

🙏 Credits

  • Original Algorithm: John Pollard (Pollard's Kangaroo)
  • Kangaroo-256: NotATether
  • FractionKangaroo Concept: JeanLuc (Windows PureBasic version)
  • Linux Port & Fixes: Community contributors

📞 Support

🔗 Related Projects

📈 Changelog

Version 1.1 (December 2025)

  • ✅ Fixed all 7 critical bugs from original implementation
  • ✅ Removed erroneous collision detection
  • ✅ Added comprehensive documentation
  • ✅ Verified with test vectors
  • ✅ Production ready

Version 1.0 (Initial Port)

  • Initial Linux port from Windows PureBasic version
  • Basic functionality

Made with ❤️ for the Bitcoin security research community

Last updated: December 2025

Support

If this work helped you, you can support me:

  • USDT (ERC-20): 0xfba2de3360ae0d98ec44216191d143bc28676af5
  • USDC (ERC-20): 0xfba2de3360ae0d98ec44216191d143bc28676af5
  • BTC: 14EVe4ejvXrSS6s34AUBP9TMoSsuzShJ8o

Have a vibe-coding project you'd like to collaborate on? Get in touch: rawanaholdingslk@gmail.com