Each CoinSpark asset has one or more servers which track its movements across transactions.

The server answers queries from lightweight wallets regarding the quantity of that asset in a particular transaction output. The address or addresses of these servers is specified on an asset’s web page in the coinspark_tracker_url field of the JSON structure.

We provide an open source asset tracking server for issuers to run themselves, or issuers can freely use assets[1|2|3].coinspark.org which track units of all CoinSpark assets. If you are a wallet developer, you must use the tracking server specified on the asset web page. Please do not hard-code our server as the tracker for all assets, since its address may change in future.

Asset servers are queried using the same JSON-RPC protocol as used by the Bitcoin Core software. The query is sent in JSON format within the raw payload of an HTTP POST request to the URL provided in the coinspark_tracker_url field. If the field contains an array of tracker URLs, one of them should be queried at random. If the query fails for any reason, another should be tried the next time round. The response is sent back in JSON format.

Example asset tracking request

{
  "id": "any_request_id",
  "method": "coinspark_assets_get_qty",
  "params": {
    "assets": [
      "f5d8ee39a430901c91a5917b9f2dc19d6d1a0e9cea205b009ca73dd04470b9a6",
      "7fe0bbe5a3a37088b8a3065ed8b2ae1624e80c5a2a023568f197e4cce85310f3"
    ],
    "txouts": [
      {
        "txid": "7f25b380f109b3b013e3f8c1ccd5a904b9bbf50bf23f98acb0b9c7586c415c79",
        "vout": 3
      },
      {
        "txid": "c7ea20fa1e8b236b92c0f5a9d9e43e1bce9095faf81ae6bce636fe883b915645",
        "vout": 2
      }
    ]
  }
}

The request has two parameters:

  • assets is a list of the CoinSpark assets of interest, specified using the bitcoin txids of the transactions which created each asset.
  • txouts is a list of the transaction outputs of interest, specified by a combination of the txid and vout index of the output.

If everything is in order, the tracking server will respond with the number of units of each asset of interest that is present in each transaction output of interest:

Successful asset tracking response

{
  "id": "any_request_id",
  "result": {
    "f5d8ee39a430901c91a5917b9f2dc19d6d1a0e9cea205b009ca73dd04470b9a6": [
      {
        "txid": "7f25b380f109b3b013e3f8c1ccd5a904b9bbf50bf23f98acb0b9c7586c415c79",
        "vout": 3,
        "qty": 146
      },
      {
        "txid": "c7ea20fa1e8b236b92c0f5a9d9e43e1bce9095faf81ae6bce636fe883b915645",
        "vout": 2,
        "qty": 0
      }
    ],
    "7fe0bbe5a3a37088b8a3065ed8b2ae1624e80c5a2a023568f197e4cce85310f3": [
      {
        "txid": "7f25b380f109b3b013e3f8c1ccd5a904b9bbf50bf23f98acb0b9c7586c415c79",
        "vout": 3,
        "qty": 146
      },
      {
        "txid": "c7ea20fa1e8b236b92c0f5a9d9e43e1bce9095faf81ae6bce636fe883b915645",
        "vout": 2,
        "qty": 0
      }
    ]
  }
}

In the result object, the top level grouping is by the asset of interest, using the txid of the asset genesis as the key. For each such asset, there is an array of results, each of which provides the quantity of that asset in each of the requested transaction outputs.

Global failure response

If there was a global problem with the JSON-RPC request, the result element will not be present, and instead the response will contain an error:

{
  "id": "any_request_id",
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

The following global error codes may be present:

code message meaning
-32700 Parse error Could not parse the JSON input received
-32600 Invalid request The JSON received is not a valid JSON-RPC request
-32601 Method not found The method in the request is not available
-32602 Invalid params The method params in the request are not valid
-32603 Internal error Something went wrong internally

Partial failure response

If the JSON-RPC request was valid, but some of the quantities for some of the specified assets and transaction outputs could not be calculated, the corresponding qty element will not be present, and instead the relevant object will contain an error:

...
      {
        "txid": "7f25b380f109b3b013e3f8c1ccd5a904b9bbf50bf23f98acb0b9c7586c415c79",
        "vout": 3,
        "error": {
          "code": -10000,
          "message": "Asset not found"
        }
      },
...

The following error codes may be present in this position:

code message meaning
-10000 Asset not found This server does not track the asset specified
-10001 Txout not found The transaction output specified could not be found

If a transaction output cannot be found (error code -10001), it could be for any of these reasons:

  • No bitcoin transaction with the specified txid exists in the network.
  • The bitcoin transaction with txid has not yet propagated to the asset tracking server.
  • The specified output index vout does not exist on this bitcoin transaction txid.
  • The specified transaction output was spent a long time ago and its CoinSpark balance is no longer being stored. (This prevents excessive memory use. The default asset server forgets spent transaction outputs after 1008 blocks, i.e. approximately one week.)

In case the problem is due to delayed transaction propagation, wallets should deal with a -10001 error by repeatedly trying to request the transaction output balance again, using an exponential back off in the request delay, to prevent overloading the asset server. If the asset web page specifies more than one tracking server, wallets should try each of these servers in turn.