Jax.Mining API
Search
⌃K
🚀

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.

Communication and support

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]

Benefits of using API instead of direct mining

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

Hash Sorting Filtering

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>
  • Hash Sorting Number for the Test Net is set to 16.
  • Hash Sorting Number for the Main Net is set to 1024.
​

Pool integration of HS

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.

Principal integration schema

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

API Location & Access

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

RPC Methods

This section describes provided RPC methods in detail.
​
Authentication and data format
All provided methods follow JSON-RPC spec (over HTTP) and are using basic HTTP Authentication for users authentication.
​

Method — getaux

Provides AUX data for further inclusion into the coinbase TX according to rules required by the protocol.
Long polling support: present
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.
Arguments: none
This method does not require any parameters to be passed.
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 and shard_targets define beacon and shards targets correspondingly. (the number i in shard_targets defines shard ID)
​
In case of any issue, corresponding error field would be populated by an error description.
Example (curl)
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.
​

Method — submitbtcaux

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.
Arguments
  • 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!
Example (curl)
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.
​
​

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.
  • timestamp — RFC3339 representation of the timestamp of the response processing (UTC).
Public Key
You can use this public key to check the origin of the responses received:
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA+vFM4H28p/9ZpV/oeVBD5D2BqDNuW7/llRPh6orawCg=
-----END PUBLIC KEY-----
​

Signature schema

  • 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 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)
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)
​

Coinbase TX requirements

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.

Requirements for Inputs

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).
  • Proof of inclusion is an exclusive hash of the Jax.Net beacon block (could be fetched via API).
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
Example
marker: 6a61786e6574
hash: 03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414
​
signature_script_hex: 03e1c720080000000000000000066a61786e65742003e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414066a61786e65740e2f503253482f6a61786e6574642f
signature_script_asm: e1c720 0000000000000000 6a61786e6574 03e818e664515a158c4eb0b99711cae6cee330724fcc76b64f59a1789eabf414 6a61786e6574 2f503253482f6a61786e6574642f
​

Requirements for Outputs

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.
Type
Outputs count
Allows Proof Of Burn
​TYPE_A​
1, 2, 5, 6 or 7
NO
​TYPE_C​
3 or 4
YES
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 and TYPE_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.

​

TYPE_A

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
Example of TYPE_A transaction
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 ]
​
​

TYPE_C

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
This must be Jaxnet Marker Out​
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
Example of TYPE_C transaction
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 ]
​

Examples

JAXnet Marker Out

jaxnet marker out is a strict special predefined output that matches the following requirements:
  1. 1.
    This is the first Tx Out.
  2. 2.
    Value of this out equals 0.
  3. 3.
    This out is to the JaxNet Burn Address.
  4. 4.
    The address in mainnet is equal to 1JAXNETJAXNETJAXNETJAXNETJAXW3bkUN (testnet address mxgUfHYGyYoVEQe95oRfzSaZKHmEPHD7Kr).
  5. 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

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

Vanity address is a normal Bitcoin PublicKeyHash address that starts with the "JAX" string. For example: 1JAXmGDsiE2CyK31dYZsMamM18pPebRDAk.
​

Serialization format

Transaction

  • 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

Signature script

  • 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
​
​
​
Previous
Jax.Network Mining API
Next
Our Solution
Last modified 1yr ago