Implement a distributed idempotency layer for buy and sell endpoints using Redis to prevent double-execution across concurrent retries

[Chucks1093]

Summary

When a client retries a buy or sell request due to a network timeout, the server may process the same transaction twice — charging the buyer or crediting the seller multiple times. A distributed idempotency layer backed by Redis should detect duplicate requests within a configurable window and return the original response without re-executing the transaction.

Scope

• Accept an Idempotency-Key header on POST /buy and POST /sell endpoints
• On first request: execute the transaction, store { statusCode, body, resolvedAt } in Redis under the key with a 24-hour TTL, then return the response
• On duplicate request (same key within TTL): return the stored response immediately without touching the database or Soroban
• If the first request is still in-flight when a duplicate arrives, block the duplicate for up to 5 seconds then either return the in-progress result or a 409 request_in_progress
• Reject requests missing the Idempotency-Key header with 400 missing_idempotency_key
• Namespace keys by wallet address to prevent cross-wallet collisions: idempotency:{walletAddress}:{key}
• Add integration tests covering: first execution stores result, duplicate returns stored result, in-flight duplicate returns 409, missing header returns 400, expired key allows re-execution

Acceptance Criteria

• First request executes and stores result in Redis with 24-hour TTL
• Duplicate key within TTL returns stored response without re-executing
• In-flight duplicate blocked up to 5 seconds then returns 409
• Missing header returns 400 with missing_idempotency_key
• Keys namespaced by wallet to prevent cross-wallet collisions
• Expired key allows a fresh execution (TTL enforced correctly)
• No Soroban transaction submitted on a duplicate request

ETA: 24 hours

---

Coordinate on Telegram

[nurudeenheroic]

I'd love to help resolve this issue with a clean and maintainable approach.

[lekanay2005-coder]

i will like to work on this issue pls

[AUWALANCHAU]

I have experience with web development and programming, particularly HTML, CSS, JavaScript, and Python. I approach technical issues by first understanding the problem, reproducing it when possible, identifying the root cause, and then testing a clear solution. I also value clean, maintainable code and documenting the changes so others can easily understand and contribute.

[Adecom16]

I'd like to jump on this

I will set up the namespaced keys, handle the 5-second in-flight wait/lock mechanism, and ensure full integration test coverage within the requested 24-hour ETA

[nomsoscript]

Hey, can I work on this.

[grantfox-oss]

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

Good luck! Track your progress on GrantFox.