payment-kit 1.26.5 → 1.27.0

package/api/src/libs/payment.ts

@@ -36,6 +36,60 @@ import { CHARGE_SUPPORTED_CHAIN_TYPES, EVM_CHAIN_TYPES } from './constants';
 import { getTokenByAddress } from '../integrations/arcblock/stake';
 import { isCreditMetered } from './credit-utils';
 
+// ============================================================================
+// Delegation cache - avoids redundant chain queries for the same user
+// ============================================================================
+const DELEGATION_CACHE_TTL_MS = 30_000; // 30 seconds
+
+// Only cache immutable lookup results (address, source), NOT DelegateState.
+// DelegateState contains on-chain token balances that change with every consumption;
+// caching it could allow stale balances to pass sufficiency checks, causing overdraft.
+interface DelegationCacheEntry {
+  delegator: string;
+  delegationAddress: string;
+  source: string;
+  needsBackfill: boolean;
+  cachedAt: number;
+}
+
+const delegationCache = new Map<string, DelegationCacheEntry>();
+
+function getDelegationCacheKey(userDid: string, paymentMethodId: string): string {
+  return `${userDid}:${paymentMethodId}`;
+}
+
+function getCachedDelegation(key: string): DelegationCacheEntry | null {
+  const entry = delegationCache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.cachedAt > DELEGATION_CACHE_TTL_MS) {
+    delegationCache.delete(key);
+    return null;
+  }
+  return entry;
+}
+
+function setCachedDelegation(key: string, entry: Omit<DelegationCacheEntry, 'cachedAt'>): void {
+  // Evict old entries if cache grows too large
+  if (delegationCache.size > 1000) {
+    const now = Date.now();
+    for (const [k, v] of delegationCache) {
+      if (now - v.cachedAt > DELEGATION_CACHE_TTL_MS) {
+        delegationCache.delete(k);
+      }
+    }
+  }
+  delegationCache.set(key, { ...entry, cachedAt: Date.now() });
+}
+
+// Invalidate cache for a specific user (e.g., after delegation changes)
+export function invalidateDelegationCache(userDid: string): void {
+  for (const key of delegationCache.keys()) {
+    if (key.startsWith(`${userDid}:`)) {
+      delegationCache.delete(key);
+    }
+  }
+}
+
 export interface SufficientForPaymentResult {
   sufficient: boolean;
   reason?: LiteralUnion<
@@ -263,39 +317,76 @@ export async function isDelegationSufficientForPayment(args: {
     });
 
     const client = paymentMethod.getOcapClient();
+    const cacheKey = getDelegationCacheKey(delegator, paymentMethod.id);
+    const cached = getCachedDelegation(cacheKey);
 
-    // have delegated before? Use migration-aware fallback query
-    // Priority: storedDelegationAddress > subscription.payment_details.arcblock.delegation_address
-    const delegationResult = await getDelegationAddressWithFallback({
-      storedAddress: storedDelegationAddress || subscription?.payment_details?.arcblock?.delegation_address,
-      delegator,
-      client,
-    });
-    if (!delegationResult) {
-      logger.error('isDelegationSufficientForPayment: no delegation address found', {
+    let delegationAddress: string;
+    let source: string;
+
+    if (cached) {
+      // Use cached delegation address (immutable), but always query fresh state
+      delegationAddress = cached.delegationAddress;
+      source = cached.source;
+      logger.info('isDelegationSufficientForPayment: using cached delegation address', {
         delegator,
-        storedDelegationAddress,
-        subscriptionDelegationAddress: subscription?.payment_details?.arcblock?.delegation_address,
-        subscriptionId: subscription?.id,
+        delegationAddress,
+        source,
+        cacheAgeMs: Date.now() - cached.cachedAt,
       });
-      return { sufficient: false, reason: 'NO_DELEGATION' };
-    }
+    } else {
+      // have delegated before? Use migration-aware fallback query
+      // Priority: storedDelegationAddress > subscription.payment_details.arcblock.delegation_address
+      const delegationResult = await getDelegationAddressWithFallback({
+        storedAddress: storedDelegationAddress || subscription?.payment_details?.arcblock?.delegation_address,
+        delegator,
+        client,
+      });
+      if (!delegationResult) {
+        logger.error('isDelegationSufficientForPayment: no delegation address found', {
+          delegator,
+          storedDelegationAddress,
+          subscriptionDelegationAddress: subscription?.payment_details?.arcblock?.delegation_address,
+          subscriptionId: subscription?.id,
+        });
+        return { sufficient: false, reason: 'NO_DELEGATION' };
+      }
 
-    const { address, needsBackfill, source } = delegationResult;
+      const { address, needsBackfill } = delegationResult;
+      delegationAddress = address;
+      source = delegationResult.source;
+
+      // Backfill if needed and subscription is available
+      if (needsBackfill && subscription) {
+        await backfillDelegationAddress(subscription.id, address);
+      }
 
-    // Backfill if needed and subscription is available
-    if (needsBackfill && subscription) {
-      await backfillDelegationAddress(subscription.id, address);
+      // Cache the immutable lookup result (address + source), not the state
+      setCachedDelegation(cacheKey, {
+        delegator,
+        delegationAddress: address,
+        source,
+        needsBackfill,
+      });
     }
 
-    const { state } = await client.getDelegateState({ address });
-    if (!state) {
-      logger.error('isDelegationSufficientForPayment: no delegation state', { address, delegator, source });
+    // Always query fresh DelegateState — balances change with every consumption
+    const delegateResult = await client.getDelegateState({ address: delegationAddress });
+    if (!delegateResult.state) {
+      logger.error('isDelegationSufficientForPayment: no delegation state', {
+        address: delegationAddress,
+        delegator,
+        source,
+      });
       return { sufficient: false, reason: 'NO_DELEGATION' };
     }
+    const { state } = delegateResult;
 
     if (!state.ops || state.ops?.length === 0) {
-      logger.error('isDelegationSufficientForPayment: no delegation ops', { address, delegator, source });
+      logger.error('isDelegationSufficientForPayment: no delegation ops', {
+        address: delegationAddress,
+        delegator,
+        source,
+      });
       return { sufficient: false, reason: 'NO_DELEGATION' };
     }
 

package/api/src/libs/queue/index.ts

@@ -45,6 +45,7 @@ type PushParams<T> = {
   persist?: boolean;
   delay?: number; // in seconds
   runAt?: number; // unix timestamp in seconds
+  skipDuplicateCheck?: boolean; // Q1: skip addJob's findOne when caller guarantees no duplicate
 };
 
 export default function createQueue<T = any>({ name, onJob, options = defaults }: QueueParams<T>) {
@@ -107,7 +108,7 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     // @ts-ignore
   }, concurrency);
 
-  const push = ({ job, id, persist = true, delay, runAt }: PushParams<T>) => {
+  const push = ({ job, id, persist = true, delay, runAt, skipDuplicateCheck = false }: PushParams<T>) => {
     const jobEvents = new EventEmitter();
     const emit = (e: string, data: any) => {
       queueEvents.emit(e, data);
@@ -142,7 +143,7 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
       }
 
       store
-        .addJob(jobId, job, attrs)
+        .addJob(jobId, job, attrs, skipDuplicateCheck)
         .then(() => {
           emit('queued', { id: jobId, job, attrs, persist });
           logger.info('delayed or scheduled job queued', { id: jobId, job, attrs, persist });
@@ -222,7 +223,7 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
 
     if (persist) {
       store
-        .addJob(jobId, job)
+        .addJob(jobId, job, {}, skipDuplicateCheck)
         .then(queueJob)
         .catch((err) => {
           logger.error('Can not add job to store', { error: err });
@@ -263,18 +264,28 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     return doc ? doc.job : null;
   };
 
-  const deleteJob = async (id: string): Promise<boolean> => {
-    const exists = await getJob(id);
-
-    if (!exists) {
-      return false;
+  // Q1: Accept knownExists flag to skip redundant getJob read when caller already checked
+  const deleteJob = async (id: string, knownExists: boolean = false): Promise<boolean> => {
+    if (!knownExists) {
+      const exists = await getJob(id);
+      if (!exists) {
+        return false;
+      }
     }
     try {
-      await cancel(id);
+      // Q1: Try direct delete first (1 DB op). If delete fails, fall back to cancel
+      // so the job is at least marked cancelled=true in DB for crash recovery.
+      cancelledJobs.add(id);
       await store.deleteJob(id);
       logger.info(`Job deleted successfully: ${id}`);
       return true;
     } catch (error) {
+      // Delete failed — ensure job is marked cancelled in DB as fallback
+      try {
+        await cancel(id);
+      } catch (cancelError) {
+        console.error(`Error during job cancellation fallback for ${id}:`, cancelError);
+      }
       console.error(`Error during job deletion process for ${id}:`, error);
       return false;
     }

package/api/src/libs/queue/store.ts

@@ -46,14 +46,18 @@ export default function createQueueStore(queue: string) {
 
       return job.update(updates);
     },
-    async addJob(id: string, job: any, attrs: Partial<TJob> = {}): Promise<TJob> {
-      const existingJob = await Job.findOne({ where: { id } });
+    // Q1: skipDuplicateCheck skips the pre-create findOne when caller guarantees no duplicate
+    // (e.g., after deleteJob). Unique constraint catch still handles concurrent edge cases.
+    async addJob(id: string, job: any, attrs: Partial<TJob> = {}, skipDuplicateCheck: boolean = false): Promise<TJob> {
+      if (!skipDuplicateCheck) {
+        const existingJob = await Job.findOne({ where: { id } });
 
-      if (existingJob) {
-        throw new CustomError(
-          'JOB_DUPLICATE',
-          `Job with id ${id} already exists ${existingJob.queue === queue ? 'in the same queue' : `in queue ${existingJob.queue}`}`
-        );
+        if (existingJob) {
+          throw new CustomError(
+            'JOB_DUPLICATE',
+            `Job with id ${id} already exists ${existingJob.queue === queue ? 'in the same queue' : `in queue ${existingJob.queue}`}`
+          );
+        }
       }
 
       try {

package/api/src/libs/reference-cache.ts

@@ -0,0 +1,115 @@
+import { Meter, PaymentCurrency } from '../store/models';
+import logger from './logger';
+
+// Shared TTL cache for reference data (meter, currency) that rarely changes.
+// Used by both ingestion route and credit consumption pipeline.
+const CACHE_TTL = 5 * 60_000; // 5 minutes (invalidated on model update/destroy)
+const CACHE_MAX_SIZE = 500; // safety cap; meter/currency counts are typically < 100
+
+// Performance instrumentation: cache hit/miss counters (logged every 60s)
+const cacheStats = { meterHit: 0, meterMiss: 0, currencyHit: 0, currencyMiss: 0, expandedHit: 0, expandedMiss: 0 };
+setInterval(() => {
+  const total =
+    cacheStats.meterHit +
+    cacheStats.meterMiss +
+    cacheStats.currencyHit +
+    cacheStats.currencyMiss +
+    cacheStats.expandedHit +
+    cacheStats.expandedMiss;
+  if (total > 0) {
+    logger.info('Reference cache stats (60s)', { ...cacheStats });
+    cacheStats.meterHit = 0;
+    cacheStats.meterMiss = 0;
+    cacheStats.currencyHit = 0;
+    cacheStats.currencyMiss = 0;
+    cacheStats.expandedHit = 0;
+    cacheStats.expandedMiss = 0;
+  }
+}, 60_000).unref();
+type CacheEntry = { data: any; expires: number };
+
+// Evict expired entries when cache exceeds max size
+function evictExpired(cache: Map<string, CacheEntry>) {
+  if (cache.size <= CACHE_MAX_SIZE) return;
+  const now = Date.now();
+  for (const [k, v] of cache) {
+    if (v.expires < now) cache.delete(k);
+  }
+}
+
+const meterCache = new Map<string, CacheEntry>();
+const currencyCache = new Map<string, CacheEntry>();
+
+// Lazily register hooks after models are initialized (avoid top-level addHook before Sequelize init)
+let hooksRegistered = false;
+function ensureCacheHooks() {
+  if (hooksRegistered) return;
+  hooksRegistered = true;
+  Meter.addHook('afterUpdate', 'invalidateMeterCache', (model: any) => {
+    meterCache.delete(model.event_name);
+    meterExpandedCache.delete(model.event_name);
+  });
+  Meter.addHook('afterDestroy', 'invalidateMeterCacheOnDelete', (model: any) => {
+    meterCache.delete(model.event_name);
+    meterExpandedCache.delete(model.event_name);
+  });
+  PaymentCurrency.addHook('afterUpdate', 'invalidateCurrencyCache', (model: any) => {
+    currencyCache.delete(model.id);
+    // Also invalidate expanded meter cache entries that reference this currency
+    meterExpandedCache.clear();
+  });
+}
+
+export async function getCachedMeter(eventName: string) {
+  ensureCacheHooks();
+  const cached = meterCache.get(eventName);
+  if (cached && cached.expires > Date.now()) {
+    cacheStats.meterHit++;
+    return cached.data;
+  }
+  cacheStats.meterMiss++;
+  const meter = await Meter.getMeterByEventName(eventName);
+  if (meter) {
+    evictExpired(meterCache);
+    meterCache.set(eventName, { data: meter, expires: Date.now() + CACHE_TTL });
+  }
+  return meter;
+}
+
+export async function getCachedCurrency(currencyId: string) {
+  ensureCacheHooks();
+  const cached = currencyCache.get(currencyId);
+  if (cached && cached.expires > Date.now()) {
+    cacheStats.currencyHit++;
+    return cached.data;
+  }
+  cacheStats.currencyMiss++;
+  const currency = await PaymentCurrency.findByPk(currencyId);
+  if (currency) {
+    evictExpired(currencyCache);
+    currencyCache.set(currencyId, { data: currency, expires: Date.now() + CACHE_TTL });
+  }
+  return currency;
+}
+
+// Q3: For consumption pipeline — cached meter with PaymentCurrency included
+const meterExpandedCache = new Map<string, CacheEntry>();
+
+export async function getCachedMeterExpanded(eventName: string) {
+  ensureCacheHooks();
+  const cached = meterExpandedCache.get(eventName);
+  if (cached && cached.expires > Date.now()) {
+    cacheStats.expandedHit++;
+    return cached.data;
+  }
+  cacheStats.expandedMiss++;
+  const meter = await Meter.findOne({
+    where: { event_name: eventName },
+    include: [{ model: PaymentCurrency, as: 'paymentCurrency' }],
+  });
+  if (meter) {
+    evictExpired(meterExpandedCache);
+    meterExpandedCache.set(eventName, { data: meter, expires: Date.now() + CACHE_TTL });
+  }
+  return meter;
+}

package/api/src/queues/auto-recharge.ts

@@ -590,10 +590,28 @@ export const autoRechargeQueue = createQueue<AutoRechargeJobData>({
 /**
  * 检查并触发自动充值 (添加到队列)
  */
+// Q2: TTL cache for AutoRechargeConfig existence check (99%+ returns null, rarely changes)
+const AUTO_RECHARGE_CACHE_TTL = 5 * 60_000; // 5 minutes
+const AUTO_RECHARGE_CACHE_MAX_SIZE = 500;
+const autoRechargeConfigCache = new Map<string, { exists: boolean; expires: number }>();
+
+let autoRechargeHooksRegistered = false;
+function ensureAutoRechargeHooks() {
+  if (autoRechargeHooksRegistered) return;
+  autoRechargeHooksRegistered = true;
+  const invalidateCache = (model: any) => {
+    autoRechargeConfigCache.delete(`${model.customer_id}:${model.currency_id}`);
+  };
+  AutoRechargeConfig.addHook('afterCreate', 'invalidateAutoRechargeCache', invalidateCache);
+  AutoRechargeConfig.addHook('afterUpdate', 'invalidateAutoRechargeCacheOnUpdate', invalidateCache);
+  AutoRechargeConfig.addHook('afterDestroy', 'invalidateAutoRechargeCacheOnDelete', invalidateCache);
+}
+
 export async function checkAndTriggerAutoRecharge(
   customer: Customer,
   currencyId: string,
-  currentBalance: string
+  currentBalance: string,
+  options?: { currency?: any; meter?: any }
 ): Promise<void> {
   try {
     logger.info('----- Checking and triggering auto recharge -----', {
@@ -602,30 +620,59 @@ export async function checkAndTriggerAutoRecharge(
       currentBalance,
     });
 
-    // Check if the associated meter is inactive
-    const currency = await PaymentCurrency.findByPk(currencyId);
-    if (currency?.type === 'credit') {
-      // Find meter by currency_id (meter.currency_id -> PaymentCurrency)
-      const meter = await Meter.findOne({
-        where: { currency_id: currencyId },
+    // Q2: Check cache first — most customers have no auto-recharge config
+    ensureAutoRechargeHooks();
+    const cacheKey = `${customer.id}:${currencyId}`;
+    const cached = autoRechargeConfigCache.get(cacheKey);
+    if (cached && cached.expires > Date.now() && !cached.exists) {
+      logger.debug('Auto recharge config not found (cached)', {
+        customerId: customer.id,
+        currencyId,
       });
-      if (meter && meter.status === 'inactive') {
-        logger.info('Meter is inactive, skipping auto recharge check', {
-          customerId: customer.id,
-          currencyId,
-          meterId: meter.id,
-        });
-        return;
+      return;
+    }
+
+    // T2b: Reuse caller-provided currency to avoid redundant DB query
+    const currency = options?.currency ?? (await PaymentCurrency.findByPk(currencyId));
+
+    // Reuse caller-provided meter when available to avoid redundant DB query
+    let meterPromise: Promise<any>;
+    if (options?.meter != null) {
+      meterPromise = Promise.resolve(options.meter);
+    } else if (currency?.type === 'credit') {
+      meterPromise = Meter.findOne({ where: { currency_id: currencyId } });
+    } else {
+      meterPromise = Promise.resolve(null);
+    }
+
+    const [meter, config] = await Promise.all([
+      meterPromise,
+      AutoRechargeConfig.findOne({
+        where: {
+          customer_id: customer.id,
+          currency_id: currencyId,
+          enabled: true,
+        },
+      }),
+    ]);
+
+    // Update cache with result (evict expired entries if cache grows too large)
+    if (autoRechargeConfigCache.size > AUTO_RECHARGE_CACHE_MAX_SIZE) {
+      const now = Date.now();
+      for (const [k, v] of autoRechargeConfigCache) {
+        if (v.expires < now) autoRechargeConfigCache.delete(k);
       }
     }
+    autoRechargeConfigCache.set(cacheKey, { exists: !!config, expires: Date.now() + AUTO_RECHARGE_CACHE_TTL });
 
-    const config = await AutoRechargeConfig.findOne({
-      where: {
-        customer_id: customer.id,
-        currency_id: currencyId,
-        enabled: true,
-      },
-    });
+    if (meter && meter.status === 'inactive') {
+      logger.info('Meter is inactive, skipping auto recharge check', {
+        customerId: customer.id,
+        currencyId,
+        meterId: meter.id,
+      });
+      return;
+    }
 
     if (!config) {
       logger.debug('No auto recharge config found', {