# retiredc/rckangaroo architecture

> Architecture diagram of the GitHub repository retiredc/rckangaroo, 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/retiredc/rckangaroo
- Repository: https://github.com/retiredc/rckangaroo

## Overview

RCKangaroo is a GPU-accelerated secp256k1 ECDLP kangaroo solver. Its main workflow parses a target key and range (or selects benchmark mode), prepares elliptic-curve jump data, runs kangaroos on selected GPUs, collects distinguished points and checks collisions, then reports a recovered key. Optional tame-point reuse is documented. The excerpts show host-side GPU setup and DP handling, but not the full kernel dispatch or tame-file call sites; those links are omitted or marked unverified.

Main entry points: [`RCKangaroo.cpp`](https://github.com/retiredc/rckangaroo/blob/main/RCKangaroo.cpp) (CLI and solver), [`GpuKang.cpp`](https://github.com/retiredc/rckangaroo/blob/main/GpuKang.cpp) (GPU kangaroo host), [`Ec.cpp`](https://github.com/retiredc/rckangaroo/blob/main/Ec.cpp) (Elliptic-curve math), [`CallCubin.cpp`](https://github.com/retiredc/rckangaroo/blob/main/CallCubin.cpp) (Cubin dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and setup"]
  node_cli["CLI and solver<br/>[RCKangaroo.cpp]"]
  node_runtime_defs["Runtime parameters<br/>[defs.h]"]
  node_tame_files["Tame point files"]
end

subgraph group_math["Curve arithmetic"]
  node_ec["Elliptic-curve math<br/>[Ec.cpp]"]
end

subgraph group_compute["GPU search"]
  node_gpu_host["GPU kangaroo host<br/>[GpuKang.cpp]"]
  node_kernel_code["CUDA kernels<br/>[RCGpuCore.cu]"]
  node_turbo_asm["Turbo kernels<br/>[newKernelB.asm]"]
  node_cubin_loader["Cubin dispatch<br/>[CallCubin.cpp]"]
end

subgraph group_solve["Collision and results"]
  node_dp_list["Distinguished points<br/>[RCKangaroo.cpp]"]
  node_dp_index[("DP index and storage<br/>[utils.cpp]")]
  node_key_result["Recovered key"]
end

node_user(("CLI user"))
node_gpu_device(("CUDA GPU"))
node_results_file["RESULTS.TXT<br/>[RESULTS.TXT]"]

node_user -->|"provides options"| node_cli
node_cli -->|"prepares curve"| node_ec
node_cli -->|"starts workers"| node_gpu_host
node_cli -->|"uses parameters"| node_runtime_defs
node_cli -.->|"loads or saves"| node_tame_files
node_gpu_host -->|"builds jump points"| node_ec
node_gpu_host -->|"copies data"| node_gpu_device
node_gpu_host -.->|"launches kernels"| node_kernel_code
node_gpu_host -.->|"dispatches turbo"| node_cubin_loader
node_cubin_loader -->|"launches cubin"| node_gpu_device
node_cli -->|"checks points"| node_dp_list
node_gpu_host -->|"returns points"| node_dp_list
node_dp_list -->|"indexes points"| node_dp_index
node_dp_list -->|"checks collisions"| node_ec
node_cli -->|"reports solution"| node_key_result
node_cli -->|"writes result"| node_results_file

click node_cli "https://github.com/retiredc/rckangaroo/blob/main/RCKangaroo.cpp"
click node_runtime_defs "https://github.com/retiredc/rckangaroo/blob/main/defs.h"
click node_ec "https://github.com/retiredc/rckangaroo/blob/main/Ec.cpp"
click node_gpu_host "https://github.com/retiredc/rckangaroo/blob/main/GpuKang.cpp"
click node_kernel_code "https://github.com/retiredc/rckangaroo/blob/main/RCGpuCore.cu"
click node_turbo_asm "https://github.com/retiredc/rckangaroo/blob/main/newKernelB.asm"
click node_cubin_loader "https://github.com/retiredc/rckangaroo/blob/main/CallCubin.cpp"
click node_dp_list "https://github.com/retiredc/rckangaroo/blob/main/RCKangaroo.cpp"
click node_dp_index "https://github.com/retiredc/rckangaroo/blob/main/utils.cpp"
click node_results_file "https://github.com/retiredc/rckangaroo/blob/main/RESULTS.TXT"

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_cli,node_runtime_defs,node_tame_files,node_user toneBlue
class node_ec toneAmber
class node_gpu_host,node_kernel_code,node_turbo_asm,node_cubin_loader toneMint
class node_dp_list,node_dp_index,node_key_result toneRose
class node_gpu_device toneIndigo
class node_results_file toneTeal
```

## Components

### Input and setup

- [CLI and solver](https://github.com/retiredc/rckangaroo/blob/main/RCKangaroo.cpp): `RCKangaroo.cpp`
- [Runtime parameters](https://github.com/retiredc/rckangaroo/blob/main/defs.h): `defs.h`
- **Tame point files**

### Curve arithmetic

- [Elliptic-curve math](https://github.com/retiredc/rckangaroo/blob/main/Ec.cpp): `Ec.cpp`

### GPU search

- [GPU kangaroo host](https://github.com/retiredc/rckangaroo/blob/main/GpuKang.cpp): `GpuKang.cpp`
- [CUDA kernels](https://github.com/retiredc/rckangaroo/blob/main/RCGpuCore.cu): `RCGpuCore.cu`
- [Turbo kernels](https://github.com/retiredc/rckangaroo/blob/main/newKernelB.asm): `newKernelB.asm`
- [Cubin dispatch](https://github.com/retiredc/rckangaroo/blob/main/CallCubin.cpp): `CallCubin.cpp`

### Collision and results

- [Distinguished points](https://github.com/retiredc/rckangaroo/blob/main/RCKangaroo.cpp): `RCKangaroo.cpp`
- [DP index and storage](https://github.com/retiredc/rckangaroo/blob/main/utils.cpp): `utils.cpp`
- **Recovered key**

### Other components

- **CLI user**
- **CUDA GPU**
- [RESULTS.TXT](https://github.com/retiredc/rckangaroo/blob/main/RESULTS.TXT): `RESULTS.TXT`

## Connections

- CLI user → CLI and solver: provides options (evidence: `README.md`)
- CLI and solver → Elliptic-curve math: prepares curve (evidence: `RCKangaroo.cpp`)
- CLI and solver → GPU kangaroo host: starts workers (evidence: `RCKangaroo.cpp`)
- CLI and solver → Runtime parameters: uses parameters (evidence: `RCKangaroo.cpp`)
- CLI and solver → Tame point files: loads or saves (evidence: `README.md`)
- GPU kangaroo host → Elliptic-curve math: builds jump points (evidence: `GpuKang.cpp`)
- GPU kangaroo host → CUDA GPU: copies data (evidence: `GpuKang.cpp`)
- GPU kangaroo host → CUDA kernels: launches kernels
- GPU kangaroo host → Cubin dispatch: dispatches turbo
- Cubin dispatch → CUDA GPU: launches cubin (evidence: `CallCubin.cpp`)
- CLI and solver → Distinguished points: checks points (evidence: `RCKangaroo.cpp`)
- GPU kangaroo host → Distinguished points: returns points (evidence: `GpuKang.cpp`)
- Distinguished points → DP index and storage: indexes points (evidence: `RCKangaroo.cpp`)
- Distinguished points → Elliptic-curve math: checks collisions (evidence: `RCKangaroo.cpp`)
- CLI and solver → Recovered key: reports solution (evidence: `README.md`)
- CLI and solver → RESULTS.TXT: writes result (evidence: `README.md`)
