How to Create Stablecoin Bridge Monitor: Cross-Chain Transfer Tracking That Actually Works

// I learned to abstract chain configs after hardcoding everything initially
class ChainManager {
  constructor() {
    this.chains = {
      ethereum: {
        rpc: process.env.ETHEREUM_RPC,
        bridgeContract: '0x40ec5B33f54e0E8A33A975908C5BA1c14e5BbbDf',
        stablecoinContract: '0xA0b86a33E6417C94c5be1b2B5F92BFB0d40CfE6F',
        confirmations: 12, // I use 12 for Ethereum mainnet
        blockTime: 13000
      },
      polygon: {
        rpc: process.env.POLYGON_RPC,
        bridgeContract: '0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063',
        stablecoinContract: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
        confirmations: 20, // Polygon can reorganize more frequently
        blockTime: 2000
      }
    };
    
    this.providers = {};
    this.contracts = {};
    this.initializeConnections();
  }

  async initializeConnections() {
    for (const [chainName, config] of Object.entries(this.chains)) {
      try {
        this.providers[chainName] = new ethers.JsonRpcProvider(config.rpc);
        
        // Test connection immediately - don't wait for first transaction
        await this.providers[chainName].getBlockNumber();
        
        this.contracts[chainName] = {
          bridge: new ethers.Contract(config.bridgeContract, BRIDGE_ABI, this.providers[chainName]),
          stablecoin: new ethers.Contract(config.stablecoinContract, ERC20_ABI, this.providers[chainName])
        };
        
        console.log(`✓ Connected to ${chainName}`);
      } catch (error) {
        // This saved me from silent failures during RPC outages
        console.error(`Failed to connect to ${chainName}:`, error);
        throw new Error(`Critical: Cannot initialize ${chainName} connection`);
      }
    }
  }
}

class BridgeEventListener {
  constructor(chainManager, eventProcessor) {
    this.chainManager = chainManager;
    this.eventProcessor = eventProcessor;
    this.lastProcessedBlock = {};
    this.missedEventCount = {};
    
    // I track these metrics after missing critical events during RPC issues
    this.healthMetrics = {
      eventsProcessed: 0,
      missedBlocks: 0,
      reconnections: 0
    };
  }

  async startListening() {
    for (const chainName of Object.keys(this.chainManager.chains)) {
      await this.initializeChainListener(chainName);
    }
  }

  async initializeChainListener(chainName) {
    const config = this.chainManager.chains[chainName];
    const contract = this.chainManager.contracts[chainName].bridge;
    
    // Get starting block - critical for not missing events during restarts
    const currentBlock = await this.chainManager.providers[chainName].getBlockNumber();
    this.lastProcessedBlock[chainName] = currentBlock - config.confirmations;
    
    console.log(`Starting ${chainName} listener from block ${this.lastProcessedBlock[chainName]}`);
    
    // Listen for deposit events (source chain)
    contract.on('TokensLocked', async (user, amount, destinationChain, nonce, event) => {
      try {
        await this.processDepositEvent(chainName, {
          user,
          amount: amount.toString(),
          destinationChain,
          nonce: nonce.toString(),
          txHash: event.transactionHash,
          blockNumber: event.blockNumber,
          timestamp: Date.now()
        });
      } catch (error) {
        console.error(`Error processing deposit event on ${chainName}:`, error);
        // Don't let one failed event kill the entire listener
      }
    });

    // Listen for withdrawal events (destination chain)
    contract.on('TokensUnlocked', async (user, amount, sourceChain, nonce, event) => {
      try {
        await this.processWithdrawalEvent(chainName, {
          user,
          amount: amount.toString(),
          sourceChain,
          nonce: nonce.toString(),
          txHash: event.transactionHash,
          blockNumber: event.blockNumber,
          timestamp: Date.now()
        });
      } catch (error) {
        console.error(`Error processing withdrawal event on ${chainName}:`, error);
      }
    });

    // Handle connection failures gracefully
    this.chainManager.providers[chainName].on('error', (error) => {
      console.error(`${chainName} provider error:`, error);
      this.reconnectChain(chainName);
    });

    // Monitor for missed blocks every 30 seconds
    setInterval(() => this.checkForMissedEvents(chainName), 30000);
  }

  async processDepositEvent(chainName, eventData) {
    console.log(`Deposit detected on ${chainName}:`, eventData);
    
    // Store in database with pending status
    await this.eventProcessor.recordDepositEvent({
      ...eventData,
      sourceChain: chainName,
      status: 'pending',
      createdAt: new Date()
    });

    // Start watching for corresponding withdrawal
    await this.eventProcessor.startWithdrawalWatch(eventData);
    
    this.healthMetrics.eventsProcessed++;
  }

  async processWithdrawalEvent(chainName, eventData) {
    console.log(`Withdrawal detected on ${chainName}:`, eventData);
    
    // Try to match with pending deposit
    const matchedDeposit = await this.eventProcessor.matchWithdrawal({
      ...eventData,
      destinationChain: chainName
    });

    if (matchedDeposit) {
      console.log(`✓ Bridge transaction completed: ${matchedDeposit.nonce}`);
      await this.eventProcessor.markTransactionComplete(matchedDeposit.id);
    } else {
      // Unmatched withdrawal - could indicate issue
      console.warn(`Unmatched withdrawal on ${chainName}:`, eventData);
      await this.eventProcessor.flagUnmatchedWithdrawal(eventData);
    }
    
    this.healthMetrics.eventsProcessed++;
  }

  async checkForMissedEvents(chainName) {
    try {
      const currentBlock = await this.chainManager.providers[chainName].getBlockNumber();
      const expectedBlock = this.lastProcessedBlock[chainName] + 1;
      
      if (currentBlock > expectedBlock) {
        const missedBlocks = currentBlock - expectedBlock;
        if (missedBlocks > 0) {
          console.warn(`Missed ${missedBlocks} blocks on ${chainName}, catching up...`);
          await this.catchUpMissedEvents(chainName, expectedBlock, currentBlock);
          this.healthMetrics.missedBlocks += missedBlocks;
        }
      }
    } catch (error) {
      console.error(`Failed to check for missed events on ${chainName}:`, error);
    }
  }
}

class BridgeTransactionProcessor {
  constructor(database, alertSystem) {
    this.db = database;
    this.alerts = alertSystem;
    
    // Transaction states I track
    this.states = {
      INITIATED: 'initiated',
      CONFIRMED: 'confirmed', 
      PROCESSING: 'processing',
      COMPLETED: 'completed',
      FAILED: 'failed',
      STUCK: 'stuck'
    };

    // Timeout thresholds learned from production data
    this.timeouts = {
      ethereum_to_polygon: 15 * 60 * 1000, // 15 minutes
      polygon_to_ethereum: 45 * 60 * 1000, // 45 minutes  
      default: 30 * 60 * 1000 // 30 minutes
    };
  }

  async recordDepositEvent(eventData) {
    const transaction = {
      id: `${eventData.sourceChain}_${eventData.nonce}`,
      nonce: eventData.nonce,
      sourceChain: eventData.sourceChain,
      destinationChain: eventData.destinationChain,
      user: eventData.user,
      amount: eventData.amount,
      sourceTxHash: eventData.txHash,
      sourceBlockNumber: eventData.blockNumber,
      status: this.states.INITIATED,
      createdAt: eventData.timestamp,
      updatedAt: eventData.timestamp,
      timeoutAt: eventData.timestamp + this.getTimeout(eventData.sourceChain, eventData.destinationChain)
    };

    await this.db.insertTransaction(transaction);
    console.log(`Recorded deposit: ${transaction.id}`);
    
    return transaction;
  }

  async startWithdrawalWatch(eventData) {
    // Set up timeout monitoring for this specific transaction
    const timeoutMs = this.getTimeout(eventData.sourceChain, eventData.destinationChain);
    
    setTimeout(async () => {
      await this.checkTransactionTimeout(eventData.nonce, eventData.sourceChain);
    }, timeoutMs);
  }

  async matchWithdrawal(withdrawalData) {
    const pendingTransaction = await this.db.findPendingTransaction({
      nonce: withdrawalData.nonce,
      sourceChain: withdrawalData.sourceChain,
      destinationChain: withdrawalData.destinationChain
    });

    if (!pendingTransaction) {
      return null;
    }

    // Validate amounts match (accounting for potential fees)
    const amountDiff = Math.abs(
      parseFloat(pendingTransaction.amount) - parseFloat(withdrawalData.amount)
    );
    const tolerance = parseFloat(pendingTransaction.amount) * 0.001; // 0.1% tolerance

    if (amountDiff > tolerance) {
      console.warn(`Amount mismatch for transaction ${pendingTransaction.id}: expected ${pendingTransaction.amount}, got ${withdrawalData.amount}`);
      await this.alerts.sendAlert('AMOUNT_MISMATCH', {
        transactionId: pendingTransaction.id,
        expected: pendingTransaction.amount,
        actual: withdrawalData.amount
      });
    }

    // Update transaction with withdrawal details
    await this.db.updateTransaction(pendingTransaction.id, {
      destinationTxHash: withdrawalData.txHash,
      destinationBlockNumber: withdrawalData.blockNumber,
      status: this.states.COMPLETED,
      completedAt: withdrawalData.timestamp,
      updatedAt: Date.now(),
      duration: withdrawalData.timestamp - pendingTransaction.createdAt
    });

    return pendingTransaction;
  }

  async checkTransactionTimeout(nonce, sourceChain) {
    const transaction = await this.db.findTransaction({ nonce, sourceChain });
    
    if (!transaction || transaction.status === this.states.COMPLETED) {
      return; // Transaction completed or doesn't exist
    }

    const now = Date.now();
    if (now > transaction.timeoutAt && transaction.status !== this.states.FAILED) {
      console.error(`Transaction timeout: ${transaction.id}`);
      
      await this.db.updateTransaction(transaction.id, {
        status: this.states.STUCK,
        updatedAt: now
      });

      // This alert saved us multiple times
      await this.alerts.sendCriticalAlert('TRANSACTION_STUCK', {
        transactionId: transaction.id,
        user: transaction.user,
        amount: transaction.amount,
        duration: now - transaction.createdAt,
        sourceChain: transaction.sourceChain,
        destinationChain: transaction.destinationChain
      });

      // Attempt automatic recovery
      await this.attemptRecovery(transaction);
    }
  }
}

class BridgeRecoveryEngine {
  constructor(chainManager, transactionProcessor, alertSystem) {
    this.chainManager = chainManager;
    this.processor = transactionProcessor;
    this.alerts = alertSystem;
    this.recoveryAttempts = new Map();
  }

  async attemptRecovery(stuckTransaction) {
    const attemptKey = stuckTransaction.id;
    const attempts = this.recoveryAttempts.get(attemptKey) || 0;
    
    if (attempts >= 3) {
      console.log(`Max recovery attempts reached for ${attemptKey}`);
      await this.escalateToManualReview(stuckTransaction);
      return;
    }

    this.recoveryAttempts.set(attemptKey, attempts + 1);
    console.log(`Recovery attempt ${attempts + 1} for transaction ${attemptKey}`);

    try {
      // Check if source transaction actually confirmed
      const sourceConfirmed = await this.verifySourceTransaction(stuckTransaction);
      if (!sourceConfirmed) {
        await this.handleUnconfirmedSource(stuckTransaction);
        return;
      }

      // Check if destination chain is processing
      const destinationReady = await this.checkDestinationChainHealth(stuckTransaction.destinationChain);
      if (!destinationReady) {
        console.log(`Destination chain ${stuckTransaction.destinationChain} not ready, will retry`);
        setTimeout(() => this.attemptRecovery(stuckTransaction), 5 * 60 * 1000);
        return;
      }

      // Try to manually trigger bridge processing
      await this.triggerManualBridgeProcessing(stuckTransaction);
      
    } catch (error) {
      console.error(`Recovery attempt failed for ${attemptKey}:`, error);
      setTimeout(() => this.attemptRecovery(stuckTransaction), 10 * 60 * 1000);
    }
  }

  async verifySourceTransaction(transaction) {
    try {
      const provider = this.chainManager.providers[transaction.sourceChain];
      const receipt = await provider.getTransactionReceipt(transaction.sourceTxHash);
      
      if (!receipt) {
        console.log(`Source transaction not found: ${transaction.sourceTxHash}`);
        return false;
      }

      const config = this.chainManager.chains[transaction.sourceChain];
      const currentBlock = await provider.getBlockNumber();
      const confirmations = currentBlock - receipt.blockNumber;

      if (confirmations < config.confirmations) {
        console.log(`Source transaction needs more confirmations: ${confirmations}/${config.confirmations}`);
        return false;
      }

      return receipt.status === 1; // Transaction successful
    } catch (error) {
      console.error(`Error verifying source transaction:`, error);
      return false;
    }
  }

  async checkDestinationChainHealth(chainName) {
    try {
      const provider = this.chainManager.providers[chainName];
      const latestBlock = await provider.getBlockNumber();
      
      // Check if chain is synced (block timestamp within 5 minutes)
      const block = await provider.getBlock(latestBlock);
      const blockAge = Date.now() - (block.timestamp * 1000);
      
      return blockAge < 5 * 60 * 1000; // 5 minutes
    } catch (error) {
      console.error(`Error checking ${chainName} health:`, error);
      return false;
    }
  }

  async escalateToManualReview(transaction) {
    console.log(`Escalating transaction ${transaction.id} to manual review`);
    
    await this.alerts.sendCriticalAlert('MANUAL_REVIEW_REQUIRED', {
      transactionId: transaction.id,
      user: transaction.user,
      amount: transaction.amount,
      sourceChain: transaction.sourceChain,
      destinationChain: transaction.destinationChain,
      sourceTxHash: transaction.sourceTxHash,
      stuckDuration: Date.now() - transaction.createdAt
    });

    // Update database to prevent further automatic attempts
    await this.processor.db.updateTransaction(transaction.id, {
      status: 'manual_review_required',
      updatedAt: Date.now()
    });
  }
}

-- Critical indexes for performance
CREATE INDEX idx_transactions_status_created ON bridge_transactions(status, created_at);
CREATE INDEX idx_transactions_nonce_chains ON bridge_transactions(nonce, source_chain, destination_chain);
CREATE INDEX idx_transactions_timeout ON bridge_transactions(timeout_at) WHERE status IN ('initiated', 'confirmed');
CREATE INDEX idx_transactions_user_recent ON bridge_transactions(user, created_at DESC);

// Cleanup completed transactions older than 30 days
setInterval(async () => {
  const cutoffDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
  await this.db.archiveCompletedTransactions(cutoffDate);
}, 24 * 60 * 60 * 1000); // Daily cleanup

// Limit in-memory recovery attempts tracking
setInterval(() => {
  const now = Date.now();
  for (const [key, timestamp] of this.recoveryAttempts.entries()) {
    if (now - timestamp > 60 * 60 * 1000) { // 1 hour old
      this.recoveryAttempts.delete(key);
    }
  }
}, 10 * 60 * 1000); // Every 10 minutes

class IntelligentAlertSystem {
  constructor() {
    this.alertLevels = {
      INFO: { slack: false, email: false, sms: false },
      WARNING: { slack: true, email: false, sms: false },
      CRITICAL: { slack: true, email: true, sms: false },
      EMERGENCY: { slack: true, email: true, sms: true }
    };
    
    // Prevent alert spam
    this.alertCooldowns = new Map();
    this.cooldownPeriods = {
      'TRANSACTION_STUCK': 15 * 60 * 1000, // 15 minutes
      'CHAIN_HEALTH': 5 * 60 * 1000,       // 5 minutes
      'HIGH_FAILURE_RATE': 30 * 60 * 1000  // 30 minutes
    };
  }

  async sendCriticalAlert(alertType, data) {
    const cooldownKey = `${alertType}_${data.transactionId || 'global'}`;
    const lastAlert = this.alertCooldowns.get(cooldownKey);
    const cooldownPeriod = this.cooldownPeriods[alertType] || 60000;
    
    if (lastAlert && Date.now() - lastAlert < cooldownPeriod) {
      console.log(`Alert ${alertType} in cooldown period`);
      return;
    }

    this.alertCooldowns.set(cooldownKey, Date.now());
    
    const alert = {
      type: alertType,
      level: 'CRITICAL',
      message: this.formatAlertMessage(alertType, data),
      data,
      timestamp: new Date().toISOString()
    };

    await this.dispatchAlert(alert);
  }

  formatAlertMessage(alertType, data) {
    switch (alertType) {
      case 'TRANSACTION_STUCK':
        return `🚨 Bridge transaction stuck: ${data.amount} USDC from ${data.sourceChain} to ${data.destinationChain} (${Math.round(data.duration / 60000)} minutes)`;
      
      case 'HIGH_FAILURE_RATE':
        return `⚠️ Bridge failure rate: ${data.failureRate}% over last hour (${data.failedCount}/${data.totalCount} transactions)`;
        
      case 'CHAIN_HEALTH':
        return `🔴 ${data.chainName} chain health degraded: ${data.issue}`;
        
      default:
        return `Alert: ${alertType}`;
    }
  }
}