Data consistency

Intro

TRAIT blockchain generates new block every 6 seconds. And every block can add new information - add a transfer of tokens, change token balance of an address etc.

When an app fetches blockchain data it may execute multiple requests to the DataGate API and shall ensure that the data is consistent. I.e. balances of all addresses are fetched for the same block, history of transfers fetched till the same block etc.

Why this matters

Let's consider a case when an app needs to fetch the balances of users in the fungible token Crystals and users make transactions in the same time:

• Initial state at the block #1000: Alice owns 100 Crystals, Bob owns 150 Crystals.

• Alice transfers 10 tokens to Bob and her transaction gets included into the block #1001.

• Final state at the block #1001: Alice owns 90 Crystals, Bob owns 160 Crystals.

Let's assume we have to make 2 API requests to fetch balances of these user. There is some delay between requests, during which a new blockchain block appears. In our example, we make the 1st request when there were 1000 blocks in the blockchain and the second request when there were 1001 blocks in the blockchain.

In this case, we will get incorrect results:

• Alice owns 100 Crystals - state of the block #1000;

• Bob owns 160 Crystals - state of the block #1001;

The fetched data is inconsistent. To get the correct results, we need to query the balances of both users as of block #1000.

Request context

The DataGate API uses the term "Request context":

• For historical data (such as blocks / transactions / token transfers etc.): the maximum block of the blockchain from which data gets included into the response;

• For blockchain state data (such as blockchain storage, current token balances): the block of the blockchain, the data from which is provided in the response;

Every API request / response has the request context. You can set it explicitly via any of the subfields of block_receipt in request JSON. Otherwise request context will be set automatically - it will be the latest available block.

Every API response contains information about the request context used to build the response. You can find it in the field metadata.request_context.

Note: DataGate API provides blockchain state data for request contexts not older than about 30 min. Fetching of the older blockchain states yields HTTP error.

Consistency of paginated results

When you make an API request that yields several data pages - request context is set on the very first request and is applied to all data pages.

You need to do nothing to fetch consistent data set.

Consistency of multiple requests

When you make several API requests and need consistency across all responses - you need to manually set the request contexts.

Let's consider the situation when you need to fetch user' token balances and token transfers. You could employ the following strategy to achieve the consistent result:

• you fetch balances of tokens via the endpoint /tokens/balances. You don't specify the request context and get the current state of the user balance;

• you note the request context used to build the response - field metadata.request_context of the response JSON;

• you fetch token transfers via the endpoint /tokens/transfers. You specify the request context via the field block_receipt.block_hash;

As a result the token balances and token transfers will be consistent with each other.