Merged Mining JSON RPC API

In order to do merged mining, pools can use these methods:

JSON RPC Methods

• mnr_getWork
• mnr_submitUlordBlock
• mnr_submitUlordBlockTransactions
• mnr_submitUlordBlockPartialMerkle (Recommended)

JSON RPC API Reference

mnr_getWork

Returns the hash of the current block for merged mining, the boundary condition to be met ("target"), parent block hash and notify flag.

Parameters none

Returns

• blockHashForMergedMining: DATA, 32 Bytes - Hash of the USC block that should be used for merged mining. This hash must be included after the USCBLOCK: tag. It is a 256-bit unsigned integer represented as a hexadecimal string.
• target: DATA, 32 Bytes - Target difficulty, the solution of the current work must be smaller than or equal to the target to be a valid block. Merged mined block is considered to be solved if it's hash is below or equal this target. Target is a 256-bit unsigned integer represented as a hexadecimal string.
• parentBlockHash: DATA, 32 Bytes - Parent block hash, 256-bit unsigned integer as a hexadecimal string.
• feesPaidToMiner: QUANTITY - Fees paid to the miner in the USC block in 1/10^18 ulord.
• notify: Boolean - This is a boolean flag that is used by USC node to alert mining pools that there is a new work unit and all previous work units can be updated.

Example

//Request
curl -X POST --data '{"jsonrpc": "2.0", "id":"1", "method": "mnr_getWork", "params": [] }' -H "Content-Type:application/json" 

//Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "jsonrpc":"2.0",
        "id":"1",
        "result":{
            "blockHashForMergedMining":"0x43513e9808bab44f1b4e9858ff737b226d7893d7d7ed4f92fdc885e5d0922672",
            "target":"0x5555555555555555555555555555555555555555555555555555555555555555",
            "feesPaidToMiner":"0",
            "notify":false,
            "parentBlockHash":"0x6953ed2171304931f096307ec71120da1e26d356e2aab6e7c35dbda9997d3f5e"
        }
    }
}

mnr_submitUlordBlock

Used for submitting a solution to USC node. This method sends a Ulord block through the network (~1Mb), for methods that use lower network resources please refer to:

• mnr_submitUlordBlockTransactions
• mnr_submitUlordBlockPartialMerkle

Parameters

Ulord block serialized as hexadecimal.

Returns

• blockImportedResult: DATA - Hexadecimal String, indicates if solution was included or not in the blockchain. Possible status are:
  • 0x494d504f525445445f42455354 (IMPORTED_BEST) - Valid block and added to the main chain.
  • 0x494d504f525445445f4e4f545f42455354 (IMPORTED_NOT_BEST) - Block is valid and was added as an uncle to the chain.
  • 0x4558495354 (EXIST) - Block already exist in chain.
  • 0x4e4f5f504152454e54 (NO_PARENT) - Block parent doesn't exist.
  • 0x494e56414c49445f424c4f434b (INVALID_BLOCK) - Block is invalid.
• blockHash: DATA, 32 Bytes - Hash for the block added to the chain.
• blockIncludedHeight: QUANTITY - Height of the chain where the block was added.

Example

//Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "mnr_submitUlordBlock", "params": ["010000309821be091716ff34ddd54dd79a5d26af10a4214229b78b6e89d490360c000000eb436828fd1883ca69c1c6876174412da9f58f4848a29d7f4d698a7d09eaed593497ee58ffff7f2021393df40101000000010000000000000000000000000000000000000000000000000000000000000000ffffffff1f021402043497ee5808f8000002000000000d2f72736b5f7374726174756d2f000000000240be4025000000001976a914e5e9208d759e89a2e1767f5baeda58f188da206a88ac00000000000000002952534b424c4f434b3a3be5d1c4427993f22f985ff8e99a2b8560b2d1205580867e4eec21123315213b00000000"], "id": 1}' -H "Content-Type:application/json"

//Result
{
  "jsonrpc":"2.0",
  "id":1,"result":{
      "blockImportedResult":"0x494d504f525445445f42455354",
      "blockHash":"0x6953ed2171304931f096307ec71120da1e26d356e2aab6e7c35dbda9997d3f5e",
      "blockIncludedHeight":"0x762"
      }
}

Error Result

{
  "jsonrpc":"2.0",
  "id":1,
  "error":{
    "code":  -33000,
    "message":"Error message.."
  }
}

mnr_submitUlordBlockTransactions

Used for submitting a solution to USC node. This method sends only some information from the Ulord block (hash, header, coinbase, transaction's hashes) It should be used over mnr_submitUlordBlock since it sends less data over the network. Implementation wide, it is considered to be easier to use than mnr_submitUlordBlockPartialMerkle.

Parameters

• blockHashHex: DATA, 32 Bytes - Hash of the Ulord block used for merged mining.
• blockHeaderHex: - DATA, 140 Bytes - Ulord block header used for merged mining.
• coinbaseHex: DATA - Ulord coinbase transaction that belongs to the block used for merged mining.
• txnHashesHex: DATA - Collection of transaction hashes that belong to the block used for merged mining. Said collection must be formatted into a space separated string (e.g. "hash1 hash1 hash2"). The coinbase's hash must not be present in the collection.

Returns

See mnr_submitUlordBlock

Example

//Request
curl -X POST --data '{"jsonrpc":"2.0","method":"mnr_submitUlordBlockTransactions","params":["39eee5957455bfdeaa432605c75659020ac75b378df2d78566449700000000","03000030c72830a3533b330c204ba9176614ca1b9e9c514bfc79efa1fc8674178c5c8c020bfd0e47a9cbcc7fd9acf206420370e2b56f6f89fc2b48f161c8db63671b2712495fcf5affff7f20892982dc","01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff3002ce000004495fcf5a04cb9e820d0c595ecf5a00000000000000000a636b706f6f6c0d2f6d696e656420627920636b2fffffffff02a80a0395000000001976a914d754fa97263b730e513a5ef814e2204e1c6a4aef88ac00000000000000002a6a52534b424c4f434b3af84a70a01da46056fa1329fa5f496cf691afb7df832834071ea3868fa1fe70a200000000","e62c2f2526fb1bd2b12d19ed1b8b545810a2743c6d05a9f241dbedaaed82a8d0"],"id":1}' -H "Content-Type:application/json"

//Result
{
   "jsonrpc":"2.0",
   "id":54,
   "result":{
       "blockImportedResult":"0x494d504f525445445f42455354",
       "blockHash":"0x6953ed2171304931f096307ec71120da1e26d356e2aab6e7c35dbda9997d3f5e",
       "blockIncludedHeight":"0x762"
   }
}

Error Result

{
    "jsonrpc":"2.0",
    "id":1,
    "error":{
        "code": -33000,
        "message":"Error message.."
    }
}

mnr_submitUlordBlockPartialMerkle

Used for submitting a solution to USC node. This method sends only some information from the Ulord block (hash, header, coinbase, coinbase's merkle tree branch hashes, transaction count) It sends minimal data over the network so it is recommended to be used over the other two submit methods provided by this API.

Parameters

• blockHashHex: DATA, 32 Bytes - Hash of the Ulord block used for merged mining.
• blockHeaderHex: - DATA, 140 Bytes - Ulord block header used for merged mining.
• coinbaseHex: DATA - Ulord coinbase transaction that belongs to the block used for merged mining.
• merkleHashesHex: DATA - Collection of merkle hashes from the Ulord block used for merged mining. Hashes should be from partial merkle tree including coinbase in the first index. Said collection must be formatted into a space separated string (e.g. "coinbaseTxHash hash1 hash2 ..."). The coinbase's hash must be present in the collection in the first position.
• blockTxnCountHex: QUANTITY - Length of merkle hashes collection represented as an hexadecimal string.

Returns

See mnr_submitUlordBlock

Example

//Request
curl -X POST --data '{"jsonrpc":"2.0","method":"mnr_submitUlordBlockPartialMerkle","params":["39eee5957455bfdeaa432605c75659020ac75b378df2d78566449700000000","03000030c72830a3533b330c204ba9176614ca1b9e9c514bfc79efa1fc8674178c5c8c020bfd0e47a9cbcc7fd9acf206420370e2b56f6f89fc2b48f161c8db63671b2712495fcf5affff7f20892982dc","01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff3002ce000004495fcf5a04cb9e820d0c595ecf5a00000000000000000a636b706f6f6c0d2f6d696e656420627920636b2fffffffff02a80a0395000000001976a914d754fa97263b730e513a5ef814e2204e1c6a4aef88ac00000000000000002a6a52534b424c4f434b3af84a70a01da46056fa1329fa5f496cf691afb7df832834071ea3868fa1fe70a200000000","39975a670108078346cb166ed991ccc7328f4f8bc06fd4a77b642e0dbcfc7405",1],"id":1}' -H "Content-Type:application/json"

//Result
{
   "jsonrpc":"2.0",
   "id":54,
   "result":{
       "blockImportedResult":"0x494d504f525445445f42455354",
       "blockHash":"0x6953ed2171304931f096307ec71120da1e26d356e2aab6e7c35dbda9997d3f5e",
       "blockIncludedHeight":"0x762"
    }
}

Error Result

{
    "jsonrpc":"2.0",
    "id":1,
    "error": {
        "code":  -33000,
        "message":"Error message.."
    }
}