Relevant source files

The following files were used as context for generating this wiki page: - [src/scanner.rs](https://github.com/oritwoen/vgen/blob/main/src/scanner.rs) - [src/lib.rs](https://github.com/oritwoen/vgen/blob/main/src/lib.rs) - [src/address.rs](https://github.com/oritwoen/vgen/blob/main/src/address.rs) - [src/pattern.rs](https://github.com/oritwoen/vgen/blob/main/src/pattern.rs) - [AGENTS.md](https://github.com/oritwoen/vgen/blob/main/AGENTS.md) - [README.md](https://github.com/oritwoen/vgen/blob/main/README.md)

# Parallel CPU Scanning Parallel CPU Scanning is the core orchestration mechanism in `vgen` for searching Bitcoin and Ethereum addresses across multiple CPU cores. It utilizes the `rayon` library to distribute the workload of private key generation, address derivation, and regex pattern matching across available system threads. This system serves as the primary scanning method when GPU acceleration is disabled or unsupported for specific formats like Ethereum. The scanning logic is divided into two primary modes: random search for vanity addresses and sequential range scanning for Bitcoin Puzzle challenges. Both modes leverage thread-local generators to minimize lock contention and maximize throughput, typically achieving rates between 50,000 and 200,000 keys per second depending on hardware. Sources: [src/scanner.rs:1-12](), [README.md:12-25](), [AGENTS.md:105-110]() ## Architecture and Configuration The CPU scanning system is built around the `ScanConfig` structure, which defines the parameters for the search, including the target address format, thread count, and batch sizes. The orchestration layer in `src/lib.rs` prepares this configuration based on CLI arguments or TUI state before invoking the scanner. ### Scan Configuration Parameters | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | `format` | `AddressFormat` | The target address type (P2PKH, P2WPKH, P2TR, Ethereum). | `P2pkh` | | `count` | `usize` | Number of matches to find before termination. | `1` | | `threads` | `Option` | Number of CPU threads to use; `None` uses all available. | `None` | | `cpu_batch_size`| `Option` | Keys processed per thread before updating global stats. | `10,000` | | `start` / `end` | `Option` | Key range boundaries for sequential scanning. | `None` | Sources: [src/scanner.rs:15-32](), [src/lib.rs:290-305]() ### Thread Management and Rayon Integration The scanner uses `rayon` for data-parallelism. When a specific thread count is provided in `ScanConfig`, a custom `rayon::ThreadPool` is initialized to execute the scan batches. To avoid the overhead of re-initializing heavy cryptographic contexts, the system uses `thread_local!` storage for the `AddressGenerator` (which contains the `Secp256k1` context) and the random number generator (`StdRng`). ```mermaid graph TD A[Scan Request] --> B{Threads Defined?} B -- Yes --> C[Build Custom Rayon Pool] B -- No --> D[Use Global Rayon Pool] C --> E[Parallel Iterator] D --> E[Parallel Iterator] E --> F[Thread 1: Local Generator] E --> G[Thread N: Local Generator] F --> H[Match Found?] G --> H H -- Yes --> I[Atomic Increment & Mutex Push] H -- No --> J[Next Iteration] ``` Sources: [src/scanner.rs:89-105](), [src/scanner.rs:114-125](), [AGENTS.md:95-98]() ## Search Logic and Data Flow The scanning process operates in batches to reduce atomic contention on global counters. Each thread processes a defined `cpu_batch_size` before reporting progress. ### Vanity Search (Random) In the default vanity search mode, threads generate cryptographically secure random 32-byte secret keys using `StdRng`. These keys are passed to the `AddressGenerator::generate` method, which derives the public key and formats the address according to the specified `AddressFormat`. 1. **Generation**: `rand::rngs::StdRng` fills a 32-byte buffer. 2. **Derivation**: `Secp256k1` context derives the address. 3. **Matching**: The address string is checked against the compiled `Pattern` regex. 4. **Collection**: Successful matches are collected into a `ScanResult`. Sources: [src/scanner.rs:126-155](), [src/address.rs:88-105]() ### Range Scanning (Sequential) For Bitcoin Puzzle solving, `scan_range_cpu` iterates sequentially through a `BigUint` range. The range is divided into large batches, which are then distributed via `into_par_iter()`. Each thread converts the numeric key value into big-endian bytes for the generator. ```mermaid sequenceDiagram participant Orchestrator participant Pool as Rayon Thread Pool participant Thread as Worker Thread participant Matcher as Pattern Matcher Orchestrator->>Pool: Start Range Scan (Start:End) loop Every Batch Pool->>Thread: Process Key Range Segment activate Thread Thread->>Thread: BigUint to [u8; 32] Thread->>Thread: Generate Address Thread->>Matcher: matches(address) Matcher-->>Thread: match status alt is_match Thread->>Orchestrator: Push to Result Mutex end Thread->>Orchestrator: Atomic Add Operations deactivate Thread end Orchestrator-->>Orchestrator: Check Stop Flag / Count ``` Sources: [src/scanner.rs:210-245](), [src/scanner.rs:250-280]() ## Performance Benchmarking The scanner includes a dedicated benchmark function that measures the raw address generation rate without the overhead of regex matching. This is used by the `estimate` command to provide the user with an expected time to find a match based on the pattern's difficulty. * **Function**: `benchmark(format: AddressFormat, iterations: u64) -> f64` * **Logic**: Runs a tight loop of random key generation and address derivation, returning the rate in addresses per second. * **Difficulty Integration**: The `Pattern::estimate_difficulty` result is divided by the benchmark rate to calculate `Expected time`. Sources: [src/scanner.rs:324-338](), [src/lib.rs:335-350](), [src/pattern.rs:95-110]() ## Progress Reporting and Interruption To provide real-time updates to the TUI or CLI progress bar, the scanning functions accept an optional `ProgressCallback` and an `AtomicBool` stop flag. * **ProgressCallback**: A `Send + Sync` closure invoked after each batch completes, passing the cumulative number of operations. * **Stop Flag**: Checked inside the parallel loops and thread-local batch loops. If set to `true` (e.g., via `Ctrl+C` or reaching the target match count), workers stop processing immediately. * **Thread Safety**: Matches are stored in an `Arc>>` to ensure safe concurrent access when a match is found. Sources: [src/scanner.rs:77-85](), [src/scanner.rs:160-170](), [src/lib.rs:555-570]() ## Summary of CPU Scanning Components | Component | Location | Role | |-----------|----------|------| | `scan_with_progress` | `scanner.rs:80` | Entry point for parallel CPU scanning. | | `scan_range_cpu` | `scanner.rs:210` | Specialized logic for sequential range iteration. | | `AddressGenerator` | `address.rs:74` | Thread-local resource for EC point math and address formatting. | | `ScanResult` | `scanner.rs:48` | Container for found `GeneratedAddress` objects and performance stats. | | `benchmark` | `scanner.rs:324` | Utility for measuring hardware performance per address format. | Sources: [src/scanner.rs:48-80](), [src/scanner.rs:210](), [src/address.rs:74]()