feat(drive): composite document queries: a page plus derived sub-queries under one merged proof

packages/rs-drive/src/drive/contract/insert/insert_contract/v0/tests/mod.rs

@@ -27,6 +27,7 @@
 //!   suite's fixture and assertion helpers.
 
 mod chained_query_e2e_tests;
+mod composite_query_e2e_tests;
 mod countable_e2e_tests;
 mod index_only_e2e_tests;
 mod noncounted_sibling_e2e_tests;

packages/rs-drive/src/drive/document/query/mod.rs

@@ -5,6 +5,7 @@
 
 mod fetch_document_history_query;
 mod query_chained_documents;
+mod query_composite_documents;
 /// query of the vote state
 pub mod query_contested_documents_vote_state;
 mod query_documents;
@@ -14,6 +15,7 @@ mod query_documents_with_flags;
 pub mod query_contested_documents_storage;
 
 pub use query_chained_documents::*;
+pub use query_composite_documents::*;
 pub use query_documents::*;
 pub use query_documents_with_flags::*;
 

packages/rs-drive/src/drive/document/query/query_composite_documents/mod.rs

@@ -0,0 +1,74 @@
+mod v0;
+
+use crate::drive::Drive;
+use crate::error::drive::DriveError;
+use crate::error::Error;
+use crate::query::drive_composite_document_query::DriveCompositeDocumentQuery;
+use dpp::block::epoch::Epoch;
+use dpp::document::Document;
+use dpp::version::PlatformVersion;
+use grovedb::TransactionArg;
+
+pub use v0::QueryCompositeDocumentsOutcomeV0;
+
+impl Drive {
+    /// Executes a composite document query (a page plus its derived
+    /// sub-queries) without proofs and returns the materialized results
+    /// plus the processing cost (when an epoch is given).
+    pub fn query_composite_documents(
+        &self,
+        query: &DriveCompositeDocumentQuery,
+        epoch: Option<&Epoch>,
+        transaction: TransactionArg,
+        platform_version: &PlatformVersion,
+    ) -> Result<QueryCompositeDocumentsOutcomeV0, Error> {
+        match platform_version
+            .drive
+            .methods
+            .document
+            .query
+            .query_composite_documents
+        {
+            0 => self.query_composite_documents_v0(query, epoch, transaction, platform_version),
+            version => Err(Error::Drive(DriveError::UnknownVersionMismatch {
+                method: "query_composite_documents".to_string(),
+                known_versions: vec![0],
+                received: version,
+            })),
+        }
+    }
+
+    /// Executes a composite document query AND generates its single
+    /// merged proof: the page and every derived sub-query merged by
+    /// `prove_query_many` — one proof, one root by construction. Grovedb
+    /// proves committed state only, so the materialize/prove sequence is
+    /// bracketed by root-hash reads and retried when a block commit
+    /// interleaves — see
+    /// [`DriveCompositeDocumentQuery::execute_with_proof_internal`].
+    /// Shares the `query_composite_documents` version slot with the
+    /// no-proof path (one surface, one version).
+    ///
+    /// Returns the merged proof plus the materialized page (the
+    /// caller's pagination cursor derives from it); the sub-query
+    /// results are covered by the proof and not materialized twice.
+    pub fn query_composite_documents_with_proof(
+        &self,
+        query: &DriveCompositeDocumentQuery,
+        platform_version: &PlatformVersion,
+    ) -> Result<(Vec<u8>, Vec<Document>), Error> {
+        match platform_version
+            .drive
+            .methods
+            .document
+            .query
+            .query_composite_documents
+        {
+            0 => self.query_composite_documents_with_proof_v0(query, platform_version),
+            version => Err(Error::Drive(DriveError::UnknownVersionMismatch {
+                method: "query_composite_documents_with_proof".to_string(),
+                known_versions: vec![0],
+                received: version,
+            })),
+        }
+    }
+}

packages/rs-drive/src/drive/document/query/query_composite_documents/v0/mod.rs

@@ -0,0 +1,62 @@
+use crate::drive::Drive;
+use crate::error::Error;
+use crate::fees::op::LowLevelDriveOperation;
+use crate::query::drive_composite_document_query::{
+    CompositeDocumentsResult, DriveCompositeDocumentQuery,
+};
+use dpp::block::epoch::Epoch;
+use dpp::version::PlatformVersion;
+use grovedb::TransactionArg;
+
+/// The outcome of a composite document query: the materialized results
+/// and the processing cost.
+#[derive(Debug, Default)]
+pub struct QueryCompositeDocumentsOutcomeV0 {
+    /// The materialized page and sub-query results.
+    pub result: CompositeDocumentsResult,
+    /// The processing cost, when an epoch was given.
+    pub cost: u64,
+}
+
+impl Drive {
+    #[inline(always)]
+    pub(super) fn query_composite_documents_v0(
+        &self,
+        query: &DriveCompositeDocumentQuery,
+        epoch: Option<&Epoch>,
+        transaction: TransactionArg,
+        platform_version: &PlatformVersion,
+    ) -> Result<QueryCompositeDocumentsOutcomeV0, Error> {
+        let mut drive_operations: Vec<LowLevelDriveOperation> = vec![];
+        let result = query.execute_no_proof_internal(
+            self,
+            transaction,
+            &mut drive_operations,
+            platform_version,
+        )?;
+        let cost = if let Some(epoch) = epoch {
+            Drive::calculate_fee(
+                None,
+                Some(drive_operations),
+                epoch,
+                self.config.epochs_per_era,
+                platform_version,
+                None,
+            )?
+            .processing_fee
+        } else {
+            0
+        };
+        Ok(QueryCompositeDocumentsOutcomeV0 { result, cost })
+    }
+
+    #[inline(always)]
+    pub(super) fn query_composite_documents_with_proof_v0(
+        &self,
+        query: &DriveCompositeDocumentQuery,
+        platform_version: &PlatformVersion,
+    ) -> Result<(Vec<u8>, Vec<dpp::document::Document>), Error> {
+        let mut drive_operations: Vec<LowLevelDriveOperation> = vec![];
+        query.execute_with_proof_internal(self, &mut drive_operations, platform_version)
+    }
+}