@requestnetwork/data-access

@requestnetwork/data-access

@requestnetwork/data-access is a typescript library part of the Request Network protocol. It is the default implementation of the Data Access layer. The Data Access layer is responsible for:

• Indexing transactions to allow retrieval. In the context of the Request Protocol, examples of transactions are "create a request", "accept a request", "change the expected amount of a request"
• Batching them into blocks to save on cost
• Accessing transactions through a local cache
• Synchronizing with the storage

Installation

npm install @requestnetwork/data-access

Usage

Persist a Transaction

import DataAccess from '@requestnetwork/data-access';
import {
  DataAccess as DataAccessTypes,
  Signature as SignatureTypes,
  Storage as StorageTypes,
} from '@requestnetwork/types';

const storage: StorageTypes.IStorage; // Any implementation of Storage layer, @requestnetwork/ethereum-storage for example

const dataAccess = new DataAccess(storage);
await dataAccess.initialize();

const transactionData = JSON.stringify({
  attribut1: 'some value',
  attribut2: 'some other value',
});

const transactionDataSignature = {
  method: SignatureTypes.REQUEST_SIGNATURE_METHOD.ECDSA,
  value:
    '0xe649fdfe25c3ee33061a8159be9b941141121c5bed8d07664cb67b7912819b4539841a206636c190178ac58978926dad1fe3637a10b656705b71bda5e187510c1b',
};

const transaction: DataAccessTypes.IRequestDataAccessTransaction = {
  data: transactionData,
  signature: transactionDataSignature,
};

const transactionTopic = 'myRequest';

const result = await dataAccess.persistTransaction(transaction, [transactionTopic]);

Get a Transaction

import DataAccess from '@requestnetwork/data-access';
import {
  DataAccess as DataAccessTypes,
  Signature as SignatureTypes,
  Storage as StorageTypes,
} from '@requestnetwork/types';

const storage: StorageTypes.IStorage; // Any implementation of Storage layer, @requestnetwork/ethereum-storage for example

const dataAccess = new DataAccess(storage);
await dataAccess.initialize();

const transactionTopic = 'myRequest';

const { result } = await dataAccess.getTransactionsByTopic(transactionTopic);

Features

Indexing

Transactions are indexed with topics. When persisting a transaction on data-access, topics can be given as second parameters. These topics will allow retrieving transactions later. For example, each transaction made by @requestnetwork/request-logic are indexed with the requestId.

Batching

To save on costs, transactions are batched together. This is the responsibility of Data Access layer. This package creates blocks that are collections of transactions

Cache

In order to speed up recovery of transactions, data-access has a local cache of topics=>transaction. This is the reason why this package should be initialized with dataAccess.initialize() before being operational.

Synchronization

Blocks can be added into the storage by other peers running their own data-access instance. Therefore, to remain consistent with the global state of the network, this package need to synchronize with these new blocks.dataAccess.synchronizeNewDataIds() allows to synchronize manually with all unsynchronized blocks. The synchronization can also be done automatically, dataAccess.startAutoSynchronization() allows to automatically synchronize with new blocks, the interval time between each synchronization can be defined in data-access constructor. dataAccess.stopAutoSynchronization() allows to stop automatic synchronization.

Architecture

data-access implements the structure of the data on the blockchain.

The architecture is a sorted list of blocks. A block is a JSON (see packages/data-access/format/) object containing:

• a sorted list of transactions
• an index of this transactions (a dictionary referencing the transactions by arbitrary string)

A transaction is an object containing the data as a string and the signature of these data. (the data will be the actions from the request logic layer)

Example of a block

{
   "header":{
      "index":{
         "0xaaaaaa":[
            0
         ],
         "0xccccccccccc":[
            0,
            1
         ],
         "0xe53f3ea2f5a8e5f2ceb89609a9c2fa783181e70f1a7508dccf5b770b846a6a8d":[
            0
         ],
         "0x320728cd4063b523cb1b4508c6e1627f497bde5cbd46b03430e438289c6e1d23":[
            1
         ]
      },
      "version":"0.1.0"
   },
   "transactions":[
      {
         "signature":{
            "method":"ecdsa",
            "value":"0x12345"
         },
         "transaction":"{\"attribut1\":\"plop\",\"attribut2\":\"value\"}"
      },
      {
         "signature":{
            "method":"ecdsa",
            "value":"0x12345"
         },
         "transaction":"{\"attribut1\":\"foo\",\"attribut2\":\"bar\"}"
      }
   ]
}

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Read the contributing guide

License

MIT