feat(monitoring): implement multi-signature monitoring and alert service

package.json

@@ -54,6 +54,7 @@
   "dependencies": {
     "@nestjs/common": "^11.1.27",
     "@nestjs/core": "^11.1.27",
+    "@nestjs/event-emitter": "^3.1.0",
     "@nestjs/jwt": "^11.0.2",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/platform-express": "^11.1.28",

src/modules/monitoring/multisig/multisig-monitoring.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { MultisigMonitoringService } from './multisig-monitoring.service';
+
+@Module({
+  imports: [EventEmitterModule.forRoot()],
+  providers: [MultisigMonitoringService],
+  exports: [MultisigMonitoringService],
+})
+export class MultisigMonitoringModule {}

src/modules/monitoring/multisig/multisig-monitoring.service.spec.ts

@@ -0,0 +1,67 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { MultisigMonitoringService } from './multisig-monitoring.service';
+
+describe('MultisigMonitoringService', () => {
+  let service: MultisigMonitoringService;
+  let eventEmitter: EventEmitter2;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        MultisigMonitoringService,
+        {
+          provide: EventEmitter2,
+          useValue: {
+            emit: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<MultisigMonitoringService>(MultisigMonitoringService);
+    eventEmitter = module.get<EventEmitter2>(EventEmitter2);
+  });
+
+  it('should register and track multisig wallet configuration', () => {
+    service.registerWallet({
+      address: '0x1234',
+      network: 'ethereum',
+      threshold: 2,
+      signers: ['0xA', '0xB'],
+    });
+
+    const config = service.getWalletConfig('0x1234');
+    expect(config).toBeDefined();
+    expect(config?.threshold).toBe(2);
+  });
+
+  it('should detect threshold changes and trigger a CRITICAL alert', async () => {
+    service.registerWallet({
+      address: '0x1234',
+      network: 'ethereum',
+      threshold: 2,
+      signers: ['0xA', '0xB'],
+    });
+
+    await service.processActivity({
+      multisigAddress: '0x1234',
+      network: 'ethereum',
+      type: 'THRESHOLD_CHANGED',
+      txHash: '0xabc',
+      oldThreshold: 2,
+      newThreshold: 1,
+    });
+
+    expect(eventEmitter.emit).toHaveBeenCalledWith(
+      'multisig.alert',
+      expect.objectContaining({
+        severity: 'CRITICAL',
+        title: '⚠️ Multisig Threshold Changed',
+      }),
+    );
+
+    const updatedConfig = service.getWalletConfig('0x1234');
+    expect(updatedConfig?.threshold).toBe(1);
+  });
+});

src/modules/monitoring/multisig/multisig-monitoring.service.ts

@@ -0,0 +1,137 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { MultisigAccountConfig, MultisigEvent, MultisigAlert } from './types/multisig.types';
+
+@Injectable()
+export class MultisigMonitoringService {
+  private readonly logger = new Logger(MultisigMonitoringService.name);
+
+  // In-memory state tracking for threshold and signers
+  private trackedWallets: Map<string, MultisigAccountConfig> = new Map();
+
+  constructor(private readonly eventEmitter: EventEmitter2) {}
+
+  /**
+   * Register a multisig wallet for monitoring
+   */
+  registerWallet(config: MultisigAccountConfig): void {
+    this.trackedWallets.set(config.address.toLowerCase(), { ...config });
+    this.logger.log(
+      `[MultisigMonitor] Registered wallet ${config.address} (Threshold: ${config.threshold}, Signers: ${config.signers.length})`,
+    );
+  }
+
+  /**
+   * Process raw multisig activity event from blockchain listener
+   */
+  async processActivity(event: Omit<MultisigEvent, 'id' | 'timestamp'>): Promise<void> {
+    const fullEvent: MultisigEvent = {
+      ...event,
+      id: `evt_${Date.now()}_${Math.random().toString(36).substr(2, 5)}`,
+      timestamp: new Date(),
+    };
+
+    const walletKey = fullEvent.multisigAddress.toLowerCase();
+    const currentState = this.trackedWallets.get(walletKey);
+
+    this.logger.log(
+      `[MultisigMonitor] Event detected on ${fullEvent.multisigAddress}: ${fullEvent.type}`,
+    );
+
+    // Track state modifications
+    if (currentState) {
+      this.updateWalletState(currentState, fullEvent);
+    }
+
+    // Evaluate security alerts
+    const alert = this.detectSecurityAlert(fullEvent, currentState);
+    if (alert) {
+      this.dispatchAlert(alert);
+    }
+
+    // Emit event for downstream consumers
+    this.eventEmitter.emit('multisig.activity', fullEvent);
+  }
+
+  private updateWalletState(state: MultisigAccountConfig, event: MultisigEvent): void {
+    switch (event.type) {
+      case 'THRESHOLD_CHANGED':
+        if (event.newThreshold !== undefined) {
+          state.threshold = event.newThreshold;
+        }
+        break;
+      case 'SIGNER_ADDED':
+        if (event.addedSigner && !state.signers.includes(event.addedSigner)) {
+          state.signers.push(event.addedSigner);
+        }
+        break;
+      case 'SIGNER_REMOVED':
+        if (event.removedSigner) {
+          state.signers = state.signers.filter(s => s !== event.removedSigner);
+        }
+        break;
+    }
+  }
+
+  private detectSecurityAlert(
+    event: MultisigEvent,
+    state?: MultisigAccountConfig,
+  ): MultisigAlert | null {
+    let severity: 'INFO' | 'WARNING' | 'CRITICAL' | null = null;
+    let title = '';
+    let message = '';
+
+    switch (event.type) {
+      case 'THRESHOLD_CHANGED':
+        severity = 'CRITICAL';
+        title = '⚠️ Multisig Threshold Changed';
+        message = `Threshold updated from ${event.oldThreshold ?? state?.threshold} to ${event.newThreshold} on ${event.multisigAddress} (Tx: ${event.txHash})`;
+        break;
+
+      case 'SIGNER_ADDED':
+        severity = 'WARNING';
+        title = '👤 New Signer Added';
+        message = `Signer ${event.addedSigner} was added to multisig ${event.multisigAddress} (Tx: ${event.txHash})`;
+        break;
+
+      case 'SIGNER_REMOVED':
+        severity = 'WARNING';
+        title = '🗑️ Signer Removed';
+        message = `Signer ${event.removedSigner} was removed from multisig ${event.multisigAddress} (Tx: ${event.txHash})`;
+        break;
+
+      case 'APPROVAL_SUBMITTED':
+        severity = 'INFO';
+        title = '✍️ Approval Submitted';
+        message = `Signer ${event.signer} approved tx ${event.txHash} (${event.currentApprovals}/${event.requiredApprovals} approvals)`;
+        break;
+
+      case 'EXECUTION_FAILED':
+        severity = 'CRITICAL';
+        title = '🚨 Transaction Execution Failed';
+        message = `Multisig transaction execution failed on ${event.multisigAddress} (Tx: ${event.txHash})`;
+        break;
+    }
+
+    if (!severity) return null;
+
+    return {
+      id: `alt_${Date.now()}`,
+      severity,
+      multisigAddress: event.multisigAddress,
+      title,
+      message,
+      event,
+      timestamp: new Date(),
+    };
+  }
+
+  private dispatchAlert(alert: MultisigAlert): void {
+    this.logger.warn(`[ALERT][${alert.severity}] ${alert.title}: ${alert.message}`);
+    this.eventEmitter.emit('multisig.alert', alert);
+  }
+
+  getWalletConfig(address: string): MultisigAccountConfig | undefined {
+    return this.trackedWallets.get(address.toLowerCase());
+  }
+}

src/modules/monitoring/multisig/types/multisig.types.ts

@@ -0,0 +1,40 @@
+export type MultisigEventType =
+  | 'SIGNER_ADDED'
+  | 'SIGNER_REMOVED'
+  | 'THRESHOLD_CHANGED'
+  | 'APPROVAL_SUBMITTED'
+  | 'EXECUTION_SUCCESS'
+  | 'EXECUTION_FAILED';
+
+export interface MultisigAccountConfig {
+  address: string;
+  network: string;
+  threshold: number;
+  signers: string[];
+}
+
+export interface MultisigEvent {
+  id: string;
+  multisigAddress: string;
+  network: string;
+  type: MultisigEventType;
+  txHash: string;
+  signer?: string;
+  newThreshold?: number;
+  oldThreshold?: number;
+  addedSigner?: string;
+  removedSigner?: string;
+  currentApprovals?: number;
+  requiredApprovals?: number;
+  timestamp: Date;
+}
+
+export interface MultisigAlert {
+  id: string;
+  severity: 'INFO' | 'WARNING' | 'CRITICAL';
+  multisigAddress: string;
+  title: string;
+  message: string;
+  event: MultisigEvent;
+  timestamp: Date;
+}