cow_sdk_browser_wallet/

error.rs

//! Browser-wallet error types and RPC error normalization.
//!
//! Browser runtime failures are normalized before they cross the public Rust boundary so callers
//! receive typed wallet and transport errors rather than raw JS values.

use cow_sdk_core::{Cancelled, ChainId, CoreError, ErrorClass, Redacted};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use thiserror::Error;

/// Serialized JSON-RPC error payload returned by an EIP-1193 wallet.
#[allow(
    clippy::derive_partial_eq_without_eq,
    reason = "the `data: Option<serde_json::Value>` field cannot participate in `Eq` because `serde_json::Value` does not implement `Eq`"
)]
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RpcErrorPayload {
    /// Numeric wallet or RPC error code.
    pub code: i32,
    /// Human-readable wallet or RPC error message.
    pub message: Redacted<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    /// Optional provider-specific error data.
    pub data: Option<Redacted<Value>>,
}

impl RpcErrorPayload {
    /// Creates a typed JSON-RPC error payload from the current public field set.
    #[must_use]
    pub fn new(code: i32, message: impl Into<String>, data: Option<Value>) -> Self {
        Self {
            code,
            message: Redacted::new(message.into()),
            data: data.map(Redacted::new),
        }
    }
}

/// Errors produced by typed browser-wallet discovery, session, provider, and signer flows.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Error)]
pub enum BrowserWalletError {
    /// No injected browser wallet provider is available in the current runtime.
    #[error("wallet provider is unavailable")]
    WalletUnavailable,
    /// Discovery found more than one candidate and requires an explicit wallet selection.
    #[error(
        "wallet discovery requires explicit provider selection because {candidates} injected wallets were found"
    )]
    DiscoverySelectionRequired {
        /// Number of candidates returned by discovery.
        candidates: usize,
    },
    /// A requested discovery index is outside the available wallet range.
    #[error(
        "wallet discovery selection index {index} is out of range for {candidates} injected wallets"
    )]
    DiscoverySelectionOutOfRange {
        /// Requested wallet index.
        index: usize,
        /// Number of available discovery candidates.
        candidates: usize,
    },
    /// A provider origin label failed local validation before provider construction.
    #[error("wallet provider origin is invalid: {message}")]
    InvalidProviderOrigin {
        /// Sanitized validation failure description.
        message: Redacted<String>,
    },
    /// An EIP-1193 provider did not have discovery metadata or an explicit trusted origin.
    #[error("wallet provider origin is not trusted: {origin}")]
    UntrustedProviderOrigin {
        /// Redacted provider origin label.
        origin: Redacted<String>,
    },
    /// The wallet explicitly rejected a user-authorized request.
    ///
    /// The rejected RPC method and the EIP-1193 code are surfaced; the
    /// provider's free-form message is retained for programmatic access but
    /// kept off the public rendering, so this variant reads as cleanly as the
    /// signing-layer typed-data rejection for the same `4001` condition.
    #[error("wallet request `{method}` was rejected by the user ({code})")]
    UserRejectedRequest {
        /// RPC method that was rejected.
        method: String,
        /// Provider error code.
        code: i32,
        /// Provider error message, retained for diagnostics and redacted on
        /// public rendering.
        message: Redacted<String>,
    },
    /// The wallet reported that it is disconnected from all chains.
    #[error(
        "wallet request `{method}` failed because the provider is disconnected ({code}): {message}"
    )]
    Disconnected {
        /// RPC method that failed.
        method: String,
        /// Provider error code.
        code: i32,
        /// Provider error message.
        message: Redacted<String>,
    },
    /// The wallet reported that the currently connected chain is incompatible with the request.
    #[error(
        "wallet request `{method}` failed because the current chain is not connected ({code}): {message}"
    )]
    WrongChain {
        /// RPC method that failed.
        method: String,
        /// Provider error code.
        code: i32,
        /// Provider error message.
        message: Redacted<String>,
    },
    /// The requested chain has not been added to the wallet yet.
    #[error(
        "wallet request `{method}` failed because the requested chain is not added ({code}): {message}"
    )]
    ChainNotAdded {
        /// Chain id requested by the wallet call, when the request carried one.
        ///
        /// `None` when the failing request did not carry a parseable chain id,
        /// so the surfaced error never claims a chain the caller did not
        /// request.
        chain_id: Option<ChainId>,
        /// RPC method that failed.
        method: String,
        /// Provider error code.
        code: i32,
        /// Provider error message.
        message: Redacted<String>,
    },
    /// The typed add-chain input is invalid before any wallet request is attempted.
    #[error("wallet chain configuration for chain {chain_id} is invalid: {message}")]
    InvalidChainConfiguration {
        /// Chain id referenced by the configuration.
        chain_id: ChainId,
        /// Validation failure description.
        message: Redacted<String>,
    },
    /// The wallet session chain does not match the expected workflow chain.
    #[error(
        "wallet session chain {session_chain_id} does not match expected chain {expected_chain_id}"
    )]
    SessionChainMismatch {
        /// Chain id required by the current workflow.
        expected_chain_id: ChainId,
        /// Chain id currently reported by the wallet session.
        session_chain_id: ChainId,
    },
    /// The typed-data payload chain does not match the expected workflow chain.
    #[error(
        "typed-data domain chain {typed_data_chain_id} does not match expected chain {expected_chain_id}"
    )]
    TypedDataChainMismatch {
        /// Chain id required by the current workflow.
        expected_chain_id: ChainId,
        /// Chain id encoded in the typed-data payload.
        typed_data_chain_id: ChainId,
    },
    /// The wallet does not support the requested RPC method.
    #[error("wallet method `{method}` is unsupported: {message}")]
    UnsupportedRpcMethod {
        /// Unsupported RPC method.
        method: String,
        /// Provider-supplied failure description.
        message: Redacted<String>,
    },
    /// The wallet returned a response that does not match the typed contract.
    #[error("wallet response for `{method}` is malformed: {message}")]
    MalformedResponse {
        /// RPC method whose response could not be decoded.
        method: String,
        /// Decode or validation failure description.
        message: Redacted<String>,
    },
    /// An unclassified wallet or RPC error payload.
    #[error("wallet rpc error for `{method}` ({code}): {message}")]
    Rpc {
        /// RPC method that failed.
        method: String,
        /// Provider error code.
        code: i32,
        /// Provider error message.
        message: Redacted<String>,
        /// Optional provider-specific error data.
        data: Option<Redacted<Value>>,
    },
    /// JavaScript interop or DOM interaction failed in the browser runtime.
    #[error("wallet JS interop error: {message}")]
    JsInterop {
        /// Interop failure description.
        message: Redacted<String>,
    },
    /// JSON serialization, ABI conversion, or typed-data encoding failed locally.
    #[error("wallet serialization error: {message}")]
    Serialization {
        /// Serialization or local encoding failure description.
        message: Redacted<String>,
    },
    /// Shared core type or validation error.
    #[error(transparent)]
    Core(#[from] CoreError),
    /// A long-running browser-wallet operation was cancelled through a cooperative cancellation token.
    #[error("operation cancelled")]
    Cancelled,
}

impl From<Cancelled> for BrowserWalletError {
    fn from(_: Cancelled) -> Self {
        Self::Cancelled
    }
}

impl BrowserWalletError {
    /// Returns the coarse-grained [`ErrorClass`] for this error.
    #[must_use]
    pub const fn class(&self) -> ErrorClass {
        match self {
            Self::Core(error) => error.class(),
            Self::Cancelled => ErrorClass::Cancelled,
            // Every other typed wallet failure (user rejection, disconnected,
            // wrong chain, malformed response, JS interop, serialization, or
            // unclassified RPC payload) surfaces from the signing edge.
            _ => ErrorClass::Signing,
        }
    }
}

impl BrowserWalletError {
    pub(crate) fn from_rpc(
        method: &str,
        payload: RpcErrorPayload,
        requested_chain: Option<ChainId>,
    ) -> Self {
        match payload.code {
            4001 => Self::UserRejectedRequest {
                method: method.to_owned(),
                code: payload.code,
                message: payload.message,
            },
            4900 => Self::Disconnected {
                method: method.to_owned(),
                code: payload.code,
                message: payload.message,
            },
            4901 => Self::WrongChain {
                method: method.to_owned(),
                code: payload.code,
                message: payload.message,
            },
            4902 => Self::ChainNotAdded {
                chain_id: requested_chain,
                method: method.to_owned(),
                code: payload.code,
                message: payload.message,
            },
            -32601 => Self::UnsupportedRpcMethod {
                method: method.to_owned(),
                message: payload.message,
            },
            _ => Self::Rpc {
                method: method.to_owned(),
                code: payload.code,
                message: payload.message,
                data: payload.data,
            },
        }
    }

    pub(crate) fn malformed_response(method: &str, message: impl Into<String>) -> Self {
        Self::MalformedResponse {
            method: method.to_owned(),
            message: message.into().into(),
        }
    }

    pub(crate) fn serialization(message: impl Into<String>) -> Self {
        Self::Serialization {
            message: message.into().into(),
        }
    }

    pub(crate) const fn discovery_selection_required(candidates: usize) -> Self {
        Self::DiscoverySelectionRequired { candidates }
    }

    pub(crate) const fn discovery_selection_out_of_range(index: usize, candidates: usize) -> Self {
        Self::DiscoverySelectionOutOfRange { index, candidates }
    }

    pub(crate) fn invalid_chain_configuration(
        chain_id: ChainId,
        message: impl Into<String>,
    ) -> Self {
        Self::InvalidChainConfiguration {
            chain_id,
            message: message.into().into(),
        }
    }

    #[cfg(target_arch = "wasm32")]
    pub(crate) fn js(message: impl Into<String>) -> Self {
        Self::JsInterop {
            message: message.into().into(),
        }
    }
}

/// Exposes the EIP-1193 provider error code carried by the
/// `UserRejectedRequest` variant so the signing crate can route the
/// rejection through `cow_sdk_signing::SigningError::SignerRejection`.
/// Every other variant returns `None` and falls through to the
/// signing crate's redacted display path.
///
/// The match is exhaustive over every typed rejection-class variant
/// the wallet error carries today; new EIP-1193 rejection variants
/// must add a row here so the classification contract stays pinned
/// against the typed error surface (and not against the `Display`
/// shape). Pinning lives in
/// `crates/browser-wallet/tests/signer_error_trait_contract.rs`.
impl cow_sdk_core::UserRejection for BrowserWalletError {
    fn user_rejection_code(&self) -> Option<i32> {
        match self {
            Self::UserRejectedRequest { code, .. } => Some(*code),
            _ => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn known_rpc_error_codes_map_to_explicit_browser_wallet_variants() {
        let cases = [
            (
                4001,
                None,
                BrowserWalletError::UserRejectedRequest {
                    method: "eth_requestAccounts".to_owned(),
                    code: 4001,
                    message: "code-4001".to_owned().into(),
                },
            ),
            (
                4900,
                None,
                BrowserWalletError::Disconnected {
                    method: "eth_requestAccounts".to_owned(),
                    code: 4900,
                    message: "code-4900".to_owned().into(),
                },
            ),
            (
                4901,
                None,
                BrowserWalletError::WrongChain {
                    method: "eth_requestAccounts".to_owned(),
                    code: 4901,
                    message: "code-4901".to_owned().into(),
                },
            ),
            (
                4902,
                Some(u64::from(cow_sdk_core::SupportedChainId::Base)),
                BrowserWalletError::ChainNotAdded {
                    chain_id: Some(u64::from(cow_sdk_core::SupportedChainId::Base)),
                    method: "eth_requestAccounts".to_owned(),
                    code: 4902,
                    message: "code-4902".to_owned().into(),
                },
            ),
            (
                -32601,
                None,
                BrowserWalletError::UnsupportedRpcMethod {
                    method: "eth_requestAccounts".to_owned(),
                    message: "code--32601".to_owned().into(),
                },
            ),
        ];

        for (code, requested_chain, expected) in cases {
            let error = BrowserWalletError::from_rpc(
                "eth_requestAccounts",
                RpcErrorPayload::new(code, format!("code-{code}"), None),
                requested_chain,
            );

            assert_eq!(error, expected);
        }
    }

    #[test]
    fn unknown_rpc_codes_preserve_the_raw_rpc_payload_shape() {
        let error = BrowserWalletError::from_rpc(
            "wallet_switchEthereumChain",
            RpcErrorPayload::new(
                -32_000,
                "generic rpc error",
                Some(json!({ "detail": "kept" })),
            ),
            Some(u64::from(cow_sdk_core::SupportedChainId::Mainnet)),
        );

        assert_eq!(
            error,
            BrowserWalletError::Rpc {
                method: "wallet_switchEthereumChain".to_owned(),
                code: -32_000,
                message: "generic rpc error".to_owned().into(),
                data: Some(json!({ "detail": "kept" }).into()),
            }
        );
    }
}