# swar0g/seeker architecture

> Architecture diagram of the GitHub repository swar0g/seeker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swar0g/seeker
- Repository: https://github.com/swar0g/seeker

## Overview

Seeker builds a sorted HASH160 index from Bitcoin addresses, then repeatedly generates valid secret keys, hashes them through a selected compute backend, and checks the results against the index. A match is reported with its private key; the application also reports throughput. The graph includes the documented CUDA kernel and verification capabilities. The main-loop excerpt is partial, so its documented workflow relationships cite the README; implementation details not shown there are not inferred.

Main entry points: [`src/main.rs`](https://github.com/swar0g/seeker/blob/main/src/main.rs) (Seeker loop), [`src/backend/mod.rs`](https://github.com/swar0g/seeker/blob/main/src/backend/mod.rs) (Backend selection), [`src/backend/cuda.rs`](https://github.com/swar0g/seeker/blob/main/src/backend/cuda.rs) (CUDA backend), [`src/bin/build_index.rs`](https://github.com/swar0g/seeker/blob/main/src/bin/build_index.rs) (Index builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_indexing["Index construction"]
  node_address_input["Address list"]
  node_index_builder["Index builder<br/>[build_index.rs]"]
  node_address_index[("Mapped address index<br/>[main.rs]")]
end

subgraph group_seeking["Collision seeking"]
  node_seeker["Seeker loop<br/>[main.rs]"]
  node_key_generation["Key generation<br/>[main.rs]"]
  node_collision_check["Collision lookup<br/>[main.rs]"]
  node_match_report["Match and stats<br/>[main.rs]"]
end

subgraph group_backends["Compute backends"]
  node_backend_factory["Backend selection<br/>[mod.rs]"]
  node_cpu_backend["CPU backend<br/>[cpu.rs]"]
  node_cpu_hashing["CPU hash pipeline<br/>[main.rs]"]
end

subgraph group_acceleration["CUDA acceleration"]
  node_cuda_backend["CUDA backend<br/>[cuda.rs]"]
  node_cuda_kernels["GPU kernels<br/>[cuda_kernels.cu]"]
  node_cuda_verification["CPU parity checks<br/>[cuda.rs]"]
end

node_operator(("Operator"))

node_operator -->|"builds index"| node_index_builder
node_operator -->|"runs search"| node_seeker
node_address_input -->|"reads addresses"| node_index_builder
node_index_builder -->|"writes index"| node_address_index
node_seeker -->|"opens index"| node_address_index
node_seeker -->|"generates batches"| node_key_generation
node_seeker -->|"selects backend"| node_backend_factory
node_backend_factory -->|"creates default"| node_cpu_backend
node_backend_factory -.->|"creates optionally"| node_cuda_backend
node_cpu_backend -->|"delegates hashing"| node_cpu_hashing
node_seeker -->|"checks digests"| node_collision_check
node_collision_check -->|"searches hashes"| node_address_index
node_seeker -->|"reports results"| node_match_report
node_cuda_backend -->|"launches kernels"| node_cuda_kernels
node_cuda_backend -->|"verifies samples"| node_cuda_verification

click node_index_builder "https://github.com/swar0g/seeker/blob/main/src/bin/build_index.rs"
click node_address_index "https://github.com/swar0g/seeker/blob/main/src/main.rs"
click node_seeker "https://github.com/swar0g/seeker/blob/main/src/main.rs"
click node_key_generation "https://github.com/swar0g/seeker/blob/main/src/main.rs"
click node_collision_check "https://github.com/swar0g/seeker/blob/main/src/main.rs"
click node_match_report "https://github.com/swar0g/seeker/blob/main/src/main.rs"
click node_backend_factory "https://github.com/swar0g/seeker/blob/main/src/backend/mod.rs"
click node_cpu_backend "https://github.com/swar0g/seeker/blob/main/src/backend/cpu.rs"
click node_cpu_hashing "https://github.com/swar0g/seeker/blob/main/src/main.rs"
click node_cuda_backend "https://github.com/swar0g/seeker/blob/main/src/backend/cuda.rs"
click node_cuda_kernels "https://github.com/swar0g/seeker/blob/main/src/backend/cuda_kernels.cu"
click node_cuda_verification "https://github.com/swar0g/seeker/blob/main/src/backend/cuda.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_address_input,node_index_builder,node_address_index toneBlue
class node_seeker,node_key_generation,node_collision_check,node_match_report toneAmber
class node_backend_factory,node_cpu_backend,node_cpu_hashing toneMint
class node_cuda_backend,node_cuda_kernels,node_cuda_verification toneRose
class node_operator toneIndigo
```

## Components

### Index construction

- **Address list**
- [Index builder](https://github.com/swar0g/seeker/blob/main/src/bin/build_index.rs): `src/bin/build_index.rs`
- [Mapped address index](https://github.com/swar0g/seeker/blob/main/src/main.rs): `src/main.rs`

### Collision seeking

- [Seeker loop](https://github.com/swar0g/seeker/blob/main/src/main.rs): `src/main.rs`
- [Key generation](https://github.com/swar0g/seeker/blob/main/src/main.rs): `src/main.rs`
- [Collision lookup](https://github.com/swar0g/seeker/blob/main/src/main.rs): `src/main.rs`
- [Match and stats](https://github.com/swar0g/seeker/blob/main/src/main.rs): `src/main.rs`

### Compute backends

- [Backend selection](https://github.com/swar0g/seeker/blob/main/src/backend/mod.rs): `src/backend/mod.rs`
- [CPU backend](https://github.com/swar0g/seeker/blob/main/src/backend/cpu.rs): `src/backend/cpu.rs`
- [CPU hash pipeline](https://github.com/swar0g/seeker/blob/main/src/main.rs): `src/main.rs`

### CUDA acceleration

- [CUDA backend](https://github.com/swar0g/seeker/blob/main/src/backend/cuda.rs): `src/backend/cuda.rs`
- [GPU kernels](https://github.com/swar0g/seeker/blob/main/src/backend/cuda_kernels.cu): `src/backend/cuda_kernels.cu`
- [CPU parity checks](https://github.com/swar0g/seeker/blob/main/src/backend/cuda.rs): `src/backend/cuda.rs`

### Other components

- **Operator**

## Connections

- Operator → Index builder: builds index (evidence: `README.md`)
- Operator → Seeker loop: runs search (evidence: `README.md`)
- Address list → Index builder: reads addresses (evidence: `README.md`)
- Index builder → Mapped address index: writes index (evidence: `src/bin/build_index.rs`)
- Seeker loop → Mapped address index: opens index (evidence: `README.md`)
- Seeker loop → Key generation: generates batches (evidence: `README.md`)
- Seeker loop → Backend selection: selects backend (evidence: `src/main.rs`)
- Backend selection → CPU backend: creates default (evidence: `src/backend/mod.rs`)
- Backend selection → CUDA backend: creates optionally (evidence: `src/backend/mod.rs`)
- CPU backend → CPU hash pipeline: delegates hashing (evidence: `src/backend/cpu.rs`)
- Seeker loop → Collision lookup: checks digests (evidence: `README.md`)
- Collision lookup → Mapped address index: searches hashes (evidence: `README.md`)
- Seeker loop → Match and stats: reports results (evidence: `README.md`)
- CUDA backend → GPU kernels: launches kernels (evidence: `README.md`)
- CUDA backend → CPU parity checks: verifies samples (evidence: `src/backend/cuda.rs`)
