### Builder Pattern Configuration

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

Example of the builder pattern used for configuring project components like Electrum transforms or Parquet backends.

```rust
ElectrumTransform::new().with_change();
ParquetBackend::new().with_compression();
```

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

### Cascade Filtering Example (Bash)

Source: https://github.com/oritwoen/vuke/blob/main/src/analyze/AGENTS.md

Demonstrates how to use the cascade filtering feature for large seed spaces (2^64) by specifying multiple targets and their corresponding key prefixes. This is crucial for algorithms like mt64 and xorshift.

```bash
vuke analyze 0x15 --analyzer mt64 --cascade "5:0x15,10:0x202,20:0xd2c55"
```

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

### Benchmark cryptographic transforms via CLI

Source: https://context7.com/oritwoen/vuke/llms.txt

Provides examples of using the Vuke CLI to measure performance of specific transforms, including support for JSON output for automated CI pipelines.

```bash
vuke bench --transform milksad
vuke bench --transform sha256
vuke bench --transform lcg:glibc

vuke bench --transform milksad --json
```

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

### Execute SQL Queries with QueryExecutor in Rust

Source: https://github.com/oritwoen/vuke/blob/main/src/storage/AGENTS.md

Illustrates using the `QueryExecutor` to query stored results. It shows examples of retrieving data as Arrow RecordBatches for high performance, as a `Vec<Row>` for simple iteration, and as scalar values like i64 or String. Requires the `storage-query` feature.

```rust
let executor = QueryExecutor::new("./results")?;

// Returns Arrow RecordBatches (zero-copy)
let result = executor.query_arrow("SELECT * FROM results WHERE transform = 'milksad'")?;
for batch in result.batches() { ... }

// Returns Vec<Row> (simple iteration)
let rows = executor.query("SELECT transform, COUNT(*) FROM results GROUP BY transform")?;
for row in rows {
    println!("{}: {}", row.get_string("transform")?, row.get_i64("count")?);
}

// Scalar queries
let count: Option<i64> = executor.query_scalar_i64("SELECT COUNT(*) FROM results")?;
```

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

### Masking Formula Example (Text)

Source: https://github.com/oritwoen/vuke/blob/main/src/analyze/AGENTS.md

Provides the formula for calculating a masked key value. This is used in analysis modules that support masking, allowing for partial key analysis.

```text
masked = (full_key & ((1<<N)-1)) | (1<<(N-1))
```

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

### Configure ParquetBackend in Rust

Source: https://github.com/oritwoen/vuke/blob/main/src/storage/AGENTS.md

Demonstrates how to instantiate and configure the `ParquetBackend`. It shows setting the output directory, filename prefix, compression, and chunking thresholds (both by record count and byte size).

```rust
ParquetBackend::new("results/", "milksad")
    .with_compression(Compression::ZSTD(Default::default()))
    .with_chunk_records(1_000_000)
    .with_chunk_bytes(100 * 1024 * 1024)
```

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

### Rust: Source Processing with Transforms and Matching

Source: https://context7.com/oritwoen/vuke/llms.txt

Shows how to process input sources (like numeric ranges or wordlists) through various cryptographic transforms (Milksad, Sha256) using the Vuke library. It demonstrates setting up a matcher to find specific Bitcoin addresses and outputting results to the console.

```rust
use vuke::derive::KeyDeriver;
use vuke::source::{RangeSource, Source, WordlistSource};
use vuke::transform::{Transform, TransformType};
use vuke::matcher::Matcher;
use vuke::output::ConsoleOutput;

fn main() -> anyhow::Result<()> {
    // Create a range source (numeric seeds 1-1000)
    let source = RangeSource::new(1, 1000);

    // Create transforms
    let transforms: Vec<Box<dyn Transform>> = vec![
        TransformType::Milksad.create(),
        TransformType::Sha256.create(),
    ];

    // Create matcher with target addresses
    let matcher = Matcher::from_addresses(vec![
        "1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH".to_string(),
    ]);

    // Create output handler
    let output = ConsoleOutput::new();
    let deriver = KeyDeriver::new();

    // Process all inputs through transforms
    let stats = source.process(&transforms, &deriver, Some(&matcher), &output)?;

    println!("Inputs processed: {}", stats.inputs_processed);
    println!("Keys generated: {}", stats.keys_generated);
    println!("Matches found: {}", stats.matches_found);

    Ok(())
}
```

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

### Parquet Backend Configuration

Source: https://github.com/oritwoen/vuke/blob/main/src/storage/AGENTS.md

Demonstrates how to configure and instantiate the ParquetBackend, including options for compression and chunking.

```APIDOC
## Parquet Backend Configuration

### Description
Demonstrates how to configure and instantiate the ParquetBackend, including options for compression and chunking.

### Initialization
```rust
ParquetBackend::new("results/", "milksad")
    .with_compression(Compression::ZSTD(Default::default()))
    .with_chunk_records(1_000_000)
    .with_chunk_bytes(100 * 1024 * 1024)
```

### Configuration Options
| Method | Default | Description |
|--------|---------|-------------|
| `with_chunk_records(n)` | 1M | Rotate after N records |
| `with_chunk_bytes(n)` | 100MB | Rotate after N bytes |
| `without_chunking()` | - | Disable auto-rotation |

### Partitioning
**Hive-style partitioning**: `transform={name}/date={YYYY-MM-DD}/chunk_{NNNN}.parquet`
```

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

### Rust: KeyDeriver for Bitcoin Addresses

Source: https://context7.com/oritwoen/vuke/llms.txt

Demonstrates using the Vuke library's KeyDeriver to convert a 32-byte private key into various Bitcoin address formats, including WIF, P2PKH, and P2WPKH. It also outputs key metadata like bit length and Hamming weight.

```rust
use vuke::derive::KeyDeriver;

fn main() {
    let deriver = KeyDeriver::new();

    // SHA256("correct horse battery staple")
    let key: [u8; 32] = [
        0xc4, 0xbb, 0xcb, 0x1f, 0xbe, 0xc9, 0x9d, 0x65,
        0xbf, 0x59, 0xd8, 0x5c, 0x8c, 0xb6, 0x2e, 0xe2,
        0xdb, 0x96, 0x3f, 0x0f, 0xe1, 0x06, 0xf4, 0x83,
        0xd9, 0xaf, 0xa7, 0x3b, 0xd4, 0xe3, 0x9a, 0x8a,
    ];

    let derived = deriver.derive(&key);

    println!("Private Key (hex): {}", derived.private_key_hex);
    println!("WIF (compressed): {}", derived.wif_compressed);
    println!("P2PKH (compressed): {}", derived.p2pkh_compressed);
    println!("P2WPKH: {}", derived.p2wpkh);
    println!("Bit Length: {}", derived.bit_length);
    println!("Hamming Weight: {}", derived.hamming_weight);

    // Check all addresses
    for addr in derived.addresses() {
        println!("Address: {}", addr);
    }
}
```

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

### Build and Test Commands

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

Standard Cargo commands for compiling the project with optional features, running test suites, and executing benchmarks.

```bash
cargo build --release
cargo build --release --features gpu
cargo build --release --features storage
cargo build --release --features storage-query
cargo test
cargo test test_name -- --exact
cargo test transform::mt64::tests
cargo test --no-fail-fast
cargo bench
```

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

### Rust Key Derivation with SHA256 Transform

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

Demonstrates how to use the Vuke library in Rust for key derivation. It initializes a KeyDeriver and a Sha256Transform, applies the transform to an input string, and then derives keys, printing the WIF and address. Requires the 'vuke' crate.

```rust
use vuke::derive::KeyDeriver;
use vuke::transform::{Input, Transform, Sha256Transform};

fn main() {
    let deriver = KeyDeriver::new();
    let transform = Sha256Transform;

    let input = Input::from_string("test passphrase".to_string());
    let mut buffer = Vec::new();
    transform.apply_batch(&[input], &mut buffer);

    for (source, key) in buffer {
        let derived = deriver.derive(&key);
        println!("Source: {}", source);
        println!("WIF: {}", derived.wif_compressed);
        println!("Address: {}", derived.p2pkh_compressed);
    }
}
```

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

### Initialize GPU Context (Rust)

Source: https://github.com/oritwoen/vuke/blob/main/src/gpu/AGENTS.md

Demonstrates the synchronous initialization of the GPU context. This context is intended to be initialized once and reused for multiple GPU operations. It returns a `GpuContext` or a `GpuError` if initialization fails.

```rust
impl GpuContext {
    pub fn new_sync() -> Result<Self, GpuError>;
    pub fn description(&self) -> String;
}

// Initialize once, reuse across operations.
```

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

### Build with Iceberg Support

Source: https://context7.com/oritwoen/vuke/llms.txt

Compiles the Vuke project with the 'storage-iceberg' feature enabled, which is necessary for registering data in an Apache Iceberg catalog.

```bash
cargo build --release --features storage-iceberg
```

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

### Rust: Cryptographic Transforms for Key Derivation

Source: https://context7.com/oritwoen/vuke/llms.txt

Illustrates using Vuke's Transform trait with different implementations like Sha256Transform and MilksadTransform to convert input data (strings or numbers) into private keys. It then uses KeyDeriver to derive Bitcoin addresses from these keys.

```rust
use vuke::derive::KeyDeriver;
use vuke::transform::{Input, Transform, Sha256Transform, MilksadTransform};

fn main() {
    let deriver = KeyDeriver::new();

    // SHA256 transform (classic brainwallet)
    let sha256_transform = Sha256Transform;
    let input = Input::from_string("test passphrase".to_string());
    let mut buffer = Vec::new();
    sha256_transform.apply_batch(&[input], &mut buffer);

    for (source, key) in &buffer {
        let derived = deriver.derive(key);
        println!("Source: {}", source);
        println!("WIF: {}", derived.wif_compressed);
        println!("Address: {}", derived.p2pkh_compressed);
    }

    // Milksad transform (MT19937 PRNG with 32-bit seeds)
    let milksad_transform = MilksadTransform;
    let input = Input::from_u64(12345);
    let mut buffer = Vec::new();
    milksad_transform.apply_batch(&[input], &mut buffer);

    for (source, key) in &buffer {
        let derived = deriver.derive(key);
        println!("Seed: {}", source);
        println!("Address: {}", derived.p2pkh_compressed);
    }
}
```

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

### Configure Persistent Storage with Parquet

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

Stores generated keys in Parquet format for large-scale analysis, requiring the `storage` feature. This allows for efficient storage and retrieval of TB-scale data. Options include configuring chunk rotation, compression algorithms, and compression levels.

```bash
# Build with storage support
cargo build --release --features storage

# Store generated keys to Parquet
vuke generate --storage ./results --transform milksad range --start 1 --end 1000000

# Configure chunk rotation
vuke generate --storage ./results --chunk-records 500000 --chunk-bytes 50M range --start 1 --end 10000000

# Configure compression (default: zstd level 3)
vuke generate --storage ./results --compression zstd --compression-level 9 range --start 1 --end 1000000

# No compression (fastest writes)
vuke generate --storage ./results --compression none range --start 1 --end 1000000
```

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

### Match derived keys against Bitcoin addresses

Source: https://context7.com/oritwoen/vuke/llms.txt

Shows how to load target addresses from files or memory and check them against derived keys using the KeyDeriver and Matcher components.

```rust
use vuke::derive::KeyDeriver;
use vuke::matcher::{Matcher, AddressType};

fn main() -> anyhow::Result<()> {
    let matcher = Matcher::load("targets.txt")?;
    let matcher = Matcher::from_addresses(vec![
        "1JwSSubhmg6iPtRjtyqhUYYH7bZg3Lfy1T".to_string(),
        "bc1qfnpg7ceg02y64qrskgz0drwp3y6hma3q6wvnzr".to_string(),
    ]);

    let deriver = KeyDeriver::new();
    let key: [u8; 32] = [
        0xc4, 0xbb, 0xcb, 0x1f, 0xbe, 0xc9, 0x9d, 0x65,
        0xbf, 0x59, 0xd8, 0x5c, 0x8c, 0xb6, 0x2e, 0xe2,
        0xdb, 0x96, 0x3f, 0x0f, 0xe1, 0x06, 0xf4, 0x83,
        0xd9, 0xaf, 0xa7, 0x3b, 0xd4, 0xe3, 0x9a, 0x8a,
    ];

    let derived = deriver.derive(&key);

    if let Some(match_info) = matcher.check(&derived) {
        println!("MATCH FOUND!");
        println!("Address: {}", match_info.address);
        println!("Type: {}", match_info.address_type.as_str());
    }

    Ok(())
}
```

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

### CLI: Benchmark Transforms

Source: https://context7.com/oritwoen/vuke/llms.txt

Command-line interface for measuring the performance of cryptographic transforms.

```APIDOC
## CLI: vuke bench

### Description
Benchmarks specific cryptographic transforms to evaluate performance and optimization metrics.

### Method
CLI Command

### Parameters
#### Query Parameters
- **--transform** (string) - Required - The transform algorithm to benchmark (e.g., milksad, sha256).
- **--json** (flag) - Optional - Output results in JSON format for CI/CD integration.

### Request Example
`vuke bench --transform milksad --json`

### Response
#### Success Response (200)
- **throughput** (float) - Operations per second.
- **latency** (float) - Average execution time.
```

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

### Analyze private keys with Vuke Analyzer Trait

Source: https://context7.com/oritwoen/vuke/llms.txt

Demonstrates how to parse private keys and utilize various analyzers such as Direct, Heuristic, and Milksad. It covers both individual analyzer execution and batch processing using the AnalyzerType interface.

```rust
use vuke::analyze::{
    Analyzer, AnalysisConfig, AnalyzerType, MilksadAnalyzer,
    DirectAnalyzer, HeuristicAnalyzer, parse_private_key
};

fn main() -> anyhow::Result<()> {
    let key = parse_private_key("c4bbcb1fbec99d65bf59d85c8cb62ee2db963f0fe106f483d9afa73bd4e39a8a")?;
    let config = AnalysisConfig::default();

    let direct = DirectAnalyzer;
    let result = direct.analyze(&key, &config, None);
    println!("{}: {:?}", result.analyzer, result.status);

    let heuristic = HeuristicAnalyzer;
    let result = heuristic.analyze(&key, &config, None);
    println!("{}: {:?} - {:?}", result.analyzer, result.status, result.details);

    for analyzer_type in AnalyzerType::fast() {
        let analyzer = analyzer_type.create();
        let result = analyzer.analyze(&key, &config, None);
        println!("{}: {:?}", result.analyzer, result.status);
    }

    let config = AnalysisConfig {
        mask_bits: Some(5),
        cascade_targets: Some(vec![(5, 0x15), (10, 0x273)]),
    };

    let milksad = MilksadAnalyzer;
    let result = milksad.analyze(&key, &config, None);
    println!("Milksad: {:?}", result);

    Ok(())
}
```

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

### Run Specific Unit Tests via Cargo

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

Demonstrates how to execute a specific unit test within the project using the cargo test command with the exact flag for precise targeting.

```bash
cargo test transform::mt64::tests::test_transform_generates_key -- --exact
```

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

### Derive Keys from Files using Bitimage Transform

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

Derives keys from image files using the Bitimage transform. This can be done for single files, recursively scanning directories, or with custom derivation paths and passphrases. It also supports deriving multiple addresses per file and brute-forcing passphrases from a wordlist.

```bash
# Generate key from a single file
vuke generate --transform=bitimage files --file image.jpg

# Scan directory recursively
vuke generate --transform=bitimage files --dir ./images/

# With custom derivation path and passphrase
vuke generate --transform=bitimage --bitimage-path "m/44'/0'/0'/0/0" --bitimage-passphrase "secret" files --file photo.png

# Derive multiple addresses per file
vuke generate --transform=bitimage --bitimage-derive-count 10 files --dir ./data/

# Brute-force passphrases from wordlist
vuke scan --transform=bitimage --bitimage-passphrase-wordlist passphrases.txt --targets addresses.txt files --dir ./images/
```

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

### Matcher API

Source: https://context7.com/oritwoen/vuke/llms.txt

The Matcher module allows for efficient checking of derived keys against a set of target Bitcoin addresses.

```APIDOC
## Rust: Matcher

### Description
Matches derived keys against a pre-loaded list of target Bitcoin addresses to identify successful derivations.

### Method
N/A (Rust Library API)

### Parameters
#### Request Body
- **targets** (Vec<String>) - Required - List of target addresses to match against.
- **derived_key** (Address) - Required - The derived address to check.

### Response
#### Success Response
- **address** (String) - The matched address.
- **address_type** (String) - The format of the address (e.g., P2PKH, Segwit).

### Response Example
```json
{
  "address": "1JwSSubhmg6iPtRjtyqhUYYH7bZg3Lfy1T",
  "address_type": "P2PKH"
}
```
```

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

### Query Executor Usage

Source: https://github.com/oritwoen/vuke/blob/main/src/storage/AGENTS.md

Shows how to use the QueryExecutor to query stored results using SQL, with options for returning Arrow RecordBatches or simple Row objects.

```APIDOC
## Query Executor Usage (feature: storage-query)

### Description
Shows how to use the QueryExecutor to query stored results using SQL, with options for returning Arrow RecordBatches or simple Row objects.

### Initialization
```rust
let executor = QueryExecutor::new("./results")?;
```

### Query Methods
- **`query_arrow(sql)`**: Returns `QueryResult` (Arrow RecordBatches). Use case: High performance, Arrow ecosystem.
  ```rust
  let result = executor.query_arrow("SELECT * FROM results WHERE transform = 'milksad'")?;
  for batch in result.batches() { ... }
  ```
- **`query(sql)`**: Returns `Vec<Row>`. Use case: Simple iteration.
  ```rust
  let rows = executor.query("SELECT transform, COUNT(*) FROM results GROUP BY transform")?;
  for row in rows {
      println!("{}: {{}}", row.get_string("transform")?, row.get_i64("count")?);
  }
  ```
- **`query_scalar_i64(sql)`**: Returns `Option<i64>`. Use case: Scalar queries like COUNT, SUM.
  ```rust
  let count: Option<i64> = executor.query_scalar_i64("SELECT COUNT(*) FROM results")?;
  ```
- **`query_scalar_string(sql)`**: Returns `Option<String>`. Use case: Scalar queries returning a single string.
- **`schema()`**: Returns `Option<Schema>`. Use case: Introspect result schema.
- **`discovered_files()`**: Returns `Vec<String>`. Use case: List Parquet files.
- **`refresh()`**: Returns `()`. Use case: Recreate view after new writes.

### Auto-discovery
**Auto-discovery**: Creates `results` view from `{path}/**/*.parquet` with Hive partitioning enabled.
```

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

### Generate, Upload, and Register in Iceberg

Source: https://context7.com/oritwoen/vuke/llms.txt

Generates data, uploads it to cloud storage, and registers it in an Apache Iceberg catalog. This command requires the Iceberg catalog endpoint and specifies the data transformation range.

```bash
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
    --iceberg-catalog http://localhost:8181 \
    --transform milksad range --start 1 --end 1000000
```

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

### Upload to AWS S3

Source: https://context7.com/oritwoen/vuke/llms.txt

Uploads generated data from a local storage path to an AWS S3 bucket using the 'vuke generate' command. It specifies the storage location, cloud upload, bucket name, and a transformation range.

```bash
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
    --transform milksad range --start 1 --end 1000000
```

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

### Pipe Input from Stdin for Key Generation

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

Generates keys by piping data from standard input (stdin) to the Vuke CLI, using a specified transform (e.g., SHA256). This is efficient for processing large lists of data without writing intermediate files.

```bash
cat passwords.txt | vuke generate --transform=sha256 stdin
```

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

### Rust Import Convention

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

Standardized import ordering for the project, requiring external crates followed by std, then super, and finally crate-level modules.

```rust
use anyhow::Result;
use rayon::prelude::*;
use std::path::PathBuf;

use super::Source;

use crate::derive::KeyDeriver;
use crate::transform::{Input, Transform};
```

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

### Generate and Upload Data to Iceberg Catalog

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

Generates data, uploads it to a cloud bucket, and registers it in an Iceberg catalog. Supports custom namespaces and table names. Requires cloud credentials and an Iceberg catalog endpoint.

```bash
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
  --iceberg-catalog http://localhost:8181 \
  --transform milksad range --start 1 --end 1000000
```

```bash
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
  --iceberg-catalog http://localhost:8181 \
  --iceberg-namespace my_namespace \
  --iceberg-table my_results \
  --transform milksad range --start 1 --end 1000000
```

```bash
export ICEBERG_CATALOG=http://localhost:8181
export ICEBERG_NAMESPACE=vuke
export ICEBERG_TABLE=results
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
  --transform milksad range --start 1 --end 1000000
```

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

### Manage Cargo Dependencies for Storage Module

Source: https://github.com/oritwoen/vuke/blob/main/src/storage/AGENTS.md

Specifies the necessary dependencies for the storage module in `Cargo.toml`. It includes optional features for Parquet, Arrow, and DuckDB, along with instructions on how to enable them during the build process.

```toml
parquet = { version = "54", optional = true, features = ["arrow", "zstd"] }
arrow = { version = "54", optional = true }
duckdb = { version = "1.4", optional = true, features = ["bundled"] }
```

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

### Set Cloud Credentials

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

Sets environment variables for cloud access key ID and secret access key. These are necessary for cloud upload operations.

```bash
export CLOUD_ACCESS_KEY_ID=your_key
export CLOUD_SECRET_ACCESS_KEY=your_secret
```

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

### Benchmark Transforms

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

Benchmarks a specified transform. This command is useful for performance testing different data transformation methods.

```bash
vuke bench --transform milksad
```

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

### GPU Module Dependencies (TOML)

Source: https://github.com/oritwoen/vuke/blob/main/src/gpu/AGENTS.md

Lists the optional dependencies required for the GPU module, including `wgpu`, `pollster`, and `bytemuck`. These are enabled via the `gpu` feature flag during the build process.

```toml
wgpu = { version = "24", optional = true }
pollster = { version = "0.4", optional = true }
bytemuck = { version = "1.21", features = ["derive"], optional = true }

# Enable with: cargo build --features gpu
```

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

### Query Stored Parquet Results using SQL

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

Queries Parquet files stored using Vuke's storage feature via SQL, requiring the `storage-query` feature. This enables complex data analysis, filtering, and exporting results in various formats like JSON and CSV.

```bash
# Build with query support
cargo build --release --features storage-query

# Count results by transform
vuke query ./results "SELECT transform, COUNT(*) FROM results GROUP BY transform"

# Find matches
vuke query ./results "SELECT * FROM results WHERE matched_target IS NOT NULL LIMIT 10"

# Export to JSON
vuke query ./results --format json "SELECT source, wif_compressed FROM results LIMIT 100"

# Export to CSV
vuke query ./results --format csv "SELECT address_p2pkh_compressed, wif_compressed FROM results" > export.csv

# Show schema
vuke query ./results --schema
```

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

### Register in Iceberg with Custom Namespace/Table

Source: https://context7.com/oritwoen/vuke/llms.txt

Generates and uploads data, then registers it in an Iceberg catalog using a custom namespace and table name. This allows for more organized data management within the catalog.

```bash
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
    --iceberg-catalog http://localhost:8181 \
    --iceberg-namespace my_namespace \
    --iceberg-table my_results \
    --transform milksad range --start 1 --end 1000000
```

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

### Provider-Based Puzzle Analysis

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

Uses data providers to automatically configure puzzle analysis, including setting masks and building cascades from solved neighbors. Supports JSON output for scripting.

```bash
vuke analyze 0x15 --puzzle boha:b1000:5
```

```bash
vuke analyze 0x15 --cascade boha:b1000:5:3 --analyzer milksad
```

```bash
vuke analyze 0x01 --verify boha:b1000
```

```bash
vuke analyze 0x01 --verify boha:b1000 --json
```

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

### Upload to Cloudflare R2

Source: https://context7.com/oritwoen/vuke/llms.txt

Uploads generated data to a Cloudflare R2 bucket. This command requires specifying the cloud endpoint, bucket name, and the transformation range for the data.

```bash
vuke generate --storage ./results --cloud-upload \
    --cloud-endpoint https://account.r2.cloudflarestorage.com \
    --cloud-bucket my-r2-bucket \
    --transform milksad range --start 1 --end 1000000
```

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

### Compute Shader Structure (WGSL)

Source: https://github.com/oritwoen/vuke/blob/main/src/gpu/AGENTS.md

Illustrates a typical compute shader structure using WGSL. It includes the compute attribute, workgroup size, accessing global invocation ID, early termination using atomic operations, and conditional atomic storage for results.

```wgsl
@compute @workgroup_size(256)
fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
    let seed = uniforms.start_seed + global_id.x;
    if atomicLoad(&result.found) != 0u { return; }  // Early termination
    // Algorithm...
    if match_found { atomicStore(&result.found, 1u); result.seed = seed; }
}
```

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

### Save Scan and Generation Results to File

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

Saves the output of Vuke generate or scan operations to a specified file. Options include specifying the output file name, format (e.g., CSV, TXT), and verbosity level.

```bash
vuke generate --output results.csv range --start 1 --end 1000000
vuke generate --output results.txt --verbose range --start 1 --end 1000
vuke scan --output hits.txt --targets addresses.txt wordlist --file passwords.txt
```

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

### Storage Backend Trait

Source: https://github.com/oritwoen/vuke/blob/main/src/storage/AGENTS.md

Defines the interface for storage backends, including methods for writing batches of records, flushing data, and retrieving the schema.

```APIDOC
## Storage Backend Trait

### Description
Defines the interface for storage backends, including methods for writing batches of records, flushing data, and retrieving the schema.

### Methods
- `write_batch(&mut self, records: &[ResultRecord<'_>]) -> Result<()>`: Writes a batch of records to the storage.
- `flush(&mut self) -> Result<Vec<PathBuf>>`: Flushes any buffered data and returns a list of paths to the flushed files.
- `schema(&self) -> &Schema`: Returns a reference to the Arrow schema used by the storage backend.

### Trait Definition
```rust
pub trait StorageBackend: Send + Sync {
    fn write_batch(&mut self, records: &[ResultRecord<'_>]) -> Result<()>;
    fn flush(&mut self) -> Result<Vec<PathBuf>>;
    fn schema(&self) -> &Schema;
}
```
```

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

### Set AWS Credentials

Source: https://context7.com/oritwoen/vuke/llms.txt

Sets the AWS access key ID and secret access key as environment variables for authentication with AWS services.

```bash
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
```

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

### Analyze with LCG (Linear Congruential Generator)

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

Checks if a private key was generated using a Linear Congruential Generator. Supports checking all variants or specific ones with endianness and masking options.

```bash
vuke analyze --analyzer lcg <KEY>
```

```bash
vuke analyze --analyzer lcg:glibc:le <KEY>
```

```bash
vuke analyze --analyzer lcg:glibc --mask 5 0x15
```

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

### Analyze Private Key Origin

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

Analyzes a given private key to determine if it could have been generated by a vulnerable method. Supports various analysis modes including fast mode and specific analyzers.

```bash
vuke analyze c4bbcb1fbec99d65bf59d85c8cb62ee2db963f0fe106f483d9afa73bd4e39a8a
```

```bash
vuke analyze --fast L3p8oAcQTtuokSCRHQ7i4MhjWc9zornvpJLfmg62sYpLRJF9woSu
```

```bash
vuke analyze --fast --json c4bbcb1f...
```

```bash
vuke analyze --analyzer milksad c4bbcb1f...
```

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

### Generate Keys with Specific Xorshift Variants

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

Generates keys using different xorshift pseudorandom number generator variants (xorshift:64, xorshift:128, xorshift:128plus, xorshift:xoroshiro) within a specified range. This is useful for creating sequences of random numbers for various applications.

```bash
vuke generate --transform=xorshift:64 range --start 1 --end 1000
vuke generate --transform=xorshift:128 range --start 1 --end 1000
vuke generate --transform=xorshift:128plus range --start 1 --end 1000
vuke generate --transform=xorshift:xoroshiro range --start 1 --end 1000
```

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

### Upload Parquet Results to Cloud Storage (S3-compatible)

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

Uploads Parquet results stored locally to S3-compatible cloud storage, requiring the `storage-cloud` feature. Supports various cloud providers like AWS S3, Cloudflare R2, and MinIO, with options for credential management, bucket configuration, and local file deletion after upload.

```bash
# Build with cloud upload support
cargo build --release --features storage-cloud

# Set credentials (AWS S3)
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

# Upload to AWS S3
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
  --transform milksad range --start 1 --end 1000000

# Upload to Cloudflare R2
vuke generate --storage ./results --cloud-upload \
  --cloud-endpoint https://account.r2.cloudflarestorage.com \
  --cloud-bucket my-r2-bucket \
  --transform milksad range --start 1 --end 1000000

# Upload to MinIO (self-hosted)
vuke generate --storage ./results --cloud-upload \
  --cloud-endpoint http://localhost:9000 \
  --cloud-bucket vuke-results \
  --transform milksad range --start 1 --end 1000000

# Delete local files after successful upload
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
  --cloud-delete-local \
  --transform milksad range --start 1 --end 1000000

# Fail fast on upload errors (default: continue on failures)
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
  --cloud-fail-fast \
  --transform milksad range --start 1 --end 1000000
```

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

### Register Parquet Files in Apache Iceberg Catalog

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

Registers Parquet files uploaded to cloud storage into an Apache Iceberg catalog, requiring the `storage-iceberg` feature. This enables SQL querying of the data through the Iceberg catalog.

```bash
# Build with Iceberg support
cargo build --release --features storage-iceberg
```

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

### Analyze Masked Key for Puzzles

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

Analyzes masked keys, often used in Bitcoin puzzles, where a full key is masked to N bits. Supports specifying the mask and analyzer.

```bash
vuke analyze 0x15 --mask 5 --analyzer milksad
```

```bash
vuke analyze 0x202 --mask 10 --analyzer milksad
```

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

### Perform Scans with Multiple Transforms

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

Executes a scan operation applying multiple hashing algorithms (SHA256, double_sha256, MD5) sequentially. This is useful for comprehensive analysis or when dealing with systems that use different hashing methods.

```bash
vuke scan --transform=sha256 --transform=double_sha256 --transform=md5 --targets addresses.txt wordlist --file words.txt
```

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

### Define StorageBackend Trait in Rust

Source: https://github.com/oritwoen/vuke/blob/main/src/storage/AGENTS.md

Defines the core `StorageBackend` trait for persistent storage. It outlines methods for writing batches of records, flushing data, and retrieving the schema. This trait is fundamental for implementing new storage backends.

```rust
pub trait StorageBackend: Send + Sync {
    fn write_batch(&mut self, records: &[ResultRecord<'_>]) -> Result<()>;
    fn flush(&mut self) -> Result<Vec<PathBuf>>;
    fn schema(&self) -> &Schema;
}
```

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

### Upload and Delete Local Files

Source: https://context7.com/oritwoen/vuke/llms.txt

Uploads generated data to AWS S3 and then deletes the local files after a successful upload. This is useful for managing disk space after cloud synchronization.

```bash
vuke generate --storage ./results --cloud-upload --cloud-bucket my-bucket \
    --cloud-delete-local \
    --transform milksad range --start 1 --end 1000000
```

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

### Cascading Filter for Multi-Puzzle Verification

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

Verifies candidates against multiple known puzzle keys using a cascading filter. This reduces false positive rates by checking against puzzles with increasing bit widths.

```bash
vuke analyze 0x16 --analyzer milksad --cascade "5:0x16,10:0x273,15:0x7a85"
```

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

### Define Output Trait in Rust

Source: https://github.com/oritwoen/vuke/blob/main/src/output/AGENTS.md

The Output trait defines the interface for all output backends in the system. Implementations must be thread-safe (Send + Sync) and provide methods for handling keys, matches, and flushing data to the destination.

```rust
pub trait Output: Send + Sync {
    fn key(&self, source: &str, transform: &str, derived: &DerivedKey) -> Result<()>;
    fn hit(&self, source: &str, transform: &str, derived: &DerivedKey, match_info: &MatchInfo) -> Result<()>;
    fn flush(&self) -> Result<()>;
}
```

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

### Rust Input Struct Definition

Source: https://github.com/oritwoen/vuke/blob/main/src/transform/AGENTS.md

Defines the `Input` struct used to represent various forms of input data for the transform algorithms. It supports string, u64, and byte array representations, including big-endian and little-endian formats.

```rust
pub struct Input {
    pub string_val: String,
    pub u64_val: u64,
    pub bytes_be: [u8; 8],
    pub bytes_le: [u8; 8],
}

// Constructors: `from_string()`, `from_u64()`, `from_bytes()`
```

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

### Scan Timestamp-Based Keys with SHA256

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

Scans for keys derived from timestamps within a specified date range using the SHA256 transform. It requires a target file containing addresses and a date range for the scan.

```bash
vuke scan --transform=sha256 --targets addresses.txt timestamps --start 2015-01-01 --end 2015-01-31
```