@dashevo/dapi-client 1.0.0-pr.1825.9 → 1.0.0-pr.1883.1

package/docs/_sidebar.md

@@ -7,13 +7,15 @@
                 - [.broadcastTransaction()](usage/application/core/broadcastTransaction.md)
                 - [.generateToAddress()](usage/application/core/generateToAddress.md)
                 - [.getBestBlockHash()](usage/application/core/getBestBlockHash.md)
+                - [.getBestBlockHeight()](usage/application/core/getBestBlockHeight.md)
                 - [.getBlockByHash()](usage/application/core/getBlockByHash.md)
                 - [.getBlockByHeight()](usage/application/core/getBlockByHeight.md)
                 - [.getBlockHash()](usage/application/core/getBlockHash.md)
-                - [.getMnListDiff()](usage/application/core/getMnListDiff.md)
                 - [.getStatus()](usage/application/core/getStatus.md)
                 - [.getTransaction()](usage/application/core/getTransaction.md)
                 - [.subscribeToTransactionsWithProofs()](usage/application/core/subscribeToTransactionsWithProofs.md)
+                - [.subscribeToBlockHeadersWithChainLocks()](usage/application/core/subscribeToBlockHeadersWithChainLocks.md)
+                - [.subscribeToMasternodeList()](usage/application/core/subscribeToMasternodeList.md)
             - Platform 
                 - [.broadcastStateTransition()](usage/application/platform/broadcastStateTransition.md)
                 - [.getDataContract()](usage/application/platform/getDataContract.md)

package/docs/usage/application/core/getBestBlockHeight.md

@@ -0,0 +1,10 @@
+**Usage**: `await client.core.getBestBlockHeight(options)`  
+**Description**: Allow to fetch the best (highest/latest block height) from the network
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<string>} - The best block height

package/docs/usage/application/core/subscribeToBlockHeadersWithChainLocks.md

@@ -0,0 +1,39 @@
+**Usage**: `await client.core.subscribeToBlockHeadersWithChainLocks(options = { count: 0 })`\
+**Description**: Returns a ClientReadableStream streaming of block headers and chainlocks.
+
+
+Parameters:
+
+| parameters                | type             | required       | Description                                                                                             |
+|----------------------------|------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **options.fromBlockHash**  | String           | yes            | Specifies block hash to start syncing from |
+| **options.fromBlockHeight**| Number           | yes            | Specifies block height to start syncing from |
+| **options.count**          | Number           | no (default: 0)| Number of blocks to sync, if set to 0 syncing is continuously sends new data as well |
+
+Returns : Promise<EventEmitter>|!grpc.web.ClientReadableStream<!BlockHeadersWithChainLocksResponse>
+
+Example :
+
+```js
+const { BlockHeader, ChainLock } = require('@dashevo/dashcore-lib');
+
+const stream = await client.subscribeToBlockHeadersWithChainLocks({ fromBlockHeight: 0 });
+
+stream
+      .on('data', (response) => {
+        const rawHeaders = response.getBlockHeaders();
+        const rawChainLock = response.getChainLock();
+
+        if (headers.length > 0) {
+          const headers = rawHeaders.map((rawHeader) =>  new BlockHeader(rawHeader));
+          console.dir(headers);
+        }
+
+        if (rawChainLock) {
+          const chainLock = new ChainLock(rawChainLock);
+        }
+      })
+    .on('error', (err) => {
+        // do something with err
+      });
+```

package/docs/usage/application/core/subscribeToMasternodeList.md

@@ -0,0 +1,24 @@
+**Usage**: `await client.core.subscribeToMasternodeList(options = {})`\
+**Description**: Returns a ClientReadableStream streaming of masternode list diffs ([DIP-4](https://github.com/dashpay/dips/blob/master/dip-0004.md)). As a first message it returns a diff from the first block to the current tip and a diff for each new chainlocked block. 
+
+Returns : Promise<EventEmitter>|!grpc.web.ClientReadableStream<!MasternodeListResponse>
+
+Example :
+
+```js
+const { SimplifiedMNList, SimplifiedMNListDiff } = require('@dashevo/dashcore-lib');
+
+const stream = await client.subscribeToMasternodeList();
+
+const list = new SimplifiedMNList();
+
+stream
+      .on('data', (response) => {
+        const diffBuffer = Buffer.from(response.getMasternodeListDiff_asU8());
+        const diff = new SimplifiedMNListDiff(diffBuffer);
+        list.applyDiff(diff);
+      })
+    .on('error', (err) => {
+        // do something with err
+      });
+```

package/docs/usage/{utils → application/core}/subscribeToTransactionsWithProofs.md

@@ -19,24 +19,27 @@ Returns : Promise<EventEmitter>|!grpc.web.ClientReadableStream<!TransactionsWith
 Example :
 
 ```js
-const filter; // A BloomFilter object
+const { BloomFilter, Transaction, MerkleBlock } = require('@dashevo/dashcore-lib');
+
+const filter = BloomFilter.create(1, 0.001); // A BloomFilter object
 const stream = await client.subscribeToTransactionsWithProofs(filter, { fromBlockHeight: 0 });
 
 stream
       .on('data', (response) => {
-        const merkleBlock = response.getRawMerkleBlock();
-        const transactions = response.getRawTransactions();
+        const rawMerkleBlock = response.getRawMerkleBlock();
+        const rawTransactions = response.getRawTransactions();
 
         if (merkleBlock) {
-          const merkleBlockHex = Buffer.from(merkleBlock).toString('hex');
+          const merkleBlock = new MerkleBlock(rawMerkleBlock);
+          console.dir(merkleBlock);
         }
 
-        if (transactions) {
-          transactions.getTransactionsList()
-              .forEach((tx) => {
-                  // tx are probabilistic, so you will have to verify it's yours
-                  const tx = new Transaction(Buffer.from(tx));
-              });
+        if (transactions.length > 0) {
+          // tx are probabilistic, so you will have to verify it's yours
+          const transactions = transactions.getTransactionsList()
+              .map((tx) => new Transaction(Buffer.from(tx)));
+          
+          console.dir(transactions);
         }
       })
     .on('error', (err) => {

package/lib/BlockHeadersProvider/createBlockHeadersProviderFromOptions.js

@@ -19,14 +19,15 @@ const validateNumber = (value, name, min = NaN, max = NaN) => {
 /**
  * @typedef {createBlockHeadersProviderFromOptions}
  * @param {DAPIClientOptions} options
+ * @param logger
  * @param {CoreMethodsFacade} coreMethods
  * @returns {BlockHeadersProvider}
  */
-function createBlockHeadersProviderFromOptions(options, coreMethods) {
+function createBlockHeadersProviderFromOptions(options, coreMethods, logger) {
   let blockHeadersProvider;
   if (options.blockHeadersProvider) {
     if (options.blockHeadersProviderOptions) {
-      throw new DAPIClientError("Can't use 'blockHeadersProviderOptions' with 'blockHeadersProvider' option");
+      throw new DAPIClientError('Can\'t use \'blockHeadersProviderOptions\' with \'blockHeadersProvider\' option');
     }
 
     blockHeadersProvider = options.blockHeadersProvider;
@@ -37,6 +38,7 @@ function createBlockHeadersProviderFromOptions(options, coreMethods) {
       coreMethods.subscribeToBlockHeadersWithChainLocks,
       {
         maxRetriesOnError: -1,
+        logger,
       },
     )({
       fromBlockHeight,

package/lib/DAPIClient.js

@@ -70,12 +70,30 @@ class DAPIClient extends EventEmitter {
    * @private
    */
   initBlockHeadersProvider() {
-    this.blockHeadersProvider = createBlockHeadersProviderFromOptions(this.options, this.core);
+    this.blockHeadersProvider = createBlockHeadersProviderFromOptions(
+      this.options,
+      this.core,
+      this.logger,
+    );
 
     this.blockHeadersProvider.on(BlockHeadersProvider.EVENTS.ERROR, (e) => {
       this.emit(EVENTS.ERROR, e);
     });
   }
+
+  /**
+   * Close all open connections
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    // Stop block headers provider
+    await this.blockHeadersProvider.stop();
+
+    // Stop masternode list provider
+    if (this.dapiAddressProvider.smlProvider) {
+      await this.dapiAddressProvider.smlProvider.unsubscribe();
+    }
+  }
 }
 
 DAPIClient.EVENTS = EVENTS;

package/lib/SimplifiedMasternodeListProvider/SimplifiedMasternodeListProvider.js

@@ -1,27 +1,33 @@
 const SimplifiedMNList = require('@dashevo/dashcore-lib/lib/deterministicmnlist/SimplifiedMNList');
 const SimplifiedMNListDiff = require('@dashevo/dashcore-lib/lib/deterministicmnlist/SimplifiedMNListDiff');
 
+const logger = require('../logger');
+
 class SimplifiedMasternodeListProvider {
   /**
-   *
-   * @param {JsonRpcTransport} jsonRpcTransport - JsonRpcTransport instance
+   * @param {Function} createStream - JsonRpcTransport instance
    * @param {object} [options] - Options
-   * @param {number} [options.updateInterval]
    * @param {string} [options.network]
+   * @param {string} [options.loggerOptions]
    */
-  constructor(jsonRpcTransport, options = {}) {
-    this.jsonRpcTransport = jsonRpcTransport;
-
-    this.options = {
-      updateInterval: 60000,
-      ...options,
-    };
-
-    this.simplifiedMNList = new SimplifiedMNList(undefined, this.options.network);
+  constructor(createStream, options = {}) {
+    this.createStream = createStream;
+    this.options = options;
+    this.logger = logger.getForId(
+      this.options.loggerOptions.identifier,
+      this.options.loggerOptions.level,
+    );
 
-    this.lastUpdateDate = 0;
+    /**
+     * @type {ReconnectableStream}
+     */
+    this.stream = undefined;
+    this.removeStreamListeners = () => {};
 
-    this.baseBlockHash = SimplifiedMasternodeListProvider.NULL_HASH;
+    /**
+     * @type {SimplifiedMNList}
+     */
+    this.simplifiedMNList = new SimplifiedMNList(undefined);
   }
 
   /**
@@ -29,75 +35,178 @@ class SimplifiedMasternodeListProvider {
    * @returns {Promise<SimplifiedMNList>}
    */
   async getSimplifiedMNList() {
-    if (this.needsUpdate()) {
-      await this.updateMasternodeList();
+    if (this.stream === undefined) {
+      await this.subscribeToMasternodeList();
     }
 
     return this.simplifiedMNList;
   }
 
   /**
-   * Checks whether simplified masternode list needs update
+   * Subscribe to simplified masternodes list updates. No need to call it manually
    * @private
-   * @returns {boolean}
+   * @returns {Promise<void>}
    */
-  needsUpdate() {
-    return Date.now() - this.options.updateInterval > this.lastUpdateDate;
-  }
-
-  /**
-   * Updates simplified masternodes list. No need to call it manually
-   * @private
-   */
-  async updateMasternodeList() {
-    const diff = await this.getSimplifiedMNListDiff();
-
-    try {
-      this.simplifiedMNList.applyDiff(diff);
-    } catch (e) {
-      if (e.message === 'Cannot apply diff: previous blockHash needs to equal the new diff\'s baseBlockHash') {
-        this.reset();
-
-        await this.updateMasternodeList();
-
-        return;
-      }
-
-      throw e;
+  async subscribeToMasternodeList() {
+    if (this.stream) {
+      this.logger.debug('Masternode list stream already started');
+      return Promise.resolve();
     }
 
-    this.baseBlockHash = diff.blockHash;
+    this.logger.debug('Starting masternode list stream');
 
-    this.lastUpdateDate = Date.now();
-  }
+    this.stream = await this.createStream();
 
-  /**
-   * Fetches masternode diff from DAPI
-   * @private
-   * @returns {Promise<SimplifiedMNListDiff>}
-   */
-  async getSimplifiedMNListDiff() {
-    const blockHash = await this.jsonRpcTransport.request('getBestBlockHash');
+    let diffCount = 0;
+    let resolved = false;
 
-    const rawSimplifiedMNListDiff = await this.jsonRpcTransport.request(
-      'getMnListDiff',
-      { baseBlockHash: this.baseBlockHash, blockHash },
-      { addresses: [this.jsonRpcTransport.getLastUsedAddress()] },
-    );
+    const rejectDiff = (error) => {
+      this.logger.silly('Stream is cancelled due to error. Retrying...', { error });
 
-    return new SimplifiedMNListDiff(rawSimplifiedMNListDiff, this.options.network);
+      this.stream.cancel();
+      this.stream.retryOnError(error);
+    };
+
+    return new Promise((resolve, reject) => {
+      const errorHandler = (error) => {
+        this.stream = null;
+
+        this.logger.error(
+          `Masternode list sync failed: ${error.message}`,
+          { error, diffCount },
+        );
+
+        if (!resolved) {
+          reject(error);
+          resolved = true;
+        }
+      };
+
+      const dataHandler = (response) => {
+        diffCount += 1;
+
+        if (diffCount === 1) {
+          this.logger.silly(
+            'Full masternode list diff received',
+            { diffCount },
+          );
+        } else {
+          this.logger.silly(
+            'Received masternode list diff',
+            { diffCount },
+          );
+        }
+
+        let simplifiedMNListDiff;
+        let simplifiedMNListDiffBuffer;
+        try {
+          simplifiedMNListDiffBuffer = Buffer.from(response.getMasternodeListDiff_asU8());
+          simplifiedMNListDiff = new SimplifiedMNListDiff(
+            simplifiedMNListDiffBuffer,
+            this.options.network,
+          );
+        } catch (e) {
+          this.logger.warn(
+            `Can't parse masternode list diff: ${e.message}`,
+            {
+              diffCount,
+              network: this.options.network,
+              error: e,
+              simplifiedMNListDiff: simplifiedMNListDiffBuffer.toString('hex'),
+            },
+          );
+
+          rejectDiff(e);
+
+          return;
+        }
+
+        this.logger.silly(
+          'Parsed masternode list diff successfully',
+          {
+            diffCount,
+            blockHash: simplifiedMNListDiff.blockHash,
+          },
+        );
+
+        try {
+          // Restart list when we receive a full diff
+          if (diffCount === 1) {
+            this.simplifiedMNList = new SimplifiedMNList(simplifiedMNListDiff);
+          } else {
+            this.simplifiedMNList.applyDiff(simplifiedMNListDiff);
+          }
+        } catch (e) {
+          this.logger.warn(
+            `Can't apply masternode list diff: ${e.message}`,
+            {
+              diffCount,
+              network: this.options.network,
+              blockHash: simplifiedMNListDiff.blockHash,
+              error: e,
+              simplifiedMNListDiff,
+            },
+          );
+
+          rejectDiff(e);
+        }
+
+        this.logger.silly(
+          'Masternode list diff applied successfully',
+          {
+            diffCount,
+            blockHash: simplifiedMNListDiff.blockHash,
+          },
+        );
+
+        if (!resolved) {
+          resolve();
+          resolved = true;
+        }
+      };
+
+      const beforeReconnectHandler = () => {
+        diffCount = 0;
+
+        this.logger.debug(
+          'Restarting masternode list stream',
+          { diffCount },
+        );
+      };
+
+      const endHandler = () => {
+        this.logger.warn(
+          'Masternode list sync stopped',
+          { diffCount },
+        );
+
+        this.removeStreamListeners();
+        this.stream = null;
+      };
+
+      this.stream.on('data', dataHandler);
+      this.stream.on('beforeReconnect', beforeReconnectHandler);
+      this.stream.on('error', errorHandler);
+      this.stream.on('end', endHandler);
+
+      this.removeStreamListeners = () => {
+        this.stream.removeListener('data', dataHandler);
+        this.stream.removeListener('beforeReconnect', beforeReconnectHandler);
+        this.stream.removeListener('error', errorHandler);
+        this.stream.removeListener('end', endHandler);
+      };
+    });
   }
 
   /**
-   * Reset simplifiedMNList
-   * @private
+   * Unsubscribe from masternode list updates
    */
-  reset() {
-    this.simplifiedMNList = new SimplifiedMNList(undefined, this.options.network);
-
-    this.lastUpdateDate = 0;
-
-    this.baseBlockHash = SimplifiedMasternodeListProvider.NULL_HASH;
+  unsubscribe() {
+    if (this.stream) {
+      this.removeStreamListeners();
+      this.stream.cancel();
+      this.stream = null;
+    }
   }
 }
 

package/lib/SimplifiedMasternodeListProvider/createMasternodeListStreamFactory.js

@@ -0,0 +1,49 @@
+const {
+  v0: {
+    MasternodeListRequest,
+    CorePromiseClient,
+  },
+} = require('@dashevo/dapi-grpc');
+
+const GrpcTransport = require('../transport/GrpcTransport/GrpcTransport');
+const createGrpcTransportError = require('../transport/GrpcTransport/createGrpcTransportError');
+const ReconnectableStream = require('../transport/ReconnectableStream');
+
+/**
+ * Creates continues masternode list stream
+ *
+ * @param {createDAPIAddressProviderFromOptions} createDAPIAddressProviderFromOptions
+ * @param {ListDAPIAddressProvider} listDAPIAddressProvider
+ * @param {Object} options
+ * @return {function(...[*]): Promise<ReconnectableStream>}
+ */
+function createMasternodeListStreamFactory(
+  createDAPIAddressProviderFromOptions,
+  listDAPIAddressProvider,
+  options,
+) {
+  const grpcTransport = new GrpcTransport(
+    createDAPIAddressProviderFromOptions,
+    listDAPIAddressProvider,
+    createGrpcTransportError,
+    options,
+  );
+
+  return ReconnectableStream
+    .create(
+      () => grpcTransport.request(
+        CorePromiseClient,
+        'subscribeToMasternodeList',
+        new MasternodeListRequest(),
+        {
+          timeout: undefined,
+          autoReconnectInterval: 0,
+        },
+      ),
+      {
+        maxRetriesOnError: -1,
+      },
+    );
+}
+
+module.exports = createMasternodeListStreamFactory;

package/lib/dapiAddressProvider/createDAPIAddressProviderFromOptions.js

@@ -6,10 +6,7 @@ const ListDAPIAddressProvider = require('./ListDAPIAddressProvider');
 
 const SimplifiedMasternodeListProvider = require('../SimplifiedMasternodeListProvider/SimplifiedMasternodeListProvider');
 const SimplifiedMasternodeListDAPIAddressProvider = require('./SimplifiedMasternodeListDAPIAddressProvider');
-
-const JsonRpcTransport = require('../transport/JsonRpcTransport/JsonRpcTransport');
-const requestJsonRpc = require('../transport/JsonRpcTransport/requestJsonRpc');
-const createJsonTransportError = require('../transport/JsonRpcTransport/createJsonTransportError');
+const createMasternodeListStreamFactory = require('../SimplifiedMasternodeListProvider/createMasternodeListStreamFactory');
 
 const DAPIClientError = require('../errors/DAPIClientError');
 
@@ -82,17 +79,15 @@ function createDAPIAddressProviderFromOptions(options) {
       options,
     );
 
-    const jsonRpcTransport = new JsonRpcTransport(
+    const createStream = createMasternodeListStreamFactory(
       createDAPIAddressProviderFromOptions,
-      requestJsonRpc,
       listDAPIAddressProvider,
-      createJsonTransportError,
       options,
     );
 
     const smlProvider = new SimplifiedMasternodeListProvider(
-      jsonRpcTransport,
-      { network: options.network },
+      createStream,
+      options,
     );
 
     return new SimplifiedMasternodeListDAPIAddressProvider(

package/lib/methods/core/CoreMethodsFacade.js

@@ -1,15 +1,15 @@
 const broadcastTransactionFactory = require('./broadcastTransactionFactory');
-const generateToAddressFactory = require('./generateToAddressFactory');
 const getBestBlockHashFactory = require('./getBestBlockHashFactory');
+const getBestBlockHeightFactory = require('./getBestBlockHeightFactory');
 const getBlockByHashFactory = require('./getBlockByHashFactory');
 const getBlockByHeightFactory = require('./getBlockByHeightFactory');
 const getBlockHashFactory = require('./getBlockHashFactory');
-const getMnListDiffFactory = require('./getMnListDiffFactory');
 const getBlockchainStatusFactory = require('./getBlockchainStatusFactory');
 const getMasternodeStatusFactory = require('./getMasternodeStatusFactory');
 const getTransactionFactory = require('./getTransaction/getTransactionFactory');
 const subscribeToTransactionsWithProofsFactory = require('./subscribeToTransactionsWithProofsFactory');
 const subscribeToBlockHeadersWithChainLocksFactory = require('./subscribeToBlockHeadersWithChainLocksFactory');
+const subscribeToToMasternodeListFactory = require('./subscribeToMasternodeListFactory');
 
 class CoreMethodsFacade {
   /**
@@ -18,12 +18,11 @@ class CoreMethodsFacade {
    */
   constructor(jsonRpcTransport, grpcTransport) {
     this.broadcastTransaction = broadcastTransactionFactory(grpcTransport);
-    this.generateToAddress = generateToAddressFactory(jsonRpcTransport);
     this.getBestBlockHash = getBestBlockHashFactory(jsonRpcTransport);
+    this.getBestBlockHeight = getBestBlockHeightFactory(grpcTransport);
     this.getBlockByHash = getBlockByHashFactory(grpcTransport);
     this.getBlockByHeight = getBlockByHeightFactory(grpcTransport);
     this.getBlockHash = getBlockHashFactory(jsonRpcTransport);
-    this.getMnListDiff = getMnListDiffFactory(jsonRpcTransport);
     this.getBlockchainStatus = getBlockchainStatusFactory(grpcTransport);
     this.getMasternodeStatus = getMasternodeStatusFactory(grpcTransport);
     this.getTransaction = getTransactionFactory(grpcTransport);
@@ -33,6 +32,9 @@ class CoreMethodsFacade {
     this.subscribeToBlockHeadersWithChainLocks = subscribeToBlockHeadersWithChainLocksFactory(
       grpcTransport,
     );
+    this.subscribeToMasternodeList = subscribeToToMasternodeListFactory(
+      grpcTransport,
+    );
   }
 }
 

package/lib/methods/core/getBestBlockHeightFactory.js

@@ -0,0 +1,34 @@
+const {
+  v0: {
+    GetBestBlockHeightRequest,
+    CorePromiseClient,
+  },
+} = require('@dashevo/dapi-grpc');
+
+/**
+ *
+ * @param {GrpcTransport} grpcTransport
+ * @returns {getBestBlockHeight}
+ */
+function getBestBlockHeightFactory(grpcTransport) {
+  /**
+   * Returns block height of chain tip
+   * @typedef {getBestBlockHeight}
+   * @param {DAPIClientOptions} [options]
+   * @returns {Promise<string>}
+   */
+  async function getBestBlockHeight(options = {}) {
+    const response = await grpcTransport.request(
+      CorePromiseClient,
+      'getBestBlockHeight',
+      new GetBestBlockHeightRequest(),
+      options,
+    );
+
+    return response.getHeight();
+  }
+
+  return getBestBlockHeight;
+}
+
+module.exports = getBestBlockHeightFactory;

package/lib/methods/core/subscribeToMasternodeListFactory.js

@@ -0,0 +1,46 @@
+const {
+  v0: {
+    MasternodeListRequest,
+    CorePromiseClient,
+  },
+} = require('@dashevo/dapi-grpc');
+
+/**
+ * @param {GrpcTransport} grpcTransport
+ * @returns {subscribeToMasternodeList}
+ */
+function subscribeToMasternodeListFactory(grpcTransport) {
+  /**
+   * @typedef {subscribeToMasternodeList}
+   * @param {DAPIClientOptions & subscribeToMasternodeListOptions} [options]
+   * @returns {
+   *    EventEmitter|!grpc.web.ClientReadableStream<!MasternodeListResponse>
+   * }
+   */
+  async function subscribeToMasternodeList(options = { }) {
+    // eslint-disable-next-line no-param-reassign
+    options = {
+      // Override global timeout option
+      // and timeout for this method by default
+      timeout: undefined,
+      ...options,
+    };
+
+    const request = new MasternodeListRequest();
+
+    return grpcTransport.request(
+      CorePromiseClient,
+      'subscribeToMasternodeList',
+      request,
+      options,
+    );
+  }
+
+  return subscribeToMasternodeList;
+}
+
+/**
+ * @typedef {object} subscribeToMasternodeListOptions
+ */
+
+module.exports = subscribeToMasternodeListFactory;