fix: show user-friendly error for duplicate identity keys (#729)

lklimek · claude · web-flow · commit ece36597c693 · 2026-03-11T13:53:12.000+01:00
* fix: show user-friendly error for duplicate identity keys (#714) Replace raw base64-encoded CBOR error with actionable messages when adding a duplicate key to an identity. Match structured SDK error variants (ConsensusError::StateError) instead of string parsing. - Add TaskError variants: DuplicateIdentityPublicKey, DuplicateIdentityPublicKeyId, IdentityPublicKeyContractBoundsConflict - Add broadcast_error_message() helper matching both SDK error paths (StateTransitionBroadcastError and Protocol/ConsensusError) - 5 unit tests covering all variants + fallback - Manual test scenarios document Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: correct error messages — duplicate keys are globally unique, not per-identity DuplicatedIdentityPublicKeyStateError and DuplicatedIdentityPublicKeyIdStateError are platform-wide uniqueness constraints, not per-identity. Updated error messages to reflect that keys must be globally unique across all identities. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: remove incorrect "globally unique" claim from error messages Only unique key types (ECDSA_SECP256K1, BLS12_381) require platform-wide uniqueness. Non-unique types (ECDSA_HASH160, BIP13_SCRIPT_HASH, EDDSA_25519_HASH160) can be shared across identities. Simplified messages to avoid misleading users about key uniqueness rules. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/docs/ai-design/2026-03-11-duplicate-key-error/manual-test-scenarios.md b/docs/ai-design/2026-03-11-duplicate-key-error/manual-test-scenarios.md
@@ -0,0 +1,177 @@
+# Manual Test Scenarios: Duplicate Key Error Handling (Issue #714)
+
+Covers the fix for showing user-friendly error messages when adding a duplicate
+key to an identity, instead of raw base64-encoded CBOR.
+
+---
+
+## Prerequisites (all scenarios)
+
+- Dash Evo Tool running and connected to **Testnet** (or Devnet).
+- A funded **wallet** loaded in the application.
+- An **identity** registered on the network with at least one existing key
+  (ECDSA_SECP256K1 AUTHENTICATION MASTER is the default).
+- The identity's master private key is available (wallet unlocked or key known).
+
+---
+
+## Scenario 1: Adding a key with the same public key data (DuplicatedIdentityPublicKeyStateError)
+
+### Goal
+
+Verify the app displays a clear, actionable message when the user tries to add
+a key whose public key data already exists on the identity.
+
+### Steps
+
+1. Open **Identities** screen and select the target identity.
+2. Click **Keys** to view the identity's existing keys.
+3. Note the public key data of an existing key (e.g., copy the hex value of key
+   ID 0).
+4. Click **Add Key**.
+5. Set **Purpose** to `AUTHENTICATION`, **Security Level** to `HIGH`,
+   **Key Type** to `ECDSA_SECP256K1` (or match the existing key's type).
+6. In the **Private key (hex)** field, enter the exact same private key that
+   corresponds to the existing public key on the identity.
+7. Click the **Add Key** button to submit.
+
+### Expected Result
+
+- An **error banner** appears at the top of the screen with the message:
+  > This public key is already registered on the platform. Try a different key.
+- The message is plain text -- no base64, no CBOR encoding, no raw error dump.
+- The banner type is **Error** (red/error styling).
+- The app does **not** crash or freeze.
+- The **Add Key** form remains accessible so the user can correct the input and
+  retry.
+
+---
+
+## Scenario 2: Adding a key with a conflicting key ID (DuplicatedIdentityPublicKeyIdStateError)
+
+### Goal
+
+Verify the app displays a clear message when a key ID collision occurs.
+
+### Context
+
+This error is less likely via the GUI because the app auto-assigns the next
+available key ID. It can occur if the identity state is out of sync (e.g.,
+another client added a key concurrently). To trigger it manually, a modified
+client or direct Platform interaction may be needed. This scenario validates the
+error display path regardless of trigger.
+
+### Steps
+
+1. Open **Identities** screen and select the target identity.
+2. Click **Keys**, then **Add Key**.
+3. Fill in a valid new key (different key data from existing keys).
+4. Arrange for the key ID to collide with an existing key ID (this may require
+   a race condition where another client adds a key between nonce fetch and
+   broadcast, or direct Platform API manipulation).
+5. Submit the **Add Key** request.
+
+### Expected Result
+
+- An **error banner** appears with the message:
+  > This key hash is already registered on the platform. Try a different key.
+- The message is plain text -- no encoded data.
+- The banner type is **Error**.
+- The app does **not** crash.
+- The user can dismiss the banner and retry.
+
+---
+
+## Scenario 3: Adding a key that conflicts with unique contract bounds (IdentityPublicKeyAlreadyExistsForUniqueContractBoundsError)
+
+### Goal
+
+Verify the app displays a clear message including the conflicting contract ID
+when a key violates unique contract bounds.
+
+### Steps
+
+1. Open **Identities** screen and select the target identity.
+2. Click **Keys**, then **Add Key**.
+3. Check the **Contract bounds** checkbox.
+4. Enter a valid **Contract ID** for a contract that enforces unique key bounds.
+5. Set the **Purpose** and **Security Level** to match an existing key that is
+   already bound to the same contract.
+6. Generate or enter a new private key.
+7. Click the **Add Key** button to submit.
+
+### Expected Result
+
+- An **error banner** appears with the message:
+  > This key conflicts with an existing key bound to contract \<contract-id\>. Use a different key or purpose.
+
+  where `<contract-id>` is the actual identifier of the conflicting contract
+  (not a placeholder, not encoded).
+- The message is plain text -- no base64, no CBOR.
+- The banner type is **Error**.
+- The app does **not** crash.
+- The user can change the **Purpose**, **Contract ID**, or key data and retry.
+
+---
+
+## Scenario 4: Fallback for unrecognized broadcast errors
+
+### Goal
+
+Verify that broadcast errors not matching the three handled patterns still
+display a readable message (prefixed with "Broadcasting error:") rather than
+crashing.
+
+### Steps
+
+1. Open **Identities** screen and select the target identity.
+2. Click **Keys**, then **Add Key**.
+3. Trigger a broadcast failure that is NOT a duplicate key error (e.g.,
+   disconnect from the network mid-broadcast, or submit with insufficient
+   identity balance for the fee).
+4. Observe the error display.
+
+### Expected Result
+
+- An **error banner** appears with a message starting with:
+  > Broadcasting error: ...
+- The remaining text may be technical but must not contain raw base64 CBOR
+  blobs.
+- The app does **not** crash.
+- The user can retry.
+
+---
+
+## Scenario 5: Successful key addition after a duplicate key error
+
+### Goal
+
+Verify the app recovers gracefully and allows a successful operation after a
+prior duplicate key error.
+
+### Steps
+
+1. Reproduce **Scenario 1** to trigger the duplicate key error banner.
+2. Observe that the error banner is displayed.
+3. Change the **Private key (hex)** field to a new, unique private key.
+4. Click the **Add Key** button again.
+
+### Expected Result
+
+- The duplicate key error banner is dismissed/replaced.
+- A progress/info banner may appear while the transaction broadcasts.
+- On success, a **success banner** appears confirming the key was added,
+  including fee information.
+- The new key appears in the identity's key list.
+- No residual error state from the previous failed attempt.
+
+---
+
+## Edge Cases
+
+| Case | Action | Expected |
+|------|--------|----------|
+| Double-click Add Key | Click Add Key rapidly twice | Only one broadcast attempt; no duplicate submission |
+| Wallet locks during broadcast | Lock wallet (if possible) after clicking Add Key | Graceful error, no crash |
+| Network disconnect during broadcast | Disable network after clicking Add Key | Timeout or connection error displayed as banner, not raw panic |
+| Very long contract ID in error | Trigger Scenario 3 with a valid 256-bit identifier | Full contract ID shown in the message, no truncation |
diff --git a/src/backend_task/error.rs b/src/backend_task/error.rs
@@ -60,6 +60,20 @@ pub enum TaskError {
     /// Callers should retry the failed operation.
     #[error("{0}")]
     MustRetry(String),
+
+    /// Duplicate identity public key — the key data already exists on the platform.
+    #[error("This public key is already registered on the platform. Try a different key.")]
+    DuplicateIdentityPublicKey,
+
+    /// Duplicate identity public key ID — the key hash is already taken platform-wide.
+    #[error("This key hash is already registered on the platform. Try a different key.")]
+    DuplicateIdentityPublicKeyId,
+
+    /// Identity public key conflicts with an existing key's unique contract bounds.
+    #[error(
+        "This key conflicts with an existing key bound to contract {contract_id}. Use a different key or purpose."
+    )]
+    IdentityPublicKeyContractBoundsConflict { contract_id: String },
 }
 
 impl From<String> for TaskError {
diff --git a/src/backend_task/identity/add_key_to_identity.rs b/src/backend_task/identity/add_key_to_identity.rs
@@ -1,11 +1,16 @@
 use super::BackendTaskSuccessResult;
 use crate::backend_task::FeeResult;
+use crate::backend_task::error::TaskError;
 use crate::context::AppContext;
 use crate::model::fee_estimation::PlatformFeeEstimator;
 use crate::model::qualified_identity::PrivateKeyTarget::PrivateKeyOnMainIdentity;
 use crate::model::qualified_identity::QualifiedIdentity;
 use crate::model::qualified_identity::qualified_identity_public_key::QualifiedIdentityPublicKey;
+use dash_sdk::Error as SdkError;
 use dash_sdk::Sdk;
+use dash_sdk::dpp::ProtocolError;
+use dash_sdk::dpp::consensus::ConsensusError;
+use dash_sdk::dpp::consensus::state::state_error::StateError;
 use dash_sdk::dpp::identity::accessors::{IdentityGettersV0, IdentitySettersV0};
 use dash_sdk::dpp::identity::identity_public_key::accessors::v0::{
     IdentityPublicKeyGettersV0, IdentityPublicKeySettersV0,
@@ -17,6 +22,36 @@ use dash_sdk::dpp::state_transition::proof_result::StateTransitionProofResult;
 use dash_sdk::platform::transition::broadcast::BroadcastStateTransition;
 use dash_sdk::platform::{Fetch, Identity};
 
+fn broadcast_error_message(error: &SdkError) -> String {
+    let consensus_error = match error {
+        SdkError::StateTransitionBroadcastError(broadcast_err) => broadcast_err.cause.as_ref(),
+        SdkError::Protocol(ProtocolError::ConsensusError(ce)) => Some(ce.as_ref()),
+        _ => None,
+    };
+
+    if let Some(ce) = consensus_error {
+        match ce {
+            ConsensusError::StateError(StateError::DuplicatedIdentityPublicKeyStateError(_)) => {
+                return TaskError::DuplicateIdentityPublicKey.to_string();
+            }
+            ConsensusError::StateError(StateError::DuplicatedIdentityPublicKeyIdStateError(_)) => {
+                return TaskError::DuplicateIdentityPublicKeyId.to_string();
+            }
+            ConsensusError::StateError(
+                StateError::IdentityPublicKeyAlreadyExistsForUniqueContractBoundsError(e),
+            ) => {
+                return TaskError::IdentityPublicKeyContractBoundsConflict {
+                    contract_id: format!("{}", e.contract_id()),
+                }
+                .to_string();
+            }
+            _ => {}
+        }
+    }
+
+    format!("Broadcasting error: {}", error)
+}
+
 impl AppContext {
     pub(super) async fn add_key_to_identity(
         &self,
@@ -69,7 +104,7 @@ impl AppContext {
         let result = state_transition
             .broadcast_and_wait(sdk, None)
             .await
-            .map_err(|e| format!("Broadcasting error: {}", e))?;
+            .map_err(|ref e| broadcast_error_message(e))?;
 
         // Log and handle the proof result
         tracing::info!("AddKeyToIdentity proof result: {}", result);
@@ -126,3 +161,86 @@ impl AppContext {
             .map_err(|e| format!("Database error: {}", e))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use dash_sdk::dpp::consensus::state::identity::duplicated_identity_public_key_id_state_error::DuplicatedIdentityPublicKeyIdStateError;
+    use dash_sdk::dpp::consensus::state::identity::duplicated_identity_public_key_state_error::DuplicatedIdentityPublicKeyStateError;
+    use dash_sdk::dpp::consensus::state::identity::identity_public_key_already_exists_for_unique_contract_bounds_error::IdentityPublicKeyAlreadyExistsForUniqueContractBoundsError;
+    use dash_sdk::dpp::identity::Purpose;
+    use dash_sdk::dpp::identifier::Identifier;
+
+    #[test]
+    fn test_duplicate_public_key_error() {
+        let consensus =
+            ConsensusError::from(DuplicatedIdentityPublicKeyStateError::new(vec![1, 2]));
+        let sdk_err = SdkError::from(consensus);
+        let msg = broadcast_error_message(&sdk_err);
+        assert_eq!(
+            msg,
+            "This public key is already registered on the platform. Try a different key."
+        );
+    }
+
+    #[test]
+    fn test_duplicate_public_key_id_error() {
+        let consensus = ConsensusError::from(DuplicatedIdentityPublicKeyIdStateError::new(vec![3]));
+        let sdk_err = SdkError::from(consensus);
+        let msg = broadcast_error_message(&sdk_err);
+        assert_eq!(
+            msg,
+            "This key hash is already registered on the platform. Try a different key."
+        );
+    }
+
+    #[test]
+    fn test_contract_bounds_conflict_error() {
+        let contract_id = Identifier::random();
+        let identity_id = Identifier::random();
+        let consensus = ConsensusError::from(
+            IdentityPublicKeyAlreadyExistsForUniqueContractBoundsError::new(
+                identity_id,
+                contract_id,
+                Purpose::AUTHENTICATION,
+                2,
+                1,
+            ),
+        );
+        let sdk_err = SdkError::from(consensus);
+        let msg = broadcast_error_message(&sdk_err);
+        assert_eq!(
+            msg,
+            format!(
+                "This key conflicts with an existing key bound to contract {}. Use a different key or purpose.",
+                contract_id
+            )
+        );
+    }
+
+    #[test]
+    fn test_broadcast_error_with_cause_duplicate_key() {
+        // Test the StateTransitionBroadcastError path (the actual production path
+        // when Platform returns a structured broadcast error with a consensus cause).
+        let consensus = ConsensusError::from(DuplicatedIdentityPublicKeyStateError::new(vec![1]));
+        let broadcast_err = dash_sdk::error::StateTransitionBroadcastError {
+            code: 40206,
+            message: "duplicate key".to_string(),
+            cause: Some(consensus),
+        };
+        let sdk_err = SdkError::StateTransitionBroadcastError(broadcast_err);
+        let msg = broadcast_error_message(&sdk_err);
+        assert_eq!(
+            msg,
+            "This public key is already registered on the platform. Try a different key."
+        );
+    }
+
+    #[test]
+    fn test_unknown_sdk_error_falls_back() {
+        let sdk_err = SdkError::Generic("connection timeout".to_string());
+        let msg = broadcast_error_message(&sdk_err);
+        assert!(msg.starts_with("Broadcasting error:"));
+        assert!(msg.contains("connection timeout"));
+    }
+}
