> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/system-overview/user-authentication-and-wallet-management-system/event-tags-and-processing.md).

# Event Tags and Processing

This section documents all event types emitted and consumed within the 0box platform, primarily via the **KafkaEventsTopic** and **KafkaBlobberMonitorEventsTopic**. These events represent blockchain state transitions or service-side activities, and they are used to:

* Persist blockchain/provider/user state in the event store DB
* Trigger downstream processes like indexing, metrics aggregation, allocation updates, or Redis publishing

## Kafka Topics

#### 1. **KafkaEventsTopic**

* Used for **core blockchain and provider events**.
* Events are **grouped by blockchain round and source**.
* Processed in **batches**, atomically inside a DB transaction.
* After DB update, certain events are **published to Redis** for real-time tracking (e.g., user rewards, finalised blocks).

#### 2. **KafkaBlobberMonitorEventsTopic**

* Used for **real-time blobber monitoring stats** (e.g., disk usage, availability).
* Events are **processed immediately**, one at a time.
* No grouping or consensus logic.
* Data is unmarshalled into `BlobberMonitoring` objects and stored in the DB.

## Event Tags

Below are all tags handled by the `EventStore.Process` logic. Tags are grouped by entity type.

### Block Events

| Tag                | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `TagFinalizeBlock` | Adds or updates block, increments finalized block count for miner. |

### User Events

| Tag                     | Description                       |
| ----------------------- | --------------------------------- |
| `TagAddOrOverwriteUser` | Adds or updates a user in the DB. |

### Transaction Events

| Tag                  | Description                                               |
| -------------------- | --------------------------------------------------------- |
| `TagAddTransactions` | Adds transactions, indexes them in Elasticsearch (async). |

### Blobber Events

| Tag                                    | Description                                             |
| -------------------------------------- | ------------------------------------------------------- |
| `TagAddBlobber`                        | Adds a new blobber.                                     |
| `TagUpdateBlobber`                     | Updates blobber metadata or config.                     |
| `TagDeleteBlobber`                     | Deletes blobber from system.                            |
| `TagUpdateBlobberAllocatedSavedHealth` | Updates allocated size, saved data, and health metrics. |
| `TagUpdateBlobberTotalStake`           | Updates total delegated stake for a blobber.            |
| `TagUpdateBlobberTotalOffers`          | Updates the number of storage offers available.         |

### Authorizer Events

| Tag                             | Description                              |
| ------------------------------- | ---------------------------------------- |
| `TagAddAuthorizer`              | Adds an authorizer to the system.        |
| `TagDeleteAuthorizer`           | Removes an authorizer from the system.   |
| `TagUpdateAuthorizerTotalStake` | Updates the total stake for authorizers. |

### Validator Events

| Tag                            | Description                    |
| ------------------------------ | ------------------------------ |
| `TagAddOrOverwiteValidator`    | Adds or updates a validator.   |
| `TagUpdateValidator`           | Updates validator metadata.    |
| `TagUpdateValidatorStakeTotal` | Updates total validator stake. |

### Miner Events

| Tag                        | Description                  |
| -------------------------- | ---------------------------- |
| `TagAddMiner`              | Adds a new miner.            |
| `TagUpdateMiner`           | Updates miner details.       |
| `TagDeleteMiner`           | Deletes a miner.             |
| `TagUpdateMinerTotalStake` | Updates miner’s total stake. |

### Sharder Events

| Tag                          | Description                    |
| ---------------------------- | ------------------------------ |
| `TagAddSharder`              | Adds a new sharder.            |
| `TagUpdateSharder`           | Updates sharder info.          |
| `TagDeleteSharder`           | Deletes a sharder.             |
| `TagUpdateSharderTotalStake` | Updates sharder’s total stake. |

### Stake Pool Events

| Tag                     | Description                                |
| ----------------------- | ------------------------------------------ |
| `TagAddDelegatePool`    | Adds a delegate pool.                      |
| `TagUpdateDelegatePool` | Updates delegate pool info.                |
| `TagStakePoolReward`    | Records rewards to a pool & blobber stats. |
| `TagStakePoolPenalty`   | Applies penalty to pool and blobber stats. |

### User Fee/Reward Events

| Tag                             | Description                      |
| ------------------------------- | -------------------------------- |
| `TagUpdateUserCollectedRewards` | Updates total rewards collected. |
| `TagUpdateUserPayedFees`        | Updates user’s total paid fees.  |

### Lock/Unlock Pool Events

| Tag                  | Description                     |
| -------------------- | ------------------------------- |
| `TagLockStakePool`   | Locks stake pool tokens.        |
| `TagUnlockStakePool` | Unlocks stake pool tokens.      |
| `TagLockReadPool`    | Locks tokens into read pool.    |
| `TagUnlockReadPool`  | Unlocks tokens from read pool.  |
| `TagLockWritePool`   | Locks tokens into write pool.   |
| `TagUnlockWritePool` | Unlocks tokens from write pool. |

### Allocation Events

| Tag                         | Description                                             |
| --------------------------- | ------------------------------------------------------- |
| `TagAddAllocation`          | Adds new storage allocation.                            |
| `TagUpdateAllocation`       | Updates an allocation. Cancels Stripe sub if cancelled. |
| `TagUpdateAllocationStakes` | Updates allocation stake pools.                         |

### Reward Minting

| Tag             | Description                        |
| --------------- | ---------------------------------- |
| `TagMintReward` | Adds mint record for user rewards. |

### Challenge Events

| Tag                            | Description                             |
| ------------------------------ | --------------------------------------- |
| `TagAddChallenge`              | Adds a new challenge.                   |
| `TagAddChallengeToAllocation`  | Associates challenge with allocation.   |
| `TagUpdateChallenge`           | Updates challenge outcome/status.       |
| `TagUpdateBlobberChallenge`    | Updates blobber challenge statistics.   |
| `TagUpdateAllocationChallenge` | Updates challenge stats per allocation. |

### Allocation Blobber Term Events

| Tag                                      | Description                                  |
| ---------------------------------------- | -------------------------------------------- |
| `TagAddOrOverwriteAllocationBlobberTerm` | Adds or overwrites allocation blobber terms. |
| `TagUpdateAllocationBlobberTerm`         | Updates blobber term for allocation.         |
| `TagDeleteAllocationBlobberTerm`         | Deletes allocation blobber term.             |

### Stat Updates

| Tag                       | Description                       |
| ------------------------- | --------------------------------- |
| `TagUpdateAllocationStat` | Updates storage allocation stats. |
| `TagUpdateBlobberStat`    | Updates blobber usage/statistics. |

### Challenge Pool

| Tag                           | Description                   |
| ----------------------------- | ----------------------------- |
| `TagAddOrUpdateChallengePool` | Updates challenge pool stats. |

### Read Pool

| Tag                 | Description                       |
| ------------------- | --------------------------------- |
| `TagInsertReadpool` | Inserts a new read pool entry.    |
| `TagUpdateReadpool` | Updates existing read pool entry. |

### Provider Reward

| Tag                        | Description                      |
| -------------------------- | -------------------------------- |
| `TagCollectProviderReward` | Logs provider reward collection. |

### Health Check Events

| Tag                        | Description                           |
| -------------------------- | ------------------------------------- |
| `TagMinerHealthCheck`      | Updates health status for miner.      |
| `TagSharderHealthCheck`    | Updates health status for sharder.    |
| `TagBlobberHealthCheck`    | Updates health status for blobber.    |
| `TagAuthorizerHealthCheck` | Updates health status for authorizer. |
| `TagValidatorHealthCheck`  | Updates health status for validator.  |

### Burn & Mint Events

| Tag                 | Description                            |
| ------------------- | -------------------------------------- |
| `TagAuthorizerBurn` | Tracks tokens burned by authorizer.    |
| `TagAddBurnTicket`  | Adds a burn ticket.                    |
| `TagAddBridgeMint`  | Adds mint record from bridge contract. |

### Shutdown/Kill Events

| Tag                   | Description                  |
| --------------------- | ---------------------------- |
| `TagShutdownProvider` | Marks provider as shut down. |
| `TagKillProvider`     | Marks provider as killed.    |

### Summary

* **KafkaEventsTopic** is critical for state sync and historic aggregation.
* Tags are mapped to specific DB models and also feed analytics systems.
* Certain events (like rewards, transactions, allocations) also drive Stripe subscription logic, search indexing, and wallet updates.
* The event system ensures **strong consistency** by grouping events per round and applying DB updates atomically.