Events

Introduction

cryptoassets.core fires events which your application may listen. Most interesting once are:

  • New incoming transaction
  • New confirmations for incoming transactions
  • New confirmations for outgoing transactions

cryptoassets.core will also post more complex events in the future (cold wallet top ups, etc.).

Also see event handling configuration.

Events types

cryptoassets.core currently sends the following events.

Note

In the future the scope of the events will be expanded: cold wallet top ups, network issues, etc.

cryptoassets.core.event.events.txupdate(coin_name, transaction, network_transaction, transaction_type, txid, account, address, amount, credited, **extra)[source]

txupdate event reports the confirmation changes of incoming transaction (deposit) or outgoing transaction (broadcasted).

This event is fired for each transaction, when its confirmations changes. One network transaction may contain several deposit or broadcast transactions and they all trigger the event.

When the incoming transaction is first seen in the network, but it is not yet confirmed, confirmations is 0. Evaluate the risk of double spending for these kind of transactions in your application context.

Parameters:
  • coin_name – Lowercase acronym name for this asset
  • transaction – Id of cryptoasset.core.models.GenericTransaction instance
  • network_transaction – Id of cryptoasset.core.models.GenericNetworkTransaction instance
  • transaction_type – String deposit (incoming) or broadcast (outgoing)
  • txid – Network transaction id (transaction hash) as a string
  • account – Database account id as int, either receiving account (deposit) or sending account (broadcast)
  • amount – How much the transaction is worth of, as Decimal
  • credited – Has this transaction reaches system-set confirmation threshold
  • extra – Any cryptoasset specific data as dict, e.g. dict(confirmations=0) in the case of mined coins
Returns:

Event data as dict()

Event handlers

Event handlers tell how cryptoassets.core will post the event to your application.

cryptoassets.core offers a framework how you can flexbile queue notifications for your application, regardless of API service or cryptocurrency you work on.

  • If you want to your web server process handle events, configure HTTP webhook
  • If you want to run event handling code inside cryptoasset helper service, use in-process Python notifications

HTTP webhook

Send events to your application as HTTP POST request.

The HTTP POST contains two fields, event_name (string) and data (JSON).

Decimals are converted to strings for serialization.

Configuration options

param class:Always cryptoassets.core.event.http.HTTPEventHandler.
param url:Do a HTTP POST to this URL on a new event. Example: http://localhost:30000.

In-process Python

In-process Python event handling.

Run Python function each time event occures. This assumes you have your Python application code in the same virtualenv as cryptoassets.core is. The code is executed directly within cryptoassets helper service process.

Configuration options

param class:Always cryptoassets.core.event.python.InProcessEventHandler.
param callback:A dotted name to Python callback function fn(event_name, data) which will be called upon a notification. event_name is a string, data is a dict.

Shell script

Run a script on a notification.

Execute an UNIX command on a new event.

Blocks the execution until the executed command returns.

The following environment variables are set for the script:

CRYPTOASSETS_EVENT_NAME="event name as a string"
CRYPTOASSETS_EVENT_DATA="JSON encoded data"

If the executed command returns non-zero status, this notification handler raises ShellNotificationFailed.

Configuration options

param class:Always cryptoassets.core.event.script.ScriptEventHandler.
param script:Executed shell command
param log_output:
 If true send the output from the executed command to cryptoassets logs on INFO log level
exception cryptoassets.core.event.script.ScriptNotificationFailed[source]

Script executed for the notification returned non-zero exit code.

Incoming transaction confirmation updates

Handling incoming cryptoasset transactions is as not as straightforward as one would hope, especially with limited APIs provided with bitcoind and its derivates. Incoming transaction event chain for bitcoind goes as following:

For 0 confirmations and 1 confirmations

# Receive raw cryptocurrency protocol packet
  • Read transaction from the network
# API service notification / bitcoind walletnotify shell hook
  • Push out notification about the updated transaction status
# Cryptoassets helper service (cryptoassets-helper)
  • Catch the low level transaction update notification (via named pipe, HTTP hook)
  • Write updated transaction information to the database
  • Update account balances, etc.
  • Call all generic cryptoasets notification handlers with txupdate event
# Your application
  • Listen for txupdate event
  • Process updated transaction

For 2 and more confirmations

# Cryptoassets helper service (cryptoassets-helper)
  • Run periodical open transaction update task - cryptoassets.core.tools.opentransactions

  • Poll the bitcond for transactions where the confirmation count in the database has not reached the maximum threshold yet. This is 15 confirmations by default.

  • If the transaction confirmation count has changed in the backend.
    • Update account balances, etc.
    • Call all generic cryptoasets notification handlers

For 15 and more confirmations

  • These transactions are not polled anymore in the backend and are considered final.
  • The threshold can be adjusted in backend settings.