Implement all three somzilla issues

Issue #493: Clear private keys from orchestrator API responses
- Added ResponseRedactionInterceptor to globally redact sensitive fields
  (privateKey, encryptedSecret, apiKey, token, etc.) from all API responses
- Recursively scans nested objects and arrays for sensitive patterns
- Added comprehensive unit tests (10 tests)

Issue #495: Add request id propagation across services
- Added RequestIdInterceptor to ensure every HTTP request has a unique
  x-request-id header propagated via AsyncLocalStorage/RequestContextService
- Interceptor reads from header or generates UUID, sets response header,
  and bootstraps into context for downstream services
- Added comprehensive unit tests (4 tests)

Issue #707: Idempotent settlement on duplicate tradeId
- Added Settlement Prisma model with unique tradeId constraint
- Created SettlementModule with service and controller for idempotent
  settlement processing using tradeId as idempotency key
- Service handles race conditions (P2002) with cache fallback + direct DB lookup
- Added comprehensive unit tests (9 tests)

Misc:
- Updated Wallet model with sentSettlements/receivedSettlements relations
- Registered global interceptors (RequestIdInterceptor, ResponseRedactionInterceptor)
  and SettlementModule in AppModule

Author: sommy92

prisma/schema.prisma

@@ -220,6 +220,12 @@ model Wallet {
   /// Transactions received by this wallet
   receivedTransactions Transaction[] @relation("ReceivedTransactions")
 
+  /// Settlements sent from this wallet
+  sentSettlements     Settlement[] @relation("SentSettlements")
+
+  /// Settlements received by this wallet
+  receivedSettlements Settlement[] @relation("ReceivedSettlements")
+
   @@unique([network, publicKey])
   @@index([userId, network])
   @@index([status, network])
@@ -862,3 +868,40 @@ model Transaction {
   @@index([createdAt])
   @@index([idempotencyKey])
 }
+
+/// Settlement records for idempotent trade settlement.
+/// Each settlement is uniquely identified by a client-supplied tradeId.
+model Settlement {
+  id String @id @default(uuid())
+
+  /// Client-supplied trade identifier, used for idempotency.
+  /// Duplicate submissions with the same tradeId return the existing result.
+  tradeId String @unique
+
+  /// Wallet references
+  senderWalletId   String
+  senderWallet      Wallet  @relation("SentSettlements", fields: [senderWalletId], references: [id])
+
+  receiverWalletId  String
+  receiverWallet    Wallet  @relation("ReceivedSettlements", fields: [receiverWalletId], references: [id])
+
+  /// Settlement amount (stored as string for precision)
+  amount String
+
+  /// Settlement status
+  status String @default("COMPLETED")
+
+  /// Optional metadata for audit and tracking
+  metadata Json?
+
+  /// Operational timestamps
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tradeId])
+  @@index([senderWalletId])
+  @@index([receiverWalletId])
+  @@index([senderWalletId, createdAt])
+  @@index([receiverWalletId, createdAt])
+}
+

src/app.module.ts

@@ -1,5 +1,5 @@
 import { Module } from '@nestjs/common';
-import { APP_GUARD } from '@nestjs/core';
+import { APP_GUARD, APP_INTERCEPTOR } from '@nestjs/core';
 import { AppController } from './app.controller';
 import { ConfigModule } from '@nestjs/config';
 import { EventEmitterModule } from '@nestjs/event-emitter';
@@ -26,6 +26,9 @@ import { TransactionsModule } from './transactions/transactions.module';
 import { DevelopersModule } from './developers/developers.module';
 import { ProjectsModule } from './projects/projects.module';
 import { HealthModule } from './health/health.module';
+import { RequestIdInterceptor } from './common/interceptors/request-id.interceptor';
+import { ResponseRedactionInterceptor } from './common/interceptors/response-redaction.interceptor';
+import { SettlementModule } from './settlement/settlement.module';
 
 @Module({
   imports: [
@@ -55,6 +58,7 @@ import { HealthModule } from './health/health.module';
     DevelopersModule,
     ProjectsModule,
     HealthModule,
+    SettlementModule,
   ],
   controllers: [AppController],
   providers: [
@@ -68,6 +72,15 @@ import { HealthModule } from './health/health.module';
       provide: APP_GUARD,
       useClass: RateLimitGuard,
     },
+    // Global interceptors
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: RequestIdInterceptor,
+    },
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: ResponseRedactionInterceptor,
+    },
   ],
 })
 export class AppModule {}

src/common/interceptors/request-id.interceptor.spec.ts

@@ -0,0 +1,124 @@
+import { RequestIdInterceptor } from './request-id.interceptor';
+import { Test, TestingModule } from '@nestjs/testing';
+import { ExecutionContext, CallHandler } from '@nestjs/common';
+import { of, throwError } from 'rxjs';
+import { RequestContextService } from '../request-context/request-context.service';
+
+describe('RequestIdInterceptor', () => {
+  let interceptor: RequestIdInterceptor;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [RequestIdInterceptor],
+    }).compile();
+    interceptor = module.get(RequestIdInterceptor);
+  });
+
+  function createMockContext(
+    headers: Record<string, string | string[] | undefined> = {},
+  ): ExecutionContext {
+    const responseHeaders: Record<string, string> = {};
+    return {
+      switchToHttp: () => ({
+        getRequest: () => ({
+          headers,
+        }),
+        getResponse: () => ({
+          setHeader: (key: string, value: string) => {
+            responseHeaders[key] = value;
+          },
+          getHeader: (key: string) => responseHeaders[key],
+        }),
+      }),
+      getHandler: () => ({}),
+      getClass: () => ({}),
+    } as unknown as ExecutionContext;
+  }
+
+  it('should use the incoming x-request-id header when provided', (done) => {
+    const incomingId = 'client-provided-id-123';
+    const context = createMockContext({ 'x-request-id': incomingId });
+
+    const callHandler: CallHandler = {
+      handle: () => {
+        // Verify requestId is set in the AsyncLocalStorage context
+        const storedId = RequestContextService.getCurrentRequestId();
+        expect(storedId).toBe(incomingId);
+        return of({ success: true });
+      },
+    };
+
+    interceptor.intercept(context, callHandler).subscribe({
+      next: (body: any) => {
+        // Verify the response has the header set
+        const response = context.switchToHttp().getResponse();
+        expect(response.getHeader('x-request-id')).toBe(incomingId);
+        expect(body).toEqual({ success: true });
+        done();
+      },
+    });
+  });
+
+  it('should generate a UUID request ID when the header is absent', (done) => {
+    const context = createMockContext({});
+
+    const callHandler: CallHandler = {
+      handle: () => {
+        const storedId = RequestContextService.getCurrentRequestId();
+        expect(storedId).toBeDefined();
+        expect(typeof storedId).toBe('string');
+        expect(storedId).toMatch(
+          /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+        );
+        return of({ success: true });
+      },
+    };
+
+    interceptor.intercept(context, callHandler).subscribe({
+      next: () => {
+        const response = context.switchToHttp().getResponse();
+        expect(response.getHeader('x-request-id')).toBeDefined();
+        done();
+      },
+    });
+  });
+
+  it('should still set the request ID on the response when the handler throws', (done) => {
+    const context = createMockContext({ 'x-request-id': 'error-test-id' });
+
+    const callHandler: CallHandler = {
+      handle: () => throwError(() => new Error('handler error')),
+    };
+
+    interceptor.intercept(context, callHandler).subscribe({
+      error: () => {
+        const response = context.switchToHttp().getResponse();
+        expect(response.getHeader('x-request-id')).toBe('error-test-id');
+        done();
+      },
+    });
+  });
+
+  it('should propagate to RequestContextService and be retrievable', (done) => {
+    const incomingId = 'propagation-test-id';
+    const context = createMockContext({ 'x-request-id': incomingId });
+
+    const callHandler: CallHandler = {
+      handle: () => {
+        const idFromService = RequestContextService.getCurrentRequestId();
+        expect(idFromService).toBe(incomingId);
+        return of({ data: 'ok' });
+      },
+    };
+
+    interceptor.intercept(context, callHandler).subscribe({
+      next: () => {
+        // After the handler processes, the context should still be accessible
+        // within the same async flow
+        const idAfter = RequestContextService.getCurrentRequestId();
+        expect(idAfter).toBe(incomingId);
+        done();
+      },
+    });
+  });
+});

src/common/interceptors/request-id.interceptor.ts

@@ -0,0 +1,80 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Logger,
+} from '@nestjs/common';
+import { Observable, tap } from 'rxjs';
+import { Request, Response } from 'express';
+import { randomUUID } from 'crypto';
+import { RequestContextService } from '../request-context/request-context.service';
+
+/**
+ * RequestIdInterceptor
+ *
+ * Ensures every HTTP request has a unique `x-request-id` header value and
+ * propagates it through the application via `RequestContextService` (AsyncLocalStorage).
+ *
+ * Behaviour:
+ * 1. Reads `x-request-id` from the incoming request headers if present.
+ * 2. If absent, generates a new UUID.
+ * 3. Sets `x-request-id` on the outgoing response headers.
+ * 4. Stores the request ID in `RequestContextService` so downstream services
+ *    (loggers, audit trails, outbound HTTP calls) can access it without
+ *    needing the Express request object.
+ *
+ * This interceptor is registered globally in `AppModule` and runs before
+ * controller- or method-scoped interceptors.
+ */
+@Injectable()
+export class RequestIdInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(RequestIdInterceptor.name);
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const httpContext = context.switchToHttp();
+    const request = httpContext.getRequest<Request>();
+    const response = httpContext.getResponse<Response>();
+
+    // Resolve request ID from header or generate a new one
+    const headerValue =
+      request.headers['x-request-id'] ||
+      request.headers['X-Request-Id'];
+
+    const requestId: string =
+      typeof headerValue === 'string' && headerValue.length > 0
+        ? headerValue
+        : randomUUID();
+
+    // Store on the request object for legacy middleware and logging access
+    (request as any).requestId = requestId;
+
+    // Set the response header
+    response.setHeader('x-request-id', requestId);
+
+    // Propagate into the AsyncLocalStorage context for this request's lifecycle.
+    // We use enterWith (not run) because the context must persist across
+    // the asynchronous Observable pipeline.  The middleware layer also calls
+    // run(), so the context is already active in most cases; this call
+    // ensures it's set even if the interceptor runs first or middleware
+    // hasn't yet bootstrapped it.
+    RequestContextService.bootstrapRequestId(requestId);
+
+    return next.handle().pipe(
+      tap({
+        next: () => {
+          // Ensure the header is always set even if previously missed
+          if (!response.getHeader('x-request-id')) {
+            response.setHeader('x-request-id', requestId);
+          }
+        },
+        error: () => {
+          // On error, still ensure the ID is on the response
+          if (!response.getHeader('x-request-id')) {
+            response.setHeader('x-request-id', requestId);
+          }
+        },
+      }),
+    );
+  }
+}