payment-kit 1.22.32 → 1.23.1

package/api/src/queues/credit-reconciliation.ts

@@ -0,0 +1,253 @@
+/**
+ * Credit Token Balance Reconciliation Queue
+ *
+ * Verifies that customer's on-chain token balance matches database records.
+ * Triggered after mint (grant) and burn (expire) operations.
+ */
+
+import { BN } from '@ocap/util';
+import logger from '../libs/logger';
+import createQueue from '../libs/queue';
+import { getCustomerTokenBalance } from '../integrations/arcblock/token';
+import { CreditGrant, CreditTransaction, Customer, PaymentCurrency } from '../store/models';
+import { events } from '../libs/event';
+
+type ReconciliationJob = {
+  customerId: string;
+  currencyId: string;
+  creditGrantId: string;
+  trigger: 'mint' | 'burn';
+};
+
+type BalanceInfo = {
+  // Sum of remaining_amount in all granted grants
+  dbRemainingAmount: string;
+  // Sum of credit_amount in pending transfers (consumed but not yet transferred on-chain)
+  pendingTransferAmount: string;
+  // Expected on-chain balance = dbRemainingAmount + pendingTransferAmount
+  expectedChainBalance: string;
+};
+
+/**
+ * Calculate customer's balance info from database
+ *
+ * The expected chain balance should be:
+ * - DB remaining_amount (what's left in grants that have been minted)
+ * - Plus pending transfer amount (consumed in DB but not yet transferred on-chain)
+ *
+ * Only counts grants with chain_status === 'mint_completed' since those have on-chain tokens.
+ */
+async function getBalanceInfo(customerId: string, currencyId: string): Promise<BalanceInfo> {
+  // Get all granted credit grants that have been minted on-chain
+  const grants = await CreditGrant.findAll({
+    where: {
+      customer_id: customerId,
+      currency_id: currencyId,
+      status: 'granted',
+      chain_status: 'mint_completed', // Only count grants with on-chain tokens
+    },
+  });
+
+  const dbRemainingAmount = grants
+    .reduce((sum, grant) => sum.add(new BN(grant.remaining_amount)), new BN(0))
+    .toString();
+
+  // Get pending transfers (consumed but token not yet transferred on-chain)
+  const pendingTransactions = await CreditTransaction.findAll({
+    where: {
+      customer_id: customerId,
+      transfer_status: 'pending',
+    },
+    include: [
+      {
+        model: CreditGrant,
+        as: 'creditGrant',
+        where: { currency_id: currencyId },
+        required: true,
+        attributes: [],
+      },
+    ],
+  });
+
+  const pendingTransferAmount = pendingTransactions
+    .reduce((sum, tx) => sum.add(new BN(tx.credit_amount)), new BN(0))
+    .toString();
+
+  // Expected chain balance = remaining in grants + pending transfers
+  // Because: consumed credit is deducted from grant but token is still in user's wallet
+  const expectedChainBalance = new BN(dbRemainingAmount).add(new BN(pendingTransferAmount)).toString();
+
+  return {
+    dbRemainingAmount,
+    pendingTransferAmount,
+    expectedChainBalance,
+  };
+}
+
+/**
+ * Handle reconciliation job
+ */
+async function handleReconciliation(job: ReconciliationJob) {
+  const { customerId, currencyId, creditGrantId, trigger } = job;
+
+  logger.info('Starting credit balance reconciliation', {
+    customerId,
+    currencyId,
+    creditGrantId,
+    trigger,
+  });
+
+  try {
+    const customer = await Customer.findByPk(customerId);
+    if (!customer) {
+      logger.warn('Customer not found for reconciliation', { customerId });
+      return;
+    }
+
+    const currency = await PaymentCurrency.findByPk(currencyId);
+    if (!currency || !currency.isOnChainCredit()) {
+      logger.warn('Currency not found or not on-chain credit', { currencyId });
+      return;
+    }
+
+    // Get balance info (considering pending transfers)
+    const balanceInfo = await getBalanceInfo(customerId, currencyId);
+    const chainBalance = await getCustomerTokenBalance(customer.did, currency);
+
+    const difference = new BN(chainBalance).sub(new BN(balanceInfo.expectedChainBalance));
+    const isMatched = difference.eq(new BN(0));
+
+    if (isMatched) {
+      logger.info('Credit balance reconciliation passed', {
+        customerId,
+        currencyId,
+        creditGrantId,
+        trigger,
+        dbRemainingAmount: balanceInfo.dbRemainingAmount,
+        pendingTransferAmount: balanceInfo.pendingTransferAmount,
+        expectedChainBalance: balanceInfo.expectedChainBalance,
+        actualChainBalance: chainBalance,
+      });
+    } else {
+      logger.error('Credit balance mismatch detected', {
+        customerId,
+        customerDid: customer.did,
+        currencyId,
+        creditGrantId,
+        trigger,
+        dbRemainingAmount: balanceInfo.dbRemainingAmount,
+        pendingTransferAmount: balanceInfo.pendingTransferAmount,
+        expectedChainBalance: balanceInfo.expectedChainBalance,
+        actualChainBalance: chainBalance,
+        difference: difference.toString(),
+      });
+
+      // Emit event for monitoring/alerting
+      events.emit('customer.credit.reconciliation.mismatch', {
+        customerId,
+        customerDid: customer.did,
+        currencyId,
+        creditGrantId,
+        trigger,
+        dbRemainingAmount: balanceInfo.dbRemainingAmount,
+        pendingTransferAmount: balanceInfo.pendingTransferAmount,
+        expectedChainBalance: balanceInfo.expectedChainBalance,
+        actualChainBalance: chainBalance,
+        difference: difference.toString(),
+      });
+    }
+  } catch (error: any) {
+    logger.error('Credit balance reconciliation failed', {
+      customerId,
+      currencyId,
+      creditGrantId,
+      trigger,
+      error: error.message,
+    });
+  }
+}
+
+/**
+ * Reconciliation queue
+ */
+export const reconciliationQueue = createQueue<ReconciliationJob>({
+  name: 'credit-reconciliation',
+  onJob: handleReconciliation,
+  options: {
+    concurrency: 3,
+    maxRetries: 2,
+    retryDelay: 5000,
+    enableScheduledJob: true,
+  },
+});
+
+reconciliationQueue.on('finished', ({ id, job }) => {
+  logger.debug('Reconciliation job completed', { id, customerId: job.customerId });
+});
+
+reconciliationQueue.on('failed', ({ id, job, error }) => {
+  logger.error('Reconciliation job failed', { id, customerId: job.customerId, error: error.message });
+});
+
+/**
+ * Add reconciliation job to queue
+ * @param delay - delay in seconds (default: 5)
+ */
+async function addReconciliationJob(
+  customerId: string,
+  currencyId: string,
+  creditGrantId: string,
+  trigger: 'mint' | 'burn',
+  delay: number = 5
+): Promise<void> {
+  const jobId = `reconcile-${customerId}-${currencyId}`;
+
+  // Skip if already queued
+  const existingJob = await reconciliationQueue.get(jobId);
+  if (existingJob) {
+    logger.debug('Reconciliation job already queued', { jobId });
+    return;
+  }
+
+  await reconciliationQueue.push({
+    id: jobId,
+    job: { customerId, currencyId, creditGrantId, trigger },
+    delay,
+  });
+
+  logger.info('Reconciliation job added', { jobId, trigger, delay });
+}
+
+/**
+ * Start reconciliation queue and register event listeners
+ */
+// eslint-disable-next-line require-await
+export async function startReconciliationQueue() {
+  logger.info('Starting credit reconciliation queue');
+
+  // Trigger reconciliation after successful mint
+  events.on('customer.credit_grant.minted', async (creditGrant: CreditGrant) => {
+    try {
+      await addReconciliationJob(creditGrant.customer_id, creditGrant.currency_id, creditGrant.id, 'mint');
+    } catch (error: any) {
+      logger.error('Failed to add reconciliation job after mint', {
+        creditGrantId: creditGrant.id,
+        error: error.message,
+      });
+    }
+  });
+
+  // Trigger reconciliation after successful burn
+  events.on('customer.credit_grant.burned', async (creditGrant: CreditGrant) => {
+    try {
+      await addReconciliationJob(creditGrant.customer_id, creditGrant.currency_id, creditGrant.id, 'burn');
+    } catch (error: any) {
+      logger.error('Failed to add reconciliation job after burn', {
+        creditGrantId: creditGrant.id,
+        error: error.message,
+      });
+    }
+  });
+
+  logger.info('Credit reconciliation queue started');
+}

package/api/src/queues/refund.ts

@@ -1,3 +1,4 @@
+import { BN, fromUnitToToken } from '@ocap/util';
 import { isRefundReasonSupportedByStripe } from '../libs/refund';
 import { checkRemainingStake, getSubscriptionStakeAddress } from '../libs/subscription';
 import { sendErc20ToUser } from '../integrations/ethereum/token';
@@ -14,6 +15,9 @@ import { PaymentIntent } from '../store/models/payment-intent';
 import { PaymentMethod } from '../store/models/payment-method';
 import { Refund } from '../store/models/refund';
 import { Subscription } from '../store/models/subscription';
+import { CreditGrant } from '../store/models/credit-grant';
+import { Invoice } from '../store/models/invoice';
+import { burnToken } from '../integrations/arcblock/token';
 import type { EVMChainType, PaymentError } from '../store/models/types';
 import { EVM_CHAIN_TYPES } from '../libs/constants';
 
@@ -111,6 +115,45 @@ export const handleRefund = async (job: RefundJob) => {
   }
 };
 
+/**
+ * Finalize refund after transfer succeeds
+ * For credit purchase refunds: set processing -> burn credit -> set succeeded/failed
+ * For other types: directly set succeeded
+ */
+async function finalizeRefundAfterTransfer(refund: Refund, paymentDetails: any): Promise<void> {
+  try {
+    // Try to burn credit tokens if this refund is for a credit purchase
+    const totalBurned = await handleOnchainCreditRefund(refund);
+
+    // All succeeded, update status
+    await refund.update({
+      status: 'succeeded',
+      last_attempt_error: null,
+      payment_details: paymentDetails,
+    });
+    logger.info('Refund succeeded', {
+      id: refund.id,
+      totalBurned,
+      hasCreditBurn: !!totalBurned && totalBurned !== '0',
+    });
+  } catch (error: any) {
+    // Burn failed, set processing status and record error
+    await refund.update({
+      status: 'processing',
+      payment_details: paymentDetails,
+      last_attempt_error: {
+        type: 'credit_burn_error',
+        code: 'BURN_FAILED',
+        message: error.message || 'Failed to burn credit tokens',
+      },
+    });
+    logger.error('Credit burn failed, refund set to processing', {
+      id: refund.id,
+      error: error.message,
+    });
+  }
+}
+
 const handleRefundJob = async (
   job: RefundJob,
   refund: Refund,
@@ -170,18 +213,13 @@ const handleRefundJob = async (
       const txHash = await client.sendTransferV2Tx({ tx: signed, wallet }, await getGasPayerExtra(buffer));
 
       logger.info('refund transfer done', { id: refund.id, txHash });
-      await refund.update({
-        status: 'succeeded',
-        last_attempt_error: null,
-        payment_details: {
-          arcblock: {
-            tx_hash: txHash,
-            payer: wallet.address,
-            type: 'transfer',
-          },
+      await finalizeRefundAfterTransfer(refund, {
+        arcblock: {
+          tx_hash: txHash,
+          payer: wallet.address,
+          type: 'transfer',
         },
       });
-      logger.info('Refund status updated to succeeded', { id: refund.id, txHash });
     }
 
     if (EVM_CHAIN_TYPES.includes(paymentMethod.type)) {
@@ -203,18 +241,14 @@ const handleRefundJob = async (
       const receipt = await sendErc20ToUser(client, paymentCurrency.contract, payer, refund.amount);
       logger.info('refund transfer done', { id: refund.id, txHash: receipt.hash });
 
-      await refund.update({
-        status: 'succeeded',
-        last_attempt_error: null,
-        payment_details: {
-          [paymentType]: {
-            tx_hash: receipt.hash,
-            payer: wallet.address,
-            block_height: receipt.blockNumber.toString(),
-            gas_used: receipt.gasUsed.toString(),
-            gas_price: receipt.gasPrice.toString(),
-            type: 'transfer',
-          },
+      await finalizeRefundAfterTransfer(refund, {
+        [paymentType]: {
+          tx_hash: receipt.hash,
+          payer: wallet.address,
+          block_height: receipt.blockNumber.toString(),
+          gas_used: receipt.gasUsed.toString(),
+          gas_price: receipt.gasPrice.toString(),
+          type: 'transfer',
         },
       });
     }
@@ -243,14 +277,10 @@ const handleRefundJob = async (
         ...(isRefundReasonSupportedByStripe(refund.reason) ? { reason: refund.reason } : {}),
       });
       if (stripeRefund.status === 'succeeded') {
-        await refund.update({
-          status: 'succeeded',
-          last_attempt_error: null,
-          payment_details: {
-            stripe: {
-              payment_intent_id: stripePaymentIntentId,
-              refund_id: stripeRefund.id,
-            },
+        await finalizeRefundAfterTransfer(refund, {
+          stripe: {
+            payment_intent_id: stripePaymentIntentId,
+            refund_id: stripeRefund.id,
           },
         });
       }
@@ -441,3 +471,206 @@ events.on('refund.created', (refund: Refund) => {
   logger.info('schedule refund', { id: refund.id });
   refundQueue.push({ id: refund.id, job: { refundId: refund.id } });
 });
+
+/**
+ * Handle onchain credit refund - burn user-held tokens for credit grants
+ *
+ * When a refund is issued for a credit purchase:
+ * 1. Find credit grants associated with the invoice
+ * 2. For each grant, check if its currency is an onchain credit
+ * 3. Calculate how much to burn based on refund amount
+ * 4. Only burn user-held tokens (remaining_amount in user's wallet)
+ * 5. If user has consumed some credit, only burn what they have left
+ *    (the consumed portion stays in system wallet as it corresponds to used services)
+ * 6. Update credit grant status
+ *
+ * @param refund - The refund record
+ * @param paymentDetails - Payment details to update on refund
+ * @returns Total amount burned (as string), '0' if nothing to burn
+ * @throws Error if burn operation fails
+ */
+/**
+ * Handle onchain credit refund - burn user-held tokens for credit grants
+ *
+ * @param refund - The refund record
+ * @returns Total amount burned (as string), undefined if nothing to burn
+ * @throws Error if burn operation fails
+ */
+export async function handleOnchainCreditRefund(refund: Refund): Promise<string | undefined> {
+  logger.info('Processing onchain credit refund', { refundId: refund.id, invoiceId: refund.invoice_id });
+
+  // If no invoice_id, no credit grants to burn
+  if (!refund.invoice_id) {
+    return undefined;
+  }
+
+  const invoice = await Invoice.findByPk(refund.invoice_id);
+  const customer = await Customer.findByPk(refund.customer_id);
+
+  if (!invoice || !customer?.did) {
+    throw new Error('Invoice or customer not found for refund');
+  }
+
+  const invoiceTotal = new BN(invoice.total || '0');
+  if (invoiceTotal.lte(new BN(0))) {
+    throw new Error(`Invoice ${refund.invoice_id} total is zero or negative`);
+  }
+
+  // Find ALL credit grants related to this invoice (not filtered by currency_id)
+  const allGrants = await CreditGrant.findAll({
+    where: {
+      customer_id: refund.customer_id,
+      status: ['pending', 'granted'],
+    },
+  });
+  const creditGrants = allGrants.filter(
+    (grant) => grant.metadata?.invoice_id === refund.invoice_id && CreditGrant.hasOnchainToken(grant)
+  );
+
+  if (creditGrants.length === 0) {
+    logger.info('No active credit grants found for refund', { refundId: refund.id, invoiceId: refund.invoice_id });
+    return undefined;
+  }
+
+  logger.info('Found credit grants to process for refund', {
+    refundId: refund.id,
+    creditGrantCount: creditGrants.length,
+    invoiceTotal: invoice.total,
+    refundAmount: refund.amount,
+  });
+
+  const refundAmount = new BN(refund.amount);
+  let totalBurnedFromUser = new BN(0);
+  let lastError: string | null = null;
+
+  // Process each credit grant
+  // eslint-disable-next-line no-restricted-syntax
+  for (const creditGrant of creditGrants) {
+    // Get the currency for THIS grant
+    // eslint-disable-next-line no-await-in-loop
+    const grantCurrency = await PaymentCurrency.findByPk(creditGrant.currency_id);
+
+    // Verify currency has token config for burn operation
+    if (!grantCurrency?.token_config) {
+      logger.error('Payment currency token config not found for burn', {
+        creditGrantId: creditGrant.id,
+        currencyId: creditGrant.currency_id,
+      });
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
+    const grantTotalAmount = new BN(creditGrant.amount);
+    const grantRemainingAmount = new BN(creditGrant.remaining_amount || '0');
+
+    // Calculate how much credit should be burned from this grant based on refund ratio
+    // shouldBurnFromGrant = grantTotalAmount × refundAmount / invoiceTotal (multiply first to avoid precision loss)
+    const shouldBurnFromGrant = grantTotalAmount.mul(refundAmount).div(invoiceTotal);
+
+    // Actual burn is limited by what user actually has in their wallet
+    const actualBurnAmount = BN.min(shouldBurnFromGrant, grantRemainingAmount);
+    // The difference (if any) is consumed credit that stays in system wallet
+    const systemRetainedAmount = shouldBurnFromGrant.sub(actualBurnAmount);
+
+    logger.info('Processing credit grant for refund', {
+      creditGrantId: creditGrant.id,
+      currencyId: grantCurrency.id,
+      grantTotal: grantTotalAmount.toString(),
+      grantRemaining: grantRemainingAmount.toString(),
+      shouldBurn: shouldBurnFromGrant.toString(),
+      willBurnFromUser: actualBurnAmount.toString(),
+      systemRetained: systemRetainedAmount.toString(),
+    });
+
+    let burnHash: string | null = null;
+    let burnError: string | null = null;
+
+    // Only burn if user has remaining tokens
+    if (actualBurnAmount.gt(new BN(0))) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        burnHash = await burnToken({
+          paymentCurrency: grantCurrency,
+          amount: fromUnitToToken(actualBurnAmount.toString(), grantCurrency.decimal),
+          sender: customer.did,
+          data: {
+            reason: 'credit_grant_refund',
+            creditGrantId: creditGrant.id,
+            refundId: refund.id,
+          },
+        });
+
+        totalBurnedFromUser = totalBurnedFromUser.add(actualBurnAmount);
+
+        logger.info('Successfully burned user tokens for refund', {
+          creditGrantId: creditGrant.id,
+          burnHash,
+          amount: actualBurnAmount.toString(),
+        });
+
+        // Emit burned event to trigger reconciliation
+        events.emit('customer.credit_grant.burned', creditGrant, {
+          burnHash,
+          burnedAmount: actualBurnAmount.toString(),
+        });
+      } catch (error: any) {
+        logger.error('Failed to burn user tokens for refund', {
+          creditGrantId: creditGrant.id,
+          refundId: refund.id,
+          error: error.message,
+        });
+        burnError = error.message;
+        lastError = error.message;
+      }
+    }
+
+    // Update credit grant using new chain_detail field
+    const newRemainingAmount = burnHash
+      ? grantRemainingAmount.sub(actualBurnAmount).toString()
+      : grantRemainingAmount.toString();
+    const isFullyVoided = new BN(newRemainingAmount).eq(new BN(0));
+    const chainDetail = creditGrant.chain_detail || {};
+
+    // eslint-disable-next-line no-await-in-loop
+    await creditGrant.update({
+      status: isFullyVoided ? 'voided' : 'granted',
+      remaining_amount: newRemainingAmount,
+      voided_at: isFullyVoided ? Math.floor(Date.now() / 1000) : undefined,
+      // eslint-disable-next-line no-nested-ternary
+      chain_status: burnHash ? 'burn_completed' : burnError ? 'burn_failed' : undefined,
+      chain_detail: {
+        ...chainDetail,
+        refund: {
+          id: refund.id,
+          burn_hash: burnHash || undefined,
+          burned_amount: burnHash ? actualBurnAmount.toString() : '0',
+          system_retained: systemRetainedAmount.toString(),
+          burn_error: burnError || undefined,
+        },
+        ...(isFullyVoided ? { voided_reason: 'refund' } : {}),
+      },
+    });
+
+    logger.info('Credit grant processed for refund', {
+      creditGrantId: creditGrant.id,
+      newStatus: isFullyVoided ? 'voided' : 'granted',
+      newRemainingAmount,
+      burnedFromUser: burnHash ? actualBurnAmount.toString() : '0',
+      systemRetained: systemRetainedAmount.toString(),
+    });
+  }
+
+  logger.info('Completed onchain credit refund processing', {
+    refundId: refund.id,
+    processedCount: creditGrants.length,
+    totalBurnedFromUser: totalBurnedFromUser.toString(),
+    refundAmount: refund.amount,
+    hasError: !!lastError,
+  });
+
+  if (lastError) {
+    throw new Error(lastError);
+  }
+
+  return totalBurnedFromUser.toString();
+}