# Notifier

mx-notifier is a blockchain event streaming service that sits between the MultiversX node and downstream consumers. It receives raw block data from the node over a binary protobuf WebSocket connection, normalizes that data into structured events, and fans them out to configured subscribers.

***

## Architecture position

```
MultiversX Node
    │  binary protobuf WebSocket frames
    ▼
mx-notifier
    ├── /hub/ws ──────► mx-relayer (internal WebSocket consumer)
    ├── RabbitMQ ──────► enterprise message queue consumers
    └── Azure Service Bus ► cloud messaging consumers
```

The node pushes block data to mx-notifier over a persistent WebSocket connection using binary protobuf frames. mx-notifier decodes each frame, preprocesses the payload, and delivers normalized events to all active output channels simultaneously.

mx-relayer connects to the `/hub/ws` endpoint to receive account delta and transaction status updates, then fans them out to its own WebSocket clients. See the [Relayer WebSocket API](https://docs.xoxno.com/developers/relayer-api) for details on that layer.

***

## Modes of consumption

### Hub WebSocket (`/hub/ws`)

The hub WebSocket is an internal endpoint intended for trusted service consumers in the same infrastructure boundary. Consumers connect, send a `SubscribeEvent` protobuf message to declare their filter criteria, and receive a stream of matching events in the same binary protobuf framing format used by the node.

Use the hub WebSocket when:

* You need sub-second event delivery with minimal additional infrastructure
* You are operating a service within the same network as mx-notifier (e.g., mx-relayer)
* You need fine-grained subscription filtering by address, identifier, or topic prefix

### Message brokers (RabbitMQ / Azure Service Bus)

Events are also published to external message brokers for integration with broader data pipelines. These channels add durable delivery, replay, and fan-out for asynchronous or batch processing workloads.

Use a message broker when:

* Consumers need durable message storage and guaranteed delivery
* You are integrating with existing AMQP or Azure Service Bus infrastructure
* You require ordered delivery across multiple consumer instances
* Consumers cannot maintain a persistent WebSocket connection

***

## Documentation structure

| Page                                                                         | Contents                                                                |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [connection.md](https://docs.xoxno.com/developers/notifier/connection)       | Hub WebSocket protocol, frame format, acknowledgement, backpressure     |
| [topics.md](https://docs.xoxno.com/developers/notifier/topics)               | All 8 topics received from the MX node — payloads, timing, use cases    |
| [filtering.md](https://docs.xoxno.com/developers/notifier/filtering)         | Subscription match levels, topic prefix matching, code examples         |
| [event-schemas.md](https://docs.xoxno.com/developers/notifier/event-schemas) | NormalizedEvent structure, field reference, per-event-type topic layout |
| [publishers.md](https://docs.xoxno.com/developers/notifier/publishers)       | RabbitMQ and Azure Service Bus configuration and message format         |

***

## Key properties

| Property              | Detail                                                        |
| --------------------- | ------------------------------------------------------------- |
| Inbound protocol      | Binary protobuf WebSocket (`WsMessage` schema)                |
| Outbound hub protocol | Same binary protobuf WebSocket                                |
| Event deduplication   | Optional Redis-backed cache, configurable TTL (default 300 s) |
| Resilience            | Circuit breaker, retry queue, auto-reconnect to node          |
| Supported brokers     | RabbitMQ (AMQP), Azure Service Bus                            |