{"id":21815761,"url":"https://github.com/bitcoin-com/bupool","last_synced_at":"2026-02-04T02:04:42.914Z","repository":{"id":88669776,"uuid":"62391837","full_name":"Bitcoin-com/bupool","owner":"Bitcoin-com","description":null,"archived":false,"fork":false,"pushed_at":"2016-12-14T18:25:49.000Z","size":3041,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-27T14:55:27.909Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bitcoin-com.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-01T12:35:27.000Z","updated_at":"2025-01-23T23:45:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"f70dc2ba-9e4d-4c3b-8a02-e7f3a61b8fd3","html_url":"https://github.com/Bitcoin-com/bupool","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2Fbupool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2Fbupool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2Fbupool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bitcoin-com%2Fbupool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bitcoin-com","download_url":"https://codeload.github.com/Bitcoin-com/bupool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248804783,"owners_count":21164131,"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":"2024-11-27T15:22:41.114Z","updated_at":"2026-02-04T02:04:42.879Z","avatar_url":"https://github.com/Bitcoin-com.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"CKPOOL + CKDB + libckpool by Con Kolivas and Andrew Smith.\n\nUltra low overhead massively scalable multi-process, multi-threaded modular\nbitcoin mining pool, proxy, passthrough, library and database interface in c\nfor Linux.\n\nCKPOOL is code provided free of charge under the GPLv3 license but its development\nis mostly paid for by commissioned funding, and the pool by default contributes\n0.5% of solved blocks in pool mode to the development team. Please consider leaving\nthis contribution in the code if you are running it on a pool or contributing to the\nauthors listed in AUTHORS if you use this code to aid funding further development.\n\n---\nLICENSE:\n\nGNU Public license V3. See included COPYING for details.\n\n\n---\nDESIGN:\n\nArchitecture:\n- Low level hand coded architecture relying on minimal outside libraries beyond\nbasic glibc functions for maximum flexibility and minimal overhead that can be\nbuilt and deployed on any Linux installation.\n- Multiprocess+multithreaded design to scale to massive deployments and\ncapitalise on modern multicore/multithread CPU designs.\n- Minimal memory overhead.\n- Utilises ultra reliable unix sockets for communication with dependent\nprocesses.\n- Modular code design to streamline further development.\n- Standalone library code that can be utilised independently of ckpool.\n- Same code can be deployed in many different modes designed to talk to each\nother on the same machine, local lan or remote internet locations.\n\nModes of deployment:\n- Comprehensive pooled mining solution with a postgresql database interface.\n- Passthrough node(s) that combine connections to a single socket which can\nbe used to scale to millions of clients and allow the main pool to be isolated\nfrom direct communication with clients.\n- Proxy nodes with a database that act as a single client to the upstream pool\nwhile storing full client data of their own.\n- Simple proxy without the limitations of hashrate inherent in other proxy\nsolutions when talking to ckpool.\n- Simple pool without a database.\n- Library for use by other software.\n\nFeatures:\n- Bitcoind communication to unmodified bitcoind with multiple failover to local\nor remote locations.\n- Local pool instance worker limited only by operating system resources and\ncan be made virtually limitless through use of multiple downstream passthrough\nnodes.\n- Proxy and passthrough modes can set up multiple failover upstream pools.\n- Optional share logging.\n- Virtually seamless restarts for upgrades through socket handover from exiting\ninstances to new starting instance.\n- Configurable custom coinbase signature.\n- Configurable instant starting and minimum difficulty.\n- Rapid vardiff adjustment with stable unlimited maximum difficulty handling.\n- New work generation on block changes incorporate full bitcoind transaction\nset without delay or requiring to send transactionless work to miners thereby\nproviding the best bitcoin network support and rewarding miners with the most\ntransaction fees.\n- Event driven communication based on communication readiness preventing\nslow communicating clients from delaying low latency ones.\n- Stratum messaging system to running clients.\n- Accurate pool and per client statistics.\n- Multiple named instances can be run concurrently on the same machine.\n\n\n---\nBUILDING:\n\nBuilding ckpool standalone without ckdb has no dependencies outside of the\nbasic build tools on any linux installation.\n\nsudo apt-get install build-essential yasm\n./configure --without-ckdb\nmake\n\n\nBuilding with ckdb requires installation of the postgresql, gsl and ssl\ndevelopment libraries.\n\nsudo apt-get install build-essential yasm libpq-dev libgsl-dev\n./configure\nmake\n\nolder distributions may instead require a different version of gsl:\n sudo apt-get install build-essential libpq-dev libgsl0ldbl libgsl0-dev yasm\n\nN.B. ckdb also requires libssl-dev but libpq-dev depends on it and installs it\n\n\nBuilding from git also requires autoconf and automake\n\nsudo apt-get install build-essential yasm libpq-dev libgsl-dev autoconf automake libtool\n./autogen.sh\n./configure\nmake\n\n\nBinaries will be built in the src/ subdirectory. Binaries generated will be:\nckpool - The main pool back end\nckdb - The pool's database\nckpmsg - An application for passing messages in libckpool format to ckpool/ckdb\nnotifier - An application designed to be run with bitcoind's -blocknotify to\n\tnotify ckpool of block changes.\n\n\nInstallation is NOT required and ckpool can be run directly from the directory\nit's built in but it can be installed with:\nsudo make install\n\n\nIt is anticipated that pool operators wishing to set up a full database based\ninstallation of ckpool+ckdb will be familiar with setting up postgresql and\nassociated permissions to the directories where the various processes will\ncommunicate with each other and a web server so these will not be documented.\n\n\n---\nRUNNING:\n\nckpool supports the following options:\n\n-A | --standalone\n-c CONFIG | --config CONFIG\n-d CKDB-NAME | --ckdb-name CKDB-NAME\n-g GROUP | --group GROUP\n-H | --handover\n-h | --help\n-k | --killold\n-L | --log-shares\n-l LOGLEVEL | --loglevel LOGLEVEL\n-N | --node\n-n NAME | --name NAME\n-P | --passthrough\n-p | --proxy\n-R | --redirector\n-S CKDB-SOCKDIR | --ckdb-sockdir CKDB-SOCKDIR\n-s SOCKDIR | --sockdir SOCKDIR\n-u | --userproxy\n\n\n-A Standalone mode tells ckpool not to try to communicate with ckdb or log any\nckdb requests in the rotating ckdb logs it would otherwise store. All users\nare automatically accepted without any attempt to authorise users in any way.\nThis option is explicitly enabled when built without ckdb support.\n\n-c \u003cCONFIG\u003e tells ckpool to override its default configuration filename and\nload the specified one. If -c is not specified, ckpool looks for ckpool.conf,\nin proxy mode it looks for ckproxy.conf, in passthrough mode for\nckpassthrough.conf and in redirector mode for ckredirector.conf\n\n-d \u003cCKDB-NAME\u003e tells ckpool what the name of the ckdb process is that it should\nspeak to, otherwise it will look for ckdb.\nThis option does not exist when built without ckdb support.\n\n-g \u003cGROUP\u003e will start ckpool as the group ID specified.\n\n-H will make ckpool attempt to receive a handover from a running incidence of\nckpool with the same name, taking its client listening socket and shutting it\ndown.\n\n-h displays the above help\n\n-k will make ckpool shut down an existing instance of ckpool with the same name,\nkilling it if need be. Otherwise ckpool will refuse to start if an instance of\nthe same name is already running.\n\n-L will log per share information in the logs directory divided by block height\nand then workbase.\n\n-l \u003cLOGLEVEL will change the log level to that specified. Default is 5 and\nmaximum debug is level 7.\n\n-N will start ckpool in passthrough node mode where it behaves like a\npassthrough but requires a locally running bitcoind and can submit blocks\nitself in addition to passing the shares back to the upstream pool. It also\nmonitors hashrate and requires more resources than a simple passthrough. Be\naware that upstream pools must specify dedicated IPs/ports that accept\nincoming node requests with the nodeserver directive described below.\n\n-n \u003cNAME\u003e will change the ckpool process name to that specified, allowing\nmultiple different named instances to be running. By default the variant\nnames are used: ckpool, ckproxy, ckpassthrough, ckredirector, cknode.\n\n-P will start ckpool in passthrough proxy mode where it collates all incoming\nconnections and streams all information on a single connection to an upstream\npool specified in ckproxy.conf . Downstream users all retain their individual\npresence on the master pool. Standalone mode is implied.\n\n-p will start ckpool in proxy mode where it appears to be a local pool handling\nclients as separate entities while presenting shares as a single user to the\nupstream pool specified. Note that the upstream pool needs to be a ckpool for\nit to scale to large hashrates. Standalone mode is Optional.\n\n-R will start ckpool in a variant of passthrough mode. It is designed to be a\nfront end to filter out users that never contribute any shares. Once an\naccepted share from the upstream pool is detected, it will issue a redirect to\none of the redirecturl entries in the configuration file. It will cycle over\nentries if multiple exist, but try to keep all clients from the same IP\nredirecting to the same pool.\n\n-S \u003cCKDB-SOCKDIR\u003e tells ckpool which directory to look for the ckdb socket to\ntalk to.\nThis option does not exist when built without ckdb support.\n\n-s \u003cSOCKDIR\u003e tells ckpool which directory to place its own communication\nsockets (/tmp by default)\n\n-u Userproxy mode will start ckpool in proxy mode as per the -p option above,\nbut in addition it will accept username/passwords from the stratum connects\nand try to open additional connections with those credentials to the upstream\npool specified in the configuration file and then reconnect miners to mine with\ntheir chosen username/password to the upstream pool.\n\n\nckdb takes the following options:\n\n-b DBPREFIX | --dbprefix DBPREFIX\n-c CONFIG | --config CONFIG\n-d DBNAME | --dbname DBNAME\n-h | --help\n-k | --killold\n-l LOGLEVEL | --loglevel LOGLEVEL\n-n NAME | --name NAME\n-p DBPASS | --dbpass DBPASS\n-r CKPOOL-LOGDIR | --ckpool-logdir CKPOOL-LOGDIR\n-R LOGDIR | --logdir LOGDIR\n-s SOCKDIR | --sockdir SOCKDIR\n-u DBUSER | --dbuser DBUSER\n-v | --version\n-y | --confirm\n-Y CONFIRMRANGE | --confirmrange CONFIRMRANGE\n\n\nckpmsg and notifier support the -n, -p and -s options\n\n---\nCONFIGURATION\n\nAt least one bitcoind is mandatory in ckpool mode with the minimum requirements\nof server, rpcuser and rpcpassword set.\n\nCkpool takes a json encoded configuration file in ckpool.conf by default or\nckproxy.conf in proxy or passthrough mode unless specified with -c. Sample\nconfigurations for ckpool and ckproxy are included with the source. Entries\nafter the valid json are ignored and the space there can be used for comments.\nThe options recognised are as follows:\n\n\n\"btcd\" : This is an array of bitcoind(s) with the options url, auth  and pass\nwhich match the configured bitcoind. The optional boolean field notify tells\nckpool this btcd is using the notifier and does not need to be polled for block\nchanges. If no btcd is specified, ckpool will look for one on localhost:8332\nwith the username \"user\" and password \"pass\".\n\n\"proxy\" : This is an array in the same format as btcd above but is used in\nproxy and passthrough mode to set the upstream pool and is mandatory.\n\n\"btcaddress\" : This is the bitcoin address to try to generate blocks to.\n\n\"btcsig\" : This is an optional signature to put into the coinbase of mined\nblocks.\n\n\"blockpoll\" : This is the frequency in milliseconds for how often to check for\nnew network blocks and is 100 by default. It is intended to be a backup only\nfor when the notifier is not set up and only polls if the \"notify\" field is\nnot set on a btcd.\n\n\"nodeserver\" : This takes the same format as the serverurl array and specifies\nadditional IPs/ports to bind to that will accept incoming requests for mining\nnode communications. It is recommended to selectively isolate this address\nto minimise unnecessary communications with unauthorised nodes.\n\n\"nonce1length\" : This is optional allowing the extranonce1 length to be chosen\nfrom 2 to 8. Default 4\n\n\"nonce2length\" : This is optional allowing the extranonce2 length to be chosen\nfrom 2 to 8. Default 8\n\n\"update_interval\" : This is the frequency that stratum updates are sent out to\nminers and is set to 30 seconds by default to help perpetuate transactions for\nthe health of the bitcoin network.\n\n\"serverurl\" : This is the IP(s) to try to bind ckpool uniquely to, otherwise it\nwill attempt to bind to all interfaces in port 3333 by default in pool mode\nand 3334 in proxy mode. Multiple entries can be specified as an array by\neither IP or resolvable domain name but the executable must be able to bind to\nall of them and ports up to 1024 usually require privileged access.\n\n\"redirecturl\" : This is an array of URLs that ckpool will redirect active\nminers to in redirector mode. They must be valid resolvable URLs+ports.\n\n\"mindiff\" : Minimum diff that vardiff will allow miners to drop to. Default 1\n\n\"startdiff\" : Starting diff that new clients are given. Default 42\n\n\"maxdiff\" : Optional maximum diff that vardiff will clamp to where zero is no\nmaximum.\n\n\"logdir\" : Which directory to store pool and client logs. Default \"logs\"\n\n\"maxclients\" : Optional upper limit on the number of clients ckpool will\naccept before rejecting further clients.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-com%2Fbupool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitcoin-com%2Fbupool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-com%2Fbupool/lists"}