diff --git a/packages/js-dapi-client/.editorconfig b/packages/js-dapi-client/.editorconfig index 74fb9e0beeb..774df6a49de 100644 --- a/packages/js-dapi-client/.editorconfig +++ b/packages/js-dapi-client/.editorconfig @@ -7,3 +7,6 @@ charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true end_of_line = lf + +[*.{md,markdown}] +trim_trailing_whitespace = false diff --git a/packages/js-dapi-client/docs/_sidebar.md b/packages/js-dapi-client/docs/_sidebar.md index c73ac50f739..2d2059938e0 100644 --- a/packages/js-dapi-client/docs/_sidebar.md +++ b/packages/js-dapi-client/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) diff --git a/packages/js-dapi-client/docs/getting-started/quickstart.md b/packages/js-dapi-client/docs/getting-started/quickstart.md index d4e22595809..3b519430c78 100644 --- a/packages/js-dapi-client/docs/getting-started/quickstart.md +++ b/packages/js-dapi-client/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 : ``` +You can see an [example usage here](https://github.com/dashevo/js-dapi-client/blob/master/examples/web/web.usage.html) + ## Initialization ```js diff --git a/packages/js-dapi-client/docs/usage/application/DAPIClient.md b/packages/js-dapi-client/docs/usage/application/DAPIClient.md new file mode 100644 index 00000000000..9c1e7862567 --- /dev/null +++ b/packages/js-dapi-client/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`. + diff --git a/packages/js-dapi-client/docs/usage/application/applyStateTransition.md b/packages/js-dapi-client/docs/usage/application/applyStateTransition.md deleted file mode 100644 index ddfe56c8fcc..00000000000 --- a/packages/js-dapi-client/docs/usage/application/applyStateTransition.md +++ /dev/null @@ -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 - diff --git a/packages/js-dapi-client/docs/usage/application/core/broadcastTransaction.md b/packages/js-dapi-client/docs/usage/application/core/broadcastTransaction.md new file mode 100644 index 00000000000..683828c35a8 --- /dev/null +++ b/packages/js-dapi-client/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). diff --git a/packages/js-dapi-client/docs/usage/application/core/generateToAddress.md b/packages/js-dapi-client/docs/usage/application/core/generateToAddress.md new file mode 100644 index 00000000000..e3eb7fafcfc --- /dev/null +++ b/packages/js-dapi-client/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} - a set of generated blockhashes. diff --git a/packages/js-dapi-client/docs/usage/application/core/getBestBlockHash.md b/packages/js-dapi-client/docs/usage/application/core/getBestBlockHash.md new file mode 100644 index 00000000000..7527ad6ff6c --- /dev/null +++ b/packages/js-dapi-client/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} - The best block hash diff --git a/packages/js-dapi-client/docs/usage/application/core/getBlockByHash.md b/packages/js-dapi-client/docs/usage/application/core/getBlockByHash.md new file mode 100644 index 00000000000..a4362bab22b --- /dev/null +++ b/packages/js-dapi-client/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} - The specified bufferized block diff --git a/packages/js-dapi-client/docs/usage/application/core/getBlockByHeight.md b/packages/js-dapi-client/docs/usage/application/core/getBlockByHeight.md new file mode 100644 index 00000000000..20b6b437fd6 --- /dev/null +++ b/packages/js-dapi-client/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} - The specified bufferized block diff --git a/packages/js-dapi-client/docs/usage/application/core/getBlockHash.md b/packages/js-dapi-client/docs/usage/application/core/getBlockHash.md new file mode 100644 index 00000000000..1eb61e3dc5f --- /dev/null +++ b/packages/js-dapi-client/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} - the corresponding block hash diff --git a/packages/js-dapi-client/docs/usage/application/core/getMnListDiff.md b/packages/js-dapi-client/docs/usage/application/core/getMnListDiff.md new file mode 100644 index 00000000000..9c1ee698ab0 --- /dev/null +++ b/packages/js-dapi-client/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} - The Masternode List Diff of the specified period diff --git a/packages/js-dapi-client/docs/usage/application/core/getStatus.md b/packages/js-dapi-client/docs/usage/application/core/getStatus.md new file mode 100644 index 00000000000..8a3df443a2a --- /dev/null +++ b/packages/js-dapi-client/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} - 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' +} +**/ +``` diff --git a/packages/js-dapi-client/docs/usage/application/core/getTransaction.md b/packages/js-dapi-client/docs/usage/application/core/getTransaction.md new file mode 100644 index 00000000000..6a4d2ca19b7 --- /dev/null +++ b/packages/js-dapi-client/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} - The bufferized transaction diff --git a/packages/js-dapi-client/docs/usage/application/platform/broadcastStateTransition.md b/packages/js-dapi-client/docs/usage/application/platform/broadcastStateTransition.md new file mode 100644 index 00000000000..8bfcf1a77d2 --- /dev/null +++ b/packages/js-dapi-client/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 diff --git a/packages/js-dapi-client/docs/usage/payment/getBestBlockHash.md b/packages/js-dapi-client/docs/usage/payment/getBestBlockHash.md deleted file mode 100644 index 6b0b5842bcc..00000000000 --- a/packages/js-dapi-client/docs/usage/payment/getBestBlockHash.md +++ /dev/null @@ -1,10 +0,0 @@ -**Usage**: `async client.core.getBestBlockHash()` -**Description**: Returns block hash of chaintip - -Parameters: - -| parameters | type | required | Description | -|------------------------|--------------------|----------------| ------------------------------------------------------------------------------------------------ | - -Returns : Promise - diff --git a/packages/js-dapi-client/docs/usage/payment/getBlockHash.md b/packages/js-dapi-client/docs/usage/payment/getBlockHash.md deleted file mode 100644 index 8dc6fb590be..00000000000 --- a/packages/js-dapi-client/docs/usage/payment/getBlockHash.md +++ /dev/null @@ -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 - diff --git a/packages/js-dapi-client/docs/usage/payment/getUTXO.md b/packages/js-dapi-client/docs/usage/payment/getUTXO.md deleted file mode 100644 index 590beea6cb8..00000000000 --- a/packages/js-dapi-client/docs/usage/payment/getUTXO.md +++ /dev/null @@ -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 with pagination info and array of unspent outputs - diff --git a/packages/js-dapi-client/docs/usage/utils/getMnListDiff.md b/packages/js-dapi-client/docs/usage/utils/getMnListDiff.md deleted file mode 100644 index 0e4c6cc2086..00000000000 --- a/packages/js-dapi-client/docs/usage/utils/getMnListDiff.md +++ /dev/null @@ -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 - diff --git a/packages/js-dapi-client/docs/usage/utils/subscribeToTransactionsWithProofs.md b/packages/js-dapi-client/docs/usage/utils/subscribeToTransactionsWithProofs.md index cf91605ebf9..96602882b5d 100644 --- a/packages/js-dapi-client/docs/usage/utils/subscribeToTransactionsWithProofs.md +++ b/packages/js-dapi-client/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. diff --git a/packages/js-dapi-client/examples/web/web.usage.html b/packages/js-dapi-client/examples/web/web.usage.html new file mode 100644 index 00000000000..1ed73959f9c --- /dev/null +++ b/packages/js-dapi-client/examples/web/web.usage.html @@ -0,0 +1,19 @@ + + + + + Title + + + + + + + +