About Extending Ledger

Generic nature of the ledger allows to model wide range of real world use cases. On top of data model provided by the core, ledger can be extended by using effects to define the logic and processes specific for the use case. This design principle we use here is called open-closed principle which states: software entities should be open for extension, but closed for modification.

Effect

Effects are used to add new features to the Ledger by applying the observer design pattern. Effect represents a registration of a listener on the ledger events which executes an action when triggered (i.e. when an event occurs). For every change which occurs in Ledger data an event is raised and as a result all matching effects will be triggered.

Key concepts related to effects:

• event
• signal
• filter
• action

Event

Event is raised by change of data in the Ledger. It can be raised when a record is created or modified, signature is added to a record, wallet balance is changed and so on. Event contains the data which describes what happened and contains the records involved in the change. Event record is structured like any other Ledger record. It is signed with a Ledger private key which enables the recipient of event to validate authenticity against the Ledger public key.

Signal

Signal is a string identifier of the event type which describes what happened in the Ledger. Effect is registered for single signal, meaning that all events with this signal will try to trigger the effect. Available signals are provided by the Ledger system and the system determines when to raise events belonging to each signal. This behaviour can’t be changed by the Ledger user.

List of supported signals can be found in the 🔗 🌐 API reference documentation.

Filter

Except for the signal the effect is registered to, filter can be used for more granular control over the events which will trigger the effect. Filter is an expression which targets the event data and only events matching the filter will trigger the effect.

Action

Action is the part of the effect which defines what will happen when effect is triggered by the event. It is an entry point for executing custom logic or processes in response to the ledger events. It can be webhook, plugin function call or other mechanism used to forward the event to the environment which will handle it.

One interesting way to use actions is to compose them with calls back to a ledger - one can create/modify new records in ledger as a response to previous modifications and that way build chains (or graphs) of operations required to model complex use cases.