Your wallet’s data model should be supplemented with two additional lists, described below.

The first is the Asset Type List, which stores information about the CoinSpark assets which are of interest to the wallet. The second is the Asset Balance List, which stores the balances of CoinSpark assets in the unspent bitcoin transaction outputs which the wallet can spend.

These lists can be stored in whichever fashion is most appropriate for your wallet, such as an SQL database, XML/JSON files on disk, or a language-specific serialization format.

Subsequent sections of this guide explain in detail exactly how the information in these lists should be used. At this stage your goal is simply to create the means by which these lists can be written, read and modified.

Asset Type List

Below is a list of fields that should be tracked for each asset type of interest:

Name Type Description Can be null?
assetID Integer, 32 bit (primary key) Your internal reference for this asset type (can use auto increment) No
whenAdded DateTime Date/time when the asset was added to this list No
fromSource Enum What caused this asset to be added – genesis, transfer or manual No
isVisible Boolean Should the asset be displayed to the user? No
genTxID Binary, 32 bytes Full txid of the transaction with genesis metadata that created the asset Yes
genesis CoinSparkGenesis The CoinSparkGenesis structure decoded from the genesis metadata in transaction genTxID. You can store this as individual fields, in a language-specific serialization format, or as the raw pre-decoded metadata. Yes
assetRef CoinSparkAssetRef The location of transaction genTxID on the blockchain. You can store this as the individual fields blockNum, txOffset and txIDPrefix, in a language-specific serialization format, or as a human-readable asset reference. Yes
validChecked DateTime Date/time when the asset’s validity was last checked Yes
validFailures Integer, 16 bit unsigned Count of consecutive failures to verify the asset’s validity No
webPageJSON Text, up to 64 KB JSON specification extracted from the asset web page Yes
contractContent Binary, up to 16 MB Raw content of the contract, retrieved from contract_url in webPageJSON Yes
contractMIMEType Text, up to 256 bytes MIME type of the contract, as received in response to the HTTP request retrieving it Yes

If your wallet supports multiple users, you should break out the isVisible field into a separate list, where each user has their own value for this field for each asset you are tracking.

An asset in the Asset Type List can be in one of three high level states:

In addition, the validity of an asset in the Asset Type List can be in one of four states:

  • The asset’s validity has never been checked. In this case, validChecked is null and validFailures is 0. In addition, webPageJSON, contractContent and contractMIMEType will also be null. For as long as either the asset’s genTxID or genesis are null, it will remain in this state, since both of those fields are required to determine the URL of the asset web page that is required to check its validity.
  • The asset’s validity has been checked and passed. In this case validChecked is the date/time of the last check and validFailures is 0. In addition, webPageJSON, contractContent and contractMIMEType will contain up-to-date information based on the last check. The asset’s validity will next be checked 24 hours after the date/time in validChecked.
  • The asset’s validity has been checked and failed. In this case validChecked is the date/time of the last check and validFailures is greater than 0. If the asset was never valid in the past, webPageJSON, contractContent and contractMIMEType will be null, otherwise they will contain the values for when the asset last validated successfully. The asset will next be checked in a short time, depending on its fromSource and the value of validFailures.
  • The refresh button for the asset has been clicked. In this case, validChecked is null and the other fields’ values will be based on the result of the most recent check.

Asset Balance List

Below is a list of fields that should be tracked for the assets that are relevant for each unspent transaction output:

Name Type Description Can be null?
assetID Integer, 32 bit Your internal reference for the asset type (links to Asset Type List above) No
unspentTxID Binary, 32 bytes Full txid of the bitcoin transaction whose output the wallet can spend No
unspentVout Integer, 16 bit unsigned Index of the output of unspentTxID which the wallet can spend No
qty Integer up to 1014 The balance of this asset in output unspentVout of transaction unspentTxID Yes
qtyChecked DateTime When this balance was last checked Yes
qtyFailures Integer, 16 bit unsigned How many consecutive failures to obtain this balance No

If your wallet supports multiple users, there is no need to break up the Asset Balance List.

The quantity of an entry in the Asset Balance List can be in one of four states:

  • The quantity has never been checked. In this case qtyChecked is null and qtyFailures is 0. In addition, qty will be null. The quantity will be checked immediately by the asynchronous checking of asset balances.
  • The quantity was checked successfully. In this case qtyChecked contains the date/time of the successful check and qtyFailures is 0. In addition, qty contains the quantity of asset assetID in output unspentVout of transaction unspentTxID. There is no need to check the quantity again, although this can be overridden when a user refreshes the asset.
  • The quantity was checked but could not be retrieved. In this case qtyChecked is the date/time of the last check and qtyFailures is greater than 0. If the quantity was never successfully checked in the past, qty will be null, otherwise it will be the value obtained by the last successful check. The quantity will next be checked in a short time, depending on the value of qtyFailures.
  • The refresh button for the asset has been clicked. In this case, qtyChecked is null and the other fields’ values will be based on the result of the most recent check.

« Previous: OverviewNext: Bitcoin Events »