The Event Plugin API [experimental]

Danger

The Event Plugin API is experimental and might change in the future.

BigchainDB implements an internal event system that allows different software components to receive updates on specific topics. The WebSocket API, for example, is a subscriber to a stream of events called BLOCK_VALID. Every time a block is voted valid, the WebSocket API is notified, and it sends updates to all the clients connected.

We decided to make this internal event system public, to allow developers to integrate BigchainDB with other applications, such as AMQP systems.

Available Events

The event types are listed in the source file bigchaindb/events.py.

Event Types
event name event id description
BLOCK_VALID 1 a block has been voted valid by the network.
BLOCK_INVALID 2 a block has been voted invalid by the network.

Plugin Example

We developed a minimal plugin that listens to new valid blocks and prints them to the console: https://github.com/bigchaindb/events-plugin-example

Architecture of an Event Plugin

Creating your own plugin is really easy, and can be summarized in few steps:

  1. Create a new Python package that defines the entry point bigchaindb.events in its setup.py.
  2. In your entry point, define two properties:
    • event_types: a variable to tell BigchainDB which events your plugin is interested in. A plugin can subscribe to more than one events by combining them using the binary or operator, e.g. in case you want to subscribe to both valid and invalid blocks your event_types can be 1 | 2.
    • run: a function that will process the events coming from BigchainDB.
  3. Install the newly created Python package in the current environment.
  4. Add the plugin name to your BigchainDB configuration.
  5. (Re)start BigchainDB.

If the installation was successful, the plugin will be run in a different process. Your plugin will receive events through a multiprocessing.Queue object.

Note

It’s your plugin’s responsibility to consume it’s queue.