From bce309b78db73fb6aae5399ef6ef2041c66d3d30 Mon Sep 17 00:00:00 2001
From: snider <snider@lt.hn>
Date: Tue, 13 Jan 2026 16:45:44 +0000
Subject: [PATCH] docs: Add miner suite documentation and release workflow

- Create miner/README.md documenting standalone C++ mining tools
- Update miner/core and miner/proxy READMEs with EUPL-1.2 license
- Add GitHub Actions workflow for multi-platform miner releases
- Add Makefile targets: build-miner, build-miner-core, build-miner-proxy
- Update main README with standalone miner usage instructions

The miner/ directory contains standalone CPU/GPU miner and stratum
proxy that can be used independently without the GUI. Pre-built
binaries will be published alongside Go releases.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .github/workflows/miner-release.yml | 251 ++++++++++++++++++++++++
 Makefile                            |  95 ++++++---
 README.md                           |  48 +++--
 miner/README.md                     | 289 ++++++++++++++++++++++++++++
 miner/core/README.md                | 210 +++++++++++++++++---
 miner/proxy/README.md               | 267 +++++++++++++++++--------
 6 files changed, 1010 insertions(+), 150 deletions(-)
 create mode 100644 .github/workflows/miner-release.yml
 create mode 100644 miner/README.md

diff --git a/.github/workflows/miner-release.yml b/.github/workflows/miner-release.yml
new file mode 100644
index 0000000..f6e4830
--- /dev/null
+++ b/.github/workflows/miner-release.yml
@@ -0,0 +1,251 @@
+name: Miner Release
+
+on:
+  push:
+    tags:
+      - 'miner-v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version tag (e.g., 0.1.0)'
+        required: true
+        default: '0.1.0'
+
+env:
+  BUILD_TYPE: Release
+
+jobs:
+  build-linux:
+    name: Linux ${{ matrix.arch }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            cmake_arch: x86_64
+          - arch: arm64
+            cmake_arch: aarch64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            cmake \
+            libuv1-dev \
+            libssl-dev \
+            libhwloc-dev \
+            git
+
+      - name: Build miner core
+        working-directory: miner/core
+        run: |
+          mkdir -p build && cd build
+          cmake .. \
+            -DCMAKE_BUILD_TYPE=$BUILD_TYPE \
+            -DWITH_OPENCL=OFF \
+            -DWITH_CUDA=OFF
+          cmake --build . --config $BUILD_TYPE -j$(nproc)
+
+      - name: Build miner proxy
+        working-directory: miner/proxy
+        run: |
+          mkdir -p build && cd build
+          cmake .. -DCMAKE_BUILD_TYPE=$BUILD_TYPE
+          cmake --build . --config $BUILD_TYPE -j$(nproc)
+
+      - name: Package binaries
+        run: |
+          mkdir -p dist
+          cp miner/core/build/miner dist/
+          cp miner/proxy/build/miner-proxy dist/
+          chmod +x dist/*
+          cd dist
+          tar -czvf ../miner-linux-${{ matrix.arch }}.tar.gz *
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: miner-linux-${{ matrix.arch }}
+          path: miner-linux-${{ matrix.arch }}.tar.gz
+
+  build-macos:
+    name: macOS ${{ matrix.arch }}
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            cmake_osx_arch: x86_64
+          - arch: arm64
+            cmake_osx_arch: arm64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install dependencies
+        run: |
+          brew install cmake libuv openssl hwloc
+
+      - name: Build miner core
+        working-directory: miner/core
+        env:
+          OSX_ARCH: ${{ matrix.cmake_osx_arch }}
+        run: |
+          mkdir -p build && cd build
+          cmake .. \
+            -DCMAKE_BUILD_TYPE=$BUILD_TYPE \
+            -DCMAKE_OSX_ARCHITECTURES=$OSX_ARCH \
+            -DWITH_OPENCL=OFF \
+            -DWITH_CUDA=OFF \
+            -DOPENSSL_ROOT_DIR=$(brew --prefix openssl)
+          cmake --build . --config $BUILD_TYPE -j$(sysctl -n hw.ncpu)
+
+      - name: Build miner proxy
+        working-directory: miner/proxy
+        env:
+          OSX_ARCH: ${{ matrix.cmake_osx_arch }}
+        run: |
+          mkdir -p build && cd build
+          cmake .. \
+            -DCMAKE_BUILD_TYPE=$BUILD_TYPE \
+            -DCMAKE_OSX_ARCHITECTURES=$OSX_ARCH \
+            -DOPENSSL_ROOT_DIR=$(brew --prefix openssl)
+          cmake --build . --config $BUILD_TYPE -j$(sysctl -n hw.ncpu)
+
+      - name: Package binaries
+        run: |
+          mkdir -p dist
+          cp miner/core/build/miner dist/
+          cp miner/proxy/build/miner-proxy dist/
+          chmod +x dist/*
+          cd dist
+          tar -czvf ../miner-macos-${{ matrix.arch }}.tar.gz *
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: miner-macos-${{ matrix.arch }}
+          path: miner-macos-${{ matrix.arch }}.tar.gz
+
+  build-windows:
+    name: Windows x64
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup MSVC
+        uses: microsoft/setup-msbuild@v2
+
+      - name: Install dependencies
+        run: |
+          vcpkg install libuv:x64-windows openssl:x64-windows
+
+      - name: Build miner core
+        working-directory: miner/core
+        run: |
+          mkdir build
+          cd build
+          cmake .. `
+            -DCMAKE_BUILD_TYPE=$env:BUILD_TYPE `
+            -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake" `
+            -DWITH_OPENCL=OFF `
+            -DWITH_CUDA=OFF
+          cmake --build . --config $env:BUILD_TYPE
+
+      - name: Build miner proxy
+        working-directory: miner/proxy
+        run: |
+          mkdir build
+          cd build
+          cmake .. `
+            -DCMAKE_BUILD_TYPE=$env:BUILD_TYPE `
+            -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake"
+          cmake --build . --config $env:BUILD_TYPE
+
+      - name: Package binaries
+        run: |
+          mkdir dist
+          Copy-Item miner/core/build/$env:BUILD_TYPE/miner.exe dist/
+          Copy-Item miner/proxy/build/$env:BUILD_TYPE/miner-proxy.exe dist/
+          Compress-Archive -Path dist/* -DestinationPath miner-windows-x64.zip
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: miner-windows-x64
+          path: miner-windows-x64.zip
+
+  release:
+    name: Create Release
+    needs: [build-linux, build-macos, build-windows]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: List artifacts
+        run: ls -la artifacts/*/
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          draft: false
+          prerelease: false
+          files: |
+            artifacts/miner-linux-x64/miner-linux-x64.tar.gz
+            artifacts/miner-linux-arm64/miner-linux-arm64.tar.gz
+            artifacts/miner-macos-x64/miner-macos-x64.tar.gz
+            artifacts/miner-macos-arm64/miner-macos-arm64.tar.gz
+            artifacts/miner-windows-x64/miner-windows-x64.zip
+          body: |
+            ## Miner Suite
+
+            ### Downloads
+
+            | Platform | Architecture | Download |
+            |----------|--------------|----------|
+            | Linux | x64 | `miner-linux-x64.tar.gz` |
+            | Linux | ARM64 | `miner-linux-arm64.tar.gz` |
+            | macOS | Intel | `miner-macos-x64.tar.gz` |
+            | macOS | Apple Silicon | `miner-macos-arm64.tar.gz` |
+            | Windows | x64 | `miner-windows-x64.zip` |
+
+            ### Included Binaries
+
+            - `miner` - CPU/GPU cryptocurrency miner
+            - `miner-proxy` - Stratum proxy for mining farms
+
+            ### Quick Start
+
+            ```bash
+            # Extract
+            tar -xzf miner-linux-x64.tar.gz
+
+            # Run miner
+            ./miner -o pool.example.com:3333 -u YOUR_WALLET -p x
+
+            # Run proxy
+            ./miner-proxy -o pool.example.com:3333 -u YOUR_WALLET -b 0.0.0.0:3333
+            ```
+
+            See [miner/README.md](miner/README.md) for full documentation.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/Makefile b/Makefile
index 84a689b..449840e 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all build test clean install run demo help lint fmt vet docs install-swag dev package e2e e2e-ui e2e-api test-cpp test-cpp-core test-cpp-proxy build-cpp-tests
+.PHONY: all build test clean install run demo help lint fmt vet docs install-swag dev package e2e e2e-ui e2e-api test-cpp test-cpp-core test-cpp-proxy build-cpp-tests build-miner build-miner-core build-miner-proxy build-miner-all
 
 # Variables
 BINARY_NAME=miner-ctrl
@@ -66,6 +66,34 @@ build-cpp-tests-proxy:
 		$(CMAKE) -DBUILD_TESTS=ON .. && \
 		$(CMAKE) --build . --target unit_tests integration_tests --parallel
 
+# Build miner binaries (release builds)
+build-miner: build-miner-core build-miner-proxy
+	@echo "Miner binaries built successfully"
+
+# Build miner core (CPU/GPU miner)
+build-miner-core:
+	@echo "Building miner core..."
+	@mkdir -p $(MINER_CORE_BUILD_DIR)
+	@cd $(MINER_CORE_BUILD_DIR) && \
+		$(CMAKE) -DCMAKE_BUILD_TYPE=Release .. && \
+		$(CMAKE) --build . --config Release --parallel
+
+# Build miner proxy
+build-miner-proxy:
+	@echo "Building miner proxy..."
+	@mkdir -p $(MINER_PROXY_BUILD_DIR)
+	@cd $(MINER_PROXY_BUILD_DIR) && \
+		$(CMAKE) -DCMAKE_BUILD_TYPE=Release .. && \
+		$(CMAKE) --build . --config Release --parallel
+
+# Build all miner components and package
+build-miner-all: build-miner
+	@echo "Packaging miner binaries..."
+	@mkdir -p dist/miner
+	@cp $(MINER_CORE_BUILD_DIR)/miner dist/miner/ 2>/dev/null || true
+	@cp $(MINER_PROXY_BUILD_DIR)/miner-proxy dist/miner/ 2>/dev/null || true
+	@echo "Miner binaries available in dist/miner/"
+
 # Run C++ tests (builds first if needed)
 test-cpp: test-cpp-proxy
 	@echo "All C++ tests completed"
@@ -177,30 +205,41 @@ e2e-api: build
 # Help
 help:
 	@echo "Available targets:"
-	@echo "  all         - Run tests and build"
-	@echo "  build       - Build the CLI binary"
-	@echo "  build-all   - Build for multiple platforms"
-	@echo "  install     - Install the binary"
-	@echo "  test        - Run all tests (Go + C++)"
-	@echo "  test-go     - Run Go tests only"
-	@echo "  test-cpp    - Run C++ tests (core + proxy)"
-	@echo "  test-cpp-core   - Run miner/core C++ tests"
-	@echo "  test-cpp-proxy  - Run miner/proxy C++ tests"
-	@echo "  build-cpp-tests - Build all C++ tests"
-	@echo "  coverage    - Run tests with coverage report"
-	@echo "  demo        - Run the demo"
-	@echo "  run         - Build and run the CLI"
-	@echo "  clean       - Clean build artifacts (including C++ builds)"
-	@echo "  fmt         - Format code"
-	@echo "  vet         - Run go vet"
-	@echo "  lint        - Run linters"
-	@echo "  tidy        - Tidy dependencies"
-	@echo "  deps        - Download dependencies"
-	@echo "  docs        - Generate Swagger documentation"
-	@echo "  install-swag- Install the swag CLI"
-	@echo "  package     - Create local distribution packages using GoReleaser"
-	@echo "  dev         - Start the development server with docs and build"
-	@echo "  e2e         - Run E2E tests with Playwright"
-	@echo "  e2e-ui      - Open Playwright UI for interactive testing"
-	@echo "  e2e-api     - Run API-only E2E tests"
-	@echo "  help        - Show this help message"
+	@echo ""
+	@echo "Go Application:"
+	@echo "  all           - Run tests and build"
+	@echo "  build         - Build the CLI binary"
+	@echo "  build-all     - Build for multiple platforms"
+	@echo "  install       - Install the binary"
+	@echo "  run           - Build and run the CLI"
+	@echo "  dev           - Start the development server with docs and build"
+	@echo ""
+	@echo "Miner (C++ Binaries):"
+	@echo "  build-miner       - Build miner core and proxy"
+	@echo "  build-miner-core  - Build miner core only"
+	@echo "  build-miner-proxy - Build miner proxy only"
+	@echo "  build-miner-all   - Build and package all miner binaries"
+	@echo ""
+	@echo "Testing:"
+	@echo "  test          - Run all tests (Go + C++)"
+	@echo "  test-go       - Run Go tests only"
+	@echo "  test-cpp      - Run C++ tests (proxy)"
+	@echo "  test-cpp-core - Run miner/core C++ tests"
+	@echo "  test-cpp-proxy- Run miner/proxy C++ tests"
+	@echo "  coverage      - Run tests with coverage report"
+	@echo "  e2e           - Run E2E tests with Playwright"
+	@echo "  e2e-ui        - Open Playwright UI for interactive testing"
+	@echo "  e2e-api       - Run API-only E2E tests"
+	@echo ""
+	@echo "Code Quality:"
+	@echo "  fmt           - Format code"
+	@echo "  vet           - Run go vet"
+	@echo "  lint          - Run linters"
+	@echo "  tidy          - Tidy dependencies"
+	@echo ""
+	@echo "Other:"
+	@echo "  clean         - Clean all build artifacts"
+	@echo "  deps          - Download dependencies"
+	@echo "  docs          - Generate Swagger documentation"
+	@echo "  package       - Create local distribution packages"
+	@echo "  help          - Show this help message"
diff --git a/README.md b/README.md
index c898f27..2294c28 100644
--- a/README.md
+++ b/README.md
@@ -108,25 +108,43 @@ wails3 build
 ```
 Mining/
 ├── cmd/
-│   ├── mining/              # CLI application
+│   ├── mining/              # CLI application (miner-ctrl)
 │   └── desktop/             # Wails desktop app
 ├── pkg/mining/              # Core Go package
 │   ├── mining.go            # Interfaces and types
 │   ├── manager.go           # Miner lifecycle management
 │   ├── service.go           # RESTful API (Gin)
-│   ├── xmrig.go             # XMRig implementation
 │   └── profile_manager.go   # Profile persistence
-├── miner/core/              # Modified XMRig with algorithm support
-│   └── src/
-│       ├── backend/opencl/  # OpenCL GPU kernels
-│       ├── backend/cuda/    # CUDA GPU kernels
-│       └── crypto/          # Algorithm implementations
+├── miner/                   # Standalone C++ mining tools
+│   ├── core/                # CPU/GPU miner binary
+│   ├── proxy/               # Stratum proxy for farms
+│   ├── cuda/                # CUDA plugin for NVIDIA
+│   └── README.md            # Miner documentation
 └── ui/                      # Angular 20+ web dashboard
     └── src/app/
         ├── components/      # Reusable UI components
         └── pages/           # Route pages
 ```
 
+## Standalone Miner Tools
+
+The `miner/` directory contains standalone C++ mining programs that can be used independently without the GUI:
+
+```bash
+# Build miner binaries
+make build-miner
+
+# Or build individually
+make build-miner-core   # CPU/GPU miner
+make build-miner-proxy  # Stratum proxy
+
+# Run directly
+./miner/core/build/miner -o pool.example.com:3333 -u WALLET -p x
+./miner/proxy/build/miner-proxy -o pool.example.com:3333 -b 0.0.0.0:3333
+```
+
+Pre-built binaries are available from [Releases](https://github.com/letheanVPN/Mining/releases). See [miner/README.md](miner/README.md) for full documentation.
+
 ## API Reference
 
 Base path: `/api/v1/mining`
@@ -158,26 +176,24 @@ Swagger UI: `http://localhost:9090/api/v1/mining/swagger/index.html`
 ### Build Commands
 
 ```bash
-# Backend
+# Go Backend
 make build              # Build CLI binary
-make test               # Run tests with coverage
+make test               # Run all tests (Go + C++)
 make dev                # Start dev server on :9090
 
+# Miner (C++ Binaries)
+make build-miner        # Build miner and proxy
+make build-miner-all    # Build and package to dist/miner/
+
 # Frontend
 cd ui
 npm install
 npm run build           # Build web component
-npm test                # Run unit tests (36 specs)
+npm test                # Run unit tests
 
 # Desktop
 cd cmd/desktop/mining-desktop
 wails3 build            # Build native app
-
-# Miner Core (GPU support)
-cd miner/core
-mkdir build && cd build
-cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
-make -j$(nproc)
 ```
 
 ## Configuration
diff --git a/miner/README.md b/miner/README.md
new file mode 100644
index 0000000..fe52ece
--- /dev/null
+++ b/miner/README.md
@@ -0,0 +1,289 @@
+# Lethean Miner Suite
+
+[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](https://opensource.org/license/eupl-1-2)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows%20%7C%20freebsd-lightgrey.svg)](https://github.com/letheanVPN/Mining/releases)
+
+High-performance cryptocurrency mining tools. These standalone C++ programs can be used independently or managed through the Mining Platform GUI.
+
+## Components
+
+| Component | Description | Binary |
+|-----------|-------------|--------|
+| [**core**](core/) | CPU/GPU miner with full algorithm support | `miner` |
+| [**proxy**](proxy/) | Stratum proxy for mining farms (100K+ connections) | `miner-proxy` |
+| [**cuda**](cuda/) | CUDA plugin for NVIDIA GPUs | `libminer-cuda.so` |
+| [**config**](config/) | Configuration generator tool | `miner-config` |
+| [**workers**](workers/) | Worker management utilities | `miner-workers` |
+| [**heatmap**](heatmap/) | Hardware temperature visualization | `miner-heatmap` |
+
+## Supported Algorithms
+
+### CPU Mining
+| Algorithm | Coins |
+|-----------|-------|
+| RandomX | Monero (XMR), Lethean (LTHN), Wownero (WOW) |
+| CryptoNight | Various CN variants |
+| GhostRider | Raptoreum (RTM) |
+| Argon2 | Chukwa, Ninja |
+
+### GPU Mining (OpenCL/CUDA)
+| Algorithm | Coins |
+|-----------|-------|
+| RandomX | Monero, Lethean |
+| KawPow | Ravencoin (RVN), Neoxa |
+| ETChash | Ethereum Classic (ETC) |
+| ProgPowZ | Zano (ZANO) |
+| Blake3 | Decred (DCR) |
+
+## Quick Start
+
+### Download Pre-built Binaries
+
+Download from [Releases](https://github.com/letheanVPN/Mining/releases):
+- `miner-linux-x64.tar.gz` - Linux x86_64
+- `miner-linux-arm64.tar.gz` - Linux ARM64
+- `miner-macos-x64.tar.gz` - macOS Intel
+- `miner-macos-arm64.tar.gz` - macOS Apple Silicon
+- `miner-windows-x64.zip` - Windows x64
+
+### Run the Miner
+
+```bash
+# Basic CPU mining
+./miner -o pool.example.com:3333 -u YOUR_WALLET -p x
+
+# With config file (recommended)
+./miner -c config.json
+
+# CPU + GPU mining
+./miner -c config.json --opencl --cuda
+
+# Show help
+./miner --help
+```
+
+### Run the Proxy
+
+```bash
+# Start proxy for mining farm
+./miner-proxy -o pool.example.com:3333 -u YOUR_WALLET -b 0.0.0.0:3333
+
+# With config file
+./miner-proxy -c proxy-config.json
+```
+
+## Building from Source
+
+### Prerequisites
+
+**All Platforms:**
+- CMake 3.10+
+- C++11 compatible compiler
+- libuv
+- OpenSSL (for TLS support)
+
+**Linux:**
+```bash
+sudo apt-get install build-essential cmake libuv1-dev libssl-dev libhwloc-dev
+```
+
+**macOS:**
+```bash
+brew install cmake libuv openssl hwloc
+```
+
+**Windows:**
+- Visual Studio 2019+ with C++ workload
+- vcpkg for dependencies
+
+### Build Miner Core
+
+```bash
+cd core
+mkdir build && cd build
+
+# Standard build
+cmake ..
+cmake --build . --config Release -j$(nproc)
+
+# With GPU support
+cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
+
+# Static build (portable)
+cmake .. -DBUILD_STATIC=ON
+
+# Minimal build (RandomX only)
+cmake .. -DWITH_ARGON2=OFF -DWITH_KAWPOW=OFF -DWITH_GHOSTRIDER=OFF
+```
+
+### Build Proxy
+
+```bash
+cd proxy
+mkdir build && cd build
+cmake ..
+cmake --build . --config Release -j$(nproc)
+```
+
+### Build All Components
+
+From the repository root:
+
+```bash
+make build-miner          # Build miner core
+make build-miner-proxy    # Build proxy
+make build-miner-all      # Build all components
+```
+
+## Configuration
+
+### Miner Config (config.json)
+
+```json
+{
+    "autosave": true,
+    "cpu": true,
+    "opencl": false,
+    "cuda": false,
+    "pools": [
+        {
+            "url": "stratum+tcp://pool.example.com:3333",
+            "user": "YOUR_WALLET",
+            "pass": "x",
+            "keepalive": true,
+            "tls": false
+        }
+    ],
+    "http": {
+        "enabled": true,
+        "host": "127.0.0.1",
+        "port": 8080,
+        "access-token": null
+    }
+}
+```
+
+### Proxy Config (proxy-config.json)
+
+```json
+{
+    "mode": "nicehash",
+    "pools": [
+        {
+            "url": "stratum+tcp://pool.example.com:3333",
+            "user": "YOUR_WALLET",
+            "pass": "x"
+        }
+    ],
+    "bind": [
+        {
+            "host": "0.0.0.0",
+            "port": 3333
+        }
+    ],
+    "http": {
+        "enabled": true,
+        "host": "127.0.0.1",
+        "port": 8081
+    }
+}
+```
+
+## HTTP API
+
+Both miner and proxy expose HTTP APIs for monitoring and control.
+
+### Miner API (default: http://127.0.0.1:8080)
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /1/summary` | Mining statistics |
+| `GET /1/threads` | Per-thread hashrates |
+| `GET /1/config` | Current configuration |
+| `PUT /1/config` | Update configuration |
+
+### Proxy API (default: http://127.0.0.1:8081)
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /1/summary` | Proxy statistics |
+| `GET /1/workers` | Connected workers |
+| `GET /1/config` | Current configuration |
+
+## Performance Tuning
+
+### CPU Mining
+
+```bash
+# Enable huge pages (Linux)
+sudo sysctl -w vm.nr_hugepages=1280
+
+# Or permanent (add to /etc/sysctl.conf)
+echo "vm.nr_hugepages=1280" | sudo tee -a /etc/sysctl.conf
+
+# Enable 1GB pages (better performance)
+sudo ./scripts/enable_1gb_pages.sh
+```
+
+### GPU Mining
+
+```bash
+# AMD GPUs - increase virtual memory
+# Add to /etc/security/limits.conf:
+# * soft memlock unlimited
+# * hard memlock unlimited
+
+# NVIDIA GPUs - optimize power
+nvidia-smi -pl 120  # Set power limit
+```
+
+## Testing
+
+```bash
+# Run miner tests
+cd core/build
+ctest --output-on-failure
+
+# Run proxy tests
+cd proxy/build
+./tests/unit_tests
+./tests/integration_tests
+```
+
+## Directory Structure
+
+```
+miner/
+├── core/               # Main miner (CPU/GPU)
+│   ├── src/
+│   │   ├── backend/    # CPU, OpenCL, CUDA backends
+│   │   ├── crypto/     # Algorithm implementations
+│   │   ├── base/       # Network, I/O, utilities
+│   │   └── core/       # Configuration, controller
+│   ├── scripts/        # Build and setup scripts
+│   └── CMakeLists.txt
+├── proxy/              # Stratum proxy
+│   ├── src/
+│   │   ├── proxy/      # Proxy core (splitters, events)
+│   │   └── base/       # Shared base code
+│   ├── tests/          # Unit and integration tests
+│   └── CMakeLists.txt
+├── cuda/               # CUDA plugin
+├── config/             # Config generator
+├── workers/            # Worker utilities
+├── heatmap/            # Temperature visualization
+├── deps/               # Dependency build scripts
+└── README.md           # This file
+```
+
+## License
+
+Copyright (c) 2025 Lethean <https://lethean.io>
+
+Licensed under the European Union Public License 1.2 (EUPL-1.2).
+See [LICENSE](../LICENSE) for details.
+
+## Related Projects
+
+- [Mining Platform](../) - GUI management platform
+- [Lethean](https://lethean.io) - Lethean Network
diff --git a/miner/core/README.md b/miner/core/README.md
index 7b6e66c..51ba528 100644
--- a/miner/core/README.md
+++ b/miner/core/README.md
@@ -1,38 +1,192 @@
-# XMRig
+# Miner
 
-[![Github All Releases](https://img.shields.io/github/downloads/xmrig/xmrig/total.svg)](https://github.com/xmrig/xmrig/releases)
-[![GitHub release](https://img.shields.io/github/release/xmrig/xmrig/all.svg)](https://github.com/xmrig/xmrig/releases)
-[![GitHub Release Date](https://img.shields.io/github/release-date/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/releases)
-[![GitHub license](https://img.shields.io/github/license/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/blob/master/LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/network)
+High-performance, cross-platform CPU/GPU cryptocurrency miner supporting RandomX, KawPow, CryptoNight, GhostRider, ETChash, ProgPowZ, and Blake3 algorithms.
 
-XMRig is a high performance, open source, cross platform RandomX, KawPow, CryptoNight and [GhostRider](https://github.com/xmrig/xmrig/tree/master/src/crypto/ghostrider#readme) unified CPU/GPU miner and [RandomX benchmark](https://xmrig.com/benchmark). Official binaries are available for Windows, Linux, macOS and FreeBSD.
+## Features
 
-## Mining backends
+### Mining Backends
 - **CPU** (x86/x64/ARMv7/ARMv8/RISC-V)
-- **OpenCL** for AMD GPUs.
-- **CUDA** for NVIDIA GPUs via external [CUDA plugin](https://github.com/xmrig/xmrig-cuda).
+- **OpenCL** for AMD GPUs
+- **CUDA** for NVIDIA GPUs via external [CUDA plugin](../cuda/)
 
-## Download
-* **[Binary releases](https://github.com/xmrig/xmrig/releases)**
-* **[Build from source](https://xmrig.com/docs/miner/build)**
+### Supported Algorithms
 
-## Usage
-The preferred way to configure the miner is the [JSON config file](https://xmrig.com/docs/miner/config) as it is more flexible and human friendly. The [command line interface](https://xmrig.com/docs/miner/command-line-options) does not cover all features, such as mining profiles for different algorithms. Important options can be changed during runtime without miner restart by editing the config file or executing [API](https://xmrig.com/docs/miner/api) calls.
+| Algorithm | Variants | CPU | GPU |
+|-----------|----------|-----|-----|
+| RandomX | rx/0, rx/wow, rx/arq, rx/graft, rx/sfx, rx/keva | Yes | Yes |
+| CryptoNight | cn/0-2, cn-lite, cn-heavy, cn-pico | Yes | Yes |
+| GhostRider | gr | Yes | No |
+| Argon2 | chukwa, chukwa2, ninja | Yes | No |
+| KawPow | kawpow | No | Yes |
+| ETChash | etchash, ethash | No | Yes |
+| ProgPowZ | progpowz | No | Yes |
+| Blake3 | blake3 | Yes | Yes |
 
-* **[Wizard](https://xmrig.com/wizard)** helps you create initial configuration for the miner.
-* **[Workers](http://workers.xmrig.info)** helps manage your miners via HTTP API.
+## Quick Start
 
-## Donations
-* Default donation 1% (1 minute in 100 minutes) can be increased via option `donate-level` or disabled in source code.
-* XMR: `48edfHu7V9Z84YzzMa6fUueoELZ9ZRXq9VetWzYGzKt52XU5xvqgzYnDK9URnRoJMk1j8nLwEVsaSWJ4fhdUyZijBGUicoD`
+### Download
 
-## Developers
-* **[xmrig](https://github.com/xmrig)**
-* **[sech1](https://github.com/SChernykh)**
+Pre-built binaries are available from [Releases](https://github.com/letheanVPN/Mining/releases).
 
-## Contacts
-* support@xmrig.com
-* [reddit](https://www.reddit.com/user/XMRig/)
-* [twitter](https://twitter.com/xmrig_dev)
+### Usage
+
+```bash
+# Basic CPU mining to a pool
+./miner -o pool.example.com:3333 -u YOUR_WALLET -p x
+
+# With JSON config (recommended)
+./miner -c config.json
+
+# Enable GPU mining
+./miner -c config.json --opencl --cuda
+
+# Benchmark mode
+./miner --bench=1M
+
+# Show all options
+./miner --help
+```
+
+### Configuration
+
+The recommended way to configure the miner is via JSON config file:
+
+```json
+{
+    "autosave": true,
+    "cpu": true,
+    "opencl": false,
+    "cuda": false,
+    "pools": [
+        {
+            "url": "stratum+tcp://pool.example.com:3333",
+            "user": "YOUR_WALLET",
+            "pass": "x",
+            "keepalive": true
+        }
+    ]
+}
+```
+
+## Building from Source
+
+### Dependencies
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get install git build-essential cmake libuv1-dev libssl-dev libhwloc-dev
+```
+
+**Linux (Fedora/RHEL):**
+```bash
+sudo dnf install git cmake gcc gcc-c++ libuv-devel openssl-devel hwloc-devel
+```
+
+**macOS:**
+```bash
+brew install cmake libuv openssl hwloc
+```
+
+**Windows:**
+- Visual Studio 2019 or later
+- CMake 3.10+
+- vcpkg for dependencies
+
+### Build Commands
+
+```bash
+mkdir build && cd build
+
+# Standard build
+cmake ..
+cmake --build . --config Release
+
+# With GPU support
+cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
+
+# Static binary
+cmake .. -DBUILD_STATIC=ON
+
+# Debug build
+cmake .. -DCMAKE_BUILD_TYPE=Debug -DWITH_DEBUG_LOG=ON
+
+# Minimal build (reduce binary size)
+cmake .. -DWITH_KAWPOW=OFF -DWITH_GHOSTRIDER=OFF -DWITH_ARGON2=OFF
+```
+
+### CMake Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `WITH_HWLOC` | ON | Hardware topology support |
+| `WITH_RANDOMX` | ON | RandomX algorithms |
+| `WITH_ARGON2` | ON | Argon2 algorithms |
+| `WITH_KAWPOW` | ON | KawPow (GPU only) |
+| `WITH_ETCHASH` | ON | ETChash/Ethash (GPU only) |
+| `WITH_PROGPOWZ` | ON | ProgPowZ (GPU only) |
+| `WITH_BLAKE3DCR` | ON | Blake3 for Decred |
+| `WITH_GHOSTRIDER` | ON | GhostRider algorithm |
+| `WITH_OPENCL` | ON | AMD GPU support |
+| `WITH_CUDA` | ON | NVIDIA GPU support |
+| `WITH_HTTP` | ON | HTTP API |
+| `WITH_TLS` | ON | SSL/TLS support |
+| `WITH_ASM` | ON | Assembly optimizations |
+| `WITH_MSR` | ON | MSR mod for CPU tuning |
+| `BUILD_STATIC` | OFF | Static binary |
+| `BUILD_TESTS` | OFF | Build unit tests |
+
+## HTTP API
+
+When built with `-DWITH_HTTP=ON`, the miner exposes a REST API:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/1/summary` | GET | Mining statistics |
+| `/1/threads` | GET | Per-thread details |
+| `/1/config` | GET | Current configuration |
+| `/1/config` | PUT | Update configuration |
+
+Example:
+```bash
+curl http://127.0.0.1:8080/1/summary
+```
+
+## Performance Optimization
+
+### Huge Pages (Linux)
+
+```bash
+# Temporary
+sudo sysctl -w vm.nr_hugepages=1280
+
+# Permanent
+echo "vm.nr_hugepages=1280" | sudo tee -a /etc/sysctl.conf
+
+# 1GB pages (best performance)
+sudo ./scripts/enable_1gb_pages.sh
+```
+
+### MSR Mod (Intel/AMD CPUs)
+
+The miner can automatically apply MSR tweaks for better RandomX performance. Requires root/admin privileges.
+
+```bash
+sudo ./miner -c config.json
+```
+
+## Testing
+
+```bash
+# Build with tests
+cmake .. -DBUILD_TESTS=ON
+cmake --build .
+
+# Run tests
+ctest --output-on-failure
+```
+
+## License
+
+Copyright (c) 2025 Lethean <https://lethean.io>
+
+Licensed under the European Union Public License 1.2 (EUPL-1.2).
diff --git a/miner/proxy/README.md b/miner/proxy/README.md
index f17b6af..6f45ae4 100644
--- a/miner/proxy/README.md
+++ b/miner/proxy/README.md
@@ -1,105 +1,216 @@
-# XMRig Proxy
-[![Github All Releases](https://img.shields.io/github/downloads/xmrig/xmrig-proxy/total.svg)](https://github.com/xmrig/xmrig-proxy/releases)
-[![GitHub release](https://img.shields.io/github/release/xmrig/xmrig-proxy/all.svg)](https://github.com/xmrig/xmrig-proxy/releases)
-[![GitHub Release Date](https://img.shields.io/github/release-date-pre/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/releases)
-[![GitHub license](https://img.shields.io/github/license/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/blob/master/LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/network)
+# Miner Proxy
 
-This is an extremely high-performance proxy for the CryptoNote stratum protocol (including Monero and others).
-It can efficiently manage over 100K connections on an inexpensive, low-memory virtual machine (with just 1024 MB of RAM).
-The proxy significantly reduces the number of connections to the pool, decreasing 100,000 workers down to just 391 on the pool side.
-The codebase is shared with the [XMRig](https://github.com/xmrig/xmrig) miner.
+High-performance stratum protocol proxy for cryptocurrency mining farms. Efficiently manages 100K+ miner connections while maintaining minimal pool-side connections through nonce splitting.
 
-## Compatibility
-Compatible with any pool and any miner that supports NiceHash.
+## Features
 
-## Why?
-This proxy is designed to handle donation traffic from XMRig. No other solution works well with high connection and disconnection rates.
+- Handle 100K+ concurrent miner connections
+- Reduce pool connections (100,000 miners → ~400 pool connections)
+- NiceHash compatibility mode
+- TLS/SSL support for secure connections
+- HTTP API for monitoring
+- Low memory footprint (~1GB RAM for 100K connections)
+
+## Quick Start
+
+### Download
+
+Pre-built binaries are available from [Releases](https://github.com/letheanVPN/Mining/releases).
+
+### Usage
+
+```bash
+# Basic usage
+./miner-proxy -o pool.example.com:3333 -u YOUR_WALLET -b 0.0.0.0:3333
+
+# With config file (recommended)
+./miner-proxy -c config.json
+
+# Test configuration
+./miner-proxy --dry-run -c config.json
+
+# Show all options
+./miner-proxy --help
+```
+
+### Command Line Options
 
-## Download
-* Binary releases: https://github.com/xmrig/xmrig-proxy/releases
-* Git tree: https://github.com/xmrig/xmrig-proxy.git
-  * Clone with `git clone https://github.com/xmrig/xmrig-proxy.git` :hammer: [Build instructions](https://xmrig.com/docs/proxy).
-  
-## Usage
-:boom: If you are using Linux and need to manage over **1000 connections**, you must [increase the limits on open files](https://github.com/xmrig/xmrig-proxy/wiki/Ubuntu-setup).
-  
-### Options
 ```
 Network:
   -o, --url=URL                 URL of mining server
-  -a, --algo=ALGO               mining algorithm https://xmrig.com/docs/algorithms
-      --coin=COIN               specify coin instead of algorithm
+  -a, --algo=ALGO               mining algorithm
   -u, --user=USERNAME           username for mining server
   -p, --pass=PASSWORD           password for mining server
-  -O, --userpass=U:P            username:password pair for mining server
-  -x, --proxy=HOST:PORT         connect through a SOCKS5 proxy
-  -k, --keepalive               send keepalived packet for prevent timeout (needs pool support)
-      --rig-id=ID               rig identifier for pool-side statistics (needs pool support)
-      --tls                     enable SSL/TLS support (needs pool support)
-      --tls-fingerprint=HEX     pool TLS certificate fingerprint for strict certificate pinning
-      --dns-ipv6                prefer IPv6 records from DNS responses
-      --dns-ttl=N               N seconds (default: 30) TTL for internal DNS cache
-      --daemon                  use daemon RPC instead of pool for solo mining
-      --daemon-zmq-port         daemon's zmq-pub port number (only use it if daemon has it enabled)
-      --daemon-poll-interval=N  daemon poll interval in milliseconds (default: 1000)
-      --daemon-job-timeout=N    daemon job timeout in milliseconds (default: 15000)
-      --self-select=URL         self-select block templates from URL
-      --submit-to-origin        also submit solution back to self-select URL
-  -r, --retries=N               number of times to retry before switch to backup server (default: 5)
-  -R, --retry-pause=N           time to pause between retries (default: 5)
-      --user-agent              set custom user-agent string for pool
-      --donate-level=N          donate level, default 0%%
+  -k, --keepalive               send keepalive packets
+      --tls                     enable SSL/TLS support
 
-Options:
-  -b, --bind=ADDR               bind to specified address, example "0.0.0.0:3333"
-  -m, --mode=MODE               proxy mode, nicehash (default) or simple
-      --custom-diff=N           override pool diff
-      --custom-diff-stats       calculate stats using custom diff shares instead of pool shares
-      --reuse-timeout=N         timeout in seconds for reuse pool connections in simple mode
-      --no-workers              disable per worker statistics
-      --access-password=P       set password to restrict connections to the proxy
-      --no-algo-ext             disable "algo" protocol extension
+Proxy:
+  -b, --bind=ADDR               bind to specified address (e.g., "0.0.0.0:3333")
+  -m, --mode=MODE               proxy mode: nicehash (default) or simple
+      --custom-diff=N           override pool difficulty
+      --access-password=P       password to restrict proxy access
 
 API:
-      --api-worker-id=ID        custom worker-id for API
-      --api-id=ID               custom instance ID for API
       --http-host=HOST          bind host for HTTP API (default: 127.0.0.1)
       --http-port=N             bind port for HTTP API
       --http-access-token=T     access token for HTTP API
-      --http-no-restricted      enable full remote access to HTTP API (only if access token set)
 
 TLS:
-      --tls-bind=ADDR           bind to specified address with enabled TLS
-      --tls-gen=HOSTNAME        generate TLS certificate for specific hostname
-      --tls-cert=FILE           load TLS certificate chain from a file in the PEM format
-      --tls-cert-key=FILE       load TLS certificate private key from a file in the PEM format
-      --tls-dhparam=FILE        load DH parameters for DHE ciphers from a file in the PEM format
-      --tls-protocols=N         enable specified TLS protocols, example: "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"
-      --tls-ciphers=S           set list of available ciphers (TLSv1.2 and below)
-      --tls-ciphersuites=S      set list of available TLSv1.3 ciphersuites
+      --tls-bind=ADDR           bind with TLS enabled
+      --tls-cert=FILE           TLS certificate file (PEM)
+      --tls-cert-key=FILE       TLS private key file (PEM)
 
 Logging:
-  -l, --log-file=FILE           log all output to a file
-  -A  --access-log-file=FILE    log all workers access to a file
-      --no-color                disable colored output
+  -l, --log-file=FILE           log all output to file
+  -A, --access-log-file=FILE    log worker access to file
       --verbose                 verbose output
 
 Misc:
-  -c, --config=FILE             load a JSON-format configuration file
-  -B, --background              run the proxy in the background
-  -V, --version                 output version information and exit
-  -h, --help                    display this help and exit
-      --dry-run                 test configuration and exit
+  -c, --config=FILE             load JSON configuration file
+  -B, --background              run in background
+  -V, --version                 show version
+  -h, --help                    show help
 ```
 
-## Donations
+## Configuration
 
-The default donation fee is 2%, which can be reduced to 1% or completely disabled using the `donate-level` option. This fee applies only when you utilize more than 256 miners.
+### JSON Config (config.json)
 
-* XMR: `48edfHu7V9Z84YzzMa6fUueoELZ9ZRXq9VetWzYGzKt52XU5xvqgzYnDK9URnRoJMk1j8nLwEVsaSWJ4fhdUyZijBGUicoD`
+```json
+{
+    "mode": "nicehash",
+    "pools": [
+        {
+            "url": "stratum+tcp://pool.example.com:3333",
+            "user": "YOUR_WALLET",
+            "pass": "x",
+            "keepalive": true
+        }
+    ],
+    "bind": [
+        {
+            "host": "0.0.0.0",
+            "port": 3333
+        },
+        {
+            "host": "0.0.0.0",
+            "port": 3334,
+            "tls": true
+        }
+    ],
+    "http": {
+        "enabled": true,
+        "host": "127.0.0.1",
+        "port": 8081,
+        "access-token": "your-secret-token"
+    },
+    "tls": {
+        "cert": "/path/to/cert.pem",
+        "cert-key": "/path/to/key.pem"
+    },
+    "access-password": null,
+    "workers": true,
+    "verbose": false
+}
+```
 
-## Contacts
-* support@xmrig.com
-* [X](https://x.com/xmrig_dev)
+### Proxy Modes
+
+**NiceHash Mode** (default): Full nonce splitting for maximum efficiency
+- Best for large farms with many workers
+- Each worker gets unique nonce space
+- Maximum reduction in pool connections
+
+**Simple Mode**: Direct passthrough with shared connections
+- Simpler setup
+- Workers share pool connections
+- Good for smaller setups
+
+## Building from Source
+
+### Dependencies
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get install build-essential cmake libuv1-dev libssl-dev
+```
+
+**macOS:**
+```bash
+brew install cmake libuv openssl
+```
+
+### Build
+
+```bash
+mkdir build && cd build
+cmake ..
+cmake --build . --config Release
+
+# With debug logging
+cmake .. -DWITH_DEBUG_LOG=ON
+```
+
+### CMake Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `WITH_TLS` | ON | SSL/TLS support |
+| `WITH_HTTP` | ON | HTTP API |
+| `WITH_DEBUG_LOG` | OFF | Debug logging |
+| `BUILD_TESTS` | ON | Build unit tests |
+
+## HTTP API
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /1/summary` | Proxy statistics |
+| `GET /1/workers` | Connected workers list |
+| `GET /1/config` | Current configuration |
+
+Example:
+```bash
+curl http://127.0.0.1:8081/1/summary
+```
+
+## High Connection Setup (Linux)
+
+For 1000+ connections, increase file descriptor limits:
+
+```bash
+# /etc/security/limits.conf
+* soft nofile 1000000
+* hard nofile 1000000
+
+# /etc/sysctl.conf
+fs.file-max = 1000000
+net.core.somaxconn = 65535
+net.ipv4.tcp_max_syn_backlog = 65535
+```
+
+Then apply:
+```bash
+sudo sysctl -p
+```
+
+## Testing
+
+```bash
+cd build
+
+# Run all tests
+ctest --output-on-failure
+
+# Run specific test suites
+./tests/unit_tests
+./tests/integration_tests
+
+# Run with verbose output
+./tests/unit_tests --gtest_verbose
+```
+
+## License
+
+Copyright (c) 2025 Lethean <https://lethean.io>
+
+Licensed under the European Union Public License 1.2 (EUPL-1.2).