Add contract call idempotency and deduplication keys

[Oluwaseyi89]

Summary

Implement idempotency and deduplication mechanisms for contract call records by associating each call with a unique business workflow ID, ensuring that repeated or retried operations do not result in duplicate or ambiguous contract interactions.

Social Media Link

Let's collaborate on Discord. And ensure to star our repo.

Technical Context

• Motivation: Without idempotency and deduplication, network failures, retries, or client errors can lead to multiple contract calls for the same business operation, causing inconsistent state, double execution, or reconciliation challenges. Tying contract calls to workflow IDs enables safe resumption and reliable state tracking.
• Current State: Contract call records may not be uniquely associated with business workflow IDs, making it difficult to detect and prevent duplicate submissions or to resume interrupted operations safely.

Requirements

Backend Changes

• Update the contract call persistence logic to require a unique workflow ID (or equivalent business identifier) for each contract call operation.
• Enforce uniqueness of contract call records based on the workflow ID and contract method, rejecting duplicate submissions for the same workflow.
• Implement deduplication logic to detect and ignore repeated contract call attempts with the same workflow ID.
• Ensure all relevant endpoints and service layers propagate and validate workflow IDs for contract-related operations.
• Provide clear error responses when duplicate or conflicting contract calls are attempted.
• Document the idempotency and deduplication strategy in code and operational docs.

Acceptance Criteria

• Each contract call record is uniquely tied to a business workflow ID.
• Duplicate contract call attempts with the same workflow ID are safely ignored or rejected.
• Retried or resumed operations do not result in duplicate contract calls or inconsistent state.
• Tests cover normal, duplicate, and retry scenarios.
• Documentation updated to describe the idempotency and deduplication approach.

Definition of Done

• PR with code changes, tests, and documentation
• Verified in staging/production environments
• Team review completed

Working Directory

corporate-platform/corporate-platform-backend

[lawalajose]

@lawalajose has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi! I’d love to work on this issue because it genuinely interests me. I’m proficient in Go and have experience working with backend systems, APIs, and open-source collaboration. I’d be happy to contribute and help move this forward.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @lawalajose to this issue.

[drips-wave]

Congratulations, @lawalajose! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @lawalajose: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊