Issue 10: Human-Readable Dictionary Layer Mapping Cryptic Soroban Error Codes

[elizabetheonoja-art]

Scope

File: src/utils/errors.ts

Problem

Soroban RPC returns terse error codes like tx_bad_seq, contract_error, auth_revoked that are meaningless to end users and even to most integrators. The current error handling simply throws the raw error string, resulting in confusing toast notifications and support tickets for trivially resolvable issues.

Requirements

1. Build an error code dictionary (SOROBAN_ERROR_CODES) mapping known Soroban error substrings to human-readable messages (minimum 15 entries).
2. Implement resolveSorobanError(rawError: string): string that:
   • Normalizes the error to lowercase
   • Checks the dictionary for substring matches
   • Falls back to network error keywords
   • Truncates and wraps unknown errors with a generic message
3. Implement classifyError(error: unknown): { message, severity: "low"|"medium"|"high", actionable: boolean }.
4. Implement formatErrorForDisplay(error: unknown): string that prepends severity level.
5. Add network error keyword mapping for common JS fetch/WebSocket errors.

Resolution Strategy

• Dictionary approach: {[keyword]: message} — check error.includes(keyword).
• Classify: auth errors → high/actionable, balance/fee errors → medium/actionable, timeout → medium/actionable, everything else → low/not actionable.
• Pure functions with full test coverage.

Tags

utils, errors, soroban, ux

[gracious01-tech]

I would like to work on this issue by implementing a centralized Soroban error resolution and classification system that transforms low-level RPC and JavaScript network errors into clear, actionable messages for end users and developers.

Currently, raw Soroban RPC responses such as tx_bad_seq, contract_error, or auth_revoked are surfaced directly to the UI, resulting in confusing notifications and unnecessary support requests. This implementation will introduce a consistent error handling layer that improves user experience while remaining easy to extend as new Soroban error codes are discovered.

Implementation Plan

1. Create a Soroban Error Dictionary

I will introduce a SOROBAN_ERROR_CODES constant in src/utils/errors.ts that maps known Soroban error substrings to user-friendly explanations.

The dictionary will contain at least 15 well-known Soroban error patterns, including transaction failures, authentication issues, contract execution failures, sequence errors, insufficient balance, simulation failures, and resource limitations.

Example structure:

const SOROBAN_ERROR_CODES = {
  tx_bad_seq: "Transaction sequence is invalid. Please refresh and try again.",
  contract_error: "The smart contract could not complete the requested operation.",
  auth_revoked: "Authorization has been revoked. Please reconnect your wallet.",
  ...
}

Using substring matching instead of exact equality ensures compatibility with verbose RPC responses that include additional context.

---

2. Implement resolveSorobanError(rawError: string): string

This utility will serve as the primary translation layer between raw RPC errors and display-ready messages.

The function will:

• Normalize input using toLowerCase()
• Iterate through SOROBAN_ERROR_CODES
• Return the first matching human-readable message
• Check common network-related keywords if no Soroban match exists
• Gracefully handle unknown errors by truncating long messages and wrapping them in a generic fallback

Proposed flow:

raw error
      │
      ▼
normalize to lowercase
      │
      ▼
check Soroban dictionary
      │
      ├── match → return friendly message
      │
      ▼
check network keywords
      │
      ├── match → return network message
      │
      ▼
generic fallback + truncated original error

This keeps the implementation simple, predictable, and easily maintainable.

---

3. Add Network Error Mapping

Many failures originate from the browser rather than Soroban itself. I will include keyword mappings for common JavaScript fetch and WebSocket failures, such as:

• networkerror
• failed to fetch
• fetch failed
• timeout
• aborted
• websocket
• connection refused
• connection reset
• offline

These will be translated into clear messages instructing users to verify their internet connection or retry the operation.

---

4. Implement classifyError(error: unknown)

This function will provide structured metadata for UI components and future logging systems.

Return type:

{
  message: string,
  severity: "low" | "medium" | "high",
  actionable: boolean
}

Classification rules will follow the issue requirements:

Error Type	Severity	Actionable
Authentication errors	High	Yes
Authorization revoked	High	Yes
Balance / Fee errors	Medium	Yes
Timeout / Network issues	Medium	Yes
Unknown / Generic errors	Low	No

The function will internally leverage resolveSorobanError() to ensure consistent messaging throughout the application.

---

5. Implement formatErrorForDisplay(error: unknown): string

This helper will generate a standardized display string by prepending the severity level.

Examples:

[HIGH] Authorization has been revoked. Please reconnect your wallet.

[MEDIUM] Insufficient balance to complete this transaction.

[LOW] Something went wrong. Please try again later.

This creates a consistent presentation format for toast notifications, alerts, and modal dialogs while allowing the UI to remain simple.

---

Testing Strategy

I will provide comprehensive unit tests covering all exported utilities.

Tests will include:

resolveSorobanError()

• Resolves known Soroban errors
• Supports mixed-case input
• Supports substring matching
• Resolves network errors
• Handles empty strings
• Returns generic fallback for unknown errors
• Truncates excessively long messages

classifyError()

• Authentication errors → high/actionable
• Balance errors → medium/actionable
• Timeout errors → medium/actionable
• Unknown errors → low/not actionable
• Handles non-string error objects safely

formatErrorForDisplay()

• Prepends correct severity labels
• Uses resolved human-readable messages
• Formats unknown errors consistently

---

Benefits

This implementation will:

• Improve end-user experience by replacing cryptic RPC codes with meaningful messages
• Reduce avoidable support tickets caused by unclear error reporting
• Centralize Soroban error handling in a single maintainable location
• Provide a reusable foundation for future logging, analytics, and UI improvements
• Ensure deterministic behavior through pure functions and comprehensive test coverage

The solution will remain lightweight, framework-independent, fully type-safe, and aligned with the project's requested dictionary-based resolution strategy while satisfying all acceptance requirements.

[grantfox-oss]

🦊 GrantFox — @gracious01-tech has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #9)
2. Your PR will be reviewed by the Utility-Protocol maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@gracious01-tech's PR #72 was approved and merged by @elizabetheonoja-art.

🏆 @gracious01-tech: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (153 total points). Track your full progress on GrantFox.

👏 Great work, @gracious01-tech! Keep contributing to Utility-Protocol.