Data consistency

Introduction

The Trevo blockchain produces a new block approximately every 6 seconds. Each block can introduce changes such as token transfers, updated balances, and other relevant state modifications. When interacting with blockchain data through multiple DataGate API requests, it's crucial to ensure consistency — meaning that all retrieved data accurately reflects the blockchain state at the same specific point in time.

Importance of Data Consistency

Consider the following example:

• Initial blockchain state (block #1000):

  • Alice: 100 Crystals

  • Bob: 150 Crystals

• Blockchain state after block #1001:

  • Alice transfers 10 Crystals to Bob.

  • Alice: 90 Crystals

  • Bob: 160 Crystals

If two separate API requests are made with a slight delay between them (one during block #1000 and one after block #1001), the results can become inconsistent:

• Request 1 returns Alice's balance: 100 Crystals (block #1000 state).

• Request 2 returns Bob's balance: 160 Crystals (block #1001 state).

This inconsistency can lead to incorrect interpretations and operational errors. To avoid this, both requests must reference the same blockchain state (block #1000 or block #1001).

Request Context

DataGate API manages consistency through a mechanism known as "Request Context." This context defines the specific blockchain state from which the requested data is retrieved.

• For historical data (blocks, transactions, transfers): The request context defines the latest block included in the response.

• For current blockchain state data (balances, storage state): The request context defines the exact blockchain state (specific block) provided in the response.

Every API request and response contains a request context. You can explicitly define this context by setting the appropriate subfields of block_receipt in your request JSON. If not explicitly set, DataGate automatically uses the latest available blockchain state.

You can always check the context used in a response by inspecting the metadata.request_context field.

Important: DataGate API supports blockchain state queries for contexts not older than approximately 24 hours. Attempts to retrieve states older than this will result in an HTTP error.

Ensuring Consistency Across Paginated Results

When API requests return multiple pages of data, DataGate automatically maintains consistency. The request context set during the initial request is consistently applied across all subsequent paginated responses. No additional action is required to maintain consistency.

Ensuring Consistency Across Multiple Requests

When querying multiple endpoints, manual setting of the request context ensures consistent data across requests.

For example, to consistently fetch token balances and corresponding token transfers:

1. Execute a request to /tokens/balances without explicitly setting the request context to retrieve the latest data.

2. Capture the metadata.request_context from this response.

3. Execute subsequent requests to other endpoints (such as /tokens/transfers) explicitly using this captured context by setting the block_receipt.block_hash field.

This method ensures that all retrieved data reflects a consistent blockchain state.