From 713fcb1f1f7d38aa5ad51230027368654a2261cc Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 18 Sep 2024 16:36:58 -0400 Subject: [PATCH 1/7] docs(ref): add getEvonodesProposedEpochBlocksByIds endpoint --- .../dapi-endpoints-platform-endpoints.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index c87497a7f..b6da77521 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -344,6 +344,70 @@ Retrieves the state of a vote for a specific contested resource. ::: :::: +### getEvonodesProposedEpochBlocksByIds + +Retrieves the proposed blocks from evonodes for a specified epoch, based on their IDs. + +**Returns**: A list of evonodes and their proposed block counts or a cryptographic proof. + +**Parameters**: + +| Name | Type | Required | Description | +| ------------------ | -------- | -------- | ----------- | +| `epoch` | Integer | No | The epoch to query for. If not set, the current epoch will be used. | +| `ids` | Array of bytes | Yes | List of evonode IDs for which proposed blocks are retrieved. | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested data. | + +**Example Request and Response** + +::::{tab-set} +:::{tab-item} gRPCurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "ids": [ + "jspLy7OhJKsoOv1C2tO9sgd7OAlll4ig8dr/zlufAB8=","dUuJ2ujbIPxM7l462wexRtfv5Qimb6Co4QlGdbnao14=" + ], + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getEvonodesProposedEpochBlocksByIds +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +```json +{ + "v0": { + "evonodesProposedBlockCountsInfo": { + "evonodesProposedBlockCounts": [ + { + "proTxHash": "dUuJ2ujbIPxM7l462wexRtfv5Qimb6Co4QlGdbnao14=" + }, + { + "proTxHash": "jspLy7OhJKsoOv1C2tO9sgd7OAlll4ig8dr/zlufAB8=", + "count": "13" + } + ] + }, + "metadata": { + "height": "13621", + "coreChainLockedHeight": 1105397, + "epoch": 1482, + "timeMs": "1726691577244", + "protocolVersion": 3, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: + ### getIdentity **Returns**: [Identity](../explanations/identity.md) information for the requested identity From 58ba508c385f3926a3c596c31df771fd9f4c512f Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 18 Sep 2024 16:37:14 -0400 Subject: [PATCH 2/7] docs(ref): update info about mn identities --- docs/reference/dapi-endpoints-platform-endpoints.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index b6da77521..5e39f9420 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -36,7 +36,9 @@ by the system based on the [Core masternode registration transaction (protx) hash](inv:core:std#ref-txs-proregtx). Masternode identity IDs are created by converting the protx hash to base58. This can be done using an [online base58 encoder](https://appdevtools.com/base58-encoder-decoder) or through JavaScript using the [bs58 -package](https://www.npmjs.com/package/bs58) as shown below. +package](https://www.npmjs.com/package/bs58) as shown below. For gRPCurl, convert the protx hash to +base64 instead. This can be done using an [online hex to base64 +encoder](https://base64.guru/converter/encode/hex). ```{eval-rst} .. _reference-dapi-endpoints-platform-grpc-protx-to-id: @@ -47,11 +49,14 @@ package](https://www.npmjs.com/package/bs58) as shown below. const bs58 = require('bs58').default; -const protx = 'b09cfb1d82a643408818d4a02f491a7ed2dc66f074618706221f2f49f2bae0de'; +const protx = '8eca4bcbb3a124ab283afd42dad3bdb2077b3809659788a0f1daffce5b9f001f'; const base58Protx = bs58.encode(Buffer.from(protx, 'hex')); console.log(`Masternode identity id (base58): ${base58Protx}`); +const base64Protx = Buffer.from(protx, 'hex').toString('base64'); +console.log(`Masternode identity id (base58): ${base64Protx}`); // Output: -// Masternode identity id (base58): CtRbCAi9R5hhC9VdsgxtRMw7MSVrBCZNEELdkTxpy5Kj +// Masternode identity id (base58): AcPogCxrxeas7jrWYG7TnLHKbsA5KLHGfvg6oYgANZ8J +// Masternode identity id (base64): jspLy7OhJKsoOv1C2tO9sgd7OAlll4ig8dr/zlufAB8= ::: ## Endpoint Details From 6dc6bd48f2e28953ed273fb801ea05f312bc7cd4 Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 18 Sep 2024 16:41:06 -0400 Subject: [PATCH 3/7] docs(ref): updates for getEvonodesProposedEpochBlocksByIds --- docs/reference/dapi-endpoints-platform-endpoints.md | 2 +- docs/reference/dapi-endpoints.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index 5e39f9420..cff9f22d7 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -351,7 +351,7 @@ Retrieves the state of a vote for a specific contested resource. ### getEvonodesProposedEpochBlocksByIds -Retrieves the proposed blocks from evonodes for a specified epoch, based on their IDs. +Retrieves the number of blocks proposed by the specified evonodes in a certain epoch, based on their IDs. **Returns**: A list of evonodes and their proposed block counts or a cryptographic proof. diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index 65f1e8761..ecb48eed2 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -46,6 +46,7 @@ data returned is valid and complete. The endpoints are versioned so updates can | 2 | [`getContestedResourceIdentityVotes`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourceidentityvotes) | **Added in Dash Platform v1.0.0**
Retrieves the voting record of a specific identity. | | 2 | [`getContestedResourceVotersForIdentity`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourcevotersforidentity) | **Added in Dash Platform v1.0.0**
Retrieves the voters for a specific identity associated with a contested resource. | | 2 | [`getContestedResourceVoteState`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourcevotestate) | **Added in Dash Platform v1.0.0**
Retrieves the state of a vote for a specific contested resource. | +| 2 | [`getEvonodesProposedEpochBlocksByIds`](../reference/dapi-endpoints-platform-endpoints.md#getevonodesproposedepochblocksbyids) | **Added in Dash Platform v1.3.0**
Retrieves the number of blocks proposed by the specified evonodes in a certain epoch, based on their IDs. | | 2 | [`getIdentity`](../reference/dapi-endpoints-platform-endpoints.md#getidentity) | Returns the requested identity | | 2 | [`getIdentityBalance`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybalance) | Returns the requested identity's balance | | 2 | [`getIdentityBalanceAndRevision`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybalanceandrevision) | Returns the requested identity's balance and revision | From 4ffa31e7a917ca51f9a15ecc595b2ca00e9bb730 Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 18 Sep 2024 16:42:29 -0400 Subject: [PATCH 4/7] docs: add prompt and exclude from build --- conf.py | 12 +++++++- docs/ai-prompt.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/ai-prompt.md diff --git a/conf.py b/conf.py index 933b219e4..26ffc5759 100644 --- a/conf.py +++ b/conf.py @@ -33,7 +33,17 @@ ] templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', '.devcontainer', 'scripts', 'img/dev/gifs/README.md', 'docs/other'] +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + 'README.md', + '.devcontainer', + 'scripts', + 'img/dev/gifs/README.md', + 'docs/other', + 'docs/ai-prompt.md' +] # The master toctree document. master_doc = 'index' diff --git a/docs/ai-prompt.md b/docs/ai-prompt.md new file mode 100644 index 000000000..27f4e9bb9 --- /dev/null +++ b/docs/ai-prompt.md @@ -0,0 +1,70 @@ +# Create documentation for a new endpoint + +Use this endpoint documentation as a template to create documentation for new platform endpoints: + +``` +### getVotePollsByEndDate + +Retrieves vote polls that will end within a specified date range. + +**Returns**: A list of vote polls or a cryptographic proof. + +**Parameters**: + +| Name | Type | Required | Description | +| ------------------ | -------- | -------- | ----------- | +| `start_time_info` | Object | No | Start time information for filtering vote polls | +| `end_time_info` | Object | No | End time information for filtering vote polls | +| `limit` | Integer | No | Maximum number of results to return | +| `offset` | Integer | No | Offset for pagination | +| `ascending` | Boolean | No | Sort order for results | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested vote polls | + +**Example Request and Response** + +::::{tab-set} +:::{tab-item} gRPCurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "start_time_info": {"start_time_ms": "1701980000000", "start_time_included": true}, + "end_time_info": {"end_time_ms": "1702000000000", "end_time_included": true}, + "limit": 10 + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getVotePollsByEndDate +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +```json +{ + "v0": { + "votePollsByTimestamps": { + "finishedResults": true + }, + "metadata": { + "height": "2876", + "coreChainLockedHeight": 1086885, + "epoch": 761, + "timeMs": "1724094056585", + "protocolVersion": 1, + "chainId": "dash-testnet-50" + } + } +} +``` +::: +:::: +``` + + +Create documentation for the following new endpoint using the style of previously provided endpoint documentation as a template: + +``` +INSERT DETAILS FROM THE .proto FILE HERE +``` From 8e41e19884a2a4ff382779d10a6f46ccf64124bd Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 19 Sep 2024 10:01:17 -0400 Subject: [PATCH 5/7] docs(ref): add getEvonodesProposedEpochBlocksByRange --- .../dapi-endpoints-platform-endpoints.md | 68 ++++++++++++++++++- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index cff9f22d7..4afb7ff8a 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -359,9 +359,9 @@ Retrieves the number of blocks proposed by the specified evonodes in a certain e | Name | Type | Required | Description | | ------------------ | -------- | -------- | ----------- | -| `epoch` | Integer | No | The epoch to query for. If not set, the current epoch will be used. | -| `ids` | Array of bytes | Yes | List of evonode IDs for which proposed blocks are retrieved. | -| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested data. | +| `epoch` | Integer | No | The epoch to query for. If not set, the current epoch will be used | +| `ids` | Array of bytes | Yes | List of evonode IDs for which proposed blocks are retrieved | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested data | **Example Request and Response** @@ -413,6 +413,68 @@ grpcurl -proto protos/platform/v0/platform.proto \ ::: :::: +### getEvonodesProposedEpochBlocksByRange + +Retrieves the number of blocks proposed by evonodes for a specified epoch. + +**Returns**: A list of evonodes and their proposed block counts or a cryptographic proof. + +**Parameters**: + +| Name | Type | Required | Description | +| ------------------ | -------- | -------- | ----------- | +| `epoch` | Integer | No | The epoch to query for. If not set, the current epoch will be used | +| `limit` | Integer | No | Maximum number of evonodes proposed epoch blocks to return | +| `start_after` | Bytes | No | Retrieve results starting after this document | +| `start_at` | Bytes | No | Retrieve results starting at this document | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested data | + +**Example Request and Response** + +::::{tab-set} +:::{tab-item} gRPCurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "epoch": 0, + "limit": 10, + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getEvonodesProposedEpochBlocksByRange +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +```json +{ + "v0": { + "evonodesProposedBlockCountsInfo": { + "evonodesProposedBlockCounts": [ + { + "proTxHash": "BbaHl4NE+iQzsqqZ1B9kPi2FgaeJzcIwhIic7KUkTqg=", + "count": "1" + } + ] + }, + "metadata": { + "height": "20263", + "coreChainLockedHeight": 1105827, + "epoch": 1499, + "timeMs": "1726752270072", + "protocolVersion": 3, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: + ### getIdentity **Returns**: [Identity](../explanations/identity.md) information for the requested identity From 58c96a00659ed7e6b3a6e03039ad71e98fdc3c6f Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 19 Sep 2024 10:49:16 -0400 Subject: [PATCH 6/7] docs(ref): update endpoint list --- docs/reference/dapi-endpoints.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index ecb48eed2..c6f5ab688 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -24,14 +24,14 @@ streaming of events related to blocks and transactions/transitions. | Layer | Endpoint | | | :---: | -------- | - | | 1 | [`broadcastTransaction`](../reference/dapi-endpoints-core-grpc-endpoints.md#broadcasttransaction) | Broadcasts the provided transaction | -| 1 | [`getBestBlockHeight`](../reference/dapi-endpoints-core-grpc-endpoints.md#getbestblockheight) | Return the best block height
**Added in Dash Platform v1.0.0**| +| 1 | [`getBestBlockHeight`](../reference/dapi-endpoints-core-grpc-endpoints.md#getbestblockheight) | *Added in Dash Platform v1.0.0*
Return the best block height| | 1 | [`getBlock`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblock) | **Disabled in Dash Platform v1.0.0**
Returns information for the requested block | -| 1 | [`getBlockchainStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblockchainstatus) | Returns blockchain status information
**Added in Dash Platform v1.0.0** | +| 1 | [`getBlockchainStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblockchainstatus) | *Added in Dash Platform v1.0.0*
Returns blockchain status information | | 1 | [`getMasternodeStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getmasternodestatus) | **Disabled in Dash Platform v1.0.0**
Returns masternode status information | | 1 | `getStatus` | **Deprecated in Dash Platform v1.0.0**
Split into [`getBlockchainStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblockchainstatus) and [`getMasternodeStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getmasternodestatus).
Returns blockchain status information | | 1 | [`getTransaction`](../reference/dapi-endpoints-core-grpc-endpoints.md#gettransaction) | Returns details for the requested transaction | | 1 | [`subscribeTo` `BlockHeadersWithChainLocks`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetoblockheaderswithchainlocks) | Returns the requested block headers along with the associated ChainLocks. | -| 1 | [`subscribeToMasternodeList`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetomasternodelist) | Returns the full masternode list from the genesis block to the chain tip as the first message and provides update messages with every new block
**Added in Dash Platform v1.0.0** | +| 1 | [`subscribeToMasternodeList`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetomasternodelist) | *Added in Dash Platform v1.0.0*
Returns the full masternode list from the genesis block to the chain tip as the first message and provides update messages with every new block | | 1 | [`subscribeTo` `TransactionsWithProofs`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetotransactionswithproofs) | Returns transactions matching the provided bloom filter along with the associated [`islock` message](https://docs.dash.org/projects/core/en/stable/docs/reference/p2p-network-instantsend-messages.html#islock) and [merkle block](https://docs.dash.org/projects/core/en/stable/docs/reference/p2p-network-data-messages.html#merkleblock) | ### Platform gRPC Service @@ -42,11 +42,12 @@ data returned is valid and complete. The endpoints are versioned so updates can | Layer | Endpoint | | | :---: | -------- | - | | 2 | [`broadcastStateTransition`](../reference/dapi-endpoints-platform-endpoints.md#broadcaststatetransition) | Broadcasts the provided State Transition | -| 2 | [`getContestedResources`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresources) | **Added in Dash Platform v1.0.0**
Retrieves the contested resources for a specific contract, document type, and index. | -| 2 | [`getContestedResourceIdentityVotes`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourceidentityvotes) | **Added in Dash Platform v1.0.0**
Retrieves the voting record of a specific identity. | -| 2 | [`getContestedResourceVotersForIdentity`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourcevotersforidentity) | **Added in Dash Platform v1.0.0**
Retrieves the voters for a specific identity associated with a contested resource. | -| 2 | [`getContestedResourceVoteState`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourcevotestate) | **Added in Dash Platform v1.0.0**
Retrieves the state of a vote for a specific contested resource. | -| 2 | [`getEvonodesProposedEpochBlocksByIds`](../reference/dapi-endpoints-platform-endpoints.md#getevonodesproposedepochblocksbyids) | **Added in Dash Platform v1.3.0**
Retrieves the number of blocks proposed by the specified evonodes in a certain epoch, based on their IDs. | +| 2 | [`getContestedResources`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresources) | *Added in Dash Platform v1.0.0*
Retrieves the contested resources for a specific contract, document type, and index. | +| 2 | [`getContestedResourceIdentityVotes`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourceidentityvotes) | *Added in Dash Platform v1.0.0*
Retrieves the voting record of a specific identity. | +| 2 | [`getContestedResourceVotersForIdentity`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourcevotersforidentity) | *Added in Dash Platform v1.0.0*
Retrieves the voters for a specific identity associated with a contested resource. | +| 2 | [`getContestedResourceVoteState`](../reference/dapi-endpoints-platform-endpoints.md#getcontestedresourcevotestate) | *Added in Dash Platform v1.0.0*
Retrieves the state of a vote for a specific contested resource. | +| 2 | [`getEvonodesProposedEpochBlocksByIds`](../reference/dapi-endpoints-platform-endpoints.md#getevonodesproposedepochblocksbyids) | **Added in Dash Platform v1.3.0**
Retrieves the number of blocks proposed by the specified evonodes in a certain epoch, based on their IDs | +| 2 | [`getEvonodesProposedEpochBlocksByRange`](../reference/dapi-endpoints-platform-endpoints.md#getevonodesproposedepochblocksbyrange) | **Added in Dash Platform v1.3.0**
Retrieves the number of blocks proposed by evonodes for a specified epoch | | 2 | [`getIdentity`](../reference/dapi-endpoints-platform-endpoints.md#getidentity) | Returns the requested identity | | 2 | [`getIdentityBalance`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybalance) | Returns the requested identity's balance | | 2 | [`getIdentityBalanceAndRevision`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybalanceandrevision) | Returns the requested identity's balance and revision | @@ -55,15 +56,15 @@ data returned is valid and complete. The endpoints are versioned so updates can | 2 | [`getIdentityKeys`](../reference/dapi-endpoints-platform-endpoints.md#getidentitykeys) | Returns the requested identity keys | 2 | [`getIdentityNonce`](../reference/dapi-endpoints-platform-endpoints.md#getidentitynonce) | Returns the current identity nonce | | 2 | `getIdentities` | **Removed in Dash Platform v1.0.0**
Returns the requested identities | -| 2 | [`getIdentitiesContractKeys`](../reference/dapi-endpoints-platform-endpoints.md#getidentitiescontractkeys) | **Added in Dash Platform v1.0.0**
Returns keys associated to a specific contract for multiple Identities | +| 2 | [`getIdentitiesContractKeys`](../reference/dapi-endpoints-platform-endpoints.md#getidentitiescontractkeys) | *Added in Dash Platform v1.0.0*
Returns keys associated to a specific contract for multiple Identities | | 2 | `getIdentitiesByPublicKeyHashes` | **Removed in Dash Platform v1.0.0**
Returns the identities associated with the provided public key hashes | | 2 | [`getDataContract`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontract) | Returns the requested data contract | | 2 | [`getDataContracts`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontracts) | Returns the requested data contracts | | 2 | [`getDataContractHistory`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontracthistory) | Returns the requested data contract history | | 2 | [`getDocuments`](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) | Returns the requested document(s) | | 2 | [`getEpochsInfo`](../reference/dapi-endpoints-platform-endpoints.md#getepochsinfo) | Returns information about the requested epoch(s) -| 2 | [`getPathElements`](../reference/dapi-endpoints-platform-endpoints.md#getpathelements) | **Added in Dash Platform v1.0.0**
Returns elements for a specified path in the Platform | -| 2 | [`getPrefundedSpecializedBalance`](../reference/dapi-endpoints-platform-endpoints.md#getprefundedspecializedbalance) | **Added in Dash Platform v1.0.0**
Returns the pre-funded specialized balance for a specific identity | +| 2 | [`getPathElements`](../reference/dapi-endpoints-platform-endpoints.md#getpathelements) | *Added in Dash Platform v1.0.0*
Returns elements for a specified path in the Platform | +| 2 | [`getPrefundedSpecializedBalance`](../reference/dapi-endpoints-platform-endpoints.md#getprefundedspecializedbalance) | *Added in Dash Platform v1.0.0*
Returns the pre-funded specialized balance for a specific identity | | 2 | `getProofs` | **Disabled for external use in Dash Platform v1.0.0**
Returns proof information for the requested identities, contracts, and/or document(s) | | 2 | [`getProtocolVersionUpgradeState`](../reference/dapi-endpoints-platform-endpoints.md#getprotocolversionupgradestate) | Returns the number of votes cast for each protocol version | 2 | [`getProtocolVersionUpgradeVoteStatus`](../reference/dapi-endpoints-platform-endpoints.md#getprotocolversionupgradevotestatus) | Returns protocol version upgrade status | From 30dcdac81f2ae5a685046ce9cdf3f08399e0fc8d Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 19 Sep 2024 11:24:51 -0400 Subject: [PATCH 7/7] docs(ref): add getIdentitiesBalances --- .../dapi-endpoints-platform-endpoints.md | 68 ++++++++++++++++++- docs/reference/dapi-endpoints.md | 1 + 2 files changed, 67 insertions(+), 2 deletions(-) diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index 4afb7ff8a..d587b3c21 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -360,7 +360,7 @@ Retrieves the number of blocks proposed by the specified evonodes in a certain e | Name | Type | Required | Description | | ------------------ | -------- | -------- | ----------- | | `epoch` | Integer | No | The epoch to query for. If not set, the current epoch will be used | -| `ids` | Array of bytes | Yes | List of evonode IDs for which proposed blocks are retrieved | +| `ids` | Array | Yes | An array of evonode IDs for which proposed blocks are retrieved IDs
Note: masternode IDs are created uniquely as described in the [masternode identity IDs section](#masternode-identity-ids) | | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested data | **Example Request and Response** @@ -1094,6 +1094,70 @@ Current identity nonce: 0 ::: :::: +### getIdentitiesBalances + +Retrieves the balances for a list of identities. + +**Returns**: A list of identities with their corresponding balances or a cryptographic proof. + +**Parameters**: + +| Name | Type | Required | Description | +|-----------|---------|----------|----------------------------------------------------------| +| `ids` | Array | No | An array of identity IDs for which balances are requested
Note: masternode IDs are created uniquely as described in the [masternode identity IDs section](#masternode-identity-ids) | +| `prove` | Boolean | No | Set to `true` to receive a proof containing the requested balances | + +**Example Request and Response** + +::::{tab-set} +:::{tab-item} gRPCurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "ids": [ + "jspLy7OhJKsoOv1C2tO9sgd7OAlll4ig8dr/zlufAB8=","dUuJ2ujbIPxM7l462wexRtfv5Qimb6Co4QlGdbnao14=" + ], + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getIdentitiesBalances +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +```json +{ + "v0": { + "identitiesBalances": { + "entries": [ + { + "identity_id": "jspLy7OhJKsoOv1C2tO9sgd7OAlll4ig8dr/zlufAB8=", + "balance": 1000000 + }, + { + "identity_id": "dUuJ2ujbIPxM7l462wexRtfv5Qimb6Co4QlGdbnao14=", + "balance": 2500000 + } + ] + }, + "metadata": { + "height": "13621", + "coreChainLockedHeight": 1105397, + "epoch": 1482, + "timeMs": "1726691577244", + "protocolVersion": 3, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: + ### getIdentitiesContractKeys **Returns**: Keys associated to a specific contract for multiple [Identities](../explanations/identity.md). @@ -1102,7 +1166,7 @@ Current identity nonce: 0 | Name | Type | Required | Description | |----------------------|-------------------------|----------|-------------| -| `identities_ids` | Array of Strings | Yes | An array of identity IDs
Note: masternode IDs are created uniquely as described in the [masternode identity IDs section](#masternode-identity-ids) | +| `identities_ids` | Array | Yes | An array of identity IDs
Note: masternode IDs are created uniquely as described in the [masternode identity IDs section](#masternode-identity-ids) | | `contract_id` | String | Yes | The ID of the contract | | `document_type_name` | String | No | Name of the document type | | `purposes` | Array of [KeyPurpose](#key-purposes) | No | Array of purposes for which keys are requested | diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index c6f5ab688..64362789e 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -56,6 +56,7 @@ data returned is valid and complete. The endpoints are versioned so updates can | 2 | [`getIdentityKeys`](../reference/dapi-endpoints-platform-endpoints.md#getidentitykeys) | Returns the requested identity keys | 2 | [`getIdentityNonce`](../reference/dapi-endpoints-platform-endpoints.md#getidentitynonce) | Returns the current identity nonce | | 2 | `getIdentities` | **Removed in Dash Platform v1.0.0**
Returns the requested identities | +| 2 | [`getIdentitiesBalances`](../reference/dapi-endpoints-platform-endpoints.md#getidentitiesbalances) | **Added in Dash Platform v1.3.0**
Retrieves the balances for a list of identities | | 2 | [`getIdentitiesContractKeys`](../reference/dapi-endpoints-platform-endpoints.md#getidentitiescontractkeys) | *Added in Dash Platform v1.0.0*
Returns keys associated to a specific contract for multiple Identities | | 2 | `getIdentitiesByPublicKeyHashes` | **Removed in Dash Platform v1.0.0**
Returns the identities associated with the provided public key hashes | | 2 | [`getDataContract`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontract) | Returns the requested data contract |