use thiserror::Error;
use crate::types::{ErrorCode, Receipt, RevertCategory, RevertReason};
#[derive(Debug, Error)]
pub enum SdkError {
#[error("RPC error: {0}")]
Rpc(String),
#[error("connection error: {0}")]
Connection(String),
#[error("signing error: {0}")]
Signing(String),
#[error("timeout: {0}")]
Timeout(String),
#[error("{}", format_revert(.gas_used, .data, .reason.as_ref()))]
Reverted {
gas_used: u64,
data: Vec<u8>,
reason: Option<RevertReason>,
},
#[error("insufficient balance: need {required}, have {available}")]
InsufficientBalance {
required: u128,
available: u128,
},
#[error("{code}: {message}")]
HostFn {
code: ErrorCode,
message: String,
},
#[error("invalid address: {0}")]
InvalidAddress(String),
#[error("invalid argument: {0}")]
InvalidArgument(String),
#[error("invalid response: {0}")]
InvalidResponse(String),
#[error("{0}")]
Other(String),
}
impl SdkError {
#[must_use]
pub fn code(&self) -> &'static str {
match self {
SdkError::Rpc(_) => "RPC_ERROR",
SdkError::Connection(_) => "CONNECTION_ERROR",
SdkError::Signing(_) => "SIGNING_ERROR",
SdkError::Timeout(_) => "TIMEOUT",
SdkError::Reverted { .. } => "CALL_EXCEPTION",
SdkError::InsufficientBalance { .. } => "INSUFFICIENT_FUNDS",
SdkError::HostFn { code, .. } => code.name(),
SdkError::InvalidAddress(_) => "INVALID_ARGUMENT",
SdkError::InvalidArgument(_) => "INVALID_ARGUMENT",
SdkError::InvalidResponse(_) => "INVALID_RESPONSE",
SdkError::Other(_) => "OTHER",
}
}
#[must_use]
pub fn revert_reason(&self) -> Option<String> {
if let SdkError::Reverted { data, .. } = self {
decode_revert_reason(data)
} else {
None
}
}
#[must_use]
pub fn error_code(&self) -> Option<ErrorCode> {
match self {
SdkError::HostFn { code, .. } => Some(*code),
SdkError::Reverted { data, .. } => extract_error_code(data),
_ => None,
}
}
#[must_use]
pub fn is_revert(&self) -> bool {
matches!(self, SdkError::Reverted { .. })
}
#[must_use]
pub fn revert_category(&self) -> Option<&RevertCategory> {
match self {
SdkError::Reverted { reason, .. } => reason.as_ref().map(|r| &r.category),
_ => None,
}
}
#[must_use]
pub fn is_engine_validation_revert(&self) -> bool {
matches!(
self.revert_category(),
Some(RevertCategory::EngineValidation)
)
}
#[must_use]
pub fn is_contract_revert(&self) -> bool {
matches!(self.revert_category(), Some(RevertCategory::Contract))
}
#[must_use]
pub fn is_vm_trap(&self) -> bool {
matches!(self.revert_category(), Some(RevertCategory::Vm))
}
#[must_use]
pub fn from_receipt(receipt: &Receipt) -> Option<Self> {
use crate::types::ReceiptStatus;
let gas_used = receipt.try_gas().unwrap_or(0);
let data = receipt.try_return_bytes().unwrap_or_default();
match receipt.status {
ReceiptStatus::Success => None,
ReceiptStatus::OutOfGas => Some(SdkError::Reverted {
gas_used,
data,
reason: Some(RevertReason {
category: RevertCategory::Vm,
message: "out of gas".to_string(),
}),
}),
ReceiptStatus::Reverted => Some(SdkError::Reverted {
gas_used,
data,
reason: receipt.revert_reason.clone(),
}),
}
}
}
pub type Result<T> = std::result::Result<T, SdkError>;
fn decode_revert_reason(data: &[u8]) -> Option<String> {
if data.is_empty() {
return None;
}
if data.len() >= 4 {
let len = u32::from_le_bytes(data[..4].try_into().ok()?) as usize;
if len > 0 && len <= data.len() - 4 {
if let Ok(s) = std::str::from_utf8(&data[4..4 + len]) {
if looks_printable(s) {
return Some(s.to_string());
}
}
}
}
if data.len() >= 8 {
let len = u64::from_le_bytes(data[..8].try_into().ok()?) as usize;
if len > 0 && len <= data.len() - 8 {
if let Ok(s) = std::str::from_utf8(&data[8..8 + len]) {
if looks_printable(s) {
return Some(s.to_string());
}
}
}
}
if let Ok(s) = std::str::from_utf8(data) {
if s.len() <= 256 && looks_printable(s) {
return Some(s.to_string());
}
}
None
}
fn looks_printable(s: &str) -> bool {
!s.is_empty() && s.chars().all(|c| !c.is_control() || c == '\n')
}
fn extract_error_code(data: &[u8]) -> Option<ErrorCode> {
let reason = decode_revert_reason(data)?;
extract_error_code_from_str(&reason)
}
fn extract_error_code_from_str(reason: &str) -> Option<ErrorCode> {
let codes = [
ErrorCode::AccessListViolation,
ErrorCode::CiphertextInvalid,
ErrorCode::CrossCallFailed,
ErrorCode::CrossCallOutOfGas,
ErrorCode::Forbidden,
ErrorCode::InsufficientBalance,
ErrorCode::Internal,
ErrorCode::InvalidAddress,
ErrorCode::InvalidFunctionName,
ErrorCode::InvalidInput,
ErrorCode::NotFound,
ErrorCode::OutOfGas,
ErrorCode::OutputBufferTooSmall,
ErrorCode::ParachainOnly,
ErrorCode::ReentrancyBlocked,
ErrorCode::SignatureInvalid,
ErrorCode::ValueTransferNotPayable,
ErrorCode::XCallRateLimited,
];
let mut sorted = codes;
sorted.sort_by_key(|c| std::cmp::Reverse(c.name().len()));
for code in sorted {
if reason.contains(code.name()) {
return Some(code);
}
}
for token in reason
.split(|c: char| !c.is_ascii_digit() && c != '-')
.filter(|t| !t.is_empty())
{
if let Ok(n) = token.parse::<i32>() {
if let Some(code) = ErrorCode::from_i32(n) {
return Some(code);
}
}
}
None
}
fn format_revert(gas_used: &u64, data: &[u8], reason: Option<&RevertReason>) -> String {
if let Some(r) = reason {
return format!(
"transaction reverted [{:?}]: {} (gas={gas_used})",
r.category, r.message
);
}
if let Some(reason) = decode_revert_reason(data) {
format!("transaction reverted: {reason} (gas={gas_used})")
} else {
format!("transaction reverted (gas={gas_used})")
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
#[test]
fn revert_reason_empty_returns_none() {
assert!(decode_revert_reason(&[]).is_none());
}
#[test]
fn revert_reason_borsh_u32_string() {
let msg = "insufficient balance";
let mut payload = (msg.len() as u32).to_le_bytes().to_vec();
payload.extend_from_slice(msg.as_bytes());
assert_eq!(decode_revert_reason(&payload).as_deref(), Some(msg));
}
#[test]
fn revert_reason_legacy_u64_string() {
let msg = "legacy revert";
let bogus_u32 = u32::MAX.to_le_bytes(); let mut payload = bogus_u32.to_vec();
payload.extend_from_slice(&(msg.len() as u32).to_le_bytes());
payload.extend_from_slice(msg.as_bytes());
let len_u64 = msg.len() as u64;
let mut alt = len_u64.to_le_bytes().to_vec();
alt.extend_from_slice(msg.as_bytes());
assert_eq!(decode_revert_reason(&alt).as_deref(), Some(msg));
}
#[test]
fn revert_reason_raw_utf8_fallback() {
let msg = "bare utf8 message";
assert_eq!(decode_revert_reason(msg.as_bytes()).as_deref(), Some(msg));
}
#[test]
fn revert_reason_rejects_binary_garbage() {
let garbage = [0xFFu8, 0xFE, 0xFD, 0xFC];
assert!(decode_revert_reason(&garbage).is_none());
}
#[test]
fn revert_reason_rejects_long_random_utf8() {
let long = "x".repeat(300);
assert!(decode_revert_reason(long.as_bytes()).is_none());
}
#[test]
fn revert_reason_rejects_control_chars() {
let with_null = b"abc\x00def";
assert!(decode_revert_reason(with_null).is_none());
}
#[test]
fn error_code_from_named_token() {
let payload = b"token: ERR_FORBIDDEN -- sstore not allowed in view";
assert_eq!(extract_error_code(payload), Some(ErrorCode::Forbidden));
}
#[test]
fn error_code_from_longer_name_wins() {
let payload = b"sub-call: ERR_CROSS_CALL_OUT_OF_GAS";
assert_eq!(
extract_error_code(payload),
Some(ErrorCode::CrossCallOutOfGas)
);
}
#[test]
fn error_code_from_integer() {
let payload = b"reverted with code -5";
assert_eq!(extract_error_code(payload), Some(ErrorCode::Forbidden));
}
#[test]
fn error_code_from_negative_unknown_returns_none() {
let payload = b"random number -42 here";
assert!(extract_error_code(payload).is_none());
}
#[test]
fn error_code_no_match_returns_none() {
let payload = b"nothing matches here at all";
assert!(extract_error_code(payload).is_none());
}
#[test]
fn reverted_error_code_extracts_named_token() {
let err = SdkError::Reverted {
gas_used: 1000,
data: b"token: ERR_INSUFFICIENT_BALANCE".to_vec(),
reason: None,
};
assert_eq!(err.error_code(), Some(ErrorCode::InsufficientBalance));
assert!(err.is_revert());
}
#[test]
fn host_fn_variant_carries_typed_code() {
let err = SdkError::HostFn {
code: ErrorCode::ReentrancyBlocked,
message: "buy() reentered".into(),
};
assert_eq!(err.error_code(), Some(ErrorCode::ReentrancyBlocked));
assert_eq!(err.code(), "ERR_REENTRANCY_BLOCKED");
assert!(!err.is_revert());
}
#[test]
fn non_revert_variants_have_no_error_code() {
let err = SdkError::Rpc("-32602: bad params".into());
assert!(err.error_code().is_none());
}
#[test]
fn code_string_for_each_variant() {
assert_eq!(SdkError::Rpc(String::new()).code(), "RPC_ERROR");
assert_eq!(
SdkError::Connection(String::new()).code(),
"CONNECTION_ERROR"
);
assert_eq!(SdkError::Signing(String::new()).code(), "SIGNING_ERROR");
assert_eq!(SdkError::Timeout(String::new()).code(), "TIMEOUT");
assert_eq!(
SdkError::Reverted {
gas_used: 0,
data: vec![],
reason: None,
}
.code(),
"CALL_EXCEPTION"
);
assert_eq!(
SdkError::InsufficientBalance {
required: 0,
available: 0
}
.code(),
"INSUFFICIENT_FUNDS"
);
assert_eq!(
SdkError::HostFn {
code: ErrorCode::Forbidden,
message: String::new()
}
.code(),
"ERR_FORBIDDEN"
);
assert_eq!(
SdkError::InvalidAddress(String::new()).code(),
"INVALID_ARGUMENT"
);
assert_eq!(
SdkError::InvalidArgument(String::new()).code(),
"INVALID_ARGUMENT"
);
assert_eq!(
SdkError::InvalidResponse(String::new()).code(),
"INVALID_RESPONSE"
);
assert_eq!(SdkError::Other(String::new()).code(), "OTHER");
}
#[test]
fn revert_category_accessors_branch_on_category() {
use crate::types::{RevertCategory, RevertReason};
let eng = SdkError::Reverted {
gas_used: 100,
data: vec![],
reason: Some(RevertReason {
category: RevertCategory::EngineValidation,
message: "nonce out of window".into(),
}),
};
assert!(matches!(
eng.revert_category(),
Some(RevertCategory::EngineValidation)
));
assert!(eng.is_engine_validation_revert());
assert!(!eng.is_contract_revert());
assert!(!eng.is_vm_trap());
let con = SdkError::Reverted {
gas_used: 100,
data: vec![],
reason: Some(RevertReason {
category: RevertCategory::Contract,
message: "ERR_FORBIDDEN".into(),
}),
};
assert!(con.is_contract_revert());
let vm = SdkError::Reverted {
gas_used: 100,
data: vec![],
reason: Some(RevertReason {
category: RevertCategory::Vm,
message: "Trap(MemoryOutOfBounds)".into(),
}),
};
assert!(vm.is_vm_trap());
let bare = SdkError::Reverted {
gas_used: 100,
data: vec![],
reason: None,
};
assert!(bare.revert_category().is_none());
assert!(!bare.is_engine_validation_revert());
}
#[test]
fn format_revert_prefers_structured_reason() {
use crate::types::{RevertCategory, RevertReason};
let err = SdkError::Reverted {
gas_used: 42_000,
data: b"insufficient balance".to_vec(),
reason: Some(RevertReason {
category: RevertCategory::EngineValidation,
message: "insufficient balance for fee+value: needed=42000, available=21000".into(),
}),
};
let msg = format!("{err}");
assert!(msg.contains("EngineValidation"));
assert!(msg.contains("needed=42000"));
assert!(msg.contains("gas=42000"));
}
#[test]
fn from_receipt_maps_each_status() {
use crate::types::{Receipt, ReceiptStatus, RevertCategory, RevertReason};
fn receipt(status: ReceiptStatus, reason: Option<RevertReason>) -> Receipt {
Receipt {
tx_hash: "0x".into(),
wave_id: "0x1".into(),
tx_index: "0x0".into(),
nonce: "0x0".into(),
commit_reveal: false,
status,
gas_used: "0x5208".into(),
fee_paid: "0x5208".into(),
return_data: "0x".into(),
events: vec![],
revert_reason: reason,
}
}
assert!(SdkError::from_receipt(&receipt(ReceiptStatus::Success, None)).is_none());
let err = SdkError::from_receipt(&receipt(ReceiptStatus::OutOfGas, None)).unwrap();
assert!(err.is_vm_trap());
let err = SdkError::from_receipt(&receipt(
ReceiptStatus::Reverted,
Some(RevertReason {
category: RevertCategory::Contract,
message: "ERR_FORBIDDEN".into(),
}),
))
.unwrap();
assert!(err.is_contract_revert());
let err = SdkError::from_receipt(&receipt(ReceiptStatus::Reverted, None)).unwrap();
assert!(err.is_revert());
assert!(err.revert_category().is_none());
}
}