This section explains the actions that should be taken by a CoinSpark wallet in response to different events which take place on the bitcoin network.

New transaction

When a new transaction is received from the bitcoin network, it should be processed in each of the three ways listed below:

Check for genesis metadata

  1. Check if this wallet can spend any of the incoming transaction’s outputs. If not, stop here.
  2. Try to extract a CoinSparkGenesis from the transaction. If none is present, stop here.
  3. Add a new entry into the Asset Type List as follows – all unspecified fields should be set to null:
    • Set assetID to a new and unique value.
    • Set whenAdded to the current date/time.
    • Set fromSource to genesis.
    • Set isVisible to true.
    • Set genTxID to the txid of the bitcoin transaction being examined.
    • Set genesis to contain the extracted CoinSparkGenesis.
    • Set validFailures to 0.
  4. For each output of the transaction which you can spend, add a new entry into the Asset Balance List as follows:
    • Set assetID to the same value inserted into the Asset Type List above.
    • Set unspentTxID to the txid of the bitcoin transaction being examined.
    • Set unspentVout to the index of this output which the wallet can spend.
    • Set qty and qtyChecked to null. (Because of the minimum transaction fee required for genesis metadata validity, you cannot trust that the genesis was successful without consulting an asset tracking server.)
    • Set qtyFailures to 0.
  5. Redraw the displayed asset balances and asset list in the user interface if they are visible.
  6. Trigger the asynchronous checking of asset validity.

Check for transfer metadata

  1. Check if this wallet can spend any of the incoming transaction’s outputs. If not, stop here.
  2. Try to extract a CoinSparkTransferList (or array of CoinSparkTransfer in C/C++) from the transaction. If none is present, stop here.
  3. For each CoinSparkTransfer in the list, and for each output in the range outputs.first(outputs.first+outputs.count-1) of that CoinSparkTransfer which you can spend, do the following:
    • Check if there is an entry in the Asset Type List whose assetRef matches the assetRef inside that CoinSparkTransfer. If so, make a note of the assetID.
    • Otherwise, add a new entry into the Asset Type List as follows – all unspecified fields should be set to null:
      • Set assetID to a new and unique value.
      • Set whenAdded to the current date/time.
      • Set fromSource to transfer.
      • Set isVisible to true.
      • Set assetRef to match that in the CoinSparkTransfer.
      • Set validFailures to 0.
    • Either way, add a new entry into the Asset Balance List as follows:
      • Set assetID to the value found in or added to the Asset Type List above.
      • Set unspentTxID to the txid of the bitcoin transaction being examined.
      • Set unspentVout to the index of the matching output which this wallet can spend.
      • Set qty and qtyChecked to null. (You cannot trust the qtyPerOutput field of the CoinSparkTransfer and must consult an asset tracking server.)
      • Set qtyFailures to 0.
  4. Redraw the displayed asset balances and asset list in the user interface if they are visible.
  5. If an asset was added to the Asset Type List, trigger the asynchronous fetching of genesis transactions.
  6. Otherwise, if an entry was added to the Asset Balance List, trigger the asynchronous checking of asset balances.

Spendable Last Output

This step should be carried out even if the transaction contained genesis or transfer metadata.

  1. Check if this wallet can spend the last non-OP_RETURN output of the incoming transaction. If not, stop here.
  2. For every entry in the Asset Type List, add a new entry into the Asset Balance List as follows:
    • Set assetID from this entry in the Asset Type List.
    • Set unspentTxID to the txid of the bitcoin transaction being examined.
    • Set unspentVout to the index of the last non-OP_RETURN output of the transaction.
    • Set qty and qtyChecked to null.
    • Set qtyFailures to 0.
  3. Redraw the displayed asset balances and asset list in the user interface if they are visible.
  4. Trigger the asynchronous checking of asset balances.

New block

When a new block arrives on the blockchain, check whether the txid of any bitcoin transaction in that block matches the genTxID of an entry in the Asset Type List. If so, update the assetRef field of that asset with the block number, transaction byte offset and txid prefix of the transaction within the block. Then redraw the displayed asset balances and asset list in the user interface if they are visible.

Orphaned blocks

If there is a blockchain rearrangement causing some blocks to be orphaned, check whether any of the orphaned blocks’ numbers match the blockNum field of an assetRef in the Asset Type List. If so, reset that assetRef value to null and redraw the displayed asset balances and asset list in the user interface if they are visible. You must complete this step before processing any new blocks which took the place of the orphans.

« Previous: Data ModelNext: Asynchronous Tasks »