Gupax is a GUI for mining Monero on P2Pool, using XMRig.

To see a 3-minute video guide on how to set-up Gupax: click here.

Contents

• What is Monero/P2Pool/XMRig/Gupax?
• Guide
• Simple
  • Status
  • Gupax
  • P2Pool
  • XMRig
• Advanced
  • Verifying
  • Running a Local Monero node
  • Command Line
  • Key Shortcuts
  • Tor
  • Logs
  • Disk
  • Swapping P2Pool/XMRig
  • Status
  • Gupax
  • P2Pool
  • XMRig
• Connections
• Remote Monero nodes
• Build
  • General Info
  • Linux
    • Building for a distribution
  • macOS
  • Windows
• License
• FAQ
  • System requirements
  • Gupax does not start
  • Where are updates downloaded from?
  • P2Pool connection errors
  • Can I quit mid-update?
  • Bundled vs Standalone
  • How much memory does Gupax use?
  • How is sudo handled? (on macOS/Linux)
  • Why does Gupax need to be Admin? (on Windows)

What is Monero/P2Pool/XMRig/Gupax?

Monero is a secure, private, and untraceable cryptocurrency.

Monero GUI allows you to run a Monero node, among other things.

---

P2Pool allows you to create/join decentralized peer-to-peer Monero mining pools.

P2Pool as a concept was first developed for Bitcoin although failed to stay relevant for various reasons.

In late 2021, 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.00027 XMR minimum payout

---

XMRig is an optimized miner that can mine Monero.

Both Monero and P2Pool have built in miners but XMRig is faster than both of them. Due to issues like anti-virus flagging, it is not feasible to integrate XMRig directly into Monero.

---

Gupax is a GUI that helps manage P2Pool & XMRig which are both CLI-only.

XMRig mines to P2Pool

P2Pool fetches blocks from a Monero node

Monero GUI runs the Monero node

Gupax runs P2Pool/XMRig

---

By default, Gupax will use a Remote Monero node so you don't have to run your own Monero node to start mining on P2Pool.

Guide

https://user-images.githubusercontent.com/101352116/207978455-6ffdc0cc-204c-4594-9a2f-e10c505745bc.mp4

1. Download the bundled version of Gupax
2. Extract
3. Launch Gupax
4. Input your Monero address in the P2Pool tab
5. Select a Remote Monero node (or run your own local Monero node)
6. Start P2Pool
7. Start XMRig

You are now mining to your own instance of P2Pool, welcome to the world of decentralized peer-to-peer mining!

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 3 submenus.

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

Benchmarks:
This submenu shows:

• Your hashrate vs others with the same CPU
• List of similar CPUs and their stats
• Data source: here

---

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.

Below that, there are some general Gupax settings:

Setting	What it does
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 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. 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.

---

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.

Windows:
Gupax will automatically launch XMRig with administrator privileges to activate mining optimizations. XMRig also needs a signed WinRing0 driver (© 2007-2009 OpenLibSys.org) 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. A direct standalone version is also provided, here.

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

Verifying

It is recommended to verify the hash and PGP signature of the download before using Gupax.

Download the SHA256SUMS file, download and import this PGP key, and verify:

sha256sum -c SHA256SUMS
gpg --import hinto-janai.asc
gpg --verify SHA256SUMS

You can 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, they are the exact same. Verifying the PGP signature is also recommended:

• P2Pool - SChernykh.asc
• XMRig - 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 provided by Gupax. This comes at the cost of downloading and syncing Monero's blockchain yourself.

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
5. (Optionally) enter --disable-dns-checkpoints --enable-dns-blocklist into Daemon startup flags
6. Start and fully sync node

The 4th step enables ZMQ, which is extra Monero node functionality that is needed for P2Pool to work correctly.

The 5th step:

• --disable-dns-checkpoints avoids periodical lag when DNS is updated (it's not needed when mining)
• --enable-dns-blocklist bans known bad nodes

---

Command Line

By default, Gupax has auto-update & auto-ping enabled. This can only be turned off in the GUI. To get around this, start Gupax with --no-startup. This will disable all auto features for that instance.

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

---

Key Shortcuts

*---------------------------------------*
|             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               |
*---------------------------------------*

---

Tor

By default, Gupax updates via Tor. In particular, it uses Arti, the official Rust implementation of Tor.

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

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:

RUST_LOG=(trace|debug|info|warn|error) ./gupax

For example:

RUST_LOG=debug ./gupax

• ERROR: has gone wrong and that something will probably break
• WARN: something has gone wrong, but things will be fine
• INFO: general info about what Gupax (the GUI thread) is currently doing
• DEBUG: much more verbose and include what EVERY thread is doing (not just the main GUI thread)
• TRACE: insanely verbose and shows very low-level logs

---

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:

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:

<DATE> <TIME> | <12_FLOATING_POINT> XMR | Block <HUMAN_READABLE_BLOCK>

e.g:

2023-01-01 00:00:00.0000 | 0.600000000000 XMR | Block 2,123,123

The payout file is just a simple count of how many payouts have been received.

The xmr file is the sum of XMR mined as Atomic Units. The equation to represent this as XMR is:

XMR_ATOMIC_UNITS / 1,000,000,000,000

e.g:

600,000,000,000 / 1,000,000,000,000 = 0.6 XMR

Gupax interacts with these files in two ways:

• Reading the files when initially starting
• Appending/overwriting new data to the files upon P2Pool payout

These files shouldn't be written to manually or Gupax will report wrong data.

If you want to reset these stats, you can run:

./gupax --reset-payouts

or just manually delete the p2pool folder in the Gupax OS data directory.

---

Gupax

Along with the updater and settings mentioned in Simple, Gupax Advanced allows you to change:

• The PATH of where Gupax looks for P2Pool/XMRig
• The selected tab on startup
• Gupax's resolution

Warning: Gupax will use your custom PATH/binary and will replace them if you use Check for updates in the [Gupax] tab. Your PATH must end in a value that appears correct or else the updater will refuse to start:

Binary	Accepted values	Good PATH	Bad PATH
P2Pool	P2POOL, P2Pool, P2pool, p2pool	P2pool/p2pool	Documents/important_file
XMRig	XMRIG, XMRig, Xmrig, xmrig	XMRig/XMRig	Desktop/

If using Windows, the PATH must end with .exe.

---

P2Pool

P2Pool Advanced has:

• Terminal input
• Overriding command arguments
• Manual node list
• P2Pool Main/Mini selection
• Out/In peer setting
• Log level setting

The overriding command arguments will completely override your Gupax settings and start P2Pool with those arguments. Warning: If using this setting, use --no-color and make sure to set --data-api <PATH> & --local-api so that the [Status] tab can work!

The manual node list allows you save and connect up-to 1000 custom Monero nodes:

Data Field	Purpose	Limits	Max Length
Name	A unique name to identify this node (only for Gupax purposes)	Only [A-Za-z0-9-_.] and spaces allowed	30 characters
IP	The Monero node IP to connect to with P2Pool	It must be a valid IPv4 address or a valid domain name	255 characters
RPC	The RPC port of the Monero node	[1-65535]	5 characters
ZMQ	The ZMQ port of the Monero node	[1-65535]	5 characters

The Main/Mini selector allows you to change which P2Pool sidechain you mine on:

P2Pool Sidechain	Description	Use-case
Main	More miners, finds blocks faster, has a higher difficulty	Suitable for miners with MORE than 50kH/s
Mini	Less miners, finds blocks slower, has a lower difficulty	Suitable for miners with LESS than 50kH/s

Given enough time, both Main and Mini will result in the same reward (as will solo mining):

Mining Method	Share Behavior	Payout/Output Behavior	Example	Total (it's the same)
P2Pool Main	LESS frequent shares that are MORE valuable	Results in MORE outputs worth LESS	20 shares, 100 outputs worth 0.006 XMR	0.6 XMR
P2Pool Mini	MORE frequent shares that are LESS valuable	Results in LESS outputs worth MORE	100 shares, 20 outputs worth 0.03 XMR	0.6 XMR
Solo mining	No shares, only payouts	1 output	1 output worth the block reward: 0.6 XMR	0.6 XMR

In the end, it doesn't matter too much which sidechain you pick, it will all average out. Getting LESS but more valuable outputs may be desired, however, since the transaction cost to combine all of them (sweep_all) will be cheaper due to being comprised of less outputs.

The remaining sliders control miscellaneous settings:

Slider	Purpose	Default	Min/Max Range
Out peers	How many out-bound peers P2Pool will connect to	10	10..450
In peers	How many in-bound peers P2Pool will allow to connect to you	10	10..450
Log level	Verbosity of the P2Pool console log	3	0..6

---

XMRig

XMRig Advanced has:

• Terminal input
• Overriding command arguments
• Custom payout address
• CPU thread slider
• Manual pool list
• Custom HTTP API IP/Port
• TLS setting
• Keepalive setting

The overriding command arguments will completely override your Gupax settings and start XMRig with those arguments.

Warning: If using this setting, use [--no-color] and make sure to set [--http-host <IP>] & [--http-port <PORT>] so that the [Status] tab can work!

The manual pool list allows you save and connect up-to 1000 custom Pools (regardless if P2Pool or not):

Data Field	Purpose	Limits	Max Length
Name	A unique name to identify this pool (only for Gupax purposes)	Only [A-Za-z0-9-_.] and spaces allowed	30 characters
IP	The pool IP to connect to with XMRig	It must be a valid IPv4 address or a valid domain name	255 characters
Port	The port of the pool	[1-65535]	5 characters
Rig	An optional rig ID; This will be the name shown on the pool	Only [A-Za-z0-9-_] and spaces allowed	30 characters

The HTTP API textboxes allow you to change to IP/Port XMRig's HTTP API opens up on:

Data Field	Purpose	Default	Limits	Max Length
HTTP API IP	The IP XMRig's HTTP API server will bind to	localhost/127.0.0.1	It must be a valid IPv4 address or a valid domain name	255 characters
HTTP API Port	The port XMRig's HTTP API server will bind to	18088	[1-65535]	5 characters

The remaining buttons control miscellaneous settings (both are disabled by default, as P2Pool does not require them):

Button	Purpose
TLS Connection	Enables SSL/TLS connections (needs pool support)
Keepalive	Enables sending keepalive packets to prevent timeout (needs pool support)

Connections

For transparency, here's all the connections Gupax makes:

Domain	Why	When	Where
https://github.com	Fetching metadata information on packages + download	[Gupax] tab -> Check for updates	update.rs
Remote Monero nodes	Connecting to with P2Pool, measuring ping latency	[P2Pool Simple] tab	node.rs
DNS	DNS connections will usually be handled by your OS (or whatever custom DNS setup you have). If using Tor, DNS requests for updates should be routed through the Tor network automatically	All of the above	All of the above

Remote Monero nodes

These are the remote nodes used by Gupax in the [P2Pool Simple] tab.

IP/Domain	Location	RPC Port	ZMQ Port
monero.10z.com.ar	🇦🇷 Argentina	18089	18084
node.monerodevs.org	🇨🇦 Canada	18089	18084
p2pmd.xmrvsbeast.com	🇩🇪 Germany	18081	18083
node2.monerodevs.org	🇫🇷 France	18089	18084
p2pool.uk	🇬🇧 United Kingdom	18089	18084
xmr.support	🇺🇸 United States	18081	18083
xmrbandwagon.hopto.org	🇺🇸 United States	18081	18084
xmr.spotlightsound.com	🇺🇸 United States	18081	18084
node.richfowler.net	🇺🇸 United States	18089	18084

Build

General Info

You need cargo, Rust's build tool and package manager.

---

Linux

The pre-compiled Linux binaries are built on Ubuntu 20.04, you'll need these packages to build:

sudo apt install build-essential cmake libgtk-3-dev

After that, run:

cargo build --release

The Linux release tars come with another file next to the Gupax binary: Gupax.AppImage.

This is not an actual AppImage, it is just a text file that contains: ./gupax. This allows users to double-click and execute Gupax in file explorers like Nautilus in Ubuntu/Debian.

Building for a distribution

Gupax has a build flag for use as a package in a Linux distribution:

cargo build --release --features distro

This is the same as the --release profile, but with some changes:

Change	Reason
Built-in Update feature is disabled	Updates should be handled by the native package manager
Default P2Pool/XMRig path is /usr/bin/	P2Pool/XMRig exist in some repositories, which means they'll be installed in /usr/bin/

---

macOS

You'll need Xcode and brew.

Due to an issue with some TLS code, Arti (Tor) needs to fall back to using OpenSSL instead of the native TLS.

These are statically linked into Gupax, so you'll need to have them on your system:

brew install pkg-config openssl xz

If you want the binary to have an icon, you must use cargo-bundle:

cargo install cargo-bundle
cargo bundle --release

This bundles Gupax into a Gupax.app, the way it comes in the pre-built tars for macOS.

To build only the binary:

cargo build --release

---

Windows

You'll need Visual Studio.

There is a build.rs file in the repo solely for Windows-specific things:

1. It sets the icon in File Explorer
2. It statically links VCRUNTIME140.dll into Gupax (the binary will not be portable without this)

After installing the development tools, run:

cargo build --release

This will build Gupax with the MSVC toolchain (x86_64-pc-windows-msvc). This is the recommended method and is how the pre-compiled release binaries are built.

License

The GUI library Gupax uses is egui. It is licensed under MIT & Apache 2.0.

Many other libraries are used that have various licenses.

Gupax, P2Pool, and XMRig are licensed under the GNU General Public License v3.0.

FAQ

System requirements

Gupax may not run on machines with:

• a deprecated OS (Windows 7, Ubuntu 18.04, etc)
• an older CPU (<2010)

Anything more recent than this should be okay.

Gupax does not start

Windows

Gupax may have issues with machines with older CPUs (~14 years old, <3.3 OpenGL) on Windows.

Gupax may also be flagged by antivirus, adding an exception to the Gupax folder should fix this.

macOS

Gupax may fail to start on macOS due to Apple's security features. Apps downloaded from the internet may be flagged as 'unsafe' if they lack proper notarization by Apple.

As a workaround you can remove the quarantine flag on the .app file by running the following command in your terminal:

xattr -d com.apple.quarantine Gupax.app

Linux ARM

Gupax only supports ARM for macOS, not Linux.

Linux ARM is not supported as XMRig does not provide official binaries. This means machines like Raspberry Pis will not work.

Where are updates downloaded from?

The latest versions are downloaded using GitHub's API.

• Gupax https://github.com/hinto-janai/gupax
• P2Pool https://github.com/SChernykh/p2pool
• XMRig https://github.com/xmrig/xmrig

GitHub's API blocks request that do not have an HTTP User-Agent header.

Gupax uses a random recent version of a Wget/Curl user-agent.

P2Pool connection errors

TL;DR: Run & use your own Monero node.

If you are using the default P2Pool settings then you are using a Remote Monero node. Using a remote node is convenient but comes at the cost of privacy and reliability. You may encounter connections issues with these nodes that look like this:

2023-01-05 12:27:37.7962 P2PServer peer 23.233.96.72:37888 is ahead on mainchain (height 2792939, your height 2792936). Is your monerod stuck or lagging?

To fix this you can select a different remote node, or better yet: Run your own local Monero node.

Running and using your own local Monero node improves privacy and ensures your connection is as stable as your own internet connection. This comes at the cost of downloading and syncing Monero's blockchain yourself (currently 155GB). If you have the disk space, consider using the P2Pool Advanced tab and connecting to your own Monero node.

For a simple guide, see the Running a Local Monero node section.

Can I quit mid-update?

If you started an update, you should let it finish. If the update has been stuck for a long time, quitting Gupax is probably okay. The worst that can happen is that your Gupax/P2Pool/XMRig binaries may be moved/deleted. Those can be easily redownloaded. Your actual Gupax user data (settings, custom nodes, pools, etc) is never touched.

Although Gupax uses a temporary folder (gupax_update_[A-Za-z0-9]) to store temporary downloaded files, there aren't measures in place to revert an upgrade once the file swapping has actually started. If you quit Gupax anytime before the Upgrading packages phase (after metadata, download, extraction), you will technically be safe but this is not recommended as it is risky, especially since these updates can be very fast.

Bundled vs Standalone

Bundled Gupax comes with the latest version of P2Pool/XMRig already in the zip/tar.

Standalone only contains the Gupax executable.

How much memory does Gupax use?

Gupax itself uses around 100-400 megabytes of memory.

Gupax also holds up to 500,000 bytes of log data from P2Pool/XMRig to display in the GUI terminals. These logs are reset once over capacity which takes around 1-4 hours.

Memory usage should never be above 500~ megabytes. If you see Gupax using more than this, please send a bug report.

How is sudo handled? (on macOS/Linux)

See here for more info.

Why does Gupax need to be Admin? (on Windows)

See here for more info.