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:

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.

Troubleshooting

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 stratum API is exposed, using --stratum. 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-stratum HATHOR_STRATUM
                             --hathor-address HATHOR_ADDRESS
                             --bitcoin-rpc BITCOIN_RPC
                             --bitcoin-address BITCOIN_ADDRESS

--port: The port that will be exposed to the miner;
--hathor-stratum: URL where the Hathor fullnode is running, including stratum 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 stratum port 8081 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-stratum http://localhost:8081/v1a/ --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-stratum http://172.16.0.4:8081/v1a/ --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).