payment-kit 1.22.32 → 1.23.0

package/api/src/queues/token-transfer.ts

@@ -0,0 +1,331 @@
+import { BN } from '@ocap/util';
+import logger from '../libs/logger';
+import createQueue from '../libs/queue';
+import { transferTokenFromCustomer, getCustomerTokenBalance } from '../integrations/arcblock/token';
+import { CreditTransaction, CreditGrant, Customer, MeterEvent, PaymentCurrency, Subscription } from '../store/models';
+
+type TokenTransferJob = {
+  creditTransactionId: string;
+  creditGrantId: string;
+  customerDid: string;
+  amount: string;
+  paymentCurrencyId: string;
+  meterEventId: string;
+  subscriptionId?: string;
+};
+
+type ValidationResult =
+  | { valid: false }
+  | {
+      valid: true;
+      creditTransaction: CreditTransaction;
+      creditGrant: CreditGrant;
+      customer: Customer;
+      paymentCurrency: PaymentCurrency;
+      meterEvent: MeterEvent;
+      subscription?: Subscription;
+    };
+
+/**
+ * Validate transfer job and fetch required data
+ */
+async function validateAndFetchData(job: TokenTransferJob): Promise<ValidationResult> {
+  const creditTransaction = await CreditTransaction.findByPk(job.creditTransactionId);
+  if (!creditTransaction) {
+    logger.warn('CreditTransaction not found', { creditTransactionId: job.creditTransactionId });
+    return { valid: false };
+  }
+
+  // Check if already transferred
+  if (creditTransaction.transfer_status === 'completed') {
+    logger.info('Token transfer already completed', { creditTransactionId: job.creditTransactionId });
+    return { valid: false };
+  }
+
+  const creditGrant = await CreditGrant.findByPk(job.creditGrantId);
+  if (!creditGrant) {
+    logger.warn('CreditGrant not found', { creditGrantId: job.creditGrantId });
+    return { valid: false };
+  }
+
+  const customer = await Customer.findByPkOrDid(job.customerDid);
+  if (!customer) {
+    logger.warn('Customer not found', { customerDid: job.customerDid });
+    return { valid: false };
+  }
+
+  const paymentCurrency = await PaymentCurrency.findByPk(job.paymentCurrencyId);
+  if (!paymentCurrency) {
+    logger.warn('PaymentCurrency not found', { paymentCurrencyId: job.paymentCurrencyId });
+    return { valid: false };
+  }
+
+  const meterEvent = await MeterEvent.findByPk(job.meterEventId);
+  if (!meterEvent) {
+    logger.warn('MeterEvent not found', { meterEventId: job.meterEventId });
+    return { valid: false };
+  }
+
+  let subscription: Subscription | undefined;
+  if (job.subscriptionId) {
+    subscription = (await Subscription.findByPk(job.subscriptionId)) || undefined;
+  }
+
+  return {
+    valid: true,
+    creditTransaction,
+    creditGrant,
+    customer,
+    paymentCurrency,
+    meterEvent,
+    subscription,
+  };
+}
+
+/**
+ * Handle token transfer job
+ */
+export async function handleTokenTransfer(job: TokenTransferJob): Promise<void> {
+  logger.info('Starting token transfer job', {
+    creditTransactionId: job.creditTransactionId,
+    creditGrantId: job.creditGrantId,
+    customerDid: job.customerDid,
+    amount: job.amount,
+  });
+
+  const validation = await validateAndFetchData(job);
+  if (!validation.valid) {
+    logger.warn('Token transfer validation failed, skipping', { job });
+    return;
+  }
+
+  const { creditTransaction, creditGrant, customer, paymentCurrency, meterEvent } = validation;
+
+  let txHash: string | null = null;
+  // Record partial transfer details when chain balance is insufficient
+  let transferResult: { expected: string; actual: string } | null = null;
+
+  try {
+    // Attempt token transfer
+    txHash = await transferTokenFromCustomer({
+      paymentCurrency,
+      customerDid: customer.did,
+      amount: job.amount,
+      data: {
+        reason: 'credit_consumption',
+        creditGrantId: creditGrant.id,
+        meterEventId: meterEvent.id,
+      },
+    });
+
+    logger.info('Token transfer completed successfully', {
+      creditTransactionId: creditTransaction.id,
+      txHash,
+      from: customer.did,
+      amount: job.amount,
+      currency: paymentCurrency.symbol,
+    });
+  } catch (error: any) {
+    const isInsufficientBalanceError =
+      error?.message?.includes('does not have enough token') || error?.message?.includes('INSUFFICIENT_TOKEN_BALANCE');
+
+    if (!isInsufficientBalanceError) {
+      logger.error('Token transfer failed', {
+        error,
+        creditTransactionId: creditTransaction.id,
+        customerDid: customer.did,
+        amount: job.amount,
+      });
+      throw error;
+    }
+
+    // Handle insufficient balance: transfer whatever we can and mark as completed
+    logger.warn('Insufficient chain balance detected', {
+      creditTransactionId: creditTransaction.id,
+      requestedAmount: job.amount,
+      error,
+    });
+
+    // Get actual chain balance
+    const chainBalance = await getCustomerTokenBalance(customer.did, paymentCurrency);
+    const chainBalanceBN = new BN(chainBalance);
+    const expectBalanceBN = new BN(job.amount);
+    const chainDebt = expectBalanceBN.sub(chainBalanceBN);
+    const transferAmount = BN.min(chainBalanceBN, expectBalanceBN);
+
+    // Record transfer result for metadata (only when partial)
+    if (chainDebt.gt(new BN(0))) {
+      transferResult = {
+        expected: job.amount,
+        actual: transferAmount.toString(),
+      };
+    }
+
+    if (chainBalanceBN.lt(expectBalanceBN)) {
+      logger.error('CRITICAL: Chain balance is less than requested amount', {
+        creditTransactionId: creditTransaction.id,
+        chainBalance: chainBalance.toString(),
+        requestedAmount: job.amount,
+        chainDebt: chainDebt.toString(),
+      });
+    }
+
+    // Transfer tokens if there is any balance
+    if (chainBalanceBN.gt(new BN(0))) {
+      txHash = await transferTokenFromCustomer({
+        paymentCurrency,
+        customerDid: customer.did,
+        amount: transferAmount.toString(),
+        data: {
+          reason: 'credit_consumption',
+          creditGrantId: creditGrant.id,
+          meterEventId: meterEvent.id,
+        },
+      });
+
+      logger.warn('Partial token transfer completed - chain balance insufficient', {
+        creditTransactionId: creditTransaction.id,
+        customerDid: customer.did,
+        currencyId: paymentCurrency.id,
+        actualBalance: chainBalanceBN.toString(),
+        expectedAmount: expectBalanceBN.toString(),
+        transferredAmount: transferAmount.toString(),
+        chainDebt: chainDebt.toString(),
+      });
+    } else {
+      logger.error('Zero chain balance - no tokens transferred', {
+        creditTransactionId: creditTransaction.id,
+        customerDid: customer.did,
+        currencyId: paymentCurrency.id,
+        expectedAmount: expectBalanceBN.toString(),
+      });
+    }
+  }
+
+  // Update transaction with result
+  await creditTransaction.update({
+    transfer_status: 'completed',
+    transfer_hash: txHash ?? undefined,
+    ...(transferResult && {
+      metadata: {
+        ...(creditTransaction.metadata || {}),
+        transfer_result: transferResult,
+      },
+    }),
+  });
+}
+
+/**
+ * Token transfer queue
+ */
+export const tokenTransferQueue = createQueue<TokenTransferJob>({
+  name: 'token-transfer',
+  onJob: handleTokenTransfer,
+  options: {
+    concurrency: 5,
+    maxRetries: 3,
+    retryDelay: 5000,
+  },
+});
+
+tokenTransferQueue.on('finished', ({ id, job }) => {
+  logger.debug('Token transfer job finished', { id, creditTransactionId: job.creditTransactionId });
+});
+
+tokenTransferQueue.on('failed', async ({ id, job, error }) => {
+  logger.error('Token transfer job failed after all retries', { id, job, error: error.message });
+
+  const creditTransaction = await CreditTransaction.findByPk(job.creditTransactionId);
+
+  if (creditTransaction && creditTransaction.transfer_status !== 'completed') {
+    await creditTransaction.update({
+      transfer_status: 'failed',
+    });
+  }
+});
+
+tokenTransferQueue.on('retry', ({ id, job }) => {
+  logger.info('Token transfer job retry scheduled', {
+    id,
+    creditTransactionId: job.creditTransactionId,
+  });
+});
+
+/**
+ * Add token transfer job to queue
+ */
+export async function addTokenTransferJob(job: TokenTransferJob): Promise<void> {
+  const jobId = `token-transfer-${job.creditTransactionId}`;
+
+  try {
+    // Check if job already exists
+    const existingJob = await tokenTransferQueue.get(jobId);
+    if (existingJob) {
+      logger.debug('Token transfer job already exists', { jobId, creditTransactionId: job.creditTransactionId });
+      return;
+    }
+
+    // Add job to queue
+    await tokenTransferQueue.push({ id: jobId, job });
+
+    logger.info('Token transfer job added to queue', {
+      jobId,
+      creditTransactionId: job.creditTransactionId,
+      customerDid: job.customerDid,
+      amount: job.amount,
+    });
+  } catch (error: any) {
+    logger.error('Failed to add token transfer job', {
+      jobId,
+      creditTransactionId: job.creditTransactionId,
+      error,
+    });
+  }
+}
+
+/**
+ * Start token transfer queue
+ */
+export async function startTokenTransferQueue(): Promise<void> {
+  try {
+    logger.info('Token transfer queue started');
+
+    // Process any pending transfers on startup
+    const pendingTransactions = await CreditTransaction.findAll({
+      where: {
+        transfer_status: 'pending',
+      },
+      limit: 100,
+      order: [['created_at', 'DESC']],
+    });
+
+    logger.info('Found pending token transfers to process', { count: pendingTransactions.length });
+
+    // Process in batches to add jobs
+    await Promise.all(
+      pendingTransactions.map(async (transaction) => {
+        try {
+          const customer = (await Customer.findByPk(transaction.customer_id))!;
+          const creditGrant = (await CreditGrant.findByPk(transaction.credit_grant_id))!;
+
+          await addTokenTransferJob({
+            creditTransactionId: transaction.id,
+            creditGrantId: transaction.credit_grant_id,
+            customerDid: customer.did,
+            amount: transaction.credit_amount,
+            paymentCurrencyId: creditGrant.currency_id,
+            meterEventId: transaction.source!,
+            subscriptionId: transaction.subscription_id || undefined,
+          });
+        } catch (error: any) {
+          logger.error('Failed to add pending transfer job', {
+            transactionId: transaction.id,
+            error: error.message,
+          });
+        }
+      })
+    );
+  } catch (error: any) {
+    logger.error('Failed to start token transfer queue', { error: error.message });
+  }
+}

package/api/src/routes/checkout-sessions.ts

@@ -2036,7 +2036,7 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
   } catch (err) {
     logger.error('Error submitting checkout session', {
       sessionId: req.params.id,
-      error: err.message,
+      error: err,
       stack: err.stack,
     });
     res.status(500).json({ code: err.code, error: err.message });

package/api/src/routes/credit-grants.ts

@@ -19,6 +19,7 @@ import {
   Subscription,
 } from '../store/models';
 import { createCreditGrant } from '../libs/credit-grant';
+import { expireGrant } from '../queues/credit-grant';
 import { getMeterPriceIdsFromSubscription } from '../libs/subscription';
 import { blocklet } from '../libs/auth';
 import { formatMetadata } from '../libs/util';
@@ -455,8 +456,9 @@ router.post('/', auth, async (req, res) => {
   }
 });
 
-const updateMetadataSchema = Joi.object({
+const updateSchema = Joi.object({
   metadata: MetadataSchema,
+  expired: Joi.boolean().optional(),
 });
 
 router.put('/:id', auth, async (req, res) => {
@@ -464,17 +466,35 @@ router.put('/:id', auth, async (req, res) => {
   if (!creditGrant) {
     return res.status(404).json({ error: `Credit grant ${req.params.id} not found` });
   }
-  const { error } = updateMetadataSchema.validate(pick(req.body, 'metadata'));
+
+  const { error, value } = updateSchema.validate(pick(req.body, ['metadata', 'expired']), { stripUnknown: true });
   if (error) {
     return res.status(400).json({ error: `Credit grant update request invalid: ${error.message}` });
   }
-  if (req.body.metadata) {
-    const { error: metadataError } = MetadataSchema.validate(req.body.metadata);
-    if (metadataError) {
-      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+
+  // Handle metadata update
+  if (value.metadata !== undefined) {
+    await creditGrant.update({ metadata: formatMetadata(value.metadata) });
+  }
+
+  // Handle expire operation first (before metadata update)
+  if (value.expired === true) {
+    // Only pending or granted grants can be expired
+    if (!['pending', 'granted'].includes(creditGrant.status)) {
+      return res.status(400).json({
+        error: `Cannot expire credit grant with status '${creditGrant.status}'. Only 'pending' or 'granted' grants can be expired.`,
+      });
     }
+
+    await expireGrant(creditGrant);
+
+    logger.info('Credit grant manually expired', {
+      creditGrantId: req.params.id,
+      previousStatus: creditGrant.status,
+      requestedBy: req.user?.did,
+    });
   }
-  await creditGrant.update({ metadata: formatMetadata(req.body.metadata) });
+
   return res.json({ success: true });
 });
 

package/api/src/routes/credit-tokens.ts

@@ -0,0 +1,38 @@
+import { Router } from 'express';
+import Joi from 'joi';
+
+import logger from '../libs/logger';
+import { authenticate } from '../libs/security';
+import { createToken } from '../integrations/arcblock/token';
+
+const router = Router();
+const auth = authenticate({ component: true, roles: ['owner', 'admin'] });
+
+const createTokenSchema = Joi.object({
+  name: Joi.string().max(64).required(),
+  symbol: Joi.string().max(16).required(),
+  decimal: Joi.number().integer().min(2).max(18).default(10),
+}).unknown(true);
+
+router.post('/', auth, async (req, res) => {
+  try {
+    const { error } = createTokenSchema.validate(req.body);
+    if (error) {
+      return res.status(400).json({ error: `Token create request invalid: ${error.message}` });
+    }
+
+    const tokenFactoryState = await createToken({
+      name: req.body.name,
+      symbol: req.body.symbol,
+      decimal: req.body.decimal,
+      livemode: !!req.livemode,
+    });
+
+    return res.json(tokenFactoryState);
+  } catch (err) {
+    logger.error('create credit token failed', { error: err?.message, request: req.body });
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
+export default router;

package/api/src/routes/index.ts

@@ -5,6 +5,7 @@ import autoRechargeConfigs from './auto-recharge-configs';
 import checkoutSessions from './checkout-sessions';
 import coupons from './coupons';
 import creditGrants from './credit-grants';
+import creditTokens from './credit-tokens';
 import creditTransactions from './credit-transactions';
 import customers from './customers';
 import donations from './donations';
@@ -61,6 +62,7 @@ router.use('/auto-recharge-configs', autoRechargeConfigs);
 router.use('/checkout-sessions', checkoutSessions);
 router.use('/coupons', coupons);
 router.use('/credit-grants', creditGrants);
+router.use('/credit-tokens', creditTokens);
 router.use('/credit-transactions', creditTransactions);
 router.use('/customers', customers);
 router.use('/donations', donations);

package/api/src/routes/meters.ts

@@ -18,9 +18,13 @@ const meterSchema = Joi.object({
   aggregation_method: Joi.string().valid('sum', 'count', 'last').default('sum'),
   unit: Joi.string().max(32).required(),
   currency_id: Joi.string().max(40).optional(),
+  decimal: Joi.number().integer().min(2).max(18).default(10),
   description: Joi.string().max(255).allow('').optional(),
   metadata: MetadataSchema,
   component_did: Joi.string().max(40).optional(),
+  token: Joi.object({
+    tokenFactoryAddress: Joi.string().required(),
+  }).optional(),
 }).unknown(true);
 
 const updateMeterSchema = Joi.object({
@@ -78,6 +82,32 @@ router.post('/', auth, async (req, res) => {
       return res.status(400).json({ error: 'Aggregation method is not supported' });
     }
 
+    const needArcblockMethod = req.body.token?.tokenFactoryAddress || !req.body.currency_id;
+    const arcblockMethod = needArcblockMethod
+      ? await PaymentMethod.findOne({ where: { livemode: !!req.livemode, type: 'arcblock' } })
+      : null;
+    if (needArcblockMethod && !arcblockMethod) {
+      throw new Error('ArcBlock payment method not found');
+    }
+
+    let tokenConfig: Record<string, any> | undefined;
+    if (req.body.token?.tokenFactoryAddress) {
+      const client = arcblockMethod!.getOcapClient();
+      const { state: tokenFactoryState } = await client.getTokenFactoryState({
+        address: req.body.token.tokenFactoryAddress,
+      });
+      if (!tokenFactoryState) {
+        return res.status(400).json({ error: 'Token factory not found on chain' });
+      }
+      tokenConfig = {
+        address: tokenFactoryState.token.address,
+        symbol: tokenFactoryState.token.symbol,
+        name: tokenFactoryState.token.name,
+        decimal: tokenFactoryState.token.decimal,
+        token_factory_address: tokenFactoryState.address,
+      };
+    }
+
     const meterData = {
       ...pick(req.body, ['name', 'event_name', 'aggregation_method', 'unit', 'currency_id', 'description', 'metadata']),
       livemode: !!req.livemode,
@@ -87,17 +117,9 @@ router.post('/', auth, async (req, res) => {
     };
 
     if (!meterData.currency_id) {
-      const paymentMethod = await PaymentMethod.findOne({
-        where: {
-          livemode: !!req.livemode,
-          type: 'arcblock',
-        },
+      const paymentCurrency = await PaymentCurrency.createForMeter(meterData, arcblockMethod!.id, tokenConfig, {
+        decimal: req.body.decimal,
       });
-      if (!paymentMethod) {
-        return res.status(400).json({ error: 'Payment method not found' });
-      }
-
-      const paymentCurrency = await PaymentCurrency.createForMeter(meterData, paymentMethod.id);
       meterData.currency_id = paymentCurrency.id;
     }
 

package/api/src/routes/payment-currencies.ts

@@ -351,6 +351,109 @@ router.put('/:id', auth, async (req, res) => {
   return res.json(updatedCurrency);
 });
 
+const tokenConfigSchema = Joi.object({
+  token_factory_address: Joi.string().required(),
+});
+
+router.put('/:id/token-config', auth, async (req, res) => {
+  try {
+    const { id } = req.params;
+
+    const { error, value } = tokenConfigSchema.validate(req.body);
+    if (error) {
+      return res.status(400).json({ error: error.message });
+    }
+
+    const currency = await PaymentCurrency.findByPk(id);
+    if (!currency) {
+      return res.status(404).json({ error: 'Payment currency not found' });
+    }
+
+    if (currency.type !== 'credit') {
+      return res.status(400).json({ error: 'Only credit currencies can have token_config' });
+    }
+
+    if (currency.token_config) {
+      return res.status(400).json({ error: 'Token config already exists. Cannot be updated once set.' });
+    }
+
+    const paymentMethod = await PaymentMethod.findOne({
+      where: {
+        livemode: currency.livemode,
+        type: 'arcblock',
+      },
+    });
+
+    if (!paymentMethod) {
+      return res.status(400).json({ error: 'ArcBlock payment method not found' });
+    }
+
+    const client = paymentMethod.getOcapClient();
+    const { state: tokenFactoryState } = await client.getTokenFactoryState({
+      address: value.token_factory_address,
+    });
+
+    if (!tokenFactoryState) {
+      return res.status(400).json({ error: 'Token factory not found on chain' });
+    }
+
+    const tokenConfig = {
+      address: tokenFactoryState.token.address,
+      symbol: tokenFactoryState.token.symbol,
+      name: tokenFactoryState.token.name,
+      decimal: tokenFactoryState.token.decimal,
+      token_factory_address: tokenFactoryState.address,
+    };
+
+    // Only update token_config, keep the original decimal to avoid breaking existing credit grants
+    await currency.update({
+      token_config: tokenConfig,
+    });
+
+    logger.info('Payment currency token_config updated', {
+      currencyId: id,
+      tokenConfig,
+    });
+
+    return res.json(currency.toJSON());
+  } catch (err) {
+    logger.error('update payment currency token_config failed', { error: err?.message, id: req.params.id });
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
+router.delete('/:id/token-config', auth, async (req, res) => {
+  try {
+    const { id } = req.params;
+
+    const currency = await PaymentCurrency.findByPk(id);
+    if (!currency) {
+      return res.status(404).json({ error: 'Payment currency not found' });
+    }
+
+    if (currency.type !== 'credit') {
+      return res.status(400).json({ error: 'Only credit currencies can have token_config' });
+    }
+
+    if (!currency.token_config) {
+      return res.status(400).json({ error: 'Token config does not exist' });
+    }
+
+    await currency.update({
+      token_config: null,
+    });
+
+    logger.info('Payment currency token_config removed', {
+      currencyId: id,
+    });
+
+    return res.json(currency.toJSON());
+  } catch (err) {
+    logger.error('delete payment currency token_config failed', { error: err?.message, id: req.params.id });
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
 router.delete('/:id', auth, async (req, res) => {
   const { id } = req.params;
 

package/api/src/routes/products.ts

@@ -37,7 +37,7 @@ const ProductAndPriceSchema = Joi.object({
   description: Joi.string().max(250).empty('').optional(),
   images: Joi.any().optional(),
   metadata: MetadataSchema,
-  tax_code: Joi.string().max(30).empty('').optional(),
+  tax_code: Joi.string().max(30).allow(null).empty('').optional(),
   statement_descriptor: Joi.string()
     .max(22)
     .pattern(/^(?=.*[A-Za-z])[^\u4e00-\u9fa5<>"’\\]*$/)
@@ -48,7 +48,7 @@ const ProductAndPriceSchema = Joi.object({
     .allow(null, '')
     .empty('')
     .optional(),
-  unit_label: Joi.string().max(12).empty('').optional(),
+  unit_label: Joi.string().max(12).allow(null).empty('').optional(),
   nft_factory: Joi.string().max(40).allow(null).empty('').optional(),
   features: Joi.array()
     .items(Joi.object({ name: Joi.string().max(64).empty('').optional() }).unknown(true))

package/api/src/routes/settings.ts

@@ -31,9 +31,10 @@ router.get('/', async (req, res) => {
   });
 
   res.json({
-    paymentMethods: methods.map((x) =>
-      pick(x, ['id', 'name', 'type', 'logo', 'payment_currencies', 'default_currency_id', 'maximum_precision'])
-    ),
+    paymentMethods: methods.map((x) => ({
+      ...pick(x, ['id', 'name', 'type', 'logo', 'payment_currencies', 'default_currency_id', 'maximum_precision']),
+      api_host: x.settings?.arcblock?.api_host,
+    })),
     baseCurrency: await PaymentCurrency.findOne({
       where: { is_base_currency: true, livemode: req.livemode },
       attributes,

package/api/src/store/migrations/20251120-add-token-config-to-currencies.ts

@@ -0,0 +1,20 @@
+import { DataTypes } from 'sequelize';
+import { safeApplyColumnChanges, type Migration } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  await safeApplyColumnChanges(context, {
+    payment_currencies: [
+      {
+        name: 'token_config',
+        field: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeColumn('payment_currencies', 'token_config');
+};