fix(sdk): validate batch base structure before signing

.gitignore

@@ -90,6 +90,8 @@ book/book/
 # gRPC coverage report
 grpc-coverage-report.txt
 
+# Git worktrees
+/worktrees/
 __pycache__/
 .claude/settings.local.json
 .claude/worktrees/

CHANGELOG.md

@@ -9,6 +9,15 @@
 * **sdk:** getSignableBytes is not compatible with sign and verify (#3048)
 * **platform:** update PlatformAddress encoding and HRP constants (#3059)
 * **platform:** 3.0 audit report fixes (#3053)
+* **swift-sdk:** `SDKError.protocolError(String)` associated values are
+  clean human-readable messages again (no embedded payload). FFI errors
+  with structured consensus details now throw `SDKDetailedError`, which
+  wraps the mapped `SDKError` plus a `consensusErrors` array; callers
+  that want the details should catch `SDKDetailedError` in addition to
+  `SDKError`. Pointer-based FFI helpers
+  (`SDKError.consensusErrors(fromDashSDKError:)` and
+  `SDKError.fromDashSDKErrorWithConsensusErrors(_:)`) remain available
+  before `dash_sdk_error_free`.
 * **sdk:** comprehensive Evo SDK refactoring (#2999)
 * upgrade bincode to 2.0.1 (#2991)
 
@@ -29,6 +38,7 @@
 * **dapi-grpc:** files generated outside sandbox
 * **dashmate:** differentiate service ports between networks to avoid conflicts ([#3085](https://github.com/dashpay/platform/issues/3085))
 * **platform:** 3.0 audit report fixes ([#3053](https://github.com/dashpay/platform/issues/3053))
+* **swift-sdk:** preserve structured consensus details in Swift state-transition helper errors
 * **sdk:** deserialization error due to outdated contract cache ([#3052](https://github.com/dashpay/platform/issues/3052))
 * **sdk:** getSignableBytes is not compatible with sign and verify ([#3048](https://github.com/dashpay/platform/issues/3048))
 * **sdk:** inconsistent document query operator ([#3039](https://github.com/dashpay/platform/issues/3039))

packages/rs-dpp/Cargo.toml

@@ -181,10 +181,17 @@ abci = [
 ]
 cbor = ["ciborium"]
 validation = [
+  "batch-base-structure-validation",
   "json-schema-validation",
   "value-conversion",
   "ed25519-dalek",
 ]
+# Narrow feature that compiles only `BatchTransition::validate_base_structure`
+# without pulling in json-schema-validation, value-conversion, or ed25519-dalek.
+# Useful for clients that need pre-broadcast base-structure checks without
+# the full validation toolchain. `state-transition-signing` enables this
+# transitively so constructor pre-sign validation is always present there.
+batch-base-structure-validation = []
 # TODO: Tring to remove regexp
 create-contested-document = []
 json-conversion = ["value-conversion", "platform-value/json", "json-object"]
@@ -243,6 +250,7 @@ state-transition-signing = [
   "state-transitions",
   "message-signing",
   "state-transition-validation",
+  "batch-base-structure-validation",
 ]
 vote-serialization = []
 vote-serde-conversion = ["serde-conversion"]

packages/rs-dpp/src/errors/consensus/basic/basic_error.rs

@@ -115,7 +115,15 @@ use crate::data_contract::errors::DataContractError;
 
 #[allow(clippy::large_enum_variant)]
 #[derive(
-    Error, Debug, PlatformSerialize, PlatformDeserialize, Encode, Decode, PartialEq, Clone,
+    Error,
+    Debug,
+    PlatformSerialize,
+    PlatformDeserialize,
+    Encode,
+    Decode,
+    PartialEq,
+    Clone,
+    strum::IntoStaticStr,
 )]
 pub enum BasicError {
     /*

packages/rs-dpp/src/errors/consensus/fee/fee_error.rs

@@ -7,7 +7,15 @@ use crate::errors::ProtocolError;
 use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
 
 #[derive(
-    Error, Debug, PartialEq, Encode, Decode, PlatformSerialize, PlatformDeserialize, Clone,
+    Error,
+    Debug,
+    PartialEq,
+    Encode,
+    Decode,
+    PlatformSerialize,
+    PlatformDeserialize,
+    Clone,
+    strum::IntoStaticStr,
 )]
 pub enum FeeError {
     /*

packages/rs-dpp/src/errors/consensus/signature/signature_error.rs

@@ -14,7 +14,15 @@ use crate::errors::ProtocolError;
 use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
 
 #[derive(
-    Error, Debug, PartialEq, Encode, Decode, PlatformSerialize, PlatformDeserialize, Clone,
+    Error,
+    Debug,
+    PartialEq,
+    Encode,
+    Decode,
+    PlatformSerialize,
+    PlatformDeserialize,
+    Clone,
+    strum::IntoStaticStr,
 )]
 pub enum SignatureError {
     /*

packages/rs-dpp/src/errors/consensus/state/state_error.rs

@@ -62,7 +62,15 @@ use crate::consensus::state::voting::vote_poll_not_found_error::VotePollNotFound
 use super::document::document_timestamps_are_equal_error::DocumentTimestampsAreEqualError;
 
 #[derive(
-    Error, Debug, PartialEq, Encode, Decode, PlatformSerialize, PlatformDeserialize, Clone,
+    Error,
+    Debug,
+    PartialEq,
+    Encode,
+    Decode,
+    PlatformSerialize,
+    PlatformDeserialize,
+    Clone,
+    strum::IntoStaticStr,
 )]
 pub enum StateError {
     /*

packages/rs-dpp/src/errors/protocol_error.rs

@@ -131,6 +131,9 @@ pub enum ProtocolError {
     #[error(transparent)]
     ConsensusError(Box<ConsensusError>),
 
+    #[error("Multiple consensus errors: {}", join_consensus_errors(.0))]
+    ConsensusErrors(Vec<ConsensusError>),
+
     #[error(transparent)]
     Document(Box<DocumentError>),
 
@@ -355,3 +358,14 @@ impl From<InvalidVectorSizeError> for ProtocolError {
         Self::InvalidVectorSizeError(err)
     }
 }
+
+/// Join the `Display` representation of every inner [`ConsensusError`] with
+/// `"; "`. Used by [`ProtocolError::ConsensusErrors`]'s `Display` impl so the
+/// rendered message is human-readable instead of a `Debug`-formatted `Vec`.
+fn join_consensus_errors(errors: &[ConsensusError]) -> String {
+    errors
+        .iter()
+        .map(ToString::to_string)
+        .collect::<Vec<_>>()
+        .join("; ")
+}

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_create_transition/mod.rs

@@ -2,6 +2,7 @@ mod convertible;
 pub mod from_document;
 pub mod v0;
 mod v0_methods;
+pub(crate) mod validate_structure;
 
 use crate::block::block_info::BlockInfo;
 use crate::data_contract::document_type::DocumentTypeRef;

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_create_transition/validate_structure/mod.rs

@@ -0,0 +1,44 @@
+use crate::state_transition::batch_transition::document_create_transition::validate_structure::v0::DocumentCreateTransitionStructureValidationV0;
+use crate::state_transition::batch_transition::DocumentCreateTransition;
+use crate::validation::SimpleConsensusValidationResult;
+use crate::ProtocolError;
+use platform_value::Identifier;
+use platform_version::version::PlatformVersion;
+
+mod v0;
+
+pub(crate) trait DocumentCreateTransitionStructureValidation {
+    fn validate_structure(
+        &self,
+        owner_id: Identifier,
+        platform_version: &PlatformVersion,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError>;
+}
+
+impl DocumentCreateTransitionStructureValidation for DocumentCreateTransition {
+    fn validate_structure(
+        &self,
+        owner_id: Identifier,
+        platform_version: &PlatformVersion,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError> {
+        // Dispatch via the DPP-owned version field. The drive-abci action
+        // validator has a separate field under
+        // `drive_abci.validation_and_processing.state_transitions.batch_state_transition`
+        // and is intentionally decoupled from this DPP/SDK pre-sign helper.
+        match platform_version
+            .dpp
+            .state_transitions
+            .documents
+            .documents_batch_transition
+            .validation
+            .document_create_transition_structure_validation
+        {
+            0 => self.validate_structure_v0(owner_id),
+            version => Err(ProtocolError::UnknownVersionMismatch {
+                method: "DocumentCreateTransition::validate_structure".to_string(),
+                known_versions: vec![0],
+                received: version,
+            }),
+        }
+    }
+}

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_create_transition/validate_structure/v0/mod.rs

@@ -0,0 +1,47 @@
+use crate::consensus::basic::document::InvalidDocumentTransitionIdError;
+use crate::consensus::basic::BasicError;
+use crate::consensus::ConsensusError;
+use crate::document::Document;
+use crate::state_transition::batch_transition::document_base_transition::document_base_transition_trait::DocumentBaseTransitionAccessors;
+use crate::state_transition::batch_transition::document_base_transition::v0::v0_methods::DocumentBaseTransitionV0Methods;
+use crate::state_transition::batch_transition::document_create_transition::v0::v0_methods::DocumentCreateTransitionV0Methods;
+use crate::state_transition::batch_transition::DocumentCreateTransition;
+use crate::validation::SimpleConsensusValidationResult;
+use crate::ProtocolError;
+use platform_value::Identifier;
+
+pub(super) trait DocumentCreateTransitionStructureValidationV0 {
+    fn validate_structure_v0(
+        &self,
+        owner_id: Identifier,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError>;
+}
+
+impl DocumentCreateTransitionStructureValidationV0 for DocumentCreateTransition {
+    fn validate_structure_v0(
+        &self,
+        owner_id: Identifier,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError> {
+        let (expected_id, invalid_id) = match self {
+            DocumentCreateTransition::V0(transition) => (
+                Document::generate_document_id_v0(
+                    &transition.base().data_contract_id(),
+                    &owner_id,
+                    transition.base().document_type_name(),
+                    &transition.entropy(),
+                ),
+                transition.base().id(),
+            ),
+        };
+
+        if invalid_id != expected_id {
+            return Ok(SimpleConsensusValidationResult::new_with_error(
+                ConsensusError::BasicError(BasicError::InvalidDocumentTransitionIdError(
+                    InvalidDocumentTransitionIdError::new(expected_id, invalid_id),
+                )),
+            ));
+        }
+
+        Ok(SimpleConsensusValidationResult::default())
+    }
+}

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/from_document.rs

@@ -4,6 +4,7 @@ use crate::prelude::IdentityNonce;
 use crate::ProtocolError;
 use platform_version::version::{FeatureVersion, PlatformVersion};
 
+use crate::state_transition::batch_transition::batched_transition::document_delete_transition::validate_structure::DocumentDeleteTransitionStructureValidation;
 use crate::state_transition::batch_transition::batched_transition::document_delete_transition::DocumentDeleteTransitionV0;
 use crate::state_transition::batch_transition::batched_transition::DocumentDeleteTransition;
 use crate::tokens::token_payment_info::TokenPaymentInfo;
@@ -27,15 +28,25 @@ impl DocumentDeleteTransition {
                 .bounds
                 .default_current_version,
         ) {
-            0 => Ok(DocumentDeleteTransitionV0::from_document(
-                document,
-                document_type,
-                token_payment_info,
-                identity_contract_nonce,
-                platform_version,
-                base_feature_version,
-            )?
-            .into()),
+            0 => {
+                let transition: DocumentDeleteTransition =
+                    DocumentDeleteTransitionV0::from_document(
+                        document,
+                        document_type,
+                        token_payment_info,
+                        identity_contract_nonce,
+                        platform_version,
+                        base_feature_version,
+                    )?
+                    .into();
+                if let Some(error) = transition
+                    .validate_structure(document_type, platform_version)?
+                    .errors_to_consensus_protocol_error()
+                {
+                    return Err(error);
+                }
+                Ok(transition)
+            }
             version => Err(ProtocolError::UnknownVersionMismatch {
                 method: "DocumentDeleteTransition::from_document".to_string(),
                 known_versions: vec![0],

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/mod.rs

@@ -1,6 +1,7 @@
 mod from_document;
 pub mod v0;
 pub mod v0_methods;
+pub(crate) mod validate_structure;
 
 use bincode::{Decode, Encode};
 use derive_more::{Display, From};

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/validate_structure/mod.rs

@@ -0,0 +1,40 @@
+use crate::data_contract::document_type::DocumentTypeRef;
+use crate::state_transition::batch_transition::batched_transition::document_delete_transition::validate_structure::v0::DocumentDeleteTransitionStructureValidationV0;
+use crate::state_transition::batch_transition::batched_transition::DocumentDeleteTransition;
+use crate::validation::SimpleConsensusValidationResult;
+use crate::ProtocolError;
+use platform_version::version::PlatformVersion;
+
+mod v0;
+
+pub(crate) trait DocumentDeleteTransitionStructureValidation {
+    fn validate_structure(
+        &self,
+        document_type: DocumentTypeRef,
+        platform_version: &PlatformVersion,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError>;
+}
+
+impl DocumentDeleteTransitionStructureValidation for DocumentDeleteTransition {
+    fn validate_structure(
+        &self,
+        document_type: DocumentTypeRef,
+        platform_version: &PlatformVersion,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError> {
+        match platform_version
+            .dpp
+            .state_transitions
+            .documents
+            .documents_batch_transition
+            .validation
+            .document_delete_transition_structure_validation
+        {
+            0 => self.validate_structure_v0(document_type),
+            version => Err(ProtocolError::UnknownVersionMismatch {
+                method: "DocumentDeleteTransition::validate_structure".to_string(),
+                known_versions: vec![0],
+                received: version,
+            }),
+        }
+    }
+}

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/validate_structure/v0/mod.rs

@@ -0,0 +1,34 @@
+use crate::consensus::basic::document::InvalidDocumentTransitionActionError;
+use crate::data_contract::document_type::accessors::DocumentTypeV0Getters;
+use crate::data_contract::document_type::DocumentTypeRef;
+use crate::state_transition::batch_transition::batched_transition::DocumentDeleteTransition;
+use crate::validation::SimpleConsensusValidationResult;
+use crate::ProtocolError;
+
+pub(super) trait DocumentDeleteTransitionStructureValidationV0 {
+    fn validate_structure_v0(
+        &self,
+        document_type: DocumentTypeRef,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError>;
+}
+
+impl DocumentDeleteTransitionStructureValidationV0 for DocumentDeleteTransition {
+    fn validate_structure_v0(
+        &self,
+        document_type: DocumentTypeRef,
+    ) -> Result<SimpleConsensusValidationResult, ProtocolError> {
+        // Mirrors the drive-abci action validator deletability check;
+        // contract-local and safe pre-sign.
+        if !document_type.documents_can_be_deleted() {
+            return Ok(SimpleConsensusValidationResult::new_with_error(
+                InvalidDocumentTransitionActionError::new(format!(
+                    "documents of type {} can not be deleted",
+                    document_type.name()
+                ))
+                .into(),
+            ));
+        }
+
+        Ok(SimpleConsensusValidationResult::default())
+    }
+}