# ilkerccom/btcpuzzle architecture

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

- Interactive diagram: https://gitdiagram.com/ilkerccom/btcpuzzle
- Repository: https://github.com/ilkerccom/btcpuzzle

## Overview

This is a CUDA-enabled Bitcoin address/key search client, adapted for btcpuzzle.info pool work. The main workflow configures a worker, obtains pool ranges, searches them for target/proof addresses, then reports progress and found keys; standalone vanity-address searching is also supported. Internally, VanitySearch coordinates key-range scanning with secp256k1/address generation and GPU execution. The graph reflects README capabilities and the shown excerpts/index references; unshown call details are omitted or marked unverified.

Main entry points: [`main.cpp`](https://github.com/ilkerccom/btcpuzzle/blob/master/main.cpp) (Client entry), [`SECP256K1.cpp`](https://github.com/ilkerccom/btcpuzzle/blob/master/SECP256K1.cpp) (Secp256k1), [`Pool/PoolClient.cpp`](https://github.com/ilkerccom/btcpuzzle/blob/master/Pool/PoolClient.cpp) (Pool API client), [`Vanity.cpp`](https://github.com/ilkerccom/btcpuzzle/blob/master/Vanity.cpp) (Search coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Client runtime"]
  node_main["Client entry<br/>[main.cpp]"]
  node_logger["Logging<br/>[Logger.cpp]"]
end

subgraph group_search["Search engine"]
  node_vanity["Search coordinator<br/>[Vanity.cpp]"]
  node_gpu["GPU engine<br/>[GPUEngine.h]"]
  node_gpuwork["GPU kernels<br/>[GPUCompute.h]"]
  node_wildcard["Pattern matching<br/>[Wildcard.cpp]"]
end

subgraph group_crypto["Cryptography"]
  node_secp["Secp256k1<br/>[SECP256K1.cpp]"]
  node_point["Curve points<br/>[Point.cpp]"]
  node_integer["Big integers<br/>[Int.cpp]"]
  node_intmod["Modular arithmetic<br/>[IntMod.cpp]"]
  node_intgroup["Integer groups<br/>[IntGroup.cpp]"]
  node_base58["Base58 encoding<br/>[Base58.cpp]"]
  node_bech32["Bech32 encoding<br/>[Bech32.cpp]"]
  node_sha256["SHA-256<br/>[sha256.cpp]"]
  node_sha512["SHA-512<br/>[sha512.cpp]"]
  node_ripemd["RIPEMD-160<br/>[ripemd160.cpp]"]
  node_random["Random source<br/>[Random.cpp]"]
end

subgraph group_pool["Pool services"]
  node_config["Pool config<br/>[PoolConfig.cpp]"]
  node_poolclient["Pool API client<br/>[PoolClient.cpp]"]
end

node_user(("User"))
node_poolservice{{"btcpuzzle pool"}}
node_telegram{{"Telegram API"}}
node_webhook{{"Custom webhook"}}
node_output["Found-key results"]

node_user -->|"configures"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"starts search"| node_vanity
node_main -->|"manages ranges"| node_poolclient
node_main -->|"logs status"| node_logger
node_vanity -.->|"dispatches search"| node_gpu
node_gpu -.->|"runs kernels"| node_gpuwork
node_vanity -->|"derives addresses"| node_secp
node_vanity -->|"uses patterns"| node_wildcard
node_secp -->|"operates on points"| node_point
node_secp -.->|"uses scalars"| node_integer
node_secp -->|"encodes addresses"| node_base58
node_secp -->|"encodes addresses"| node_bech32
node_secp -->|"hashes keys"| node_sha256
node_secp -->|"hashes keys"| node_ripemd
node_integer -->|"uses grouped values"| node_intgroup
node_integer -.->|"uses modular math"| node_intmod
node_integer -->|"generates random values"| node_random
node_vanity -->|"groups scan values"| node_intgroup
node_main -->|"derives seed key"| node_sha512
node_poolclient -->|"requests ranges"| node_poolservice
node_poolclient -->|"submits progress"| node_poolservice
node_main -->|"passes found keys"| node_poolclient
node_poolclient -->|"sends notifications"| node_telegram
node_poolclient -.->|"shares results"| node_webhook
node_poolclient -->|"records found keys"| node_output
node_config -->|"reports settings"| node_logger

click node_main "https://github.com/ilkerccom/btcpuzzle/blob/master/main.cpp"
click node_config "https://github.com/ilkerccom/btcpuzzle/blob/master/Pool/PoolConfig.cpp"
click node_vanity "https://github.com/ilkerccom/btcpuzzle/blob/master/Vanity.cpp"
click node_gpu "https://github.com/ilkerccom/btcpuzzle/blob/master/GPU/GPUEngine.h"
click node_gpuwork "https://github.com/ilkerccom/btcpuzzle/blob/master/GPU/GPUCompute.h"
click node_wildcard "https://github.com/ilkerccom/btcpuzzle/blob/master/Wildcard.cpp"
click node_secp "https://github.com/ilkerccom/btcpuzzle/blob/master/SECP256K1.cpp"
click node_point "https://github.com/ilkerccom/btcpuzzle/blob/master/Point.cpp"
click node_integer "https://github.com/ilkerccom/btcpuzzle/blob/master/Int.cpp"
click node_intmod "https://github.com/ilkerccom/btcpuzzle/blob/master/IntMod.cpp"
click node_intgroup "https://github.com/ilkerccom/btcpuzzle/blob/master/IntGroup.cpp"
click node_base58 "https://github.com/ilkerccom/btcpuzzle/blob/master/Base58.cpp"
click node_bech32 "https://github.com/ilkerccom/btcpuzzle/blob/master/Bech32.cpp"
click node_sha256 "https://github.com/ilkerccom/btcpuzzle/blob/master/hash/sha256.cpp"
click node_sha512 "https://github.com/ilkerccom/btcpuzzle/blob/master/hash/sha512.cpp"
click node_ripemd "https://github.com/ilkerccom/btcpuzzle/blob/master/hash/ripemd160.cpp"
click node_random "https://github.com/ilkerccom/btcpuzzle/blob/master/Random.cpp"
click node_poolclient "https://github.com/ilkerccom/btcpuzzle/blob/master/Pool/PoolClient.cpp"
click node_logger "https://github.com/ilkerccom/btcpuzzle/blob/master/Pool/Logger.cpp"

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_main,node_logger,node_user toneBlue
class node_vanity,node_gpu,node_gpuwork,node_wildcard toneAmber
class node_secp,node_point,node_integer,node_intmod,node_intgroup,node_base58,node_bech32,node_sha256,node_sha512,node_ripemd,node_random,node_telegram,node_webhook toneMint
class node_config,node_poolclient toneRose
class node_poolservice,node_output toneIndigo
```

## Components

### Client runtime

- [Client entry](https://github.com/ilkerccom/btcpuzzle/blob/master/main.cpp): `main.cpp`
- [Logging](https://github.com/ilkerccom/btcpuzzle/blob/master/Pool/Logger.cpp): `Pool/Logger.cpp`

### Search engine

- [Search coordinator](https://github.com/ilkerccom/btcpuzzle/blob/master/Vanity.cpp): `Vanity.cpp`
- [GPU engine](https://github.com/ilkerccom/btcpuzzle/blob/master/GPU/GPUEngine.h): `GPU/GPUEngine.h`
- [GPU kernels](https://github.com/ilkerccom/btcpuzzle/blob/master/GPU/GPUCompute.h): `GPU/GPUCompute.h`
- [Pattern matching](https://github.com/ilkerccom/btcpuzzle/blob/master/Wildcard.cpp): `Wildcard.cpp`

### Cryptography

- [Secp256k1](https://github.com/ilkerccom/btcpuzzle/blob/master/SECP256K1.cpp): `SECP256K1.cpp`
- [Curve points](https://github.com/ilkerccom/btcpuzzle/blob/master/Point.cpp): `Point.cpp`
- [Big integers](https://github.com/ilkerccom/btcpuzzle/blob/master/Int.cpp): `Int.cpp`
- [Modular arithmetic](https://github.com/ilkerccom/btcpuzzle/blob/master/IntMod.cpp): `IntMod.cpp`
- [Integer groups](https://github.com/ilkerccom/btcpuzzle/blob/master/IntGroup.cpp): `IntGroup.cpp`
- [Base58 encoding](https://github.com/ilkerccom/btcpuzzle/blob/master/Base58.cpp): `Base58.cpp`
- [Bech32 encoding](https://github.com/ilkerccom/btcpuzzle/blob/master/Bech32.cpp): `Bech32.cpp`
- [SHA-256](https://github.com/ilkerccom/btcpuzzle/blob/master/hash/sha256.cpp): `hash/sha256.cpp`
- [SHA-512](https://github.com/ilkerccom/btcpuzzle/blob/master/hash/sha512.cpp): `hash/sha512.cpp`
- [RIPEMD-160](https://github.com/ilkerccom/btcpuzzle/blob/master/hash/ripemd160.cpp): `hash/ripemd160.cpp`
- [Random source](https://github.com/ilkerccom/btcpuzzle/blob/master/Random.cpp): `Random.cpp`

### Pool services

- [Pool config](https://github.com/ilkerccom/btcpuzzle/blob/master/Pool/PoolConfig.cpp): `Pool/PoolConfig.cpp`
- [Pool API client](https://github.com/ilkerccom/btcpuzzle/blob/master/Pool/PoolClient.cpp): `Pool/PoolClient.cpp`

### Other components

- **User**
- **btcpuzzle pool**
- **Telegram API**
- **Custom webhook**
- **Found-key results**

## Connections

- User → Client entry: configures
- Client entry → Pool config: loads settings (evidence: `main.cpp`)
- Client entry → Search coordinator: starts search (evidence: `main.cpp`)
- Client entry → Pool API client: manages ranges (evidence: `main.cpp`)
- Client entry → Logging: logs status (evidence: `main.cpp`)
- Search coordinator → GPU engine: dispatches search
- GPU engine → GPU kernels: runs kernels
- Search coordinator → Secp256k1: derives addresses (evidence: `Vanity.cpp`)
- Search coordinator → Pattern matching: uses patterns (evidence: `Vanity.cpp`)
- Secp256k1 → Curve points: operates on points
- Secp256k1 → Big integers: uses scalars
- Secp256k1 → Base58 encoding: encodes addresses (evidence: `SECP256K1.cpp`)
- Secp256k1 → Bech32 encoding: encodes addresses (evidence: `SECP256K1.cpp`)
- Secp256k1 → SHA-256: hashes keys (evidence: `SECP256K1.cpp`)
- Secp256k1 → RIPEMD-160: hashes keys (evidence: `SECP256K1.cpp`)
- Big integers → Integer groups: uses grouped values (evidence: `Int.cpp`)
- Big integers → Modular arithmetic: uses modular math
- Big integers → Random source: generates random values
- Search coordinator → Integer groups: groups scan values (evidence: `Vanity.cpp`)
- Client entry → SHA-512: derives seed key (evidence: `main.cpp`)
- Pool API client → btcpuzzle pool: requests ranges
- Pool API client → btcpuzzle pool: submits progress
- Client entry → Pool API client: passes found keys (evidence: `main.cpp`)
- Pool API client → Telegram API: sends notifications (evidence: `Pool/PoolClient.cpp`)
- Pool API client → Custom webhook: shares results
- Pool API client → Found-key results: records found keys (evidence: `Pool/PoolClient.cpp`)
- Pool config → Logging: reports settings (evidence: `Pool/PoolConfig.cpp`)
