@dashevo/dapi-client 0.21.6 → 0.22.0-dev.6

package/README.md

@@ -12,7 +12,7 @@ Platform via the decentralized API ([DAPI](https://github.com/dashevo/dapi))
 hosted on Dash masternodes.
 
  - `DAPI-Client` provides automatic server (masternode) discovery using either a default seed node or a user-supplied one
- - `DAPI-Client` maps to DAPI's [RPC](https://github.com/dashevo/dapi/tree/master/lib/rpcServer/commands) and [gRPC](https://github.com/dashevo/dapi/tree/master/lib/grpcServer/handlers) endpoints
+ - `DAPI-Client` maps to DAPI's [RPC](https://github.com/dashevo/platform/tree/master/packages/dapi/lib/rpcServer/commands) and [gRPC](https://github.com/dashevo/platform/tree/master/packages/dapi/lib/grpcServer/handlers) endpoints
 
 ## Table of Contents
 - [Install](#install)
@@ -101,12 +101,12 @@ client.core.getBestBlockHash(options).then((r) => {
 
 ## Documentation
 
-More extensive documentation available at https://dashevo.github.io/js-dapi-client/.
+More extensive documentation available at https://dashevo.github.io/platform/DAPI-Client/.
 
 
 ## Contributing
 
-Feel free to dive in! [Open an issue](https://github.com/dashevo/js-dapi-client/issues/new/choose) or submit PRs.
+Feel free to dive in! [Open an issue](https://github.com/dashevo/platform/issues/new/choose) or submit PRs.
 
 ## License
 

package/docs/_sidebar.md

@@ -1,18 +1,24 @@
 - Getting started
     - [Quick start](getting-started/quickstart.md)
 - Usage
-    - Application
-        - [`.applyStateTransition()`](usage/application/applyStateTransition.md)
-        - [`.getDataContract()`](usage/application/getDataContract.md)
-        - [`.getDocuments()`](usage/application/getDocuments.md)
-        - [`.getIdentity()`](usage/application/getIdentity.md)
-        - [`.getIdentityByFirstPublicKey()`](usage/application/getIdentityByFirstPublicKey.md)
-        - [`.getIdentityIdByFirstPublicKey()`](usage/application/getIdentityIdByFirstPublicKey.md)
-    - Payment
-        - [`.getBestBlockHash()`](usage/payment/getBestBlockHash.md)
-        - [`.getBlockHash()`](usage/payment/getBlockHash.md)
-        - [`.getUTXO()`](usage/payment/getUTXO.md)
-   - Utilities
-        - [`.getMnListDiff()`](usage/utils/getMnListDiff.md)
-        - [`.subscribeToTransactionsWithProofs()`](usage/utils/subscribeToTransactionsWithProofs.md)
+    - DAPIClient
+        - [new DAPIClient()](usage/application/DAPIClient.md)
+            - Core
+                - [.broadcastTransaction()](usage/application/core/broadcastTransaction.md)
+                - [.generateToAddress()](usage/application/core/generateToAddress.md)
+                - [.getBestBlockHash()](usage/application/core/getBestBlockHash.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)
+            - Platform 
+                - [.broadcastStateTransition()](usage/application/platform/broadcastStateTransition.md)
+                - [.getDataContract()](usage/application/platform/getDataContract.md)
+                - [.getDocuments()](usage/application/platform/getDocuments.md)
+                - [.getIdentityByFirstPublicKey()](usage/application/platform/getIdentityByFirstPublicKey.md)
+                - [.getIdentity()](usage/application/platform/getIdentity.md)
+                - [.getIdentityIdByFirstPublicKey()](usage/application/platform/getIdentityIdByFirstPublicKey.md)
 - [License](https://github.com/dashevo/dapi-client/blob/master/LICENSE)

package/docs/getting-started/quickstart.md

@@ -1,6 +1,6 @@
 # Quick start
 
-### ES5/ES6 via NPM
+## ES5/ES6 via NPM
 
 In order to use this library in Node, you will need to add it to your project as a dependency.
 
@@ -10,7 +10,7 @@ Having [NodeJS](https://nodejs.org/) installed, just type in your terminal :
 npm install @dashevo/dapi-client
 ```
 
-### CDN Standalone
+## CDN Standalone
 
 For browser usage, you can also directly rely on unpkg :
 
@@ -18,6 +18,8 @@ For browser usage, you can also directly rely on unpkg :
 <script src="https://unpkg.com/@dashevo/dapi-client"></script>
 ```
 
+You can see an [example usage here](https://github.com/dashevo/js-dapi-client/blob/master/examples/web/web.usage.html) 
+
 ## Initialization
 
 ```js

package/docs/usage/application/DAPIClient.md

@@ -0,0 +1,29 @@
+**Usage**: `new DAPIClient(options)`  
+**Description**: This method creates a new DAPIClient instance.
+
+Parameters:
+
+| parameters                                | type                | required[def value]         | Description                                                                                                                                                                    |
+|-------------------------------------------|---------------------|-----------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **options**                               | Object              |  |   |
+| **options.dapiAddressProvider**           | DAPIAddressProvider | no[ListDAPIAddressProvider] | Allow to override the default dapiAddressProvider (do not allow seeds or dapiAddresses params)  |
+| **options.seeds**                         | string[]            | no[seeds]                   | Allow to override default seeds (to connect to specific node) |
+| **options.network**                       | string|Network      | no[=evonet]                 | Allow to setup the network to be used (livenet, testnet, evonet,..) |
+| **options.timeout**                       | number              | no[=2000]                   | Used to specify the timeout time in milliseconds. |
+| **options.retries**                       | number              | no[=3]                      | Used to specify the number of retries before aborting and erroring a request. |
+| **options.baseBanTime**                   | number              | no[=6000]                   |  |
+
+Returns : DAPIClient instance.
+
+```js
+const DAPIClient = require('@dashevo/dapi-client');
+const client = new DAPIClient({
+  timeout: 5000,
+  retries: 3,
+  network: 'livenet'
+});
+```
+
+**Notes**: 
+- Accessing the SimplifiedMasternodeListDAPIAddressProvider (or its overwrote instance), can be accessed via `client.dapiAddressProvider`.  
+ 

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

@@ -0,0 +1,15 @@
+**Usage**: `await client.core.broadcastTransaction(transaction)`  
+**Description**: Allow to broadcast a valid **signed** transaction to the network.
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **transaction**           | Buffer              | yes            | A valid Buffer representation of a transaction                                                   |
+| **options**               | Object              |                |                                                  |
+| **options.allowHighFees** | Boolean             | no[=false]     | As safety measure, "absurd" fees are rejected when considered to high. This allow to overwrite that comportement |
+| **options.bypassLimits**  | Boolean             | no[=false]     | Allow to bypass default transaction policy rules limitation |
+
+Returns : transactionId (string).
+
+N.B : The TransactionID provided is subject to [transaction malleability](https://dashcore.readme.io/docs/core-guide-transactions-transaction-malleability), and is not a source of truth (the transaction might be included in a block with a different txid).

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

@@ -0,0 +1,13 @@
+**Usage**: `await client.core.generateToAddress(blockMumber, address, options)`  
+**Description**: Allow to broadcast a valid **signed** transaction to the network.
+**Notes**: Will only works on regtest.
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **blocksNumber**          | Number              | yes            | A number of block to see generated on the regtest network                                        |
+| **address**               | String              | yes            | The address that will receive the newly generated Dash                                           |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<string[]>} - a set of generated blockhashes.

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

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

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

@@ -0,0 +1,11 @@
+**Usage**: `await client.core.getBlockByHash(hash, options)`  
+**Description**: Allow to fetch a specific block by its hash
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **hash**                  | String              | yes            | A valid block hash |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<null|Buffer>} - The specified bufferized block

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

@@ -0,0 +1,11 @@
+**Usage**: `await client.core.getBlockByHeight(height, options)`  
+**Description**: Allow to fetch a specific block by its height
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **height**                | Number              | yes            | A valid block height |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<null|Buffer>} - The specified bufferized block

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

@@ -0,0 +1,11 @@
+**Usage**: `await client.core.getBlockHash(height, options)`  
+**Description**: Allow to fetch a specific block hash from  its height
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **height**                | Number              | yes            | A valid block height |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<null|string>} - the corresponding block hash

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

@@ -0,0 +1,12 @@
+**Usage**: `await client.core.getMnListDiff(baseBlockHash, blockHash, options)`  
+**Description**: Allow to fetch a specific block hash from  its height
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **baseBlockHash**         | String              | yes            |  hash or height of start block |
+| **blockHash**             | String              | yes            |  hash or height of end block |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<object>} - The Masternode List Diff of the specified period

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

@@ -0,0 +1,29 @@
+**Usage**: `await client.core.getStatus(options)`  
+**Description**: Allow to fetch a specific block hash from  its height
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<object>} - Status object
+
+```js
+const status = await client.core.getStatus()
+/**
+{
+  coreVersion: 150000,
+  protocolVersion: 70216,
+  blocks: 10630,
+  timeOffset: 0,
+  connections: 58,
+  proxy: '',
+  difficulty: 0.001745769130443678,
+  testnet: false,
+  relayFee: 0.00001,
+  errors: '',
+  network: 'testnet'
+}
+**/
+```

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

@@ -0,0 +1,11 @@
+**Usage**: `await client.core.getTransaction(id, options)`  
+**Description**: Allow to fetch a transaction by ID
+
+Parameters:
+
+| parameters                | type                | required       | Description                                                                                      |
+|---------------------------|---------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **id**                    | string              | yes            | A valid transaction id to fetch  |
+| **options**               | DAPIClientOptions   | no             |  |
+
+Returns : {Promise<null|Buffer>} - The bufferized transaction

package/docs/usage/application/platform/broadcastStateTransition.md

@@ -0,0 +1,11 @@
+**Usage**: `async client.platform.broadcastStateTransition(stateTransition, options)`
+**Description**: Send State Transition to machine
+
+Parameters:
+
+| parameters             | type              | required       | Description                                                                                      |
+|------------------------|-------------------|----------------| ------------------------------------------------------------------------------------------------ |
+| **stateTransition**    | Buffer            | yes            | A valid bufferized state transition |
+| **options**            | DAPIClientOptions | no             | A valid state transition |
+
+Returns : Promise<!BroadcastStateTransitionResponse>

package/docs/usage/utils/subscribeToTransactionsWithProofs.md

@@ -1,4 +1,4 @@
-**Usage**: `async client.core.subscribeToTransactionsWithProofs(bloomFilter, options = { count: 0 })`\
+**Usage**: `await client.core.subscribeToTransactionsWithProofs(bloomFilter, options = { count: 0 })`\
 **Description**: For any provided bloomfilter, it will return a ClientReadableStream streaming the transaction matching the filter.
 
 

package/lib/methods/core/CoreMethodsFacade.js

@@ -8,6 +8,7 @@ const getMnListDiffFactory = require('./getMnListDiffFactory');
 const getStatusFactory = require('./getStatusFactory');
 const getTransactionFactory = require('./getTransaction/getTransactionFactory');
 const subscribeToTransactionsWithProofsFactory = require('./subscribeToTransactionsWithProofsFactory');
+const subscribeToBlockHeadersWithChainLocksFactory = require('./subscribeToBlockHeadersWithChainLocksFactory');
 
 class CoreMethodsFacade {
   /**
@@ -27,6 +28,9 @@ class CoreMethodsFacade {
     this.subscribeToTransactionsWithProofs = subscribeToTransactionsWithProofsFactory(
       grpcTransport,
     );
+    this.subscribeToBlockHeadersWithChainLocks = subscribeToBlockHeadersWithChainLocksFactory(
+      grpcTransport,
+    );
   }
 }
 

package/lib/methods/core/subscribeToBlockHeadersWithChainLocksFactory.js

@@ -0,0 +1,69 @@
+const {
+  v0: {
+    BlockHeadersWithChainLocksRequest,
+    CorePromiseClient,
+  },
+} = require('@dashevo/dapi-grpc');
+
+const DAPIClientError = require('../../errors/DAPIClientError');
+
+/**
+ * @param {GrpcTransport} grpcTransport
+ * @returns {subscribeToBlockHeadersWithChainLocks}
+ */
+function subscribeToBlockHeadersWithChainLocksFactory(grpcTransport) {
+  /**
+   * @typedef {subscribeToBlockHeadersWithChainLocks}
+   * @param {DAPIClientOptions & subscribeToBlockHeadersWithChainLocksOptions} [options]
+   * @returns {
+   *    EventEmitter|!grpc.web.ClientReadableStream<!BlockHeadersWithChainLocksResponse>
+   * }
+   */
+  async function subscribeToBlockHeadersWithChainLocks(options = { }) {
+    // eslint-disable-next-line no-param-reassign
+    options = {
+      count: 0,
+      // Override global timeout option
+      // and timeout for this method by default
+      timeout: undefined,
+      ...options,
+    };
+
+    if (options.fromBlockHeight === 0) {
+      throw new DAPIClientError('Invalid argument: minimum value for `fromBlockHeight` is 1');
+    }
+
+    const request = new BlockHeadersWithChainLocksRequest();
+
+    if (options.fromBlockHeight !== undefined) {
+      request.setFromBlockHeight(options.fromBlockHeight);
+    }
+
+    if (options.fromBlockHash) {
+      request.setFromBlockHash(
+        Buffer.from(options.fromBlockHash, 'hex'),
+      );
+    }
+
+    request.setCount(options.count);
+
+    return grpcTransport.request(
+      CorePromiseClient,
+      'subscribeToBlockHeadersWithChainLocks',
+      request,
+      options,
+    );
+  }
+
+  return subscribeToBlockHeadersWithChainLocks;
+}
+
+/**
+ * @typedef {object} subscribeToBlockHeadersWithChainLocksOptions
+ * @property {string} [fromBlockHash] - Specifies block hash to start syncing from
+ * @property {number} [fromBlockHeight] - Specifies block height to start syncing from
+ * @property {number} [count=0] - Number of blocks to sync,
+ *                                if set to 0 syncing is continuously sends new data as well
+ */
+
+module.exports = subscribeToBlockHeadersWithChainLocksFactory;

package/lib/methods/platform/getIdentitiesByPublicKeyHashes/GetIdentitiesByPublicKeyHashesResponse.js

@@ -1,3 +1,5 @@
+const cbor = require('cbor');
+
 const AbstractResponse = require('../response/AbstractResponse');
 
 class GetIdentitiesByPublicKeyHashesResponse extends AbstractResponse {
@@ -13,7 +15,7 @@ class GetIdentitiesByPublicKeyHashesResponse extends AbstractResponse {
   }
 
   /**
-   * @returns {Buffer[]}
+   * @returns {Array<Buffer[]>}
    */
   getIdentities() {
     return this.identities;
@@ -27,8 +29,13 @@ class GetIdentitiesByPublicKeyHashesResponse extends AbstractResponse {
     const { metadata, proof } = AbstractResponse.createMetadataAndProofFromProto(proto);
 
     return new GetIdentitiesByPublicKeyHashesResponse(
-      proto.getIdentitiesList()
-        .map((identity) => (identity.length > 0 ? Buffer.from(identity) : null)),
+      proto.getIdentitiesList().map((identitiesSerialized) => {
+        const identities = cbor.decode(identitiesSerialized);
+
+        return identities.map((identity) => (
+          (identity.length > 0 ? Buffer.from(identity) : null)
+        ));
+      }),
       metadata,
       proof,
     );

package/lib/methods/platform/getIdentityIdsByPublicKeyHashes/GetIdentityIdsByPublicKeyHashesResponse.js

@@ -1,3 +1,5 @@
+const cbor = require('cbor');
+
 const AbstractResponse = require('../response/AbstractResponse');
 
 class GetIdentityIdsByPublicKeyHashesResponse extends AbstractResponse {
@@ -13,7 +15,7 @@ class GetIdentityIdsByPublicKeyHashesResponse extends AbstractResponse {
   }
 
   /**
-   * @returns {Buffer[]}
+   * @returns {Array<Buffer[]>}
    */
   getIdentityIds() {
     return this.identityIds;
@@ -27,8 +29,13 @@ class GetIdentityIdsByPublicKeyHashesResponse extends AbstractResponse {
     const { metadata, proof } = AbstractResponse.createMetadataAndProofFromProto(proto);
 
     return new GetIdentityIdsByPublicKeyHashesResponse(
-      proto.getIdentityIdsList()
-        .map((identityId) => (identityId.length > 0 ? Buffer.from(identityId) : null)),
+      proto.getIdentityIdsList().map((identityIdsSerialized) => {
+        const identityIds = cbor.decode(identityIdsSerialized);
+
+        return identityIds.map((identityId) => (
+          (identityId.length > 0 ? Buffer.from(identityId) : null)
+        ));
+      }),
       metadata,
       proof,
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dashevo/dapi-client",
-  "version": "0.21.6",
+  "version": "0.22.0-dev.6",
   "description": "Client library used to access Dash DAPI endpoints",
   "main": "lib/DAPIClient.js",
   "contributors": [
@@ -26,10 +26,10 @@
     }
   ],
   "dependencies": {
-    "@dashevo/dapi-grpc": "~0.21.6",
+    "@dashevo/dapi-grpc": "~0.22.0-dev.6",
     "@dashevo/dashcore-lib": "~0.19.28",
-    "@dashevo/dpp": "~0.21.6",
-    "@dashevo/grpc-common": "~0.21.6",
+    "@dashevo/dpp": "~0.22.0-dev.6",
+    "@dashevo/grpc-common": "~0.22.0-dev.6",
     "@grpc/grpc-js": "^1.3.7",
     "axios": "^0.21.1",
     "bs58": "^4.0.1",

package/docs/usage/application/applyStateTransition.md

@@ -1,11 +0,0 @@
-**Usage**: `async client.platform.applyStateTransition(stateTransition)`
-**Description**: Send State Transition to machine
-
-Parameters:
-
-| parameters             | type                                                 | required       | Description                                                                                             |
-|------------------------|------------------------------------------------------|----------------| ------------------------------------------------------------------------------------------------ |
-| **stateTransition**    | DataContractStateTransition/DocumentsStateTransition | yes            | A valid state transition |
-
-Returns : Promise<!ApplyStateTransitionResponse>
-

package/docs/usage/payment/getBestBlockHash.md

@@ -1,10 +0,0 @@
-**Usage**: `async client.core.getBestBlockHash()`
-**Description**: Returns block hash of chaintip
-
-Parameters:
-
-| parameters             | type               | required       | Description                                                                                             |
-|------------------------|--------------------|----------------| ------------------------------------------------------------------------------------------------ |
-
-Returns : Promise<string>
-

package/docs/usage/payment/getBlockHash.md

@@ -1,11 +0,0 @@
-**Usage**: `client.core.getBlockHash(height)`
-**Description**: Returns block hash for the given height
-
-Parameters:
-
-| parameters             | type               | required       | Description                                                                                             |
-|------------------------|--------------------|----------------| ------------------------------------------------------------------------------------------------ |
-| **height**             | Number             | yes            | Any valid height value |
-
-Returns : Promise<string>
-

package/docs/usage/payment/getUTXO.md

@@ -1,15 +0,0 @@
-**Usage**: `async client.core.getUTXO(address, from, to, fromHeight, toHeight)`
-**Description**: Returns UTXO for a given address or multiple addresses (max result 1000)
-
-Parameters:
-
-| parameters             | type               | required       | Description                                                                                             |
-|------------------------|--------------------|----------------| ------------------------------------------------------------------------------------------------ |
-| **address**            | String/[String]    | yes            | address or array of addresses |
-| **from**               | Number             | no             | start of range in the ordered list of latest UTXO |
-| **to**                 | Number             | no             | end of range in the ordered list of latest UTXO |
-| **fromHeight**         | Number             | no             | which height to start from (optional, overriding from/to) |
-| **toHeight**           | Number             | no             | on which height to end (optional, overriding from/to) |
-
-Returns : Promise<object> - Object with pagination info and array of unspent outputs
-

package/docs/usage/utils/getMnListDiff.md

@@ -1,12 +0,0 @@
-**Usage**: `async client.core.getMnListDiff(baseBlockHash, blockHash)`
-**Description**: Get deterministic masternodelist diff
-
-Parameters:
-
-| parameters             | type   | required       | Description                                                                                             |
-|------------------------|--------|----------------| ------------------------------------------------------------------------------------------------ |
-| **baseBlockHash**      | String | yes            | Hash or height of start block |
-| **blockHash**          | String | yes            | Hash or height of end block |
-
-Returns : Promise<object>
-