🚀
JAX Merged Mining API integration flow description
Provided API simplifies merged mining of the JAX Network with
SHA256d
-derived networks (like BTC, BCH, BSV, etc), and are expected to be easily integrated with already deployed mining facilities without impact on hash rate generated. Provided documentation describes all the details needed for successful integration. As developers, we do understand how important it is to have a direct way of communication with third-party developers during an integration process. We prefer fast and efficient communication channels (like Telegram, Discord, etc) and would set up a communication channel for you ASAP. All you need to do is to notify us via [email protected]
- Lower complexity Using an API allows you to delegate maintenance of the JAX-nodes infrastructure directly to us. You do not need to have a deep knowledge of how to deploy it, control it, and how to maintain it.
- Lower resources consumption (including human resources) You can do and support the integration with the help of the same team that supports your mining facilities. Since there are no additional deployments and components — you will most probably not need additional data center resources or human resources.
- HashRate risk-free The proposed integration schema being implemented correctly does not affect the level of the hash rate generated for the original network.
Dealing with multiple shards, JAX Network has introduced a way how to control block propagation problems by distributing blocks generation in time. This affects the 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 the required prefix. This prefix is unique for specific the shard (until the 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) then the PoW prefix is 4 bits long. If the network has only Beacon Chain (prefix == 0), and let's say 2 shards (prefixes are 1, and 2) then if the PoW hash of the 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 the difficulty of the shards and Beacon Chain — the idea is to just swap the required amount of bits used by the target to the beginning of the PoW hash and use them as a prefix, so the PoW would look like
<
target bits..><hash sorting bits>
It is strictly suggested for the pool to implement this HS filtering on its side.
Otherwise, there would be a huge amount of unusable submissions to the API, which could use the redundant amount of traffic and make significant pressure on the RPC communication layer.

Fig. 1 — Principal schema of API integration with the Mining Pool
As shown on this schema, merged mining API hides the complexity of managing nodes and the infrastructure and proxies 2 RPC methods which allows the mining pool to do merged mining with present
sha256d
network.
The flow is as simple as follows:
- The mining pool constantly (asynchronously, in a loop) fetches AUX data using the method
getaux
This method provides targets for the beacon and each shard of the JAX network as well as HEX-encoded AUX data. - Being fetched this data is then used to form the coinbase TX for BTC, BCH, or BSV (depends on which network is originally mined by the pool) according to requirements specified here. Following these specific requirements is strictly required to make it possible for JAX to be merge-mined with an external
sha256d
network. - Once mined up to one of the required targets (the least one is usually used), the pool must pass the newly generated block through the Hash Sorting Filter and then, in case if block passes validation — push it back to the API.
it is not required to mine a real-world BTC/BCH/BSW/etc block that would be valid for these networks. It is totally enough to have a block, that would correspond to one of the received targets, fetched by the
getaux
.
As API providers we do understand that the physical location of the API determines its efficiency for the pool, so we provide several regions to choose: East/West Europe, Middle East, Asia/Pacific. Please contact us and we would consider providing the API in your region.
This section describes provided RPC methods in detail.
All provided methods follow JSON-RPC spec (over HTTP) and are using basic HTTP Authentication for users authentication.
Provides AUX data for further inclusion into the coinbase TX according to rules required by the protocol.
You can specify early received
beacon_aux_data_hex
as id
parameter in request to turn request into a long-polling request, that will return the response only when beacon_aux_data_hex
would change on API's side. This could be useful alternative for doing repetitive request in some short interval of time.Successful result
Errors processing
"result" : {
"beacon_aux_data_hex" : "6a61786e65749cc87f00bb433a7cca295fa2545b49cd139b5c8a809e5519df828d071be583986a61786e6574",
"beacon_target" : "00001fff00000000000000000000000000000000000000000000000000000000",
"shards_targets" : {
"1" : "001ff00000000000000000000000000000000000000000000000000000000000",
"2" : "001ff00000000000000000000000000000000000000000000000000000000000",
"3" : "001ff00000000000000000000000000000000000000000000000000000000000"
}
}
beacon_aux_data_hex
— HEX-encoded AUX data, that must be added to the mined block.beacon_target
andshard_targets
define beacon and shards targets correspondingly. (the numberi
inshard_targets
defines shard ID)
In case of any issue, corresponding
error
field would be populated by an error description.curl --user {api-user}:{api-user-pasword} -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"id","method":"getaux","params":[]}' https://{pool-endpoint}.api.mine.jax.net
api-user
/api-password
— credentials provided to the pool.pool-endpoint
— API endpoint reserved for the pool.
These credentials are expected to be known on a integration stage. Please contact us for the details.
Accepts mined BTC / BCH / BSV / etc block data, validates it and in case of success — creates corresponding JAX network block and submits it to the corresponding shard or beacon chain.
header_hex
— HEX representation of binary encoded block header.coinbase_hex
— HEX representation of binary encoded coinbase TX.- [
tx_hash_1
,tx_hash_2
, ...] — set of block transaction hashes (must be sorted in the same way as TXs occur in block, except coinbase TX)
WARN:
TXs hashes must be encoded in big-endian coding (default format for network transmission).
Succesfull result
Second Tab
In case of successful request processing, the
result
and error
fields would be set to null
{
"error" : null,
"id" : "id",
"result" : null
}
In case of any issue, corresponding
error
field would be populated by an error description.
Please, be patient:
The
☝
error
field could be a JSON-structure, that would contain more than error if submission has affected more than one shard!curl --user {api-user}:{api-password} -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"id","method":"submitbtcaux","params":["<header hex>", "<coinbase_hex>", ["<tx_hash_1>", "<tx_hash_2>"]]}' https://{pool-endpoint}.api.mine.jax.net
api-user
/api-password
— credentials provided to the pool.pool-endpoint
— API endpoint reserved for the pool.
These credentials are expected to be known on a integration stage. Please contact us for the details.
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.
- Elliptic Curve used —
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 encodeduint64
— 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.
utcNow := time.Now().UTC()
utcNowBinary := make([]byte, 8)
binary.BigEndian.PutUint64(utcNowBinary, uint64(utcNow.UnixNano()))
headers.Add("timestamp", utcNow.Format(time.RFC3339))
responseHash := sha256.Sum256(marshalledResponse)
responseHashAndTimestamp := make([]byte, 0, len(responseHash)+len(utcNowBinary))
responseHashAndTimestamp = append(responseHashAndTimestamp, responseHash[:]...)
responseHashAndTimestamp = append(responseHashAndTimestamp, utcNowBinary[:]...)
hash := sha256.Sum256(responseHashAndTimestamp)
signature, _ := keystore.KeyChain.Sign(hash[:])
signatureHex := hex.EncodeToString(signature)
headers.Add("sig", signatureHex)
This section defines requirements for a BTC / BCH / BSV coinbase transaction, that can be a valid Coinbase AUX in beacon chain and shard chain blocks in Jax.Network.
The protocol requires special markers and proof of inclusion to be present in the signature script of the first tx input.
- The signature script marker is
6a61786e6574
("jaxnet" in ASCII hex format).
They can be at any position of the signature script, but they must follow each other in a row, like this:
<marker> <beacon_hash> <marker>
According to the rules of Bitcoin script serialization, in the raw format, the length must be present prior to each part.
<marker> <beacon_hash> <marker>
marker: 6a61786e6574
hash: 03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414
// part of script
...066a61786e65742003e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414066a61786e6574...
06 // 0x06 = 6 -- 6 bytes
6a 61 78 6e 65 74 // marker
20 // 0x20 = 32 -- 32 bytes
03 e8 18 e6 64 51 5a 15 8c 4e b0 b9 97 11 ca e6 ce e3 30 72 4f cc 76 b6 4f 59 a1 78 9e ab f4 14 // hash
06 // 0x06 = 6 -- 6 bytes
6a 61 78 6e 65 74 // marker
marker: 6a61786e6574
hash: 03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414
signature_script_hex: 03e1c720080000000000000000066a61786e65742003e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414066a61786e65740e2f503253482f6a61786e6574642f
signature_script_asm: e1c720 0000000000000000 6a61786e6574 03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414 6a61786e6574 2f503253482f6a61786e6574642f
There are 3 ways to craft a Bitcoin coinbase transaction as valid BTC Coinbase AUX for Jax.Network. The only difference between them is in the set of outputs.
ONLY a transaction matching one of these requirements can be used as a BTC Coinbase AUX to create a valid BTC AUX and to mine the Jax.Network block. Valid blocks for the beacon chain and shard chains can be made using these kinds.
- If
TYPE_A
andTYPE_B
are used as BTC Coinbase AUX, only BTC and JAXNET block rewards will be issued, while JAX reward will be burnt. - If
TYPE_C
is used as BTC Coinbase AUX, BTC, and JAXNET block rewards will be burnt.
A BTC/BCH/BSV coinbase transaction without
jaxnet marker out
.
This type of coinbase can't cause Proof of Burn and issuance of JAX coins (in shards). It can have 1, 2, 5, 6, or 7 outputs.There is only one requirement:
- the address of the first out must have a vanity prefix
1JAX
. Example:1JAXmGDsiE2CyK31dYZsMamM18pPebRDAk
Decoded and pretty-printed transaction data:
version: 1
locktime: 0
tx_in: [
0: {
prev_out_hash: 00000000000000000000000000000000000000000000000c00000000000000000
prev_out_id: ffffffff
signature_script_hex: 03e1c720080000000000000000066a61786e65742003e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414066a61786e65740e2f503253482f6a61786e6574642f
signature_script: e1c720 0000000000000000 6a61786e6574 03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414 6a61786e6574 2f503253482f6a61786e6574642f
sequence: ffffffff
}
]
tx_out: [
0: {
value: 4bc5b4
pk_script_hex: 76a914bc478fcf931d1a0074fc5f8014d6d9c69641db3a88ac
pk_script: OP_DUP OP_HASH160 bc478fcf931d1a0074fc5f8014d6d9c69641db3a OP_EQUALVERIFY OP_CHECKSIG
pk_script_address: [ 1JAXmGDsiE2CyK31dYZsMamM18pPebRDAk ]
script_class: pubkeyhash
}
1: {
value: 0
pk_script_hex: 6a24aa21a9edd960d12fcd5bae3184513d03828259cd6b3dd50bf7153bf56d7498560d22edcb
pk_script: OP_RETURN aa21a9edd960d12fcd5bae3184513d03828259cd6b3dd50bf7153bf56d7498560d22edcb
pk_script_address: []
script_class: nulldata
}
]
tx_witness: [ 0000000000000000000000000000000000000000000000000000000000000000 ]
This type of coinbase contains Proof of Burn and causes the issuance of JAX coins (in shards).
It can have only 3 or 4 outputs.
These are the requirements for outputs:
Out N | Value | Address | Description |
---|---|---|---|
0 | 0 | ||
1 | block_reward <= 6.25 BTC | This output "burns" all block rewards | |
2 | block_fee <= 0.5 BTC; if block_reward < 6.25 BTC | Any valid btc address | This output handles fees of all transactions |
3* | 0 | Witness commitment | Optional output with witness commitment |
NOTE: if the value of the second output is LESS than 6.25 BTC (current BTC Block reward), the protocol will check that a block fee is LESS THAN OR EQUAL TO 0.5 BTC
Decoded and pretty-printed transaction data:
version: 1
locktime: 0
tx_in: [
0: {
prev_out_hash: 00000000000000000000000000000000000000000000000c00000000000000000
prev_out_id: ffffffff
signature_script_hex: 03e1c720080000000000000000066a61786e65742003e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414066a61786e65740e2f503253482f6a61786e6574642f
signature_script: e1c720 0000000000000000 6a61786e6574 03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414 6a61786e6574 2f503253482f6a61786e6574642f
sequence: ffffffff
}
]
tx_out: [
0: {
value: 0
pk_script_hex: 76a914bc473af4c71c45d5aa3278adc99701ded3740a5488ac
pk_script: OP_DUP OP_HASH160 bc473af4c71c45d5aa3278adc99701ded3740a54 OP_EQUALVERIFY OP_CHECKSIG
pk_script_address: [ 1JAXNETJAXNETJAXNETJAXNETJAXW3bkUN ]
script_class: pubkeyhash
}
1: {
value: 4a817c
pk_script_hex: 76a914bc473af4c71c45d5aa3278adc99701ded3740a5488ac
pk_script: OP_DUP OP_HASH160 bc473af4c71c45d5aa3278adc99701ded3740a54 OP_EQUALVERIFY OP_CHECKSIG
pk_script_address: [ 1JAXNETJAXNETJAXNETJAXNETJAXW3bkUN ]
script_class: pubkeyhash
}
2: {
value: 14438
pk_script_hex: 76a914bc478fcf931d1a0074fc5f8014d6d9c69641db3a88ac
pk_script: OP_DUP OP_HASH160 bc478fcf931d1a0074fc5f8014d6d9c69641db3a OP_EQUALVERIFY OP_CHECKSIG
pk_script_address: [ 1JAXmGDsiE2CyK31dYZsMamM18pPebRDAk ]
script_class: pubkeyhash
}
3: {
value: 0
pk_script_hex: 6a24aa21a9edd960d12fcd5bae3184513d03828259cd6b3dd50bf7153bf56d7498560d22edcb
pk_script: OP_RETURN aa21a9edd960d12fcd5bae3184513d03828259cd6b3dd50bf7153bf56d7498560d22edcb
pk_script_address: []
script_class: nulldata
}
]
tx_witness: [ 0000000000000000000000000000000000000000000000000000000000000000 ]
jaxnet marker out
is a strict special predefined output that matches the following requirements:- 1.This is the first Tx Out.
- 2.Value of this out equals
0
. - 3.
- 4.The address in mainnet is equal to
1JAXNETJAXNETJAXNETJAXNETJAXW3bkUN
(testnet addressmxgUfHYGyYoVEQe95oRfzSaZKHmEPHD7Kr
). - 5.PKScript of this out is equal to
76a914bc473af4c71c45d5aa3278adc99701ded3740a5488ac
.
Here it is:
tx_out: [
0: {
value: 0
pk_script_hex: 76a914bc473af4c71c45d5aa3278adc99701ded3740a5488ac
pk_script_asm: OP_DUP OP_HASH160 bc473af4c71c45d5aa3278adc99701ded3740a54 OP_EQUALVERIFY OP_CHECKSIG
pk_script_address: [ 1JAXNETJAXNETJAXNETJAXNETJAXW3bkUN ]
script_class: pubkeyhash
},
...
]
JaxNet Burn Address
is the predefined unspendable address.Type | Value |
---|---|
mainnet address | 1JAXNETJAXNETJAXNETJAXNETJAXW3bkUN |
testnet address | mxgUfHYGyYoVEQe95oRfzSaZKHmEPHD7Kr |
pk_script | 76a914bc473af4c71c45d5aa3278adc99701ded3740a5488ac |
script asm | OP_DUP OP_HASH160 bc473af4c71c45d5aa3278adc99701ded3740a54 OP_EQUALVERIFY OP_CHECKSIG |
script class | pay-to-pubkeyhash |
Vanity address is a normal Bitcoin PublicKeyHash address that starts with the "JAX" string. For example:
1JAXmGDsiE2CyK31dYZsMamM18pPebRDAk
.
- Serialized transaction:
010000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff4b03e1c720080000000000000000066a61786e65742003e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414066a61786e65740e2f503253482f6a61786e6574642fffffffff0400000000000000001976a914bc473af4c71c45d5aa3278adc99701ded3740a5488ac7c814a00000000001976a914bc478fcf931d1a0074fc5f8014d6d9c69641db3a88ac38440100000000001976a914bc478fcf931d1a0074fc5f8014d6d9c69641db3a88ac0000000000000000266a24aa21a9edd960d12fcd5bae3184513d03828259cd6b3dd50bf7153bf56d7498560d22edcb0120000000000000000000000000000000000000000000000000000000000000000000000000
- Explanation of serialization format:
Data | Description |
---|---|
01 00 00 00 | version |
00 01 | witess marker bytes |
01 | number of inputs |
0000000000000000000000000000000000000000000000000000000000000000 | prev_out_hash |
ff ff ff ff | prev_out_id |
4b | len of signature script |
03e1c720080000000000000000066a61786e657420
03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf41406
6a61786e65740e2f503253482f6a61786e6574642f | signature script |
ff ff ff ff | sequence |
04 | number of outputs |
00 00 00 00 00 00 00 00 | value == 0x00 |
19 | len of pk_script == 0x19 |
76a914bc473af4c71c45d5aa3278adc99701ded3740a5488ac | pk script |
7c 81 4a 00 00 00 00 00 | value == 0x4a817c |
19 | len of pk_script == 0x19 |
76a914bc478fcf931d1a0074fc5f8014d6d9c69641db3a88ac | pk script |
38 44 01 00 00 00 00 00 | value == 0x14438 |
19 | len of pk_script == 0x19 |
76a914bc478fcf931d1a0074fc5f8014d6d9c69641db3a88ac | pk script |
00 00 00 00 00 00 00 00 | value == 0x00 |
26 | len of pk_script == 0x26 |
6a24aa21a9edd960d12fcd5bae3184513d03828259cd6b3dd50bf7153bf56d7498560d22edcb | pk script |
01 | number of witness hashes |
20 | len of witness hash |
000000000000000000000000000000000000000000000000000000000000000000000000 | witness hash |
- Serialized signature script:
03e1c720080000000000000000066a61786e65742003e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414066a61786e65740e2f503253482f6a61786e6574642f
- Explanation of serialization format:
Data | Description |
---|---|
03 | size of varint |
e1 c7 20 | varint; next height |
08 | size of extranonce |
00 00 00 00 00 00 00 00 | extranonce |
06 | size of marker |
6a61786e6574 | "jaxnet" marker |
20 | size of exclusive hash |
03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414 | exclusive hash |
06 | size of marker |
6a61786e6574 | "jaxnet" marker |
0e | size of some extra data |
2f503253482f6a61786e6574642f | some extra data |
Last modified 1yr ago