### Install vgen from Source

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

Install the vgen utility from the project source using cargo. This command compiles and installs the vgen project from the current directory.

```bash
cargo install --path .
```

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

### Bash: Command-Line Usage Examples

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

Demonstrates various command-line invocations for the VGen tool, including generating vanity addresses, estimating pattern difficulty, scanning ranges, and verifying private keys.

```bash
# Development
cargo test                    # Run tests
cargo build --release         # Optimized build
cargo bench                   # Run benchmarks

# Release (updates Cargo.toml, PKGBUILD, CHANGELOG.md)
just release X.Y.Z            # Then: git push && git push --tags

# Usage
vgen generate -p "^1Cat"      # Find vanity address
vgen estimate -p "^1CatDog"   # Estimate difficulty
vgen range --puzzle 66        # Scan Bitcoin puzzle range
vgen verify -k <WIF>          # Verify private key
```

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

### Install vgen via Cargo

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

Install the vgen utility from crates.io using the cargo package manager. This command downloads and compiles the vgen project.

```bash
cargo install vgen
```

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

### Install vgen from Arch Linux AUR

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

Install the vgen utility on Arch Linux using the paru package manager. This command uses the Arch User Repository (AUR) to install the necessary dependencies and the vgen project.

```bash
paru -S vgen
```

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

### Range Scanning for Private Keys - Rust

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

Scans a specific range of private keys for Bitcoin addresses, useful for Bitcoin Puzzle challenges or deterministic key searches. It utilizes `num_bigint::BigUint` to define large start and end points for the private key range. The function `scan_with_progress` is used, and it can match any address within the specified range.

```rust
use vgen::{Pattern, ScanConfig, AddressFormat, scan_with_progress};
use num_bigint::BigUint;
use num_traits::Num;

// Puzzle #66 range: 2^65 to 2^66-1
let start = BigUint::from(1u64) << 65;
let end = (BigUint::from(1u64) << 66) - 1u32;

let config = ScanConfig {
    format: AddressFormat::P2pkh,
    count: 1,
    threads: Some(16),
    cpu_batch_size: Some(10_000),
    gpu_batch_size: None,
    start: Some(start),
    end: Some(end),
};

// Match any address in range
let pattern = Pattern::new(".", false)?;

let result = scan_with_progress(&pattern, &config, None, None);

if !result.matches.is_empty() {
    println!("Found key in range!");
    println!("Address: {}", result.matches[0].address);
    println!("Private key: {}", result.matches[0].hex);
}

// Custom hex range
let start_hex = BigUint::from_str_radix("20000000000000000", 16)?;
let end_hex = BigUint::from_str_radix("3FFFFFFFFFFFFFFFF", 16)?;

let config_custom = ScanConfig {
    start: Some(start_hex),
    end: Some(end_hex),
    ..config
};
```

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

### Rust: Main Entry Point

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

A minimal wrapper around the core logic in `lib.rs`. This file serves as the primary entry point for the executable.

```rust
src/main.rs: Thin wrapper → lib.rs
```

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

### Library API - GPU Scanning

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

Leverage GPU acceleration for 5-10x faster address generation using wgpu compute shaders.

```APIDOC
## Library API - GPU Scanning

### Description
Leverage GPU acceleration for 5-10x faster address generation using wgpu compute shaders.

### Method
`scan_gpu_with_runner`

### Endpoint
Not applicable (Library function)

### Parameters
#### Request Body
- **pattern** (`Pattern`) - Required - The pattern to search for.
- **config** (`ScanConfig`) - Required - Configuration for the scan (format, count, batch size, etc.). Note: `threads` should be `None` for GPU scanning.
- **progress_cb** (`Option<Arc<dyn Fn(u64) + Send + Sync>>`) - Optional - Callback function to report progress.
- **stop** (`Option<Arc<AtomicBool>>`) - Optional - Atomic boolean flag to signal a stop.
- **runner** (`Arc<GpuRunner>`) - Required - An initialized `GpuRunner` instance.

### Request Example
```rust
use vgen::{Pattern, ScanConfig, AddressFormat, GpuRunner, scan_gpu_with_runner};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize GPU runner (async)
    let batch_size = 1_048_576; // 1 million keys per batch
    let gpu_runner = GpuRunner::new(batch_size).await?;
    println!("GPU Device: {}", gpu_runner.device_name);

    let runner = Arc::new(gpu_runner);

    // Configure GPU scan
    let config = ScanConfig {
        format: AddressFormat::P2pkh,
        count: 1,
        threads: None,
        gpu_batch_size: Some(batch_size),
        cpu_batch_size: None,
        start: None,
        end: None,
    };

    let pattern = Pattern::new("^1Cat", false)?;

    // Progress callback
    let progress_cb = Arc::new(|ops: u64| {
        println!("Checked {} keys", ops);
    });

    // Run GPU scan
    let result = scan_gpu_with_runner(
        &pattern,
        &config,
        Some(progress_cb),
        None,
        runner
    ).await?;
}
```

### Response
#### Success Response (Result)
- **matches** (`Vec<Match>`): A list of found matches (address, wif, hex).
- **operations** (`u64`): Total number of keys checked.

#### Response Example
```rust
println!("Found: {} ({})", result.matches[0].address, result.matches[0].wif);
println!("Rate: {:.0} keys/sec", result.rate());
```
```

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

### Rust: Validate Address Patterns and Benchmark Generation

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

Demonstrates how to use the vgen library in Rust to validate address patterns against character sets of various address formats (e.g., P2PKH, Bech32) and to benchmark the performance of address generation. It shows how to identify invalid characters and estimate the time needed to find a matching address.

```rust
use vgen::{Pattern, AddressFormat, benchmark};

// Validate pattern charset
let pattern = Pattern::new("^1O0Il", false)?;
let invalid_chars = pattern.validate_charset(AddressFormat::P2pkh);

if !invalid_chars.is_empty() {
    println!("Warning: Pattern contains invalid Base58 characters: {:?}", invalid_chars);
    println!("Base58 excludes: 0, O, I, l");
    println!("This pattern will NEVER match!");
}

//Bech32 validation
let bech32_pattern = Pattern::new("^bc1qABCD", false)?;
let invalid = bech32_pattern.validate_charset(AddressFormat::P2wpkh);
// Bech32 excludes: 1, b, i, o and uppercase letters
assert!(invalid.contains(&'A'));
assert!(invalid.contains(&'B'));

// Benchmark address generation rate
let iterations = 10_000u64;
let rate_p2pkh = benchmark(AddressFormat::P2pkh, iterations);
let rate_p2wpkh = benchmark(AddressFormat::P2wpkh, iterations);
let rate_ethereum = benchmark(AddressFormat::Ethereum, iterations);

println!("P2PKH:    {:.0} addr/sec", rate_p2pkh);
println!("P2WPKH:   {:.0} addr/sec", rate_p2wpkh);
println!("Ethereum: {:.0} addr/sec", rate_ethereum);

// Estimate search time
let pattern = Pattern::new("^1CatDog", false)?;
let difficulty = pattern.estimate_difficulty(AddressFormat::P2pkh);
let expected_secs = difficulty as f64 / rate_p2pkh;

println!("Pattern difficulty: 1 in {}", difficulty);
println!("Expected time: {:.1} hours", expected_secs / 3600.0);

```

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

### Rust: Pattern Matching for Address Validation

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

Demonstrates using the `vgen` Rust library to create and use regular expression patterns for matching Bitcoin addresses. Includes case-sensitive and case-insensitive matching, difficulty estimation, and character set validation.

```rust
use vgen::{Pattern, AddressFormat};

// Create case-sensitive pattern
let pattern = Pattern::new("^1Cat", false)?;

// Check if address matches
let address = "1CatXXXXXXXXXXXXXXXXXXXXXXXXXXX";
assert!(pattern.matches(address));

// Case-insensitive pattern
let pattern_ci = Pattern::new("^1cat", true)?;
assert!(pattern_ci.matches("1CatXXX"));
assert!(pattern_ci.matches("1CATXXX"));

// Estimate difficulty (1 in N addresses will match)
let difficulty = pattern.estimate_difficulty(AddressFormat::P2pkh);
// For "^1Cat" (3 chars after "1"): 58^3 = 195,112

// Validate charset - returns invalid characters for format
let invalid_chars = pattern.validate_charset(AddressFormat::P2pkh);
// Base58 excludes: 0 (zero), O (uppercase o), I (uppercase i), l (lowercase L)
assert!(invalid_chars.is_empty()); // "Cat" is valid

let bad_pattern = Pattern::new("^1O0Il", false)?;
let invalid = bad_pattern.validate_charset(AddressFormat::P2pkh);
// Returns: ['O', '0', 'I', 'l']
```

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

### Rust: GPU Acceleration Pipeline

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

Manages the GPU acceleration pipeline using the 'wgpu' library. This includes setting up pipelines, managing buffers, and dispatching compute tasks for faster address generation.

```rust
src/gpu.rs: GpuRunner struct, dispatch(), await_result()
```

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

### Build Automation with Just

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

Uses the 'just' build system for automating common development tasks, including building, testing, and releasing new versions of the project.

```makefile
justfile
```

```makefile
just release X.Y.Z
```

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

### Rust: Address Generation for Bitcoin and Ethereum

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

Shows how to use the `vgen` Rust library to generate Bitcoin and Ethereum addresses from secret keys. Supports P2PKH, P2WPKH (Bech32), P2TR (Taproot), and Ethereum formats. Includes helper functions for generating addresses from public keys and converting bytes to WIF.

```rust
use vgen::{AddressGenerator, AddressFormat};
use bitcoin::Network;

// Create generator for P2PKH addresses
let generator = AddressGenerator::new(AddressFormat::P2pkh);

// Generate from 32-byte secret key
let secret = [0x01; 32];
let result = generator.generate(&secret).unwrap();

println!("Address: {}", result.address);  // Starts with "1"
println!("WIF: {}", result.wif);          // WIF-encoded private key
println!("Hex: {}", result.hex);          // Hex-encoded private key

// Generate Bech32 address (P2WPKH)
let gen_bech32 = AddressGenerator::new(AddressFormat::P2wpkh);
let result = gen_bech32.generate(&secret).unwrap();
assert!(result.address.starts_with("bc1q"));

// Generate Ethereum address
let gen_eth = AddressGenerator::new(AddressFormat::Ethereum);
let result = gen_eth.generate(&secret).unwrap();
assert!(result.address.starts_with("0x"));
assert_eq!(result.address.len(), 42); // 0x + 40 hex chars

// Generate P2TR (Taproot) address
let gen_taproot = AddressGenerator::new(AddressFormat::P2tr);
let result = gen_taproot.generate(&secret).unwrap();
assert!(result.address.starts_with("bc1p"));

// Helper: Generate P2PKH from compressed public key bytes
let pubkey_bytes: [u8; 33] = [0x02; 33]; // Compressed public key
let address = AddressGenerator::p2pkh_from_public_key_bytes(&pubkey_bytes)?;

// Helper: Convert secret bytes to WIF
let wif = AddressGenerator::bytes_to_wif(&secret, Network::Bitcoin);

```

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

### GPU Scanning with wgpu Runner - Rust

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

Accelerates Bitcoin address generation using GPU compute shaders via the wgpu library. This method offers a 5-10x speedup compared to CPU scanning. It requires initializing a `GpuRunner` asynchronously and configuring scan parameters specific to GPU batch processing. This is ideal for high-throughput scanning tasks.

```rust
use vgen::{Pattern, ScanConfig, AddressFormat, GpuRunner, scan_gpu_with_runner};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize GPU runner (async)
    let batch_size = 1_048_576; // 1 million keys per batch
    let gpu_runner = GpuRunner::new(batch_size).await?;
    println!("GPU Device: {}", gpu_runner.device_name);

    let runner = Arc::new(gpu_runner);

    // Configure GPU scan
    let config = ScanConfig {
        format: AddressFormat::P2pkh,
        count: 1,
        threads: None,
        gpu_batch_size: Some(batch_size),
        cpu_batch_size: None,
        start: None,
        end: None,
    };

    let pattern = Pattern::new("^1Cat", false)?;

    // Progress callback
    let progress_cb = Arc::new(|ops: u64| {
        println!("Checked {} keys", ops);
    });

    // Run GPU scan
    let result = scan_gpu_with_runner(
        &pattern,
        &config,
        Some(progress_cb),
        None,
        runner
    ).await?;

    println!("Found: {} ({})", result.matches[0].address, result.matches[0].wif);
    println!("Rate: {:.0} keys/sec", result.rate());

    Ok(())
}
```

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

### Library API - CPU Scanning

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

Scan for vanity addresses using parallel CPU with rayon, progress callbacks, and stop signals.

```APIDOC
## Library API - CPU Scanning

### Description
Scan for vanity addresses using parallel CPU with rayon, progress callbacks, and stop signals.

### Method
`scan_with_progress`

### Endpoint
Not applicable (Library function)

### Parameters
#### Request Body
- **pattern** (`Pattern`) - Required - The pattern to search for.
- **config** (`ScanConfig`) - Required - Configuration for the scan (format, count, threads, batch size, etc.).
- **progress_cb** (`Option<Arc<dyn Fn(u64) + Send + Sync>>`) - Optional - Callback function to report progress.
- **stop** (`Option<Arc<AtomicBool>>`) - Optional - Atomic boolean flag to signal a stop.

### Request Example
```rust
use vgen::{Pattern, ScanConfig, AddressFormat, scan_with_progress};
use std::sync::{Arc, atomic::{AtomicBool, AtomicU64, Ordering}};

// Configure scan
let config = ScanConfig {
    format: AddressFormat::P2pkh,
    count: 3,                      // Find 3 matches
    threads: Some(8),               // Use 8 threads
    cpu_batch_size: Some(10_000),   // 10K keys per batch
    gpu_batch_size: None,           // No GPU
    start: None,                    // Random scan (not range)
    end: None,
};

// Create pattern
let pattern = Pattern::new("^1Cat", false)?;

// Progress callback
let ops_counter = Arc::new(AtomicU64::new(0));
let ops_clone = ops_counter.clone();
let progress_cb = Arc::new(move |ops: u64| {
    ops_clone.store(ops, Ordering::Relaxed);
    println!("Checked {} keys", ops);
});

// Stop flag for graceful shutdown
let stop = Arc::new(AtomicBool::new(false));
let stop_clone = stop.clone();
ctrlc::set_handler(move || {
    stop_clone.store(true, Ordering::Relaxed);
})?;

// Run scan
let result = scan_with_progress(
    &pattern,
    &config,
    Some(progress_cb),
    Some(stop)
);
```

### Response
#### Success Response (Result)
- **matches** (`Vec<Match>`): A list of found matches (address, wif, hex).
- **operations** (`u64`): Total number of keys checked.
- **elapsed_secs** (`f64`): Time taken for the scan in seconds.

#### Response Example
```rust
println!("Found {} matches", result.matches.len());
println!("Checked {} keys in {:.2}s", result.operations, result.elapsed_secs);
println!("Rate: {:.0} keys/sec", result.rate());

for (i, addr) in result.matches.iter().enumerate() {
    println!("Match {}: {} -> {}", i+1, addr.address, addr.wif);
}
```
```

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

### Verify Private Key using vgen

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

Verify a private key using the vgen utility. Input can be in WIF or hex formats. Optionally, verify against an expected address.

```bash
# From WIF
vgen verify -k "5HueCGU8rMjxEXxiPuD5BDku4MkFqeZyd4dZ1jvhTVqvbTLvyTJ"

# From hex
vgen verify -k "0c28fca386c7a227600b2fe50b7cae11ec86d3bf1fbe471be89827e19d72aa1d"

# Verify against expected address
vgen verify -k "5HueCGU8rMjxEXxiPuD5BDku4MkFqeZyd4dZ1jvhTVqvbTLvyTJ" -a "1GAehh7TsJAHuUAeKZcXf5CnwuGuGgyX2S"
```

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

### Rust: Regex Pattern Matching and Difficulty Estimation

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

Compiles and validates regular expression patterns for vanity addresses. It also includes functionality to estimate the difficulty of finding an address matching a given pattern.

```rust
src/pattern.rs: Pattern struct, validate_charset(), estimate_difficulty()
```

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

### Rust: CPU Parallel Scanning

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

Provides functionality for parallel scanning of private keys using CPU resources. It leverages the 'rayon' crate for efficient multi-threading.

```rust
src/scanner.rs: scan_with_progress(), rayon parallel batches
```

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

### Rust: Command-Line Interface (CLI) and Terminal User Interface (TUI)

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

Implements the command-line interface using the 'clap' crate and the terminal user interface with 'ratatui'. This module orchestrates the overall application flow.

```rust
src/lib.rs: CLI (clap), TUI (ratatui), orchestration
```

```rust
src/lib.rs: Clap Commands enum, run_tui(), output formatting
```

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

### CPU Scanning with Progress and Stop Signals - Rust

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

Scans for vanity Bitcoin addresses using parallel CPU processing with the rayon crate. It demonstrates how to configure scan parameters, set up progress callbacks to monitor scan progress, and implement a stop signal for graceful shutdown using ctrlc. This is suitable for general-purpose address generation.

```rust
use vgen::{Pattern, ScanConfig, AddressFormat, scan_with_progress};
use std::sync::{Arc, atomic::{AtomicBool, AtomicU64, Ordering}};

// Configure scan
let config = ScanConfig {
    format: AddressFormat::P2pkh,
    count: 3,                      // Find 3 matches
    threads: Some(8),               // Use 8 threads
    cpu_batch_size: Some(10_000),   // 10K keys per batch
    gpu_batch_size: None,           // No GPU
    start: None,                    // Random scan (not range)
    end: None,
};

// Create pattern
let pattern = Pattern::new("^1Cat", false)?;

// Progress callback
let ops_counter = Arc::new(AtomicU64::new(0));
let ops_clone = ops_counter.clone();
let progress_cb = Arc::new(move |ops: u64| {
    ops_clone.store(ops, Ordering::Relaxed);
    println!("Checked {} keys", ops);
});

// Stop flag for graceful shutdown
let stop = Arc::new(AtomicBool::new(false));
let stop_clone = stop.clone();
ctrlc::set_handler(move || {
    stop_clone.store(true, Ordering::Relaxed);
})?;

// Run scan
let result = scan_with_progress(
    &pattern,
    &config,
    Some(progress_cb),
    Some(stop)
);

println!("Found {} matches", result.matches.len());
println!("Checked {} keys in {:.2}s", result.operations, result.elapsed_secs);
println!("Rate: {:.0} keys/sec", result.rate());

for (i, addr) in result.matches.iter().enumerate() {
    println!("Match {}: {} -> {}", i+1, addr.address, addr.wif);
}
```

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

### Estimate Difficulty using vgen

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

Estimate the difficulty of generating a vanity address based on a given pattern using the vgen utility.

```bash
vgen estimate -p "^1CatDog"
```

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

### Library API - Range Scanning

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

Scan a specific range of private keys for Bitcoin Puzzle challenges or deterministic key search.

```APIDOC
## Library API - Range Scanning

### Description
Scan a specific range of private keys for Bitcoin Puzzle challenges or deterministic key search.

### Method
`scan_with_progress` (with `start` and `end` in `ScanConfig`)

### Endpoint
Not applicable (Library function)

### Parameters
#### Request Body
- **pattern** (`Pattern`) - Required - The pattern to search for.
- **config** (`ScanConfig`) - Required - Configuration for the scan, including `start` and `end` for the key range.
- **progress_cb** (`Option<Arc<dyn Fn(u64) + Send + Sync>>`) - Optional - Callback function to report progress.
- **stop** (`Option<Arc<AtomicBool>>`) - Optional - Atomic boolean flag to signal a stop.

### Request Example
```rust
use vgen::{Pattern, ScanConfig, AddressFormat, scan_with_progress};
use num_bigint::BigUint;
use num_traits::Num;

// Puzzle #66 range: 2^65 to 2^66-1
let start = BigUint::from(1u64) << 65;
let end = (BigUint::from(1u64) << 66) - 1u32;

let config = ScanConfig {
    format: AddressFormat::P2pkh,
    count: 1,
    threads: Some(16),
    cpu_batch_size: Some(10_000),
    gpu_batch_size: None,
    start: Some(start),
    end: Some(end),
};

// Match any address in range
let pattern = Pattern::new(".", false)?;

let result = scan_with_progress(&pattern, &config, None, None);

// Custom hex range
let start_hex = BigUint::from_str_radix("20000000000000000", 16)?;
let end_hex = BigUint::from_str_radix("3FFFFFFFFFFFFFFFF", 16)?;

let config_custom = ScanConfig {
    start: Some(start_hex),
    end: Some(end_hex),
    ..config
};
```

### Response
#### Success Response (Result)
- **matches** (`Vec<Match>`): A list of found matches within the specified range.

#### Response Example
```rust
if !result.matches.is_empty() {
    println!("Found key in range!");
    println!("Address: {}", result.matches[0].address);
    println!("Private key: {}", result.matches[0].hex);
}
```
```

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

### Generate Bitcoin Addresses with Patterns (CLI)

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

Generates Bitcoin addresses matching a given pattern using the command-line interface. Supports various output formats like CSV and minimal (WIF only).

```bash
vgen generate -p "^1Cat" -o csv -c 2
vgen generate -p "^1Cat" -o minimal
vgen generate -p "^1Cat" -o jsonl --file results.jsonl -c 10
vgen generate -p "^1Cat" -q
```

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

### Estimate Vanity Pattern Difficulty

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

Calculates the estimated difficulty and time required to find a Bitcoin or Ethereum address matching a given regex pattern. Supports specifying the address format and case sensitivity.

```bash
# Estimate difficulty for pattern "^1CatDog"
vgen estimate -p "^1CatDog"

# Estimate for Bech32 pattern
vgen estimate -p "^bc1q.*dead$" -f p2wpkh

# Case insensitive estimation
vgen estimate -p "^1cat" -i

# Expected output:
# Pattern: ^1CatDog
# Format: P2PKH (1...)
# Case insensitive: false
#
# Estimated difficulty: 1 in 195,112,
# Benchmark rate: 123,456 addr/sec
# Expected time: 26.3m

```

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

### Rust: Address Generation Logic

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

Handles the core logic for address generation, including support for various Bitcoin address formats like P2PKH, P2WPKH, and P2TR. It utilizes the 'bitcoin' crate for cryptographic operations.

```rust
src/address.rs: AddressFormat enum, AddressGenerator::generate()
```

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

### Output Formats in vgen

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

Specify the output format for the generated vanity address using the vgen utility. Supported formats include text, JSON, JSON Lines, CSV, and minimal.

```bash
# Default text output
vgen generate -p "^1Cat" -o text

# JSON output (pretty-printed)
vgen generate -p "^1Cat" -o json

# JSON Lines (one JSON object per line, for data pipelines)
vgen generate -p "^1Cat" -o jsonl

# CSV (with header, for data catalogs/Iceberg)
vgen generate -p "^1Cat" -o csv

# Minimal (just WIF)
vgen generate -p "^1Cat" -o minimal

# Write to file
vgen generate -p "^1Cat" -o jsonl --file results.jsonl
vgen generate -p "^1Cat" -o csv --file results.csv
```

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

### Scan Key Range for Bitcoin Puzzles

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

Scans a specific range of private keys, primarily for Bitcoin Puzzle challenges. Allows specifying predefined puzzle ranges or custom hex ranges for scanning. Supports pattern matching and limiting the number of results.

```bash
# Scan Bitcoin Puzzle #66 range
vgen range --puzzle 66 -p "."

# Custom hex range (start:end format)
vgen range -r "20000000000000000:3FFFFFFFFFFFFFFFF" -p "^1"

# Scan puzzle range with pattern match
vgen range --puzzle 66 -p "^1BTC"

# Stop after finding 5 matches in range
vgen range --puzzle 66 -p "." -c 5

# CPU only range scanning
vgen range --puzzle 66 -p "." --no-gpu

# Expected output (text format):
# === Match 1 of 1 ===
# Pattern : .
# Format  : P2PKH
# Address : 13zb1hQbWVsc2S7ZTZnP2G4undNNpdh5so
# WIF     : KwDiBf89QgGbjEhKnhXJuH7LrciVrZi3qYjgd9M7rFU73sVHnoWn
# Hex     : 20d45a6a762535700ce9e0b216e31994335db8a5
# Ops     : 8,192,000,000 (1,234,567/sec)
# Time    : 1.8h

```

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

### Generate Vanity Bitcoin or Ethereum Addresses

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

Generates Bitcoin (P2PKH, P2WPKH, P2TR) or Ethereum addresses matching a specified regex pattern. Supports case-sensitive/insensitive matching, disabling GPU acceleration, custom thread counts, and disabling the TUI for scripting. Outputs include address, WIF, hex, operations count, and time.

```bash
# Find P2PKH address starting with "1Cat" (case sensitive)
vgen generate -p "^1Cat"

# Case insensitive matching
vgen generate -p "^1cat" -i

# P2WPKH (Bech32) address ending with "dead"
vgen generate -p "dead$" -f p2wpkh

# Ethereum address starting with "0xdead"
vgen generate -p "^0xdead" -f ethereum

# CPU only mode (disable GPU acceleration)
vgen generate -p "^1Cat" --no-gpu

# Find 5 matching addresses
vgen generate -p "^1Cat" -c 5

# Custom thread count
vgen generate -p "^1Cat" -t 8

# Disable TUI for scripting
vgen generate -p "^1Cat" --no-tui

# Expected output (text format):
# === Match 1 of 1 ===
# Pattern : ^1Cat
# Format  : P2PKH
# Address : 1CatXXXXXXXXXXXXXXXXXXXXXXXXXXX
# WIF     : 5HueCGU8rMjxEXxiPuD5BDku4MkFqeZyd4dZ1jvhTVqvbTLvyTJ
# Hex     : 0c28fca386c7a227600b2fe50b7cae11ec86d3bf1fbe471be89827e19d72aa1d
# Ops     : 3,364 (58,000/sec)
# Time    : 0.06s

```

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

### Generate Vanity Address using vgen

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

Generate a Bitcoin vanity address matching a custom regex pattern. Several options are available, including case-insensitive matching, specifying address formats, and disabling GPU acceleration.

```bash
# Find address starting with "1Cat"
vgen generate -p "^1Cat"

# Case insensitive matching
vgen generate -p "^1cat" -i

# Bech32 address ending with "dead"
vgen generate -p "dead$" -f p2wpkh

# Ethereum address
vgen generate -p "^0xdead" -f ethereum

# CPU only (GPU is enabled by default)
vgen generate -p "^1Cat" --no-gpu

# Find multiple matches
vgen generate -p "^1Cat" -c 5
```

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

### WGSL: Elliptic Curve Arithmetic Shaders

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

Contains WebGPU Shading Language (WGSL) compute shaders for performing elliptic curve arithmetic operations, specifically for the secp256k1 curve, which is central to Bitcoin's cryptography.

```wgsl
src/shaders/generator.wgsl: secp256k1 EC arithmetic, main kernel
```

```wgsl
src/shaders/generator.wgsl: point_add(), point_double(), scalar_mult()
```

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

### WGSL: RIPEMD-160 Hashing Shader

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

Implements the RIPEMD-160 hashing algorithm within WGSL, often used in conjunction with SHA-256 for Bitcoin address generation.

```wgsl
src/shaders/ripemd160.wgsl: RIPEMD-160 implementation
```

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

### Scan Key Range using vgen

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

Scan a key range, often used for Bitcoin Puzzle challenges, using the vgen utility. This allows for searching for addresses within a specified range.

```bash
# Scan puzzle #66 range
vgen range --puzzle 66 -p "."

# Custom range
vgen range -r "20000000000000000:3FFFFFFFFFFFFFFFF"
```

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

### WGSL: SHA-256 Hashing Shader

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

Implements the SHA-256 hashing algorithm within WGSL. This shader can be used for cryptographic hashing operations on the GPU.

```wgsl
src/shaders/sha256.wgsl: SHA-256 implementation
```

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

### Export Vanity Addresses in JSON or JSON Lines

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

Exports generated vanity addresses in JSON or JSON Lines format. JSON provides a single object per result, while JSON Lines outputs one JSON object per line, suitable for streaming and data pipelines.

```bash
# JSON output (pretty-printed)
vgen generate -p "^1Cat" -o json
# Output: {"address":"1CatXXX...","wif":"5HueC...","private_key_hex":"0c28f...","format":"P2PKH","pattern":"^1Cat","operations":3364,"elapsed_secs":0.058,"rate":58000.0}

# JSON Lines format (one object per line, for streaming/data pipelines)
vgen generate -p "^1Cat" -o jsonl -c 3
# Output:
# {"address":"1Cat111...","wif":"5Hue...","private_key_hex":"0c2...","format":"P2PKH","pattern":"^1Cat","operations":1842,"elapsed_secs":0.032,"rate":57562.5}
# {"address":"1Cat222...","wif":"5Jxk...","private_key_hex":"1a3...","format":"P2PKH","pattern":"^1Cat","operations":3684,"elapsed_secs":0.064,"rate":57562.5}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.