# Custom XMR (Monero) Mining System — Architecture & Implementation Plan ## 1. Executive Summary **The Vision:** A custom Monero (XMR) mining system built from scratch, consisting of: - A **Miner Builder** — a web tool that generates custom `.exe` files on demand, pre-configured for each machine - A **lightweight Windows agent** (single `.exe`, no install) that performs RandomX hashing - A **Go-based control server** running on **your local Windows machine** at **port 8989** - A **web-based Command Deck** dashboard (same Go server, serves the UI) - **Cloudflare Tunnel** exposing your local server to the internet via your `.com` domain - **No VPS needed** — everything runs on your Windows box - **No full installation** on worker machines — just drop the agent and run - **Single build script** — one command sets everything up and launches the server - **Self-contained** — all data saves back into its own directory **Is this reality-based?** **Yes, absolutely.** This is essentially a custom Stratum protocol implementation with a fleet management layer. The RandomX algorithm is open-source (CPU-only, ASIC-resistant). You're building a private mining pool with a management overlay — all running locally, tunneled through Cloudflare. ### The Core Innovation: Miner Builder Instead of building one generic miner and configuring each machine manually, you build a **Miner Builder** web page that: 1. Lets you configure agent parameters (server URL, wallet address, thread count, worker name) 2. Generates a unique `.exe` with those settings **baked in at compile time** 3. You download it, put it on a USB drive or network share, and run it on any Windows machine 4. The `.exe` auto-connects to your command deck — zero configuration needed on the target machine --- ## 2. System Architecture Overview ``` ┌─────────────────────────────────────────────────────────────────────┐ │ INTERNET │ │ (100+ distributed Windows machines connect here) │ └─────────────────────────────────────────────────────────────────────┘ ▲ ▲ ▲ │ │ │ │ wss://pool. │ wss://pool. │ wss://pool. │ yourdomain.com │ yourdomain.com │ yourdomain.com ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ CLOUDFLARE TUNNEL (cloudflared) │ │ │ │ Your domain: pool.yourdomain.com │ │ Cloudflare Tunnel proxies all traffic to your local Windows PC │ │ - HTTPS/TLS termination handled by Cloudflare │ │ - No open ports on your home/work network │ │ - No VPS needed │ │ - cloudflared runs as a Windows service or task │ └─────────────────────────────────────────────────────────────────────┘ │ │ localhost:8989 ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ YOUR LOCAL WINDOWS PC │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Go Control Server (single binary, runs on Windows) │ │ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ │ │ REST API │ │ WebSocket │ │ Miner Builder │ │ │ │ │ │ :8989/api │ │ Hub │ │ :8989/build │ │ │ │ │ │ │ │ :8989/ws │ │ (compiles .exe │ │ │ │ │ │ │ │ (real-time │ │ on demand) │ │ │ │ │ │ │ │ agent │ │ │ │ │ │ │ │ │ │ comms) │ │ │ │ │ │ │ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │ │ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ │ │ SQLite Database (local file, no install) │ │ │ │ │ │ - Agents table │ │ │ │ │ │ - Mining stats (hashrate, shares, accepted/rejected) │ │ │ │ │ │ - Jobs table │ │ │ │ │ │ - Build records (track which .exe was built for who) │ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ │ │ Command Deck (Web UI - served by Go server) │ │ │ │ │ │ - React SPA, embedded in Go binary (embed.FS) │ │ │ │ │ │ - Real-time dashboard via WebSocket │ │ │ │ │ │ - Agent management, stats, alerts │ │ │ │ │ │ - Miner Builder page │ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Go Toolchain (for Miner Builder) │ │ │ │ - Go compiler installed on this machine │ │ │ │ - When you click "Build .exe", it runs: │ │ │ │ GOOS=windows GOARCH=amd64 go build -o miner-{name}.exe │ │ │ │ - Pre-compiled RandomX static lib linked at build time │ │ │ └─────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 2.1 Why This Architecture is Better for You | Approach | VPS (old plan) | Local + Cloudflare (new plan) | |----------|---------------|------------------------------| | **Cost** | $10-50/month VPS | $0 (Cloudflare Tunnel is free) | | **Setup** | Provision server, install deps | Install cloudflared, one command | | **Monero daemon** | Need 150GB+ blockchain sync | **You don't need monerod at all** — connect to a public pool | | **Miner Builder** | Cross-compile from Linux | Build natively on Windows | | **Management** | SSH into remote server | Local Windows GUI, RDP, or just sit at the machine | | **Security** | Cloudflare Tunnel handles TLS | Cloudflare Tunnel handles TLS | | **Uptime** | Depends on VPS provider | Depends on your local machine + internet | ### 2.2 The Monero Piece — You Don't Need monerod Since you're running locally and don't want to sync the blockchain (150GB+), your server connects to a **public mining pool** as an upstream: ``` Your Agent ──WebSocket──> Your Control Server ──Stratum──> Public Pool (e.g., supportxmr.com) │ Monero Network ``` Your control server acts as a **proxy pool**: 1. Connects to a public pool (like supportxmr.com, minexmr.com, etc.) via Stratum TCP 2. Receives jobs from the public pool 3. Distributes those jobs to your 100+ agents 4. Receives shares from your agents 5. Forwards valid shares to the public pool 6. Public pool pays out to **your wallet** **Result:** You get the hashrate of all 100+ machines pointed at your wallet, without running a full node. --- ## 3. RandomX Algorithm — What You Need to Know RandomX is Monero's proof-of-work algorithm. Key characteristics: - **CPU-only** — ASIC-resistant by design, uses random code execution - **Memory-hard** — Requires ~2GB of RAM per mining instance (dataset) - **Two phases:** 1. **Dataset initialization** (~2GB, takes 30-60 seconds on modern CPUs) 2. **Hashing** — Uses the dataset to execute random programs - **Verification is fast** — The server can verify a submitted hash in microseconds **Implementation approach for your custom miner:** - You will **NOT** reimplement RandomX from scratch (that's millions of lines of crypto) - Instead, you'll use the official [`randomx`](https://github.com/tevador/RandomX) C library via CGo bindings - Your Go agent wraps this library, handles the network protocol, and reports stats --- ## 4. Component Details ### 4.1 Windows Agent (`agent/`) **Goal:** A single `.exe` file (no installer, no dependencies) that: 1. Connects to your `.com` endpoint via WebSocket (through Cloudflare Tunnel) 2. Receives mining jobs (block template + difficulty) 3. Hashes using RandomX 4. Submits shares back 5. Reports system stats (CPU usage, hashrate, temperature) 6. Auto-updates itself **Architecture:** ``` ┌─────────────────────────────────────────────┐ │ Windows Agent (Go binary) │ │ │ │ ┌─────────────┐ ┌──────────────────────┐ │ │ │ WebSocket │ │ RandomX Worker Pool │ │ │ │ Client │◄─┤ (N workers = CPU │ │ │ │ (goroutine) │ │ threads - 1) │ │ │ └──────┬──────┘ │ │ │ │ │ │ ┌────────────────┐ │ │ │ │ │ │ Worker 1 (CGo │ │ │ │ │ │ │ RandomX hash) │ │ │ │ │ │ ├────────────────┤ │ │ │ │ │ │ Worker 2 ... │ │ │ │ │ │ ├────────────────┤ │ │ │ │ │ │ Worker N ... │ │ │ │ │ │ └────────────────┘ │ │ │ │ └──────────────────────┘ │ │ │ │ │ ┌──────┴──────┐ ┌──────────────────────┐ │ │ │ Stats │ │ Auto-Updater │ │ │ │ Reporter │ │ (checks /latest- │ │ │ │ (CPU, RAM, │ │ version endpoint) │ │ │ │ hashrate) │ └──────────────────────┘ │ │ └─────────────┘ │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ Config (baked-in at compile time) │ │ │ │ Server URL, wallet, threads, │ │ │ │ worker name — all hardcoded │ │ │ │ No config file needed │ │ │ └──────────────────────────────────────┘ │ └─────────────────────────────────────────────┘ ``` **Key files:** ``` agent/ ├── main.go # Entry point ├── config/ │ ├── config.go # Config loading (builtin > flags > file) │ └── builtin.go # AUTO-GENERATED by Miner Builder ├── client/ │ ├── websocket.go # WebSocket connection management │ └── protocol.go # Message types (jobs, shares, stats) ├── miner/ │ ├── randomx.go # CGo bindings to RandomX library │ ├── randomx_cgo.go # #cgo directives and C bindings │ ├── worker.go # Mining worker goroutine │ └── pool.go # Worker pool management ├── stats/ │ └── reporter.go # System stats collection (CPU, RAM, hashrate) ├── updater/ │ └── updater.go # Auto-update mechanism ├── randomx/ # Vendored RandomX C library │ ├── CMakeLists.txt │ ├── src/ │ ├── lib/ │ └── include/ ├── go.mod └── go.sum ``` ### 4.2 Control Server (`server/`) **Goal:** The central brain — runs on your local Windows machine. Connects to a public Monero pool via Stratum, distributes jobs to your agents, validates shares, serves the Command Deck and Miner Builder. **Architecture:** ``` ┌─────────────────────────────────────────────────────────────┐ │ Go Control Server (Windows binary) │ │ │ │ ┌──────────────────┐ ┌──────────────────────────────┐ │ │ │ HTTP Router │ │ WebSocket Hub │ │ │ │ (chi or gin) │ │ ┌────────────────────────┐ │ │ │ │ │ │ │ Agent Connection Map │ │ │ │ │ GET /api/stats │ │ │ agentID -> WS Conn │ │ │ │ │ GET /api/agents │ │ └────────────────────────┘ │ │ │ │ POST /api/config │ │ ┌────────────────────────┐ │ │ │ │ GET /api/jobs │ │ │ Broadcast: new job │ │ │ │ │ WS /ws/agent │ │ │ Receive: share submit │ │ │ │ │ WS /ws/dashboard│ │ │ Send: job assignment │ │ │ │ │ GET /builder/* │ │ └────────────────────────┘ │ │ │ │ GET /dashboard/*│ └──────────────┬───────────────┘ │ │ └────────┬─────────┘ │ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Stratum Bridge (connects to public pool) │ │ │ │ - TCP connection to pool.supportxmr.com:3333 │ │ │ │ - Implements Stratum protocol (login, job, submit) │ │ │ │ - Receives jobs from pool, forwards to agents │ │ │ │ - Receives shares from agents, forwards to pool │ │ │ │ - Handles reconnection if pool drops │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Miner Builder Pipeline │ │ │ │ - Receives build config from web form │ │ │ │ - Generates config/builtin.go with baked-in values │ │ │ │ - Runs: go build -o miner-{name}.exe │ │ │ │ - Returns the .exe for download │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ SQLite Database │ │ │ │ - agents table: id, name, wallet, ip, status, │ │ │ │ last_seen, version │ │ │ │ - shares table: id, agent_id, job_id, difficulty, │ │ │ │ accepted, timestamp │ │ │ │ - hashrate_samples: agent_id, hashrate, timestamp │ │ │ │ - builds table: id, worker_name, config, created_at │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **Key files:** ``` server/ ├── main.go ├── config.go ├── cmd/ │ └── server.go # Server startup ├── internal/ │ ├── api/ │ │ ├── router.go # HTTP route definitions │ │ ├── handlers.go # REST endpoint handlers │ │ ├── middleware.go # Auth, logging, CORS │ │ └── websocket.go # WebSocket upgrade + hub │ ├── pool/ │ │ ├── stratum_client.go # Stratum TCP client to public pool │ │ ├── job_manager.go # Job distribution to agents │ │ └── share_validator.go # Validate submitted shares │ ├── builder/ │ │ ├── handler.go # HTTP handler for build requests │ │ ├── builder.go # Build pipeline logic │ │ ├── compiler.go # Go cross-compilation wrapper │ │ └── templates/ │ │ └── builtin.go.tmpl # Template for baked-in config │ ├── models/ │ │ ├── agent.go │ │ ├── share.go │ │ ├── job.go │ │ └── stats.go │ ├── db/ │ │ ├── sqlite.go # SQLite connection + migrations │ │ └── queries.go # SQL queries │ └── auth/ │ └── tokens.go # Agent authentication tokens ├── web/ # Embedded React dashboard │ └── dist/ # Built static files (go:embed) ├── go.mod └── go.sum ``` ### 4.3 Command Deck + Miner Builder (Web UI) (`web/`) **Goal:** A single-page React app served by the Go server (embedded via `embed.FS`). Contains both the Command Deck dashboard and the Miner Builder. **Pages:** | Route | Page | Purpose | |-------|------|---------| | `/` | Dashboard | Live stats, hashrate chart, agent grid | | `/agents` | Agent List | All agents with status, details | | `/agents/:id` | Agent Detail | Single agent stats, history | | `/builder` | Miner Builder | Configure and build custom `.exe` | | `/settings` | Settings | Pool connection, wallet, auth | **Dashboard Layout:** ``` ┌─────────────────────────────────────────────────────────────┐ │ ☰ Command Deck pool.yourdomain.com │ ├──────────┬──────────────────────────────────────────────────┤ │ │ │ │ Overview │ ┌──────────────────────────────────────────┐ │ │ Agents │ │ Total Hashrate: 45.2 KH/s │ │ │ Builder │ │ Active Agents: 87 / 102 ████████████░ │ │ │ Settings │ │ Shares/hr: 12,450 | Accepted: 99.2% │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ Hashrate Chart (last 24h) │ │ │ │ │ ╱╲ ╱╲ ╱╲ ╱╲ │ │ │ │ │ ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲ │ │ │ │ │╱ ╲╱ ╲╱ ╲╱ ╲ │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ Agents 🟢 87 online │ │ │ │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ │ │ │office- │ │warehse-│ │remote- │ │ │ │ │ │ │pc-01 │ │pc-03 │ │office-2│ │ │ │ │ │ │4.2 KH/s│ │3.8 KH/s│ │5.1 KH/s│ │ │ │ │ │ └────────┘ └────────┘ └────────┘ │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ └──────────┴──────────────────────────────────────────────────┘ ``` **Miner Builder Page:** ``` ┌─────────────────────────────────────────────────────────────┐ │ 🛠️ Miner Builder │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Server URL: [wss://pool.yourdomain.com/ws/agent ] │ │ │ │ │ │ │ │ Wallet Address: │ │ │ │ [4A...your-monero-wallet-address.................] │ │ │ │ │ │ │ │ Worker Name: [office-pc-01 ] │ │ │ │ │ │ │ │ Thread Count: [4 ] (auto-detect: ☑) │ │ │ │ │ │ │ │ CPU Priority: [Low ] [Normal] [High] │ │ │ │ │ │ │ │ Auto-start on boot: [✅ Yes - add to startup] │ │ │ │ │ │ │ │ Hide console window: [✅ Yes - run silently] │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ │ │ 🔨 BUILD MINER .EXE │ │ │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ Build status: ✅ Complete - miner-office-pc.exe │ │ │ │ Size: 8.4 MB | Download ⬇️ │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **Key files:** ``` web/ ├── package.json ├── tsconfig.json ├── vite.config.ts ├── index.html ├── src/ │ ├── main.tsx │ ├── App.tsx │ ├── pages/ │ │ ├── Dashboard.tsx │ │ ├── Agents.tsx │ │ ├── AgentDetail.tsx │ │ ├── Builder.tsx # Miner Builder form │ │ └── Settings.tsx │ ├── api/ │ │ ├── client.ts # REST API client │ │ └── websocket.ts # WebSocket hook │ ├── components/ │ │ ├── Layout/ │ │ │ ├── Sidebar.tsx │ │ │ └── Header.tsx │ │ ├── Dashboard/ │ │ │ ├── StatsCards.tsx │ │ │ ├── HashrateChart.tsx │ │ │ └── AgentGrid.tsx │ │ ├── Agents/ │ │ │ ├── AgentList.tsx │ │ │ ├── AgentCard.tsx │ │ │ └── AgentDetail.tsx │ │ └── Shared/ │ │ ├── StatusBadge.tsx │ │ └── LoadingSpinner.tsx │ ├── hooks/ │ │ ├── useWebSocket.ts │ │ └── useApi.ts │ ├── types/ │ │ ├── agent.ts │ │ ├── stats.ts │ │ └── job.ts │ └── styles/ │ └── globals.css ``` --- ## 5. Miner Builder — The Core Innovation This is the key differentiator. Instead of distributing a generic `.exe` that needs manual configuration on each machine, you build a **web-based Miner Builder** that generates custom `.exe` files on demand. ### 5.1 How It Works ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Miner Builder Flow │ │ │ │ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │ │ │ You visit │────>│ Configure via │────>│ Click │ │ │ │ builder. │ │ Web Form: │ │ "Build .exe"│ │ │ │ yourdomain. │ │ - Server URL │ │ │ │ │ │ com/build │ │ - Wallet addr │ │ │ │ │ │ │ │ - Thread count │ │ │ │ │ │ │ │ - Worker name │ │ │ │ │ │ │ │ - Auto-start │ │ │ │ │ └──────────────┘ └────────┬─────────┘ └──────┬───────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ Local Windows Build Pipeline │ │ │ │ (runs on YOUR machine) │ │ │ │ │ │ │ │ 1. Receive config JSON │ │ │ │ 2. Generate config/builtin.go │ │ │ │ 3. Run: go build -o miner-{name}.exe │ │ │ │ 4. Return download link │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ You download │ │ │ │ miner-office-pc.exe │ │ │ └──────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ Copy to USB / │ │ │ │ Network share │ │ │ │ Run on target PC │ │ │ │ No config needed │ │ │ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 5.2 The Build Pipeline (Server-Side) ```go // Pseudocode for the build handler func handleBuildRequest(w http.ResponseWriter, r *http.Request) { var cfg AgentBuildConfig json.NewDecoder(r.Body).Decode(&cfg) // 1. Validate config if cfg.Threads < 1 || cfg.Threads > 64 { /* error */ } if !validWallet(cfg.Wallet) { /* error */ } // 2. Generate unique build ID buildID := uuid.New().String() // 3. Create temp build directory buildDir := filepath.Join(os.TempDir(), "miner-builds", buildID) copyAgentSource(buildDir) // 4. Write baked-in config configContent := fmt.Sprintf(`package config const ( DefaultServer = "%s" DefaultWallet = "%s" DefaultThreads = %d DefaultWorker = "%s" AutoStart = %v SilentMode = %v )`, cfg.Server, cfg.Wallet, cfg.Threads, cfg.WorkerName, cfg.AutoStart, cfg.SilentMode) writeFile(filepath.Join(buildDir, "config", "builtin.go"), configContent) // 5. Compile (natively on Windows!) cmd := exec.Command("go", "build", "-ldflags", "-s -w", // Strip debug symbols, smaller binary "-o", fmt.Sprintf("miner-%s.exe", cfg.WorkerName), ".") cmd.Dir = buildDir cmd.Run() // 6. Return the .exe w.Header().Set("Content-Type", "application/x-msdownload") w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="miner-%s.exe"`, cfg.WorkerName)) http.ServeFile(w, r, exePath) } ``` ### 5.3 How the Baked-In Config Works The agent source code has a `config/builtin.go` file that is **generated at build time**: ```go // config/builtin.go — THIS FILE IS AUTO-GENERATED BY THE MINER BUILDER package config // BuiltinConfig holds the compile-time baked-in configuration type BuiltinConfig struct { ServerURL string WalletAddr string WorkerName string ThreadCount int AutoStart bool SilentMode bool } var Defaults = BuiltinConfig{ ServerURL: "wss://pool.yourdomain.com/ws/agent", WalletAddr: "4A...your-monero-wallet...", WorkerName: "office-pc-01", ThreadCount: 4, AutoStart: true, SilentMode: true, } ``` The agent's `main.go` checks for built-in config first, then falls back to CLI flags or `config.json`: ```go func main() { // Priority: CLI flags > config.json > builtin defaults cfg := config.Load() if cfg.ServerURL == "" { cfg.ServerURL = config.Defaults.ServerURL } // ... etc } ``` ### 5.4 Build Optimization | Technique | Benefit | |-----------|---------| | `-ldflags="-s -w"` | Strips debug info, reduces binary size by ~40% | | UPX compression | Optional: compress .exe by 50-70% (adds startup time) | | Go build cache | Subsequent builds are faster (cached dependencies) | | Pre-compiled RandomX lib | Ship pre-compiled `.a` file, link at build time | ### 5.5 Distribution Methods Once you have the `.exe`: 1. **USB Drive** — Copy to a USB, walk around and plug into each machine 2. **Network Share** — `\\server\share\miner-office-pc.exe` 3. **Group Policy** — Push via Windows GPO startup script 4. **PDQ Deploy / SCCM** — Enterprise deployment tools 5. **Simple batch file** — `copy \\server\share\miner.exe C:\temp\ && start C:\temp\miner.exe` 6. **One-liner PowerShell** — `Invoke-WebRequest -Uri https://pool.yourdomain.com/download/miner.exe -OutFile $env:TEMP\miner.exe; Start-Process $env:TEMP\miner.exe` ### 5.6 Builder API Endpoints ``` POST /api/v1/builder/build # Submit build request (returns build ID) GET /api/v1/builder/status/:id # Check build status GET /api/v1/builder/download/:id # Download the built .exe GET /api/v1/builder/presets # Get saved build presets POST /api/v1/builder/presets # Save a build preset for reuse ``` --- ## 6. Cloudflare Tunnel Setup This is how your local Windows machine becomes accessible at `pool.yourdomain.com`. ### 6.1 What You Need 1. A domain name (e.g., `yourdomain.com`) 2. Cloudflare account (free tier) 3. Your domain's DNS managed by Cloudflare 4. `cloudflared` installed on your Windows machine ### 6.2 Setup Steps ```powershell # 1. Install cloudflared on Windows # Download from: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ # Or via winget: winget install cloudflare.cloudflared # 2. Authenticate cloudflared with your Cloudflare account cloudflared tunnel login # 3. Create a tunnel cloudflared tunnel create crypto-miner # 4. Create config.yml # C:\Users\you\.cloudflared\config.yml tunnel: crypto-miner credentials-file: C:\Users\you\.cloudflared\crypto-miner.json ingress: - hostname: pool.yourdomain.com service: http://localhost:8989 - service: http_status:404 # 5. Configure DNS cloudflared tunnel route dns crypto-miner pool.yourdomain.com # 6. Run the tunnel (as a Windows service) cloudflared service install ``` ### 6.3 Result ``` User types: https://pool.yourdomain.com │ ▼ Cloudflare Edge (TLS termination) │ ▼ Cloudflare Tunnel (encrypted) │ ▼ Your local Windows PC :8989 │ ▼ Go Control Server (Command Deck + Builder + WebSocket) ``` --- ## 7. Settings & Configuration UI The Command Deck includes a full **Settings** page where you configure everything through the GUI. No config files to edit, no command-line flags to remember. All settings save to `data/config.json` automatically. ### 7.1 Settings Page Layout ``` ┌─────────────────────────────────────────────────────────────┐ │ ☰ Command Deck Settings │ ├──────────┬──────────────────────────────────────────────────┤ │ │ │ │ Overview │ ┌──────────────────────────────────────────┐ │ │ Agents │ │ 🔗 POOL CONNECTION │ │ │ Builder │ │ │ │ │ Settings │ │ Pool Address: │ │ │ │ │ [pool.supportxmr.com:3333 ] │ │ │ │ │ │ │ │ │ │ Pool Password (optional): │ │ │ │ │ [x:your-worker-password ] │ │ │ │ │ │ │ │ │ │ Use TLS/SSL: [✅ Yes] │ │ │ │ │ ┌──────────────────────────────────┐ │ │ │ │ │ │ 🔄 Test Connection │ │ │ │ │ │ └──────────────────────────────────┘ │ │ │ │ │ Status: ✅ Connected to pool │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ 👛 WALLET │ │ │ │ │ │ │ │ │ │ Monero Wallet Address: │ │ │ │ │ [4A...your-address....................] │ │ │ │ │ │ │ │ │ │ Payment ID (optional): │ │ │ │ │ [ ] │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ ⚙️ DEFAULT AGENT CONFIG (for Builder) │ │ │ │ │ │ │ │ │ │ These become the defaults in the │ │ │ │ │ Miner Builder form: │ │ │ │ │ │ │ │ │ │ Default Threads: [4 ] │ │ │ │ │ Default CPU Priority: │ │ │ │ │ ○ Low (idle) ● Below Normal ○ Normal │ │ │ │ │ │ │ │ │ │ Mining Mode: │ │ │ │ │ ● Always mine │ │ │ │ │ ○ Only when idle (CPU < 20% for 5min) │ │ │ │ │ ○ On a schedule (9PM - 6AM) │ │ │ │ │ │ │ │ │ │ Max CPU Usage: [80 ] % │ │ │ │ │ Min Free RAM: [1024 ] MB │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ 🖥️ BACKGROUND / SILENT MODE │ │ │ │ │ │ │ │ │ │ Run in background (no console window): │ │ │ │ │ [✅ Yes - run silently] │ │ │ │ │ │ │ │ │ │ When in background, run as: │ │ │ │ │ ○ Current user (visible in task manager) │ │ │ │ │ ● Windows Service (survives logoff) │ │ │ │ │ ○ Scheduled Task (run on idle) │ │ │ │ │ │ │ │ │ │ Auto-start on boot: │ │ │ │ │ [✅ Yes - add to HKCU\Run] │ │ │ │ │ │ │ │ │ │ Minimize to system tray: │ │ │ │ │ [✅ Yes - tray icon only] │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ 🔔 ALERTS & NOTIFICATIONS │ │ │ │ │ │ │ │ │ │ Notify when agent goes offline: │ │ │ │ │ [✅ Yes - after 5 minutes] │ │ │ │ │ │ │ │ │ │ Notify on hashrate drop: │ │ │ │ │ [✅ Yes - if drops below 50%] │ │ │ │ │ │ │ │ │ │ Notify on high rejection rate: │ │ │ │ │ [✅ Yes - if > 5% rejected] │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ 💾 SAVE CONFIG │ │ │ │ └──────────────────────────────────────────┘ │ │ └──────────────────────────────────────────────────┘ ``` ### 7.2 Settings Saved to `data/config.json` ```json { "server": { "port": 8989, "dashboard_auth_enabled": false, "dashboard_password": "" }, "pool": { "host": "pool.supportxmr.com", "port": 3333, "use_tls": true, "password": "x" }, "wallet": { "address": "4A...your-monero-wallet...", "payment_id": "" }, "default_agent_config": { "threads": 4, "cpu_priority": "below_normal", "max_cpu_usage_pct": 80, "min_free_ram_mb": 1024, "mining_mode": "always", "idle_threshold_pct": 20, "idle_duration_minutes": 5, "schedule_start": "21:00", "schedule_end": "06:00" }, "background": { "silent_mode": true, "run_as": "service", "auto_start": true, "minimize_to_tray": true }, "alerts": { "offline_threshold_minutes": 5, "hashrate_drop_threshold_pct": 50, "rejection_rate_threshold_pct": 5 } } ``` ### 7.3 Feature Details | Feature | What It Does | Where It Applies | |---------|-------------|------------------| | **Pool Address** | The public Monero pool your server connects to | Server-side (all agents share this) | | **Wallet Address** | Your XMR wallet for payouts | Server-side + baked into agent .exe | | **Default Threads** | How many CPU threads each agent uses | Default in Miner Builder form | | **CPU Priority** | Idle/Low/BelowNormal/Normal — controls how much CPU the miner takes | Baked into agent .exe | | **Mining Mode** | Always / On Idle / Scheduled — when the agent actually mines | Baked into agent .exe | | **Max CPU Usage %** | Caps CPU usage so the machine stays usable | Baked into agent .exe | | **Min Free RAM** | Stops mining if system RAM drops below this threshold | Baked into agent .exe | | **Silent Mode** | No console window, runs hidden | Baked into agent .exe | | **Run As** | Current user / Windows Service / Scheduled Task | Determines how agent is installed | | **Auto-Start** | Adds to Windows startup registry | Baked into agent .exe | | **System Tray** | Minimizes to tray icon with right-click menu | Agent runtime behavior | | **Alerts** | Dashboard notifications for offline agents, hashrate drops | Server-side dashboard | ### 7.4 How Settings Flow to the Agent ``` Settings Page (GUI) │ ▼ data/config.json (saved on server) │ ▼ Miner Builder reads defaults from config.json │ ▼ You adjust per-agent in the Builder form │ ▼ Builder generates config/builtin.go with those values │ ▼ Compiled into miner-{name}.exe │ ▼ Agent runs with baked-in settings - Connects to your pool - Uses your wallet - Respects CPU/memory limits - Runs in background/silent mode - Auto-starts on boot ``` ### 7.5 Per-Agent Override (Remote Config Push) From the Command Deck, you can also push config changes to **already-running agents**: ``` Agent Detail Page │ ▼ ┌─────────────────────────────────────────────┐ │ Remote Config Push │ │ │ │ Agent: office-pc-01 (currently online) │ │ │ │ Current: 4 threads, Normal priority │ │ │ │ New config: │ │ Threads: [6 ] (was 4) │ │ Priority: [Low ] (was Normal) │ │ Max CPU: [70 ] % (was 80%) │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ 📤 PUSH CONFIG TO AGENT │ │ │ └──────────────────────────────────────┘ │ │ │ │ Status: ✅ Config sent, agent applied │ └─────────────────────────────────────────────┘ ``` The server sends a `config_update` message over WebSocket, and the agent applies it live without restarting. --- ## 8. Build Script & Self-Contained Operation ### 7.1 The One-Click Setup The entire system is designed around a single `run.bat` script that lives in the project root. You double-click it or run it from the command line, and it: 1. Checks if Go is installed (prompts if not) 2. Builds the Go server binary 3. Builds the React dashboard (or uses pre-built) 4. Launches the server on port 8989 5. Opens your browser to `http://localhost:8989` ``` crypto-miner/ │ ├── run.bat ← THE ONLY FILE YOU NEED TO RUN ├── server/ ← Go source code (compiled by run.bat) ├── agent/ ← Agent source (used by Miner Builder) ├── web/ ← React dashboard source ├── data/ ← Created automatically — stores SQLite DB + builds │ ├── miner.db ← SQLite database (agents, shares, stats) │ └── builds/ ← Generated .exe files saved here └── config.json ← Created on first run — your settings ``` ### 7.2 What `run.bat` Does ```batch @echo off title Crypto Miner Control Server echo [1/4] Checking dependencies... where go >nul 2>nul if %ERRORLEVEL% neq 0 ( echo ERROR: Go is not installed. Download from https://go.dev/dl/ pause exit /b 1 ) echo [2/4] Building server... cd /d "%~dp0" go build -o bin\miner-server.exe .\server\main.go if %ERRORLEVEL% neq 0 ( echo ERROR: Build failed pause exit /b 1 ) echo [3/4] Creating data directories... if not exist data\builds mkdir data\builds if not exist data\db mkdir data\db echo [4/4] Starting server on port 8989... echo. echo ╔══════════════════════════════════════════════════╗ echo ║ Crypto Miner Control Server ║ echo ║ Dashboard: http://localhost:8989 ║ echo ║ WebSocket: ws://localhost:8989/ws/agent ║ echo ║ Press Ctrl+C to stop ║ echo ╚══════════════════════════════════════════════════╝ echo. .\bin\miner-server.exe -port 8989 -data .\data pause ``` ### 7.3 Self-Contained Data Storage Everything saves back into the project directory — no registry, no AppData, no system files: | File | Purpose | Created | |------|---------|---------| | `data/miner.db` | SQLite database — all agents, shares, stats | Auto on first run | | `data/builds/miner-{name}.exe` | Generated miner executables | When you use Miner Builder | | `data/config.json` | Server settings (pool, wallet, port) | Auto on first run | | `data/logs/server.log` | Server logs | Auto on first run | ### 7.4 What Happens When You Run It ``` Step 1: Double-click run.bat Step 2: Script compiles the Go server (takes ~5 seconds) Step 3: Server starts on http://localhost:8989 Step 4: Browser opens automatically Step 5: You see the Command Deck dashboard From here you can: - Visit the Miner Builder to generate .exe files - Monitor agents as they connect - View hashrate charts and stats - Configure pool connection settings ``` ### 7.5 Port 8989 Convention Port 8989 is used consistently throughout: ``` Server listens on: :8989 Dashboard URL: http://localhost:8989 WebSocket agent URL: ws://localhost:8989/ws/agent WebSocket dashboard: ws://localhost:8989/ws/dashboard Builder API: http://localhost:8989/api/v1/builder/build Cloudflare Tunnel: localhost:8989 ``` --- ## 8. Communication Protocol ### 7.1 WebSocket Message Format (Agent <-> Server) All messages are JSON over WebSocket (TLS wss://). ```jsonc // Agent -> Server: Authentication { "type": "auth", "payload": { "agent_id": "generated-uuid", "wallet": "4A...XMR_WALLET...", "version": "1.0.0", "hostname": "OFFICE-PC-01", "cpu_cores": 8, "memory_gb": 16 } } // Server -> Agent: Authentication response { "type": "auth_response", "payload": { "success": true, "agent_id": "assigned-id", "config": { "threads": 6, "priority": 1, "extra_flags": "" } } } // Server -> Agent: New mining job (from public pool via Stratum bridge) { "type": "new_job", "payload": { "job_id": "job-abc-123", "block_template": "", "difficulty": 250000, "height": 3123456, "seed_hash": "", "target": "" } } // Agent -> Server: Share submission { "type": "submit_share", "payload": { "job_id": "job-abc-123", "nonce": "", "hash": "", "worker_name": "OFFICE-PC-01" } } // Server -> Agent: Share result { "type": "share_result", "payload": { "job_id": "job-abc-123", "accepted": true, "error": null } } // Agent -> Server: Stats heartbeat (every 10s) { "type": "stats", "payload": { "hashrate_15s": 4520.5, "hashrate_1m": 4480.2, "hashrate_15m": 4400.1, "shares_submitted": 142, "shares_accepted": 140, "cpu_usage_pct": 85.2, "memory_usage_pct": 62.1, "uptime_seconds": 3600 } } ``` ### 7.2 REST API Endpoints ``` # Agent-facing GET /api/v1/agent/config # Get agent configuration POST /api/v1/agent/register # Register new agent GET /api/v1/agent/update # Check for agent update # Dashboard-facing GET /api/v1/dashboard/stats # Aggregate fleet stats GET /api/v1/agents # List all agents GET /api/v1/agents/:id # Single agent detail GET /api/v1/agents/:id/stats # Agent historical stats POST /api/v1/agents/:id/config # Push config to agent GET /api/v1/shares # Recent shares (paginated) GET /api/v1/shares/:agent_id # Shares per agent GET /api/v1/jobs # Recent jobs GET /api/v1/health # Health check # Builder-facing POST /api/v1/builder/build # Submit build request GET /api/v1/builder/status/:id # Check build status GET /api/v1/builder/download/:id # Download built .exe # WebSocket endpoints WS /ws/agent # Agent WebSocket connection WS /ws/dashboard # Dashboard WebSocket connection ``` --- ## 9. Security Considerations | Concern | Solution | |---------|----------| | **Agent authentication** | Pre-shared API tokens, or agent registers with a one-time setup key | | **TLS encryption** | Handled by Cloudflare Tunnel (automatic) | | **Agent spoofing** | Each agent gets a unique ID + secret on first registration | | **Dashboard access** | JWT-based auth with session tokens (optional for local use) | | **Public pool connection** | Stratum over TCP, standard pool auth with your wallet | | **Rate limiting** | Prevent share spam from rogue agents | --- ## 10. Project Structure (Full) ``` crypto-miner/ ├── run.bat ← THE ONLY FILE YOU NEED TO DOUBLE-CLICK ├── README.md ├── .env.example │ ├── server/ # Go control server (runs on your Windows PC) │ ├── main.go │ ├── config.go │ ├── go.mod │ ├── go.sum │ ├── cmd/ │ │ └── server.go │ ├── internal/ │ │ ├── api/ │ │ │ ├── router.go │ │ │ ├── handlers.go │ │ │ ├── middleware.go │ │ │ └── websocket.go │ │ ├── pool/ │ │ │ ├── stratum_client.go # Connects to public Monero pool │ │ │ ├── job_manager.go │ │ │ └── share_validator.go │ │ ├── builder/ │ │ │ ├── handler.go │ │ │ ├── builder.go │ │ │ ├── compiler.go │ │ │ └── templates/ │ │ │ └── builtin.go.tmpl │ │ ├── models/ │ │ │ ├── agent.go │ │ │ ├── share.go │ │ │ ├── job.go │ │ │ └── stats.go │ │ ├── db/ │ │ │ ├── sqlite.go │ │ │ └── queries.go │ │ └── auth/ │ │ └── tokens.go │ └── web/ # Embedded React dashboard │ └── dist/ │ ├── agent/ # Windows miner agent source (used by Builder) │ ├── main.go │ ├── config/ │ │ ├── config.go │ │ └── builtin.go # AUTO-GENERATED by Miner Builder │ ├── go.mod │ ├── go.sum │ ├── client/ │ │ ├── websocket.go │ │ └── protocol.go │ ├── miner/ │ │ ├── randomx.go │ │ ├── randomx_cgo.go │ │ ├── worker.go │ │ └── pool.go │ ├── stats/ │ │ └── reporter.go │ ├── updater/ │ │ └── updater.go │ └── randomx/ # Vendored RandomX C library │ ├── CMakeLists.txt │ ├── src/ │ ├── lib/ │ └── include/ │ ├── data/ ← Created automatically on first run │ ├── miner.db ← SQLite database (agents, shares, stats) │ ├── builds/ ← Generated .exe files from Miner Builder │ ├── config.json ← Server settings │ └── logs/ │ └── server.log ← Server logs │ ├── scripts/ │ ├── setup-tunnel.bat # Install & configure Cloudflare Tunnel │ └── docs/ ├── architecture.md ├── protocol.md ├── cloudflare-tunnel.md └── deployment.md ``` --- ## 11. Implementation Phases ### Phase 1: Foundation + Build Script (Week 1) - [ ] Set up Go project structure for `server/` - [ ] Create `run.bat` — the single build & launch script - [ ] Server listens on port 8989 by default - [ ] Implement WebSocket hub (agent connections) - [ ] Implement basic REST API (health, agent registration) - [ ] Set up SQLite database and schema (saves to `data/miner.db`) - [ ] Create React dashboard skeleton with Vite - [ ] Implement dashboard WebSocket connection - [ ] Set up Cloudflare Tunnel (cloudflared) - [ ] Test: run `run.bat`, verify `http://localhost:8989` loads the dashboard ### Phase 2: Miner Builder (Week 2) - [ ] Create builder web UI (form with server URL, wallet, threads, worker name) - [ ] Implement build pipeline handler in Go server - [ ] Create `config/builtin.go` template with baked-in config values - [ ] Implement Go compilation wrapper - [ ] Add build queue with status tracking - [ ] Add download endpoint for completed builds - [ ] Test: generate .exe, copy to another Windows machine, verify zero-config startup ### Phase 3: Mining Core (Week 3-4) - [ ] Build RandomX C library for Windows - [ ] Create CGo bindings in `agent/` - [ ] Implement mining worker pool in Go agent - [ ] Implement Stratum bridge (connect to public pool) - [ ] Implement job distribution from server to agents - [ ] Implement share submission and validation - [ ] Test with a few machines pointed at your domain ### Phase 4: Agent Polish (Week 5) - [ ] Add auto-update mechanism to agent - [ ] Add stats reporting (hashrate, CPU, memory) - [ ] Add graceful shutdown and reconnection logic - [ ] Add silent mode (no console window) - [ ] Add auto-start via Windows registry (HKCU\Software\Microsoft\Windows\CurrentVersion\Run) ### Phase 5: Command Deck + Settings (Week 6) - [ ] Build live hashrate chart - [ ] Build agent status grid with real-time updates - [ ] Build share history table - [ ] Build Settings page with all config sections: - [ ] Pool connection settings + test connection button - [ ] Wallet address input - [ ] Default agent config (threads, priority, mining mode) - [ ] Background/silent mode settings - [ ] Alerts & notifications config - [ ] Save/load settings from `data/config.json` - [ ] Add alert system (agent offline, hashrate drop) - [ ] Add remote config push to agents - [ ] Add authentication for dashboard access ### Phase 6: Production Hardening (Week 7-8) - [ ] Add rate limiting - [ ] Add logging and monitoring - [ ] Add backup (SQLite database) - [ ] Performance tuning (batch share submissions) - [ ] Test with 100+ simulated agents - [ ] Documentation --- ## 12. Why Go for Everything? | Factor | Go Advantage | |--------|-------------| | **Single binary** | Go compiles to a standalone `.exe` — no runtime needed | | **Native Windows** | First-class Windows support, unlike Python/Node | | **Goroutines** | Perfect for 100+ concurrent WebSocket connections + mining workers | | **CGo** | Can call RandomX C library directly for hashing | | **Performance** | Near-C performance for hashing, excellent for networking | | **embed.FS** | Embed the React dashboard directly in the server binary | | **Small binary** | Server ~15MB, Agent ~10MB (with RandomX) | | **Cross-compile** | Build for any platform from any platform | --- ## 13. MVP (Minimum Viable Product) Scope If you want to start small and iterate, here's the MVP: 1. **Cloudflare Tunnel** — Get `pool.yourdomain.com` pointing to your local PC 2. **Server** — WebSocket hub + Stratum bridge to a public pool 3. **Miner Builder** — Web form that generates custom `.exe` with baked-in config 4. **Agent** — Connects to server, hashes with RandomX, submits shares 5. **Dashboard** — Simple page showing agent list + total hashrate This gets you mining in ~2 weeks. Then add features incrementally. --- ## 14. What You Need to Get Started 1. **Go installed** on your Windows machine (go.dev/dl) 2. **Node.js** for building the React dashboard 3. **Cloudflare account** (free) with your domain's DNS managed there 4. **cloudflared** installed on your Windows machine 5. **A Monero wallet address** (for payouts from the public pool) 6. **Visual Studio Build Tools** or MinGW-w64 (for compiling RandomX C library) --- ## 15. Questions for You 1. **Monero wallet**: Do you have an XMR wallet address ready? 2. **Domain**: Is your domain already on Cloudflare DNS? 3. **Go experience**: Have you used Go before, or is this new to you? 4. **Build tools**: Do you have Visual Studio Build Tools or MinGW-w64 installed for C compilation? 5. **Dashboard auth**: Do you want password protection on the Command Deck, or is it just you accessing it locally? 6. **Public pool preference**: Any preference on which Monero pool to connect through? (supportxmr.com, minexmr.com, etc.)