diff --git a/docs/protocol-ref/shielded-pool.md b/docs/protocol-ref/shielded-pool.md index 6279b9de5..c4b10cfa3 100644 --- a/docs/protocol-ref/shielded-pool.md +++ b/docs/protocol-ref/shielded-pool.md @@ -200,14 +200,11 @@ Shielded Transfer, Unshield, and Shielded Withdrawal have no transparent signatu ## Querying shielded state -DAPI exposes a set of read-only endpoints for clients that need to fetch anchors, scan encrypted notes, verify nullifier status, or sync incremental nullifier updates. See the [DAPI Platform endpoints reference](../reference/dapi-endpoints-platform-endpoints.md) for request and response shapes: +DAPI exposes a set of read-only endpoints for clients that need to fetch anchors, scan encrypted notes, verify nullifier status, or track shielded sync progress. See the [DAPI Platform endpoints reference](../reference/dapi-endpoints-platform-endpoints.md) for request and response shapes: - [`getShieldedPoolState`](../reference/dapi-endpoints-platform-endpoints.md#getshieldedpoolstate) - [`getShieldedAnchors`](../reference/dapi-endpoints-platform-endpoints.md#getshieldedanchors) - [`getMostRecentShieldedAnchor`](../reference/dapi-endpoints-platform-endpoints.md#getmostrecentshieldedanchor) - [`getShieldedEncryptedNotes`](../reference/dapi-endpoints-platform-endpoints.md#getshieldedencryptednotes) +- [`getShieldedNotesCount`](../reference/dapi-endpoints-platform-endpoints.md#getshieldednotescount) - [`getShieldedNullifiers`](../reference/dapi-endpoints-platform-endpoints.md#getshieldednullifiers) -- [`getNullifiersTrunkState`](../reference/dapi-endpoints-platform-endpoints.md#getnullifierstrunkstate) -- [`getNullifiersBranchState`](../reference/dapi-endpoints-platform-endpoints.md#getnullifiersbranchstate) -- [`getRecentNullifierChanges`](../reference/dapi-endpoints-platform-endpoints.md#getrecentnullifierchanges) -- [`getRecentCompactedNullifierChanges`](../reference/dapi-endpoints-platform-endpoints.md#getrecentcompactednullifierchanges) diff --git a/docs/reference/dapi-endpoints-core-grpc-endpoints.md b/docs/reference/dapi-endpoints-core-grpc-endpoints.md index 6a8798bbe..89ae2dcfd 100644 --- a/docs/reference/dapi-endpoints-core-grpc-endpoints.md +++ b/docs/reference/dapi-endpoints-core-grpc-endpoints.md @@ -498,7 +498,7 @@ the update messages following a new block. | `from_block_height` | Integer | No | Return records beginning with the block height provided | | ---------- | | | | | `count` | Integer | No | Number of blocks to sync. If set to 0, syncing continuously sends new data as well (default: 0) | -| `send_transaction_hashes` \* | Boolean | No | | +| `send_transaction_hashes` | Boolean | No | When `true`, includes transaction hashes in the response stream | **Example Request and Response** diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index d0a985791..d0bb66622 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -826,9 +826,9 @@ grpcurl -proto protos/platform/v0/platform.proto \ | Name | Type | Required | Description | | ------- | -------- | -------- | ---------------------------------------- | | `id` | Bytes | Yes | A data contract `id` | -| `start_at_ms` | Integer | Yes | Request revisions starting at this timestamp | -| `limit` | Integer | Yes | The maximum number of revisions to return | -| `offset` | Integer | Yes | The offset of the first revision to return | +| `start_at_ms` | Integer | No | Request revisions starting at this timestamp | +| `limit` | Integer | No | The maximum number of revisions to return | +| `offset` | Integer | No | The offset of the first revision to return | | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested data contract. The data requested will be encoded as part of the proof in the response.| **Example Request and Response** @@ -1386,6 +1386,78 @@ grpcurl -proto protos/platform/v0/platform.proto \ Client computes `avg = 215 / 50 = 4.3`. +### getDocumentHistory + +**Returns**: The revision history for a single document on a contract that keeps document history +**Parameters**: + +| Name | Type | Required | Description | +| ---- | ---- | -------- | ----------- | +| `data_contract_id` | Bytes | Yes | A data contract `id` | +| `document_type_name` | String | Yes | A document type defined by the data contract | +| `document_id` | Bytes | Yes | The `id` of the document whose history is requested | +| `limit` | Integer | No | The maximum number of history entries to return | +| `offset` | Integer | No | The offset for pagination through the document history | +| `start_at_ms` | Integer | No | Only return results starting at this time in milliseconds | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested document history. The data requested will be encoded as part of the proof in the response.| + +**Example Request** + +::::{tab-set} +:::{tab-item} gRPCurl +:sync: grpcurl +```shell +# `data_contract_id` and `document_id` must be represented in base64 +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "data_contract_id": "nfpmJoj9R+rFTYLo/ddAuhHA4Si2YlK6BAAvEGmUIdo=", + "document_type_name": "review", + "document_id": "wZiWoQCwYKPVjAZ8NDXpbSMb7IEh++hGXzB38niWrIg=", + "limit": 2, + "offset": 0, + "start_at_ms": 0, + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getDocumentHistory +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +:sync: grpcurl +```json +{ + "v0": { + "documentHistory": { + "documentEntries": [ + { + "date": "1782423220252", + "value": "AsGYlqEAsGCj1YwGfDQ16W0jG+yBIfvoRl8wd/J4lqyIM1bHElsMayy0ZD9WkprWAf6lYDIwqyC8dsdzc++MmRsBAAMAAAGfALPwHAAAAZ8As/AcCGRhc2hub3RlBQEuV2Fsa3Rocm91Z2ggcmV2aWV3IGNyZWF0ZSAyMDI2LTA2LTI1VDIxOjMzOjM1Wg==" + }, + { + "date": "1782423230374", + "value": "AsGYlqEAsGCj1YwGfDQ16W0jG+yBIfvoRl8wd/J4lqyIM1bHElsMayy0ZD9WkprWAf6lYDIwqyC8dsdzc++MmRsCAAMAAAGfALPwHAAAAZ8AtBemCGRhc2hub3RlBQEsV2Fsa3Rocm91Z2ggcmV2aWV3IGVkaXQgMjAyNi0wNi0yNVQyMTozMzo0NVo=" + } + ] + }, + "metadata": { + "height": "375045", + "coreChainLockedHeight": 1506013, + "epoch": 17082, + "timeMs": "1782851061688", + "protocolVersion": 12, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: + ## Identity Endpoints ### getIdentity @@ -1846,10 +1918,10 @@ Current identity contract nonce: 0 | Name | Type | Required | Description | | ------- | ------- | -------- | ------------ | -| `identity_td` | String | Yes | An identity ID
Note: masternode IDs are created uniquely as described in the [masternode identity IDs section](#masternode-identity-ids) +| `identity_id` | Bytes | Yes | An identity ID
Note: masternode IDs are created uniquely as described in the [masternode identity IDs section](#masternode-identity-ids) | `request_type` | [KeyRequestType](#request-types) | Yes | Request all keys (`all_keys`), specific keys (`specific_keys`), search for keys (`search_key`) -| `limit` | Integer | Yes | The maximum number of revisions to return | -| `offset` | Integer | Yes | The offset of the first revision to return | +| `limit` | Integer | No | The maximum number of keys to return | +| `offset` | Integer | No | The offset for pagination through the keys | | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identity #### Request Types @@ -2151,7 +2223,7 @@ grpcurl -proto protos/platform/v0/platform.proto \ | Name | Type | Required | Description | |----------------------|-------------------------|----------|-------------| | `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 | +| `contract_id` | Bytes | 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 | | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identity keys | @@ -2404,6 +2476,7 @@ Retrieves a list of actions performed by a specific group within a contract. | | `destroy_frozen_funds` | Destroys frozen funds for a specified entity. | | | `emergency_action` | Performs emergency actions like pausing or resuming the contract. | | | `token_config_update` | Updates token configuration settings. | +| | `update_price` | Updates the token's direct purchase price (fixed or tiered). | | **DocumentEvent** | `create` | Represents the creation of a document. | | **ContractEvent** | `update` | Represents updates to a contract. | @@ -2433,6 +2506,7 @@ Retrieves a list of actions performed by a specific group within a contract. | | `recipient_id` | Bytes | Identity ID of the recipient. | | | `public_note` | String (Optional) | A public note for the mint event. | | `burn` | `amount` | UInt64 | Amount of tokens to burn. | +| | `burn_from_id` | Bytes | Identity ID the tokens are burned from. | | | `public_note` | String (Optional) | A public note for the burn event. | | `freeze` | `frozen_id` | Bytes | Identifier of the entity being frozen. | | | `public_note` | String (Optional) | A public note for the freeze event. | @@ -2443,8 +2517,11 @@ Retrieves a list of actions performed by a specific group within a contract. | | `public_note` | String (Optional) | A public note for the destruction event. | | `emergency_action` | `action_type` | Enum (`PAUSE = 0`, `RESUME = 1`) | Type of emergency action performed. | | | `public_note` | String (Optional) | A public note for the emergency action. | -| `token_config_update` | `token_config_update_item` | Bytes | Configuration update details. | +| `token_config_update` | `token_config_`
`update_item` | Bytes | Configuration update details. | | | `public_note` | String (Optional) | A public note for the configuration update. | +| `update_price` | `fixed_price` | UInt64 | Fixed direct purchase price (present when a fixed price is set). | +| | `variable_price` | Object | Tiered pricing schedule (`price_for_quantity` array of `{quantity, price}`), present when tiered pricing is set. | +| | `public_note` | String (Optional) | A public note for the price update event. | **Example Request and Response** @@ -2695,13 +2772,11 @@ grpcurl -proto protos/platform/v0/platform.proto \ Retrieves current quorum details, including validator sets and metadata for each quorum. **Returns**: Information about current quorums, including quorum hashes, validator sets, and -cryptographic proof. +the last block proposer. **Parameters**: -| Name | Type | Required | Description | -| ------------- | ------ | -------- | ----------- | -| `version` | Object | No | Version object containing request parameters | +This endpoint does not require any parameters. **Example Request and Response** @@ -2908,7 +2983,6 @@ grpcurl -proto protos/platform/v0/platform.proto \ :::{tab-item} gRPCurl :sync: grpcurl ```shell -# `id` must be represented in base64 grpcurl -proto protos/platform/v0/platform.proto \ -d '{ "v0": { @@ -3232,7 +3306,7 @@ grpcurl -proto protos/platform/v0/platform.proto \ | Name | Type | Required | Description | | ------- | ------- | -------- | ------------ | -| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identity +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested protocol version state **Example Request and Response** @@ -3286,9 +3360,9 @@ grpcurl -proto protos/platform/v0/platform.proto \ | Name | Type | Required | Description | | ------- | ------- | -------- | ------------ | -| `start_pro_tx_hash` | String | No | Protx hash of an evonode +| `start_pro_tx_hash` | Bytes | No | Protx hash of an evonode | `count` | Integer | No | Number of records to request -| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identity +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested protocol version vote status **Example Request and Response** @@ -3767,7 +3841,8 @@ grpcurl -proto protos/platform/v0/platform.proto \ { "v0": { "data": { - "contractId": "L+2jKoiBdmhzIAg82a3nnOn8/K5sQiaIW/Tinw0ypNM=" + "contractId": "L+2jKoiBdmhzIAg82a3nnOn8/K5sQiaIW/Tinw0ypNM=", + "tokenContractPosition": 0 }, "metadata": { "height": "157984", @@ -3895,6 +3970,8 @@ Retrieves the last-claim timestamp for a token’s perpetual distribution for a **Returns**: A timestamp indicating the last successful claim, or a cryptographic proof. +The returned `last_claim` value takes one of several forms depending on the token’s distribution interval: `timestamp_ms` (milliseconds since epoch), `block_height`, `epoch`, or `raw_bytes`. + **Parameters**: | Name | Type | Required | Description | @@ -4505,10 +4582,6 @@ grpcurl -proto protos/platform/v0/platform.proto \ :::{versionadded} 3.1.0 ::: -:::{attention} -These endpoints are defined in the protocol but are not yet available on public nodes. -::: - ### getShieldedEncryptedNotes Returns encrypted notes from the shielded pool for a specified range. Clients use these notes for trial decryption to identify notes belonging to their viewing key. @@ -4523,6 +4596,62 @@ Returns encrypted notes from the shielded pool for a specified range. Clients us | `count` | Integer | Yes | The number of notes to retrieve | | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested notes | +**Example Request and Response** + +::::{tab-set} +:::{tab-item} gRPCurl +:sync: grpcurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "start_index": 0, + "count": 2, + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getShieldedEncryptedNotes +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +:sync: grpcurl +```json +{ + "v0": { + "encryptedNotes": { + "entries": [ + { + "nullifier": "ACLc9k5HtKNM//KyTT/iWa+MIA8f1Ya3HDIsURjUYRc=", + "cmx": "ecV1F/WDoBa8CfL2Fwdlq3gcBrrZqnvgI+NwtsJZ6Ss=", + "encryptedNote": "WhToIlQhpze9cE45wNRsmxukpDPVOQ5k2Ws5FW2WYIjJiNctiIDc0CvGIKA49tJu8Z0lwjhp8RTUPmLdGShZgSTIp7W/dO2emMRUtPxb1TWUVU8EYd1lBnIXOATGmuV35oUQbt94GeX2PLp5rEOmm0o5rtgqiDyJ305AiLRSwZeOPPRrFrly/XQX90nacrqVBVg7vNvLlTKQazFPAcyjG1O/DpYh82W4jzXWakCn5XQYnMkRHv/u+YxK87viIG5C6XLpxOkxBgeONeYFBBGz8YlTnCnOBIkp", + "cvNet": "3Z5DAoE4aC3roM3Qh4U+wuCndC1WiASsxer1oSIMIIY=" + }, + { + "nullifier": "5ShcfdX68dfTfdZZ4nAXwfooPvd+1XHLXFP4D5hUzS4=", + "cmx": "CEa3w+gR7bMftk6XcIA1/1JT27UqxZYGmfO7gP7fWwg=", + "encryptedNote": "JzRWtHVnO5x4Ijn4M2URM4ojlY9W9mPV2Qz/Rz2TeA6hz5s63bYlTzy/eAQuJStsjCYQwq5H9OtN/EqFov/f1CqtwRTEWnro/3H+QAwMW+hYW982lBNImsPZhLk533fG2f0QD3yuu+BQXAryxNg4jHFBb70wEDF+m9ZklhNH5Bdyl0KoTXjEZqL2mUcY6zcb5gjU6DkozwNOFuiVjMCRVjzRdwUVNLNQhZqqLFIeWUCo37GZbN8oC6p24Lb9phnYNu53Km2d4c74nLdOVdSMeAzTIjle+woH", + "cvNet": "TuY3Si9ojWn1BbX4oHLQ+ZDZ/eFlHpMNV5vh3rzd+jU=" + } + ] + }, + "metadata": { + "height": "375055", + "coreChainLockedHeight": 1506025, + "epoch": 17083, + "timeMs": "1782852695259", + "protocolVersion": 12, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: + ### getShieldedAnchors Returns all commitment tree anchors for the shielded pool. Anchors are used by shielded transaction provers to reference a valid state of the commitment tree. @@ -4535,6 +4664,51 @@ Returns all commitment tree anchors for the shielded pool. Anchors are used by s |---------|---------|----------|-------------| | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested anchors | +**Example Request and Response** + +::::{tab-set} +:::{tab-item} gRPCurl +:sync: grpcurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getShieldedAnchors +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +:sync: grpcurl +```json +{ + "v0": { + "anchors": { + "anchors": [ + "Ahh3yHTlv9H1vhEGVFRbRquziIuG7is28el/VpCv7jk=", + "JeaJEco0ewcWxwIudW6TX/GQQQ+muiLIMwn8S3cbNw8=", + "Li/voQtJmL93TZfi/j3ht81uXY4TfPB2iPkRpfnfhhw=" + ] + }, + "metadata": { + "height": "375055", + "coreChainLockedHeight": 1506025, + "epoch": 17083, + "timeMs": "1782852695259", + "protocolVersion": 12, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: + ### getMostRecentShieldedAnchor Returns the most recent commitment tree anchor for the shielded pool. @@ -4547,6 +4721,45 @@ Returns the most recent commitment tree anchor for the shielded pool. |---------|---------|----------|-------------| | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested anchor | +**Example Request and Response** + +::::{tab-set} +:::{tab-item} gRPCurl +:sync: grpcurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getMostRecentShieldedAnchor +``` +::: +:::: + +::::{tab-set} +:::{tab-item} Response (gRPCurl) +:sync: grpcurl +```json +{ + "v0": { + "anchor": "Li/voQtJmL93TZfi/j3ht81uXY4TfPB2iPkRpfnfhhw=", + "metadata": { + "height": "375055", + "coreChainLockedHeight": 1506025, + "epoch": 17083, + "timeMs": "1782852695259", + "protocolVersion": 12, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: + ### getShieldedPoolState Returns the total balance held in the shielded pool. @@ -4559,73 +4772,159 @@ Returns the total balance held in the shielded pool. |---------|---------|----------|-------------| | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested pool state | -### getShieldedNullifiers - -Returns the spent status of specified nullifiers. Clients use this to determine whether notes have already been spent. - -**Returns**: A list of nullifier statuses or a cryptographic proof. +**Example Request and Response** -**Parameters**: +::::{tab-set} +:::{tab-item} gRPCurl +:sync: grpcurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getShieldedPoolState +``` +::: +:::: -| Name | Type | Required | Description | -|--------------|----------------|----------|-------------| -| `nullifiers` | Array of Bytes | Yes | The nullifiers to query (each 32 bytes) | -| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested nullifier statuses | +::::{tab-set} +:::{tab-item} Response (gRPCurl) +:sync: grpcurl +```json +{ + "v0": { + "totalBalance": "1831893452700", + "metadata": { + "height": "375055", + "coreChainLockedHeight": 1506025, + "epoch": 17083, + "timeMs": "1782852695259", + "protocolVersion": 12, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: -### getNullifiersTrunkState +### getShieldedNotesCount -Returns a cryptographic proof of the trunk state of a nullifier tree. Used with `getNullifiersBranchState` to perform incremental sync of nullifier sets. +Returns the count of leaves in the shielded notes commitment tree. Wallets use this at the start of a shielded sync to seed a determinate progress indicator. -**Returns**: A cryptographic proof of the nullifier tree trunk state. +**Returns**: The total shielded notes count or a cryptographic proof. **Parameters**: -| Name | Type | Required | Description | -|-------------------|---------|----------|-------------| -| `pool_type` | Integer | Yes | The shielded pool type: `0` = credit pool, `1` = main token pool, `2` = individual token pool | -| `pool_identifier` | Bytes | No | 32-byte token identifier; required when `pool_type` is `2` | - -### getNullifiersBranchState - -Returns a Merkle proof for a branch of the nullifier tree. Use `checkpoint_height` from the metadata of a `getNullifiersTrunkState` response to ensure consistency. +| Name | Type | Required | Description | +|---------|---------|----------|-------------| +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested count | -**Returns**: A Merkle proof for the specified branch. +**Example Request and Response** -**Parameters**: +::::{tab-set} +:::{tab-item} gRPCurl +:sync: grpcurl +```shell +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getShieldedNotesCount +``` +::: +:::: -| Name | Type | Required | Description | -|---------------------|---------|----------|-------------| -| `pool_type` | Integer | Yes | The shielded pool type: `0` = credit pool, `1` = main token pool, `2` = individual token pool | -| `pool_identifier` | Bytes | No | 32-byte token identifier; required when `pool_type` is `2` | -| `key` | Bytes | Yes | The branch key to query | -| `depth` | Integer | Yes | The depth of the branch | -| `checkpoint_height` | Integer | Yes | Block height from a `getNullifiersTrunkState` response metadata, for consistency | +::::{tab-set} +:::{tab-item} Response (gRPCurl) +:sync: grpcurl +```json +{ + "v0": { + "totalNotesCount": "622", + "metadata": { + "height": "375055", + "coreChainLockedHeight": 1506025, + "epoch": 17083, + "timeMs": "1782852695259", + "protocolVersion": 12, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: -### getRecentNullifierChanges +### getShieldedNullifiers -Returns nullifier additions starting from a specified block height, indicating which notes were spent per block. +Returns the spent status of specified nullifiers. Clients use this to determine whether notes have already been spent. -**Returns**: A list of nullifier additions grouped by block, or a cryptographic proof. +**Returns**: A list of nullifier statuses or a cryptographic proof. **Parameters**: -| Name | Type | Required | Description | -|----------------|---------|----------|-------------| -| `start_height` | String (uint64) | Yes | Block height to start from (as a string due to uint64 size) | -| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested changes | - -### getRecentCompactedNullifierChanges +| Name | Type | Required | Description | +|--------------|----------------|----------|-------------| +| `nullifiers` | Array of Bytes | Yes | The nullifiers to query (each 32 bytes) | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested nullifier statuses | -Returns compacted nullifier additions from a specified block height. Compacted changes merge multiple blocks into ranges, reducing response size for bulk sync. +**Example Request and Response** -**Returns**: A list of compacted nullifier additions grouped by block range, or a cryptographic proof. +::::{tab-set} +:::{tab-item} gRPCurl +:sync: grpcurl +```shell +# Each nullifier must be represented in base64 +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "v0": { + "nullifiers": [ + "ACLc9k5HtKNM//KyTT/iWa+MIA8f1Ya3HDIsURjUYRc=" + ], + "prove": false + } + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getShieldedNullifiers +``` +::: +:::: -**Parameters**: +::::{tab-set} +:::{tab-item} Response (gRPCurl) +:sync: grpcurl +```json +{ + "v0": { + "nullifierStatuses": { + "entries": [ + { + "nullifier": "ACLc9k5HtKNM//KyTT/iWa+MIA8f1Ya3HDIsURjUYRc=" + } + ] + }, + "metadata": { + "height": "375055", + "coreChainLockedHeight": 1506025, + "epoch": 17083, + "timeMs": "1782852695259", + "protocolVersion": 12, + "chainId": "dash-testnet-51" + } + } +} +``` +::: +:::: -| Name | Type | Required | Description | -|----------------------|---------|----------|-------------| -| `start_block_height` | String (uint64) | Yes | Block height to start from (as a string due to uint64 size) | -| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested changes | +A nullifier's `is_spent` field is omitted from the response when `false` (proto3 default), so an entry without `is_spent` indicates the nullifier has not been spent. ## Code Reference diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index 5e1e87c41..252892e1a 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -135,11 +135,8 @@ Shielded Transaction endpoints are defined in the protocol but are not yet avail | [`getShieldedAnchors`](../reference/dapi-endpoints-platform-endpoints.md#getshieldedanchors) | Returns all commitment tree anchors for the shielded pool. | | [`getMostRecentShieldedAnchor`](../reference/dapi-endpoints-platform-endpoints.md#getmostrecentshieldedanchor) | Returns the most recent commitment tree anchor. | | [`getShieldedPoolState`](../reference/dapi-endpoints-platform-endpoints.md#getshieldedpoolstate) | Returns the total balance held in the shielded pool. | +| [`getShieldedNotesCount`](../reference/dapi-endpoints-platform-endpoints.md#getshieldednotescount) | Returns the count of leaves in the shielded notes commitment tree, used to seed shielded sync progress. | | [`getShieldedNullifiers`](../reference/dapi-endpoints-platform-endpoints.md#getshieldednullifiers) | Returns the spent status of specified nullifiers. | -| [`getNullifiersTrunkState`](../reference/dapi-endpoints-platform-endpoints.md#getnullifierstrunkstate) | Returns a proof of the trunk state of a nullifier tree. | -| [`getNullifiersBranchState`](../reference/dapi-endpoints-platform-endpoints.md#getnullifiersbranchstate) | Returns a Merkle proof for a branch of the nullifier tree. | -| [`getRecentNullifierChanges`](../reference/dapi-endpoints-platform-endpoints.md#getrecentnullifierchanges) | Returns recent nullifier additions starting from a specified block height. | -| [`getRecentCompactedNullifierChanges`](../reference/dapi-endpoints-platform-endpoints.md#getrecentcompactednullifierchanges) | Returns compacted nullifier additions from a specified block height. | ```{eval-rst} .. diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md index c2859d12b..1832f4cc6 100644 --- a/docs/reference/query-syntax.md +++ b/docs/reference/query-syntax.md @@ -68,9 +68,9 @@ Valid fields consist of the indices defined for the document being queried. For :::{tip} - Only one range operator is allowed in a query. `Between` and its variants are single operators that replace a `>=`/`<=` pair — the engine also normalizes two range operators on the same field into the equivalent `Between*` form automatically - The `in` operator is only allowed for last two indexed properties -- Range operators are only allowed after `==` and `in` operators +- Range operators apply to an indexed field that follows any `==` and `in` clauses in the index. A standalone range (with no preceding `==`/`in` clause) is valid when a matching index exists - Range operators are only allowed for the last two fields used in the where condition -- Queries using range operators must also include an `orderBy` statement +- Queries using range operators (including `in`, which is treated as a range) must also include an `orderBy` statement ::: ### Evaluation Operators @@ -90,6 +90,9 @@ Valid fields consist of the indices defined for the document being queried. For where: [ ["nameHash", "<", "56116861626961756e6176657a382e64617368"], ], + orderBy: [ + ["nameHash", "asc"], + ], } ::: :::: @@ -121,7 +124,10 @@ Valid fields consist of the indices defined for the document being queried. For ["normalizedParentDomainName", "==", "dash"], // Return all matching names from the provided array ["normalizedLabel", "in", ["alice", "bob"]], - ] + ], + orderBy: [ + ["normalizedLabel", "asc"], + ] } ::: :::: @@ -152,7 +158,7 @@ The query modifiers described here determine how query results will be sorted an | Modifier | Effect | Example | | - | - | - | | `limit` | Restricts the number of results returned (maximum: 100) | `limit: 10` | -| `orderBy` | Returns records sorted by the field(s) provided. Sorting must be by the last indexed property. Can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | +| `orderBy` | Returns records sorted by the field(s) provided. The `orderBy` fields must match a consecutive run of the index's properties, read from the end of the index (for a compound index, sort by one or more of its trailing fields). Can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | | `startAt` | Returns records beginning with the document ID provided | `startAt: ''` | | `startAfter` | Returns records beginning after the document ID provided | `startAfter: ''` | | `offset` | Skips the first N matching results (available at the CBOR/DAPI layer; not exposed in the JS SDK) | `offset: 10` |