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.

---

🚀 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

• Documentation: HOW_TO_USE.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

🔗 Related Projects

• Kangaroo-256 - The underlying ECDLP solver
• BitCrack - Alternative GPU-based key finder
• KeyHunt - Multi-method key search tool

---

📈 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