fix(maintenance-pool): guard assignReward on (pool escrow, issueId) (…

src/common/entities/payment.entity.spec.ts

@@ -18,4 +18,22 @@ describe('Payment entity indexes', () => {
       ]),
     );
   });
+
+  // #458: unique index on (escrowId, maintenanceIssueId) closes concurrent-call
+  // double-payout races for maintenance pool rewards.
+  it('indexes (escrowId, maintenanceIssueId) as unique UQ_payment_escrow_maintenance_issue', () => {
+    const indexes = getMetadataArgsStorage().indices.filter(
+      (index) => index.target === Payment,
+    );
+
+    expect(indexes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: 'UQ_payment_escrow_maintenance_issue',
+          columns: ['escrowId', 'maintenanceIssueId'],
+          unique: true,
+        }),
+      ]),
+    );
+  });
 });

src/common/entities/payment.entity.ts

@@ -10,6 +10,7 @@ import {
 } from 'typeorm';
 import { Escrow } from './escrow.entity';
 import { User } from './user.entity';
+import { Issue } from './issue.entity';
 import { AssetType, PaymentStatus } from '../enums';
 
 /**
@@ -22,9 +23,18 @@ import { AssetType, PaymentStatus } from '../enums';
  * payout — a hot path on every milestone-driven incremental release
  * (#307). The same gap class as `IDX_escrow_sponsor_status` (#97) and the
  * `Bounty.claimedById` index (#148).
+ *
+ * `UQ_payment_escrow_maintenance_issue` prevents duplicate payouts for the
+ * same maintenance issue from the same pool's escrow, closing concurrent-call
+ * races (#458).
  */
 @Entity('payments')
 @Index('IDX_payment_escrow', ['escrowId'])
+@Index(
+  'UQ_payment_escrow_maintenance_issue',
+  ['escrowId', 'maintenanceIssueId'],
+  { unique: true },
+)
 export class Payment {
   @PrimaryGeneratedColumn('uuid')
   id: string;
@@ -51,6 +61,13 @@ export class Payment {
   @Column({ type: 'varchar', nullable: true })
   recipientAddress: string | null;
 
+  @ManyToOne(() => Issue, { onDelete: 'SET NULL', nullable: true })
+  @JoinColumn()
+  maintenanceIssue: Issue | null;
+
+  @Column({ type: 'varchar', nullable: true })
+  maintenanceIssueId: string | null;
+
   @Column({ type: 'decimal', precision: 20, scale: 7 })
   amount: string;
 

src/database/migrations/1785400000000-AddPaymentMaintenanceIssueIdAndIndex.ts

@@ -0,0 +1,41 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Fixes #458: Add maintenanceIssueId to payments and unique index
+ * on (escrowId, maintenanceIssueId) to prevent double payouts for the
+ * same maintenance issue.
+ */
+export class AddPaymentMaintenanceIssueIdAndIndex1785400000000
+  implements MigrationInterface
+{
+  name = 'AddPaymentMaintenanceIssueIdAndIndex1785400000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "payments" ADD COLUMN IF NOT EXISTS "maintenanceIssueId" character varying`,
+    );
+    const fkCheck = (await queryRunner.query(`
+      SELECT 1 FROM pg_constraint WHERE conname = 'FK_payment_maintenance_issue'
+    `)) as Array<unknown>;
+    if (!fkCheck || fkCheck.length === 0) {
+      await queryRunner.query(
+        `ALTER TABLE "payments" ADD CONSTRAINT "FK_payment_maintenance_issue" FOREIGN KEY ("maintenanceIssueId") REFERENCES "issues"("id") ON DELETE SET NULL`,
+      );
+    }
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS "UQ_payment_escrow_maintenance_issue" ON "payments" ("escrowId", "maintenanceIssueId")`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS "UQ_payment_escrow_maintenance_issue"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "payments" DROP CONSTRAINT IF EXISTS "FK_payment_maintenance_issue"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "payments" DROP COLUMN IF EXISTS "maintenanceIssueId"`,
+    );
+  }
+}

src/escrow/escrow.service.spec.ts

@@ -851,6 +851,31 @@ describe('EscrowService', () => {
       expect(payment.amount).toBe('10.0000000');
     });
 
+    it('records maintenanceIssueId on the payment when provided (#458)', async () => {
+      escrowRepo.findOne.mockResolvedValue(lockedPoolEscrow());
+      userRepo.find.mockResolvedValue([
+        { id: 'user-1', stellarAddress: 'GRECIPIENT' },
+      ]);
+
+      await service.poolWithdraw(
+        'escrow-pool',
+        '10.0000000',
+        'GRECIPIENT',
+        'user-1',
+        'issue-42',
+      );
+
+      expect(paymentRepo.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          escrowId: 'escrow-pool',
+          recipientId: 'user-1',
+          recipientAddress: 'GRECIPIENT',
+          amount: '10.0000000',
+          maintenanceIssueId: 'issue-42',
+        }),
+      );
+    });
+
     it('leaves the escrow row LOCKED after a withdraw (pool is not closed out)', async () => {
       escrowRepo.findOne.mockResolvedValue(lockedPoolEscrow());
 

src/escrow/escrow.service.ts

@@ -409,6 +409,7 @@ export class EscrowService {
     amount: string,
     recipientAddress: string,
     recipientId?: string,
+    maintenanceIssueId?: string,
   ): Promise<Payment> {
     const escrow = await this.getOrThrow(escrowId);
     this.assertLocked(escrow);
@@ -432,6 +433,7 @@ export class EscrowService {
         asset: escrow.asset,
         status: PaymentStatus.CONFIRMED,
         txHash: result.txHash,
+        maintenanceIssueId: maintenanceIssueId ?? null,
       }),
     );
   }

src/maintenance-pool/maintenance-pool.controller.ts

@@ -8,7 +8,7 @@ import {
   Req,
   UseGuards,
 } from '@nestjs/common';
-import { Request } from 'express';
+import type { Request } from 'express';
 import {
   ApiBearerAuth,
   ApiOperation,