# Topics

mx-notifier receives blockchain data from the MultiversX node across eight topics. Each topic maps to a specific category of blockchain event. The node pushes frames for all topics over a single persistent WebSocket connection; mx-notifier dispatches each frame based on its `topic` field.

***

## Topic overview

| Topic                   | Emitted when                               | Primary payload                            |
| ----------------------- | ------------------------------------------ | ------------------------------------------ |
| `SaveBlock`             | A block is accepted and indexed            | Full block: transactions, SCRs, log events |
| `RevertIndexedBlock`    | A previously indexed block is reverted     | Block hash and nonce to un-index           |
| `SaveRoundsInfo`        | Round timing data is available for a shard | Round timestamps and proposer info         |
| `SaveValidatorsPubKeys` | Epoch changes, new validator set elected   | Validator bls public keys per shard        |
| `SaveValidatorsRating`  | Validator ratings computed for an epoch    | Rating scores per validator                |
| `SaveAccounts`          | Accounts are altered in a block            | Changed balances, nonces, code hashes      |
| `FinalizedBlock`        | A block reaches finality                   | Block hash and nonce                       |
| `Settings`              | Node sends configuration parameters        | Protocol version, shard topology           |

***

## Topic details

### `SaveBlock`

**Emitted when:** The node finishes processing and persisting a new block.

**Payload contents:**

* Block header (nonce, round, epoch, timestamp, shard ID, proposer)
* All transactions included in the block (sender, receiver, value, data, status)
* All smart contract results (SCRs) — asynchronous outputs from contract calls
* Log events — structured events emitted by contract executions (ESDTTransfer, swapTokensFixedInput, etc.)
* Receipts

**Consumer use cases:**

* Index transactions for a block explorer
* Detect ESDT transfers and DEX swap events in real time
* Track smart contract executions across all contracts
* Trigger downstream processing (e.g., update account balances, refresh LP positions)

{% hint style="info" %}
`SaveBlock` is the highest-volume topic. Each block on the mainnet shard may contain hundreds of transactions and thousands of log events. Size your consumer to handle sustained throughput at peak network activity.
{% endhint %}

***

### `RevertIndexedBlock`

**Emitted when:** The chain reorganizes and a previously accepted block must be un-indexed. Rare on MultiversX, but can occur during network partitions or proposer failures.

**Payload contents:**

* Block hash
* Block nonce
* Shard ID

**Consumer use cases:**

* Remove transactions from an index that were included in the reverted block
* Roll back balance or state updates derived from that block
* Alert monitoring systems to a chain reorg event

{% hint style="warning" %}
Consumers that maintain derived state (balance caches, swap histories, NFT ownership indexes) must handle revert events to avoid serving stale data. If your consumer ignores `RevertIndexedBlock`, your state will diverge from chain truth during reorganization.
{% endhint %}

***

### `SaveRoundsInfo`

**Emitted when:** Round timing data is available for a shard, typically at the end of each round.

**Payload contents:**

* Shard ID
* List of round descriptors, each containing:
  * Round number
  * Block nonce proposed in that round (0 if no block was proposed)
  * Timestamp
  * Proposer public key

**Consumer use cases:**

* Calculate validator uptime and missed-round statistics
* Monitor round skip rates for network health dashboards
* Compute block proposal latency per shard

***

### `SaveValidatorsPubKeys`

**Emitted when:** A new epoch begins and the validator set is elected.

**Payload contents:**

* Epoch number
* Map of shard ID to list of validator BLS public keys assigned to that shard
* Waiting list keys (validators eligible for the next assignment)

**Consumer use cases:**

* Maintain a current-epoch validator directory
* Cross-reference validator keys with staking provider identity data
* Track validator shard migrations across epochs

***

### `SaveValidatorsRating`

**Emitted when:** Validator rating scores are computed for an epoch (at epoch end).

**Payload contents:**

* Epoch number
* List of (public key, rating score) pairs

**Consumer use cases:**

* Display validator performance metrics in staking dashboards
* Alert staking providers when ratings fall below thresholds
* Build historical rating time series for analytics

***

### `SaveAccounts`

**Emitted when:** One or more accounts are modified during block execution — once per block per shard, with a batch of all altered accounts.

**Payload contents:** For each altered account:

* Address (bech32 or bytes)
* Balance
* Nonce
* Code hash (for smart contracts; empty for regular accounts)
* Root hash of the account's storage trie

**Consumer use cases:**

* Maintain a real-time account balance cache (as mx-relayer does)
* Track nonce changes for transaction submission sequencing
* Detect when a contract's code is upgraded (code hash change)
* Trigger user-facing notifications for balance changes

{% hint style="info" %}
`SaveAccounts` delivers only altered accounts — it is not a full state snapshot. Accounts with no changes in a block are omitted. Consumers must start from a known baseline state and apply deltas.
{% endhint %}

***

### `FinalizedBlock`

**Emitted when:** A block reaches finality (confirmed by the metachain). On MultiversX, finality typically occurs 1–2 rounds after block acceptance.

**Payload contents:**

* Shard ID
* Block nonce
* Block hash

**Consumer use cases:**

* Confirm that transactions included in a block are irreversible
* Advance a "finalized height" cursor for downstream indexers
* Trigger settlement logic that must wait for finality before proceeding

***

### `Settings`

**Emitted when:** The node sends its current configuration to mx-notifier — at startup or after a protocol upgrade.

**Payload contents:**

* Connected node version string
* Network ID
* Number of shards
* Round duration (milliseconds)
* Genesis timestamp

**Consumer use cases:**

* Validate that the notifier is connected to the expected network
* Configure shard-aware routing logic based on the current shard topology
* Log node version for audit trails