diff --git a/docs/dapi-client-js/overview.md b/docs/dapi-client-js/overview.md new file mode 100644 index 000000000..4d975cdf2 --- /dev/null +++ b/docs/dapi-client-js/overview.md @@ -0,0 +1,39 @@ +# Overview + +## DAPI-Client + +[![NPM Version](https://img.shields.io/npm/v/@dashevo/dapi-client)](https://www.npmjs.com/package/@dashevo/dapi-client) +[![Build Status](https://github.com/dashevo/js-dapi-client/actions/workflows/test_and_release.yml/badge.svg)](https://github.com/dashevo/js-dapi-client/actions/workflows/test_and_release.yml) +[![Release Date](https://img.shields.io/github/release-date/dashpay/platform)](https://github.com/dashpay/platform/releases/latest) +[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen)](https://github.com/RichardLitt/standard-readme) + +Client library used to access Dash DAPI endpoints + +This library enables HTTP-based interaction with the Dash blockchain and Dash Platform via the decentralized API ([DAPI](https://github.com/dashpay/platform/tree/master/packages/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/dashpay/platform/tree/master/packages/dapi/lib/rpcServer/commands) and [gRPC](https://github.com/dashpay/platform/tree/master/packages/dapi/lib/grpcServer/handlers) endpoints + +### Install + +### ES5/ES6 via NPM + +In order to use this library in Node, you will need to add it to your project as a dependency. + +Having [NodeJS](https://nodejs.org/) installed, just type in your terminal : + +```sh +npm install @dashevo/dapi-client +``` + +### CDN Standalone + +For browser usage, you can also directly rely on unpkg : + +``` + +``` + +## Licence + +[MIT](https://github.com/dashevo/dapi-client/blob/master/LICENCE.md) © Dash Core Group, Inc. \ No newline at end of file diff --git a/docs/dapi-client-js/quick-start.md b/docs/dapi-client-js/quick-start.md new file mode 100644 index 000000000..411e04d37 --- /dev/null +++ b/docs/dapi-client-js/quick-start.md @@ -0,0 +1,37 @@ +# Quick start + +## ES5/ES6 via NPM + +In order to use this library in Node, you will need to add it to your project as a dependency. + +Having [NodeJS](https://nodejs.org/) installed, just type in your terminal : + +```sh +npm install @dashevo/dapi-client +``` + +## CDN Standalone + +For browser usage, you can also directly rely on unpkg : + +``` + +``` + +You can see an [example usage here](https://github.com/dashpay/platform/blob/master/packages/js-dapi-client/examples/web/web.usage.html) . + +## Initialization + +```js +const DAPIClient = require('@dashevo/dapi-client'); +const client = new DAPIClient(); + +(async () => { + const bestBlockHash = await client.core.getBestBlockHash(); + console.log(bestBlockHash); +})(); +``` + +## Quicknotes + +This package allows you to fetch & send information from both the payment chain (layer 1) and the application chain (layer 2, a.k.a Platform chain). \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/broadcasttransaction.md b/docs/dapi-client-js/usage/core/broadcasttransaction.md new file mode 100644 index 000000000..49cabc979 --- /dev/null +++ b/docs/dapi-client-js/usage/core/broadcasttransaction.md @@ -0,0 +1,17 @@ +# broadcasttransaction + +**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). \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/core.md b/docs/dapi-client-js/usage/core/core.md new file mode 100644 index 000000000..bb7ffee96 --- /dev/null +++ b/docs/dapi-client-js/usage/core/core.md @@ -0,0 +1,18 @@ +# Core + +```{toctree} +:maxdepth: 2 +:titlesonly: + + +broadcasttransaction +generatetoaddress +getbestblockhash +getblockbyhash +getblockbyheight +getblockhash +getmnlistdiff +getstatus +gettransaction +subscribetotransactionswithproofs +``` diff --git a/docs/dapi-client-js/usage/core/generatetoaddress.md b/docs/dapi-client-js/usage/core/generatetoaddress.md new file mode 100644 index 000000000..5e94781d5 --- /dev/null +++ b/docs/dapi-client-js/usage/core/generatetoaddress.md @@ -0,0 +1,15 @@ +# generatetoaddress + +**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. \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getbestblockhash.md b/docs/dapi-client-js/usage/core/getbestblockhash.md new file mode 100644 index 000000000..7964a4203 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getbestblockhash.md @@ -0,0 +1,12 @@ +# getbestblockhash + +**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 \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getblockbyhash.md b/docs/dapi-client-js/usage/core/getblockbyhash.md new file mode 100644 index 000000000..949f1f329 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getblockbyhash.md @@ -0,0 +1,13 @@ +# getblockbyhash + +**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 \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getblockbyheight.md b/docs/dapi-client-js/usage/core/getblockbyheight.md new file mode 100644 index 000000000..f73d9ce8a --- /dev/null +++ b/docs/dapi-client-js/usage/core/getblockbyheight.md @@ -0,0 +1,13 @@ +# getblockbyheight + +**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 \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getblockhash.md b/docs/dapi-client-js/usage/core/getblockhash.md new file mode 100644 index 000000000..e9aa91d47 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getblockhash.md @@ -0,0 +1,13 @@ +# getblockhash + +**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 \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getmnlistdiff.md b/docs/dapi-client-js/usage/core/getmnlistdiff.md new file mode 100644 index 000000000..f6282e1e6 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getmnlistdiff.md @@ -0,0 +1,14 @@ +# getmnlistdiff + +**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 \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getstatus.md b/docs/dapi-client-js/usage/core/getstatus.md new file mode 100644 index 000000000..f7bd66bee --- /dev/null +++ b/docs/dapi-client-js/usage/core/getstatus.md @@ -0,0 +1,31 @@ +# getstatus + +**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' +} +**/ +``` \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/gettransaction.md b/docs/dapi-client-js/usage/core/gettransaction.md new file mode 100644 index 000000000..fea1ae92f --- /dev/null +++ b/docs/dapi-client-js/usage/core/gettransaction.md @@ -0,0 +1,13 @@ +# gettransaction + +**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 \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/subscribetotransactionswithproofs.md b/docs/dapi-client-js/usage/core/subscribetotransactionswithproofs.md new file mode 100644 index 000000000..09b300fb5 --- /dev/null +++ b/docs/dapi-client-js/usage/core/subscribetotransactionswithproofs.md @@ -0,0 +1,46 @@ +# subscribetotransactionswithproofs + +**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. + +Parameters: + +| parameters | type | required | Description | +| --------------------------- | ---------------- | --------------- | --------------------------------------------------------------------------------------------------------- | +| **bloomFilter.vData** | Uint8Array/Array | yes | The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes. | +| **bloomFilter.nHashFuncs** | Number | yes | The number of hash functions to use in this filter. The maximum value allowed in this field is 50. | +| **bloomFilter.nTweak** | Number | yes | A random value to add to the seed value in the hash function used by the bloom filter. | +| **bloomFilter.nFlags** | Number | yes | A set of flags that control how matched items are added to the filter. | +| **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|!grpc.web.ClientReadableStream\ + +Example : + +```js +const filter; // A BloomFilter object +const stream = await client.subscribeToTransactionsWithProofs(filter, { fromBlockHeight: 0 }); + +stream + .on('data', (response) => { + const merkleBlock = response.getRawMerkleBlock(); + const transactions = response.getRawTransactions(); + + if (merkleBlock) { + const merkleBlockHex = Buffer.from(merkleBlock).toString('hex'); + } + + 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)); + }); + } + }) + .on('error', (err) => { + // do something with err + }); +``` \ No newline at end of file diff --git a/docs/dapi-client-js/usage/dapiclient.md b/docs/dapi-client-js/usage/dapiclient.md new file mode 100644 index 000000000..ee576394d --- /dev/null +++ b/docs/dapi-client-js/usage/dapiclient.md @@ -0,0 +1,27 @@ +# DAPIClient + +**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 | 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' +}); +``` \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/broadcaststatetransition.md b/docs/dapi-client-js/usage/platform/broadcaststatetransition.md new file mode 100644 index 000000000..15667f37a --- /dev/null +++ b/docs/dapi-client-js/usage/platform/broadcaststatetransition.md @@ -0,0 +1,13 @@ +# broadcaststatetransition + +**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\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getdatacontract.md b/docs/dapi-client-js/usage/platform/getdatacontract.md new file mode 100644 index 000000000..c6c4ebd96 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getdatacontract.md @@ -0,0 +1,12 @@ +# getdatacontract + +**Usage**: `async client.platform.getDataContract(contractId)` +**Description**: Fetch Data Contract by id + +Parameters: + +| parameters | type | required | Description | +| -------------- | ------ | -------- | ----------------------------- | +| **contractId** | String | yes | A valid registered contractId | + +Returns : Promise \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getdocuments.md b/docs/dapi-client-js/usage/platform/getdocuments.md new file mode 100644 index 000000000..ff290de62 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getdocuments.md @@ -0,0 +1,18 @@ +# getdocuments + +**Usage**: `async client.platform.getDocuments(contractId, type, options)` +**Description**: Fetch Documents from Drive + +Parameters: + +| parameters | type | required | Description | +| ---------------------- | ------ | -------- | -------------------------------------------------- | +| **contractId** | String | yes | A valid registered contractId | +| **type** | String | yes | DAP object type to fetch (e.g: 'preorder' in DPNS) | +| **options.where** | Object | yes | Mongo-like query | +| **options.orderBy** | Object | yes | Mongo-like sort field | +| **options.limit** | Number | yes | Limit the number of object to fetch | +| **options.startAt** | Number | yes | number of objects to skip | +| **options.startAfter** | Number | yes | exclusive skip | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getidentity.md b/docs/dapi-client-js/usage/platform/getidentity.md new file mode 100644 index 000000000..fa6de9f78 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getidentity.md @@ -0,0 +1,12 @@ +# getidentity + +**Usage**: `async client.platform.getIdentity(id)` +**Description**: Fetch the identity by id + +Parameters: + +| parameters | type | required | Description | +| ---------- | ------ | -------- | --------------------------- | +| **id** | String | yes | A valid registered identity | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getidentitybyfirstpublickey.md b/docs/dapi-client-js/usage/platform/getidentitybyfirstpublickey.md new file mode 100644 index 000000000..646b3bc27 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getidentitybyfirstpublickey.md @@ -0,0 +1,12 @@ +# getidentitybyfirstpublickey + +**Usage**: `async client.platform.getIdentityByFirstPublicKey(publicKeyHash)` +**Description**: Fetch the identity using the public key hash of the identity's first key + +Parameters: + +| parameters | type | required | Description | +| ----------------- | ------ | -------- | ----------------------- | +| **publicKeyHash** | String | yes | A valid public key hash | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getidentityidbyfirstpublickey.md b/docs/dapi-client-js/usage/platform/getidentityidbyfirstpublickey.md new file mode 100644 index 000000000..814d11d37 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getidentityidbyfirstpublickey.md @@ -0,0 +1,12 @@ +# getidentityidbyfirstpublickey + +**Usage**: `async client.platform.getIdentityIdByFirstPublicKey(publicKeyHash)` +**Description**: Fetch the identity ID using the public key hash of the identity's first key + +Parameters: + +| parameters | type | required | Description | +| ----------------- | ------ | -------- | ----------------------- | +| **publicKeyHash** | String | yes | A valid public key hash | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/platform.md b/docs/dapi-client-js/usage/platform/platform.md new file mode 100644 index 000000000..f24015909 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/platform.md @@ -0,0 +1,14 @@ +# Platform + +```{toctree} +:maxdepth: 2 +:titlesonly: + + +broadcaststatetransition +getdatacontract +getdocuments +getidentity +getidentitybyfirstpublickey +getidentityidbyfirstpublickey +``` diff --git a/docs/dapi-client-js/usage/usage.md b/docs/dapi-client-js/usage/usage.md new file mode 100644 index 000000000..361a9a1e1 --- /dev/null +++ b/docs/dapi-client-js/usage/usage.md @@ -0,0 +1,10 @@ +# Usage + +```{toctree} +:maxdepth: 2 +:titlesonly: + +dapiclient +core/core +platform/platform +``` diff --git a/docs/index.md b/docs/index.md index c67ce0f47..4245443be 100644 --- a/docs/index.md +++ b/docs/index.md @@ -89,3 +89,14 @@ JavaScript SDK ``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: DAPI Client +:hidden: + +dapi-client-js/overview +dapi-client-js/quick-start +dapi-client-js/usage/usage +``` diff --git a/scripts/1-readme-rename.sh b/scripts/1-readme-rename.sh index b96500c48..2d0697590 100755 --- a/scripts/1-readme-rename.sh +++ b/scripts/1-readme-rename.sh @@ -2,6 +2,8 @@ RENAME_ARGS="-d" +find docs/dapi-client-js -iname "*.md" -type f -name 'dapi-client-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dapi-client-//' +find docs/dapi-client-js/usage -iname "*.md" -type f -name 'usage-*' -print0 | xargs -0 rename $RENAME_ARGS 's/usage-//' find docs/explanations -iname "*.md" -type f -name 'explanation-*' -print0 | xargs -0 rename $RENAME_ARGS 's/explanation-//' find docs/intro -iname "*.md" -type f -name 'introduction-*' -print0 | xargs -0 rename $RENAME_ARGS 's/introduction-//' find docs/intro -iname "*.md" -type f -name 'intro-*' -print0 | xargs -0 rename $RENAME_ARGS 's/intro-//'