Optimistic UI Updates and Rollback Management for Node Escrow Adjustments

[JamesEjembi]

Problem Statement

Soroban transaction finality on Stellar can take 3–7 seconds. When users deposit or withdraw escrow funds from the billing dashboard, the multi-second wait for chain confirmation creates a sluggish UX. Users often tap submit repeatedly, causing duplicate transactions. The current useSorobanBilling hook provides no optimistic UI layer, so the dashboard balance only updates after the backend confirms the ledger change. This destroys the feeling of responsiveness expected in modern Web3 applications.

Technical Bounds & Invariants

• Optimistic updates must be applied locally within 50ms of user action.
• If the on-chain transaction fails, the local state must revert to the pre-action values within 200ms.
• Duplicate submissions must be prevented via a transaction nonce deduplication layer.
• The optimistic state must survive accidental browser tab refreshes via sessionStorage recovery.
• Contract revert errors must be mapped to user-facing messages that explain why the optimistic update was rolled back.

Codebase Navigation Guide

• /src/hooks/useSorobanBilling.ts - Current billing hook; needs optimistic wrapper.
• /src/components/wallet/EscrowPanel.tsx - UI panel for deposit/withdraw actions.
• /src/lib/txQueue.ts - Transaction queue for ordering submissions.
• /src/services/localCache.ts - sessionStorage persistence layer for optimistic state.

Step-by-Step Resolution Blueprint

1. Create an OptimisticTransactionManager class that wraps the Soroban contract call with a unique client-generated nonce.
2. On submit, immediately apply the balance delta to the React Query cache via queryClient.setQueryData with a rollback snapshot.
3. Persist the optimistic state snapshot to sessionStorage keyed by the nonce.
4. Send the actual Soroban contract invocation; if successful, mark the nonce as confirmed and remove the rollback snapshot.
5. If the transaction reverts, restore the pre-action snapshot from the rollback store and trigger a toast notification with the decoded error.
6. Use useRef flags to prevent double-submission: disable the submit button until a response is received.
7. Write a recovery routine in useSorobanBilling that checks sessionStorage on mount for orphaned optimistic entries (from tab crashes) and reconciles them with the backend.

[damianosakwe]

Hello maintainer i would like to work on this issue and I will fix it perfecty

[grantfox-oss]

🦊 GrantFox — @damianosakwe 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 #5)
2. Your PR will be reviewed by the Lumina-etwork 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!

@damianosakwe's PR #34 was approved and merged by @JamesEjembi.

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

👏 Great work, @damianosakwe! Keep contributing to Lumina-etwork.