minerstat mining tutorial #32: Custom mining clients

Published in

minerstat

6 min readApr 13, 2019

Before introducing this new feature to all of the minerstat users, implementation of the custom miner required you to write to us and request a custom miner, which we would then implement and prepare for your usage. From now on, you are able to implement your own custom mining client by yourself. This doesn’t mean we will stop adding new mining clients per request but gives all of you an option to use a custom mining client without any delay. It also gives farms an opportunity to have control over their own private miners without anyone accessing the mining client files.

Our goal was to create this feature in a way that allows flexibility as much as privacy.

In this tutorial, we will show you two things:

How to prepare a package that can be used as a custom mining client with minerstat mining OS.
How to create a new mining client on your minerstat dashboard and then use it in the worker’s config. The same procedure can be applied to the scheduler, config templates, and profit switch.

💡 While the second step is very straightforward and its difficulty is not much different than using the minerstat dashboard, the first one requires some development and programming knowledge.

1. Preparing mining client’s package

In this tutorial, we will show you an example of how to create a package for implementing ArioMiner. We decided to use this miner as an example as it was previously suggested for implementation by one of our customers and the fact that ArioMiner doesn’t use JSON API for reporting. From the point of mining management software, it is really welcome for mining client developers to provide a JSON API. From this example, you can see that you can use minerstat mining OS even if there is no JSON API report.

The package that you will prepare for msOS should contain:

The mining client and all of its files.
Modified API file (you can find the template here).

ArioMiner example

To check the files while you are reading this tutorial, you can first download the prepared package. The package is a .zip file that contains two files:

ariominer executable
api bash script

The first is an executable mining client with all necessary files and the second is a modified api file. Since ArioMiner doesn’t report the results, we will enable logging that will save some of the data to log.txt file. The API bash script will then read the data that is available in the log.txt and serve it in the required format. If you will be implementing any other mining client, its approach might be different and the data will need to be read differently.

Let’s take a look at the api file.

Hashrate (in H/s)
To read the hashrate from the log.txt file, the following code is used.

hashrate_total=$(tac /home/minerstat/minerstat-os/clients/ariominer/log.txt | grep "Hash Rate:" | head -n 1 | cut -f1 -d"/" | sed 's/[^0-9.]*//g' | cut -f1 -d".")

Please note that hashrate must always be provided in H/s (1 kH/s = 1 000 H/s; 1 MH/s = 1 000 000 H/s; 1 GH/s = 1 000 000 000 H/s; and so on).

Uptime (in seconds)
To read the uptime in seconds from the log.txt file, the following code is used.

uptime_in_sec=$(tac /home/minerstat/minerstat-os/clients/ariominer/log.txt | grep "Time:" | head -n 1 | sed 's@.*Time: @@' | cut -f1 -d"S" | sed 's/[^0-9.]*//g')

Please note that uptime must always be provided in seconds.

Pool URL
Unfortunately, log.txt doesn’t report information about the pool. Because of this, we have to enter the pool data manually.

pool="aropool.com:80"

Shares
To read the accepted and rejected shares from the log.txt file, the following code lines are used.

shares_accepted=$(tac /home/minerstat/minerstat-os/clients/ariominer/log.txt | grep "Shares:" | head -n 1 | sed 's@.*Shares: @@' | cut -f1 -d"F" | sed 's/[^0-9.]*//g')shares_rejected=$(tac /home/minerstat/minerstat-os/clients/ariominer/log.txt | grep "Rejected:" | head -n 1 | sed 's@.*Rejected: @@' | sed 's/[^0-9.]*//g')

At the end of the file, the following format must stay unchanged.

echo "hashrate_total:$hashrate_total,uptime:$uptime_in_sec,pool:$pool,shares_rejected:$shares_rejected,shares_accepted:$shares_accepted$hashrate_gpu"

Without that last line, the data would not get processed and sent from msOS to your minerstat dashboard.

So, when you have both mining client executables and API file ready, you can compress them in a .zip or .tar.gz and upload them to your selected server (even a local one that is accessible only from the rig).

2. Adding mining client to the dashboard

The next step is to add the mining client to the dashboard. Navigate to the custom clients page. Click on the button to add a new mining client and enter all necessary information. Each mining client requires the following information: name, package URL, executable file name, client config type, client args/config, and extra args.

For the ArioMiner example we will add the following information.

Name

The name is used on the dashboard, worker’s config, profit switch, config templates, and scheduler.

ARIOMINER

Package URL

The URL to your mining client. It can also be a local URL or URL that is accessible only from your rig which assures you maximum possible privacy.

https://static-ssl.minerstat.farm/miners/custom/ariominer.zip

Executable file name

The first file you have created in the first step of this tutorial. The name is case sensitive.

ariominer

Client config type

If your mining client reads configs from the external file, select Config file and if your mining client reads configs from arguments, select Arguments.

Arguments

Client args/config

Provide default config for your client.

--mode miner--pool http://aropool.com:80/ --wallet 4fAkEHALahEbDRobAbJgW3Mi9eTFNK2dTa7VD6ngR4ve1znXhh1jX3RoHibUdttGCoGAjLtcSLWJRvXTbaL4g3CK --name test -c 0 -g 93 -x 100

Extra args

Define extra arguments that will be called on the client run. We will enable logging by adding an extra argument as defined below. This will allow API bash script to read the information about hashrate, uptime, and rejected and accepted shares.

| tee log.txt

When you have entered all of the fields you can click Save.

The next step is to navigate to the worker’s config page and select your new mining client as a default mining client. All custom mining clients are denoted with blue color. Enter your configuration and save changes.