1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 Regit
//! Typed failures with fixed diagnostics that contain no supplied input.
//!
//! Errors intentionally carry no endpoint, credential, response body, or
//! arbitrary provider message. Their serialization preserves the category and
//! typed reason. Parsing a serialization format may independently produce
//! errors from that format's parser.
use std::fmt;
use serde::{Deserialize, Serialize};
/// A typed failure with a stable category and secret-safe diagnostic.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(tag = "category", content = "reason", rename_all = "snake_case")]
pub enum Error {
/// Caller-supplied configuration is invalid.
Configuration,
/// A value violates a domain contract.
Validation(ValidationError),
/// The requested capability is unsupported.
UnsupportedCapability,
/// The operation exceeded its time limit.
Timeout,
/// The provider reports that a contract call reverted during execution.
ExecutionReverted,
/// A provider operation failed.
Provider(ProviderError),
/// An outgoing submission was attempted, but its outcome could not be established.
/// The request may have reached the server; this is not evidence of rejection.
SubmissionOutcomeUnknown(SubmissionFailure),
/// The requested data is unavailable at the selected source.
UnavailableData,
}
impl Error {
/// Returns the stable serialized category name.
#[must_use]
pub const fn code(self) -> &'static str {
match self {
Self::Configuration => "configuration",
Self::Validation(_) => "validation",
Self::UnsupportedCapability => "unsupported_capability",
Self::Timeout => "timeout",
Self::ExecutionReverted => "execution_reverted",
Self::Provider(_) => "provider",
Self::SubmissionOutcomeUnknown(_) => "submission_outcome_unknown",
Self::UnavailableData => "unavailable_data",
}
}
}
impl fmt::Display for Error {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Configuration => formatter.write_str("invalid configuration"),
Self::Validation(reason) => reason.fmt(formatter),
Self::UnsupportedCapability => formatter.write_str("unsupported capability"),
Self::Timeout => formatter.write_str("operation timed out"),
Self::ExecutionReverted => formatter.write_str("contract execution reverted"),
Self::Provider(reason) => reason.fmt(formatter),
Self::SubmissionOutcomeUnknown(reason) => {
write!(formatter, "submission outcome unknown: {reason}")
}
Self::UnavailableData => formatter.write_str("data unavailable at source"),
}
}
}
impl std::error::Error for Error {}
/// A fixed, input-free cause of an attempted submission's unknown outcome.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SubmissionFailure {
/// The attempted submission exceeded its time limit.
Timeout,
/// Connection or response-body transfer failed after dispatch was attempted.
Transport,
/// The server returned HTTP 429 after dispatch was attempted.
RateLimited,
/// The server returned another non-success HTTP status after attempted dispatch.
HttpStatus,
/// The submission response exceeded its configured body limit.
ResponseTooLarge,
/// The submission response was malformed or mismatched after attempted dispatch.
InvalidResponse,
/// An RPC error was returned after dispatch was attempted.
Rpc,
}
impl fmt::Display for SubmissionFailure {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::Timeout => "operation timed out",
Self::Transport => "transport failed",
Self::RateLimited => "provider rate limited",
Self::HttpStatus => "non-success HTTP response",
Self::ResponseTooLarge => "response body too large",
Self::InvalidResponse => "invalid provider response",
Self::Rpc => "provider RPC error",
})
}
}
// Keep each public variant and its fixed diagnostic together, so additions
// cannot silently omit their Display mapping or expose arbitrary source text.
macro_rules! validation_errors {
($( $(#[$documentation:meta])* $variant:ident => $message:literal, )*) => {
/// The contract violated by an input value.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ValidationError {
$( $(#[$documentation])* $variant, )*
}
impl fmt::Display for ValidationError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
$( Self::$variant => $message, )*
})
}
}
};
}
validation_errors! {
/// An integer is not in canonical unsigned decimal notation.
InvalidAmount => "invalid unsigned decimal integer",
/// An integer exceeds the 256-bit unsigned range.
AmountOverflow => "unsigned integer exceeds 256 bits",
/// A signed decimal is not in supported finite decimal notation.
InvalidDecimal => "invalid finite decimal value",
/// A signed decimal exceeds bounded input, exponent, scale, or output size.
DecimalOutOfBounds => "decimal value exceeds resource bounds",
/// An EVM address has an invalid length, encoding, or mixed-case checksum.
InvalidAddress => "invalid EVM address",
/// An EVM transaction identifier has invalid hexadecimal encoding or width.
InvalidEvmTransactionId => "invalid EVM transaction identifier",
/// EVM bytes violate their bounded hexadecimal or binary encoding contract.
InvalidEvmBytes => "invalid EVM byte encoding",
/// An EVM transaction, receipt or operation record violates its structural contract.
InvalidEvmRecord => "invalid EVM record",
/// EVM token metadata violates its typed availability or value contract.
InvalidEvmMetadata => "invalid EVM token metadata",
/// An unsigned EVM preparation violates its explicit transaction intent.
InvalidEvmPreparation => "invalid EVM transaction preparation",
/// A signed EVM transaction violates its supported envelope contract.
InvalidEvmSignedTransaction => "invalid EVM signed transaction envelope",
/// A Solana public key has an invalid base58 encoding or byte length.
InvalidSolanaPubkey => "invalid Solana public key",
/// A Solana hash has an invalid base58 encoding or byte length.
InvalidSolanaHash => "invalid Solana hash",
/// A Solana signature has an invalid base58 encoding or byte length.
InvalidSolanaSignature => "invalid Solana signature",
/// A Solana transaction violates its bounded supported encoding contract.
InvalidSolanaTransaction => "invalid Solana transaction",
/// A Solana preparation violates its explicit unsigned transfer contract.
InvalidSolanaPreparation => "invalid Solana transaction preparation",
/// A Solana execution record violates its method-specific source contract.
InvalidSolanaExecution => "invalid Solana execution record",
/// A Solana native or token base-unit amount exceeds the unsigned 64-bit range.
SolanaAmountOverflow => "Solana amount exceeds 64 bits",
/// An observation context declares an operation differing from its value.
ObservationOperationMismatch => "observation operation and value differ",
/// A Solana observation slot is below the explicitly requested minimum.
ContextSlotBelowMinimum => "observation slot is below requested minimum",
/// A Solana account record differs from the requested account identity.
InvalidSolanaAccount => "Solana account and requested identity differ",
/// Solana account data exceeds the protocol's maximum byte length.
SolanaAccountDataTooLarge => "Solana account data exceeds byte limit",
/// A Bitcoin address has invalid encoding or checksum.
InvalidBitcoinAddress => "invalid Bitcoin address",
/// A Litecoin address violates its family encoding, checksum or network contract.
InvalidLitecoinAddress => "invalid Litecoin address",
/// A Dogecoin address violates its family encoding, checksum or network contract.
InvalidDogecoinAddress => "invalid Dogecoin address",
/// A Bitcoin Cash address violates its qualified encoding contract.
InvalidBitcoinCashAddress => "invalid Bitcoin Cash address",
/// A Bitcoin Cash source record violates its typed contract.
InvalidBitcoinCashRecord => "invalid Bitcoin Cash record",
/// Bitcoin Cash bytes violate their bounded encoding contract.
InvalidBitcoinCashBytes => "invalid Bitcoin Cash byte encoding",
/// A TON address violates its encoding, flags or checksum contract.
InvalidTonAddress => "invalid TON address",
/// A TON network identity violates its zero-state or alias contract.
InvalidTonNetwork => "invalid TON network",
/// A TON hash violates its exact-width encoding contract.
InvalidTonHash => "invalid TON hash",
/// A TON bag of cells violates its bounded container contract.
InvalidTonBoc => "invalid TON bag of cells",
/// A TON source record violates its typed structural contract.
InvalidTonRecord => "invalid TON record",
/// A TON transfer violates its explicit unsigned intent contract.
InvalidTonTransfer => "invalid TON transfer preparation",
/// A Jupiter request violates its explicit typed query contract.
InvalidJupiterRequest => "invalid Jupiter request",
/// A Jupiter quote violates its exact source/request contract.
InvalidJupiterQuote => "invalid Jupiter quote",
/// A Jupiter build response violates its bounded source contract.
InvalidJupiterBuild => "invalid Jupiter build",
/// A Jupiter preparation violates its explicitly reviewed unsigned contract.
InvalidJupiterPreparation => "invalid Jupiter swap preparation",
/// A Jupiter estimate violates its independently sourced operation contract.
InvalidJupiterEstimate => "invalid Jupiter estimate",
/// A Uniswap deployment violates its explicit supported-version contract.
InvalidUniswapDeployment => "invalid Uniswap deployment",
/// A Uniswap V3 path violates its bounded token/fee contract.
InvalidUniswapPath => "invalid Uniswap V3 path",
/// A Uniswap V3 quote violates its exact request/source contract.
InvalidUniswapQuote => "invalid Uniswap V3 quote",
/// A Uniswap preparation violates its exact reviewed swap intent.
InvalidUniswapPreparation => "invalid Uniswap swap preparation",
/// An indexed UTxO-family source record violates its structural contract.
InvalidUtxoRecord => "invalid indexed UTxO record",
/// Indexed UTxO-family bytes violate their bounded encoding contract.
InvalidUtxoBytes => "invalid indexed UTxO byte encoding",
/// A Bitcoin address is incompatible with the explicitly declared network.
BitcoinAddressNetworkMismatch => "Bitcoin address and declared network differ",
/// A Bitcoin block hash has an invalid hexadecimal encoding or length.
InvalidBitcoinHash => "invalid Bitcoin block hash",
/// A Bitcoin transaction identifier has invalid hexadecimal encoding or length.
InvalidBitcoinTxid => "invalid Bitcoin transaction identifier",
/// A Bitcoin satoshi value exceeds the supported exact unsigned 64-bit range.
BitcoinAmountOverflow => "Bitcoin amount exceeds 64 bits",
/// Bitcoin balance statistics imply a negative confirmed balance.
BitcoinBalanceInconsistent => "inconsistent Bitcoin balance statistics",
/// Bitcoin history entries violate pagination limits or identity uniqueness.
InvalidBitcoinHistory => "invalid Bitcoin history page",
/// Bitcoin transaction confirmation and inclusion fields are inconsistent.
InvalidBitcoinStatus => "inconsistent Bitcoin transaction status",
/// A fee estimate has an invalid horizon or negative exact rate.
InvalidBitcoinFeeEstimate => "invalid Bitcoin fee estimate",
/// A Bitcoin transaction has invalid or inconsistent indexed facts.
InvalidBitcoinTransaction => "invalid Bitcoin transaction",
/// Bitcoin bytes violate bounded canonical hexadecimal or script encoding.
InvalidBitcoinBytes => "invalid Bitcoin byte encoding",
/// A mempool summary, collection, fee rate or recent record is inconsistent.
InvalidMempoolRecord => "invalid mempool record",
/// A `THORChain` network identity is invalid.
InvalidThorchainNetwork => "invalid THORChain network identity",
/// A `THORChain` account address is invalid.
InvalidThorchainAddress => "invalid THORChain account address",
/// A `THORChain` asset identity is invalid.
InvalidThorchainAsset => "invalid THORChain asset identity",
/// A `THORChain` record violates its typed structural contract.
InvalidThorchainRecord => "invalid THORChain record",
/// A caller-supplied wallet handoff identifier violates its lexical or length contract.
InvalidWalletHandoffId => "invalid wallet handoff identifier",
/// Returned handoff identity, network, intent or unsigned bytes differ from reviewed preparation.
WalletBindingMismatch => "wallet handoff does not match reviewed preparation",
/// A trusted verifier rejected the binding of actual signed contents to reviewed preparation.
SignedPayloadRejected => "signed payload rejected by verifier",
/// A Bitcoin observation uses an unsupported schema version.
UnsupportedBitcoinSchema => "unsupported Bitcoin observation schema",
/// A Cardano address has invalid encoding or checksum.
InvalidCardanoAddress => "invalid Cardano address",
/// A Cardano network identity is invalid.
InvalidCardanoNetwork => "invalid Cardano network identity",
/// A Cardano hash has invalid encoding or length.
InvalidCardanoHash => "invalid Cardano hash",
/// A Cardano native asset identity is invalid.
InvalidCardanoAsset => "invalid Cardano asset identity",
/// A Cardano record violates its structural contract.
InvalidCardanoRecord => "invalid Cardano record",
/// A Cardano transaction violates its bounded era-aware source contract.
InvalidCardanoTransaction => "invalid Cardano transaction",
/// A Cardano preparation violates its explicit unsigned payment contract.
InvalidCardanoPreparation => "invalid Cardano preparation",
/// A bounded page request is invalid.
InvalidPageRequest => "invalid page request",
/// A Cardano output amount exceeds its supported width.
CardanoAmountOverflow => "amount exceeds Cardano output width",
/// A block hash is not a 32-byte hexadecimal value.
InvalidBlockHash => "invalid block hash",
/// A network alias is not a bounded label.
InvalidNetworkAlias => "invalid network alias",
/// An asset symbol is not a bounded display label.
InvalidAssetSymbol => "invalid asset symbol",
/// A source identifier, method, or version is not a bounded label.
InvalidSourceLabel => "invalid source label",
/// A balance's amount and native asset declare different decimals.
DecimalMismatch => "amount and asset decimals differ",
/// An explicit selector does not match the resolved block.
BlockMismatch => "selector and resolved block differ",
/// A balance's chain identity does not match its observation context.
NetworkMismatch => "balance and observation chains differ",
/// An observation uses an unsupported schema version.
UnsupportedSchemaVersion => "unsupported observation schema version",
/// A serialized formatted amount does not match its exact raw value.
InvalidFormattedAmount => "formatted amount differs from exact value",
/// An XRPL address has invalid encoding, length or checksum.
InvalidXrplAddress => "invalid XRPL address",
/// An XRPL hash has invalid hexadecimal encoding or width.
InvalidXrplHash => "invalid XRPL hash",
/// An XRPL currency identifier violates its family contract.
InvalidXrplCurrency => "invalid XRPL currency",
/// An XRPL native or issued amount violates its exact numeric contract.
InvalidXrplAmount => "invalid XRPL amount",
/// An XRPL record violates its structural contract.
InvalidXrplRecord => "invalid XRPL record",
/// An XRPL network identity violates its explicit network contract.
InvalidXrplNetwork => "invalid XRPL network identity",
/// A market identifier or label violates its lexical or length contract.
InvalidMarketIdentity => "invalid market identity or label",
/// A market request or record violates its structural contract.
InvalidMarketRecord => "invalid market request or record",
/// A Helius request violates its bounded typed contract.
InvalidHeliusRequest => "invalid Helius request",
/// A Helius asset violates its bounded typed contract.
InvalidHeliusAsset => "invalid Helius asset",
/// A Helius transaction violates its bounded typed contract.
InvalidHeliusTransaction => "invalid Helius transaction",
/// A 1inch request violates its bounded typed contract.
InvalidOneinchRequest => "invalid 1inch request",
/// A 1inch source record violates its exact correlated contract.
InvalidOneinchRecord => "invalid 1inch record",
/// A 1inch payload violates its explicit unsigned preparation contract.
InvalidOneinchPayload => "invalid 1inch unsigned payload",
/// A Rubic identity violates its bounded typed contract.
InvalidRubicIdentity => "invalid Rubic identity",
/// A Rubic request violates its bounded typed contract.
InvalidRubicRequest => "invalid Rubic request",
/// A Rubic quote violates its bounded typed contract.
InvalidRubicQuote => "invalid Rubic quote",
/// A Rubic preparation violates its bounded typed contract.
InvalidRubicPreparation => "invalid Rubic preparation",
/// A Rubic status violates its bounded typed contract.
InvalidRubicStatus => "invalid Rubic status",
/// A LI.FI chain, asset, address or route identifier violates its typed contract.
InvalidLifiIdentity => "invalid LI.FI identity",
/// A LI.FI quote, route, continuation or status record violates its structural contract.
InvalidLifiRecord => "invalid LI.FI record",
/// A LI.FI prepared payload violates its bounded family encoding contract.
InvalidLifiPayload => "invalid LI.FI prepared payload",
}
impl From<ValidationError> for Error {
fn from(reason: ValidationError) -> Self {
Self::Validation(reason)
}
}
/// A provider failure category without an arbitrary remote message.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ProviderError {
/// The provider returned an RPC error.
Rpc,
/// The provider returned a malformed or inconsistent response.
InvalidResponse,
/// The provider rate-limited the request.
RateLimited,
/// A connection or response-body transfer failed.
Transport,
/// The provider returned an unsuccessful HTTP status.
HttpStatus,
/// The response exceeded the explicitly configured byte limit.
ResponseTooLarge,
/// The provider's chain identity differs from the configured identity.
ChainMismatch,
}
impl fmt::Display for ProviderError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::Rpc => "provider RPC failure",
Self::InvalidResponse => "invalid provider response",
Self::RateLimited => "provider rate limit reached",
Self::Transport => "provider transport failure",
Self::HttpStatus => "unsuccessful provider HTTP status",
Self::ResponseTooLarge => "provider response exceeds byte limit",
Self::ChainMismatch => "provider chain identity differs from configuration",
})
}
}