Merge pull request #280 from Meme11030/feat/transaction-idempotency-key

feat(transactions): add idempotency key support

Author: Jambox11

prisma/migrations/20260601000000_add_transaction_idempotency_key/migration.sql

@@ -0,0 +1,8 @@
+-- AlterTable
+ALTER TABLE "Transaction" ADD COLUMN "idempotencyKey" TEXT;
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Transaction_idempotencyKey_key" ON "Transaction"("idempotencyKey");
+
+-- CreateIndex
+CREATE INDEX "Transaction_idempotencyKey_idx" ON "Transaction"("idempotencyKey");

prisma/schema.prisma

@@ -645,6 +645,9 @@ model Transaction {
   
   /// Metadata for future webhooks and analytics
   metadata Json? // Flexible JSON for additional transaction context
+
+  /// Client-supplied idempotency key to prevent duplicate submissions
+  idempotencyKey String? @unique
   
   /// Operational metadata
   createdAt DateTime @default(now())
@@ -658,4 +661,5 @@ model Transaction {
   @@index([stellarHash])
   @@index([stellarLedger])
   @@index([createdAt])
+  @@index([idempotencyKey])
 }

src/transactions/dto/create-transaction.dto.ts

@@ -10,4 +10,6 @@ export class CreateTransactionDto {
   senderWalletId: string;
   receiverWalletId?: string;
   metadata?: Record<string, any>;
+  /** Optional client-supplied key to prevent duplicate submissions */
+  idempotencyKey?: string;
 }

src/transactions/entities/transaction.entity.ts

@@ -30,6 +30,8 @@ export class Transaction {
 
   metadata?: Record<string, any> | null;
 
+  idempotencyKey?: string | null;
+
   createdAt: Date;
   updatedAt: Date;
 }

src/transactions/transactions.service.ts

@@ -33,13 +33,34 @@ export class TransactionsService {
   ) {}
 
   /**
-   * Create a new transaction in PENDING state
+   * Create a new transaction in PENDING state.
+   * If an idempotencyKey is supplied and a transaction with that key already
+   * exists, the existing transaction is returned without creating a duplicate.
    */
   async create(
     createTransactionDto: CreateTransactionDto,
   ): Promise<TransactionEntity> {
-    const { amount, asset, senderWalletId, receiverWalletId, metadata } =
-      createTransactionDto;
+    const {
+      amount,
+      asset,
+      senderWalletId,
+      receiverWalletId,
+      metadata,
+      idempotencyKey,
+    } = createTransactionDto;
+
+    // Idempotency check: return existing transaction if key already used
+    if (idempotencyKey) {
+      const existing = await this.prisma.transaction.findUnique({
+        where: { idempotencyKey },
+      });
+      if (existing) {
+        this.logger.log(
+          `Idempotency hit for key ${idempotencyKey}, returning existing transaction ${existing.id}`,
+        );
+        return this.mapPrismaToEntity(existing);
+      }
+    }
 
     // Validate wallets exist
     const senderWallet = await this.prisma.wallet.findUnique({
@@ -83,20 +104,20 @@ export class TransactionsService {
     }
 
     // Create transaction in database
-    const created = await this.prisma.transaction.create({
-      data: {
-        amount,
-        assetType: asset.type,
-        assetCode: asset.code ?? null,
-        assetIssuer: asset.issuer ?? null,
-        senderWalletId,
-        receiverWalletId: receiverWalletId ?? null,
-        status: TransactionStatus.PENDING,
-        metadata: metadata ?? null,
-      },
-    });
-
-    this.logger.log(`Created transaction ${created.id} in PENDING state`);
+    try {
+      const created = await this.prisma.transaction.create({
+        data: {
+          amount,
+          assetType: asset.type,
+          assetCode: asset.code ?? null,
+          assetIssuer: asset.issuer ?? null,
+          senderWalletId,
+          receiverWalletId: receiverWalletId ?? null,
+          status: TransactionStatus.PENDING,
+          metadata: metadata ?? null,
+          idempotencyKey: idempotencyKey ?? null,
+        },
+      });
 
     this.webhookEventEmitter
       .emitTransactionCreated({
@@ -329,6 +350,7 @@ export class TransactionsService {
       confirmedAt: prismaTransaction.confirmedAt,
       failedAt: prismaTransaction.failedAt,
       metadata: prismaTransaction.metadata,
+      idempotencyKey: prismaTransaction.idempotencyKey,
       createdAt: prismaTransaction.createdAt,
       updatedAt: prismaTransaction.updatedAt,
     };