Rework refund approvals into a state machine with on-chain settlement

[grantfox-oss]

Refund approval updates database status to approved, but does not appear to execute or track the contract refund operation. This can create a dangerous gap where operators believe a refund was approved while escrow funds remain on-chain.

Affected areas: app/backend/src/refunds/refunds.service.ts, app/backend/src/refunds/refunds.controller.ts, app/backend/src/refunds/refunds.types.ts, app/backend/src/transactions/soroban-rpc.service.ts, app/backend/src/common/soroban-errors/*, app/backend/supabase/migrations/*refund*, refund tests/docs.

Implementation scope:

• Introduce explicit states such as pending, approved, submitted, confirmed, failed, rejected.
• Store on-chain transaction hash, contract ID, network, failure reason, and retry metadata.
• Wire approval to a job or service that calls the contract refund function.
• Make idempotency keys cover both database and on-chain submission paths.

Acceptance criteria:

• Approved refunds eventually become confirmed or failed with a clear reason.
• Duplicate approvals cannot submit duplicate contract refunds.
• API responses expose refund state, transaction hash, and retryability.

[modrispath]

This is a genuinely dangerous gap. Marking a refund as approved in the database without actually triggering the on-chain operation means operators are looking at a status that doesn't reflect reality, and escrow funds that users expect to have received are still sitting in the contract. That needs to be fixed at the architecture level, not patched.

The core change is introducing a proper state machine in refunds.types.ts with explicit states: pending, approved, submitted, confirmed, failed, and rejected. Each transition needs to be intentional and traceable, not just a status column that gets overwritten. I'll update the Supabase schema via migration to store the on-chain transaction hash, contract ID, network, failure reason, and retry metadata alongside the status so the full lifecycle is auditable.

In refunds.service.ts the approval flow gets split into two distinct steps. The first step records the approval in the database and transitions state to approved. The second step, handled by a background job or service, picks up approved refunds, calls the contract refund function via soroban-rpc.service.ts, and transitions to submitted on dispatch or failed with a reason if the call errors. Confirmation gets tracked separately once the transaction is finalized on-chain, moving state to confirmed.

Idempotency needs to cover both paths. A refund with a given idempotency key should not be submittable twice regardless of whether the duplicate comes in before or after the on-chain submission goes out. I'll make sure the key is checked against both the database record and any in-flight submission state.

For soroban-errors I'll extend the existing error handling to map contract-level failures to structured failure reasons that get stored on the refund record and exposed in the API response, so callers know whether a failed refund is retryable or terminal.

Tests will cover the full state machine including duplicate approval attempts, on-chain submission failure with retry metadata, and confirmation flow.

Will open a draft PR with the state machine types and migration first so the schema and state transitions can be agreed on before wiring up the job and contract calls.

[Noble-Devbase]

Hi maintainer I have thoroughly read the description to this issue and I can resolve this according to the description required ensuring it meet all the acceptance criteria kindly assign..

[grantfox-oss]

🦊 GrantFox — @Noble-Devbase 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 #3)
2. Your PR will be reviewed by the BlockDash-Studios 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!

@Noble-Devbase's PR #47 was approved and merged by @MaryammAli.

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

👏 Great work, @Noble-Devbase! Keep contributing to BlockDash-Studios.