BE — Translate Stellar transaction failure codes into plain-English explanations

[Tinna23]

Description

When a Stellar transaction fails, Horizon returns structured error codes in the result_codes field — codes like tx_bad_seq, op_no_trust, op_underfunded, op_no_destination. Currently the backend marks the transaction as successful: false and returns a generic summary. Users have no idea why their transaction failed.

This issue parses Horizon result codes and adds a human-readable failure_reason field to the transaction explanation that tells the user exactly what went wrong and how to fix it.

Horizon Error Response

When a transaction fails, Horizon includes:

{
  "extras": {
    "result_codes": {
      "transaction": "tx_bad_seq",
      "operations": ["op_no_trust", "op_success"]
    }
  }
}

Target Response Addition

{
  "successful": false,
  "failure_reason": "Transaction failed: sequence number is out of date. This usually means another transaction was submitted from this account simultaneously. Try again.",
  "operation_failures": [
    {
      "index": 0,
      "code": "op_no_trust",
      "explanation": "This account has not opted in to hold this asset. The sender needs to establish a trust line before receiving it."
    }
  ]
}

Error Codes to Translate

Transaction-level codes (result_codes.transaction)

Code	Plain-English explanation
tx_bad_seq	Sequence number is out of date — another transaction from this account may have been submitted first. Try again.
tx_bad_auth	The transaction was not properly signed by the required keys.
tx_insufficient_balance	The account does not have enough XLM to cover this transaction and the minimum balance.
tx_no_account	The source account does not exist on the Stellar network.
tx_insufficient_fee	The fee offered was too low.
tx_too_early	The transaction was submitted before its min_time boundary.
tx_too_late	The transaction expired before it was processed.
tx_missing_operation	The transaction contains no operations.
tx_bad_auth_extra	The transaction has more signatures than required.

Operation-level codes (result_codes.operations[])

Code	Plain-English explanation
op_no_trust	The destination account has not opted in to hold this asset.
op_underfunded	The source account does not have enough of this asset to send.
op_no_destination	The destination account does not exist on the Stellar network.
op_not_authorized	The asset issuer has not authorised this account to hold the asset.
op_line_full	The destination account's trust line is full and cannot receive more.
op_no_issuer	The asset issuer account does not exist.
op_low_reserve	The account would fall below the minimum XLM reserve after this operation.

Key Files

• packages/core/src/explain/failure.rs — new file, maps error codes to explanations
• packages/core/src/models/transaction.rs — add failure_reason and operation_failures fields
• packages/core/src/services/horizon.rs — parse extras.result_codes from Horizon error response
• packages/core/src/explain/transaction.rs — wire failure explanations into the response

Acceptance Criteria

• Failed transactions include failure_reason with a plain-English explanation
• operation_failures[] array present when operations also have error codes
• All transaction-level codes listed above are translated
• All operation-level codes listed above are translated
• Unknown codes return a graceful fallback (not null or empty)
• Successful transactions have failure_reason: null and operation_failures: []
• Unit tests for each error code translation
• cargo test passes with no regressions

Complexity: High · 200 pts

[NteinPrecious]

hey maintainer, i would really love to work on this?

[grantfox-oss]

🦊 GrantFox — @NteinPrecious 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 #510)
2. Your PR will be reviewed by the StellarCommons 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!

@NteinPrecious's PR #522 was approved and merged by @Tinna23.

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

👏 Great work, @NteinPrecious! Keep contributing to StellarCommons.