Implement Request Idempotency for Critical Mutations

[Mkalbani]

Description

Add idempotency key support to critical state-changing endpoints — session submission, reward grants, and NFT minting — so that clients can safely retry requests without risking duplicate side effects. This is especially important given the on-chain integrations where double-processing a mint or reward could have real financial consequences.

Acceptance Criteria

• An Idempotency-Key header is accepted on POST /sessions, POST /nft/mint, and reward endpoints
• Idempotency keys are stored with the request hash and response in a IdempotencyRecord entity
• Replaying a request with the same key returns the original cached response without re-executing
• Keys expire after a configurable TTL (default 24 hours)
• Missing idempotency keys on protected endpoints return a 400 with instructions
• A NestJS interceptor handles idempotency check and cache uniformly across decorated routes
• Concurrent requests with the same key are serialised — only one executes, others wait for the result
• Unit tests cover first execution, replay, expiry, concurrency handling, and missing key enforcement

[Ayinkx01]

Hi l would like to take this job

[nanoulloa]

Here's one tailored to this issue (NestJS idempotency, financial-side risk on mint/reward):

Hi! I'd like to apply for this issue. This is a classic idempotency pattern but with real stakes here given the on-chain mint/reward flows, so getting the concurrency and caching semantics right matters more than usual.
My approach:

IdempotencyInterceptor in NestJS that reads the Idempotency-Key header, hashes the request body, and checks against the IdempotencyRecord entity before letting the handler run.
On first execution: store {key, requestHash, status: 'processing'}, run the handler, then persist the response and flip to completed.
On replay: if completed, return cached response immediately; if requestHash differs from what's stored for that key, return a 409/422 (key reuse with different payload); if processing, block/poll until resolved instead of re-executing (this handles the concurrent-request case with a DB-level lock or unique constraint on the key).
TTL-based expiry via a scheduled cleanup job or lazy check on read, defaulting to 24h and configurable via env.
Missing key on protected routes (POST /sessions, POST /nft/mint, reward endpoints) short-circuits with a 400 and a clear message on how to generate/pass one.
Tests covering: first execution, exact replay, replay with mismatched payload, expiry, and concurrent duplicate requests.

I can have a draft PR up with tests in a few days, happy to align on the entity schema first if there's a preferred ORM/migration convention in the repo.

[gelluisaac]

Hi, I’m interested in working on this issue. I have experience with web and blockchain development, and I’d love to contribute to the project. Please assign this issue to me if it’s available. Thanks!

[estebanbq07]

Hi! I'd like to take this issue if it's available.

I'm interested in implementing the idempotency layer for the protected endpoints. I'll review the current architecture, implement a reusable NestJS interceptor, add support for idempotency records with TTL, handle concurrent requests safely, and include comprehensive unit tests.

I'd appreciate it if you could assign this issue to me. Thanks!

[grantfox-oss]

🦊 GrantFox — @nanoulloa has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #85)
2. Your PR will be reviewed by the MindFlowInteractive maintainers

Good luck! Track your progress on GrantFox.