Skip to main content
Software

Merged Mining guide

What's merged mining?

Merged mining means that one can mine both Hathor and Bitcoin at the same time, at the cost of dedicating a few bytes of the BTC block payload to carry HTR data.

For the full techinical specification, check out the Merged Mining RFC.

As the Bitcoin network hashrate is extremely high, it's unlikely that a Bitcoin block is found when doing solo merged mining. However, the advantage of merged mining over direct mining (only mining HTR) is that it's possible to use unmodified mining equipment, the same as when mining Bitcoin.

Currently we provide a stratum server for doing solo merged mining that anyone can use. Feel free to run your own server though.

Using the public server

Our public stratum server runs at stratum+tcp://beta.mm.hathor.network:3333.

It is in beta phase, and although we think it's working well there might be problems from time to time.

The only requirement for using this server is that the login username/workername needs to have a Hathor address and a Bitcoin address under a special format: {HTR_ADDRESS}.{BTC_ADDRESS}.{WORKER_NAME} or {HTR_ADDRESS}.{BTC_ADDRESS} (WORKER_NAME is optional and has no format restriction).

For example, these are two valid usernames/workernames:

These addresses are used directly on the coinbase output of each coin that the miner is mining. This is because even though it uses a pool protocol (stratum) it is still solo mining both coins.

Caveats: because it is solo mining, finding any BTC will be very unlikely.

Using it with Mining Rig Rentals (MRR)

This server has been extensively tested with Sha256 rigs on MRR.

You can add this server to your Favorite Pools, click "Add Pool", and fill these fields:

- Name: anything you want, like Hathor MM Beta
- Type: Sha256 (Sha256 Asicboost will not work)
- Pool Host:Port: beta.mm.hathor.network:3333
- Workername (-u): {HTR_ADDRESS}.{BTC_ADDRESS}.{WORKER_NAME} or {HTR_ADDRESS}.{BTC_ADDRESS} (with your addresses)
- Password (-p): anything, ignored by the server
- Notes: anything (even blank)

For example (note that Workername (-u) field is cropped, but the full value is there):

MRR Add Pool

Caveats: because Hathor needs to update jobs more frequently than Bitcoin, jobs have generally smaller difficulty. MRR may complain sometimes about a low difficulty, but it should be fine.

Using it with NiceHash (NC)

NiceHash is also supported. First, add the server to your list of pools:

NiceHash Add Pool

Configure the pool settings:

- Custom pool name: anything you want, like Hathor MM Beta
- Algorithm: SHA256
- Stratum hostname or IP: beta.mm.hathor.network
- Port: 3333
- Username: {HTR_ADDRESS}.{BTC_ADDRESS}.{WORKER_NAME} or {HTR_ADDRESS}.{BTC_ADDRESS} (with your addresses)
- Password (-p): anything that contains nicehash. It can be in any caps or position (e.g. `NICEHASH`, `nicehash`, `NiceHash`, `xxxnicehashxxxx`)

NiceHash Pool Settings

Then you just need to go to the Marketplace page and place an order to start mining. Remember to filter orders for SHA256.

Troubleshooting

You can search for your miners/workers on https://beta.mm.hathor.network/status to see info like the mining difficulty (as set by the server) and hashrate (as estimated by the server). Note that this will require a JSON viewer (built-in in Firefox, but not Chrome).

If you experience any problem, please go to our Discord channel #mining and let us know.

Setting up your own server

To setup merged mining, you need some components:
1. Hathor fullnode;
2. Bitcoin fullnode;
3. Merged mining coordinator;

The miner connects directly to the Merged Mining Coordinator and request a mining job. The coordinator gets block templates from both Bitcoin and Hathor's full nodes, and use both of them to create the mining job. When the miner finds a solution to the mining job, they submit the solution to the coordinator, which will validate it and, if a block is found, the coordinator propagates the block to the corresponding network (either Hathor or Bitcoin or both).

┌───────────────┐                  ┌───────────────────┐
│               │◀───Get block─────│                   │
│   Hathor      │    template      │                   │
│   Full node   │                  │                   │                ┌───────────┐
│               │◀──Submit block───│                   │◀───Get job─────│           │
└───────────────┘                  │   Merged Mining   │                │   Miner   │
                                   │   Coordinator     │◀───Submit──────│           │
┌───────────────┐                  │                   │    solution    └───────────┘
│               │◀───Get block─────│                   │
│   Bitcoin     │    template      │                   │
│   Full node   │                  │                   │
│               │◀──Submit block───│                   │
└───────────────┘                  └───────────────────┘

Hathor fullnode

Check this guide for running a Hathor fullnode.

It's important to write down the port where the API is exposed, using --status. It'll be used later when starting the coordinator.

Bitcoin fullnode

Instructions for running a Bitcoin fullnode can be found here.

You can set RPC username and port by using -rpcuser and -rpcpassword. Default fullnode port is 8332 for mainnet.

Merged Mining Coordinator

The Hathor coordinator is available on the same repository as hathor-core: https://github.com/HathorNetwork/hathor-core.

Starting it is similar to starting a fullnode:

hathor-cli run_merged_mining --port PORT
                             --hathor-api HATHOR_API
                             --hathor-address HATHOR_ADDRESS
                             --bitcoin-rpc BITCOIN_RPC
                             --bitcoin-address BITCOIN_ADDRESS

--port: The port that will be exposed to the miner;
--hathor-api: URL where the Hathor fullnode is running, including API port;
--hathor-address: your Hathor address, where the HTR block reward is sent;
--bitcoin-rpc: URL where the Bitcoin fullnode is running;
--bitcoin-address: your bitcoin address, where the BTC block reward is sent;

Supposing the Hathor fullnode is running on localhost with API exposed on port 8080 and Bitcoin fullnode is on the local network (let's say 192.168.1.34; user=foo, password=bar), this would be the starting command:

hathor-cli run_merged_mining --port 9000 --hathor-api http://localhost:8080/ --hathor-address HATHOR_ADDRESS --bitcoin-rpc http://foo:bar@192.168.1.34:8332 --bitcoin-address BITCOIN_ADDRESS

WARNING: you must replace HATHOR_ADDRESS and BITCOIN_ADDRESS with your own Hathor and Bitcoin addresses

Docker image

The coordinator can also be run with the same Docker image as the fullnode.

docker run -ti -p 9000:9000 hathornetwork/hathor-core run_merged_mining --port 9000 --hathor-api http://172.16.0.4:8080/ --hathor-address HATHOR_ADDRESS --bitcoin-rpc http://foo:bar@192.168.1.34:8332 --bitcoin-address BITCOIN_ADDRESS

When running the coordinator and fullnode on the same host with Docker, they won't be able to communicate by using localhost, as each container runs on a separate network stack. It's recommended to use the IP of the fullnode's container (here's how to find a container's IP address).