Soroban transaction polling — implement exponential back-off and FAILED status handling in UnlockModal

[prodbycorne]

Problem

UnlockModal.tsx calls unlockAssets from src/lib/soroban.ts and awaits a TransactionResult. The underlying SorobanService.unlockAssets method submits the transaction and is expected to poll rpcServer.getTransaction(hash) for the final status, but the polling loop is not yet implemented — it returns immediately after sendTransaction.

A transaction can remain in the PENDING or NOT_FOUND state for up to 30 seconds on a loaded network. During this window the UI has no feedback and the user may close the modal or click again, causing a double submission.

Expected Behaviour

After sendTransaction the frontend polls getTransaction(hash) with exponential back-off until SUCCESS, FAILED, or a configurable timeout (30 s). The UnlockModal shows the transaction hash as a clickable Stellar Expert link and a polling spinner during the wait.

Acceptance Criteria

• SorobanService gains a pollTransactionStatus(hash, timeoutMs = 30000) private method implementing exponential back-off starting at 1 s, doubling each attempt, capped at 5 s
• The method returns { status: 'SUCCESS' | 'FAILED' | 'TIMEOUT'; resultXdr?: string; errorCode?: string }
• unlockAssets (and the future lockAssets) call pollTransactionStatus before resolving
• UnlockModal displays three distinct states: Signing → Submitting → Confirming (hash link) → Success / Error
• On FAILED, the contract error code extracted from the result XDR is decoded (e.g. Error::Locked = 1 → "Assets are still locked") and shown to the user
• On TIMEOUT, the modal shows the hash and invites the user to check Stellar Expert manually
• A Vitest test simulates getTransaction returning NOT_FOUND twice then SUCCESS and verifies the result is SUCCESS after 3 calls

Relevant Files

• src/lib/soroban.ts — unlockAssets, add pollTransactionStatus
• src/components/UnlockModal/UnlockModal.tsx — multi-step UI state

[clintjeff2]

Hello, I have 6 years of experience working on tasks like this and handling similar challenges across backend, frontend, and smart-contract development. I have carefully read and fully understood the task requirements, and I am confident I can deliver a clean, efficient, and well-tested solution promptly. I always ensure high-quality implementation, maintainability, and adherence to best practices.

Pull request in 5 hours.

[Sparexonzy95]

Hi team, I’d like to work on this issue.

I understand this as a transaction-finality and user-safety problem in the Unlock flow. Currently, UnlockModal calls unlockAssets and receives a TransactionResult, but the underlying SorobanService returns immediately after sendTransaction instead of waiting for the submitted transaction to reach a final state. Because Soroban transactions may remain PENDING or NOT_FOUND for several seconds, the UI can leave the user without clear confirmation, which increases the risk of confusion, modal closure, or repeated unlock attempts.

My approach will be to make transaction finality explicit inside the Soroban service layer, then reflect that lifecycle clearly in the UnlockModal UI.

I plan to:

1. Add a private pollTransactionStatus(hash, timeoutMs = 30000) method inside SorobanService.
2. Implement exponential backoff starting at 1 second, doubling per attempt, and capped at 5 seconds.
3. Continue polling rpcServer.getTransaction(hash) until the transaction resolves to SUCCESS, FAILED, or TIMEOUT.
4. Return a clear normalized result shape: SUCCESS, FAILED, or TIMEOUT, with resultXdr and errorCode where available.
5. Update unlockAssets so it does not resolve immediately after sendTransaction, but waits for final transaction status first.
6. Keep the method reusable so future lockAssets can use the same polling path.
7. Improve UnlockModal to show a proper transaction lifecycle: Signing → Submitting → Confirming with a clickable Stellar Expert transaction hash → Success or Error.
8. Decode known contract error codes from failed result XDR where possible, so users see meaningful messages such as “Assets are still locked” instead of a vague failure.
9. On timeout, show the transaction hash and guide the user to verify the transaction manually on Stellar Expert.
10. Add Vitest coverage for the polling behavior by simulating getTransaction returning NOT_FOUND twice and then SUCCESS, and confirming the poll resolves successfully after three calls.

This should make the unlock flow safer, more transparent, and less prone to accidental double submissions while keeping the fix focused on the current acceptance criteria.

I’ll keep the PR scoped, include test/build results, and document the polling/status behavior clearly in the PR description.

[grantfox-oss]

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

@Sparexonzy95's PR #64 was approved and merged by @prodbycorne.

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

👏 Great work, @Sparexonzy95! Keep contributing to SmartDropLabs.