Forward-Deployed Engineer & Systems Integration Architect

/**
 * Solo-Architected Event-Driven Loyalty & Dynamic State Engine
 * Ingests live gRPC block events, computes time-weighted holding curves,
 * and idempotently mutates user profile badges and tier states.
 */

import { Redis } from 'ioredis';
import { Pool } from 'pg';

export interface IngestedTransactionEvent {
  signature: string;
  slot: number;
  blockTime: number;
  userAddress: string;
  assetMint: string;
  action: 'TRANSFER_IN' | 'TRANSFER_OUT' | 'INTERACTION';
  volumeUsd: number;
}

export interface UserTierState {
  userAddress: string;
  currentTier: 'BRONZE' | 'SILVER' | 'GOLD' | 'OBSIDIAN';
  holdingDurationSeconds: number;
  timeWeightedScore: number;
  eligibleBadges: string[];
  lastEvaluatedSlot: number;
  nonce: number;
}

export class LoyaltyRuleEngine {
  constructor(
    private readonly db: Pool,
    private readonly redis: Redis,
    private readonly idempotencyTtl: number = 86400
  ) {}

  /**
   * Evaluates incoming stream events against deterministic tier & badge rule curves.
   * Ensures sub-50ms evaluation with zero double-issuance via atomic Redis lock.
   */
  async processEvent(event: IngestedTransactionEvent): Promise<UserTierState | null> {
    const idempotencyKey = `idemp:${event.signature}:${event.userAddress}`;
    
    // 1. Idempotency Gate: prevent race conditions and duplicate event replay
    const acquired = await this.redis.set(idempotencyKey, '1', 'EX', this.idempotencyTtl, 'NX');
    if (!acquired) {
      return null; // Event signature already processed in sliding window
    }

    const client = await this.db.connect();
    try {
      await client.query('BEGIN');

      // 2. Fetch current state with row-level pessimistic lock
      const userRes = await client.query(
        `SELECT current_tier, holding_duration_seconds, time_weighted_score, eligible_badges, last_evaluated_slot, nonce
         FROM user_loyalty_profiles WHERE user_address = $1 FOR UPDATE`,
        [event.userAddress]
      );

      const current = userRes.rows[0] || {
        current_tier: 'BRONZE',
        holding_duration_seconds: 0,
        time_weighted_score: 0,
        eligible_badges: [],
        last_evaluated_slot: 0,
        nonce: 0,
      };

      // 3. Compute Time-Weighted Holding Curve: Score = ln(1 + delta_t) * volume_multiplier
      const deltaSeconds = Math.max(0, event.blockTime - (current.holding_duration_seconds || event.blockTime));
      const logWeight = Math.log1p(deltaSeconds / 86400); // 1-day logarithmic normalization
      const updatedScore = current.time_weighted_score + (logWeight * Math.max(1, event.volumeUsd * 0.1));

      // 4. Deterministic Badge & Tier Qualification Rules
      const newBadges = new Set<string>(current.eligible_badges);
      if (deltaSeconds >= 30 * 86400) newBadges.add('BADGE_DIAMOND_HOLDER_30D');
      if (updatedScore >= 1000) newBadges.add('BADGE_HIGH_VELOCITY_TRADER');
      if (event.volumeUsd >= 5000) newBadges.add('BADGE_WHALE_SWAP');

      let newTier: 'BRONZE' | 'SILVER' | 'GOLD' | 'OBSIDIAN' = 'BRONZE';
      if (updatedScore >= 5000 && newBadges.has('BADGE_DIAMOND_HOLDER_30D')) {
        newTier = 'OBSIDIAN';
      } else if (updatedScore >= 2000) {
        newTier = 'GOLD';
      } else if (updatedScore >= 500) {
        newTier = 'SILVER';
      }

      // 5. Atomic state update with monotonic nonce increment
      const updatedProfile: UserTierState = {
        userAddress: event.userAddress,
        currentTier: newTier,
        holdingDurationSeconds: current.holding_duration_seconds + deltaSeconds,
        timeWeightedScore: Math.round(updatedScore * 100) / 100,
        eligibleBadges: Array.from(newBadges),
        lastEvaluatedSlot: event.slot,
        nonce: current.nonce + 1,
      };

      await client.query(
        `INSERT INTO user_loyalty_profiles 
         (user_address, current_tier, holding_duration_seconds, time_weighted_score, eligible_badges, last_evaluated_slot, nonce)
         VALUES ($1, $2, $3, $4, $5, $6, $7)
         ON CONFLICT (user_address) DO UPDATE SET
           current_tier = EXCLUDED.current_tier,
           holding_duration_seconds = EXCLUDED.holding_duration_seconds,
           time_weighted_score = EXCLUDED.time_weighted_score,
           eligible_badges = EXCLUDED.eligible_badges,
           last_evaluated_slot = EXCLUDED.last_evaluated_slot,
           nonce = EXCLUDED.nonce`,
        [
          updatedProfile.userAddress,
          updatedProfile.currentTier,
          updatedProfile.holdingDurationSeconds,
          updatedProfile.timeWeightedScore,
          updatedProfile.eligibleBadges,
          updatedProfile.lastEvaluatedSlot,
          updatedProfile.nonce,
        ]
      );

      await client.query('COMMIT');
      return updatedProfile;
    } catch (err) {
      await client.query('ROLLBACK');
      await this.redis.del(idempotencyKey); // Release key on error
      throw err;
    } finally {
      client.release();
    }
  }
}