perf: replace UUIDv4 with UUIDv7 for ordered primary keys

src/controllers/complianceController.ts

@@ -5,6 +5,7 @@ import { prisma } from "../config/database";
 import { AppError } from "../middleware/errorHandler";
 import { logger } from "../config/logger";
 import crypto from "crypto";
+import { generateId } from '../utils/idGenerator';
 
 /**
  * GET /compliance/export
@@ -88,7 +89,7 @@ export async function deleteAccount(
       await tx.guardian.deleteMany({ where: { guardianUserId: userId } });
 
       // 2. Tombstone the User record
-      const tombstoneSuffix = crypto.randomUUID().substring(0, 8);
+      const tombstoneSuffix = generateId().substring(0, 8);
       await tx.user.update({
         where: { id: userId },
         data: {

src/controllers/kycController.ts

@@ -11,6 +11,7 @@
 import { Response, NextFunction } from "express";
 import { z } from "zod";
 import crypto from "crypto";
+import { generateId } from '../utils/idGenerator';
 import { AuthRequest } from "../middleware/auth";
 import { prisma } from "../config/database";
 import { AppError } from "../middleware/errorHandler";
@@ -101,7 +102,7 @@ export async function requestUploadUrl(
     // Generate a document ID if not provided
     const documentId =
       body.document_id ??
-      crypto.randomUUID();
+      generateId();
 
     const result = await generateUploadUrl(
       userId,

src/controllers/onrampController.ts

@@ -5,6 +5,7 @@
 import { Response, NextFunction } from "express";
 import { z } from "zod";
 import crypto from "crypto";
+import { generateId } from '../utils/idGenerator';
 import { prisma } from "../config/database";
 import { AuthRequest } from "../middleware/auth";
 import { Decimal } from "@prisma/client/runtime/library";
@@ -125,7 +126,7 @@ export async function registerOnRampSwap(
     }
     const correlationId =
       (req.headers["x-request-id"] as string | undefined) ??
-      crypto.randomUUID();
+      generateId();
     logFinancialEvent({
       event: "onramp.registered",
       status: "pending",

src/controllers/userController.ts

@@ -1,4 +1,5 @@
 import crypto from "crypto";
+import { generateId } from '../utils/idGenerator';
 import { Response, NextFunction } from "express";
 import type { Prisma } from "@prisma/client";
 import { z } from "zod";
@@ -565,7 +566,7 @@ export async function deleteMe(
       await tx.guardian.deleteMany({ where: { guardianUserId: userId } });
 
       // 2. Tombstone the User record
-      const tombstoneSuffix = crypto.randomUUID().substring(0, 8);
+      const tombstoneSuffix = generateId().substring(0, 8);
       await tx.user.update({
         where: { id: userId },
         data: {

src/controllers/webhookController.ts

@@ -14,6 +14,7 @@ function setFiatWebhookDeprecationHeaders(res: Response): void {
 }
 import { Request, Response, NextFunction } from "express";
 import crypto from "crypto";
+import { generateId } from '../utils/idGenerator';
 import { config } from "../config/env";
 import { logger, logFinancialEvent } from "../config/logger";
 import { prisma } from "../config/database";
@@ -219,7 +220,7 @@ export async function handlePaystackWebhook(
       paystackStatusMap[data.status ?? ""] ?? "pending";
     const paystackCorrelationId =
       (req.headers["x-request-id"] as string | undefined) ??
-      crypto.randomUUID();
+      generateId();
 
     logFinancialEvent({
       event: "webhook.received",
@@ -300,7 +301,7 @@ export async function handleFlutterwaveWebhook(
       flwStatusMap[data.status ?? ""] ?? "pending";
     const flwCorrelationId =
       (req.headers["x-request-id"] as string | undefined) ??
-      crypto.randomUUID();
+      generateId();
 
     logFinancialEvent({
       event: "webhook.received",

src/jobs/withdrawalProcessingJob.ts

@@ -2,7 +2,7 @@
  * Consumes WITHDRAWAL_PROCESSING queue: after BurnEvent, validate withdrawal and recipient,
  * disburse via fintech, update transaction status, optionally publish user notification.
  */
-import { randomUUID } from "crypto";
+import { generateId } from '../utils/idGenerator';
 import type { ConsumeMessage } from "amqplib";
 import {
   connectRabbitMQ,
@@ -28,7 +28,7 @@ export async function startWithdrawalProcessingConsumer(): Promise<void> {
     queue,
     async (msg: ConsumeMessage | null) => {
       if (!msg) return;
-      const correlationId = randomUUID();
+      const correlationId = generateId();
       try {
         const body = JSON.parse(msg.content.toString()) as WithdrawalPayload;
         const { transactionId, txHash } = body;

src/jobs/xlmToAcbuJob.ts

@@ -9,7 +9,7 @@ import { logger, logFinancialEvent } from "../config/logger";
 import { prisma } from "../config/database";
 import { mintFromUsdcInternal } from "../controllers/mintController";
 import { fetchXlmRateUsd } from "../services/oracle/cryptoClient";
-import { randomUUID } from "crypto";
+import { generateId } from '../utils/idGenerator';
 
 const QUEUE = QUEUES.XLM_TO_ACBU;
 const MAX_RETRIES = 5;
@@ -34,7 +34,7 @@ export async function startXlmToAcbuConsumer(): Promise<void> {
       const retries = typeof headers["x-retries"] === "number" ? headers["x-retries"] : 0;
       try {
         const body = JSON.parse(msg.content.toString()) as XlmToAcbuPayload;
-        const correlationId = randomUUID();
+        const correlationId = generateId();
         await processXlmToAcbu(body, correlationId);
         ch.ack(msg);
       } catch (e) {
@@ -61,7 +61,7 @@ export async function startXlmToAcbuConsumer(): Promise<void> {
  */
 export async function processXlmToAcbu(
   payload: XlmToAcbuPayload,
-  correlationId: string = randomUUID(),
+  correlationId: string = generateId(),
 ): Promise<void> {
   const { onRampSwapId, userId, stellarAddress, xlmAmount, usdcEquivalent } =
     payload;

src/services/auth/authService.ts

@@ -6,7 +6,7 @@
  */
 import bcrypt from "bcryptjs";
 import { totp } from "otplib";
-import { randomUUID } from "crypto";
+import { generateId } from '../../utils/idGenerator';
 import { config } from "../../config/env";
 import { prisma } from "../../config/database";
 import { generateApiKey } from "../../middleware/auth";
@@ -889,8 +889,8 @@ export interface RevokeRefreshTokenParams {
 }
 
 function generateSecureRefreshToken(): string {
-  const bytes = Buffer.from(randomUUID()).toString('base64');
-  return bytes + Buffer.from(randomUUID()).toString('base64');
+  const bytes = Buffer.from(generateId()).toString('base64');
+  return bytes + Buffer.from(generateId()).toString('base64');
 }
 
 async function hashRefreshToken(token: string): Promise<string> {
@@ -907,7 +907,7 @@ export async function issueRefreshToken(
   const { userId } = params;
   const token = generateSecureRefreshToken();
   const tokenHash = await hashRefreshToken(token);
-  const tokenFamilyId = randomUUID();
+  const tokenFamilyId = generateId();
   const expiresAt = new Date(
     Date.now() + REFRESH_TOKEN_EXPIRY_DAYS * 24 * 60 * 60 * 1000,
   );
@@ -995,7 +995,7 @@ export async function refreshAccessToken(
   // Issue a new refresh token in a NEW family
   const newToken = generateSecureRefreshToken();
   const newTokenHash = await hashRefreshToken(newToken);
-  const newTokenFamilyId = randomUUID();
+  const newTokenFamilyId = generateId();
   const newExpiresAt = new Date(
     Date.now() + REFRESH_TOKEN_EXPIRY_DAYS * 24 * 60 * 60 * 1000,
   );

src/services/bills/billsService.ts

@@ -1,5 +1,6 @@
 import { Decimal } from "@prisma/client/runtime/library";
 import { prisma } from "../../config/database";
+import { generateId } from '../../utils/idGenerator';
 import { AppError } from "../../middleware/errorHandler";
 import { logger, logFinancialEvent } from "../../config/logger";
 import { logAudit } from "../audit";
@@ -204,7 +205,7 @@ export async function payBill(
     performedBy: request.userId ?? undefined,
   });
 
-  const correlationId = crypto.randomUUID();
+  const correlationId = generateId();
 
   logFinancialEvent({
     event: "bill.initiated",
@@ -433,7 +434,7 @@ export async function reconcileBillsWebhook(event: BillsWebhookEvent): Promise<{
     userId: transaction.userId ?? transaction.id,
     accountId: transaction.userId ?? transaction.id,
     idempotencyKey: transaction.id,
-    correlationId: crypto.randomUUID(),
+    correlationId: generateId(),
     amount: Math.round((transaction.localAmount?.toNumber() ?? event.amount) * 100),
     currency: transaction.localCurrency ?? event.currency,
     provider: event.provider,
@@ -497,7 +498,7 @@ export async function refundBillPayment(
     userId: transaction.userId ?? transaction.id,
     accountId: transaction.userId ?? transaction.id,
     idempotencyKey: transaction.id,
-    correlationId: crypto.randomUUID(),
+    correlationId: generateId(),
     amount: Math.round(localAmount * 100),
     currency,
     provider: refundResponse.provider,

src/services/bills/simulatedBillsPartner.ts

@@ -7,6 +7,7 @@ import type {
   PartnerBillRefundRequest,
   PartnerBillRefundResponse,
 } from "./types";
+import { generateId } from '../../utils/idGenerator';
 
 const SIMULATED_BILLERS: BillsCatalogBiller[] = [
   {
@@ -107,7 +108,7 @@ export class SimulatedBillsPartner implements BillsPartnerAdapter {
   async payBill(
     request: PartnerBillPaymentRequest,
   ): Promise<PartnerBillPaymentResponse> {
-    const providerReference = `bill_${crypto.randomUUID()}`;
+    const providerReference = `bill_${generateId()}`;
     return {
       provider: this.providerId,
       providerReference,

src/services/salary/salaryService.ts

@@ -6,6 +6,7 @@ import { logger, logFinancialEvent } from "../../config/logger";
 import { CreateSalaryBatchParams, CreateSalaryBatchResult } from "./types";
 import { AppError } from "../../middleware/errorHandler";
 import crypto from "crypto";
+import { generateId } from '../../utils/idGenerator';
 
 /**
  * Creates a new salary batch with items. Supports idempotency via idempotencyKey.
@@ -74,7 +75,7 @@ export async function createSalaryBatch(
     organizationId,
   });
 
-  const salaryCorrelationId = idempotencyKey ?? crypto.randomUUID();
+  const salaryCorrelationId = idempotencyKey ?? generateId();
   logFinancialEvent({
     event: "salary.batch.initiated",
     status: "pending",
@@ -205,7 +206,7 @@ export async function processSalaryBatch(batchId: string): Promise<void> {
     idempotencyKey: batch.idempotencyKey ?? batchId,
     amount: Math.round(batch.totalAmount.toNumber() * 100),
     currency: batch.currency,
-    correlationId: crypto.randomUUID(),
+    correlationId: generateId(),
   });
 
   logger.info("Salary batch processing finished", {

src/services/transfer/transferService.ts

@@ -14,6 +14,7 @@ import { stellarClient } from "../stellar/client";
 import { getBaseFee } from "../stellar/feeManager";
 import { resolveRecipientToStellarAddress } from "../recipient/recipientResolver";
 import crypto from "crypto";
+import { generateId } from '../../utils/idGenerator';
 
 import { logger, logFinancialEvent } from "../../config/logger";
 import type {
@@ -154,7 +155,7 @@ export async function createTransfer(
     throw createError;
   }
 
-  const correlationId = options?.correlationId ?? crypto.randomUUID();
+  const correlationId = options?.correlationId ?? generateId();
   // Avoid float arithmetic: parse integer and fractional parts separately to
   // prevent precision loss when amount has up to 7 decimal places.
   const [wholePart, fracPart = ""] = amount.split(".");

src/utils/idGenerator.ts

@@ -0,0 +1,38 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * Generates a UUIDv7 (timestamp-ordered) string.
+ * Timestamp-ordered UUIDs avoid B-tree index fragmentation in PostgreSQL
+ * compared to random UUIDv4, improving insert performance and index locality.
+ * A monotonic counter ensures strict ordering within the same millisecond.
+ */
+
+let lastMs = -1n;
+let seq = 0;
+
+export function generateId(): string {
+  let ms = BigInt(Date.now());
+  if (ms === lastMs) {
+    seq = (seq + 1) & 0xfff;
+    if (seq === 0) ms = ++lastMs; // counter overflow: advance clock
+  } else {
+    seq = 0;
+    lastMs = ms;
+  }
+
+  const rand = randomBytes(8);
+  const timeLow = Number(ms & BigInt(0xffffffff));
+  const timeMid = Number((ms >> BigInt(32)) & BigInt(0xffff));
+  const ver = 0x7000 | seq;                          // version 7 | 12-bit seq
+  const varRand = 0x80 | (rand[0] & 0x3f);           // variant 10xx | random
+
+  const hex = (n: number, pad: number) => n.toString(16).padStart(pad, '0');
+
+  return [
+    hex(timeLow, 8),
+    hex(timeMid, 4),
+    hex(ver, 4),
+    hex(varRand, 2) + hex(rand[1], 2),
+    rand.slice(2).reduce((s, b) => s + hex(b, 2), ''),
+  ].join('-');
+}