feat(backend): make transfer creation idempotent under retries and concurrency

[arisu6804]

Problem

A client or provider retry can create duplicate transfers when the original request timed out before its response was delivered.

Objective

Deliver a production-quality improvement to transfer creation and mutation service that creates measurable value for correctness, security, reliability, performance, or maintainability.

Implementation scope

• Require an actor-scoped idempotency key and canonical request fingerprint; persist terminal results; serialize concurrent requests and reject conflicting reuse.

Acceptance criteria

• A retry returns the original transfer without duplicate movement; conflicting payloads fail clearly; one audit record and one provider command are produced.

Required validation

• Concurrent request, timeout, restart, conflict, and provider-retry integration tests.
• Existing tests and CI remain passing.
• Add regression coverage for the original failure mode.
• Do not weaken, delete, or skip unrelated tests to obtain a green build.

PR quality bar

• Keep the PR focused and explain design tradeoffs, compatibility impact, and test evidence.
• Avoid typo-only, documentation-only, cosmetic-only, or unrelated refactor submissions.

Out of scope

• Broad rewrites not required by the acceptance criteria.
• Changes to unrelated services, contracts, or user flows.

[leocagli]

Hi, I would like to take this one.

I am Leo Cagliero, from the Starmaker program, working on Cosmos LATAM and Open Stellar. I maintain @cosmosapp/pay_sdk, a Stellar SEP-7 payments SDK, so this failure mode is the one I spend my time on.

Why I am credible on this specific issue: three days ago I audited a NestJS + Prisma Stellar payments service and the top finding was this exact bug class. It is now filed as a tracked issue: swap creation was not idempotent, so two consecutive POSTs produced the same sequence number and the same txHash, and the observer emitted the success event twice for a single on-chain operation. I also shipped a merged fix in another payments repo (Micopay/micopaybridge#12) for the sibling problem: a settlement path that reported success on a failed lock.

One thing I want to flag before writing code, because it changes the design and I would rather agree with you first.

The scope says "actor-scoped idempotency key and canonical request fingerprint". Those two are doing different jobs and the interesting case is when they disagree:

• Same key, same fingerprint: return the stored terminal result. Straightforward.
• Same key, different fingerprint: that is the conflict case, and per the acceptance criteria it must "fail clearly". My reading is 409, with a body naming which fields diverged, not a generic error.
• Concurrent requests with the same key where neither has finished: this is the one that decides the design. Serializing means the second request blocks until the first reaches a terminal state. If the provider call is slow, that request holds a connection. The alternative is returning 409 immediately with a "in progress" marker and letting the client retry. I lean toward serializing with a bounded wait plus a fallback to the in-progress response on timeout, but tell me if you prefer a different tradeoff.

There is also a subtlety in "persist terminal results": the record has to be written before the provider command is issued, not after, or a crash between the two leaves no trace and the retry duplicates. That means the store needs a non-terminal state too, which is what makes the restart test in your validation list meaningful.

On the required validation, the restart test is the one that usually gets skipped and it is the one that matters most: kill the process between persisting the intent and receiving the provider response, then retry with the same key and assert one audit record and one provider command. I would write that one first.

Happy to answer anything before you assign.

[grantfox-oss]

🦊 GrantFox — @leocagli 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 #128)
2. Your PR will be reviewed by the RemitFlow maintainers

Good luck! Track your progress on GrantFox.