mostro_core/error.rs
1//! Error taxonomy used across the crate.
2//!
3//! Errors surfaced to clients are modelled as [`MostroError`], which is split
4//! into two branches:
5//!
6//! * [`MostroError::MostroCantDo`] — a "soft" error: the request was
7//! well-formed but the server refuses to perform the action (e.g. the order
8//! is not in the right state). Clients should surface the inner
9//! [`CantDoReason`] to the user.
10//! * [`MostroError::MostroInternalErr`] — a "hard" error: something went
11//! wrong while processing the request (database failure, Nostr relay
12//! issue, malformed invoice, etc.). The inner [`ServiceError`] carries the
13//! diagnostic detail.
14//!
15//! Both inner enums implement [`Display`](std::fmt::Display) with
16//! human-readable messages suited for logging.
17
18use crate::prelude::*;
19
20/// Machine-readable reasons carried by a `CantDo` response.
21///
22/// Serialized in `snake_case` so clients can pattern-match on the value
23/// transported in [`crate::message::Payload::CantDo`].
24#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
25#[serde(rename_all = "snake_case")]
26pub enum CantDoReason {
27 /// The provided signature is invalid or missing.
28 InvalidSignature,
29 /// The specified trade index does not exist or is invalid.
30 InvalidTradeIndex,
31 /// The provided amount is invalid or out of acceptable range.
32 InvalidAmount,
33 /// The provided invoice is malformed or expired.
34 InvalidInvoice,
35 /// The payment request is invalid or cannot be processed.
36 InvalidPaymentRequest,
37 /// The specified peer is invalid or not found.
38 InvalidPeer,
39 /// The rating value is invalid or out of range.
40 InvalidRating,
41 /// The text message is invalid or contains prohibited content.
42 InvalidTextMessage,
43 /// The order kind is invalid.
44 InvalidOrderKind,
45 /// The order status is invalid.
46 InvalidOrderStatus,
47 /// The provided public key is invalid.
48 InvalidPubkey,
49 /// One or more request parameters are invalid.
50 InvalidParameters,
51 /// The provided payload is the wrong shape for this action,
52 /// or carries values that cannot be processed (e.g. a
53 /// `BondResolution` requesting a slash against a side with no
54 /// active bond row). The caller should correct and resend.
55 InvalidPayload,
56 /// The targeted order has already been canceled.
57 OrderAlreadyCanceled,
58 /// User creation failed on the server side.
59 CantCreateUser,
60 /// The caller tried to operate on an order that does not belong to them.
61 IsNotYourOrder,
62 /// The requested action is not allowed in the order's current status.
63 NotAllowedByStatus,
64 /// The fiat amount is outside the allowed range for this order.
65 OutOfRangeFiatAmount,
66 /// The sats amount is outside the allowed range for this order.
67 OutOfRangeSatsAmount,
68 /// The caller tried to operate on a dispute that does not belong to them.
69 IsNotYourDispute,
70 /// A solver is being notified that an admin has taken over their dispute.
71 DisputeTakenByAdmin,
72 /// The caller is authenticated but lacks the permission for this action.
73 NotAuthorized,
74 /// A dispute could not be created (e.g. order not in a disputable state).
75 DisputeCreationError,
76 /// Generic "resource not found" error.
77 NotFound,
78 /// The dispute is in an invalid state for the requested action.
79 InvalidDisputeStatus,
80 /// The requested action is invalid.
81 InvalidAction,
82 /// The caller already has a pending order and cannot create another.
83 PendingOrderExists,
84 /// The fiat currency code is not accepted by this Mostro node.
85 InvalidFiatCurrency,
86 /// The caller is being rate-limited.
87 TooManyRequests,
88 /// The submitted Cashu token is malformed, cannot be parsed, or its
89 /// 2-of-3 spending condition does not match the expected
90 /// buyer/seller/Mostro pubkeys.
91 InvalidCashuToken,
92 /// The configured Cashu mint could not be reached or did not answer the
93 /// state check.
94 CashuMintUnavailable,
95 /// The provided mint URL is malformed or does not match the node's
96 /// configured mint.
97 InvalidMintUrl,
98 /// The requested action needs a locked Cashu escrow, but none has been
99 /// recorded for this order.
100 CashuEscrowNotLocked,
101 /// A required Cashu signature is missing from the request.
102 CashuSignatureMissing,
103}
104
105/// Internal errors raised by services behind the Mostro API.
106///
107/// Unlike [`CantDoReason`], values of this enum are not expected to be
108/// forwarded verbatim to end users; they are meant for logs, telemetry and
109/// other server-to-server diagnostics.
110#[derive(Debug, PartialEq, Eq)]
111pub enum ServiceError {
112 /// Wraps an error returned by `nostr_sdk`.
113 NostrError(String),
114 /// The invoice string could not be parsed as a valid BOLT-11 invoice.
115 ParsingInvoiceError,
116 /// A numeric value could not be parsed.
117 ParsingNumberError,
118 /// The invoice has expired.
119 InvoiceExpiredError,
120 /// The invoice is otherwise invalid.
121 InvoiceInvalidError,
122 /// The invoice expiration time is below the minimum required.
123 MinExpirationTimeError,
124 /// The invoice amount is below the minimum allowed.
125 MinAmountError,
126 /// The invoice amount does not match the expected value.
127 WrongAmountError,
128 /// The price API did not answer in time.
129 NoAPIResponse,
130 /// The requested currency is not listed by the exchange API.
131 NoCurrency,
132 /// The exchange API returned a response that could not be parsed.
133 MalformedAPIRes,
134 /// Amount value is negative where only positives are allowed.
135 NegativeAmount,
136 /// A Lightning Address could not be parsed.
137 LnAddressParseError,
138 /// A Lightning Address payment was attempted with a wrong amount.
139 LnAddressWrongAmount,
140 /// A Lightning payment failed; the inner string carries the reason.
141 LnPaymentError(String),
142 /// Communication with the Lightning node failed.
143 LnNodeError(String),
144 /// Order id was not found in the database.
145 InvalidOrderId,
146 /// Database access failed; the inner string carries the detail.
147 DbAccessError(String),
148 /// The provided public key is invalid.
149 InvalidPubkey,
150 /// Hold-invoice operation failed; the inner string carries the detail.
151 HoldInvoiceError(String),
152 /// Could not update the order status in the database.
153 UpdateOrderStatusError,
154 /// The order status is invalid.
155 InvalidOrderStatus,
156 /// The order kind is invalid.
157 InvalidOrderKind,
158 /// A dispute already exists for this order.
159 DisputeAlreadyExists,
160 /// Could not publish the dispute Nostr event.
161 DisputeEventError,
162 /// The rating message itself is invalid.
163 InvalidRating,
164 /// The rating value is outside the accepted range.
165 InvalidRatingValue,
166 /// Failed to serialize or deserialize a [`crate::message::Message`].
167 MessageSerializationError,
168 /// The dispute id is invalid or unknown.
169 InvalidDisputeId,
170 /// The dispute status is invalid.
171 InvalidDisputeStatus,
172 /// The payload does not match the action.
173 InvalidPayload,
174 /// Any other unexpected error; inner string carries the detail.
175 UnexpectedError(String),
176 /// An environment variable could not be read or parsed.
177 EnvVarError(String),
178 /// Underlying I/O error.
179 IOError(String),
180 /// NIP-44/NIP-59 encryption failed.
181 EncryptionError(String),
182 /// NIP-44/NIP-59 decryption failed.
183 DecryptionError(String),
184}
185
186/// Top-level error type returned by the Mostro API surface.
187///
188/// Most public functions in this crate return `Result<T, MostroError>`.
189/// Match on the variants to distinguish between user-actionable "can't do"
190/// responses and internal service errors.
191#[derive(Debug, PartialEq, Eq)]
192pub enum MostroError {
193 /// An internal service-level error; diagnostic only.
194 MostroInternalErr(ServiceError),
195 /// A structured "can't do" response to surface to the user.
196 MostroCantDo(CantDoReason),
197}
198
199impl std::error::Error for MostroError {}
200
201impl std::fmt::Display for MostroError {
202 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
203 match self {
204 MostroError::MostroInternalErr(m) => write!(f, "Error caused by {}", m),
205 MostroError::MostroCantDo(m) => write!(f, "Sending cantDo message to user for {:?}", m),
206 }
207 }
208}
209
210impl std::fmt::Display for ServiceError {
211 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
212 match self {
213 ServiceError::ParsingInvoiceError => write!(f, "Incorrect invoice"),
214 ServiceError::ParsingNumberError => write!(f, "Error parsing the number"),
215 ServiceError::InvoiceExpiredError => write!(f, "Invoice has expired"),
216 ServiceError::MinExpirationTimeError => write!(f, "Minimal expiration time on invoice"),
217 ServiceError::InvoiceInvalidError => write!(f, "Invoice is invalid"),
218 ServiceError::MinAmountError => write!(f, "Minimal payment amount"),
219 ServiceError::WrongAmountError => write!(f, "The amount on this invoice is wrong"),
220 ServiceError::NoAPIResponse => write!(f, "Price API not answered - retry"),
221 ServiceError::NoCurrency => write!(f, "Currency requested is not present in the exchange list, please specify a fixed rate"),
222 ServiceError::MalformedAPIRes => write!(f, "Malformed answer from exchange quoting request"),
223 ServiceError::NegativeAmount => write!(f, "Negative amount is not valid"),
224 ServiceError::LnAddressWrongAmount => write!(f, "Ln address need amount of 0 sats - please check your order"),
225 ServiceError::LnAddressParseError => write!(f, "Ln address parsing error - please check your address"),
226 ServiceError::LnPaymentError(e) => write!(f, "Lightning payment failure cause: {}",e),
227 ServiceError::LnNodeError(e) => write!(f, "Lightning node connection failure caused by: {}",e),
228 ServiceError::InvalidOrderId => write!(f, "Order id not present in database"),
229 ServiceError::InvalidPubkey => write!(f, "Invalid pubkey"),
230 ServiceError::DbAccessError(e) => write!(f, "Error in database access: {}",e),
231 ServiceError::HoldInvoiceError(e) => write!(f, "Error holding invoice: {}",e),
232 ServiceError::UpdateOrderStatusError => write!(f, "Error updating order status"),
233 ServiceError::InvalidOrderStatus => write!(f, "Invalid order status"),
234 ServiceError::InvalidOrderKind => write!(f, "Invalid order kind"),
235 ServiceError::DisputeAlreadyExists => write!(f, "Dispute already exists"),
236 ServiceError::DisputeEventError => write!(f, "Error publishing dispute event"),
237 ServiceError::NostrError(e) => write!(f, "Error in nostr: {}",e),
238 ServiceError::InvalidRating => write!(f, "Invalid rating message"),
239 ServiceError::InvalidRatingValue => write!(f, "Invalid rating value"),
240 ServiceError::MessageSerializationError => write!(f, "Error serializing message"),
241 ServiceError::InvalidDisputeId => write!(f, "Invalid dispute id"),
242 ServiceError::InvalidDisputeStatus => write!(f, "Invalid dispute status"),
243 ServiceError::InvalidPayload => write!(f, "Invalid payload"),
244 ServiceError::UnexpectedError(e) => write!(f, "Unexpected error: {}", e),
245 ServiceError::EnvVarError(e) => write!(f, "Environment variable error: {}", e),
246 ServiceError::IOError(e) => write!(f, "IO error: {}", e),
247 ServiceError::EncryptionError(e) => write!(f, "Encryption error: {}", e),
248 ServiceError::DecryptionError(e) => write!(f, "Decryption error: {}", e),
249 }
250 }
251}
252
253#[cfg(test)]
254mod tests {
255 use super::*;
256
257 #[test]
258 fn invalid_payload_serializes_to_snake_case() {
259 let json = serde_json::to_string(&CantDoReason::InvalidPayload).unwrap();
260 assert_eq!(json, "\"invalid_payload\"");
261 let round: CantDoReason = serde_json::from_str(&json).unwrap();
262 assert_eq!(round, CantDoReason::InvalidPayload);
263 }
264}