fix(sdk): index-only document creates and deletes resolve once they land (#5136)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: QuantumExplorer

packages/js-evo-sdk/src/documents/facade.ts

@@ -106,6 +106,8 @@ export class DocumentsFacade {
    * instance when you later intend to delete an indexOnly document whose
    * type requires `$createdAt`. A document of a contested index joins a
    * contest: `options.contestFund` is the most, in credits, it pays into it.
+   * For an indexOnly type the proof shows the document's entry at the proof's
+   * block, not that this create wrote it: no stronger proof exists for one.
    */
   async create(options: wasm.DocumentCreateOptions): Promise<wasm.Document> {
     const w = await this.sdk.getWasmSdkConnected();
@@ -117,6 +119,11 @@ export class DocumentsFacade {
     return w.documentReplace(options);
   }
 
+  /**
+   * Deletes a document and resolves once the proof shows it gone. For an
+   * indexOnly type the proof shows the document's entry gone at the proof's
+   * block, not that this delete removed it: no stronger proof exists for one.
+   */
   async delete(options: wasm.DocumentDeleteOptions): Promise<void> {
     const w = await this.sdk.getWasmSdkConnected();
     return w.documentDelete(options);

packages/rs-sdk/src/platform/documents/transitions/create.rs

@@ -3,6 +3,7 @@ use crate::platform::transition::broadcast::BroadcastStateTransition;
 use crate::platform::transition::put_settings::PutSettings;
 use crate::{Error, Sdk};
 use dpp::data_contract::accessors::v0::DataContractV0Getters;
+use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters;
 use dpp::data_contract::document_type::action_fees::agreement::DocumentActionFeeAgreement;
 use dpp::data_contract::DataContract;
 use dpp::document::{Document, DocumentV0Getters};
@@ -252,6 +253,9 @@ impl Sdk {
     ///
     /// This method broadcasts a document creation transition to add a new document
     /// to the specified data contract. The result contains the created document.
+    /// For an indexOnly document type the proof shows the document's entry at the
+    /// proof's block, not that this create wrote it: no stronger proof exists for
+    /// such a document.
     ///
     /// # Arguments
     ///
@@ -279,6 +283,11 @@ impl Sdk {
         let platform_version = self.version();
 
         let put_settings = create_document_transition_builder.settings;
+        let index_only = create_document_transition_builder
+            .data_contract
+            .document_type_for_name(&create_document_transition_builder.document_type_name)
+            .map_err(|e| Error::Protocol(e.into()))?
+            .index_only();
 
         let state_transition = create_document_transition_builder
             .sign(self, signing_key, signer, platform_version)
@@ -289,9 +298,22 @@ impl Sdk {
         trace!(hex = %hex::encode(state_transition.serialize_to_bytes()?), "document_create: transition bytes");
         trace!(transition = ?state_transition, "document_create: transition details");
 
-        let proof_result = state_transition
-            .broadcast_and_wait::<StateTransitionProofResult>(self, put_settings)
-            .await?;
+        // An indexOnly document keeps no row: its proof shows the entry the create leaves,
+        // which an earlier create with the same values would show too, so it cannot prove that
+        // this create executed. That is the strongest proof such a document has, so it is
+        // accepted rather than failing a create that landed.
+        let proof_result = if index_only {
+            state_transition
+                .broadcast_and_wait_for_affected_state::<StateTransitionProofResult>(
+                    self,
+                    put_settings,
+                )
+                .await?
+        } else {
+            state_transition
+                .broadcast_and_wait::<StateTransitionProofResult>(self, put_settings)
+                .await?
+        };
 
         match proof_result {
             StateTransitionProofResult::VerifiedDocuments(documents) => {

packages/rs-sdk/src/platform/documents/transitions/delete.rs

@@ -3,6 +3,7 @@ use crate::platform::transition::put_settings::PutSettings;
 use crate::platform::Identifier;
 use crate::{Error, Sdk};
 use dpp::data_contract::accessors::v0::DataContractV0Getters;
+use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters;
 use dpp::data_contract::document_type::action_fees::agreement::DocumentActionFeeAgreement;
 use dpp::data_contract::DataContract;
 use dpp::document::{Document, INITIAL_REVISION};
@@ -195,7 +196,6 @@ impl DocumentDeleteTransitionBuilder {
         ),
         Error,
     > {
-        use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters;
         use dpp::document::DocumentV0Getters;
 
         let document_type = self
@@ -320,7 +320,10 @@ impl Sdk {
     /// Deletes an existing document from the platform.
     ///
     /// This method broadcasts a document deletion transition to permanently remove
-    /// a document from the platform. The result confirms the deletion.
+    /// a document from the platform. The result confirms the deletion. For an
+    /// indexOnly document type the proof shows the document's entry gone at the
+    /// proof's block, not that this delete removed it: no stronger proof exists
+    /// for such a document.
     ///
     /// # Arguments
     ///
@@ -349,14 +352,32 @@ impl Sdk {
         let platform_version = self.version();
 
         let put_settings = delete_document_transition_builder.settings;
+        let index_only = delete_document_transition_builder
+            .data_contract
+            .document_type_for_name(&delete_document_transition_builder.document_type_name)
+            .map_err(|e| Error::Protocol(e.into()))?
+            .index_only();
 
         let state_transition = delete_document_transition_builder
             .sign(self, signing_key, signer, platform_version)
             .await?;
 
-        let proof_result = state_transition
-            .broadcast_and_wait::<StateTransitionProofResult>(self, put_settings)
-            .await?;
+        // An indexOnly document keeps no row: its proof shows the entry is gone, which it would
+        // also be had it never existed, so it cannot prove that this delete executed. That is the
+        // strongest proof such a document has, so it is accepted rather than failing a delete
+        // that landed.
+        let proof_result = if index_only {
+            state_transition
+                .broadcast_and_wait_for_affected_state::<StateTransitionProofResult>(
+                    self,
+                    put_settings,
+                )
+                .await?
+        } else {
+            state_transition
+                .broadcast_and_wait::<StateTransitionProofResult>(self, put_settings)
+                .await?
+        };
 
         match proof_result {
             StateTransitionProofResult::VerifiedDocuments(documents) => {

packages/rs-sdk/src/platform/transition/broadcast.rs

@@ -45,7 +45,9 @@ pub trait BroadcastStateTransition {
     /// transition executed. For the transition families whose proofs can
     /// only authenticate the affected state (balance top-ups, credit
     /// transfers and withdrawals, address funds movements, shields,
-    /// no-history token operations, key limits updates), this returns
+    /// no-history token operations, key limits updates, contract updates,
+    /// contract moderation and fee claims, and creates and deletes of
+    /// indexOnly documents), this returns
     /// [`Error::ExecutionNotProved`] — use
     /// [`wait_for_affected_state`](Self::wait_for_affected_state) for those
     /// flows and treat the result as a height-pinned snapshot.
@@ -395,7 +397,7 @@ pub fn require_execution_proved(
         StateTransitionProofGuarantee::ExecutionProved => Ok(result),
         StateTransitionProofGuarantee::AffectedState => Err(Error::ExecutionNotProved(
             format!(
-                "received a verified {} snapshot for this transition family; use the *_affected_state wait APIs and treat the result as a height-pinned snapshot",
+                "received a verified {} snapshot for this transition family; wait with the affected-state APIs instead (wait_for_affected_state in Rust, waitForAffectedState or broadcastAndWaitForAffectedState in JavaScript) and treat the result as a height-pinned snapshot",
                 result
             ),
         )),

packages/rs-sdk/src/platform/transition/put_document.rs

@@ -6,7 +6,7 @@ use crate::platform::transition::put_settings::PutSettings;
 use crate::{Error, Sdk};
 use dpp::dashcore::secp256k1::rand::rngs::StdRng;
 use dpp::dashcore::secp256k1::rand::{Rng, SeedableRng};
-use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters;
+use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters};
 use dpp::data_contract::document_type::methods::DocumentTypeV0Methods;
 use dpp::data_contract::document_type::DocumentType;
 use dpp::document::{Document, DocumentV0Getters, DocumentV0Setters, INITIAL_REVISION};
@@ -36,7 +36,10 @@ pub trait PutDocument<S: Signer<IdentityPublicKey>>: Waitable {
         settings: Option<PutSettings>,
     ) -> Result<StateTransition, Error>;
 
-    /// Puts a document on platform and waits for the confirmation proof
+    /// Puts a document on platform and waits for the confirmation proof. For an
+    /// indexOnly document type the proof shows the document's entry at the proof's
+    /// block, not that this put wrote it: no stronger proof exists for such a
+    /// document.
     #[allow(clippy::too_many_arguments)]
     async fn put_to_platform_and_wait_for_response(
         &self,
@@ -204,6 +207,7 @@ impl<S: Signer<IdentityPublicKey>> PutDocument<S> for Document {
         signer: &S,
         settings: Option<PutSettings>,
     ) -> Result<Document, Error> {
+        let index_only = document_type.index_only();
         let state_transition = self
             .put_to_platform(
                 sdk,
@@ -216,6 +220,13 @@ impl<S: Signer<IdentityPublicKey>> PutDocument<S> for Document {
             )
             .await?;
 
+        // An indexOnly document keeps no row: its proof shows the entry the create leaves, not
+        // that this create executed, and no stronger proof exists for it.
+        if index_only {
+            return wait_for_document_and_owner_balance(sdk, state_transition, settings)
+                .await
+                .map(|(document, _owner_balance)| document);
+        }
         Self::wait_for_response(sdk, state_transition, settings).await
     }
 }

packages/wasm-sdk/src/state_transitions/broadcast.rs

@@ -226,7 +226,9 @@ impl WasmSdk {
     /// whose proofs cannot be bound to the execution of one specific
     /// transition (balance top-ups, credit transfers and withdrawals,
     /// address funds movements, shields, no-history token operations, key
-    /// limits updates). This method accepts those outcomes instead. The result is a verified,
+    /// limits updates, contract updates, contract moderation and fee claims,
+    /// and creates and deletes of indexOnly documents). This method accepts
+    /// those outcomes instead. The result is a verified,
     /// height-pinned snapshot of the affected state — NOT evidence that this
     /// specific transition executed.
     ///

packages/wasm-sdk/src/state_transitions/document.rs

@@ -168,7 +168,10 @@ impl WasmSdk {
     ///
     /// @returns Promise resolving to the confirmed Document as Platform
     ///          committed it — its final `id` and the consensus-populated system fields
-    ///          (`$createdAt` and friends) included. Keep THIS instance
+    ///          (`$createdAt` and friends) included. For an indexOnly document type
+    ///          the proof shows the document's entry at the proof's block, not that
+    ///          this create wrote it: no stronger proof exists for such a document.
+    ///          Keep THIS instance
     ///          when you later intend to delete an indexOnly document
     ///          whose type requires `$createdAt`: the delete carries the
     ///          document's values, and the pre-broadcast wrapper never
@@ -447,7 +450,10 @@ impl WasmSdk {
     /// 3. Broadcasts and waits for confirmation
     ///
     /// @param options - Delete options including document (or document identifiers), identity key, and signer
-    /// @returns Promise that resolves when the document is deleted
+    /// @returns Promise that resolves when the document is deleted. For an indexOnly
+    ///          document type the proof shows the document's entry gone at the proof's
+    ///          block, not that this delete removed it: no stronger proof exists for
+    ///          such a document.
     #[wasm_bindgen(js_name = "documentDelete")]
     pub async fn document_delete(
         &self,