Skip to main content

​
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 or Archive Exports.

​
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.
​
chain_id
number
The EVM network identifier.
​
dataset_id
string
The 4-digit ID of the stream (e.g., 0101 for Blocks).
​
is_reorg
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.
​
data
object
The stream-specific payload.
{
  "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"
  }
}

​
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_ids 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.
Maximum Reorg Depth: You can find the maximum expected reorg depth for each chain on the Data Freshness page. This is usually the window within which corrections may occur.

​
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 for the last few blocks to ensure no messages were missed during transient network blips.

​
See Also