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) orbroadcast
(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 |
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
- Listen for
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.