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 +``` diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index c87497a7f..d587b3c21 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 @@ -344,6 +349,132 @@ Retrieves the state of a vote for a specific contested resource. ::: :::: +### getEvonodesProposedEpochBlocksByIds + +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. + +**Parameters**: + +| Name | Type | Required | Description | +| ------------------ | -------- | -------- | ----------- | +| `epoch` | Integer | No | The epoch to query for. If not set, the current epoch will be used | +| `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** + +::::{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" + } + } +} +``` +::: +:::: + +### 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 @@ -963,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). @@ -971,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 65f1e8761..64362789e 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,10 +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 | [`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 | @@ -54,15 +56,16 @@ 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 | [`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 | | 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 |