Mining/docs/development/architecture.md

Architecture

This document provides a detailed overview of the Mining Platform architecture, design decisions, and component interactions.

High-Level Architecture

The Mining Platform follows a modular, layered architecture:

┌─────────────────────────────────────────────────────────┐
│                    User Interfaces                       │
│  ┌──────────┐  ┌───────────────┐  ┌─────────────────┐  │
│  │   CLI    │  │ Web Dashboard │  │ Desktop App     │  │
│  │  (Cobra) │  │   (Angular)   │  │  (Wails+Angular)│  │
│  └────┬─────┘  └───────┬───────┘  └────────┬────────┘  │
└───────┼────────────────┼───────────────────┼───────────┘
        │                │                   │
        └────────────────┼───────────────────┘
                         │
┌────────────────────────┼───────────────────────────────┐
│                 REST API Layer (Gin)                    │
│                  /api/v1/mining/*                       │
└────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────┼───────────────────────────────┐
│              Core Business Logic (pkg/mining)           │
│  ┌──────────────┐  ┌─────────────┐  ┌───────────────┐ │
│  │   Manager    │  │   Miner     │  │   Profile     │ │
│  │  Interface   │  │ Implemen-   │  │   Manager     │ │
│  │              │  │   tations   │  │               │ │
│  └──────┬───────┘  └──────┬──────┘  └───────┬───────┘ │
└─────────┼──────────────────┼─────────────────┼─────────┘
          │                  │                 │
┌─────────┼──────────────────┼─────────────────┼─────────┐
│    System Layer (OS, Filesystem, Processes)             │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Mining Software (XMRig, T-Rex, lolMiner, etc.)  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Core Components

Manager Interface

The ManagerInterface is the central abstraction for miner lifecycle management.

Location: pkg/mining/manager.go

Purpose:

• Provides a contract for miner operations
• Enables testing through mocking
• Supports multiple miner implementations
• Manages running miners in-memory

Interface Definition:

type ManagerInterface interface {
    StartMiner(minerType string, config *Config) (Miner, error)
    StopMiner(name string) error
    GetMiner(name string) (Miner, error)
    ListMiners() []Miner
    ListAvailableMiners() []AvailableMiner
    GetMinerHashrateHistory(name string) ([]HashratePoint, error)
    Stop()
}

Implementation Details:

• Maintains a map[string]Miner for running miners
• Automatically collects statistics every 10 seconds
• Supports autostart from configuration
• Thread-safe with mutex locks

Miner Interface

The Miner interface defines the contract for all miner implementations.

Location: pkg/mining/mining.go

Interface Definition:

type Miner interface {
    GetName() string
    GetStats() (*PerformanceMetrics, error)
    Stop() error
    IsRunning() bool
    GetConfig() *Config
    GetHashrateHistory() []HashratePoint
}

Implementations:

• XMRigMiner: CPU/GPU mining for RandomX and CryptoNight
• TRexMiner: NVIDIA GPU mining for KawPow, Ethash (future)
• LolMiner: AMD/NVIDIA mining for Ethash, Beam (future)

BaseMiner

Provides shared functionality for all miner implementations.

Location: pkg/mining/miner.go

Features:

• Binary discovery and installation
• Archive extraction (tar.gz, tar.xz, zip)
• Download from URLs with progress tracking
• Hashrate history management
• XDG directory compliance

Key Methods:

func (m *BaseMiner) InstallFromURL(url string) error
func (m *BaseMiner) FindBinary(name string) (string, error)
func (m *BaseMiner) AddHashratePoint(hashrate float64)
func (m *BaseMiner) GetHashrateHistory() []HashratePoint

Hashrate History:

• High-resolution: 10-second intervals, 5-minute retention
• Low-resolution: 1-minute averages, 24-hour retention
• Automatically manages data retention

XMRig Implementation

Complete implementation for XMRig miner.

Files:

• pkg/mining/xmrig.go: Core implementation
• pkg/mining/xmrig_start.go: Startup logic
• pkg/mining/xmrig_stats.go: Statistics parsing

Architecture:

┌─────────────────────────────────────────────┐
│           XMRigMiner                        │
│  ┌─────────────────────────────────────┐   │
│  │        BaseMiner (embedded)         │   │
│  │  - Binary management                │   │
│  │  - Hashrate history                 │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  Start() → Generate config.json            │
│         → Execute xmrig binary             │
│         → Capture stdout/stderr            │
│         → Monitor process                  │
│                                             │
│  GetStats() → Poll HTTP API                │
│            → Parse JSON response           │
│            → Return PerformanceMetrics     │
│                                             │
│  Stop() → Send SIGTERM                     │
│        → Wait for graceful shutdown        │
│        → Force kill if needed              │
└─────────────────────────────────────────────┘

Configuration Generation:

• Creates JSON config file
• Supports CPU and GPU mining
• Handles pool authentication
• Manages algorithm selection
• Configures API endpoint for stats

Statistics Collection:

• Polls XMRig HTTP API (default: http://127.0.0.1:44321/1/summary)
• Parses JSON response
• Extracts hashrate, shares, connection info
• Updates hashrate history

Service Layer (REST API)

Exposes the Manager functionality via HTTP endpoints.

Location: pkg/mining/service.go

Framework: Gin Web Framework

Features:

• RESTful API design
• Swagger documentation
• CORS support
• JSON request/response
• Error handling middleware
• Route grouping

Route Organization:

/api/v1/mining
├── /info                    # GET - System info
├── /doctor                  # POST - Diagnostics
├── /update                  # POST - Check updates
├── /miners
│   ├── /                    # GET - List miners
│   ├── /available           # GET - Available types
│   ├── /:miner_type         # POST - Start miner
│   ├── /:miner_name         # DELETE - Stop miner
│   ├── /:miner_name/stats   # GET - Get statistics
│   ├── /:miner_type/install # POST - Install miner
│   └── /:miner_type/uninstall # DELETE - Uninstall
└── /profiles
    ├── /                    # GET - List profiles
    ├── /                    # POST - Create profile
    ├── /:id                 # GET - Get profile
    ├── /:id                 # PUT - Update profile
    ├── /:id                 # DELETE - Delete profile
    └── /:id/start           # POST - Start from profile

Middleware Stack:

1. Logger
2. Recovery (panic handler)
3. CORS
4. Request validation
5. Response formatter

Profile Manager

Manages saved mining configurations.

Location: pkg/mining/profile_manager.go

Storage: JSON file at ~/.config/lethean-desktop/mining_profiles.json

Data Structure:

type MiningProfile struct {
    ID          string    `json:"id"`
    Name        string    `json:"name"`
    Description string    `json:"description,omitempty"`
    MinerType   string    `json:"minerType"`
    Config      *Config   `json:"config"`
    CreatedAt   time.Time `json:"createdAt"`
    UpdatedAt   time.Time `json:"updatedAt"`
}

Features:

• CRUD operations for profiles
• UUID-based profile IDs
• Atomic file writes
• Import/export support
• Validation

Config Manager

Handles autostart and last-used configurations.

Location: pkg/mining/config_manager.go

Storage: JSON file at ~/.config/lethean-desktop/mining_config.json

Features:

• Autostart configuration
• Last-used miner configs
• Preference storage
• Default settings

Data Flow

Starting a Miner

User Request
    │
    ├─→ CLI: miner-ctrl start xmrig --config config.json
    ├─→ API: POST /api/v1/mining/miners/xmrig
    └─→ Desktop: profileManager.start(profileId)
    │
    ▼
Service Layer (service.go)
    │
    ├─→ Validate request
    ├─→ Parse configuration
    └─→ Call manager.StartMiner()
    │
    ▼
Manager (manager.go)
    │
    ├─→ Check if miner already running
    ├─→ Validate configuration
    └─→ Create miner instance
    │
    ▼
Miner Implementation (xmrig.go)
    │
    ├─→ Generate config.json
    ├─→ Find/verify binary
    ├─→ Execute miner process
    ├─→ Capture output streams
    └─→ Start statistics collection
    │
    ▼
Manager
    │
    ├─→ Store miner in running map
    └─→ Return miner instance
    │
    ▼
Service Layer
    │
    ├─→ Format response
    └─→ Return HTTP 200/201

Collecting Statistics

Background goroutine (every 10s)
    │
    ▼
For each running miner:
    │
    ├─→ miner.GetStats()
    │       │
    │       ├─→ Poll HTTP API
    │       ├─→ Parse JSON
    │       └─→ Return PerformanceMetrics
    │
    ├─→ Extract hashrate
    └─→ miner.AddHashratePoint(hashrate)
            │
            ├─→ Store in high-res buffer
            ├─→ Update low-res averages
            └─→ Prune old data

Retrieving Statistics (API Request)

Client: GET /api/v1/mining/miners/xmrig/stats
    │
    ▼
Service Layer
    │
    ├─→ Extract miner name
    └─→ Call manager.GetMiner(name)
    │
    ▼
Manager
    │
    ├─→ Lookup in miners map
    └─→ Return miner instance
    │
    ▼
Service Layer
    │
    ├─→ Call miner.GetStats()
    ├─→ Format response
    └─→ Return JSON

Frontend Architecture (Angular)

Component Hierarchy

AppComponent
├── DashboardPage
│   ├── MinerStatusCard
│   ├── HashrateCard
│   ├── SharesCard
│   └── EarningsCard
├── MinersPage
│   ├── RunningMinersList
│   │   └── MinerCard
│   └── AvailableMinersList
│       └── MinerInstallCard
├── ProfilesPage
│   ├── ProfileList
│   │   └── ProfileCard
│   └── ProfileEditor
├── StatisticsPage
│   ├── HashrateChart
│   ├── SharesChart
│   └── TimeRangeSelector
├── PoolsPage
│   ├── RecommendedPools
│   └── CustomPoolForm
├── AdminPage
│   ├── SystemInfo
│   ├── MinerManagement
│   └── DiagnosticsPanel
└── SettingsPage
    ├── GeneralSettings
    ├── NotificationSettings
    └── AdvancedSettings

Services

MinerService

• API communication
• Miner lifecycle management
• Statistics fetching

ProfileService

• Profile CRUD operations
• Profile storage
• Import/export

WebSocketService

• Real-time updates
• Event notifications
• Connection management

ThemeService

• Theme switching
• Preference persistence

State Management

The application uses RxJS for state management:

• Services emit observables
• Components subscribe to updates
• Automatic cleanup on destroy
• Centralized error handling

Desktop Application (Wails)

Architecture

┌─────────────────────────────────────────┐
│         Go Backend (main.go)            │
│  ┌───────────────────────────────────┐  │
│  │     MiningService                 │  │
│  │  - Wraps pkg/mining.Manager       │  │
│  │  - Exposes methods to frontend    │  │
│  └────────────┬──────────────────────┘  │
└───────────────┼─────────────────────────┘
                │ Wails Bindings
┌───────────────┼─────────────────────────┐
│         TypeScript Frontend             │
│  ┌────────────┴──────────────────────┐  │
│  │   Angular Application             │  │
│  │ (Embedded from ui/dist/browser)   │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

MiningService (miningservice.go):

• Binds Go methods to frontend
• Handles lifecycle events
• Manages application state
• Provides system tray integration

Auto-generated Bindings (frontend/bindings/):

• TypeScript definitions
• Type-safe Go method calls
• Event system integration

Modified XMRig Core

OpenCL Backend

Location: miner/core/src/backend/opencl/

Supported Algorithms:

• ETChash (Ethereum Classic)
• ProgPowZ (Zano)
• KawPow (Ravencoin)

Key Files:

• cl/etchash/: OpenCL kernels for ETChash
• cl/progpowz/: OpenCL kernels for ProgPowZ
• runners/OclEtchashRunner.*: ETChash GPU runner
• runners/OclProgPowZRunner.*: ProgPowZ GPU runner

Algorithm Implementations

Location: miner/core/src/crypto/

ETChash:

• ETCCache.cpp/h: DAG cache management
• Ethash variant optimized for ETC

ProgPowZ:

• Custom ProgPow variant for Zano
• Period-based algorithm rotation

Build System

CMake-based build with conditional compilation:

option(WITH_OPENCL "Enable OpenCL backend" ON)
option(WITH_CUDA "Enable CUDA backend" ON)

Automatically detects:

• OpenCL SDK
• CUDA Toolkit
• GPU capabilities

Security Considerations

API Security

• No authentication by default (local use)
• Consider reverse proxy for production
• CORS enabled for web component
• Input validation on all endpoints

File System

• XDG Base Directory compliance
• Restricted file permissions (0644 for config, 0755 for binaries)
• Atomic file writes for configs
• Safe path handling (no path traversal)

Process Management

• Graceful shutdown (SIGTERM → SIGKILL)
• Process isolation
• Resource limits (if configured)
• Log rotation

Performance Optimizations

Hashrate History

• Two-tier storage (high-res + low-res)
• Automatic data pruning
• In-memory ring buffers
• Minimal memory footprint

Statistics Collection

• Background goroutine (non-blocking)
• Cached HTTP requests
• JSON parsing optimization
• Error resilience

Frontend

• Lazy loading of routes
• Virtual scrolling for large lists
• Chart data decimation
• Debounced API calls

Extensibility

Adding New Miners

1. Implement Miner interface
2. Extend BaseMiner for common functionality
3. Register in Manager
4. Add API endpoints if needed

Adding New Algorithms

1. Add algorithm support to miner core
2. Update configuration structs
3. Add validation rules
4. Update UI selectors

Adding New Frontends

The REST API is frontend-agnostic:

• Mobile apps (React Native, Flutter)
• CLI tools
• Third-party integrations
• Monitoring dashboards

Deployment Patterns

Single User (Local)

User Machine
├── miner-ctrl (CLI/API server)
├── Browser (accessing localhost:8080)
└── Mining software (XMRig, etc.)

Multi-User (Server)

Server
├── miner-ctrl (API server on 0.0.0.0:8080)
└── Mining software

Reverse Proxy (nginx)
├── HTTPS termination
├── Authentication
└── Rate limiting

Clients
├── Web browsers
├── Mobile apps
└── API clients

Desktop (Standalone)

Single Binary (Wails)
├── Embedded API server
├── Embedded frontend
└── Integrated mining software

Next Steps

• Review Development Guide for setup instructions
• Read Contributing Guidelines for contribution process
• See API Documentation for endpoint details