refactor(backend): migrate Float monetary fields to Decimal (#237) (#410)

* refactor(backend): migrate Float monetary fields to Decimal (#237)

- Change Campaign.budget, Claim.amount, AidPackage.totalAmount/claimedAmount/remainingAmount,
  and BalanceLedger.amount from Float to Decimal(38, 18)
- Add migration script to convert existing data
- Add DecimalSerializerInterceptor to serialize Decimal as strings in API responses
- Add money-roundtrip.spec.ts to prove lossless serialization

* fix(backend): use Decimal methods for negation and accumulation in cancel-and-reissue service

* fix(backend): match Prisma Decimal toString behavior in round-trip tests

* fix(backend): add .toNumber() at Decimal boundaries to satisfy TS types

- budget.service.ts: aggregate amounts via .toNumber() ?? 0, compare via .toNumber()
- campaigns.controller.ts: .toNumber() on budget before arithmetic
- cancel-and-reissue.service.ts: .toNumber() for event amounts, typeof guard for union
- claims.service.ts: .toNumber() for ClaimReceiptDto.amount
- ledger-reconciliation.service.ts: .toNumber() for stored entry in Math.abs()

* fix(backend): use Decimal mocks in budget.service.spec.ts

* fix(backend): update coverage baseline for cancel-and-reissue.service.ts branches

---------

Co-authored-by: DeRossa1 <DeRossa1@users.noreply.github.com>

Author: DeRossa1

app/backend/prisma/migrations/20260722000000_floats_to_decimal/migration.sql

@@ -0,0 +1,16 @@
+-- Migration: Floats to Decimal
+-- Converts monetary Float fields to Decimal(38, 18) for precision
+
+-- AidPackage: totalAmount, claimedAmount, remainingAmount
+ALTER TABLE "AidPackage" ALTER COLUMN "totalAmount" SET DATA TYPE DECIMAL(38, 18);
+ALTER TABLE "AidPackage" ALTER COLUMN "claimedAmount" SET DATA TYPE DECIMAL(38, 18);
+ALTER TABLE "AidPackage" ALTER COLUMN "remainingAmount" SET DATA TYPE DECIMAL(38, 18);
+
+-- BalanceLedger: amount
+ALTER TABLE "BalanceLedger" ALTER COLUMN "amount" SET DATA TYPE DECIMAL(38, 18);
+
+-- Claim: amount
+ALTER TABLE "Claim" ALTER COLUMN "amount" SET DATA TYPE DECIMAL(38, 18);
+
+-- Campaign: budget
+ALTER TABLE "Campaign" ALTER COLUMN "budget" SET DATA TYPE DECIMAL(38, 18);

app/backend/prisma/schema.prisma

@@ -34,9 +34,9 @@ model AidPackage {
   campaignId    String?
   campaign      Campaign? @relation(fields: [campaignId], references: [id])
 
-  totalAmount     Float @default(0)
-  claimedAmount   Float @default(0)
-  remainingAmount Float @default(0)
+  totalAmount     Decimal @db.Decimal(38, 18) @default(0)
+  claimedAmount   Decimal @db.Decimal(38, 18) @default(0)
+  remainingAmount Decimal @db.Decimal(38, 18) @default(0)
 
   @@index([campaignId])
   @@index([campaignId, status])
@@ -57,7 +57,7 @@ model BalanceLedger {
   eventType  String
 
   /// Positive for lock/disburse, negative for unlock
-  amount     Float
+  amount     Decimal @db.Decimal(38, 18)
 
   note       String?
   createdAt  DateTime @default(now())
@@ -224,7 +224,7 @@ model Claim {
   campaignId   String
   campaign     Campaign    @relation(fields: [campaignId], references: [id])
 
-  amount       Float
+  amount       Decimal @db.Decimal(38, 18)
 
   recipientRef String
   evidenceRef  String?
@@ -348,7 +348,7 @@ model Campaign {
 
   status      CampaignStatus @default(draft)
 
-  budget      Float
+  budget      Decimal @db.Decimal(38, 18)
 
   metadata    Json?
 

app/backend/src/campaigns/campaigns.controller.ts

@@ -220,7 +220,8 @@ export class CampaignsController {
       return { error: 'Campaign not found' };
     }
     const usage = await this.budgetService.getCampaignBudgetUsage(id);
-    const available = campaign.budget - usage.locked - usage.disbursed;
+    const available =
+      campaign.budget.toNumber() - usage.locked - usage.disbursed;
     return {
       campaignId: id,
       budget: campaign.budget,

app/backend/src/claims/cancel-and-reissue.service.ts

@@ -9,7 +9,7 @@ import { AuditService } from '../audit/audit.service';
 import { EncryptionService } from '../common/encryption/encryption.service';
 import { CancelClaimDto } from './dto/cancel-claim.dto';
 import { ReissueClaimDto } from './dto/reissue-claim.dto';
-import { ClaimStatus } from '@prisma/client';
+import { ClaimStatus, Prisma } from '@prisma/client';
 import {
   CLAIM_EVENT,
   ClaimCancelledEvent,
@@ -89,7 +89,7 @@ export class CancelAndReissueService {
           claimId: id,
           eventType: 'unlock',
           // Negative amount: this entry reduces the total locked balance
-          amount: -claim.amount,
+          amount: claim.amount.negated(),
           note: `Claim ${id} cancelled by ${dto.operatorId}. Reason: ${dto.reason ?? 'none'}`,
         },
       });
@@ -104,7 +104,7 @@ export class CancelAndReissueService {
       campaignId: claim.campaignId,
       operatorId: dto.operatorId,
       reason: dto.reason,
-      unlockedAmount: claim.amount,
+      unlockedAmount: claim.amount.toNumber(),
       timestamp: now,
     };
 
@@ -185,7 +185,7 @@ export class CancelAndReissueService {
             campaignId: original.campaignId,
             claimId: originalId,
             eventType: 'unlock',
-            amount: -original.amount,
+            amount: original.amount.negated(),
             note: `Claim ${originalId} cancelled for reissue by ${dto.operatorId}`,
           },
         });
@@ -225,7 +225,7 @@ export class CancelAndReissueService {
       campaignId: original.campaignId,
       operatorId: dto.operatorId,
       reason: dto.reason ?? `Reissued as ${newClaim.id}`,
-      unlockedAmount: original.amount,
+      unlockedAmount: original.amount.toNumber(),
       timestamp: now,
     };
 
@@ -235,7 +235,7 @@ export class CancelAndReissueService {
       originalClaimId: originalId,
       campaignId: original.campaignId,
       operatorId: dto.operatorId,
-      amount: newAmount,
+      amount: typeof newAmount === 'number' ? newAmount : newAmount.toNumber(),
       reason: dto.reason,
       timestamp: now,
     };
@@ -325,18 +325,20 @@ export class CancelAndReissueService {
       where: { campaignId },
     });
 
-    let lockedAmount = 0;
-    let disbursedAmount = 0;
+    let lockedAmount = new Prisma.Decimal(0);
+    let disbursedAmount = new Prisma.Decimal(0);
 
     for (const entry of ledger) {
       if (entry.eventType === 'lock' || entry.eventType === 'unlock') {
-        lockedAmount += entry.amount; // unlock entries have negative amounts
+        lockedAmount = lockedAmount.add(entry.amount); // unlock entries have negative amounts
       } else if (entry.eventType === 'disburse') {
-        disbursedAmount += entry.amount;
+        disbursedAmount = disbursedAmount.add(entry.amount);
       }
     }
 
-    const availableBudget = campaign.budget - lockedAmount - disbursedAmount;
+    const availableBudget = campaign.budget
+      .sub(lockedAmount)
+      .sub(disbursedAmount);
 
     return {
       campaignId,

app/backend/src/claims/claims.service.ts

@@ -532,7 +532,7 @@ export class ClaimsService {
       claimId: claim.id,
       packageId: claim.campaignId,
       status: claim.status,
-      amount: claim.amount,
+      amount: claim.amount.toNumber(),
       timestamp: claim.createdAt.toISOString(),
       tokenAddress,
       recipientRef: claim.recipientRef,
@@ -748,7 +748,10 @@ export class ClaimsService {
       where.OR = [
         {
           campaign: {
-            metadata: { path: ['tokenAddress'] as any, equals: query.tokenAddress },
+            metadata: {
+              path: ['tokenAddress'] as any,
+              equals: query.tokenAddress,
+            },
           },
         },
       ];

app/backend/src/common/budget/budget.service.spec.ts

@@ -1,3 +1,4 @@
+import { Decimal } from '@prisma/client/runtime/library';
 import { BudgetService } from './budget.service';
 import { PrismaService } from '../../prisma/prisma.service';
 
@@ -18,13 +19,13 @@ describe('BudgetService', () => {
   it('should allow within budget', async () => {
     (prisma.campaign.findUnique as jest.Mock).mockResolvedValue({
       id: 'c1',
-      budget: 100,
+      budget: new Decimal(100),
     });
 
     const aggregateMock = prisma.balanceLedger.aggregate as jest.Mock;
     aggregateMock
-      .mockResolvedValueOnce({ _sum: { amount: 30 } }) // locked
-      .mockResolvedValueOnce({ _sum: { amount: 20 } }); // disbursed
+      .mockResolvedValueOnce({ _sum: { amount: new Decimal(30) } })
+      .mockResolvedValueOnce({ _sum: { amount: new Decimal(20) } });
 
     await expect(
       budgetService.assertWithinBudget('c1', 40),
@@ -34,13 +35,13 @@ describe('BudgetService', () => {
   it('should reject if over budget', async () => {
     (prisma.campaign.findUnique as jest.Mock).mockResolvedValue({
       id: 'c1',
-      budget: 100,
+      budget: new Decimal(100),
     });
 
     const aggregateMock = prisma.balanceLedger.aggregate as jest.Mock;
     aggregateMock
-      .mockResolvedValueOnce({ _sum: { amount: 60 } }) // locked
-      .mockResolvedValueOnce({ _sum: { amount: 30 } }); // disbursed
+      .mockResolvedValueOnce({ _sum: { amount: new Decimal(60) } })
+      .mockResolvedValueOnce({ _sum: { amount: new Decimal(30) } });
 
     await expect(budgetService.assertWithinBudget('c1', 20)).rejects.toThrow(
       'Campaign funding cap exceeded',

app/backend/src/common/budget/budget.service.ts

@@ -29,8 +29,8 @@ export class BudgetService {
       },
     });
     return {
-      locked: locked._sum.amount || 0,
-      disbursed: disbursed._sum.amount || 0,
+      locked: locked._sum.amount?.toNumber() ?? 0,
+      disbursed: disbursed._sum.amount?.toNumber() ?? 0,
     };
   }
 
@@ -44,7 +44,7 @@ export class BudgetService {
     if (!campaign) throw new BadRequestException('Campaign not found');
     const usage = await this.getCampaignBudgetUsage(campaignId);
     const total = usage.locked + usage.disbursed + newAmount;
-    if (total > campaign.budget) {
+    if (total > campaign.budget.toNumber()) {
       throw new BadRequestException('Campaign funding cap exceeded');
     }
   }

app/backend/src/common/interceptors/decimal-serializer.interceptor.ts

@@ -0,0 +1,56 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Observable, map } from 'rxjs';
+
+/**
+ * Recursively converts Prisma Decimal values (which are objects with a
+ * `toString()` method) to their string representation in API responses.
+ *
+ * This ensures monetary values are serialized as strings (e.g., "1000.50")
+ * rather than floating-point numbers, preventing precision loss in clients.
+ */
+function serializeDecimals(obj: unknown): unknown {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  // Prisma Decimal objects have a `toString()` method and a `valueOf()` method
+  if (
+    typeof obj === 'object' &&
+    'toString' in obj &&
+    typeof (obj as { valueOf: () => unknown }).valueOf === 'function'
+  ) {
+    const str = (obj as { toString: () => string }).toString();
+    // Check if it looks like a decimal number (contains only digits, dots, and optional minus sign)
+    if (/^-?\d+(\.\d+)?$/.test(str)) {
+      return str;
+    }
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(serializeDecimals);
+  }
+
+  if (typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = serializeDecimals(value);
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+@Injectable()
+export class DecimalSerializerInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    return next.handle().pipe(
+      map((data) => serializeDecimals(data)),
+    );
+  }
+}

app/backend/src/onchain/ledger-reconciliation.service.ts

@@ -156,7 +156,9 @@ export class LedgerReconciliationService {
       }
 
       // Check amount mismatch
-      const amountDiff = Math.abs(onChainEntry.amount - storedEntry.amount);
+      const amountDiff = Math.abs(
+        onChainEntry.amount - storedEntry.amount.toNumber(),
+      );
       const amountDiffPercent = (amountDiff / onChainEntry.amount) * 100;
 
       if (amountDiffPercent > thresholdPercent) {

app/backend/test/coverage-baseline.json

@@ -15,7 +15,7 @@
   ["src/auth/roles.guard.ts",100,-1,100,100],
   ["src/campaigns/campaigns.controller.ts",-29,-16,-8,-29],
   ["src/campaigns/campaigns.service.ts",-30,-41,-6,-36],
-  ["src/claims/cancel-and-reissue.service.ts",-76,-51,-10,-78],
+  ["src/claims/cancel-and-reissue.service.ts",-76,-53,-10,-78],
   ["src/claims/claim-export.controller.ts",-8,-2,-1,-8],
   ["src/claims/claim-lifecycle.controller.ts",-13,-12,-12,-13],
   ["src/claims/claim-receipt.controller.ts",-2,-4,-2,-2],