Some questions about merged mining

[Grizzly1127]

I'm a developer of the mining pool service.
Regarding the merged mining of hathor, I have a questions I want to ask, and I hope to get your answer.

When I write hathor's merged mining program in my service, do I need to construct htr_block_hash after getting the result through get_block_template?

I look forward to your reply.

[jansegre]

The merged mining RFC covers all about constructing the bytes that are needed for making merged mining blocks. But it doesn't show how to use any API, that's is something we can definitely improve.

I'm not sure what you're calling htr_block_hash, maybe it is what the RFC calls base_hash, that is the hash that goes into the parent (for example BTC) chain's coinbase. If you're using get_block_template you will have to construct the base_hash.

I would also recommend using the merged mining websocket (/v1a/mining_ws) instead of get_block_template. You can try the API with wscat -c https://miners.mainnet.hathor.network/v1a/mining_ws, but I highly recommend using your own node for production.

If you have any suggestions, like what type of examples would help, or if there is any information we can add to an API that would make your life easier. I'd love to hear it.

[jansegre]

/v1a/mining_ws unfortunately isn't well documented. I'll go briefly on the fields:

# it is formatted as JSONRPC over WebSocket
{
  "id": null,
  # this method is sent periodically and as soon as there is a new block, so you don't have to call an API every time and always have a little latency when the parent_hash changes
  "method": "mining.notify",
  "params": [
    {
      # this is a sample data of how all the fields would be serialized with no output
      # - you can either use this data as a base for adding the output and generating the [aux_block_hash]
      # - or use this to test if you are serializing the other fields correctly
      "data": "00000100000c80000000404fa9a391d06f5a60de8e3e03000000000000000016aaabc1b4fe6ab98d4341326a3040e06c6f83a8b870d0b400000000459226083d3e23d4113c707b0aeade8d3bd16d5e591b91fd5c6b451400000717377b04388cc0fe5b1291e072cd6b925aa5c5bc41e5e7a10079251b9c00",
      # starting from here all these are values that either go directly in a field or limit what values will be accepted
      # this are the values accepted for the version field
      "versions": [
        0,
        3
      ],
      # amount to use in the output
      "reward": 3200,
      # weight is another formula for difficulty
      "weight": 63.325304247641455,
      # these are hints on how to fill the timestamp field, timestamp_now is an acceptable value, but it can be anything between timestamp_min and timestamp_max
      "timestamp_now": 1625198152,
      "timestamp_min": 1625198142,
      "timestamp_max": 1625202640,
      # this are the parents that _have_ to be included (it's always between 1 and 3 elements)
      "parents": [
        "000000000000000016aaabc1b4fe6ab98d4341326a3040e06c6f83a8b870d0b4",
        "00000000459226083d3e23d4113c707b0aeade8d3bd16d5e591b91fd5c6b4514",
        "00000717377b04388cc0fe5b1291e072cd6b925aa5c5bc41e5e7a10079251b9c"
      ],
      # if there are less than 3 elements above, any of the parents here can be used to complete the list (a Hathor block always has exactly 3 parents: 1 block and 2 transactions)
      "parents_any": [],
      # informational fields, these don't affect anything but can be used to prioritize a node (if one node returns a score or height different than another, they are out of sync and the one with best score should be used)
      "height": 1559449,
      "score": 84.09203077778888
    }
  ]
}

The data field above can be split in:

• funds: 00000100000c80000000
• graph: 404fa9a391d06f5a60de8e3e03000000000000000016aaabc1b4fe6ab98d4341326a3040e06c6f83a8b870d0b400000000459226083d3e23d4113c707b0aeade8d3bd16d5e591b91fd5c6b451400000717377b04388cc0fe5b1291e072cd6b925aa5c5bc41e5e7a10079251b9c00

The funds part is not yet marked as merged mining and lacks an output script. For example, if your address was H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1 the funds with correct output would be:

• funds 00030100000c8000001976a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac

Then you would continue with:

block_header_without_nonce = sha256(block_funds) + sha256(block_graph)
aux_block_hash = sha256d(block_header_without_nonce)

Like in the RFC (note that sha256 != sha256d).

In the example above (assuming the address H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1, don't forget to use your address), the result would be:

hash_funds = 1aeeb6b50457026369142d147d6dd8cc66162580a931e33fab7007488cb99c86
hash_graph = 484be6584337ba6df9dccdf03fabcb2d28af1d96a60652c2bd9e953d00734f2a
aux_block_hash = 3ba08844bd9942e6fbe343f95937cee6ea0d9841008ccae2624a586f97889aae

And after mining a Bitcoin block with [magic_number] [aux_block_hash] in the coinbase, you will need to build the aux_pow to have a complete Hathor block. Which can be sent on the same WebSocket channel like:

{
  # this id should vary to distinguish differrent requests, can be a string, not limited to numbers
  "id": 1,
  "method": "mining.submit",
  "params": {
    # basically `[funds] [graph] [aux_pow]`, this example is missing the `aux_pow`
    "hexdata": "00030100000c8000001976a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac404fa9a391d06f5a60de8e3e03000000000000000016aaabc1b4fe6ab98d4341326a3040e06c6f83a8b870d0b400000000459226083d3e23d4113c707b0aeade8d3bd16d5e591b91fd5c6b451400000717377b04388cc0fe5b1291e072cd6b925aa5c5bc41e5e7a10079251b9c00..."
  }
}

[Grizzly1127]

Your answer is very useful to me. But I still have a problem:

The funds part is not yet marked as merged mining and lacks an output script. For example, if your address was H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1 the funds with correct output would be:

funds 00030100000c8000001976a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac

0003 is version，0100000c800000 is funds in data, 1976a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac is an address(H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1), Am I right? How to convert address?

[jansegre]

0003 is version，0100000c800000 is funds in data, 1976a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac is an address(H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1), Am I right? How to convert address?

That's right. 76a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac is an output script, it is included as [script length] [script], the script has 25 bytes (0x19) so it is included as 1976a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac. The sample data from the API has 00 because the length is 0, so it can be parsed.

To convert and address to an output script, is basically like this:

• H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1 is encoded in base58, when parsed these are the bytes: 2821cef9fa40363507cf465f6309b6cc8581a9d9f52c5c04ba;
• Of those 25 bytes, the first byte is the network identifier (it makes the base58 address always start with H and not mix it with other network's addresses, and also indicate that it is a P2PKH script) and the last 4 bytes are use for checksum (it is the first 4 bytes of the sha256 of the previous 21 bytes). Those 20 bytes in the middle are the public key that the wallet generated for that address: 21cef9fa40363507cf465f6309b6cc8581a9d9f5
• A P2PKH (with no timelock) is basically OP_DUP OP_HASH160 (DATA_20) OP_EQUALVERIFY OP_CHECKSIG, the opcodes for that are:
  • OP_DUP: 0x76
  • OP_HASH160: 0xa9
  • DATA_20: 0x14 [20 bytes]
  • OP_EQUALVERIFY: 0x88
  • OP_CHECKSIG: 0xac
• Putting that together it is 76 a9 14 21cef9fa40363507cf465f6309b6cc8581a9d9f5 88 ac

If you have a hathor-core environment setup, you can do this to check it both ways:

from hathor.transaction import scripts
scripts.P2PKH('H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1').get_script().hex()  # -> '76a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac'
scripts.parse_address_script(bytes.fromhex('76a91421cef9fa40363507cf465f6309b6cc8581a9d9f588ac')).address  # -> 'H9btdenbJ1QTNGWTM7U9Hsoz27HCZ5ygC1'

[Grizzly1127]

I have one last question, do you have testnet explorer?

[jansegre]

Yes: https://explorer.testnet.hathor.network/ Just keep in mind that testnet addresses start with W (with the bytes 0x49 after base58 parsed).