Gupax is a (Windows|macOS|Linux) GUI for mining [**Monero**](https://github.com/monero-project/monero) on [**P2Pool**](https://github.com/SChernykh/p2pool), using [**XMRig**](https://github.com/xmrig/xmrig). **To see a 3-minute video on how to download and run Gupax: [click here.](#How-To)**
## Contents * [What is Monero/P2Pool/XMRig/Gupax?](#what-is-monerop2poolxmriggupax) * [How-To](#How-To) * [Simple](#Simple) - [Status](#Status) - [Gupax](#Gupax) - [P2Pool](#P2Pool) - [XMRig](#XMRig) * [Advanced](#Advanced) - [Verifying](#Verifying) - [Running a Local Monero Node](#running-a-local-monero-node) - [Command Line](#Command-Line) - [Key Shortcuts](#Key-Shortcuts) - [Resolution](#Resolution) - [Tor/Arti](#TorArti) - [Logs](#Logs) - [Disk](#Disk) - [Swapping P2Pool/XMRig](#Swapping-P2PoolXMRig) - [Status](#Status-1) - [Gupax](#Gupax-1) - [P2Pool](#P2Pool-1) - [XMRig](#XMRig-1) * [Connections](#Connections) * [Remote Monero Nodes](#remote-monero-nodes) * [Build](#Build) - [General Info](#General-Info) - [Linux](#Linux) - [Building for a distribution](#building-for-a-distribution) - [macOS](#macOS) - [Windows](#Windows) * [License](#License) * [FAQ](#FAQ) - [Where are updates downloaded from?](#where-are-updates-downloaded-from) - [P2Pool connection errors](#p2pool-connection-errors) - [Can I quit mid-update?](#can-i-quit-mid-update) - [Bundled vs Standalone](#bundled-vs-standalone) - [How much memory does Gupax use?](#how-much-memory-does-gupax-use) - [How is sudo handled? (on macOS/Linux)](#how-is-sudo-handled-on-macoslinux) - [Why does Gupax need to be Admin? (on Windows)](#why-does-gupax-need-to-be-admin-on-windows) ## What is Monero/P2Pool/XMRig/Gupax? **Monero** is a secure, private, and untraceable cryptocurrency. The [Monero GUI](https://github.com/monero-project/monero-gui) software lets you run a Monero node (among other things). A Monero node connects you to other peers and lets you download Monero's [blockchain](https://en.wikipedia.org/wiki/Blockchain). ***[More info here.](https://github.com/monero-project/monero)*** --- **P2Pool** is software that lets you create/join decentralized peer-to-peer Monero mining pools. P2Pool as a concept was [first developed for Bitcoin](https://en.bitcoin.it/wiki/P2Pool) but was [never fully realized](https://github.com/p2pool/p2pool) due to many limitations. These limitations were fixed when SChernykh rewrote P2Pool from scratch for Monero. P2Pool combines the best of solo mining and traditional pool mining: * ***It's decentralized:*** There's no central server that can be shutdown or pool admin that controls your hashrate * ***It's permissionless:*** It's peer-to-peer so there's no one to decide who can and cannot mine on the pool * ***It's trustless:*** Funds are never in custody, all pool blocks pay out to miners directly and immediately * **0% transaction fee, 0 payout fee, immediate ~0.0003 XMR minimum payout** ***[More info here.](https://github.com/SChernykh/p2pool)*** --- **XMRig** is an optimized miner which mines Monero at higher speeds. Both Monero and P2Pool have built in miners but XMRig is quite faster than both of them. Due to issues like [anti-virus flagging](https://github.com/monero-project/monero-gui/pull/3829#issuecomment-1018191461), it is not feasible to integrate XMRig directly into Monero or P2Pool, however, XMRig is still freely available for anyone to download with the caveat being: you have to set it up yourself. ***[More info here.](https://github.com/xmrig/xmrig)*** --- **Gupax** is a GUI that helps with configuring, updating, and managing P2Pool & XMRig (both originally CLI-only).   ***Recap:***   1. **XMRig** mines to **P2Pool** which fetchs blocks from a **Monero node**   2. **Monero GUI** runs the ***Monero node***   3. **Gupax** runs ***P2Pool/XMRig***
By default, though, Gupax will use a [Remote Monero Node](#remote-monero-nodes) so you don't even have to run your own full Monero node to start mining on P2Pool:
## How-To https://user-images.githubusercontent.com/101352116/207978455-6ffdc0cc-204c-4594-9a2f-e10c505745bc.mp4 1. [Download the bundled version of Gupax for your OS here](https://github.com/hinto-janaiyo/gupax/releases) or from [gupax.io](https://gupax.io/downloads) 2. Extract somewhere (Desktop, Documents, etc) 3. Launch Gupax 4. Input your Monero address in the `[P2Pool]` tab 5. Select a [`Remote Monero Node`](#remote-monero-nodes) that you trust 5. Start P2Pool 6. Start XMRig You are now mining to your own instance of P2Pool, welcome to the world of decentralized peer-to-peer mining! _Notes:_ - _[What is bundled? What is standalone?](#bundled-vs-standalone)_ - _If you'd like to get deeper into the settings, see [Advanced.](#advanced)_ ## Simple The `Gupax/P2Pool/XMRig` tabs have two versions, `Simple` & `Advanced`. `Simple` is for a minimal & working out-of-the-box configuration. --- ### Status This tab has 2 submenus that show some info about running processes and P2Pool-specific stats. **Processes:** This submenu shows: - General PC stats - General P2Pool stats - General XMRig stats
**P2Pool:** This submenu shows: - ***Permanent*** stats on all your payouts received via P2Pool & Gupax - Payout sorting options - Share/block time calculator
--- ### Gupax This tab has the updater and general Gupax settings. If `Check for updates` is pressed, Gupax will update your `Gupax/P2Pool/XMRig` (if needed) using the [GitHub API](#where-are-updates-downloaded-from). Below that, there are some general Gupax settings: | Setting | What does it do? | |--------------------|-------------------| | `Update via Tor` | Causes updates to be fetched via the Tor network. Tor is embedded within Gupax; a Tor system proxy is not required | `Auto-Update` | Gupax will automatically check for updates at startup | `Auto-P2Pool` | Gupax will automatically start P2Pool at startup | `Auto-XMRig` | Gupax will automatically start XMRig at startup | `Ask before quit` | Gupax will ask before quitting (and notify if there are any updates/processes still alive) | `Save before quit` | Gupax will automatically saved any un-saved setting on quit --- ### P2Pool P2Pool Simple allows you to ping & connect to a [Remote Monero Node](#remote-monero-nodes) and start your own local P2Pool instance on the `Mini` sidechain. To start P2Pool, first input the Monero address you'd like to receive payouts from. You must use a primary Monero address to mine on P2Pool (starts with a 4). It is highly recommended to create a new wallet since addresses are public on P2Pool! **Warning: [There are negative privacy/security implications when using a Monero node not in your control.](https://www.getmonero.org/resources/moneropedia/remote-node.html)** Select a remote node that you trust, or better yet, run your own node. If you'd like to manually specify a node to connect to, see [Advanced.](#advanced) --- ### XMRig XMRig Simple has a log output box, a thread slider, and `Pause-on-active` setting. If XMRig is started with `Pause-on-active` with a value greater than 0, XMRig will automatically pause for that many seconds if it detects any user activity (mouse movements, keyboard clicks). [This setting is only available on Windows/macOS.](https://xmrig.com/docs/miner/config/misc#pause-on-active) **Windows:** Gupax will automatically launch XMRig with administrator privileges to activate [mining optimizations.](https://xmrig.com/docs/miner/randomx-optimization-guide) XMRig also needs a [signed WinRing0 driver (© 2007-2009 OpenLibSys.org)](https://xmrig.com/docs/miner/randomx-optimization-guide/msr#manual-configuration) to access MSR registers. This is the file next to XMRig called `WinRing0x64.sys`. This comes in the bundled version of Gupax. If missing/deleted, a copy is packaged with all [Windows XMRig releases.](https://github.com/xmrig/xmrig/releases/) A direct standalone version is also provided, [here.](https://github.com/xmrig/xmrig/blob/master/bin/WinRing0/WinRing0x64.sys) **macOS/Linux:** Gupax will prompt for your `sudo` password to start XMRig with and do all the things above. XMRig Simple will always mine to your own local P2Pool (`127.0.0.1:3333`), if you'd like to manually specify a pool to mine to, see [Advanced](#advanced). ## Advanced ### Verifying It is recommended to verify the hash and PGP signature of the download before using Gupax. Download the [`SHA256SUMS`](https://github.com/hinto-janaiyo/gupax/releases/latest) file, download and import my [`PGP key`](https://github.com/hinto-janaiyo/gupax/blob/main/pgp/hinto-janaiyo.asc), and verify: ```bash sha256sum -c SHA256SUMS gpg --import hinto-janaiyo.asc gpg --verify SHA256SUMS ``` Q: How can I be sure the P2Pool/XMRig bundled with Gupax hasn't been tampered with? A: Verify the hash. You can always compare the hash of the `P2Pool/XMRig` binaries bundled with Gupax with the hashes of the binaries found here: - https://github.com/SChernykh/p2pool/releases - https://github.com/xmrig/xmrig/releases Make sure the _version_ you are comparing against is correct, and make sure you are comparing the _binary_ to the _binary_, not the `tar/zip`. If they match, you can be sure they are the exact same. Verifying the PGP signature is also recommended: - P2Pool - [`SChernykh.asc`](https://github.com/monero-project/gitian.sigs/blob/master/gitian-pubkeys/SChernykh.asc) - XMRig - [`xmrig.asc`](https://github.com/xmrig/xmrig/blob/master/doc/gpg_keys/xmrig.asc) --- ### Running a Local Monero Node Running and using your own local Monero node improves privacy and security. It also means you won't be depending on one of the [Remote Monero Nodes](#remote-monero-nodes) provided by Gupax. This comes at the cost of downloading and syncing Monero's blockchain yourself (currently `155GB`). If you'd like to run and use your own local Monero node for P2Pool, follow these steps:
1. In the Monero GUI, go to `Settings` 2. Go to the `Node` tab 3. Enable `Local node` 4. Enter `--zmq-pub=tcp://127.0.0.1:18083` into `Daemon startup flags` After syncing the blockchain, you will now have your own Monero node. The 4th step enables `ZMQ`, which is extra Monero node functionality that is needed for P2Pool to work correctly. [For much more detailed information on configuring a Monero node, click here.](https://monerodocs.org) --- ### Command Line Gupax comes with some command line options: ``` USAGE: ./gupax [--flag] --help Print this help message --version Print version and build info --state Print Gupax state --nodes Print the manual node list --payouts Print the P2Pool payout log, payout count, and total XMR mined --no-startup Disable all auto-startup settings for this instance (auto-update, auto-ping, etc) --reset-state Reset all Gupax state (your settings) --reset-nodes Reset the manual node list in the [P2Pool] tab --reset-pools Reset the manual pool list in the [XMRig] tab --reset-payouts Reset the permanent P2Pool stats that appear in the [Status] tab --reset-all Reset the state, manual node list, manual pool list, and P2Pool stats --ferris Print an extremely cute crab ``` By default, Gupax has `auto-update` & `auto-ping` enabled. This can only be turned off in the GUI which causes a chicken-and-egg problem. To get around this, start Gupax with `--no-startup`. This will disable all `auto` features for that instance. --- ### Key Shortcuts The letter keys (Z/X/C/V/S/R) will only work if nothing is in focus, i.e, you _are not_ editing a text box. An ALT+F4 will also trigger the exit confirm screen (if enabled). ``` *---------------------------------------* | Key shortcuts | |---------------------------------------| | F11 | Fullscreen | | Escape | Quit screen | | Up | Start/Restart | | Down | Stop | | Z | Left Tab | | X | Right Tab | | C | Left Submenu | | V | Right Submenu | | S | Save | | R | Reset | *---------------------------------------* ``` --- ### Resolution The default resolution of Gupax is `1280x960` which is a `4:3` aspect ratio. This can be changed by dragging the corner of the window itself or by using the resolution sliders in the `Gupax Advanced` tab. After a resolution change, Gupax will fade-in/out of black and will take a second to resize all the UI elements to scale correctly to the new resolution. If you have changed your OS's pixel scaling, you may need to resize Gupax to see all UI correctly. The minimum window size is: `640x480` The maximum window size is: `3840x2160` Fullscreen mode can also be entered by pressing `F11`. --- ### Tor/Arti By default, Gupax updates via Tor. In particular, it uses [`Arti`](https://gitlab.torproject.org/tpo/core/arti), the official Rust implementation of Tor. Instead of bootstrapping onto the Tor network every time, Arti saves state/cache about the Tor network (circuits, guards, etc) for later reuse onto the disk: State: | OS | Data Folder | |----------|---------------------------------------------------------------| | Windows | `C:\Users\USER\AppData\Local\torproject\Arti\data` | | macOS | `/Users/USER/Library/Application Support/org.torproject.Arti` | | Linux | `/home/USER/.local/share/arti` | Cache: | OS | Data Folder | |----------|---------------------------------------------------------------| | Windows | `C:\Users\USER\AppData\Local\torproject\Arti\cache` | | macOS | `/Users/USER/Library/Caches/org.torproject.Arti` | | Linux | `/home/USER/.cache/arti` | --- ### Disk Long-term state is saved onto the disk in the "OS data folder", using the [TOML](https://github.com/toml-lang/toml) format. If not found, default files will be created. Given a slightly corrupted `state.toml` file, Gupax will attempt to merge it with a new default one. This will most likely happen if the internal data structure of `state.toml` is changed in the future (e.g removing an outdated setting). The node/pool database cannot be merged. If Gupax can't read/write to disk at all, or if there are any other big issues, it will show an unrecoverable error screen. | OS | Data Folder | Example | |----------|------------------------------------------|-------------------------------------------------| | Windows | `{FOLDERID_RoamingAppData}` | `C:\Users\USER\AppData\Roaming\Gupax` | | macOS | `$HOME`/Library/Application Support | `/Users/USER/Library/Application Support/Gupax` | | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | `/home/USER/.local/share/gupax` | The current files saved to disk: * `state.toml` Gupax state/settings * `node.toml` The manual node database used for P2Pool advanced * `pool.toml` The manual pool database used for XMRig advanced * `p2pool/` The Gupax-P2Pool API files --- ### Logs Gupax has console logs that show with increasing detail, what exactly it is is doing. There are multiple log filter levels but by default, `INFO` and above are enabled. To view more detailed console debug information, start Gupax with the environment variable `RUST_LOG` set to a log level like so: ```bash RUST_LOG=(trace|debug|info|warn|error) ./gupax ``` For example: ```bash RUST_LOG=debug ./gupax ``` In general: - `ERROR` means something has gone wrong and that something will probably break - `WARN` means something has gone wrong, but things will be fine - `INFO` logs are general info about what Gupax (the GUI thread) is currently doing - `DEBUG` logs are much more verbose and include what EVERY thread is doing (not just the main GUI thread) - `TRACE` logs are insanely verbose and shows very low-level logs of the libraries Gupax uses (HTTP connections, GUI polling, etc) --- ### Swapping P2Pool/XMRig If you want to use your own `P2Pool/XMRig` binaries you can: - Edit the PATH in `Gupax Advanced` to point at the new binaries - Change the binary itself By default, Gupax will look for `P2Pool/XMRig` in folders next to itself: Windows: ``` Gupax\ ├─ Gupax.exe ├─ P2Pool\ │ ├─ p2pool.exe ├─ XMRig\ ├─ xmrig.exe ``` macOS (Gupax is packaged as an `.app` on macOS): ``` Gupax.app/Contents/MacOS/ ├─ gupax ├─ p2pool/ │ ├─ p2pool ├─ xmrig/ ├─ xmrig ``` Linux: ``` gupax/ ├─ gupax ├─ p2pool/ │ ├─ p2pool ├─ xmrig/ ├─ xmrig ``` --- ### Status The `[P2Pool]` submenu in this tab reads/writes to a file-based API in a folder called `p2pool` located in the [Gupax OS data directory:](#Disk) | File | Purpose | Specific Data Type | |----------|---------------------------------------------------------|--------------------| | `log` | Formatted payout lines extracted from P2Pool | Basically a `String` that needs to be parsed correctly | `payout` | The total amount of payouts received via P2Pool & Gupax | `u64` | `xmr` | The total amount of XMR mined via P2Pool & Gupax | Atomic Units represented with a `u64` The `log` file contains formatted payout lines extracted from your P2Pool: ```