{"id":28818659,"url":"https://github.com/kadena-io/chainweb-mining-client","last_synced_at":"2025-07-17T04:36:34.680Z","repository":{"id":45966099,"uuid":"282301956","full_name":"kadena-io/chainweb-mining-client","owner":"kadena-io","description":"A mining client for Kadena","archived":false,"fork":false,"pushed_at":"2025-06-06T23:04:14.000Z","size":223,"stargazers_count":43,"open_issues_count":5,"forks_count":11,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-06-06T23:24:35.181Z","etag":null,"topics":["blockchain","chainweb","kadena","mining","proof-of-work"],"latest_commit_sha":null,"homepage":"","language":"Haskell","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/kadena-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2020-07-24T19:37:54.000Z","updated_at":"2025-06-02T03:42:52.000Z","dependencies_parsed_at":"2023-11-06T23:39:46.076Z","dependency_job_id":"1832ab39-a871-4deb-9a34-d85e8c961450","html_url":"https://github.com/kadena-io/chainweb-mining-client","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/kadena-io/chainweb-mining-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadena-io%2Fchainweb-mining-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadena-io%2Fchainweb-mining-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadena-io%2Fchainweb-mining-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadena-io%2Fchainweb-mining-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kadena-io","download_url":"https://codeload.github.com/kadena-io/chainweb-mining-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadena-io%2Fchainweb-mining-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260616578,"owners_count":23036868,"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":["blockchain","chainweb","kadena","mining","proof-of-work"],"created_at":"2025-06-18T19:06:55.572Z","updated_at":"2025-07-17T04:36:34.671Z","avatar_url":"https://github.com/kadena-io.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mining Client for Kadena\n\nA mining client for Kadena's chainweb node mining API. It supports\n\n* mining with ASICs through a stratum server,\n* simulated mining for testing,\n* multi threaded CPU mining,\n* external mining workers (e.g. a GPU),\n* timed miners for non-PoW usecases.\n\n*Competitive mining on the Kadena Mainnet requires special mining hardware\n(ASIC), which connects to a Stratum Server from where it obtains work.*\n\n*All other mining modes (GPU, CPU, and simulation) are intended only for testing.*\n\n*   [Installation](#installation)\n*   [Usage](#usage)\n*   [Usage Examples](#usage-examples)\n    *  [Generating a New Key Pair](#generating-a-new-key-pair)\n    *  [Mining on Mainnet With an ASIC](#mining-on-mainnet-with-an-asic)\n    *  [CPU Mining](#cpu-mining)\n    *  [GPU Mining](#gpu-mining)\n    *  [Creating a Configuration File](#creating-a-configuration-file)\n*   [Related Resources](#related-resources)\n\n## Installation\n\nA docker image of the latest version is available at\n`ghcr.io/kadena-io/chainweb-mining-client:latest`.\n\nBinaries can also be compiled with a recent version of GHC and cabal directly\nfrom [Hackage](https://hackage.haskell.org/package/chainweb-mining-client)\n\n```sh\ncabal install chainweb-mining-client\n```\n\nor from the GitHub sources\n\n```sh\ngit clone https://github.com/kadena-io/chainweb-mining-client/\ncd chainweb-mining-client\ncabal build\ncabal run chainweb-mining-client -- --help\n```\n\n## Usage\n\nCalling `chainweb-mining-client --help` provides an overview of the available\nusage options:\n\n```txt\nUsage: chainweb-mining-client [--info] [--long-info] [-v|--version] [--license]\n                              [-?|-h|--help]\n                              [--print-config-as full|minimal|diff |\n                                --print-config] [--config-file FILE]\n                              [-r|--hash-rate ARG] [-n|--node DOMAIN:PORT]\n                              [(-t|--tls) | --no-tls]\n                              [(-x|--insecure) | --no-insecure]\n                              [-k|--public-key ARG] [-a|--account ARG]\n                              [-c|--thread-count ARG]\n                              [--generate-key | --no-generate-key]\n                              [-l|--log-level error|warn|info|debug]\n                              [-w|--worker cpu|external|simulation|stratum|constant-delay|on-demand]\n                              [--external-worker-cmd ARG] [--stratum-port ARG]\n                              [--stratum-interface ARG]\n                              [--stratum-difficulty ARG] [-s|--stratum-rate ARG]\n                              [--constant-delay-block-time ARG]\n                              [--on-demand-interface ARG] [--on-demand-port ARG]\n\n  Kadena Chainweb Mining Client\n\nAvailable options:\n  --info                   Print program info message and exit\n  --long-info              Print detailed program info message and exit\n  -v,--version             Print version string and exit\n  --license                Print license of the program and exit\n  -?,-h,--help             Show this help message\n  --print-config-as full|minimal|diff\n                           Print the parsed configuration to standard out and\n                           exit\n  --print-config           Print the parsed configuration to standard out and\n                           exit. This is an alias for --print-config-as=full\n  --config-file FILE       Configuration file in YAML or JSON format. If more\n                           than a single config file option is present files are\n                           loaded in the order in which they appear on the\n                           command line.\n  -r,--hash-rate ARG       hashes per second (only relevant for mining\n                           simulation, ignored by the cpu worker)\n  -n,--node DOMAIN:PORT    node to which to connect\n  -t,--tls                 use TLS to connect to node\n  --no-tls                 unset flag tls\n  -x,--insecure            accept self-signed TLS certificates\n  --no-insecure            unset flag insecure\n  -k,--public-key ARG      public-key for the mining rewards account\n  -a,--account ARG         account for the mining rewards (default: public-key\n                           prefixed with 'k:')\n  -c,--thread-count ARG    number of concurrent mining threads\n  --generate-key           Generate a new key pair and exit\n  --no-generate-key        unset flag generate-key\n  -l,--log-level error|warn|info|debug\n                           Level at which log messages are written to the\n                           console\n  -w,--worker cpu|external|simulation|stratum|constant-delay|on-demand\n                           The type of mining worker that is used\n  --external-worker-cmd ARG\n                           command that is used to call an external worker. When\n                           the command is called the target value is added as\n                           last parameter to the command line.\n  --stratum-port ARG       the port on which the stratum server listens\n  --stratum-interface ARG  network interface that the stratum server binds to\n  --stratum-difficulty ARG How the difficulty for stratum mining shares is\n                           choosen. Possible values are \"block\" for using the\n                           block target of the most most recent notification of\n                           new work, or number between 0 and 256 for specifiying\n                           a fixed difficulty as logarithm of base 2 (number of\n                           leading zeros).\n  -s,--stratum-rate ARG    Rate (in milliseconds) at which a stratum worker\n                           thread emits jobs.\n  --constant-delay-block-time ARG\n                           time at which a constant-delay worker emits blocks\n  --on-demand-interface ARG\n                           network interface that the on-demand mining server\n                           binds to\n  --on-demand-port ARG     port on which the on-demand mining server listens\n\nConfigurations are loaded in order from the following sources:\n  1. Configuration files from locations provided through --config-file options\n     in the order as they appear.\n  2. Command line options.\n\nConfiguration file locations can be either local file system paths or remote\nHTTP or HTTPS URLs. Remote URLs must start with either \"http://\" or \"https://\".\n\nConfiguration settings that are loaded later overwrite settings that were loaded\nbefore.\n```\n\n## Usage Examples\n\n### Generating a New Key Pair\n\n```sh\nchainweb-mining-client --generate-key\n```\n\nThis outputs a public and a private key. The public key is given to the mining\nclient. The private key must be kept secret.\n\n```txt\npublic:  87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cf\nprivate: 64ef6379db5ef6004aff98182688c6e8b4a5229e706f1ccf6a73b05b1432aedf\n```\n\n### Mining on Mainnet With an ASIC\n\nchainweb-mining-client needs access to the mining API of a full [Chainweb\nnode](https://github.com/kadena-io/chainweb-node) in\nthe Kadena Mainnet. The node must be configured to enable the mining API with\nthe Pact *public* key (and, optionally, account name) of the miner. Rewards for\nmined blocks will be credited to that account. The default is to use the `k:`\naccount for the key.\n\nThe `--enable-mining-coordination`, `--mining-public-key` can be used to\nconfigure chainweb-node for mining. The mining API is served on the service API\nport (default is 1848).\n\n\nAssuming that `example.com` serves the chainweb-node mining API on port 1848,\nthe following command can be used to run chainweb-mining-client with the stratum\nserver on port 1917:\n\n```\nchainweb-mining-client \\\n    --public-key 87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cf \\\n    --node example.com:1848 \\\n    --stratum-port 1917\n```\n\nAssuming that the host on which chainweb-mining-client runs is 192.168.1.2, the\npool address that is used to configure the ASIC miner is\n`stratum+tcp://192.168.1.2:1917`.\n\nOne can point more than a single ASIC miner to the same chainweb-mining-client\nstratum server. All connected clients work together and all mining rewards are\ncredited to the same account, that is configured in chainweb node.\n\nBy default the stratum server sets the difficulty of the work that is sent to\nthe mining clients to the actual difficulty of the block of the most recent\nwork. This means that it can take a long time before the client solves any work.\nIt also means that the target is reset for each new block.\n\nIt is also possible to set a custom difficulty. As a consequence not all\naccepted solutions qualify as solved blocks, but ASIC miner may provide a more\ncontinuous feedback on its current performance. Some devices may also be more\nefficient in this mode an yield higher returns.\n\nThe thread count determines how many independent stratum works are used to\nconcurrently provide work to the clients. Each stratum worker receives one work\nheader at a time from the chainweb-node mining API and emits jobs for that work\nto all clients at a configurable rate. The effective rate of jobs is higher than\nthen configured rate because when upstream work gets preempted. Each client\nreceives are all jobs from all workers.\n\nThe following command runs two stratum workers that serve jobs at least every 500\nmilliseconds at a fixed difficulty level of 50.\n\n```\nchainweb-mining-client \\\n    --public-key 87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cf \\\n    --node example.com:1848 \\\n    --stratum-port 1917 \\\n    --stratum-difficulty=50 \\\n    --stratum-rate=500 \\\n    --thread-count=2\n```\n\nThe solution space for each mining job is about 280 terra hashes. The\n`--stratum-rate` should be chosen such that the mining devices does not perform\nmore than that number of hashes within the provided time range. For instance,\nfor an miner that performs 140TH/s the `--stratum-rate` should be at most 2000 milliseconds\n(2 seconds).\n\nThe `--stratum-difficulty` parameter expects a integral number between 0 and\n256. It denotes the difficulty as a logarithm of base 2. In practice the actual\ntarget uses a difficulty level of at least 42 and at most the difficulty of\nblock of the current work.\n\nIt may help to experiment a little with the `--stratum-difficulty`,\n`--stratum-rate`, and the `--thread-count` parameters. We found, that small\nvalues for `--thread-count` (one to three) and moderate values for\n`--stratum-difficulty` (in the upper forties / lower fifties) yielded good\nresults. The But that may differ between different devices and setups.\n\nIf the chainweb-node mining API is served via a reverse proxy with TLS the\n`--tls` flag must be used to enable HTTPS.\n\n### CPU Mining\n\nAssuming that `example.com` serves the chainweb-node mining API on port 1848, the\nfollowing command can be used for CPU mining to the from the previous example:\n\n```sh\nchainweb-mining-client \\\n    --public-key 87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cfa \\\n    --node example.com:1848 \\\n    --worker cpu \\\n    --thread-count 16 \\\n```\n\n### GPU Mining\n\nGPU mining is supported via calling an external worker that does the mining\nwork. An example for such a GPU mining tool for Kadena is\n[bigolchunugus](https://github.com/kadena-community/bigolchungus).\n\n```sh\nchainweb-mining-client \\\n    --public-key 87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cf \\\n    --node example.com:1848 \\\n    --worker external \\\n    --external-miner-cmd bigolchunus\n```\n\nFor selecting the GPU or passing additional arguments to the external tools, the\nextra parameters are appended to the command. E.g.\n\n```sh\nchainweb-mining-client \\\n    --public-key 87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cf \\\n    --node example.com:1848 \\\n    --worker external \\\n    --external-worker-cmd \"bigolchunus -d 2\"\n```\n\nThe external mining tool is called by adding the target as the last command line\nparameter and passing the work bytes on stdin.\n\n### Non-PoW mining\n\nThe Non-PoW mining modes ignore the PoW nonce of block headers, instead just\nreturning the input block header when they \"mine\" a block. Naturally this makes\ntheir blocks invalid from the perspective of mainnet or testnet. A chainweb\nnode running in development mode can disable the PoW validity check by setting\nthe DISABLE_POW_VALIDATION environment variable to `1`, making these modes\nproduce valid blocks.\n\nThe modes are:\n    1. simulation. This mode accepts a hash rate via `--hash-rate`, for example\n       `--hash-rate 100M` and produces a block with a delay congruent with\n       running a real miner at the given hash rate, given the difficulty of the\n       block header being mined.\n\n       This mode is useful for testing difficulty adjustment, but because block\n       mining times have a long tail, it may be time consuming.\n\n    2. constant-delay. This mode accepts a delay in seconds via\n       `--constant-delay-block-time` and produces blocks at a constant rate,\n       i.e. a heartbeat, ignoring the block's difficulty.\n\n       This mode is useful for testing that does not involve PoW or difficulty\n       adjustment at all.\n\n    3. on-demand. This mode creates an HTTP server that binds to the configured\n       interface and port, and listens for a POST request to the `/make-blocks`\n       endpoint. The body is a JSON object mapping chain IDs to counts of\n       blocks to mine on those chains. The worker will only mine blocks as\n       required to mine as many blocks as have been requested and maintain the\n       braiding condition of chainweb.\n\n       This mode is useful for generating blocks just after submitting the\n       transactions that make them up, or generating empty blocks in bulk to\n       get past a certain block height and test some new behavior.\n\n### Creating a Configuration File\n\nThe current configuration of chainweb-mining-client can be stored in a\nconfiguration file by adding the `--print-config` parameter\n\n```sh\nchainweb-mining-client \\\n    --public-key 87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cf \\\n    --node example.com:1848 \\\n    --stratum-port 1917 \\\n    --statum-difficulty=50\n    --print-config \u003e config.yml\n```\n\nThis results in the following configuration file:\n\n```yaml\naccount: null\nexternalWorkerCommand: echo 'no external worker command configured' \u0026\u0026 /bin/false\ngenerateKey: false\nhashRate: 1000000.0\ninsecure: true\nlogLevel: info\nnode: example.com:1848\npublicKey: 87ef8fdb229ad10285ae191a168ea2ec0794621a127df21e372f41fd0246e4cf\nstratumDifficulty: 50\nstratumInterface: '*'\nstratumPort: 1917\nthreadCount: 10\nuseTls: true\nworker: stratum\n```\n\nThe configuration can then be used via\n\n```sh\nchainweb-mining-client --config-file config.yml\n```\n\n## Related Resources\n\n*   [Chainweb Node Project Page](https://github.com/kadena-io/chainweb-node)\n*   [Kadena Stratum Protocol](https://gist.github.com/mightybyte/f1567c2bec0380539c638225fb8c1cf4)\n*   [mining API of chainweb-node](https://api.chainweb.com/openapi/#tag/mining)\n*   [work header format](https://github.com/kadena-io/chainweb-node/wiki/Block-Header-Binary-Encoding#work-header-binary-format).\n*   [mining API wiki](https://github.com/kadena-io/chainweb-node/wiki/Mining-API).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkadena-io%2Fchainweb-mining-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkadena-io%2Fchainweb-mining-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkadena-io%2Fchainweb-mining-client/lists"}