feat(backend): make stream creation and withdrawal idempotent

[arisu6804]

Problem

Client retries after provider timeouts can create duplicate streams or withdraw the same accrued amount twice.

Objective

Deliver a production-quality improvement to stream creation, top-up, and withdrawal commands that creates measurable value for correctness, security, reliability, performance, or maintainability.

Implementation scope

• Require actor-scoped idempotency keys and request fingerprints; persist terminal outcomes; serialize concurrent commands.

Acceptance criteria

• Retries return the original result; conflicting payloads fail; one balance mutation and lifecycle event are produced.

Required validation

• Concurrency, restart, timeout, conflict, and duplicate-provider 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.

Why this issue specifically: three days ago I audited a Stellar payments service and this was the top finding. Filed as a tracked issue: creation was not idempotent, so two consecutive POSTs produced the same sequence number and the same txHash, and the observer then 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 adjacent failure: a settlement path that reported success when the on-chain lock had failed.

The part I would want to settle before writing code, because it is where these implementations usually go wrong:

The record has to be persisted before the on-chain call is issued, not after. If the process dies between "sent to chain" and "wrote the result", a retry with the same key finds nothing stored and duplicates the withdrawal. That means the store needs a non-terminal state, and the retry path has to distinguish "in progress" from "never seen". Without it, the restart test is unpassable.

That leaves the three cases to agree on:

• Same key, same payload: return the stored terminal result.
• Same key, different payload: reject clearly. My reading is 409 naming the fields that diverged, not a generic error.
• Same key, still in progress: this is the design decision. Serialize with a bounded wait, or answer immediately with an in-progress marker and let the client retry. I lean toward the first with a fallback to the second on timeout, since a withdrawal holding a connection open is worse than a retry.

For streams specifically there is one more wrinkle worth naming: a withdrawal is idempotent on the request, but the amount it settles depends on elapsed time. So the stored result has to be the amount actually moved, not a recomputation, or a retry after a few seconds returns a different figure for the same key.

Happy to answer anything before you assign.