From bf7c50189b9988e380d85af6cdd1a7dafd23d9b0 Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 9 Dec 2025 13:30:51 -0500 Subject: [PATCH 1/3] docs: add draft query capabilities explanation --- docs/explanations/query.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + 2 files changed, 39 insertions(+) create mode 100644 docs/explanations/query.md diff --git a/docs/explanations/query.md b/docs/explanations/query.md new file mode 100644 index 000000000..49bcdc8e6 --- /dev/null +++ b/docs/explanations/query.md @@ -0,0 +1,38 @@ +# Query Capabilities + +Dash Platform allows applications to retrieve blockchain state in a structured and deterministic +way. Instead of replaying historical transactions, clients query the latest committed state of +identities, data contracts, documents, etc. This enables predictable data access similar to +traditional databases while retaining decentralized trust guarantees. + +## Querying the State + +All queries operate on the finalized state stored within Platform’s state tree. Responses reflect +the most recently committed block and do not include pending or historical intermediate changes. + +This means: + +- Query results are consistent across nodes +- Clients do not need to process blockchain history +- Data retrieval is deterministic and efficient + +:::{note} +Queries return the *current finalized state*, not the sequence of events that created it. +::: + +## Indexed Queries + +Dash Platform requires that queries use indexes defined in the data contract for the relevant +document type. If a field is not indexed, it cannot be used in filtering or sorting expressions. + +Benefits of indexed querying include: + +- Predictable performance +- No full-table scanning +- Consistent execution across nodes + +:::{important} +Indexes should be planned during contract design since there are [limited index update +options](./platform-protocol-data-contract.md#contract-updates) for already registered contracts. +::: + diff --git a/docs/index.md b/docs/index.md index 2095793ff..92cf82361 100644 --- a/docs/index.md +++ b/docs/index.md @@ -137,6 +137,7 @@ explanations/dashpay explanations/fees explanations/tokens explanations/nft +explanations/query ``` ```{toctree} From 7fceca987fdc3f70b10da034a32e26b421a2acc4 Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 10 Dec 2025 12:16:59 -0500 Subject: [PATCH 2/3] docs: update query explanation --- docs/explanations/query.md | 44 ++++++++++++++++++++++++++++++-------- 1 file changed, 35 insertions(+), 9 deletions(-) diff --git a/docs/explanations/query.md b/docs/explanations/query.md index 49bcdc8e6..d86d42423 100644 --- a/docs/explanations/query.md +++ b/docs/explanations/query.md @@ -1,14 +1,17 @@ +```{eval-rst} +.. _explanations-query: +``` + # Query Capabilities -Dash Platform allows applications to retrieve blockchain state in a structured and deterministic -way. Instead of replaying historical transactions, clients query the latest committed state of -identities, data contracts, documents, etc. This enables predictable data access similar to -traditional databases while retaining decentralized trust guarantees. +Dash Platform allows applications to retrieve data in a structured and deterministic manner. Clients +query the latest committed state of identities, data contracts, documents, and other Platform data +similar to traditional databases while retaining decentralized trust benefits. ## Querying the State -All queries operate on the finalized state stored within Platform’s state tree. Responses reflect -the most recently committed block and do not include pending or historical intermediate changes. +Queries operate on the finalized data stored within Platform’s state tree. Responses reflect the +most recently committed block and do not include pending or historical intermediate changes. This means: @@ -20,10 +23,34 @@ This means: Queries return the *current finalized state*, not the sequence of events that created it. ::: +## Deterministic Results + +All queries produce deterministic results. The same query executed on two honest and up-to-date +Platform nodes will always produce the same result. This ensures consistent application behavior +regardless of which node provides the response. + +## Data Proofs + +Queries can return locally verifiable cryptographic proofs, allowing clients to verify response +accuracy without trusting the responding node. + +Two types of proofs exist: + +| Proof Type | Purpose | +|------------|---------| +| Inclusion Proof | Confirms that specific data exists and has not been modified | +| Non-Inclusion Proof | Confirms that specific data does *not* exist (useful for uniqueness checks such as usernames) | + +Proofs are especially valuable for: + +- Light clients +- Browser-based and serverless environments +- Trust-minimized applications + ## Indexed Queries -Dash Platform requires that queries use indexes defined in the data contract for the relevant -document type. If a field is not indexed, it cannot be used in filtering or sorting expressions. +Dash Platform requires queries to use indexes defined in the data contract for the relevant document +type. If a field is not indexed, it cannot be used for filtering or sorting. Benefits of indexed querying include: @@ -35,4 +62,3 @@ Benefits of indexed querying include: Indexes should be planned during contract design since there are [limited index update options](./platform-protocol-data-contract.md#contract-updates) for already registered contracts. ::: - From 12659c0096e621f2067d186b8365b81a32cb5f52 Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 10 Dec 2025 13:21:28 -0500 Subject: [PATCH 3/3] docs: query updates --- docs/explanations/dapi.md | 5 +++++ docs/explanations/query.md | 1 - 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/explanations/dapi.md b/docs/explanations/dapi.md index 37ab2e0ff..c53f05a59 100644 --- a/docs/explanations/dapi.md +++ b/docs/explanations/dapi.md @@ -24,6 +24,11 @@ To overcome these obstacles, the Dash decentralized API (DAPI) uses Dash's robus DAPI protects connections by using TLS to encrypt communication between clients and the masternodes. This encryption safeguards transmitted data from unauthorized access, interception, or tampering. [Platform gRPC endpoints](../reference/dapi-endpoints-platform-endpoints.md) provide an additional level of security by optionally returning cryptographic proofs. Successful proof verification guarantees that the server responded without modifying the requested data. +:::{note} +See the [Query Capabilities page](./query.md) for more detailed information regarding Platform data +retrieval. +::: + ## Endpoint Overview DAPI currently provides 2 types of endpoints: [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/docs/guides/). The JSON-RPC endpoints expose some layer 1 information while the gRPC endpoints support layer 2 as well as streaming of events related to blocks and transactions/transitions. For a list of all endpoints and usage details, please see the [DAPI endpoint reference section](../reference/dapi-endpoints.md). diff --git a/docs/explanations/query.md b/docs/explanations/query.md index d86d42423..a8a5624aa 100644 --- a/docs/explanations/query.md +++ b/docs/explanations/query.md @@ -55,7 +55,6 @@ type. If a field is not indexed, it cannot be used for filtering or sorting. Benefits of indexed querying include: - Predictable performance -- No full-table scanning - Consistent execution across nodes :::{important}