//! Definitions of errors use crate::platform::encrypted_for::EncryptedForError; use dapi_grpc::platform::v0::StateTransitionBroadcastError as StateTransitionBroadcastErrorProto; use dapi_grpc::tonic::Code; pub use dash_context_provider::ContextProviderError; use dpp::block::block_info::BlockInfo; use dpp::block::epoch::EpochIndex; use dpp::consensus::basic::state_transition::{ OutputBelowMinimumError, StateTransitionMaxSizeExceededError, TransitionNoInputsError, TransitionNoOutputsError, }; use dpp::consensus::state::address_funds::{AddressDoesNotExistError, AddressNotEnoughFundsError}; use dpp::consensus::ConsensusError; use dpp::serialization::PlatformDeserializableUntrusted; use dpp::validation::SimpleConsensusValidationResult; use dpp::version::PlatformVersionError; use dpp::{dashcore_rpc, ProtocolError}; use rs_dapi_client::transport::TransportError; use rs_dapi_client::{CanRetry, DapiClientError, ExecutionError}; use std::fmt::Debug; use std::time::Duration; /// Error type for the SDK // TODO: Propagate server address and retry information so that the user can retrieve it #[allow(clippy::large_enum_variant)] #[derive(Debug, thiserror::Error)] pub enum Error { /// SDK is not configured properly #[error("SDK misconfigured: {0}")] Config(String), /// The request cannot succeed as written on any node: the SDK refused it before sending /// it, because its query syntax or bounds are invalid, no node serves it, or no answer verifies as the requested result /// type, or a fresh verified answer showed that the result cannot be returned as that /// type (for example several documents for a single-document fetch). /// /// Every honest node answers it alike, so the SDK neither retries it on another node nor /// bans the node that answered. The request has to change. A node's own refusal of a /// request (an `INVALID_ARGUMENT` status) stays an [`Error::DapiClientError`]. #[error("invalid request: {0}")] InvalidRequest(String), /// Drive error #[error("Drive error: {0}")] Drive(#[from] drive::error::Error), /// Drive proof error with associated proof bytes and block info #[error("Drive error with associated proof: {0}")] DriveProofError(drive::error::proof::ProofError, Vec, BlockInfo), /// DPP error #[error("Protocol error: {0}")] Protocol(#[from] ProtocolError), /// Proof verification error #[error("Proof verification error: {0}")] Proof(#[source] drive_proof_verifier::Error), /// Invalid Proved Response error #[error("Invalid Proved Response error: {0}")] InvalidProvedResponse(String), /// The proof authenticated only the state the transition affects (a /// height-pinned snapshot), while the caller required evidence that this /// specific transition executed. Use the `*_affected_state` wait APIs to /// accept snapshot outcomes explicitly. #[error("proof authenticates the transition's affected state only, not its execution: {0}")] ExecutionNotProved(String), /// A state transition may have been submitted but its outcome is unresolved. /// The cause is diagnostic, not permission to create a replacement operation. #[error("state transition outcome is unconfirmed; reconcile the original operation before submitting a replacement: {0}")] StateTransitionResultUnconfirmed(#[source] Box), /// DAPI client error, for example, connection error #[error("Dapi client error: {0}")] DapiClientError(rs_dapi_client::DapiClientError), #[cfg(feature = "mocks")] /// DAPI mocks error #[error("Dapi mocks error: {0}")] DapiMocksError(#[from] rs_dapi_client::mock::MockError), /// Dash core error #[error("Dash core error: {0}")] CoreError(#[from] dpp::dashcore::Error), /// MerkleBlockError #[error("Dash core error: {0}")] MerkleBlockError(#[from] dpp::dashcore::merkle_tree::MerkleBlockError), /// Core client error, for example, connection error #[error("Core client error: {0}")] CoreClientError(#[from] dashcore_rpc::Error), /// Dependency not found, for example data contract for a document not found #[error("Required {0} not found: {1}")] MissingDependency(String, String), /// Total credits in Platform are not found; we must always have credits in Platform #[error("Total credits in Platform are not found; it should never happen")] TotalCreditsNotFound, /// Epoch not found; we must have at least one epoch #[error("No epoch found on Platform; it should never happen")] EpochNotFound, /// SDK operation timeout reached error #[error("SDK operation timeout {} secs reached: {}", .0.as_secs(), .1)] TimeoutReached(Duration, String), /// Returned when an attempt is made to create an object that already exists in the system #[error("Object already exists: {0}")] AlreadyExists(String), /// Invalid credit transfer configuration #[error("Invalid credit transfer: {0}")] InvalidCreditTransfer(String), /// Identity nonce overflow: the nonce has reached its maximum value and /// cannot be incremented further without wrapping to zero. #[error("Identity nonce overflow: nonce has reached the maximum value ({0})")] NonceOverflow(u64), /// Identity nonce not found on Platform. /// /// Platform returned no nonce for the requested identity (or identity– /// contract pair). This usually means the queried DAPI node has not yet /// indexed the identity — for example right after identity creation or /// when the node is lagging behind the chain tip. /// /// **Recovery**: retry the state transition; the SDK will re-fetch the /// nonce from a (potentially different) DAPI node on the next attempt. #[error("Identity nonce not found on platform: {0}")] IdentityNonceNotFound(String), /// Drive returned an internal error that is not a consensus error. /// /// Contains the decoded human-readable message extracted from the /// `drive-error-data-bin` gRPC metadata (CBOR map, `message` field). /// Typically a storage-level failure (e.g., GroveDB constraint violation). #[error("Drive internal error: {0}")] DriveInternalError(String), /// Generic error // TODO: Use domain specific errors instead of generic ones #[error("SDK error: {0}")] Generic(String), /// Context provider error #[error("Context provider error: {0}")] ContextProviderError(#[from] ContextProviderError), /// Operation cancelled - cancel token was triggered, timeout, etc. #[error("Operation cancelled: {0}")] Cancelled(String), /// Remote node is stale; try another server #[error(transparent)] StaleNode(#[from] StaleNodeError), /// Error returned when trying to broadcast a state transition #[error(transparent)] StateTransitionBroadcastError(#[from] StateTransitionBroadcastError), /// All available addresses have been exhausted (banned due to errors). /// Contains the last meaningful error that caused addresses to be banned. #[error("no available addresses to retry, last error: {0}")] NoAvailableAddressesToRetry(Box), /// A property declared `encryptedFor` could not be encrypted or decrypted #[error(transparent)] EncryptedFor(#[from] EncryptedForError), /// The request uses a feature that not every node of the network serves yet, so the /// SDK refused it without sending it: nodes of an older release would answer /// UNIMPLEMENTED or a different question, and get banned for it. /// /// Retrying another node cannot help. The same request succeeds once a verified answer /// shows the network runs `required`, and this SDK's own version is at least /// `required`. See [`Query::protocol_requirement`](crate::platform::Query::protocol_requirement). #[error( "{method} needs Platform protocol version {required}{}; {}", describe_feature(*.feature), describe_proven_protocol_version(*.network, *.pinned, .cause.is_some()) )] ProtocolVersionNotActive { /// gRPC method of the refused request, e.g. `get_contract_fee_pots`. method: &'static str, /// Protocol version from which every node serves the request. required: u32, /// The feature of the request that needs `required`, when the method alone does not, /// for example "time-range selections" of a `get_documents` request. feature: Option<&'static str>, /// Protocol version the SDK could rely on: the lower of its own version and the /// newest version a verified answer was signed with; 0 before any verified answer. network: u32, /// Whether the SDK is pinned to a version below `required` /// ([`SdkBuilder::with_version`](crate::SdkBuilder::with_version)): then no answer /// can lift the refusal, whatever the network runs. pinned: bool, /// Why the network's version could not be confirmed, when a query for it failed. /// The refusal may then be transient. #[source] cause: Option>, }, } /// The feature [`Error::ProtocolVersionNotActive`]'s message names, if any. fn describe_feature(feature: Option<&'static str>) -> String { feature .map(|feature| format!(" for {feature}")) .unwrap_or_default() } /// The end of [`Error::ProtocolVersionNotActive`]'s message. fn describe_proven_protocol_version( network: u32, pinned: bool, confirmation_failed: bool, ) -> String { if pinned { "this SDK is pinned to an earlier protocol version".to_string() } else if confirmation_failed { "the network's protocol version could not be confirmed".to_string() } else if network == 0 { "the network's protocol version is not verified yet".to_string() } else { format!("the network is proven at protocol version {network}") } } impl Error { /// Whether an unresolved submission must be reconciled before replacement. pub fn is_state_transition_result_unconfirmed(&self) -> bool { match self { Self::StateTransitionResultUnconfirmed(_) => true, Self::NoAvailableAddressesToRetry(inner) => { inner.is_state_transition_result_unconfirmed() } _ => false, } } /// Preserve the diagnostic cause without nesting uncertainty wrappers. pub(crate) fn into_unconfirmed(self) -> Self { if self.is_state_transition_result_unconfirmed() { self } else { Self::StateTransitionResultUnconfirmed(Box::new(self)) } } /// Inspect the typed duplicate cause, including unresolved/retry envelopes. pub(crate) fn is_already_exists(&self) -> bool { match self { Self::AlreadyExists(_) => true, Self::StateTransitionResultUnconfirmed(inner) | Self::NoAvailableAddressesToRetry(inner) => inner.is_already_exists(), _ => false, } } /// Whether this is an [`Error::ProtocolVersionNotActive`] refusal that may lift soon: the /// SDK could not learn the network's version for a reason that can pass, such as nodes /// or a quorum source not answering, so the network may serve the request already. /// /// False for any other error, for a refusal the network's verified version explains, /// and for one caused by this SDK's own setup: no context provider, or one configured so /// that it cannot give quorum keys at all ([`ContextProviderError::Config`]). Retrying /// cannot change those. A provider's other failures, such as a quorum service not /// answering, may pass. pub fn is_transient_protocol_version_refusal(&self) -> bool { match self { Self::ProtocolVersionNotActive { cause: Some(cause), .. } => !cause.cannot_verify_answers(), _ => false, } } /// Whether this SDK's own setup keeps it from verifying any answer, looking through /// retry-exhaustion wrappers. fn cannot_verify_answers(&self) -> bool { match self { Self::NoAvailableAddressesToRetry(last_error) => last_error.cannot_verify_answers(), Self::Proof(drive_proof_verifier::Error::QuorumKeyUnavailable { error, .. }) | Self::ContextProviderError(error) => { matches!(error, ContextProviderError::Config(_)) } _ => false, } } /// Whether this error is a trusted quorum-source failure, looking through /// nested retry-exhaustion wrappers. This is distinct from /// [`CanRetry::can_retry`] and does not affect node-ban attribution. pub fn is_quorum_source_unavailable(&self) -> bool { match self { Self::ContextProviderError(ContextProviderError::QuorumSourceUnavailable(_)) => true, Self::NoAvailableAddressesToRetry(last_error) => { last_error.is_quorum_source_unavailable() } _ => false, } } /// The consensus verdict this error carries, from the shapes that can /// carry one: `StateTransitionBroadcastError` (wait-stream), /// `Protocol(ConsensusError)` (CheckTx), and the dapi-client's /// exhausted-retry envelope, which it recurses into. Re-audit when this /// enum gains another consensus-carrying variant. pub fn consensus_error(&self) -> Option<&ConsensusError> { match self { Self::StateTransitionBroadcastError(broadcast_err) => broadcast_err.cause.as_ref(), Self::Protocol(ProtocolError::ConsensusError(ce)) => Some(ce.as_ref()), Self::NoAvailableAddressesToRetry(inner) => inner.consensus_error(), // An unconfirmed submission's later diagnostic verdict does not // establish that an earlier node never accepted the operation. Self::StateTransitionResultUnconfirmed(_) => None, _ => None, } } /// Whether the node that sent the answer leaves the request's rotation without a ban: /// the answer cannot be used, but does not show that the node is at fault. pub(crate) fn spares_responder(&self) -> bool { matches!( self, Self::StaleNode(StaleNodeError::ProtocolVersion { .. }) ) } /// The error a request reports when every one of its attempts ended with this kind of /// error and no attempt is left. /// /// When every node asked answered a document query at an older protocol version than the /// SDK's, while no verified answer has shown the network running the SDK's version, the /// request fails as a configuration error: the SDK may be set ahead of its network. pub(crate) fn into_exhausted_error(self) -> Self { match self { Self::StaleNode(StaleNodeError::ProtocolVersion { received_protocol_version: signed, expected_protocol_version: sdk, }) => Self::Config(format!( "the last answer names protocol version {signed}, below the SDK's protocol \ version {sdk}, and no verified answer has yet shown the network running \ {sdk}; if the SDK was set ahead of its network, let it follow the network's \ protocol version instead, or seed it with the network's version \ (with_initial_version)" )), error => error, } } } /// A trusted source outage is not the responding node's fault. Preserve that /// attribution and quorum context. A missing context provider, or one configured so that /// it cannot serve a lookup the verifier makes (a quorum key, or a data contract or token /// configuration a proof is read with), is this SDK's own setup, which no node can change: /// it is a configuration error that is not retried and bans no node. A data contract the /// client's context cannot give as the request needs it fails every node's answer alike, /// and is not retried either. A verified result no node can return as the requested type /// is the request's to change ([`Error::InvalidRequest`]); every other verifier failure /// stays `Proof`. impl From for Error { fn from(value: drive_proof_verifier::Error) -> Self { match value { drive_proof_verifier::Error::QuorumKeyUnavailable { quorum_type, quorum_hash, core_chain_locked_height, error: ContextProviderError::QuorumSourceUnavailable(reason), } => Self::ContextProviderError(ContextProviderError::QuorumSourceUnavailable(format!( "quorum {quorum_type}:{} at Core chain-locked height {core_chain_locked_height}: {reason}", hex::encode(quorum_hash) ))), drive_proof_verifier::Error::QuorumKeyUnavailable { error: error @ ContextProviderError::Config(_), .. } | drive_proof_verifier::Error::ContextProviderError( error @ ContextProviderError::Config(_), ) => Self::ContextProviderError(error), drive_proof_verifier::Error::ContextProviderNotSet => { Self::ContextProviderError(ContextProviderError::Config( "context provider is not set, so no proof can be verified; set one with \ SdkBuilder::with_context_provider() or Sdk::set_context_provider()" .to_string(), )) } drive_proof_verifier::Error::ContextProviderError( error @ ContextProviderError::DataContractFailure(_), ) => Self::ContextProviderError(error), // Every honest node proves the same result, so it is the request's to change. drive_proof_verifier::Error::UnusableVerifiedResult { reason } => { Self::InvalidRequest(reason) } error => Self::Proof(error), } } } impl From for Error { fn from(value: dash_platform_queries::Error) -> Self { match value { dash_platform_queries::Error::Config(msg) => Self::Config(msg), dash_platform_queries::Error::Drive(e) => Self::Drive(e), dash_platform_queries::Error::Protocol(e) => Self::Protocol(e), } } } /// State transition broadcast error #[derive(Debug, thiserror::Error)] #[error("state transition broadcast error: {message}")] pub struct StateTransitionBroadcastError { /// Error code pub code: u32, /// Error message pub message: String, /// Consensus error caused the state transition broadcast error pub cause: Option, } impl TryFrom for StateTransitionBroadcastError { type Error = Error; fn try_from(value: StateTransitionBroadcastErrorProto) -> Result { let cause = if !value.data.is_empty() { let consensus_error = ConsensusError::deserialize_from_bytes_untrusted(&value.data) .map_err(|e| { tracing::debug!("Failed to deserialize consensus error: {}", e); Error::Protocol(e) })?; Some(consensus_error) } else { None }; Ok(Self { code: value.code, message: value.message, cause, }) } } // TODO: Decompose DapiClientError to more specific errors like connection, node error instead of DAPI client error impl From for Error { fn from(value: DapiClientError) -> Self { if let DapiClientError::Transport(TransportError::Grpc(status)) = &value { // If we have some consensus error metadata, we deserialize it and return as ConsensusError if let Some(consensus_error_value) = status .metadata() .get_bin("dash-serialized-consensus-error-bin") { return consensus_error_value .to_bytes() .map(|bytes| { ConsensusError::deserialize_from_bytes_untrusted(&bytes) .map(|consensus_error| { Self::Protocol(ProtocolError::ConsensusError(Box::new( consensus_error, ))) }) .unwrap_or_else(|e| { tracing::debug!("Failed to deserialize consensus error: {}", e); Self::Protocol(e) }) }) .unwrap_or_else(|e| { tracing::debug!("Failed to deserialize consensus error: {}", e); // TODO: Introduce a specific error for this case Self::Generic(format!("Invalid consensus error encoding: {e}")) }); } // Check drive-error-data-bin for decoded Drive error messages if status.code() == Code::Internal { if let Some(drive_error_value) = status.metadata().get_bin("drive-error-data-bin") { match drive_error_value.to_bytes() { Ok(bytes) => { if let Some(message) = extract_drive_error_message(&bytes) { return Self::DriveInternalError(message); } } Err(e) => { tracing::debug!( "Failed to decode drive-error-data-bin metadata: {}", e ); } } } } // Otherwise we parse the error code and act accordingly if status.code() == Code::AlreadyExists { return Self::AlreadyExists(status.message().to_string()); } } // Preserve the original DAPI client error for structured inspection Self::DapiClientError(value) } } /// Hard cap on the length of attacker-influenceable CBOR payloads accepted /// before decoding the `drive-error-data-bin` gRPC metadata. /// /// gRPC metadata is conventionally bounded around 8 KiB; 64 KiB is comfortably /// above any legitimate payload. The cap bounds memory only — `ciborium`'s /// own recursion limit (256) bounds nesting depth and returns /// `RecursionLimitExceeded` rather than recursing into the stack. const MAX_CBOR_INPUT_SIZE: usize = 65_536; // `ciborium` caps recursion at depth 256 and returns // `Error::RecursionLimitExceeded` (a normal `Err`, not a panic) for deeper // input, so a hostile peer cannot exhaust the stack here. fn decode_cbor_value(bytes: &[u8]) -> Option { ciborium::from_reader::(bytes).ok() } /// Extract the `message` text from CBOR-encoded `drive-error-data-bin` metadata. /// /// The metadata is a CBOR map with optional fields `code`, `message`, /// `consensus_error`. Returns `Some(message)` when a non-empty `message` /// text is present. Inputs larger than [`MAX_CBOR_INPUT_SIZE`] are rejected /// unread. // // MIRROR: keep in sync with `walk_cbor_for_key` in // packages/rs-dapi/src/services/platform_service/error_mapping.rs. fn extract_drive_error_message(bytes: &[u8]) -> Option { if bytes.len() > MAX_CBOR_INPUT_SIZE { tracing::debug!( len = bytes.len(), max = MAX_CBOR_INPUT_SIZE, "drive-error-data-bin exceeds size cap; refusing to decode" ); return None; } let value = decode_cbor_value(bytes)?; let map = value.as_map()?; for (key, val) in map { if key.as_text() == Some("message") { if let Some(msg) = val.as_text() { if !msg.is_empty() { return Some(msg.to_string()); } } } } None } impl From for Error { fn from(value: PlatformVersionError) -> Self { Self::Protocol(value.into()) } } impl From for Error { fn from(value: ConsensusError) -> Self { Self::Protocol(ProtocolError::ConsensusError(Box::new(value))) } } impl From for Error { fn from(value: StateTransitionMaxSizeExceededError) -> Self { Self::Protocol(ProtocolError::ConsensusError(Box::new(value.into()))) } } impl From for Error { fn from(value: TransitionNoInputsError) -> Self { Self::Protocol(ProtocolError::ConsensusError(Box::new(value.into()))) } } impl From for Error { fn from(value: TransitionNoOutputsError) -> Self { Self::Protocol(ProtocolError::ConsensusError(Box::new(value.into()))) } } impl From for Error { fn from(value: OutputBelowMinimumError) -> Self { Self::Protocol(ProtocolError::ConsensusError(Box::new(value.into()))) } } impl From for Error { fn from(value: SimpleConsensusValidationResult) -> Self { value .errors .into_iter() .next() .map(Error::from) .unwrap_or_else(|| { Error::Protocol(ProtocolError::CorruptedCodeExecution( "state transition structure validation failed without an error".to_string(), )) }) } } impl From for Error { fn from(value: AddressDoesNotExistError) -> Self { Self::Protocol(ProtocolError::ConsensusError(Box::new(value.into()))) } } impl From for Error { fn from(value: AddressNotEnoughFundsError) -> Self { Self::Protocol(ProtocolError::ConsensusError(Box::new(value.into()))) } } // Retain legacy behavior for generic execution errors that are not DapiClientError impl From> for Error where ExecutionError: ToString, { fn from(value: ExecutionError) -> Self { // Fallback to a generic string representation Self::Generic(value.to_string()) } } impl CanRetry for Error { fn can_retry(&self) -> bool { matches!( self, Error::StaleNode(..) | Error::TimeoutReached(_, _) | Error::Proof(_) ) } fn is_no_available_addresses(&self) -> bool { matches!( self, Error::DapiClientError(DapiClientError::NoAvailableAddresses) | Error::DapiClientError(DapiClientError::NoAvailableAddressesToRetry(_)) ) } } /// Server returned stale metadata #[derive(Debug, thiserror::Error)] pub enum StaleNodeError { /// Server returned metadata with outdated height #[error("received height is outdated: expected {expected_height}, received {received_height}, tolerance {tolerance_blocks}; try another server")] Height { /// Expected height - last block height seen by the Sdk expected_height: u64, /// Block height received from the server received_height: u64, /// Tolerance - how many blocks can be behind the expected height tolerance_blocks: u64, }, /// Server returned metadata with time outside of the tolerance #[error( "received invalid time: expected {expected_timestamp_ms}ms, received {received_timestamp_ms} ms, tolerance {tolerance_ms} ms; try another server" )] Time { /// Expected time in milliseconds - is local time when the message was received expected_timestamp_ms: u64, /// Time received from the server in the message, in milliseconds received_timestamp_ms: u64, /// Tolerance in milliseconds tolerance_ms: u64, }, /// Server kept reporting a current epoch that its own proofs contradict /// /// The epoch index in response metadata is not covered by the quorum /// signature, so `ExtendedEpochInfo::fetch_current` only uses it to shape a /// proved query and then checks it against the proof. This error means the /// check kept failing: every proof showed a newer epoch already started. #[error("received epoch is outdated: hinted {hinted_epoch}, proven started epoch {proven_epoch}; try another server")] Epoch { /// Epoch index the server reported as current in unsigned response metadata hinted_epoch: EpochIndex, /// Newer epoch index that the server's own proof showed as already started proven_epoch: EpochIndex, }, /// Server answered a document query at an older protocol version than the SDK's, and no /// verified answer has yet shown the network running the SDK's version /// /// A document query answer is not verified with the rules of another protocol version than /// the one that signed it. The SDK may be set ahead of its network, where every node answers /// this way, so the node is not banned: the request moves to another node. A request whose /// every attempt ends with this error fails with [`Error::Config`] instead, also when no /// node is left to ask. #[error("received protocol version {received_protocol_version} is below the SDK's protocol version {expected_protocol_version}; try another server")] ProtocolVersion { /// Protocol version the SDK verifies the query with expected_protocol_version: u32, /// Protocol version named in the server's response metadata received_protocol_version: u32, }, /// Server answered a request that needs a newer protocol version with a response /// signed at an older one: it is behind the network's protocol upgrade. /// /// Such a request is sent only once a verified answer has shown the network running /// `required`, so unlike [`StaleNodeError::ProtocolVersion`] the node is at fault: it is /// banned, and the request moves to another node. #[error("received an answer signed at protocol version {signed} to a request that needs {required}; try another server")] BehindProtocolUpgrade { /// Protocol version from which every node serves the request required: u32, /// Protocol version in the response metadata signed: u32, }, /// Server proved a private document type's store of `total_count` entries for a page from /// `position`, which an earlier page showed the store already holds: its snapshot is older /// than the one the read started from. A later read, or another server, can serve it. #[error("received a private document store of {total_count} entries for a page from position {position}, which it already holds; try another server")] PrivateDocumentStoreBehind { /// The page's first position position: u64, /// How many entries the server's snapshot of the store holds total_count: u64, }, } #[cfg(test)] mod tests { use super::*; /// Only the typed source failure, including nested retry exhaustion, /// receives source attribution; sibling variants and messages do not. #[test] fn should_identify_only_typed_quorum_source_failures_through_retry_exhaustion() { let mut source = Error::ContextProviderError( ContextProviderError::QuorumSourceUnavailable("offline".to_string()), ); assert!(source.is_quorum_source_unavailable()); for _ in 0..2 { source = Error::NoAvailableAddressesToRetry(Box::new(source)); assert!(source.is_quorum_source_unavailable()); } for unrelated in [ Error::ContextProviderError(ContextProviderError::InvalidQuorum( "quorum source unavailable".to_string(), )), Error::Generic("QuorumSourceUnavailable: quorum source unavailable".to_string()), ] { assert!(!unrelated.is_quorum_source_unavailable()); let wrapped = Error::NoAvailableAddressesToRetry(Box::new(unrelated)); assert!(!wrapped.is_quorum_source_unavailable()); } } /// Another node cannot serve a request the network has not activated yet, and the /// refusal names no node to ban. The message says why it was refused. A stale answer to /// such a request is retried elsewhere. #[test] fn should_not_retry_a_request_the_network_cannot_serve_yet() { let refused = |network, pinned, cause: Option| Error::ProtocolVersionNotActive { method: "get_contract_fee_pots", required: 14, feature: None, network, pinned, cause: cause.map(Box::new), }; for (error, reason) in [ (refused(13, false, None), "proven at protocol version 13"), (refused(0, false, None), "not verified"), (refused(0, true, None), "pinned"), (refused(13, true, None), "pinned"), ( refused(0, false, Some(Error::Generic("offline".to_string()))), "could not be confirmed", ), ] { assert!(!error.can_retry(), "{error}"); let message = error.to_string(); assert!( message.contains("get_contract_fee_pots") && message.contains("version 14") && message.contains(reason), "{message}" ); } assert!(std::error::Error::source(&refused( 0, false, Some(Error::Generic("offline".into())) )) .is_some()); let behind = Error::StaleNode(StaleNodeError::BehindProtocolUpgrade { required: 14, signed: 13, }); assert!(behind.can_retry()); assert!( !behind.spares_responder(), "a node behind an upgrade the network has proven is banned" ); } /// A context provider configured so that it cannot serve a lookup the verifier makes, /// such as the data contract a document history proof is read with, fails alike for /// every node's answer: the request is not retried and no node is banned for it. #[test] fn should_not_retry_a_lookup_the_context_provider_is_configured_not_to_serve() { let error = Error::from(drive_proof_verifier::Error::ContextProviderError( ContextProviderError::Config("dump dir not set".to_string()), )); assert!( matches!( &error, Error::ContextProviderError(ContextProviderError::Config(reason)) if reason == "dump dir not set" ), "{error:?}" ); assert!(!error.can_retry()); } /// A result that verified but cannot be returned as the requested type is the same from /// every honest node: the request fails without being retried, and the node is not banned. #[test] fn should_not_retry_a_verified_result_no_node_can_return_as_the_requested_type() { let error = Error::from(drive_proof_verifier::Error::UnusableVerifiedResult { reason: "a single-document fetch matched 2 documents".to_string(), }); assert!( matches!(&error, Error::InvalidRequest(reason) if reason.contains("matched 2")), "{error:?}" ); assert!(!error.can_retry()); } /// A request error the verifier raises while it reads an answer can come from parts of /// the answer it has not verified yet, such as the block time a time window resolves /// against. A node that forges them must keep being retried away from and banned. #[test] fn should_retry_a_request_error_raised_while_an_answer_is_verified() { let error = Error::from(drive_proof_verifier::Error::RequestError { error: "the time window does not resolve at the answer's block time".to_string(), }); assert!(matches!(error, Error::Proof(_)), "{error:?}"); assert!(error.can_retry()); } /// A refusal may lift soon only when the SDK could not learn the network's version for a /// reason that can pass; not when its own setup can never verify an answer, nor when the /// network's verified version explains it. #[test] fn should_call_a_refusal_transient_only_when_its_cause_can_pass() { let refused = |cause: Option| Error::ProtocolVersionNotActive { method: "get_contract_fee_pots", required: 14, feature: None, network: 0, pinned: false, cause: cause.map(Box::new), }; let quorum_key = |error| { Error::Proof(drive_proof_verifier::Error::QuorumKeyUnavailable { quorum_type: 106, quorum_hash: [2; 32], core_chain_locked_height: 1, error, }) }; let transient = [ Error::DapiClientError(DapiClientError::NoAvailableAddresses), Error::ContextProviderError(ContextProviderError::QuorumSourceUnavailable( "HTTP 503".to_string(), )), quorum_key(ContextProviderError::InvalidQuorum( "unknown yet".to_string(), )), // What the trusted HTTP provider reports when refetching the quorum lists fails. quorum_key(ContextProviderError::Generic( "Failed to find quorum: HTTP 503".to_string(), )), Error::StaleNode(StaleNodeError::Time { expected_timestamp_ms: 1, received_timestamp_ms: 2, tolerance_ms: 0, }), ]; for cause in transient { let message = cause.to_string(); assert!( refused(Some(cause)).is_transient_protocol_version_refusal(), "{message}" ); } let permanent = [ Error::from(drive_proof_verifier::Error::ContextProviderNotSet), quorum_key(ContextProviderError::Config( "Non-trusted mode is not supported".to_string(), )), Error::NoAvailableAddressesToRetry(Box::new(quorum_key(ContextProviderError::Config( "no quorum source".to_string(), )))), ]; for cause in permanent { let message = cause.to_string(); assert!( !refused(Some(cause)).is_transient_protocol_version_refusal(), "{message}" ); } assert!(!refused(None).is_transient_protocol_version_refusal()); assert!(!Error::Generic("offline".to_string()).is_transient_protocol_version_refusal()); } mod from_dapi_client_error { use super::*; use assert_matches::assert_matches; use base64::Engine; use dapi_grpc::tonic::metadata::{MetadataMap, MetadataValue}; use dpp::consensus::basic::identity::IdentityAssetLockProofLockedTransactionMismatchError; use dpp::consensus::basic::BasicError; use dpp::dashcore::Txid; use dpp::serialization::PlatformSerializableWithPlatformVersion; use dpp::version::PlatformVersion; #[test] fn test_already_exists() { let error = DapiClientError::Transport(TransportError::Grpc( dapi_grpc::tonic::Status::new(Code::AlreadyExists, "Object already exists"), )); let sdk_error: Error = error.into(); assert!(matches!(sdk_error, Error::AlreadyExists(_))); } #[test] fn test_consensus_error() { 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"); let mut metadata = MetadataMap::new(); metadata.insert_bin( "dash-serialized-consensus-error-bin", MetadataValue::from_bytes(&consensus_error_bytes), ); 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); assert_matches!( sdk_error, Error::Protocol(ProtocolError::ConsensusError(e)) if matches!(*e, ConsensusError::BasicError( BasicError::IdentityAssetLockProofLockedTransactionMismatchError(_) )) ); } #[test] fn test_consensus_error_with_fixture() { let consensus_error_bytes = base64::engine::general_purpose::STANDARD.decode("ATUgJOJEYbuHBqyTeApO/ptxQ8IAw8nm9NbGROu1nyE/kqcgDTlFeUG0R4wwVcbZJMFErL+VSn63SUpP49cequ3fsKw=").expect("decode base64"); let consensus_error = MetadataValue::from_bytes(&consensus_error_bytes); let mut metadata = MetadataMap::new(); metadata.insert_bin("dash-serialized-consensus-error-bin", consensus_error); 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); assert_matches!( sdk_error, Error::Protocol(ProtocolError::ConsensusError(e)) if matches!(*e, ConsensusError::BasicError( BasicError::IdentityAssetLockProofLockedTransactionMismatchError(_) )) ); } #[test] fn test_drive_error_data_bin_maps_to_drive_internal_error() { let cbor_map = ciborium::Value::Map(vec![ ( ciborium::Value::Text("code".to_string()), ciborium::Value::Integer(13.into()), ), ( ciborium::Value::Text("message".to_string()), ciborium::Value::Text( "storage: identity: a unique key with that hash already exists: \ the key already exists in the non unique set [1, 2, 3]" .to_string(), ), ), ]); let mut cbor_bytes = Vec::new(); ciborium::into_writer(&cbor_map, &mut cbor_bytes).expect("CBOR serialization"); 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, "internal", metadata); let error = DapiClientError::Transport(TransportError::Grpc(status)); let sdk_error = Error::from(error); assert_matches!(sdk_error, Error::DriveInternalError(msg) if msg.contains("unique key")); } #[test] fn test_internal_error_without_drive_metadata_falls_through() { let status = dapi_grpc::tonic::Status::new(Code::Internal, "Internal error"); let error = DapiClientError::Transport(TransportError::Grpc(status)); let sdk_error = Error::from(error); assert_matches!(sdk_error, Error::DapiClientError(_)); } #[test] fn test_non_internal_code_with_drive_metadata_not_intercepted() { let cbor_map = ciborium::Value::Map(vec![( ciborium::Value::Text("message".to_string()), ciborium::Value::Text("some drive error".to_string()), )]); let mut cbor_bytes = Vec::new(); ciborium::into_writer(&cbor_map, &mut cbor_bytes).expect("CBOR serialization"); 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::Unavailable, "unavailable", metadata); let error = DapiClientError::Transport(TransportError::Grpc(status)); let sdk_error = Error::from(error); assert_matches!(sdk_error, Error::DapiClientError(_)); } #[test] fn test_malformed_cbor_in_drive_error_data_bin_falls_through() { let garbage_bytes = vec![0xFF, 0xFE, 0x00, 0x01, 0x02]; let mut metadata = MetadataMap::new(); metadata.insert_bin( "drive-error-data-bin", MetadataValue::from_bytes(&garbage_bytes), ); let status = dapi_grpc::tonic::Status::with_metadata(Code::Internal, "internal", metadata); let error = DapiClientError::Transport(TransportError::Grpc(status)); let sdk_error = Error::from(error); assert_matches!(sdk_error, Error::DapiClientError(_)); } // Pathological CBOR: 60_000 nested single-pair-map openers (`0xA1`). // `ciborium` rejects this at its depth-256 recursion limit with a // normal `Err`, so the decode returns `None` without exhausting the // stack. #[test] fn test_deeply_nested_cbor_rejected_without_stack_exhaustion() { let payload = vec![0xA1u8; 60_000]; assert!(super::extract_drive_error_message(&payload).is_none()); } } } #[cfg(test)] mod unconfirmed_top_up_tests { use super::*; use dpp::address_funds::PlatformAddress; use dpp::consensus::state::address_funds::AddressInvalidNonceError; use std::error::Error as StdError; #[test] fn should_preserve_unconfirmed_source_without_authorizing_a_retry() { for source in [ Error::TimeoutReached(Duration::from_secs(1), "wait timed out".into()), Error::InvalidProvedResponse("unexpected identity in proof".into()), Error::Protocol(ProtocolError::ConsensusError(Box::new( AddressInvalidNonceError::new(PlatformAddress::P2pkh([7; 20]), 1, 2).into(), ))), ] { let expected = source.to_string(); let error = Error::StateTransitionResultUnconfirmed(Box::new(source)); assert_eq!(StdError::source(&error).unwrap().to_string(), expected); assert!(!error.can_retry()); assert!(error.consensus_error().is_none()); } } }