### Run Documentation Examples

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/INDEX.md

Execute code examples embedded within the project's documentation. This ensures that the documentation examples are functional and up-to-date.

```bash
cargo test --doc
```

--------------------------------

### Basic Solver Usage in Rust

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/INDEX.md

Demonstrates how to initialize and use the KangarooSolver in Rust to find a key. Requires GPU context setup and parsing of public key and start values.

```rust
use kangaroo::{KangarooSolver, GpuContext, GpuBackend, parse_pubkey, parse_hex_u256};

let pubkey = parse_pubkey("03a2efa...")?;
let start = parse_hex_u256("8000000000")?;
let ctx = GpuContext::new(0, GpuBackend::Auto).await?;

let mut solver = KangarooSolver::new(ctx, pubkey, start, 40, 12, 1024)?;
loop {
    if let Some(key) = solver.step()? {
        println!("Found: {}", hex::encode(&key));
        break;
    }
}
```

--------------------------------

### Full Verification Usage Example

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/types.md

Demonstrates how to use the `full_verify` function and check the match results for a Bitcoin key.

```rust
let result = full_verify(&key, &exp_pubkey, &exp_hash160, &exp_address)?;
if result.pubkey_match && result.hash160_match && result.address_match {
    println!("Full verification passed!");
}
```

--------------------------------

### Modular Constraints Example

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Apply modular constraints to the search space for private keys. This example searches for keys k such that k is congruent to 37 modulo 60.

```bash
# Constraint: k ≡ 37 (mod 60)
kangaroo --pubkey 03... --range 40 --mod-step 3c --mod-start 25
# 3c in hex = 60 in decimal
# 25 in hex = 37 in decimal
```

--------------------------------

### Bash: CLI Usage for Modular Constraints

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/modular-constraints.md

Command-line interface example for setting up a modular constraint (k ≡ 37 mod 60) with the Kangaroo tool. Specifies public key, start value, range, and modular parameters.

```bash
# Constraint: k ≡ 37 (mod 60)
kangaroo \
  --pubkey 03a2efa402fd5268400c77c20e574ba86409ededee7c4020e4b9f0edbee53de0d4 \
  --start 8000000000 \
  --range 40 \
  --mod-step 3c \
  --mod-start 25

# Key recovery in lib.rs handles j → k conversion

```

--------------------------------

### Run Kangaroo with Public Key

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

Example of running the Kangaroo tool with a specified public key and default parameters.

```bash
kangaroo --pubkey 03...
```

--------------------------------

### Bitcoin Puzzle Example with ModConstraint

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

Example demonstrating how to set mod_step and mod_start for a Bitcoin puzzle where the private key is known to be congruent to 37 modulo 60.

```text
mod_step = 60 = 0x3c
mod_start = 37 = 0x25
effective_range = 40 - 6 = 34 bits (60× reduction)
```

--------------------------------

### Example Usage of CpuKangarooSolver

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Demonstrates how to create and use the CpuKangarooSolver. It shows initializing the solver, running the solve method with a timeout, and printing the found key and operation count.

```rust
let mut solver = CpuKangarooSolver::new(pubkey, start, 30, 12, ProjectivePoint::GENERATOR);
if let Some(key) = solver.solve(Duration::from_secs(60)) {
    println!("Found: {}", hex::encode(&key));
    println!("Ops: {}, K-factor: {:.3}", solver.total_ops(), solver.total_ops() as f64 / (2.0_f64).powf(15.0));
}
```

--------------------------------

### GPU Selection Examples

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Select specific GPUs or all available discrete GPUs for computation. Use comma-separated indices for multiple GPUs.

```bash
kangaroo --pubkey 03... --range 40 --gpu 0       # GPU 0 only
```

```bash
kangaroo --pubkey 03... --range 40 --gpu all     # All discrete GPUs
```

```bash
kangaroo --pubkey 03... --range 40 --gpu 0,2     # GPU 0 and 2
```

--------------------------------

### Initialize GPU Context and Solver

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/README.md

Demonstrates how to initialize a GPU context and a Kangaroo solver. This is a complete, runnable example requiring specific imports.

```rust
use kangaroo::{KangarooSolver, GpuContext, GpuBackend};

let ctx = GpuContext::new(0, GpuBackend::Auto).await?;
let solver = KangarooSolver::new(...)?;
```

--------------------------------

### Kangaroo CLI Debug Logging Example

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

This example demonstrates how to enable debug-level tracing output for the Kangaroo CLI by setting the RUST_LOG environment variable.

```bash
RUST_LOG=debug kangaroo --pubkey 03... --range 40
```

--------------------------------

### Kangaroo CLI Usage Examples

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/overview.md

Illustrates various command-line options for the Kangaroo solver, including GPU auto-detection, listing GPUs, benchmarking, modular constraints, multi-GPU usage, and CPU solving.

```bash
# Auto-detect GPU, solve puzzle
kangaroo --pubkey 03a2efa... --start 8000000000 --range 40

# List available GPUs
kangaroo --list-gpus

# Benchmark hardware
kangaroo --benchmark --save-benchmarks

# Modular constraint
kangaroo --pubkey 03a2efa... --range 40 --mod-step 3c --mod-start 25

# Multi-GPU
kangaroo --pubkey 03a2efa... --range 40 --gpu all

# CPU solver
kangaroo --pubkey 03a2efa... --range 40 --cpu

```

--------------------------------

### Install Kangaroo via Cargo

Source: https://github.com/oritwoen/kangaroo/blob/main/README.md

Install Kangaroo using Cargo, the Rust package manager.

```bash
cargo install kangaroo
```

--------------------------------

### Install Kangaroo via AUR

Source: https://github.com/oritwoen/kangaroo/blob/main/README.md

Use paru to install Kangaroo on Arch Linux from the AUR.

```bash
paru -S kangaroo
```

--------------------------------

### Rust Library Usage for Pollard's Kangaroo

Source: https://github.com/oritwoen/kangaroo/blob/main/README.md

Demonstrates how to use the KangarooSolver from the kangaroo library in Rust to find a private key. It includes setup for GPU context, parsing public keys and start points, and the main solving loop.

```rust
use kangaroo::{KangarooSolver, GpuContext, GpuBackend, parse_pubkey, parse_hex_u256, verify_key};

fn main() -> anyhow::Result<()> {
    let pubkey = parse_pubkey("03...")?;
    let start = parse_hex_u256("8000000000")?;

    let ctx = pollster::block_on(GpuContext::new(0, GpuBackend::Auto))?;
    let mut solver = KangarooSolver::new(
        ctx,
        pubkey.clone(),
        start,
        40,  // range_bits
        12,  // dp_bits
        1024, // num_kangaroos
    )?;

    loop {
        if let Some(key) = solver.step()? {
            if verify_key(&key, &pubkey) {
                println!("Found: {}", hex::encode(&key));
                break;
            }
        }
    }

    Ok(())
}
```

--------------------------------

### Key Verification in Rust

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/INDEX.md

Provides Rust code examples for verifying a key using `verify_key` and performing a full verification with `full_verify`.

```rust
use kangaroo::{verify_key, full_verify};

let key = hex::decode("c28fca...")?;
assert!(verify_key(&key, &pubkey));

let result = full_verify(&key, "03...", "a2a7...", "1FWQ...")?;
assert!(result.pubkey_match && result.address_match);
```

--------------------------------

### Command-Line Interface Reference

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/MANIFEST.txt

Documents the complete command-line interface, including all arguments, options, examples, and scripting patterns.

```APIDOC
## Command-Line Interface Reference

### Description
This document provides a complete reference for the command-line interface (CLI). It details all available arguments with their descriptions and default values, organizes options by category, and includes over 15 real-world examples. It also covers scripting patterns, exit codes, and environment variables.

### Features
- All arguments with descriptions and defaults
- Options organized by category
- 15+ real-world examples
- Scripting patterns
- Exit codes and environment variables

### Further Information
Refer to the `cli-reference.md` document for comprehensive CLI usage details.
```

--------------------------------

### GPU to CPU Solver Fallback

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

Example of attempting to initialize a GPU solver and falling back to a CPU solver if initialization fails.

```rust
// Try GPU, fallback to CPU
let solver = match KangarooSolver::new(&ctx, ...) {
    Ok(s) => s,
    Err(_) => {
        eprintln!("GPU failed, using CPU");
        return cpu_solve(...);
    }
};

// Retry with different DP bits if memory error
match solver.step() {
    Err(e) if e.to_string().contains("OOM") => {
        // Recreate with higher DP bits (fewer DPs)
    }
    other => other,
}
```

--------------------------------

### Args Parsing from Command Line

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/types.md

Shows how to parse command-line arguments into the Args struct using the clap crate. Includes examples for parsing from standard arguments and a specific argument list.

```rust
use clap::Parser;

let args = Args::parse();  // From std::env::args()
let args = Args::parse_from(&["kangaroo", "--pubkey", "03...", "--range", "40"]);
```

--------------------------------

### Set Search Start and Range

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Define the beginning of the search range using a hex string and specify the bit width of the search range. The '0x' prefix is optional for the start value.

```bash
kangaroo --pubkey 03... --start 8000000000 --range 40
```

```bash
kangaroo --start 0x1000
```

--------------------------------

### Rust Library Example: GPU Solver

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/overview.md

Demonstrates how to use the KangarooSolver library in Rust to solve a puzzle using a GPU. Ensure you have the necessary dependencies and a compatible GPU.

```rust
use kangaroo::{KangarooSolver, GpuContext, GpuBackend, parse_pubkey, parse_hex_u256};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let pubkey = parse_pubkey("03a2efa402fd5268400c77c20e574ba86409ededee7c4020e4b9f0edbee53de0d4")?;
    let start = parse_hex_u256("8000000000")?;

    let ctx = GpuContext::new(0, GpuBackend::Auto).await?;
    let mut solver = KangarooSolver::new(
        ctx,
        pubkey.clone(),
        start,
        40,  // range_bits
        12,  // dp_bits
        1024, // num_kangaroos
    )?;

    loop {
        if let Some(key) = solver.step()? {
            println!("Found: {}", hex::encode(&key));
            break;
        }
    }

    Ok(())
}

```

--------------------------------

### Default Progress Output Example

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

When not using --quiet or --json, Kangaroo displays detailed progress including GPU info, DP bits, kangaroo count, a real-time progress bar, and periodic DP counts.

```text
GPU: NVIDIA GeForce RTX 3090
Compute units: 82
DP bits: 14
Kangaroos: 4096
Starting search...
 [████████████░░░░░░░░░░░░░░░░░░░░░░] 1.2M/2.1M (0.98 ops/sec)
```

--------------------------------

### Specify Puzzle Source via Target

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Load puzzle parameters like pubkey, start, and range from a specified provider and path. This is one of the required ways to define the puzzle source.

```bash
kangaroo --target boha:b1000/66
```

```bash
kangaroo --target boha:b1000/135 --range 60
```

--------------------------------

### Modular Constraints API

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/MANIFEST.txt

Explains the mathematical theory and API for modular constraints (k ≡ R (mod M)), including practical examples and performance analysis.

```APIDOC
## Modular Constraints API

### Description
This document delves into the mathematical theory behind the k ≡ R (mod M) transformation and provides a detailed description of the `ModConstraint` API. It includes over 5 practical examples covering scenarios like Bitcoin, odd/even, and industrial applications, along with performance scaling analysis, parameter validation, and correctness proofs.

### Topics Covered
- Mathematical theory of k ≡ R (mod M) transformation
- ModConstraint API and field descriptions
- 5+ practical examples (Bitcoin, odd/even, industrial)
- Performance scaling analysis
- Parameter validation
- Correctness proofs

### Further Information
Refer to the `modular-constraints.md` document for detailed information.
```

--------------------------------

### Basic Single-GPU Search

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Perform a basic key search on a single GPU, specifying the public key, start point, and the range of keys to search.

```bash
# Search 2^40 keys starting from 0x8000000000
kangaroo --pubkey 03a2efa402fd5268400c77c20e574ba86409ededee7c4020e4b9f0edbee53de0d4 \
  --start 8000000000 \
  --range 40
```

--------------------------------

### KangarooSolver Constructor with Custom Base Point

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Creates a solver with a custom base point, suitable for modular constraint searches. The pubkey and start parameters should be transformed according to the constraint.

```rust
pub fn new_with_base(
    ctx: GpuContext,
    pubkey: Point,
    start: U256,
    range_bits: u32,
    dp_bits: u32,
    num_kangaroos: u32,
    base_point: ProjectivePoint,
) -> Result<Self>
```

```rust
let constraint = ModConstraint::new("3c", "25", &pubkey, &start, 40)?;
if let Some(c) = constraint {
    let solver = KangarooSolver::new_with_base(
        gpu_ctx,
        c.transformed_pubkey,
        c.j_start,
        c.effective_range_bits,
        dp_bits,
        num_kangaroos,
        c.base_point,
    )?;
}
```

--------------------------------

### Industrial-Scale Key Reduction with Partial Knowledge

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/modular-constraints.md

Demonstrates a large-scale reduction in search space when a partial key is known, such as k ≡ 0x1234 (mod 0x10000). This example shows a 65536x reduction in the search space.

```bash
kangaroo \
  --pubkey 03... \
  --start 0 \
  --range 40 \
  --mod-step 10000 \
  --mod-start 1234
```

--------------------------------

### Parse Hex U256 Example with Padding

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-crypto.md

Illustrates parsing a hex string with parse_hex_u256, showing how it pads to 64 hex characters and the resulting little-endian byte representation. Also shows parsing the maximum U256 value.

```rust
let start = parse_hex_u256("8000000000")?;
// Pads to: 0x00000000000000000000000000000000000000000000008000000000
// LE bytes: [0x00, ..., 0x80, 0x00, ...]

let max = parse_hex_u256("ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")?;
// All 0xff bytes
```

--------------------------------

### Build Kangaroo from Source

Source: https://github.com/oritwoen/kangaroo/blob/main/README.md

Clone the repository and build the release version of Kangaroo from source.

```bash
git clone https://github.com/oritwoen/kangaroo
cd kangaroo
cargo build --release
```

--------------------------------

### Enumerate available GPUs and display info

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/types.md

Demonstrates how to enumerate available GPUs using `enumerate_gpus` and then iterate through the discovered devices to print their index, name, and type.

```rust
let devices = enumerate_gpus(GpuBackend::Auto).await?;
for dev in devices {
    println!("{}: {} ({:?})", dev.index, dev.name, dev.device_type);
}
```

--------------------------------

### Modular Constraint Configuration

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

Create a ModConstraint with modular step, start, public key, start point, and range bits. The constraint can transform values for a reduced search space.

```rust
let constraint = ModConstraint::new(
    mod_step_hex,
    mod_start_hex,
    &pubkey,
    &start,
    range_bits,
)?;

if let Some(c) = constraint {
    // Use transformed values:
    // - base_point: H = M*G
    // - transformed_pubkey: Q = P - R*G
    // - j_start: ceil((start - R) / M)
    // - effective_range_bits: range_bits - log2(M)
}
```

--------------------------------

### Run Benchmark Suite

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

Execute the benchmark suite with specified GPU and save results.

```bash
kangaroo --benchmark --gpu 0 --save-benchmarks
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/INDEX.md

Shows fundamental Kangaroo CLI commands for solving with a public key and range, and for benchmarking.

```bash
kangaroo --pubkey 03... --range 40
kangaroo --pubkey 03... --range 40 --gpu all
kangaroo --benchmark --save-benchmarks
```

--------------------------------

### Get GPU Device Name

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Retrieve the human-readable name of the GPU device, such as its model.

```rust
pub fn device_name(&self) -> &str
```

--------------------------------

### CLI Usage with Modular Constraints

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/INDEX.md

Demonstrates how to use the Kangaroo CLI with modular constraints for solving.

```bash
kangaroo --pubkey 03... --range 40 --mod-step 3c --mod-start 25
```

--------------------------------

### Get Active GPU Backend

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Retrieve the specific GPU backend that the context is currently using.

```rust
pub fn backend(&self) -> GpuBackend
```

--------------------------------

### Create a GpuContext

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/types.md

Illustrates creating a `GpuContext` for managing GPU resources, either by specifying a device index and backend or by using a global index.

```rust
let ctx = GpuContext::new(0, GpuBackend::Auto).await?;
let ctx = GpuContext::new_from_global_index(0, GpuBackend::Auto).await?;
```

--------------------------------

### Get GPU Compute Unit Count

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Obtain the approximate number of compute units (SMs or EUs) on the GPU.

```rust
pub fn compute_units(&self) -> u32
```

--------------------------------

### Run Benchmarks with Cargo

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/INDEX.md

Alternatively, benchmarks can be run using the Cargo build tool.

```bash
cargo bench
```

--------------------------------

### Manual Parameter Search

Source: https://github.com/oritwoen/kangaroo/blob/main/README.md

Execute Kangaroo by manually specifying the public key, start of the search range, and the range in bits.

```bash
kangaroo \
    --pubkey 03a2efa402fd5268400c77c20e574ba86409ededee7c4020e4b9f0edbee53de0d4 \
    --start 8000000000 \
    --range 40
```

--------------------------------

### Create GpuContext with Index and Backend

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Instantiate a GpuContext using a specific GPU index and backend. The `Auto` backend selects the best available GPU. Metal backend is macOS specific.

```rust
pub async fn new(index: u32, backend: GpuBackend) -> Result<Self>
```

```rust
let ctx = GpuContext::new(0, GpuBackend::Auto).await?;
let ctx_metal = GpuContext::new(0, GpuBackend::Metal).await?; // macOS only
```

--------------------------------

### Output to File

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Specify a file path to save the discovered private key. The file will be created or overwritten.

```bash
kangaroo --pubkey 03... --range 40 --output result.txt
```

```bash
kangaroo --pubkey 03... --range 40 --output /tmp/key.hex
```

--------------------------------

### Basic Kangaroo Usage

Source: https://github.com/oritwoen/kangaroo/blob/main/README.md

Execute Kangaroo with essential parameters: public key, start of search range, and search range in bits.

```bash
kangaroo --pubkey <PUBKEY> --start <START> --range <BITS>
```

--------------------------------

### Run All Tests

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/INDEX.md

Execute all unit and integration tests for the project. This is the standard command for verifying the project's integrity.

```bash
cargo test
```

--------------------------------

### Run Test Suite

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/overview.md

Execute the project's test suite. Use the 'boha' feature for specific provider resolution tests.

```bash
cargo test
cargo test --features boha
```

--------------------------------

### Run Benchmark Suite

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Executes the benchmark suite to measure GPU throughput. Use `--save-benchmarks` to persist results.

```bash
kangaroo --benchmark
```

```bash
kangaroo --benchmark --save-benchmarks
```

--------------------------------

### Get Optimal Kangaroo Count

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Determine a recommended number of kangaroos (processing units) based on the GPU's capabilities. This is a heuristic value.

```rust
pub fn optimal_kangaroos(&self) -> u32
```

--------------------------------

### step_collect

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Executes one iteration of the Kangaroo algorithm and returns all distinguished points without performing collision detection. This is useful for multi-GPU setups.

```APIDOC
## step_collect

### Description
Performs one iteration and returns all distinguished points without collision detection, suitable for multi-GPU configurations.

### Method
`step_collect()`

### Return Type
`Result<(Vec<GpuDistinguishedPoint>, u64)>`

- `Vec<GpuDistinguishedPoint>`: A vector containing all DP points generated in this step.
- `u64`: The number of operations performed (kangaroo steps) during this iteration.

### Example
```rust
// Multi-GPU setup: collect DPs from each solver
let (dps, ops_delta) = solver.step_collect()?;
total_ops += ops_delta;

// Send DPs to central collision detection
for dp in dps {
    if let Some(key) = central_dp_table.insert_and_check(dp) {
        // Collision found!
        break;
    }
}
```

### Notes
- Intended for use when the solver is created with `new_with_base_no_dp_table`.
- Does not perform any internal collision detection.
- Returns immediately if no DP points are generated.
```

--------------------------------

### Development Commands

Source: https://github.com/oritwoen/kangaroo/blob/main/AGENTS.md

Commands for local development, including testing, building, and linting with Clippy.

```bash
# Development
just test              # cargo test --all-features
just build             # cargo build --release --all-features
just clippy            # cargo clippy --all-features -- -D warnings
```

--------------------------------

### JSON Output for Scripting

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Obtain JSON formatted results from the search, which can be easily parsed by scripting languages. This example shows how to extract the 'k_factor' from the metadata.

```bash
# Get JSON results for parsing
kangaroo --pubkey 03... --range 40 --json | jq '.metadata.k_factor'
```

--------------------------------

### Rust: Single-GPU Solver with Modular Constraint

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/modular-constraints.md

Demonstrates setting up a modular constraint (k ≡ 37 mod 60) and using the Kangaroo solver on a single GPU. Requires importing necessary modules and initializing the GPU context.

```rust
use kangaroo::{KangarooSolver, ModConstraint, GpuContext, GpuBackend, parse_pubkey, parse_hex_u256};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let pubkey = parse_pubkey("03a2efa402fd5268400c77c20e574ba86409ededee7c4020e4b9f0edbee53de0d4")?;
    let start = parse_hex_u256("8000000000")?;

    // Create constraint: k ≡ 37 (mod 60)
    let constraint = ModConstraint::new("3c", "25", &pubkey, &start, 40)?;

    if let Some(c) = constraint {
        let ctx = GpuContext::new(0, GpuBackend::Auto).await?;
        let mut solver = KangarooSolver::new_with_base(
            ctx,
            c.transformed_pubkey,
            c.j_start,
            c.effective_range_bits,  // ~40 - 6 = 34 bits
            12,  // DP bits
            1024, // kangaroos
        )?;

        loop {
            if let Some(j_bytes) = solver.step()? {
                // Recover k from j
                let k_scalar = c.mod_start + c.mod_step * Scalar::from_repr_vartime(...)?;
                let k_bytes = k_scalar.to_bytes();
                
                println!("Found j: {}", hex::encode(&j_bytes));
                println!("Found k: {}", hex::encode(k_bytes));
                break;
            }
        }
    } else {
        println!("No constraint (M=1, R=0)");
    }

    Ok(())
}

```

--------------------------------

### Solve Puzzle Using Boha Data

Source: https://github.com/oritwoen/kangaroo/blob/main/README.md

Use the 'boha' data provider to solve a puzzle. Parameters for pubkey, start, and range are automatically determined.

```bash
kangaroo --target boha:b1000/66
```

--------------------------------

### Run Kangaroo Benchmarks

Source: https://github.com/oritwoen/kangaroo/blob/main/BENCHMARKS.md

Execute the benchmark suite for the Kangaroo project. This command initiates performance tests on your hardware.

```bash
kangaroo --benchmark
```

--------------------------------

### CpuKangarooSolver Methods

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/MANIFEST.txt

Methods for interacting with the CPU-based Kangaroo solver.

```APIDOC
## CpuKangarooSolver::new()

### Description
Creates a new instance of the CpuKangarooSolver.

### Method
N/A (Method Call)

### Parameters
None.
```

```APIDOC
## CpuKangarooSolver::solve()

### Description
Executes the Kangaroo solving process using the CPU.

### Method
N/A (Method Call)

### Parameters
None.
```

--------------------------------

### Validate Search Bounds with Provider

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/modular-constraints.md

Ensures that constraint bounds are correctly validated when using a provider like Boha, checking the relationship between provider_start, start, range_bits, and provider_end.

```rust
validate_search_bounds(start, range_bits, provider_puzzle)?;
```

--------------------------------

### Get Cumulative Operation Count

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Retrieves the total number of kangaroo steps executed since the solver was created. This can be used to calculate performance metrics like the K-factor.

```rust
pub fn total_operations(&self) -> u64
```

```rust
let ops = solver.total_operations();
let k_factor = ops as f64 / (2.0_f64).powf(range_bits as f64 / 2.0);
println!("Operations: {}, K-factor: {:.3}", ops, k_factor);
```

--------------------------------

### List Available GPUs

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Displays a list of all detected GPU devices and their associated backends. This command exits after listing.

```bash
kangaroo --list-gpus
```

--------------------------------

### Parse Hex U256 Example

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-crypto.md

Demonstrates parsing a hexadecimal string into a U256 type. The function handles conversion to little-endian byte order and pads with leading zeros if necessary.

```rust
let start = parse_hex_u256("8000000000")?;
// start = [0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, ...]
//         (LE representation)
```

--------------------------------

### Cryptographic Utility Functions

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/MANIFEST.txt

Details the cryptographic utility functions available, such as key parsing, verification, and private key to public key conversion, along with type definitions and examples.

```APIDOC
## Cryptographic Utility Functions

### Description
This section covers the cryptographic utility functions provided by the library. It includes functions for parsing public keys, verifying keys, performing full verification (e.g., Bitcoin address verification), converting private keys to public keys, and computing hash160 values. Type definitions and examples are also provided.

### Functions
- parse_pubkey
- parse_hex_u256
- verify_key
- verify_key_with_base
- full_verify (Bitcoin address verification)
- privkey_to_pubkey
- compute_hash160

### Further Information
Refer to the `api-crypto.md` document for complete details on these functions, their parameters, and usage examples.
```

--------------------------------

### Benchmarking Commands

Source: https://github.com/oritwoen/kangaroo/blob/main/AGENTS.md

Commands for running benchmarks, both through Cargo and the built-in suite.

```bash
# Benchmarks
cargo test --release cpu_vs_gpu -- --nocapture --ignored
kangaroo --benchmark   # Built-in benchmark suite
```

--------------------------------

### CpuKangarooSolver::new

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Creates a new instance of the CPU solver. This is a blocking, synchronous constructor used to initialize the solver with specific parameters for the search.

```APIDOC
## CpuKangarooSolver::new

### Description
Create a CPU solver (blocking, synchronous).

### Parameters
#### Path Parameters
- **pubkey** (ProjectivePoint) - Required - Target public key
- **start_bytes** ([u8; 32]) - Required - Start range as BE bytes
- **range_bits** (u32) - Required - Bit width of range
- **dp_bits** (u32) - Required - Distinguished point bits (8–20 for CPU, lower = faster)
- **base_point** (ProjectivePoint) - Required - Base point (usually GENERATOR)
```

--------------------------------

### GpuContext::optimal_kangaroos

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Provides a recommended number of 'kangaroos' (likely a unit of parallel work) based on the GPU's capabilities. This is a heuristic value intended to guide workload sizing.

```APIDOC
## GpuContext::optimal_kangaroos

### Description
Recommended kangaroo count based on GPU capability.

### Method
`pub fn optimal_kangaroos(&self) -> u32`

### Return Type
`u32` — Heuristic kangaroo count (typically 512–8192)
```

--------------------------------

### GpuContext Creation

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

Create a GpuContext by specifying the device index and the GPU backend. The default device index is 0 and the backend defaults to Auto.

```rust
let ctx = GpuContext::new(device_index, backend).await?;
```

--------------------------------

### CpuKangarooSolver Struct Definition

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Defines the structure for the CPU-based Kangaroo solver. It includes fields for the public key, starting range, range bits, distinguished point bits, and base point.

```rust
pub struct CpuKangarooSolver { /* ... */ }

impl CpuKangarooSolver {
    pub fn new(
        pubkey: ProjectivePoint,
        start_bytes: [u8; 32],
        range_bits: u32,
        dp_bits: u32,
        base_point: ProjectivePoint,
    ) -> Self

    pub fn solve(&mut self, timeout: Duration) -> Option<Vec<u8>>

    pub fn total_ops(&self) -> u64
}
```

--------------------------------

### Type Relationships and Data Flow

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/types.md

Illustrates the relationships between different types and the data flow, from CLI arguments to solver output and verification. Useful for understanding the overall process.

```text
Args (CLI)
  ↓
  ├─→ parse_pubkey() → Point (ProjectivePoint)
  ├─→ parse_hex_u256() → U256 ([u8; 32])
  └─→ ModConstraint::new() → Option<ModConstraint>
       ├─→ base_point: Point
       ├─→ transformed_pubkey: Point
       └─→ effective_range_bits: u32

GpuBackend (Enum)
  ↓
enumerate_gpus() → Vec<GpuDeviceInfo>
  ↓
GpuContext::new() → GpuContext
  ↓
KangarooSolver::new() → KangarooSolver
  ↓
solver.step() → Option<Vec<u8>> (private key)
  ↓
verify_key() → bool
full_verify() → Result<FullVerification>
```

--------------------------------

### CLI Entry Points

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/MANIFEST.txt

Functions to run the Kangaroo CLI application with provided arguments.

```APIDOC
## run(args: Args)

### Description
Main entry point for the Kangaroo CLI application. It takes a set of arguments and executes the corresponding functionality.

### Method
N/A (Function Call)

### Parameters
- **args** (Args) - Required - The arguments to configure and run the application.
```

```APIDOC
## run_from_args(args_iter)

### Description
Parses an iterator of arguments and runs the Kangaroo application based on the parsed configuration.

### Method
N/A (Function Call)

### Parameters
- **args_iter** - Required - An iterator yielding arguments for parsing and execution.
```

--------------------------------

### GPU Backend Selection

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/cli-reference.md

Choose the specific GPU backend to use for computation. The 'auto' option attempts to detect the best available backend.

```bash
kangaroo --pubkey 03... --range 40 --backend vulkan
```

```bash
kangaroo --pubkey 03... --range 40 --backend metal     # macOS
```

```bash
kangaroo --pubkey 03... --range 40 --backend dx12      # Windows
```

--------------------------------

### Search Bitcoin Address with Specific Prefix and Modulo Constraint

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/modular-constraints.md

Searches for a Bitcoin address starting with '0xc28f' using a modular constraint k ≡ 100 (mod 256). This reduces the search space significantly.

```bash
kangaroo \
  --pubkey 03a2efa402fd5268400c77c20e574ba86409ededee7c4020e4b9f0edbee53de0d4 \
  --start c28f00000000000000000000000000000000000000000000000000000000 \
  --range 32 \
  --mod-step 100 \
  --mod-start 64
```

--------------------------------

### Boha Provider Build and Target

Source: https://github.com/oritwoen/kangaroo/blob/main/AGENTS.md

Commands for building with the 'boha' provider and targeting a specific configuration.

```bash
# With boha provider
cargo build --release --features boha
kangaroo --target boha:b1000/66
```

--------------------------------

### GpuContext Creation from Global Index

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/configuration.md

Create a GpuContext using a device's global index obtained from enumerating GPUs. This allows selection of a specific GPU from a list.

```rust
let devices = enumerate_gpus(GpuBackend::Auto).await?;
let ctx = GpuContext::new_from_global_index(devices[0].index, GpuBackend::Auto).await?;
```

--------------------------------

### KangarooSolver Constructor for Multi-GPU without DP Table

Source: https://github.com/oritwoen/kangaroo/blob/main/_autodocs/api-solver.md

Creates a solver without a CPU-side DP table, intended for multi-GPU setups where collision detection is managed externally. Requires global kangaroo count and an offset.

```rust
pub fn new_with_base_no_dp_table(
    ctx: GpuContext,
    pubkey: Point,
    start: U256,
    range_bits: u32,
    dp_bits: u32,
    num_kangaroos: u32,
    global_kangaroo_count: u32,
    base_point: ProjectivePoint,
    kangaroo_offset: u32,
) -> Result<Self>
```