fix(rs-sdk): decode consensus errors from drive-error-data-bin metadata fallback

lklimek · claude · lklimek · commit 4aa4910ee6f7 · 2026-03-16T16:49:57.000+01:00
When `dash-serialized-consensus-error-bin` gRPC metadata is absent (e.g.
broadcast errors routed through Tenderdash), fall back to decoding
`drive-error-data-bin` CBOR metadata to extract the consensus error bytes.

Security hardening:
- CBOR recursion limit (16) via `from_reader_with_recursion_limit`
- Payload size cap (8 KiB) before deserialization
- Graceful fallthrough on any decode failure

Includes 9 new tests with real-world DET log fixtures proving the fix
works with production error data (GroveDB storage errors, DPP state
errors with consensus_error bytes).

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/packages/rs-sdk/src/error.rs b/packages/rs-sdk/src/error.rs
@@ -17,6 +17,21 @@ use rs_dapi_client::{CanRetry, DapiClientError, ExecutionError};
 use std::fmt::Debug;
 use std::time::Duration;
 
+/// Maximum size of `drive-error-data-bin` metadata to parse.
+/// gRPC metadata is typically limited to 8 KiB, but we enforce explicitly.
+const MAX_DRIVE_ERROR_METADATA_BYTES: usize = 8 * 1024;
+
+/// CBOR recursion limit for parsing drive error metadata from untrusted DAPI nodes.
+const DRIVE_ERROR_CBOR_RECURSION_LIMIT: usize = 16;
+
+/// CBOR structure mirroring the server-side `TenderdashStatus` layout
+/// found in `drive-error-data-bin` gRPC metadata.
+#[derive(serde::Serialize, serde::Deserialize)]
+struct DriveErrorData {
+    #[serde(default)]
+    consensus_error: Option<Vec<u8>>,
+}
+
 /// Error type for the SDK
 // TODO: Propagate server address and retry information so that the user can retrieve it
 #[allow(clippy::large_enum_variant)]
@@ -184,6 +199,43 @@ impl From<DapiClientError> for Error {
                         Self::Generic(format!("Invalid consensus error encoding: {e}"))
                     });
             }
+            // Fallback: try drive-error-data-bin (CBOR-encoded TenderdashStatus).
+            // SECURITY: bytes originate from a potentially untrusted DAPI node.
+            // Apply strict size and recursion limits before deserializing.
+            if let Some(drive_error_value) = status.metadata().get_bin("drive-error-data-bin") {
+                if let Ok(bytes) = drive_error_value.to_bytes() {
+                    if bytes.len() > MAX_DRIVE_ERROR_METADATA_BYTES {
+                        tracing::debug!(
+                            len = bytes.len(),
+                            "drive-error-data-bin metadata exceeds size limit, skipping"
+                        );
+                    } else if let Ok(drive_error) =
+                        ciborium::de::from_reader_with_recursion_limit::<DriveErrorData, _>(
+                            bytes.as_ref(),
+                            DRIVE_ERROR_CBOR_RECURSION_LIMIT,
+                        )
+                    {
+                        if let Some(consensus_bytes) = drive_error.consensus_error {
+                            return ConsensusError::deserialize_from_bytes(&consensus_bytes)
+                                .map(|ce| {
+                                    Self::Protocol(ProtocolError::ConsensusError(Box::new(ce)))
+                                })
+                                .unwrap_or_else(|e| {
+                                    tracing::debug!(
+                                        "Failed to deserialize consensus error from drive-error-data-bin: {}",
+                                        e
+                                    );
+                                    Self::Protocol(e)
+                                });
+                        }
+                    } else {
+                        tracing::debug!("Failed to CBOR-decode drive-error-data-bin metadata");
+                    }
+                } else {
+                    tracing::debug!("Failed to decode drive-error-data-bin metadata bytes");
+                }
+            }
+
             // Otherwise we parse the error code and act accordingly
             if status.code() == Code::AlreadyExists {
                 return Self::AlreadyExists(status.message().to_string());
@@ -371,6 +423,330 @@ mod tests {
             );
         }
 
+        #[test]
+        fn test_consensus_error_from_drive_error_data_bin() {
+            let platform_version = PlatformVersion::latest();
+
+            let consensus_error = ConsensusError::BasicError(
+                BasicError::IdentityAssetLockProofLockedTransactionMismatchError(
+                    IdentityAssetLockProofLockedTransactionMismatchError::new(
+                        Txid::from_byte_array([0; 32]),
+                        Txid::from_byte_array([1; 32]),
+                    ),
+                ),
+            );
+
+            let consensus_error_bytes = consensus_error
+                .serialize_to_bytes_with_platform_version(platform_version)
+                .expect("serialize consensus error to bytes");
+
+            // Build CBOR payload matching TenderdashStatus struct
+            let drive_error_data = DriveErrorData {
+                consensus_error: Some(consensus_error_bytes),
+            };
+            let mut cbor_bytes = Vec::new();
+            ciborium::ser::into_writer(&drive_error_data, &mut cbor_bytes).expect("serialize CBOR");
+
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&cbor_bytes),
+            );
+            // No dash-serialized-consensus-error-bin set
+
+            let status =
+                dapi_grpc::tonic::Status::with_metadata(Code::Internal, "Drive error", metadata);
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            assert_matches!(
+                sdk_error,
+                Error::Protocol(ProtocolError::ConsensusError(e)) if matches!(*e, ConsensusError::BasicError(
+                    BasicError::IdentityAssetLockProofLockedTransactionMismatchError(_)
+                ))
+            );
+        }
+
+        #[test]
+        fn test_consensus_error_primary_preferred_over_fallback() {
+            let platform_version = PlatformVersion::latest();
+
+            let consensus_error = ConsensusError::BasicError(
+                BasicError::IdentityAssetLockProofLockedTransactionMismatchError(
+                    IdentityAssetLockProofLockedTransactionMismatchError::new(
+                        Txid::from_byte_array([0; 32]),
+                        Txid::from_byte_array([1; 32]),
+                    ),
+                ),
+            );
+
+            let consensus_error_bytes = consensus_error
+                .serialize_to_bytes_with_platform_version(platform_version)
+                .expect("serialize consensus error to bytes");
+
+            // Set primary metadata key
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "dash-serialized-consensus-error-bin",
+                MetadataValue::from_bytes(&consensus_error_bytes),
+            );
+
+            // Also set fallback with garbage CBOR (should not be reached)
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&[0xDE, 0xAD]),
+            );
+
+            let status =
+                dapi_grpc::tonic::Status::with_metadata(Code::InvalidArgument, "Test", metadata);
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            // Should succeed via primary path, not fail on garbage fallback
+            assert_matches!(
+                sdk_error,
+                Error::Protocol(ProtocolError::ConsensusError(e)) if matches!(*e, ConsensusError::BasicError(
+                    BasicError::IdentityAssetLockProofLockedTransactionMismatchError(_)
+                ))
+            );
+        }
+
+        #[test]
+        fn test_drive_error_data_bin_without_consensus_error() {
+            let drive_error_data = DriveErrorData {
+                consensus_error: None,
+            };
+            let mut cbor_bytes = Vec::new();
+            ciborium::ser::into_writer(&drive_error_data, &mut cbor_bytes).expect("serialize CBOR");
+
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&cbor_bytes),
+            );
+
+            let status = dapi_grpc::tonic::Status::with_metadata(
+                Code::Internal,
+                "some drive error",
+                metadata,
+            );
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            // Should fall through to DapiClientError since consensus_error is None
+            assert_matches!(sdk_error, Error::DapiClientError(_));
+        }
+
+        #[test]
+        fn test_drive_error_data_bin_invalid_cbor() {
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&[0xFF, 0xFE, 0xFD]),
+            );
+
+            let status = dapi_grpc::tonic::Status::with_metadata(
+                Code::Internal,
+                "some drive error",
+                metadata,
+            );
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            // Should fall through gracefully to DapiClientError
+            assert_matches!(sdk_error, Error::DapiClientError(_));
+        }
+
+        #[test]
+        fn test_drive_error_data_bin_valid_cbor_invalid_consensus_bytes() {
+            // Valid CBOR envelope, but the inner consensus_error bytes are corrupt.
+            // Expected: returns Protocol error (deserialization failure), NOT DapiClientError.
+            // This documents the current behavior and ensures it does not silently regress.
+            let corrupt_consensus_bytes: Vec<u8> = vec![0xAA, 0xBB, 0xCC, 0xDD, 0xEE];
+            let drive_error_data = DriveErrorData {
+                consensus_error: Some(corrupt_consensus_bytes),
+            };
+            let mut cbor_bytes = Vec::new();
+            ciborium::ser::into_writer(&drive_error_data, &mut cbor_bytes).expect("serialize CBOR");
+
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&cbor_bytes),
+            );
+
+            let status =
+                dapi_grpc::tonic::Status::with_metadata(Code::Internal, "drive error", metadata);
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            // Corrupt inner bytes cause deserialization failure; returned as Protocol error
+            assert_matches!(sdk_error, Error::Protocol(_));
+        }
+
+        #[test]
+        fn test_real_world_internal_error_with_null_consensus_error() {
+            // Real-world fixture: gRPC Internal (13) error from DAPI node.
+            // drive-error-data-bin CBOR = {code: 13, message: <base64 inner>, consensus_error: null}
+            // This is a GroveDB storage error ("unique key already exists"), NOT a DPP
+            // ConsensusError — so consensus_error is null and the fallback should
+            // gracefully fall through to DapiClientError.
+            let drive_error_data_bytes = base64::engine::general_purpose::STANDARD
+                .decode(concat!(
+                    "o2Rjb2RlDWdtZXNzYWdleQEYb1dkdFpYTnpZV2RsZU1kemRHOXlZV2RsT2lCcBlp",
+                    "R1Z1ZEdsMGVUb2dZU0IxYm1seGRXVWdhMlY1SUhkcGRHZ2dkR2hoZENCaFlYTm9J",
+                    "R0ZzY21WaFpIa2daWGhwYzNSek9pQjBhR1VnYTJWNUlHRnNjbVZoWkhrZ1pYaHBj",
+                    "M1J6SUdsdUlIUm9aU0IxYm1seGRXVWdjMlYwSUZzeU16SXNJRFExTENBeE1Ua3NJ",
+                    "REV6Tnl3Z01UWXhMQ0F4TkRNc0lERTFMQ0F4Tnprc0lESXpOU3dnT1Rnc0lERXdN",
+                    "U3dnTWpVeExDQXlOVEVzSURFeE1Dd2dNVE15TENBek5Td2dNVFE1TENBNE5Dd2dN",
+                    "VFEzTENBeE1qUmRvY29uc2Vuc3VzX2Vycm9y9g==",
+                ))
+                .expect("decode fixture base64");
+
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&drive_error_data_bytes),
+            );
+
+            let status = dapi_grpc::tonic::Status::with_metadata(
+                Code::Internal,
+                "storage: identity: a unique key with that hash already exists",
+                metadata,
+            );
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            // consensus_error is null in the CBOR, so fallback should fall through
+            // to DapiClientError (not panic, not return a ConsensusError)
+            assert_matches!(sdk_error, Error::DapiClientError(_));
+        }
+
+        #[test]
+        fn test_real_world_internal_error_non_unique_set() {
+            // Real-world fixture from DET logs: gRPC Internal (13) error.
+            // drive-error-data-bin CBOR = {code: 13, message: <storage error>, consensus_error: null}
+            // Storage error: "the key already exists in the non unique set [135, 202, ...]"
+            // consensus_error is null => should fall through to DapiClientError.
+            let drive_error_data_bytes = base64::engine::general_purpose::STANDARD
+                .decode(concat!(
+                    "o2Rjb2RlDWdtZXNzYWdleQEYb1dkdFpYTnpZV2RsZU1WemRHOXlZV2RsT2lCcFpH",
+                    "VnVkR2wwZVRvZ1lTQjFibWx4ZFdVZ2EyVjVJSGRwZEdnZ2RHaGhkQ0JvWVhOb0lH",
+                    "RnNjbVZoWkhrZ1pYaHBjM1J6T2lCMGFHVWdhMlY1SUdGc2NtVmhaSGtnWlhocGMz",
+                    "UnpJR2x1SUhSb1pTQnViMjRnZFc1cGNYVmxJSE5sZENCYk1UTTFMQ0F5TURJc0lE",
+                    "RTNNaXdnTlRNc0lERTNOaXdnTkRVc0lERTVNU3dnTWpjc0lEVXdMQ0F4TWl3Z05U",
+                    "QXNJREl4TlN3Z05qVXNJREV5TkN3Z01UUTNMQ0F6TENBeU1EZ3NJRFlzSURJeU5p",
+                    "d2dNVFV4WFE9PW9jb25zZW5zdXNfZXJyb3L2",
+                ))
+                .expect("decode fixture base64");
+
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&drive_error_data_bytes),
+            );
+
+            let status = dapi_grpc::tonic::Status::with_metadata(
+                Code::Internal,
+                "storage: identity: a unique key with that hash already exists in the non unique set",
+                metadata,
+            );
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            assert_matches!(sdk_error, Error::DapiClientError(_));
+        }
+
+        #[test]
+        fn test_real_world_dpp_error_with_both_metadata_keys() {
+            // Real-world fixture from DET logs: a DPP state error where BOTH
+            // `dash-serialized-consensus-error-bin` AND `drive-error-data-bin`
+            // are present. The primary path (dash-serialized-consensus-error-bin)
+            // should be used to produce Error::Protocol(ConsensusError).
+            let direct_consensus_bytes = base64::engine::general_purpose::STANDARD
+                .decode(concat!(
+                    "ATggUDAtq56qZ8U5oJOS70tCvH+rkum8",
+                    "tkQRw3Rlsru4TOkA/AU+xgD8BT7GAPwO",
+                    "XV5A",
+                ))
+                .expect("decode direct consensus error base64");
+
+            let drive_error_data_bytes = base64::engine::general_purpose::STANDARD
+                .decode(concat!(
+                    "o2Rjb2RlGSkiZ21lc3NhZ2V4oG9XUmtZWFJob1c5elpYSnBZV3hwZW1Wa1JYSnli",
+                    "M0tZTXdFWU9CZ2dHRkFZTUJpdEdLc1luaGlxR0djWXhSZzVHS0FZa3hpU0dPOFlT",
+                    "eGhDR0x3WWZ4aXJHSklZNlJpOEdMWVlSQkVZd3hoMEdHVVlzaGk3R0xnWVRCanBB",
+                    "Qmo0QlJnK0dNWUFHUHdGR0Q0WXhnQVkvQTRZWFJoZUdFQT1vY29uc2Vuc3VzX2Vy",
+                    "cm9ymDMBGDgYIBhQGDAYrRirGJ4YqhhnGMUYORigGJMYkhjvGEsYQhi8GH8YqxiS",
+                    "GOkYvBi2GEQRGMMYdBhlGLIYuxi4GEwY6QAY/AUYPhjGABj8BRg+GMYAGPwOGF0Y",
+                    "XhhA",
+                ))
+                .expect("decode drive-error-data-bin base64");
+
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "dash-serialized-consensus-error-bin",
+                MetadataValue::from_bytes(&direct_consensus_bytes),
+            );
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&drive_error_data_bytes),
+            );
+
+            let status = dapi_grpc::tonic::Status::with_metadata(
+                Code::InvalidArgument,
+                "state transition error",
+                metadata,
+            );
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            // Primary path should succeed; result is a ConsensusError
+            assert_matches!(sdk_error, Error::Protocol(ProtocolError::ConsensusError(_)));
+        }
+
+        #[test]
+        fn test_real_world_dpp_error_fallback_only() {
+            // Real-world fixture from DET logs: only `drive-error-data-bin` present.
+            // Simulates the case where `dash-serialized-consensus-error-bin` is absent
+            // and our CBOR fallback must extract consensus_error bytes from the CBOR
+            // array-of-integers encoding.
+            //
+            // NOTE: ciborium serializes Vec<u8> as a CBOR array of integers, and this
+            // is how production Drive encodes the field. If ciborium cannot deserialize
+            // a CBOR array of integers back into Vec<u8>, this test will reveal that.
+            let drive_error_data_bytes = base64::engine::general_purpose::STANDARD
+                .decode(concat!(
+                    "o2Rjb2RlGSkiZ21lc3NhZ2V4oG9XUmtZWFJob1c5elpYSnBZV3hwZW1Wa1JYSnli",
+                    "M0tZTXdFWU9CZ2dHRkFZTUJpdEdLc1luaGlxR0djWXhSZzVHS0FZa3hpU0dPOFlT",
+                    "eGhDR0x3WWZ4aXJHSklZNlJpOEdMWVlSQkVZd3hoMEdHVVlzaGk3R0xnWVRCanBB",
+                    "Qmo0QlJnK0dNWUFHUHdGR0Q0WXhnQVkvQTRZWFJoZUdFQT1vY29uc2Vuc3VzX2Vy",
+                    "cm9ymDMBGDgYIBhQGDAYrRirGJ4YqhhnGMUYORigGJMYkhjvGEsYQhi8GH8YqxiS",
+                    "GOkYvBi2GEQRGMMYdBhlGLIYuxi4GEwY6QAY/AUYPhjGABj8BRg+GMYAGPwOGF0Y",
+                    "XhhA",
+                ))
+                .expect("decode drive-error-data-bin base64");
+
+            let mut metadata = MetadataMap::new();
+            metadata.insert_bin(
+                "drive-error-data-bin",
+                MetadataValue::from_bytes(&drive_error_data_bytes),
+            );
+            // No dash-serialized-consensus-error-bin — forces fallback path
+
+            let status = dapi_grpc::tonic::Status::with_metadata(
+                Code::InvalidArgument,
+                "state transition error",
+                metadata,
+            );
+            let error = DapiClientError::Transport(TransportError::Grpc(status));
+            let sdk_error = Error::from(error);
+
+            // The CBOR fallback should extract consensus_error bytes from the
+            // array-of-integers encoding and produce a ConsensusError.
+            assert_matches!(sdk_error, Error::Protocol(ProtocolError::ConsensusError(_)));
+        }
+
         #[test]
         fn test_consensus_error_with_fixture() {
             let consensus_error_bytes = base64::engine::general_purpose::STANDARD.decode("ATUgJOJEYbuHBqyTeApO/ptxQ8IAw8nm9NbGROu1nyE/kqcgDTlFeUG0R4wwVcbZJMFErL+VSn63SUpP49cequ3fsKw=").expect("decode base64");
