Streaming pending data

The Apibara streaming protocol supports sending pending data, that is data that has not been produced on the chain yet.

This feature is extremely powerful and unique to Apibara. Developers can use it to add optimistic updates to their application, this makes the application feel faster and more responsive to the users.

Use cases for optimistic updates are:

Gaming: update a game's state as players submit their moves.
NFT: update a drop status in real-time.
DeFi: show prices and liquidity as they will be in the future, not the past.
Social: create a smooth user experience.

Requesting pending data

Request pending data when configuring the stream by the finality configuration to DATA_STATUS_PENDING. Apibara may send multiple pending blocks between accepted blocks if it detects pending data changing.


┌──────────┐                               ┌──────────┐
│  Client  │                               │  Server  │
└──────────┘                               └──────────┘
      │                                          │
      │   StreamDataRequest(finality=PENDING)    │
      │─────────────────────────────────────────▶│
      │                                          │
      │                                          │
      │  StreamDataResponse(finality=ACCEPTED)   │
      │◀─────────────────────────────────────────│
      │   StreamDataResponse(finality=PENDING)   │
      │◀─────────────────────────────────────────│
      │   StreamDataResponse(finality=PENDING)   │
      │◀─────────────────────────────────────────│
      │  StreamDataResponse(finality=ACCEPTED)   │
      │◀─────────────────────────────────────────│
      │                                          │
      │                                          │

Best practices for handling pending data

Treat pending data as "mini" chain reorganizations. Invalidate the previous pending data before handling the new pending data. The Apibara integrations do this automatically for you.
Invalidate pending data when receiving a new data message. The Apibara integrations do this automatically for you.