Event Framework

The purpose of the Event Framework is to provide a standard unified architecture to capture all Mojaloop events.

Disclaimer: This is experimental and is being implemented as a PoC. As such the design may change based on the evolution of the PoC's implementation, and any lessons learned.

1. Requirements

• Events will be produced by utilising a standard common library that will publish events to a sidecar component utilising a light-weight highly performant protocol (e.g. gRPC).
• Sidecar module will publish events to a singular Kafka topic that will allow for multiple handlers to consume and process the events as required.
• Kafka partitions will be determined by the event-type (e.g. log, audit, trace, errors etc).
• Each Mojaloop component will have its own tightly coupled Sidecar.
• Event messages will be produced to Kafka using the Trace-Id as the message key. This will ensure that all the messages part of the same trace (transaction) are stored in the same partition in order.

2. Architecture

2.1 Overview

2.2 Micro Service Pods

2.3 Event Flow

3. Event Envelope Model

3.1 JSON Example

{
    "from": "noresponsepayeefsp",
    "to": "payerfsp",
    "id": "aa398930-f210-4dcd-8af0-7c769cea1660",
    "content": {
        "headers": {
            "content-type": "application/vnd.interoperability.transfers+json;version=1.0",
            "date": "2019-05-28T16:34:41.000Z",
            "fspiop-source": "noresponsepayeefsp",
            "fspiop-destination": "payerfsp"
        },
        "payload": "data:application/vnd.interoperability.transfers+json;version=1.0;base64,ewogICJmdWxmaWxtZW50IjogIlVObEo5OGhaVFlfZHN3MGNBcXc0aV9VTjN2NHV0dDdDWkZCNHlmTGJWRkEiLAogICJjb21wbGV0ZWRUaW1lc3RhbXAiOiAiMjAxOS0wNS0yOVQyMzoxODozMi44NTZaIiwKICAidHJhbnNmZXJTdGF0ZSI6ICJDT01NSVRURUQiCn0"
    },
    "type": "application/json",
    "metadata": {
        "event": {
            "id": "3920382d-f78c-4023-adf9-0d7a4a2a3a2f",
            "type": "trace",
            "action": "span",
            "createdAt": "2019-05-29T23:18:32.935Z",
            "state": {
                "status": "success",
                "code": 0,
                "description": "action successful"
            },
            "responseTo": "1a396c07-47ab-4d68-a7a0-7a1ea36f0012"
        },
        "trace": {
            "service": "central-ledger-prepare-handler",
            "traceId": "bbd7b2c7-3978-408e-ae2e-a13012c47739",
            "parentSpanId": "4e3ce424-d611-417b-a7b3-44ba9bbc5840",
            "spanId": "efeb5c22-689b-4d04-ac5a-2aa9cd0a7e87",
            "startTimestamp": "2015-08-29T11:22:09.815479Z",
            "finishTimestamp": "2015-08-29T11:22:09.815479Z",
            "tags": {
              "transctionId": "659ee338-c8f8-4c06-8aff-944e6c5cd694",
              "transctionType": "transfer",
              "parentEventType": "bulk-prepare",
              "parentEventAction": "prepare"
            }
        }
    }
}

3.2 Schema Definition

3.2.1 Object Definition: EventMessage

3.2.1.1 Object Definition: MessageMetadata

3.2.1.2 Object Definition: EventMetadata

3.2.1.3 Object Definition: EventStateMetadata

3.2.1.4 Object Definition: EventTraceMetaData

Note: HEXDIGLC = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" ; lower case hex character. Ref: WC3 standard for trace-context.

3.2.1.5 Object Definition: EventTraceMetaDataTags

3.2.1.6 Enum: EventStatusType

3.2.1.7 Enum: EventType

3.2.1.8 Enum: LogEventAction

3.2.1.9 Enum: AuditEventAction

3.2.1.10 Enum: TraceEventAction

4. Tracing Design

4.1 HTTP Transports

Below find the current proposed standard HTTP Transport headers for tracing.

Mojaloop has yet to standardise on either standard, or if it will possible support both.

4.1.1 W3C Http Headers

Refer to the following publication for more information: https://w3c.github.io/trace-context/

Note: Before this specification was written, some tracers propagated X-B3-Sampled as true or false as opposed to 1 or 0. While you shouldn't encode X-B3-Sampled as true or false, a lenient implementation may accept them.

Note: (Event-SDK)[https://github.com/mojaloop/event-sdk] since version v9.4.1 has methods to add key value tags in the tracestate, and since version v9.5.2 the tracestate is base64 encoded. To be able to use the tracestate consistently, use matching versions across all services in a system.

4.1.2 B3 HTTP Headers

Refer to the following publication for more information: https://github.com/apache/incubator-zipkin-b3-propagation

4.2 Kafka Transports

Refer to Event Envelope Model section. This defines the message that will be sent through the Kafka transport.

Alternatively the tracing context could be stored in Kafka headers which are only supports v0.11 or later. Note that this would break support for older versions of Kafka.

4.3 Known limitations

• Transfer tracing would be limited to each of the transfer legs (i.e. Prepare and Fulfil) as a result of the Mojaloop API specification not catering for tracing information. The trace information will be send as part of the callbacks by the Switch, but the FSPs will not be required to respond appropriately with a reciprocal trace headers.