CONTRACT_ERROR_MESSAGES maps exactly one on-chain error code — every other lock/unlock/boost failure surfaces a generic failed on-chain message with no actionable detail

[prodbycorne]

Overview

src/lib/soroban.ts maintains a table intended to translate on-chain contract error codes into user-legible messages:

const CONTRACT_ERROR_MESSAGES: Record<string, string> = {
  '1': 'Assets are still locked',
};

export function getContractErrorMessage(errorCode?: string): string | undefined {
  const normalized = normalizeContractErrorCode(errorCode);
  return normalized ? CONTRACT_ERROR_MESSAGES[normalized] : undefined;
}

This table has exactly one entry. Every call site that surfaces a failed on-chain transaction to the user falls back to a generic message the moment the error code isn't '1':

// SorobanService.lockAssets / unlockAssets, e.g. soroban.ts:986-991
error:
  confirmation.status === 'TIMEOUT'
    ? 'Transaction confirmation is taking longer than expected.'
    : getContractErrorMessage(confirmation.errorCode) ??
      `Transaction ${submissionResult.hash} failed on-chain`,

Meanwhile the surrounding infrastructure for extracting a contract error code is substantial and clearly built to support more than one mapped case: findContractErrorCode, extractContractErrorCodeFromXdr, extractContractErrorCode, and normalizeContractErrorCode together implement a recursive, defensive walk through Soroban's XDR result structures — decoding hex, matching contract[_-]?code/error[_-]?code patterns, walking nested union arms — specifically so that confirmation.errorCode is a reliable, normalized string regardless of exactly how the RPC/SDK happens to represent it. All of that machinery currently exists to feed a lookup table with a single entry. Every other realistic on-chain failure a farming-pool/staking contract would define — insufficient balance, pool inactive or closed, amount below the pool's minimum, unauthorized caller, boost percentage out of range, a position that doesn't exist — falls through to Transaction {hash} failed on-chain, a message that gives a user precisely zero information about why their deposit, unlock, or boost-configuration attempt failed, or what they could do differently.

Requirements

• Expand CONTRACT_ERROR_MESSAGES to cover the actual set of error codes the deployed pool/factory contracts define, once that set can be enumerated (from the contract's own error enum/spec, or empirically from observed errorCode values in testnet transactions).
• Where the specific set of contract error codes isn't yet knowable from within this repository, at minimum make the gap visible and trackable rather than silent: log the unmapped errorCode distinctly (e.g. console.warn('[SmartDrop] Unmapped contract error code:', errorCode)) whenever getContractErrorMessage returns undefined, so unmapped codes are discoverable from real usage instead of requiring someone to notice the generic message and go spelunking.
• Consider whether the generic fallback message could at least include the raw errorCode for support/debugging purposes (e.g. Transaction {hash} failed on-chain (code {errorCode})) rather than omitting it entirely when unmapped.

Acceptance Criteria

• CONTRACT_ERROR_MESSAGES contains more than one entry, covering the pool/factory contracts' actual documented or empirically-observed error codes.
• Every code path that calls getContractErrorMessage and receives undefined logs the unmapped code distinctly, so gaps are discoverable going forward without requiring a user complaint first.
• The generic fallback message includes the raw error code (when one was extracted) so a user or support agent has something concrete to reference, even for a still-unmapped code.
• A test enumerates the (updated) CONTRACT_ERROR_MESSAGES table and asserts each entry produces the expected user-facing string via getContractErrorMessage.

Additional Notes

More precise references

• src/lib/soroban.ts:328-330 (CONTRACT_ERROR_MESSAGES) — confirmed the single '1': 'Assets are still locked' entry.
• src/lib/soroban.ts:466-469 (getContractErrorMessage) — confirmed the lookup and undefined fallback.
• src/lib/soroban.ts:368-464 (findContractErrorCode/extractContractErrorCodeFromXdr/extractContractErrorCode/normalizeContractErrorCode) — confirmed this is genuinely substantial, carefully-written extraction logic (recursive XDR-union walking with cycle protection via a WeakSet, hex/decimal normalization, multiple XDR decoder attempts) — i.e. real engineering investment went into reliably producing an errorCode string, which the single-entry lookup table doesn't currently make good use of.
• src/lib/soroban.ts:986-991 (lockAssets's failure path) and :1127-1132 (unlockAssets's failure path) — confirmed both use the identical getContractErrorMessage(...) ?? generic-message pattern, so this gap affects both deposit and withdrawal failures identically.
• src/components/UnlockModal/UnlockModal.tsx:185-190 — confirmed the UI-level consumer: getContractErrorMessage(result.errorCode) ?? result.error ?? "Unlock transaction failed.", i.e. the user-visible text in the modal directly reflects this table's coverage.

Additional edge cases

• Since this repository doesn't contain the actual Soroban contract source, the correct mapping of code → message can't be fully authored from within this codebase alone — the acceptance criteria are written to require either (a) sourcing the real error enum from the contract team/spec, or (b) at minimum making unmapped codes observable in production so the table can be filled in incrementally from real data, rather than leaving the current single-entry table as if it were already complete.
• setBoost's failure path (soroban.ts:1193-1198) does not call getContractErrorMessage at all — it only ever returns the raw Simulation failed: ${simulation.error} string, meaning boost-related contract errors (once boost UI ships, per Boost allocation is fully wired in the data layer but has no UI — the Boost button is permanently disabled dead code #81/Boost allocation is fully wired in the data layer but has no UI — the Boost button is permanently disabled dead code #111) wouldn't benefit from this table even after it's expanded, unless setBoost is also updated to extract and map its error code the same way lockAssets/unlockAssets do — worth including in this fix's scope for consistency.

Implementation sketch

const CONTRACT_ERROR_MESSAGES: Record<string, string> = {
  '1': 'Assets are still locked',
  // additional entries once the contract's real error codes are known, e.g.:
  // '2': 'Insufficient balance for this action',
  // '3': 'This pool is not currently active',
  // ...
};

export function getContractErrorMessage(errorCode?: string): string | undefined {
  const normalized = normalizeContractErrorCode(errorCode);
  if (!normalized) return undefined;
  const message = CONTRACT_ERROR_MESSAGES[normalized];
  if (!message) {
    console.warn('[SmartDrop] Unmapped contract error code:', normalized);
  }
  return message;
}

And update the generic fallbacks (lockAssets/unlockAssets) to include the code when present: `Transaction ${hash} failed on-chain${confirmation.errorCode ? ` (code ${confirmation.errorCode})` : ''}`.

Test/reproduction plan

• getContractErrorMessage('1') → 'Assets are still locked' (existing behavior, regression-protected).
• getContractErrorMessage('99') (an intentionally-unmapped code) → undefined, and assert console.warn fired with that code.
• Once real codes are added: one test per new entry, asserting the exact mapped string.

Cross-references

• No existing issue in the repo's 75-issue history covers the completeness of CONTRACT_ERROR_MESSAGES.

[devkryssie]

I’m interested in this issue because clear error handling is essential for a good user experience. With experience in TypeScript, JavaScript, React, and Web3 development, I can help expand the error mapping, improve fallback messages, and add tests to ensure contract failures provide useful and actionable feedback.

[richardtoms100]

The application's on-chain error translation layer is effectively incomplete: CONTRACT_ERROR_MESSAGES contains only a single mapped error code, '1'.

Every user-facing transaction failure goes through getContractErrorMessage(), but any contract error other than '1' immediately falls back to the generic Transaction <hash> failed on-chain message. This discards the semantic information already provided by the Soroban contract.

As the contract grows and exposes additional error variants, users therefore receive the same opaque failure message for fundamentally different situations—invalid amounts, authorization failures, insufficient balance, invalid state, expired resources, and other contract-specific conditions. A transaction hash is useful for investigation but does not tell a user what they can do to resolve the problem.

I have experience reviewing blockchain UX where raw transaction failures need to be translated into actionable application-level errors. The mapping should cover the contract's complete error enum (and be kept synchronized as new errors are introduced), with a sensible fallback for genuinely unknown codes. The resulting messages should explain the failure in user-facing terms and, where possible, indicate the corrective action rather than exposing only the transaction hash.

[grantfox-oss]

🦊 GrantFox — @richardtoms100 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.