Mining/README.md

# Mining

[![Go Version](https://img.shields.io/badge/go-1.24+-blue.svg)](https://golang.org)
[![GoDoc](https://pkg.go.dev/badge/github.com/Snider/Mining.svg)](https://pkg.go.dev/github.com/Snider/Mining)
[![Go Report Card](https://goreportcard.com/badge/github.com/Snider/Mining)](https://goreportcard.com/report/github.com/Snider/Mining)
[![codecov](https://codecov.io/gh/Snider/Mining/branch/main/graph/badge.svg)](https://codecov.io/gh/Snider/Mining)
[![Release](https://img.shields.io/github/release/Snider/Mining.svg)](https://github.com/Snider/Mining/releases)
[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](https://opensource.org/license/eupl-1-2)

A modern, modular cryptocurrency mining management platform with GPU support, RESTful API, and cross-platform desktop application.

<img width="834" height="657" alt="Mining Dashboard" src="https://github.com/user-attachments/assets/d4fc4704-819c-4aca-bcd3-ae4af6e25c1b" />

## Features

### Supported Algorithms

| Algorithm | Coin | CPU | GPU (OpenCL) | GPU (CUDA) |
|-----------|------|-----|--------------|------------|
| RandomX | Monero (XMR) | ✅ | ✅ | ✅ |
| KawPow | Ravencoin (RVN) | ❌ | ✅ | ✅ |
| ETChash | Ethereum Classic (ETC) | ❌ | ✅ | ✅ |
| ProgPowZ | Zano (ZANO) | ❌ | ✅ | ✅ |
| Blake3 | Decred (DCR) | ✅ | ✅ | ✅ |
| CryptoNight | Various | ✅ | ✅ | ✅ |

### Core Capabilities

- **Multi-Algorithm Mining**: Support for CPU and GPU mining across multiple algorithms
- **Dual Mining**: Run CPU and GPU mining simultaneously with separate pools
- **Profile Management**: Save and switch between mining configurations
- **Real-time Monitoring**: Live hashrate, shares, and performance metrics
- **RESTful API**: Full control via HTTP endpoints with Swagger documentation
- **Web Dashboard**: Embeddable Angular web component for any application
- **Desktop Application**: Native cross-platform app built with Wails v3
- **Mobile Responsive**: Touch-friendly UI with drawer navigation

### Mining Software

Manages installation and configuration of:
- **XMRig** - High-performance CPU/GPU miner (RandomX, CryptoNight)
- **T-Rex** - NVIDIA GPU miner (KawPow, Ethash, and more)
- **lolMiner** - AMD/NVIDIA GPU miner (Ethash, Beam, Equihash)
- **TT-Miner** - NVIDIA GPU miner (Ethash, KawPow, Autolykos2)

## Quick Start

### CLI

```bash
# Install
go install github.com/Snider/Mining/cmd/mining@latest

# Start the API server
miner-ctrl serve --host localhost --port 9090

# Or use the interactive shell
miner-ctrl serve
```

### Web Component

```html
<script type="module" src="./mbe-mining-dashboard.js"></script>
<snider-mining api-base-url="http://localhost:9090/api/v1/mining"></snider-mining>
```

### Desktop Application

Download pre-built binaries from [Releases](https://github.com/Snider/Mining/releases) or build from source:

```bash
cd cmd/desktop/mining-desktop
wails3 build
```

## Architecture

```
Mining/
├── cmd/
│   ├── mining/              # CLI application
│   └── desktop/             # Wails desktop app
├── pkg/mining/              # Core Go package
│   ├── mining.go            # Interfaces and types
│   ├── manager.go           # Miner lifecycle management
│   ├── service.go           # RESTful API (Gin)
│   ├── xmrig.go             # XMRig implementation
│   └── profile_manager.go   # Profile persistence
├── miner/core/              # Modified XMRig with algorithm support
│   └── src/
│       ├── backend/opencl/  # OpenCL GPU kernels
│       ├── backend/cuda/    # CUDA GPU kernels
│       └── crypto/          # Algorithm implementations
└── ui/                      # Angular 20+ web dashboard
    └── src/app/
        ├── components/      # Reusable UI components
        └── pages/           # Route pages
```

## API Reference

Base path: `/api/v1/mining`

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/info` | System info and installed miners |
| GET | `/miners` | List running miners |
| POST | `/miners/:name` | Start a miner |
| DELETE | `/miners/:name` | Stop a miner |
| GET | `/miners/:name/stats` | Get miner statistics |
| GET | `/profiles` | List saved profiles |
| POST | `/profiles` | Create a profile |
| PUT | `/profiles/:id` | Update a profile |
| DELETE | `/profiles/:id` | Delete a profile |
| POST | `/miners/:name/install` | Install miner software |

Swagger UI: `http://localhost:9090/api/v1/mining/swagger/index.html`

## Development

### Prerequisites

- Go 1.24+
- Node.js 20+ (for UI development)
- CMake 3.21+ (for miner core)
- OpenCL SDK (for GPU support)

### Build Commands

```bash
# Backend
make build              # Build CLI binary
make test               # Run tests with coverage
make dev                # Start dev server on :9090

# Frontend
cd ui
npm install
npm run build           # Build web component
npm test                # Run unit tests (36 specs)

# Desktop
cd cmd/desktop/mining-desktop
wails3 build            # Build native app

# Miner Core (GPU support)
cd miner/core
mkdir build && cd build
cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
make -j$(nproc)
```

## Configuration

Mining profiles are stored in `~/.config/lethean-desktop/mining_profiles.json`

Example profile:
```json
{
  "id": "uuid",
  "name": "My XMR Mining",
  "minerType": "xmrig",
  "config": {
    "pool": "stratum+tcp://pool.supportxmr.com:3333",
    "wallet": "YOUR_WALLET_ADDRESS",
    "algo": "rx/0"
  }
}
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the EUPL-1.2 License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [XMRig](https://github.com/xmrig/xmrig) - High performance miner
- [Wails](https://wails.io) - Desktop application framework
- [Angular](https://angular.io) - Web framework
- [Gin](https://gin-gonic.com) - HTTP web framework
- [Cobra](https://github.com/spf13/cobra) - CLI framework