Tutorial: events

events

Whiteflag API Events

The Whiteflag API uses events internally for modules to know when protocol actions must be triggered. Three main event types are defined in the protocol/events.js module for usage by other modules.

  • rxEvent
  • txEvent
  • stateEvent

Receive and Transmit Events

The rx and tx events are used by the blockchains, datastores and protocol modules to bind handlers to incoming and outgoing Whiteflag message processing steps. This is useful given the complex processing flows, especially for cases such as encryption, authentication, etc. that require different handling paths for each messages.

Specifically, the lib/protocol/receive.js and lib/protocol/transmit.js modules chain the appropriate events to create the processing chains for incoming and outgoing messages. The lib/datastores.js module listens for these events to store messages as configured in the config/datastores.toml configuration file.

Currently defined rx and tx events are:

Event Direction Description
error RX, TX An error occured when processing the message
messageReceived RX A new incoming message has been received from the blockchain or from the REST interface
messageCommitted TX A new outgoing message has been posted on the REST interface or is generated automatically
metadataVerified RX, TX The message metadata has been verified and is valid
messageEncrypted RX The received message has been encrypted and cannot be decoded immediately
messageDecoded RX The incoming message has been succesfully decrypted/decoded
messageEncoded TX The outgoing message has been succesfully encoded/encrypted
originatorVerified RX The originator of the incoming message has been verified
originatorSkipped RX Verification of the originator of the incoming message has been skipped
referenceVerified RX, TX The message correctly references other messages
referenceSkipped RX, TX The way the message references other messages has not been verified
messageSent TX The outgoing message has been sucessfully transmitted on the blockchain
messageProcessed RX, TX The processing of the message has been completed
messageUpdated RX, TX The message metadata has been updated after initial processing

State Events

The state event allows to bind handlers to state changes using events; this is useful when a process does not only want to keep track of some data, but also wants to trigger required actions when the Whiteflag state changes.

Currently, only the initialised and saved events are used on startup and closing respectively.