{"id":15146859,"url":"https://github.com/jtgrassie/monero-pool","last_synced_at":"2025-04-05T04:14:38.985Z","repository":{"id":39178320,"uuid":"144484038","full_name":"jtgrassie/monero-pool","owner":"jtgrassie","description":"A Monero mining pool server written in C","archived":false,"fork":false,"pushed_at":"2024-03-10T02:18:47.000Z","size":1039,"stargazers_count":363,"open_issues_count":5,"forks_count":129,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-03-29T03:11:12.400Z","etag":null,"topics":["mining-pool","monero","monero-mining","monero-pool","xmr"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jtgrassie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-12T16:45:41.000Z","updated_at":"2025-03-28T12:18:21.000Z","dependencies_parsed_at":"2024-03-10T03:21:40.664Z","dependency_job_id":"30984c87-ce30-484d-882e-5cbe2fe71f56","html_url":"https://github.com/jtgrassie/monero-pool","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtgrassie%2Fmonero-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtgrassie%2Fmonero-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtgrassie%2Fmonero-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtgrassie%2Fmonero-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtgrassie","download_url":"https://codeload.github.com/jtgrassie/monero-pool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284953,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mining-pool","monero","monero-mining","monero-pool","xmr"],"created_at":"2024-09-26T12:20:18.940Z","updated_at":"2025-04-05T04:14:38.947Z","avatar_url":"https://github.com/jtgrassie.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# monero-pool\n\nA Monero mining pool server written in C.\n\nDesign decisions are focused on performance and efficiency, hence the use of\nlibevent and LMDB.  Currently it uses only *two* threads under normal operation\n(one for the stratum clients and one for the web UI clients). It gets away with\nthis thanks to the efficiency of both LMDB and libevent (for the stratum\nclients) and some sensible proxying/caching being placed in front of the [web\nUI](#web-ui).\n\nConfiguration is extremely flexible, now allowing for the pool to run in a\nvariety of setups, such as highly available and redundant configurations.\nDiscussed further below in: [Interconnected pools](#Interconnected-pools).\n\nThis pool was the *first* pool to support RandomX and is currently the *only*\npool which supports the RandomX fast/full-memory mode.\n\nThe single payout mechanism is PPLNS, which favors loyal pool miners, and there\nare no plans to add any other payout mechanisms or other coins. Work should stay\nfocussed on performance, efficiency and stability.\n\nThe pool also supports an optional method of mining whereby miners select their\n*own* block template to mine on. Further information can be found in the\ndocument: [Stratum mode self-select](./sss.md).\n\nFor testing, a reference mainnet pool can be found at\n[monerop.com](http://monerop.com).\n\n## Compiling from source\n\n### Dependencies\n\nThe build system requires the Monero source tree to be cloned and compiled.\nFollow the\n[instructions](https://github.com/monero-project/monero#compiling-monero-from-source)\nfor compiling Monero, then export the following variable:\n\n```bash\nexport MONERO_ROOT=/path/to/cloned/monero\n```\n\nReplacing the path appropriately.\n\nBeyond the Monero dependencies, the following extra libraries are also required\nto build the pool:\n\n- liblmdb\n- libevent\n- json-c\n- uuid\n\nAs an example, on Ubuntu, these dependencies can be installed with the following\ncommand:\n\n```\nsudo apt-get install liblmdb-dev libevent-dev libjson-c-dev uuid-dev\n```\n### Compile\n\nAfter installing all the dependencies as described above, to compile the pool as\na release build, run:\n\n```\nmake release\n```\n\nThe application will be built in `build/release/`.\n\nOptionally you can compile a debug build by simply running:\n\n```\nmake\n```\n\nDebug builds are output in `build/debug/`.\n\n## Configuration\n\nDuring compilation, a copy of [pool.conf](./pool.conf) is placed in the output\nbuild directory. Edit this file as you see fit. When running the pool, if a\ncustom location is not set via the command-line parameter `--config-file\n\u003cfile\u003e`, the pool will first look for this file in the same directory as the\npool binary, then in the current users home directory. The configuration options\nshould all be self explanatory.\n\nThere are also some [command-line parameters](#command-line-parameters) which\ncan be used to override some of these settings.\n\n### Block notification\n\nThe pool can optionally be started with the flag `--block-notified` (or set in\nthe config file: `block-notified = 1`). This will prevent the pool from\n*polling* for new blocks (using a timer), and instead fetch a new block template\nwhen it receives a *signal* (specifically, *SIGUSR1*). The Monero daemon,\n`monerod`, has a feature whereby it can execute a command whenever a block as\nadded to the chain, which can thus be used to generate the required signal.\n\nE.g.\n\n\u003cpre\u003e\nmonerod ... \u003cb\u003e--block-notify '/usr/bin/pkill -USR1 monero-pool'\u003c/b\u003e\n\u003c/pre\u003e\n\nLaunching `monerod` like this instructs it to send the required signal,\n*SIGUSR1*, to the pool whenever a new block is added to the chain.\n\nUsing this mechanism has a *significant* benefit - your pool *immediately* knows\nwhen to fetch a new block template to send to your miners. You're essentially\ngiving your miners a head-start over miners in pools which use polling (which is\nwhat currently all the other pool implementations do).\n\n### Interconnected pools\n\nIn some situations it's desirable to run multiple pool instances that behave as\none. Some examples being:\n\n - When running a global public pool, it's desirable to offer extremely\n   low-latency pool connections to geographically dispersed miners.\n - When running a private pool across multiple data centers, it's desirable to\n   make use of the internal site-to-site network makeup.\n - Where there are multiple hosts available, it's desirable to offer extra\n   redundancy.\n\nTo meet these needs, multiple instances of the pool can be run with each\nbehaving either as an edge pool, an upstream pool, both (i.e. bridged) or a\nnormal single pool.\n\nAny pool that has an upstream pool configured does almost everything a normal\npool does, with the exception that it offloads payout processing to its upstream\npool, thus it relays validated shares and blocks to the upstream pool. In\nreturn, the upstream pool sends the combined pools stats, balance updates and\nhandles the payout processing.  Should an upstream become unreachable, the\ndownstream pools continue as normal, then upon reconnection to the upstream,\nsends over the backlog of shares and blocks accumulated whilst the upstream was\nunreachable.\n\nConfiguration is fairly trivial. A pool that will allow downstream pools to\nconnect to it, does so via the config file parameters `trusted-listen`,\n`trusted-port` and `trusted-allowed`. E.g.\n\n    trusted-listen = 10.0.0.1\n    trusted-port = 4244\n    trusted-allowed = 10.0.0.2,10.0.0.3\n\nAs share validation is performed on the edge pools, it's ***vitally*** important\nthis trusted listener is secured. Ideally it's only bound to an internal / local\nnetwork / private interface and specifying the IP addresses of the downstream\npools allowed to connect to it (as in the example above). If the interface being\nbound to is already secured, the parameter `trusted-allowed` can be omitted.\n\nThen the downstream pools (`10.0.0.2` and `10.0.0.3` in the above example), need\nto include in their config files the parameters `upstream-host` and\n`upstream-port`. E.g.\n\n    upstream-host = 10.0.0.1\n    upstream-port = 4244\n\nTo create a bridged pool, use all five parameters discussed above. For example:\n\n    trusted-listen = 10.0.0.4\n    trusted-port = 4244\n    trusted-allowed = 10.0.0.5,10.0.0.6\n    upstream-host = 10.0.0.1\n    upstream-port = 4244\n\nAn example where bridging can be useful is for spanning network providers, e.g.\nusing a global provider for the main pool hubs (the bridges) and local providers\nfor edge pools within a territory.\n\nEvery pool, however configured, still needs RPC access to a Monero daemon.  They\ncan of course all be configured to use the *same* daemon, or for extra\nredundancy, make use of separate daemons. Downstream pools do not need RPC\naccess to the pool's wallet, only the final upstream needs wallet access. If\nStratum mode self-select is being offered, the pool wallet view key can be set\nin the downstream pool config files via the `pool-view-key` parameter, or by\nrunning a local view-only wallet RPC.\n\n## Running\n\nEnsure you have your Monero daemon (`monerod`) and wallet RPC\n(`monero-wallet-rpc`) up and running with the correct host and port settings as\ndefined in your pool config file.\n\nIt is highly recommended to run these on the same host as the pool server to\navoid any network latency when their RPC methods are called.\n\nThen simply `cd build/[debug|release]` and run `./monero-pool`.\n\n### Command-line parameters\n\nA few of the configuration options can be overridden via the following\ncommand-line parameters:\n\n    -c, --config-file \u003cfile\u003e\n    -l, --log-file \u003cfile\u003e\n    -b, --block-notified [0|1]\n    -d, --data-dir \u003cdir\u003e\n    -p, --pid-file \u003cfile\u003e\n    -f, --forked [0|1]\n\n## Web UI\n\nThis project is not designed to be a one-stop solution for running a public\npool; it is an highly efficient mining pool implementation. For a public pool,\nwhich typically entails having a fancy web UI, that part is down to you. There\nis howeveer a minimal web UI that gets served on the port specified in the\nconfig file. If you plan on running a *public* pool via this UI (or any other\nfor that matter), it's advisable to use either Apache or Nginx as a proxy in\n   front of this with some appropriate caching configured. The goal is to\n   offload browser based traffic to something built for the task and allow the\n   pool to focus on its primary function - serving miners.\n\nIf you intend to make changes to this minimal web UI, note that the HTML gets\ncompiled into the pool binary. The single web page that gets served simply makes\nuse of a JSON endpoint to populate the stats. Thus, a sensible option for your\nown web UI is to simply make use of that endpoint (for stats and balances), and\nkeep your website completely separate, served by Apache or Nginx for example.\n\n## SSL\n\nThe pool has been tested behind both [HAProxy](http://www.haproxy.org/) and\n[stunnel](https://www.stunnel.org/), so if you wish to provide SSL access to the\npool, these are both good options and simple to setup. The [reference\npool](https://monerop.com) makes use of HAProxy and port 4343 for SSL traffic.\n\nThe web UI, as mentioned above, should ideally be placed behind a *caching\nproxy*. Therefore SSL termination should be be configured there (i.e. in\nApache/Nginx).\n\n## Help / Contact\n\nIf you need help setting up your own pool, you can find\nme (jtgrassie) on IRC in [#monero-pool](irc://chat.freenode.net/#monero-pool)\nand many of the other Monero channels.\n\n## Supporting the project\n\nThis mining pool has **no built-in developer donation** (like *other* mining\npool software has), so if you use it and want to donate, XMR donations to:\n\n```\n451ytzQg1vUVkuAW73VsQ72G96FUjASi4WNQse3v8ALfjiR5vLzGQ2hMUdYhG38Fi15eJ5FJ1ZL4EV1SFVi228muGX4f3SV\n```\n\n![QR code](./qr-small.png)\n\nwould be very much appreciated.\n\n## License\n\nPlease see the [LICENSE](./LICENSE) file.\n\n[//]: # ( vim: set tw=80: )\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtgrassie%2Fmonero-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtgrassie%2Fmonero-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtgrassie%2Fmonero-pool/lists"}