{"id":35122071,"url":"https://github.com/oritwoen/kangaroo","last_synced_at":"2026-02-15T17:18:09.367Z","repository":{"id":328366419,"uuid":"1115300829","full_name":"oritwoen/kangaroo","owner":"oritwoen","description":"GPU-accelerated Pollard's Kangaroo ECDLP solver for secp256k1 (Vulkan/Metal/DX12)","archived":false,"fork":false,"pushed_at":"2026-01-10T21:37:34.000Z","size":103,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T04:58:42.507Z","etag":null,"topics":["bitcoin","cryptography","ecdlp","elliptic-curves","gpu","pollard-kangaroo","rust","secp256k1","vulkan","wgpu"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oritwoen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-12T16:35:16.000Z","updated_at":"2026-01-10T21:37:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oritwoen/kangaroo","commit_stats":null,"previous_names":["oritwoen/kangaroo"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/oritwoen/kangaroo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oritwoen%2Fkangaroo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oritwoen%2Fkangaroo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oritwoen%2Fkangaroo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oritwoen%2Fkangaroo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oritwoen","download_url":"https://codeload.github.com/oritwoen/kangaroo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oritwoen%2Fkangaroo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","cryptography","ecdlp","elliptic-curves","gpu","pollard-kangaroo","rust","secp256k1","vulkan","wgpu"],"created_at":"2025-12-28T00:36:58.288Z","updated_at":"2026-01-17T17:44:57.893Z","avatar_url":"https://github.com/oritwoen.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kangaroo\n\n[![Crates.io](https://img.shields.io/crates/v/kangaroo?style=flat\u0026colorA=130f40\u0026colorB=474787)](https://crates.io/crates/kangaroo)\n[![Downloads](https://img.shields.io/crates/d/kangaroo?style=flat\u0026colorA=130f40\u0026colorB=474787)](https://crates.io/crates/kangaroo)\n[![License](https://img.shields.io/crates/l/kangaroo?style=flat\u0026colorA=130f40\u0026colorB=474787)](LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/oritwoen/kangaroo)\n\nGPU-accelerated Pollard's Kangaroo algorithm for solving the Elliptic Curve Discrete Logarithm Problem (ECDLP) on secp256k1.\n\n## Community\n\n- [Bitcointalk](https://bitcointalk.org/index.php?topic=5571086) - Discussion thread\n\n## Features\n\n- **Cross-platform GPU support** via wgpu (Vulkan/Metal/DX12)\n  - AMD GPUs (via Vulkan/RADV)\n  - NVIDIA GPUs (via Vulkan)\n  - Intel GPUs (via Vulkan)\n  - Apple Silicon (via Metal)\n- **Pure Rust** implementation with WGSL compute shaders\n- **Distinguished Points** optimization for efficient collision detection\n- **CPU fallback** for testing and comparison\n- **Data providers** for puzzle sources (boha integration)\n\n## Why This Project?\n\nMost existing Kangaroo implementations (JeanLucPons/Kangaroo, RCKangaroo, etc.) only support NVIDIA GPUs via CUDA. This implementation uses WebGPU/wgpu which provides cross-platform GPU compute through Vulkan, Metal, and DX12.\n\n## Installation\n\n### Arch Linux (AUR)\n\n```bash\nparu -S kangaroo\n```\n\n### Cargo\n\n```bash\ncargo install kangaroo\n```\n\n### From source\n\n```bash\ngit clone https://github.com/oritwoen/kangaroo\ncd kangaroo\ncargo build --release\n```\n\n### With boha provider\n\n```bash\ncargo build --release --features boha\n```\n\n## Usage\n\n```bash\nkangaroo --pubkey \u003cPUBKEY\u003e --start \u003cSTART\u003e --range \u003cBITS\u003e\n```\n\n### Arguments\n\n| Argument | Default | Description |\n|----------|---------|-------------|\n| `-t, --target` | - | Data provider target (e.g., `boha:b1000/135`) |\n| `-p, --pubkey` | - | Target public key (compressed hex, 33 bytes) |\n| `-s, --start` | 0 | Start of search range (hex, without 0x prefix) |\n| `-r, --range` | 32 | Search range in bits (key is in [start, start + 2^range]) |\n| `-d, --dp-bits` | auto | Distinguished point bits |\n| `-k, --kangaroos` | auto | Number of parallel kangaroos |\n| `--gpu` | 0 | GPU device index |\n| `-o, --output` | - | Output file for result |\n| `-q, --quiet` | false | Minimal output, just print found key |\n| `--max-ops` | 0 | Max operations (0 = unlimited) |\n| `--cpu` | false | Use CPU solver instead of GPU |\n| `--json` | false | Output benchmark results in JSON format |\n| `--list-providers` | false | List available puzzles from providers |\n\nEither `--target` or `--pubkey` is required.\n\n### Examples\n\n**Using data provider (boha):**\n\n```bash\n# Solve puzzle using boha data (auto: pubkey, start, range)\nkangaroo --target boha:b1000/66\n\n# Override range (search smaller subset)\nkangaroo --target boha:b1000/66 --range 60\n\n# List available puzzles\nkangaroo --list-providers\n```\n\n**Manual parameters:**\n\n```bash\nkangaroo \\\n    --pubkey 03a2efa402fd5268400c77c20e574ba86409ededee7c4020e4b9f0edbee53de0d4 \\\n    --start 8000000000 \\\n    --range 40\n```\n\n## How It Works\n\nThe Pollard's Kangaroo algorithm solves the discrete logarithm problem in O(√n) time where n is the search range. It works by:\n\n1. **Tame kangaroos** start from a known point and make random jumps\n2. **Wild kangaroos** start from the target public key and make the same type of jumps\n3. When a wild and tame kangaroo land on the same point (collision), we can compute the private key\n\n**Distinguished Points (DP)** optimization: Instead of storing all visited points, we only store points whose x-coordinate has a specific number of leading zero bits. This dramatically reduces memory usage while still allowing collision detection.\n\n## Performance\n\nExpected operations: ~2^(range_bits/2)\n\nRun `kangaroo --benchmark` to test your hardware. See [BENCHMARKS.md](BENCHMARKS.md) for results on various GPUs.\n\n## Use Cases\n\n| Use Case | Example |\n|----------|---------|\n| Partial key decoded | Puzzle gives ~240 bits, need to find remaining ~16 |\n| Key in known range | Know key is between X and Y |\n| Verify near-solution | Have candidate, search ±N bits around it |\n\n**NOT useful for:**\n- Full 256-bit key search (mathematically impossible)\n- BIP39 passphrase brute-force (use dictionary attack instead)\n- Puzzles without partial key information\n\n## Library Usage\n\n```rust\nuse kangaroo::{KangarooSolver, GpuContext, parse_pubkey, parse_hex_u256, verify_key};\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    let pubkey = parse_pubkey(\"03...\")?;\n    let start = parse_hex_u256(\"8000000000\")?;\n\n    let ctx = pollster::block_on(GpuContext::new(0))?;\n    let mut solver = KangarooSolver::new(\n        ctx,\n        pubkey.clone(),\n        start,\n        40,  // range_bits\n        12,  // dp_bits\n        1024, // num_kangaroos\n    )?;\n\n    loop {\n        if let Some(key) = solver.step()? {\n            if verify_key(\u0026key, \u0026pubkey) {\n                println!(\"Found: {}\", hex::encode(\u0026key));\n                break;\n            }\n        }\n    }\n\n    Ok(())\n}\n```\n\n## Data Providers\n\nKangaroo supports external data providers for puzzle sources. Providers supply pubkey, key range, and other puzzle metadata.\n\n### boha (optional feature)\n\n[boha](https://github.com/oritwoen/boha) provides crypto puzzle data including Bitcoin Puzzle Transaction (b1000).\n\nBuild with boha support:\n```bash\ncargo build --release --features boha\n```\n\nUsage:\n```bash\n# Solve specific puzzle\nkangaroo --target boha:b1000/66\n\n# List solvable puzzles (unsolved with known pubkey)\nkangaroo --list-providers\n```\n\nProvider validates range overrides - you cannot search outside the puzzle's key range.\n\n## Architecture\n\n```\nsrc/\n├── main.rs              # CLI entry point\n├── lib.rs               # Library entry + Args + run()\n├── solver.rs            # GPU solver coordination\n├── cli.rs               # CLI utilities (tracing, progress bar)\n├── provider/\n│   ├── mod.rs           # Provider system interface\n│   └── boha.rs          # boha provider (feature-gated)\n├── cpu/\n│   ├── cpu_solver.rs    # Pure CPU solver (testing/comparison)\n│   ├── dp_table.rs      # Distinguished Points collision detection\n│   └── init.rs          # Kangaroo initialization + jump tables\n├── crypto/\n│   └── mod.rs           # k256/secp256k1 wrappers\n├── gpu/\n│   ├── pipeline.rs      # Compute pipeline setup\n│   └── buffers.rs       # GPU buffer management\n├── gpu_crypto/\n│   ├── context.rs       # GPU context abstraction\n│   └── shaders/         # WGSL shader library\n│       ├── field.wgsl   # secp256k1 field arithmetic\n│       └── curve.wgsl   # Jacobian point operations\n└── shaders/\n    └── kangaroo_affine.wgsl  # Main Kangaroo compute shader\n```\n\n## Requirements\n\n- Rust 1.70+\n- Vulkan-capable GPU (AMD, NVIDIA, Intel) or Metal (macOS)\n- GPU drivers installed\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Related Projects\n\n- [JeanLucPons/Kangaroo](https://github.com/JeanLucPons/Kangaroo) - CUDA implementation (NVIDIA only)\n- [RCKangaroo](https://github.com/RetiredC/RCKangaroo) - CUDA implementation (NVIDIA only)\n- [boha](https://github.com/oritwoen/boha) - Crypto puzzles and bounties data library\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foritwoen%2Fkangaroo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foritwoen%2Fkangaroo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foritwoen%2Fkangaroo/lists"}