> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reliability & Reorgs

> Ordering guarantees, deduplication, and how to handle EVM chain reorganizations in BlockDB WSS streams.

## Delivery Model

BlockDB WebSocket (WSS) streams are optimized for **real-time, low-latency delivery**. They are intended to trigger actions and update local caches, not to serve as a persistent, gap-free historical archive.

* **Idempotency is Required**: Messages can occasionally be redelivered after a reconnection.
* **Connection Loss**: Standard WebSocket connections do not buffer messages while a client is offline.
* **Completeness**: While we aim for 100% delivery, mission-critical systems should reconcile WSS data with our [REST APIs](/api-reference/evm/overview) or [Bulk Exports](/pricing/home#bulk-export-sftp-s3-azure--more).

## Standard Update Envelope

Every data update sent by the server follows a consistent envelope. This allows you to route messages to the correct handler before parsing the stream-specific `data` payload.

<ResponseField name="chain_id" type="number">
  The EVM network identifier.
</ResponseField>

<ResponseField name="dataset_id" type="string">
  The 4-digit ID of the stream (e.g., `0101` for Blocks).
</ResponseField>

<ResponseField name="is_reorg" type="boolean">
  If `true`, this message is a **reorg correction**. It indicates that a previously emitted record at this height/index has been eclipsed and this new message contains the updated canonical state.
</ResponseField>

<ResponseField name="data" type="object">
  The stream-specific payload.
</ResponseField>

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0101",
    "is_reorg": false,
    "data": {
      "block_number": 12345678,
      "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
      "parent_block_hash": "f78e26c5959a94d6a62ed3837f5dcecf0d3761bf0a502e12a08fd7bc44c8568d",
      "miner": "0000000000000000000000000000000000000000",
      "gas_limit": 30000000,
      "size": 124836,
      "timestamp_utc": "2025-11-11T18:42:15.123Z",
      "_tracing_id": "010100000000000000000000000000000000",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>

## Ordering & Deduplication

### Ordering Guarantees

* **Per-Stream**: Messages within a single `dataset_id` on a specific `chain_id` are delivered in the exact order they are processed by our ingestion engine.
* **Cross-Stream**: There is **no global ordering** guarantee across different datasets. For example, a `Logs` message might arrive slightly before or after the `Blocks` message for the same height.

### Deduplication

Most `data` payloads include a `_tracing_id`. This is a unique, deterministic hash of the record.

* **Strategy**: Maintain a small LRU cache of recently seen `_tracing_id`s to skip duplicates.
* **Alternative**: If a stream lacks `_tracing_id`, use the natural primary key (e.g., `tx_hash` + `log_index`).

## Handling Chain Reorganizations (Reorgs)

EVM chains are probabilistic; blocks can be "reorged" out of the canonical chain after they are mined. BlockDB is reorg-aware and provides explicit signals so your application stays in sync with the canonical chain.

### The `is_reorg` Signal

When a reorg occurs, BlockDB emits a new message for the affected record with **`is_reorg: true`**.

1. **Detection**: Your handler sees `is_reorg: true`.
2. **Action**: Treat this as an **overwrite**. If you have already stored or processed a record at this `block_number` (or `tx_hash`), replace it with the data in the new message.
3. **Propagation**: If you have derived state (e.g., a user's balance), you may need to recalculate it using the new canonical data.

<Tip>
  **Maximum Reorg Depth**: You can find the maximum expected reorg depth for each chain on the [Data Freshness](/data-catalog/overview/data-freshness) page. This is usually the window within which corrections may occur.
</Tip>

## Practical Implementation Guidance

To build a production-grade stream consumer, we recommend the following patterns:

* **Upsert Logic**: Design your database/cache handlers to perform `UPSERT` operations. This naturally handles both duplicates and reorg corrections.
* **Stateless Triggers**: If using WSS to trigger external actions (like sending an email), consider waiting for a specific number of block confirmations or verify the event via REST API before executing.
* **The Reconciliation Loop**:
  * Use WSS for **Real-time UI** and **Low-latency actions**.
  * Periodically (e.g., every 5 minutes) query the [REST API](/api-reference/evm/overview) for the last few blocks to ensure no messages were missed during transient network blips.

## See Also

* [Quickstart](/wss-reference/overview/quickstart) - Connect and subscribe in minutes.
* [Connection Management](/wss-reference/overview/connection-management) - Heartbeats and reconnection.
* [Dataset ID](/api-reference/enumerations/dataset-id) — How `dataset_id` maps to tables and `_tracing_id` joins rows across exports.