{"id":29560916,"url":"https://github.com/decred/dcrpool","last_synced_at":"2025-07-18T15:39:23.101Z","repository":{"id":42665011,"uuid":"144629068","full_name":"decred/dcrpool","owner":"decred","description":"decred mining pool","archived":false,"fork":false,"pushed_at":"2024-08-12T08:21:07.000Z","size":10728,"stargazers_count":28,"open_issues_count":13,"forks_count":27,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-08-13T08:59:51.664Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decred.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-13T20:15:47.000Z","updated_at":"2024-08-12T08:21:11.000Z","dependencies_parsed_at":"2023-10-13T00:14:38.567Z","dependency_job_id":"df4e1f23-899e-49bf-afce-6936f23bf7bd","html_url":"https://github.com/decred/dcrpool","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/decred/dcrpool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decred%2Fdcrpool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decred%2Fdcrpool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decred%2Fdcrpool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decred%2Fdcrpool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decred","download_url":"https://codeload.github.com/decred/dcrpool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decred%2Fdcrpool/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265787586,"owners_count":23828458,"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":[],"created_at":"2025-07-18T15:39:22.354Z","updated_at":"2025-07-18T15:39:23.088Z","avatar_url":"https://github.com/decred.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dcrpool\n\n[![Build Status](https://github.com/decred/dcrpool/workflows/Build%20and%20Test/badge.svg)](https://github.com/decred/dcrpool/actions)\n[![ISC License](https://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)\n[![Go Report Card](https://goreportcard.com/badge/github.com/decred/dcrpool)](https://goreportcard.com/report/github.com/decred/dcrpool)\n\n## Overview\n\ndcrpool is a stratum Decred mining pool.  It supports BLAKE3 mining as required\nby [DCP0011](https://github.com/decred/dcps/blob/master/dcp-0011/dcp-0011.mediawiki).\n\nThe default port all supported miners connect to the pool via is `:5550`.  The\npool can be configured to mine in solo pool mode or as a publicly available\nmining pool.  Solo pool mode represents a private mining pool operation where\nall connected miners to the pool are owned by the pool administrator.  For this\nreason, mining rewards are left to accumulate at the specified address for the\nmining node. There isn't a need for payment processing in solo pool mining mode,\nit is disabled as a result.\n\nIn solo pool mining mode, miners only need to identify themselves when\nconnecting to the pool. The miner's username, specifically the username sent in\na `mining.authorize` message, should be a unique name identifying the client.\n\nThe pool supports Pay Per Share (`PPS`) and Pay Per Last N Shares (`PPLNS`)\npayment schemes when configured for pool mining. With pool mining, mining\nclients connect to the pool, contribute work towards solving a block and claim\nshares for participation. When a block is found by the pool, portions of the\nmining reward due participating accounts are calculated based on claimed shares\nand the payment scheme used. The pool pays out the mining reward portions due\neach participating account when it matures.\n\nIn addition to identifying itself to the pool, each connecting miner has to\nspecify the address its portion of the mining reward should be sent to when a\nblock is found. For this reason, the mining client's username is a combination\nof the address mining rewards are paid to and its name, formatted as:\n`address.name`. This username format for pool mining is required. The pool uses\nthe address provided in the username to create an account, all other connected\nminers with the same address set will contribute work to that account.\n\nThe user interface of the pool provides public access to statistics and pool\naccount data. Users of the pool can access all payments, mined blocks by the\naccount and also work contributed by clients of the account via the interface.\nThe interface is only accessible via HTTPS and by default uses a self-signed\ncertificate, served on port `:8080`. In production, particularly for pool\nmining, a certificate from an authority (`CA`) like\n[letsencrypt](https://letsencrypt.org/) is recommended.\n\n## Build and installation\n\n- **Install Go 1.21 or higher**\n\n  Installation instructions can be found here: https://golang.org/doc/install.\n  Ensure Go was installed properly and is a supported version:\n  ```sh\n  $ go version\n  $ go env GOROOT GOPATH\n  ```\n  NOTE: if `GOROOT` and `GOPATH` are initialized they must not be at the same path.\n  It is recommended to add `$GOPATH/bin` to your `PATH` according to the Golang.org\n  instructions.\n\n- **Build and Install or Update dcrpool**\n\n  The latest release of `dcrpool` may be built and installed with a single\n  command without cloning this repository:\n\n  ```sh\n  $ go install github.com/decred/dcrpool@release-v2.0.0\n  ```\n\n  Using `@master` instead will perform a build using the latest code from the\n  master branch.  This may be useful to use newer features or bug fixes not yet\n  found in the latest release:\n\n  ```sh\n  $ go install github.com/decred/dcrpool@master\n  ```\n\n  Alternatively, a development build can be performed by running `go install` in\n  a locally checked-out repository.\n\n  In all cases, the `dcrpool` executable will be installed to the `bin`\n  directory rooted at the path reported by `go env GOPATH`.\n\n  Therefore, if you want to easily access `dcrpool` from the command-line\n  without having to type the full path to the binary every time, ensure the\n  aforementioned directory is added to your system path:\n\n  * macOS: [how to add binary to your PATH](https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7#mac-os-x)\n  * Windows: [how to add binary to your PATH](https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7#windows)\n  * Linux and other Unix: [how to add binary to your PATH](https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7#linux)\n\n## Database\n\ndcrpool can run with either a [Bolt database](https://github.com/etcd-io/bbolt)\nor a [Postgres database](https://www.postgresql.org/). Bolt is used by default.\n[postgres.md](./docs/postgres.md) has more details about running with Postgres.\n\nWhen running in Bolt mode, the pool maintains a backup of the database\n(`backup.kv`), created on shutdown in the same directory as the database itself.\nThe user interface also provides functionality for pool administrators to backup\nBolt database when necessary.\n\n## Configuration\n\ndcrpool requires [dcrd](https://github.com/decred/dcrd) and\n[dcrwallet](https://github.com/decred/dcrwallet) when configured as a mining\npool, it only requires dcrd when configured as a solo pool.\nDeploying the user interface requires copying the `dcrpool/internal/gui/assets`\nfolder from source to a reachable location and updating the gui directory\n(`--guidir`) of the configuration. Currently only single instance deployments\nare supported, support for distributed deployments will be implemented in the\nfuture.\n\n### Example of a solo pool configuration\n\n```no-highlight\nrpcuser=user\nrpcpass=pass\ndcrdrpchost=127.0.0.1:9109\ndcrdrpccert=/home/.dcrd/rpc.cert\nsolopool=true\nactivenet=mainnet\nadminpass=adminpass\nguidir=/home/gui\n```\n\nThe configuration above uses a [Bolt database](https://github.com/etcd-io/bbolt). \nTo switch to a [Postgres database](https://www.postgresql.org/) additional\nconfig options will be needed, refer to [postgres.md](./docs/postgres.md).\n\n### Example output of a solo pool startup\n\n```no-highlight\ndcrpool --configfile=pool.conf --appdata=/tmp/dcrpool-harness/pool\n2023-09-19 20:10:31.149 [INF] MP: Version: 1.3.0-pre+88afbe8d1 (Go version go1.21.1 linux/amd64)\n2023-09-19 20:10:31.149 [INF] MP: Home dir: /tmp/dcrpool-harness/pool\n2023-09-19 20:10:31.120 [INF] POOL: Maximum work submission generation time at pool difficulty is 28s.\n2023-09-19 20:10:31.149 [INF] MP: Creating profiling server listening on 127.0.0.1:6060\n2023-09-19 20:10:31.129 [INF] POOL: Solo pool mode active.\n2023-09-19 20:10:31.150 [INF] POOL: listening on 0.0.0.0:5550\n2023-09-19 20:10:31.149 [INF] GUI: Starting GUI server on [::]:8080\n```\n\n### Example of a mining pool configuration\n\n```no-highlight\nrpcuser=user\nrpcpass=pass\ndcrdrpchost=127.0.0.1:9109\ndcrdrpccert=/home/.dcrd/rpc.cert\nwalletgrpchost=127.0.0.1:9111\nwalletrpccert=/home/.dcrwallet/rpc.cert\nmaxgentime=20s\nsolopool=false\nactivenet=mainnet\nwalletpass=walletpass\npoolfeeaddrs=SsVPfV8yoMu7AvF5fGjxTGmQ57pGkaY6n8z\npaymentmethod=pplns\nlastnperiod=5m\nadminpass=adminpass\nguidir=/home/gui\n```\n\nThe configuration above uses a [Bolt database](https://github.com/etcd-io/bbolt). \nTo switch to a [Postgres database](https://www.postgresql.org/) additional\nconfig options will be needed, refer to [postgres.md](./docs/postgres.md).\n\n### Example output of a mining pool startup\n\n```no-highlight\ndcrpool --configfile=pool.conf --appdata=/tmp/dcrpool-harness/pool\n2023-09-19 19:57:45.916 [INF] MP: Version: 1.3.0-pre+88afbe8d1 (Go version go1.21.1 linux/amd64)\n2023-09-19 19:57:45.916 [INF] MP: Home dir: /tmp/dcrpool-harness/pool\n2023-09-19 19:57:45.795 [INF] POOL: Maximum work submission generation time at pool difficulty is 20s.\n2023-09-19 19:57:45.916 [INF] MP: Creating profiling server listening on 127.0.0.1:6060\n2023-09-19 19:57:45.816 [INF] POOL: Payment method is PPLNS.\n2023-09-19 19:57:45.917 [INF] GUI: Starting GUI server on [::]:8080\n2023-09-19 19:57:45.932 [INF] POOL: listening on 0.0.0.0:5550\n```\n\nRefer to [config descriptions](config.go) for more detail. \n\n\n## Wallet accounts\n\nIn mining pool mode the ideal wallet setup is to have two wallet accounts, the\npool account and the fee account, for the mining pool. This account structure\nseparates revenue earned from pool operations from mining rewards received on\nbehalf of participating clients. The pool account's purpose is to receive mining\nrewards of the pool. The addresses generated from it should be the mining\naddresses (`--miningaddr`) set for the mining node. It is important to set\nmultiple mining addresses for the mining node in production to make it difficult\nfor third-parties wanting to track coinbases mined by the pool and ultimately\ndetermine the cumulative value of coinbases mined.\n\nThe fee account's purpose is to receive pool fees of the mining pool. It is\nimportant to set multiple pool fee addresses to the mining pool in production to\nmake it difficult for third-parties wanting to track pool fees collected by the\npool and ultimately determine the cumulative value accrued by pool operators.\nWith multiple pool fee addresses set, the mining pool picks one at random for\nevery payout made. The addresses generated from the fee account should be set as\nthe pool fee addresses (`--poolfeeaddrs`) of the mining pool.\n\n## Wallet Client Authentication\n\ndcrwallet v1.6 and greater requires client authentication certificates to be\nprovided on startup via the client CA file config option (`--clientcafile`).\nSince dcrpool is expected to maintain a grpc connection to the wallet it needs\nto generate the needed certificate before the wallet is started. A config option\n(`--gencertsonly`) which allows the generation of all key pairs without starting\nthe pool has been added for this purpose. Pool operators running a publicly\navailable mining pool will be required to first run their pools with\n`--gencertsonly` to generate required key pairs before configuring their pool\nwallets and starting them. The test harness, [harness.sh](./harness.sh),\nprovides a detailed example for reference. \n\n## Pool Fees\n\nIn mining pool mode pool fees collected by the pool operator are for maintaining\na connection to the decred network, the delivery of work to mining clients, the\nsubmission of solved work by mining clients to the network, and processing of\nblock rewards based on work contributed by participting accounts.\n\n## Transaction fees\n\nEvery mature group of payments plus the pool fees collected completely exhaust\nthe referenced coinbases being sourced from by payments. For this reason payout\ntransactions by the pool create no change. It is implicit that the transaction\nfees of the payout transaction are paid for by the accounts receiving payouts,\nsince transaction fees are not collected as part of pool fees. Each account\nreceiving a payout from the transaction pays a portion of the transaction fee\nbased on value of the payout in comparison to the overall value of payouts being\nmade by the transaction.\n\n## Dust payments\n\nDust payments generated by participating accounts of the pool are forfeited to\nthe pool fees paid per each block mined. The reason for this is two-fold.  Dust\npayments render payout transactions non-standard causing it to fail, also making\nparticipating accounts forfeit dust payments serves as a good deterrent to\naccounts that contribute intermittent, sporadic work. Participating accounts\nbecome compelled to commit and contribute enough resources to the pool worth\nmore than dust outputs to guarantee receiving dividends whenever the pool mines\na block.\n\n## Testing\n\nThe project has a configurable tmux mining harness and a CPU miner for testing\non simnet. Further documentation can be found in [harness.sh](./harness.sh).\n\n## Should I be running dcrpool?\n\ndcrpool is ideal for miners running medium-to-large mining operations. The\nrevenue generated from mining blocks as well as not paying pool fees to a\npublicly available mining pool in the process should be enough to offset the\ncost of running a pool. It will most likely not be cost effective to run dcrpool\nfor a small mining operation, the better option here would be using a public\nmining pool instead.\n\nFor people looking to setup a publicly available mining pool, dcrpool's\nwell-documented configuration and simple setup process also make it a great\noption.\n\n## Contact\n\nIf you have any further questions you can find us at\nhttps://decred.org/community/.\n\n## Issue Tracker\n\nThe [integrated github issue tracker](https://github.com/decred/dcrpool/issues)\nis used for this project.\n\n## License\n\ndcrpool is licensed under the [copyfree](http://copyfree.org) ISC License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecred%2Fdcrpool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecred%2Fdcrpool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecred%2Fdcrpool/lists"}