Integration flow
(Revision 1.01/611)
Provided API simplifies merged mining of the JAX Network with SHA256d-derived networks, and is expected to be easily integrated with already deployed SHA256d mining facilities. Provided documentation describes integration steps and requirements.

Requirements

BTC block AUX

Blocks in JAX Network could be closed by combining JAX Network blocks with solved (up to some target *) BTC blocks (BTC AUX), or other similar network blocks. That allows JAX Network to be merged mined with Bitcoin and rest SHA256d mined networks.
To combine these data structures, the API user only needs to add provided Beacon Block AUX into the merged mining network block's (usually BTC block) coinbase TX. The Beacon ** Block AUX is just a hash of the Jax.Net Beacon block wrapped with special binary markers, that allow it to be easily found into destination coinbase TX.
The API simplifies fetching of this Beacon AUX data and dealing with data structures. Once the coinbase TX is updated and block is mined up to some target — API would deal with composing submitted block into required data structures and publishing it to the network. The API user only needs to deal with already known mining process.
  1. 1.
    Required target is defined by the JAX Network, and could be less or greater than current target of the merged mining network.
  2. 2.
    For more details about what Beacon Chain is please, refer to original JAX Network Academic Paper.

Hash Sorting

Dealing with multiple shards, JAX Network has introduced the way how to control block propagation problem by distributing blocks generation in time*. Thus affects mining process, so it should be briefly explained in this doc.
The idea is that to be accepted by some shard, the PoW hash should begin with required prefix. This prefix is unique for specific shard (until total amount of shards is less than Hash Sorting Number), and can repeat every Hash Sorting number in other case. For instance, if Hash Sorting Number is set to 16 (4 bits) than PoW prefix is 4 bits long. If network has only Beacon Chain (prefix == 0), and lets say 2 shards (prefixes are 1, and 2) than, if PoW hash of submitted block begins with 0, 1, or 2 — the submission would be accepted into the Beacon Chain, or Shard 1, or Shard 2 correspondingly. Otherwise — the submission would be ignored.
Taking into account that Hash Sorting affects difficulty of the shards and Beacon Chain — the idea is to just swap required amount of bits used by target to the beginning of the PoW hash and use them as a prefix.
  • Hash Sorting Number for the Test Net is set to 16.
  • Hash Sorting Number for the Main Net is set to 1024.
The API user should not deal with the HS directly, the API takes care of this aspect **.
  1. 1.
    For more details about what Beacon Chain is please, refer to original JAX Network Academic Paper.
  2. 2.
    The motivation to describe HS here is just to explain why some percent of submissions would be silently ignored and to published into the network (because of Hash Sorting validation failure). The submission failure is suppressed to keep compatibility with legacy miners, that threat jsonRPC errors of sumbitblock method as a transport error and tries to resubmit the same block again and again.

Integration Flow

AUX + Coinbase Update (schema)

Schema 1 — Principal integration flow
This way of integration is the easiest one. It only requires from the API user to fetch Beacon Chain AUX data and to insert it into the required coinbase TX. The way how it could be inserted is the same how other AUX'es are being added to the BTC coinbase (e.g. namecoin).
jsonRPC Method to be used: getaux
1
curl -v --user jaxdev:jaxdev -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"id","method":"getaux","params":[]}' https://merged-mining-api.jax.net:4500
Copied!
Example of the response is:
1
{
2
"error" : null,
3
"id" : "id",
4
"result" : {
5
"beacon_aux_data_hex" : "6a61786e65749cc87f00bb433a7cca295fa2545b49cd139b5c8a809e5519df828d071be583986a61786e6574",
6
"beacon_target" : "00001fff00000000000000000000000000000000000000000000000000000000",
7
"shards_targets" : {
8
"1" : "001ff00000000000000000000000000000000000000000000000000000000000",
9
"2" : "001ff00000000000000000000000000000000000000000000000000000000000",
10
"3" : "001ff00000000000000000000000000000000000000000000000000000000000"
11
}
12
}
13
}
14
Copied!
Provided data contains HEX representation of wrapped with special markers Beacon Chain hash and current targets of the network (on per-shard bases).
After coinbase modification, the updated block should be mined as usual, using stratum-based mechanics, or any other. Once one of the required target is reached — the block should be sent back to the API as is (in format of classic BTC-block). No any changes required. The API would take care about combining this block with the Beacon Block as an AUX and would attempt to close corresponding Beacon Chain block or shard Chain Block (if all validation would pass).
jsonRPC Method to be used: submitblock. The method is totally the same as it is defined in the BTC Core.

Responses auditing

Each response returned from the API contains a signature, that proves it was processed by the API. Corresponding response headers are:
  • sig — HEX representation of the signature.
  • timestampRFC3339 representation of the timestamp of the response processing (UTC).

Public Key

1
-----BEGIN PUBLIC KEY-----
2
MCowBQYDK2VwAyEA+vFM4H28p/9ZpV/oeVBD5D2BqDNuW7/llRPh6orawCg=
3
-----END PUBLIC KEY-----
Copied!

Signature schema

  • Elliptic Curve — ed25519
  • sig = ed25519(H)
  • H — hash of the response, built by chaining another hash (response hash, 32 bytes, see below) and current timestamp in binary form (big endian encoded uint64 — Unix Nanosecond Timestamp format);
H = sha256(ResponseH + T)
T — timestamp of the response processing (on the API side) in the UNIX nano format (int64)
ResponseH — sha256(jsonResponse)
jsonResponse — json marshalled response.
Reference code of response signing (golang):
1
utcNow := time.Now().UTC()
2
utcNowBinary := make([]byte, 8)
3
binary.BigEndian.PutUint64(utcNowBinary, uint64(utcNow.UnixNano()))
4
headers.Add("timestamp", utcNow.Format(time.RFC3339))
5
6
responseHash := sha256.Sum256(marshalledResponse)
7
responseHashAndTimestamp := make([]byte, 0, len(responseHash)+len(utcNowBinary))
8
responseHashAndTimestamp = append(responseHashAndTimestamp, responseHash[:]...)
9
responseHashAndTimestamp = append(responseHashAndTimestamp, utcNowBinary[:]...)
10
hash := sha256.Sum256(responseHashAndTimestamp)
11
12
signature, _ := keystore.KeyChain.Sign(hash[:])
13
signatureHex := hex.EncodeToString(signature)
14
headers.Add("sig", signatureHex)
Copied!
Last modified 22d ago