Skip to main content

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 technical 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.

Mining pools

Using a mining pool is the best option for merged mining.

There are currently three third-party mining pools supporting merged mining between Hathor and Bitcoin:
- acc-pool: website, Discord
- Zulu Pool: website, Discord
- f2pool: website, Discord

These pools are managed by community members and are not affiliated to the Hathor team.

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:

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; 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@ --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 --hathor-address HATHOR_ADDRESS --bitcoin-rpc http://foo:bar@ --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).