Files

drjones 6c42f2b600 Complete private Monero miner control stack.

Implement Windows agent with RandomX mining and WebSocket fleet reporting, wire dashboard settings into the builder with saved exe paths, and add project README.

2026-05-26 22:51:47 -07:00

65 KiB

Raw Permalink Blame History

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:

Lets you configure agent parameters (server URL, wallet address, thread count, worker name)
Generates a unique .exe with those settings baked in at compile time
You download it, put it on a USB drive or network share, and run it on any Windows machine
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:

Connects to a public pool (like supportxmr.com, minexmr.com, etc.) via Stratum TCP
Receives jobs from the public pool
Distributes those jobs to your 100+ agents
Receives shares from your agents
Forwards valid shares to the public pool
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 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:

Connects to your .com endpoint via WebSocket (through Cloudflare Tunnel)
Receives mining jobs (block template + difficulty)
Hashes using RandomX
Submits shares back
Reports system stats (CPU usage, hashrate, temperature)
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)

// 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:

// 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:

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:

USB Drive — Copy to a USB, walk around and plug into each machine
Network Share — \\server\share\miner-office-pc.exe
Group Policy — Push via Windows GPO startup script
PDQ Deploy / SCCM — Enterprise deployment tools
Simple batch file — copy \\server\share\miner.exe C:\temp\ && start C:\temp\miner.exe
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

A domain name (e.g., yourdomain.com)
Cloudflare account (free tier)
Your domain's DNS managed by Cloudflare
cloudflared installed on your Windows machine

6.2 Setup Steps

# 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`

{
  "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:

Checks if Go is installed (prompts if not)
Builds the Go server binary
Builds the React dashboard (or uses pre-built)
Launches the server on port 8989
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

@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://).

// 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": "<hex-encoded>",
    "difficulty": 250000,
    "height": 3123456,
    "seed_hash": "<hex-encoded>",
    "target": "<hex-encoded>"
  }
}

// Agent -> Server: Share submission
{
  "type": "submit_share",
  "payload": {
    "job_id": "job-abc-123",
    "nonce": "<hex-encoded>",
    "hash": "<hex-encoded>",
    "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:

Cloudflare Tunnel — Get pool.yourdomain.com pointing to your local PC
Server — WebSocket hub + Stratum bridge to a public pool
Miner Builder — Web form that generates custom .exe with baked-in config
Agent — Connects to server, hashes with RandomX, submits shares
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

Go installed on your Windows machine (go.dev/dl)
Node.js for building the React dashboard
Cloudflare account (free) with your domain's DNS managed there
cloudflared installed on your Windows machine
A Monero wallet address (for payouts from the public pool)
Visual Studio Build Tools or MinGW-w64 (for compiling RandomX C library)

15. Questions for You

Monero wallet: Do you have an XMR wallet address ready?
Domain: Is your domain already on Cloudflare DNS?
Go experience: Have you used Go before, or is this new to you?
Build tools: Do you have Visual Studio Build Tools or MinGW-w64 installed for C compilation?
Dashboard auth: Do you want password protection on the Command Deck, or is it just you accessing it locally?
Public pool preference: Any preference on which Monero pool to connect through? (supportxmr.com, minexmr.com, etc.)

65 KiB Raw Permalink Blame History Unescape Escape

Custom XMR (Monero) Mining System — Architecture & Implementation Plan

1. Executive Summary

The Core Innovation: Miner Builder

2. System Architecture Overview

2.1 Why This Architecture is Better for You

2.2 The Monero Piece — You Don't Need monerod

3. RandomX Algorithm — What You Need to Know

4. Component Details

4.1 Windows Agent (agent/)

4.2 Control Server (server/)

4.3 Command Deck + Miner Builder (Web UI) (web/)

5. Miner Builder — The Core Innovation

5.1 How It Works

5.2 The Build Pipeline (Server-Side)

5.3 How the Baked-In Config Works

5.4 Build Optimization

5.5 Distribution Methods

5.6 Builder API Endpoints

6. Cloudflare Tunnel Setup

6.1 What You Need

6.2 Setup Steps

6.3 Result

7. Settings & Configuration UI

7.1 Settings Page Layout

7.2 Settings Saved to data/config.json

7.3 Feature Details

7.4 How Settings Flow to the Agent

7.5 Per-Agent Override (Remote Config Push)

8. Build Script & Self-Contained Operation

7.1 The One-Click Setup

7.2 What run.bat Does

7.3 Self-Contained Data Storage

7.4 What Happens When You Run It

7.5 Port 8989 Convention

8. Communication Protocol

7.1 WebSocket Message Format (Agent <-> Server)

7.2 REST API Endpoints

9. Security Considerations

10. Project Structure (Full)

11. Implementation Phases

Phase 1: Foundation + Build Script (Week 1)

Phase 2: Miner Builder (Week 2)

Phase 3: Mining Core (Week 3-4)

Phase 4: Agent Polish (Week 5)

Phase 5: Command Deck + Settings (Week 6)

Phase 6: Production Hardening (Week 7-8)

12. Why Go for Everything?

13. MVP (Minimum Viable Product) Scope

14. What You Need to Get Started

15. Questions for You

65 KiB

Raw Permalink Blame History

4.1 Windows Agent (`agent/`)

4.2 Control Server (`server/`)

4.3 Command Deck + Miner Builder (Web UI) (`web/`)

7.2 Settings Saved to `data/config.json`

7.2 What `run.bat` Does