- ✓
+ {VARIANT_ICON[variant] ?? VARIANT_ICON.success}
- {status}
+ {label}
-
-
-
Transaction Hash
-
-
- {shortenedHash}
-
-
+ {message &&
{message}
}
+
+ {hash && (
+
+
+
Transaction Hash
+
+
+ {shortenedHash}
+
+
+
-
-
- View on Stellar Expert
-
-
-
+ View on Stellar Expert
+
+
+
+ )}
);
}
diff --git a/frontend/src/hooks/useOptimisticAction.js b/frontend/src/hooks/useOptimisticAction.js
new file mode 100644
index 00000000..9bfd2c75
--- /dev/null
+++ b/frontend/src/hooks/useOptimisticAction.js
@@ -0,0 +1,93 @@
+import { useCallback, useRef, useState } from 'react';
+import { mapError as defaultMapError } from '../lib/errorMapping';
+
+/**
+ * useOptimisticAction — drives an "optimistic UI" lifecycle for an async,
+ * chain-backed action (register, claim, …):
+ *
+ * submit → apply optimistic state immediately
+ * → await the real action
+ * → success: reconcile with chain truth
+ * → failure: roll back the optimistic state + surface a mapped error
+ *
+ * It also guards against double-submit (a second `run` while one is in flight
+ * is ignored) so a double-click can't fire two transactions.
+ *
+ * State machine: 'idle' → 'pending' → 'success' | 'error'.
+ *
+ * @param {{ mapError?: (error: unknown) => object }} [options]
+ * `mapError` converts a thrown error into the structured shape from
+ * lib/errorMapping (overridable for testing). Defaults to the shared mapper.
+ */
+export function useOptimisticAction({ mapError = defaultMapError } = {}) {
+ const [status, setStatus] = useState('idle');
+ const [error, setError] = useState(null);
+ // Synchronous in-flight latch: state updates are async, so a ref is what
+ // actually prevents a same-tick double-submit.
+ const inFlight = useRef(false);
+
+ /**
+ * @template T
+ * @param {() => Promise
} action The real async action (e.g. submit tx).
+ * @param {{
+ * optimistic?: () => void, // apply expected state right away
+ * rollback?: () => void, // undo the optimistic state on failure
+ * reconcile?: (result: T) => void, // align local state with chain truth
+ * }} [handlers]
+ * @returns {Promise<{ ok: boolean, skipped?: boolean, result?: T, error?: object }>}
+ */
+ const run = useCallback(
+ async (action, { optimistic, rollback, reconcile } = {}) => {
+ if (inFlight.current) {
+ return { ok: false, skipped: true };
+ }
+ inFlight.current = true;
+ setStatus('pending');
+ setError(null);
+
+ let appliedOptimistic = false;
+ try {
+ if (optimistic) {
+ optimistic();
+ appliedOptimistic = true;
+ }
+
+ const result = await action();
+
+ reconcile?.(result);
+ setStatus('success');
+ return { ok: true, result };
+ } catch (err) {
+ // Only undo what we actually applied — keeps rollback idempotent and
+ // correct even if the failure happened before the optimistic step.
+ if (appliedOptimistic) {
+ rollback?.();
+ }
+ const mapped = mapError(err);
+ setError(mapped);
+ setStatus('error');
+ return { ok: false, error: mapped };
+ } finally {
+ inFlight.current = false;
+ }
+ },
+ [mapError],
+ );
+
+ const reset = useCallback(() => {
+ setStatus('idle');
+ setError(null);
+ }, []);
+
+ return {
+ status,
+ error,
+ isPending: status === 'pending',
+ isSuccess: status === 'success',
+ isError: status === 'error',
+ run,
+ reset,
+ };
+}
+
+export default useOptimisticAction;
diff --git a/frontend/src/hooks/useOptimisticAction.test.jsx b/frontend/src/hooks/useOptimisticAction.test.jsx
new file mode 100644
index 00000000..3ddd21e0
--- /dev/null
+++ b/frontend/src/hooks/useOptimisticAction.test.jsx
@@ -0,0 +1,167 @@
+// Tests for the optimistic-action lifecycle hook and the error classification
+// that powers register/claim's rollback messaging (#627).
+//
+// Located under src/hooks/ to match the vitest `include` glob
+// (src/hooks/**/*.test.{js,jsx}) so it runs in CI.
+
+import { renderHook, act } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { useOptimisticAction } from './useOptimisticAction';
+import { classifyError, mapError, ERROR_CLASS } from '../lib/errorMapping';
+
+describe('useOptimisticAction', () => {
+ it('applies the optimistic update, then reconciles on success', async () => {
+ const { result } = renderHook(() => useOptimisticAction());
+ const optimistic = vi.fn();
+ const reconcile = vi.fn();
+ const rollback = vi.fn();
+
+ await act(async () => {
+ const outcome = await result.current.run(async () => 'BALANCE_42', {
+ optimistic,
+ rollback,
+ reconcile,
+ });
+ expect(outcome).toEqual({ ok: true, result: 'BALANCE_42' });
+ });
+
+ expect(optimistic).toHaveBeenCalledTimes(1);
+ expect(reconcile).toHaveBeenCalledWith('BALANCE_42');
+ expect(rollback).not.toHaveBeenCalled();
+ expect(result.current.isSuccess).toBe(true);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('rolls back and surfaces a mapped error on failure', async () => {
+ const { result } = renderHook(() => useOptimisticAction());
+ const optimistic = vi.fn();
+ const rollback = vi.fn();
+ const reconcile = vi.fn();
+
+ await act(async () => {
+ const outcome = await result.current.run(
+ async () => {
+ throw new Error('Error(Contract, #103)');
+ },
+ { optimistic, rollback, reconcile },
+ );
+ expect(outcome.ok).toBe(false);
+ expect(outcome.error.class).toBe(ERROR_CLASS.CONTRACT);
+ });
+
+ expect(optimistic).toHaveBeenCalledTimes(1);
+ expect(rollback).toHaveBeenCalledTimes(1);
+ expect(reconcile).not.toHaveBeenCalled();
+ expect(result.current.isError).toBe(true);
+ expect(result.current.error.code).toBe(103);
+ expect(result.current.error.message).toMatch(/not active/i);
+ });
+
+ it('does not roll back if the failure happens before the optimistic step', async () => {
+ const { result } = renderHook(() => useOptimisticAction());
+ const rollback = vi.fn();
+
+ await act(async () => {
+ await result.current.run(
+ async () => {
+ throw new Error('boom');
+ },
+ {
+ optimistic: () => {
+ throw new Error('optimistic failed');
+ },
+ rollback,
+ },
+ );
+ });
+
+ // The optimistic callback threw, so nothing was applied → nothing to undo.
+ expect(rollback).not.toHaveBeenCalled();
+ expect(result.current.isError).toBe(true);
+ });
+
+ it('ignores a second submit while one is in flight (double-submit guard)', async () => {
+ const { result } = renderHook(() => useOptimisticAction());
+
+ let resolveFirst;
+ const action = vi.fn(
+ () =>
+ new Promise((resolve) => {
+ resolveFirst = resolve;
+ }),
+ );
+
+ let firstPromise;
+ act(() => {
+ firstPromise = result.current.run(action);
+ });
+ expect(result.current.isPending).toBe(true);
+
+ // Second call while pending must be skipped and must not invoke the action.
+ await act(async () => {
+ const second = await result.current.run(action);
+ expect(second).toEqual({ ok: false, skipped: true });
+ });
+ expect(action).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ resolveFirst('ok');
+ await firstPromise;
+ });
+ expect(result.current.isSuccess).toBe(true);
+
+ // After settling, a fresh submit is allowed again.
+ await act(async () => {
+ await result.current.run(async () => 'again');
+ });
+ expect(action).toHaveBeenCalledTimes(1);
+ });
+
+ it('reset returns the hook to its idle state', async () => {
+ const { result } = renderHook(() => useOptimisticAction());
+
+ await act(async () => {
+ await result.current.run(async () => {
+ throw new Error('nope');
+ });
+ });
+ expect(result.current.isError).toBe(true);
+
+ act(() => {
+ result.current.reset();
+ });
+ expect(result.current.status).toBe('idle');
+ expect(result.current.error).toBeNull();
+ });
+});
+
+describe('error classification (distinct messaging)', () => {
+ it('classifies a contract revert by its decoded code', () => {
+ expect(classifyError(new Error('HostError: Error(Contract, #102)'))).toBe(ERROR_CLASS.CONTRACT);
+ const mapped = mapError(new Error('Error(Contract, #102)'));
+ expect(mapped.code).toBe(102);
+ expect(mapped.message).toMatch(/participant limit/i);
+ });
+
+ it('classifies a wallet rejection separately from a system failure', () => {
+ expect(classifyError(new Error('User declined the transaction in Freighter'))).toBe(
+ ERROR_CLASS.WALLET,
+ );
+ expect(mapError(new Error('User rejected request')).message).toMatch(/cancelled/i);
+ });
+
+ it('distinguishes network failures from contract reverts', () => {
+ expect(classifyError(new TypeError('Failed to fetch'))).toBe(ERROR_CLASS.NETWORK);
+ const net = mapError(new Error('network timeout while submitting'));
+ expect(net.class).toBe(ERROR_CLASS.NETWORK);
+ expect(net.retryable).toBe(true);
+ expect(net.message).toMatch(/not submitted/i);
+ });
+
+ it('classifies RPC/Horizon outages as their own class', () => {
+ const rpc = mapError(new Error('Soroban RPC simulate failed: 503 service unavailable'));
+ expect(rpc.class).toBe(ERROR_CLASS.RPC);
+ expect(rpc.retryable).toBe(true);
+ expect(rpc.message).toMatch(/temporarily unavailable/i);
+ });
+});
diff --git a/frontend/src/lib/errorMapping.js b/frontend/src/lib/errorMapping.js
index 59869c81..2779ab82 100644
--- a/frontend/src/lib/errorMapping.js
+++ b/frontend/src/lib/errorMapping.js
@@ -31,6 +31,128 @@ export const ERROR_MESSAGES = {
503: 'The blockchain service is temporarily unavailable',
};
+/**
+ * Coarse error classes used to give register/claim failures distinct messaging
+ * and to decide how the optimistic UI should recover (see useOptimisticAction).
+ *
+ * - `contract` — the contract reverted with a known/mapped error code.
+ * - `wallet` — the user rejected/closed the signing prompt.
+ * - `network` — request never reached the chain (offline, DNS, timeout).
+ * - `rpc` — Soroban RPC / Horizon reachable but failing (5xx, simulate).
+ * - `validation` — client-side input problem.
+ * - `unknown` — anything we can't confidently bucket.
+ */
+export const ERROR_CLASS = {
+ CONTRACT: 'contract',
+ WALLET: 'wallet',
+ NETWORK: 'network',
+ RPC: 'rpc',
+ VALIDATION: 'validation',
+ UNKNOWN: 'unknown',
+};
+
+/** Per-class fallback copy used when no specific contract message applies. */
+const CLASS_MESSAGES = {
+ [ERROR_CLASS.WALLET]: 'Signing was cancelled in your wallet. Nothing was submitted.',
+ [ERROR_CLASS.NETWORK]:
+ 'Network problem reaching the blockchain — your action was not submitted. Check your connection and try again.',
+ [ERROR_CLASS.RPC]:
+ 'The Soroban network is temporarily unavailable. Your action was not applied; please try again in a moment.',
+ [ERROR_CLASS.VALIDATION]: 'Please check your input and try again.',
+ [ERROR_CLASS.UNKNOWN]: 'An unexpected error occurred. Your action was not applied.',
+};
+
+/**
+ * Extract a numeric contract/HTTP error code from any error shape.
+ * @param {Error|number|string|object} error
+ * @returns {number|null}
+ */
+export function extractErrorCode(error) {
+ if (error === null || error === undefined) return null;
+ if (typeof error === 'number') return Number.isFinite(error) ? error : null;
+ if (typeof error === 'string') {
+ const fromString = error.match(/(?:Error\(Contract,\s*#|contract.*?#|code[:\s]+)(\d+)/i);
+ return fromString ? Number(fromString[1]) : null;
+ }
+ if (typeof error.code === 'number') return error.code;
+ if (typeof error.status === 'number') return error.status;
+ const text = error.message || error.toString?.() || '';
+ const match = text.match(/(?:Error\(Contract,\s*#|contract.*?#|code[:\s]+)(\d+)/i);
+ return match ? Number(match[1]) : null;
+}
+
+/**
+ * Classify an error so the UI can show class-specific messaging and decide
+ * recovery. Order matters: a contract revert with a real code is the most
+ * specific signal, a rejected wallet prompt next, then transport problems.
+ * @param {Error|number|string|object} error
+ * @returns {string} one of ERROR_CLASS
+ */
+export function classifyError(error) {
+ if (!error) return ERROR_CLASS.UNKNOWN;
+
+ const code = extractErrorCode(error);
+ const text = (
+ typeof error === 'string' ? error : error.message || error.toString?.() || ''
+ ).toLowerCase();
+
+ // A decoded contract revert (e.g. `Error(Contract, #103)`) is unambiguous.
+ if (/error\(contract|contract.*?#\d+/i.test(text)) return ERROR_CLASS.CONTRACT;
+
+ // User-driven wallet rejections must not look like a system failure.
+ if (
+ /user (rejected|declined)|reject|declin|denied|cancel|freighter|wallet|not allowed/.test(text)
+ )
+ return ERROR_CLASS.WALLET;
+
+ // Transport: never reached the chain.
+ if (
+ /failed to fetch|networkerror|offline|timeout|timed out|enotfound|econnrefused|etimedout|dns/.test(
+ text,
+ )
+ )
+ return ERROR_CLASS.NETWORK;
+
+ // RPC/Horizon reachable but erroring.
+ if (/rpc|simulat|soroban|horizon|gateway|bad gateway|service unavailable|50[023]/.test(text))
+ return ERROR_CLASS.RPC;
+
+ if (/invalid|required|must be|too large|not a number/.test(text)) return ERROR_CLASS.VALIDATION;
+
+ // A bare contract code with no transport hints is still a contract error.
+ if (typeof code === 'number' && code >= 1 && code <= 199) return ERROR_CLASS.CONTRACT;
+
+ return ERROR_CLASS.UNKNOWN;
+}
+
+/**
+ * Map any error to a structured, user-facing shape for the optimistic UI.
+ * @param {Error|number|string|object} error
+ * @returns {{ class: string, code: number|null, message: string, recovery: string|null, retryable: boolean }}
+ */
+export function mapError(error) {
+ const errorClass = classifyError(error);
+ const code = extractErrorCode(error);
+
+ // Contract reverts get the precise per-code copy; everything else uses the
+ // class-level message so network/RPC failures read differently from reverts.
+ const message =
+ errorClass === ERROR_CLASS.CONTRACT && code && ERROR_MESSAGES[code]
+ ? getErrorMessage(code)
+ : CLASS_MESSAGES[errorClass] || getErrorMessage(error);
+
+ return {
+ class: errorClass,
+ code: code ?? null,
+ message,
+ recovery: code ? getRecoverySuggestion(code) : null,
+ retryable:
+ errorClass === ERROR_CLASS.NETWORK ||
+ errorClass === ERROR_CLASS.RPC ||
+ (code ? isRetryableError(code) : false),
+ };
+}
+
/**
* Get user-friendly error message from error object or code
* @param {Error|number|string} error - Error object, code, or status