payment-kit 1.25.0 → 1.25.2

package/api/src/integrations/arcblock/stake.ts

@@ -13,6 +13,7 @@ import logger from '../../libs/logger';
 import { Customer, GroupedBN, PaymentCurrency, PaymentMethod, Subscription } from '../../store/models';
 import { fetchErc20Balance, fetchEtherBalance } from '../ethereum/token';
 import { EVM_CHAIN_TYPES } from '../../libs/constants';
+import { getAppStakeAddressWithFallback, getMigratedFromList } from '../../libs/wallet-migration';
 
 export async function ensureStakedForGas() {
   const currencies = await PaymentCurrency.findAll({ where: { active: true, is_base_currency: true } });
@@ -26,10 +27,10 @@ export async function ensureStakedForGas() {
       try {
         const { state: account } = await client.getAccountState({ address: wallet.address });
 
-        const address = toStakeAddress(wallet.address, wallet.address);
-        const { state: stake } = await client.getStakeState({ address });
-        if (stake) {
-          logger.info(`app already staked for gas on chain ${host}`);
+        // Use migration-aware fallback to check if app has staked for gas
+        const stakeResult = await getAppStakeAddressWithFallback({ client });
+        if (stakeResult) {
+          logger.info(`app already staked for gas on chain ${host}`, { source: stakeResult.source });
           continue;
         }
 
@@ -59,6 +60,14 @@ export async function ensureStakedForGas() {
 export async function hasStakedForGas(method: PaymentMethod, sender = wallet.address) {
   if (method.type === 'arcblock') {
     const client = method.getOcapClient();
+
+    // If checking app's own stake, use migration-aware fallback
+    if (sender === wallet.address) {
+      const stakeResult = await getAppStakeAddressWithFallback({ client });
+      return !!stakeResult;
+    }
+
+    // For other senders, use direct query
     const address = toStakeAddress(sender, sender);
     const { state } = await client.getStakeState({ address });
     return !!state;
@@ -195,23 +204,32 @@ export async function getStakeSummaryByDid(did: string, livemode: boolean = true
   await Promise.all(
     methods.map(async (method: PaymentMethod) => {
       const client = method.getOcapClient();
-      const { stakes } = await client.listStakes({
-        addressFilter: {
-          receiver: wallet.address,
-        },
-      });
-      (stakes || [])
-        .filter((x: any) => x.sender === did)
-        .forEach((x: any) => {
-          const { tokens } = x;
-          (tokens || []).forEach((t: any) => {
-            // @ts-ignore
-            const currency = method.payment_currencies?.find((c: PaymentCurrency) => t.address === c.contract);
-            if (currency) {
-              results[currency.id] = new BN(results[currency.id] || '0').add(new BN(t.balance || '0')).toString();
-            }
-          });
+
+      // Get all possible receiver addresses (current + migratedFrom) for migration compatibility
+      const migratedFrom = await getMigratedFromList(client);
+      const receiverAddresses = [...new Set([wallet.address, ...migratedFrom])];
+
+      // Query stakes for all possible receiver addresses
+      for (const receiver of receiverAddresses) {
+        // eslint-disable-next-line no-await-in-loop
+        const { stakes } = await client.listStakes({
+          addressFilter: {
+            receiver,
+          },
         });
+        (stakes || [])
+          .filter((x: any) => x.sender === did)
+          .forEach((x: any) => {
+            const { tokens } = x;
+            (tokens || []).forEach((t: any) => {
+              // @ts-ignore
+              const currency = method.payment_currencies?.find((c: PaymentCurrency) => t.address === c.contract);
+              if (currency) {
+                results[currency.id] = new BN(results[currency.id] || '0').add(new BN(t.balance || '0')).toString();
+              }
+            });
+          });
+      }
     })
   );
 

package/api/src/libs/payment.ts

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/indent */
 import { isEthereumDid } from '@arcblock/did';
-import { toDelegateAddress } from '@arcblock/did-util';
 import { getWalletDid } from '@blocklet/sdk/lib/did';
 import type { DelegateState, TokenLimit } from '@ocap/client';
 import { toTxHash } from '@ocap/mcrypto';
@@ -20,7 +19,9 @@ import {
   Payout,
   CreditGrant,
   Customer,
+  Subscription,
 } from '../store/models';
+import { getDelegationAddressWithFallback, backfillDelegationAddress, getMigratedFromList } from './wallet-migration';
 import type { TPaymentCurrency } from '../store/models/payment-currency';
 import { blocklet, ethWallet, wallet, getVaultAddress } from './auth';
 import logger from './logger';
@@ -212,8 +213,11 @@ export async function isDelegationSufficientForPayment(args: {
   amount: string;
   delegatorAmounts?: string[];
   lineItems?: TLineItemExpanded[];
+  subscription?: Subscription | null; // Optional subscription for migration fallback
+  storedDelegationAddress?: string; // Direct stored address (for auto-recharge etc.)
 }): Promise<SufficientForPaymentResult> {
-  const { paymentCurrency, paymentMethod, userDid, amount, delegatorAmounts } = args;
+  const { paymentCurrency, paymentMethod, userDid, amount, delegatorAmounts, subscription, storedDelegationAddress } =
+    args;
   if (!userDid) {
     return { sufficient: false, reason: 'NO_DID_WALLET' };
   }
@@ -251,14 +255,32 @@ export async function isDelegationSufficientForPayment(args: {
 
     const client = paymentMethod.getOcapClient();
 
-    // have delegated before?
-    const address = toDelegateAddress(delegator, wallet.address);
+    // 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) {
+      return { sufficient: false, reason: 'NO_DELEGATION' };
+    }
+
+    const { address, needsBackfill, source } = delegationResult;
+
+    // Backfill if needed and subscription is available
+    if (needsBackfill && subscription) {
+      await backfillDelegationAddress(subscription.id, address);
+    }
+
     const { state } = await client.getDelegateState({ address });
     if (!state) {
+      logger.error('isDelegationSufficientForPayment: no delegation state', { address, delegator, source });
       return { sufficient: false, reason: 'NO_DELEGATION' };
     }
 
     if (!state.ops || state.ops?.length === 0) {
+      logger.error('isDelegationSufficientForPayment: no delegation ops', { address, delegator, source });
       return { sufficient: false, reason: 'NO_DELEGATION' };
     }
 
@@ -277,8 +299,14 @@ export async function isDelegationSufficientForPayment(args: {
 
       // FIXME: @wangshijun check other conditions in the token limit: txCount, totalAllowance, validUntil, rateLimit
 
-      if (Array.isArray(tokenLimit.to) && tokenLimit.to.length && tokenLimit.to.includes(wallet.address) === false) {
-        return { sufficient: false, reason: 'NO_TRANSFER_TO' };
+      // Check if tokenLimit.to includes current wallet.address or any migratedFrom addresses
+      if (Array.isArray(tokenLimit.to) && tokenLimit.to.length) {
+        const migratedFrom = await getMigratedFromList(client);
+        const allWalletAddresses = [wallet.address, ...migratedFrom];
+        const hasValidTo = allWalletAddresses.some((addr) => tokenLimit.to.includes(addr));
+        if (!hasValidTo) {
+          return { sufficient: false, reason: 'NO_TRANSFER_TO' };
+        }
       }
 
       // check allowance

package/api/src/libs/session.ts

@@ -35,6 +35,7 @@ import type {
 } from '../store/models/types';
 import { wallet } from './auth';
 import logger from './logger';
+import { getMigratedFromList } from './wallet-migration';
 import { applyDiscountsToLineItems } from './discount/discount';
 import { getQuoteService, QuoteResponse } from './quote-service';
 import { getExchangeRateService } from './exchange-rate';
@@ -443,8 +444,23 @@ export function getMinStakeAmount(config: Record<string, any> = {}) {
   return 0;
 }
 
-export function canPayWithDelegation(beneficiaries: PaymentBeneficiary[]) {
-  return beneficiaries.length === 0 || beneficiaries.every((x) => x.address === wallet.address);
+export async function canPayWithDelegation(
+  beneficiaries: PaymentBeneficiary[],
+  paymentMethod?: PaymentMethod
+): Promise<boolean> {
+  if (beneficiaries.length === 0) {
+    return true;
+  }
+
+  // Get all valid wallet addresses (current + migrated)
+  let allWalletAddresses = [wallet.address];
+  if (paymentMethod?.type === 'arcblock') {
+    const client = paymentMethod.getOcapClient();
+    const migratedFrom = await getMigratedFromList(client);
+    allWalletAddresses = [wallet.address, ...migratedFrom];
+  }
+
+  return beneficiaries.every((x) => allWalletAddresses.includes(x.address));
 }
 
 export function createPaymentBeneficiaries(total: string, beneficiaries: PaymentBeneficiary[]) {

package/api/src/libs/subscription.ts

@@ -37,6 +37,7 @@ import { trimDecimals, limitTokenPrecision } from './math-utils';
 import { getPriceCurrencyOptions, getPriceUintAmountByCurrency } from './price';
 import { getRecurringPeriod, getSubscriptionCreateSetup, SlippageOptions } from './session';
 import { getConnectQueryParam, getCustomerStakeAddress } from './util';
+import { getStakingAddressWithFallback } from './wallet-migration';
 import { wallet } from './auth';
 import { getGasPayerExtra } from './payment';
 import { getLock } from './lock';
@@ -1056,11 +1057,32 @@ export function getSubscriptionTrialSetup(data: Partial<SubscriptionData>, curre
   };
 }
 
-export async function getSubscriptionStakeAddress(subscription: Subscription, customerDid: string) {
-  return (
-    subscription.payment_details?.arcblock?.staking?.address ||
-    (await getCustomerStakeAddress(customerDid, subscription.id))
-  );
+export async function getSubscriptionStakeAddress(
+  subscription: Subscription,
+  customerDid: string,
+  paymentMethod?: PaymentMethod
+) {
+  // If stored address exists, use it
+  const storedAddress = subscription.payment_details?.arcblock?.staking?.address;
+  if (storedAddress) {
+    return storedAddress;
+  }
+
+  // Use migration-aware fallback if paymentMethod is available
+  if (paymentMethod?.type === 'arcblock') {
+    const client = paymentMethod.getOcapClient();
+    const stakingResult = await getStakingAddressWithFallback({
+      userDid: customerDid,
+      nonce: subscription.id,
+      client,
+    });
+    if (stakingResult) {
+      return stakingResult.address;
+    }
+  }
+
+  // Fallback to direct calculation
+  return getCustomerStakeAddress(customerDid, subscription.id);
 }
 
 export async function getSubscriptionStakeCancellation(

package/api/src/libs/wallet-migration.ts

@@ -0,0 +1,317 @@
+/**
+ * Wallet Migration Compatibility
+ *
+ * Provides utilities to handle wallet address changes after app migration.
+ * When an app's DID changes, the derived addresses (delegation, staking) also change,
+ * but user authorizations were made with the old addresses.
+ *
+ * This module provides fallback query mechanisms using migratedFrom list.
+ */
+
+import { toDelegateAddress, toStakeAddress } from '@arcblock/did-util';
+import type OcapClient from '@ocap/client';
+
+import { wallet } from './auth';
+import logger from './logger';
+import { Subscription } from '../store/models';
+
+// Cache for migratedFrom list (refreshed when wallet.address changes)
+let cachedMigratedFrom: string[] | null = null;
+let cachedWalletAddress: string | null = null;
+
+/**
+ * Get the migratedFrom list for the current app wallet (with caching)
+ * The cache is invalidated when wallet.address changes
+ */
+export async function getMigratedFromList(client: OcapClient): Promise<string[]> {
+  // If wallet address hasn't changed, use cached value
+  if (wallet.address === cachedWalletAddress && cachedMigratedFrom !== null) {
+    return cachedMigratedFrom;
+  }
+
+  // Query chain for migratedFrom list
+  try {
+    const { state } = await client.getAccountState({ address: wallet.address });
+    cachedMigratedFrom = state?.migratedFrom || [];
+    cachedWalletAddress = wallet.address;
+
+    if (cachedMigratedFrom.length > 0) {
+      logger.info('wallet-migration: loaded migratedFrom list', {
+        walletAddress: wallet.address,
+        migratedFrom: cachedMigratedFrom,
+      });
+    }
+
+    return cachedMigratedFrom;
+  } catch (err) {
+    logger.error('wallet-migration: failed to get migratedFrom list', { error: err });
+    return [];
+  }
+}
+
+/**
+ * Clear the migratedFrom cache (for testing purposes)
+ */
+export function clearMigratedFromCache(): void {
+  cachedMigratedFrom = null;
+  cachedWalletAddress = null;
+}
+
+export type AddressWithFallbackResult = {
+  address: string;
+  needsBackfill: boolean;
+  source: 'stored' | 'current' | 'migrated';
+};
+
+export type GetDelegationAddressParams = {
+  /** Stored delegation address from payment_details (if available) */
+  storedAddress?: string;
+  /** The delegator's DID (user's wallet DID) */
+  delegator: string;
+  /** OCAP client for chain queries */
+  client: OcapClient;
+};
+
+/**
+ * Get the effective delegation address with migration fallback
+ *
+ * Priority:
+ * 1. Use stored delegation_address if provided
+ * 2. Try current wallet.address
+ * 3. Fallback to migratedFrom addresses
+ */
+export async function getDelegationAddressWithFallback({
+  storedAddress,
+  delegator,
+  client,
+}: GetDelegationAddressParams): Promise<AddressWithFallbackResult | null> {
+  // 1. Check stored delegation_address first
+  if (storedAddress) {
+    return { address: storedAddress, needsBackfill: false, source: 'stored' };
+  }
+
+  // 2. Try current wallet.address
+  const currentAddress = toDelegateAddress(delegator, wallet.address);
+  try {
+    const { state: currentState } = await client.getDelegateState({ address: currentAddress });
+    if (currentState?.ops?.length > 0) {
+      return { address: currentAddress, needsBackfill: true, source: 'current' };
+    }
+  } catch (err) {
+    logger.warn('wallet-migration: failed to query current delegation state', {
+      address: currentAddress,
+      error: err,
+    });
+  }
+
+  // 3. Fallback to migratedFrom addresses
+  const migratedFrom = await getMigratedFromList(client);
+  for (const oldAppDid of migratedFrom) {
+    const oldAddress = toDelegateAddress(delegator, oldAppDid);
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const { state: oldState } = await client.getDelegateState({ address: oldAddress });
+      if (oldState?.ops?.length > 0) {
+        logger.info('wallet-migration: found delegation in migratedFrom', {
+          delegator,
+          oldAppDid,
+          oldAddress,
+        });
+        return { address: oldAddress, needsBackfill: true, source: 'migrated' };
+      }
+    } catch (err) {
+      logger.warn('wallet-migration: failed to query migrated delegation state', {
+        address: oldAddress,
+        oldAppDid,
+        error: err,
+      });
+    }
+  }
+
+  // Not found
+  return null;
+}
+
+export type GetStakingAddressParams = {
+  /** Stored staking address from payment_details (if available) */
+  storedAddress?: string;
+  /** The user's DID */
+  userDid: string;
+  /** The nonce for stake address derivation (usually subscription ID) */
+  nonce: string;
+  /** OCAP client for chain queries */
+  client: OcapClient;
+};
+
+/**
+ * Get the effective staking address with migration fallback
+ *
+ * Priority:
+ * 1. Use stored staking.address if provided
+ * 2. Try current wallet.address
+ * 3. Fallback to migratedFrom addresses
+ */
+export async function getStakingAddressWithFallback({
+  storedAddress,
+  userDid,
+  nonce,
+  client,
+}: GetStakingAddressParams): Promise<AddressWithFallbackResult | null> {
+  // 1. Check stored staking.address first
+  if (storedAddress) {
+    return { address: storedAddress, needsBackfill: false, source: 'stored' };
+  }
+
+  // 2. Try current wallet.address
+  const currentAddress = toStakeAddress(userDid, wallet.address, nonce);
+  try {
+    const { state: currentState } = await client.getStakeState({ address: currentAddress });
+    if (currentState) {
+      return { address: currentAddress, needsBackfill: true, source: 'current' };
+    }
+  } catch (err) {
+    logger.warn('wallet-migration: failed to query current stake state', {
+      address: currentAddress,
+      error: err,
+    });
+  }
+
+  // 3. Fallback to migratedFrom addresses
+  const migratedFrom = await getMigratedFromList(client);
+  for (const oldAppDid of migratedFrom) {
+    const oldAddress = toStakeAddress(userDid, oldAppDid, nonce);
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const { state: oldState } = await client.getStakeState({ address: oldAddress });
+      if (oldState) {
+        logger.info('wallet-migration: found stake in migratedFrom', {
+          userDid,
+          nonce,
+          oldAppDid,
+          oldAddress,
+        });
+        return { address: oldAddress, needsBackfill: true, source: 'migrated' };
+      }
+    } catch (err) {
+      logger.warn('wallet-migration: failed to query migrated stake state', {
+        address: oldAddress,
+        oldAppDid,
+        error: err,
+      });
+    }
+  }
+
+  // Not found
+  return null;
+}
+
+export type GetAppStakeAddressParams = {
+  /** OCAP client for chain queries */
+  client: OcapClient;
+};
+
+/**
+ * Get the effective staking address for gas with migration fallback
+ * This is for app's own stake (sender === receiver === wallet.address)
+ */
+export async function getAppStakeAddressWithFallback({
+  client,
+}: GetAppStakeAddressParams): Promise<AddressWithFallbackResult | null> {
+  // 1. Try current wallet.address
+  const currentAddress = toStakeAddress(wallet.address, wallet.address);
+  try {
+    const { state: currentState } = await client.getStakeState({ address: currentAddress });
+    if (currentState) {
+      return { address: currentAddress, needsBackfill: false, source: 'current' };
+    }
+  } catch (err) {
+    logger.warn('wallet-migration: failed to query current app stake state', {
+      address: currentAddress,
+      error: err,
+    });
+  }
+
+  // 2. Fallback to migratedFrom addresses
+  const migratedFrom = await getMigratedFromList(client);
+  for (const oldAppDid of migratedFrom) {
+    const oldAddress = toStakeAddress(oldAppDid, oldAppDid);
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const { state: oldState } = await client.getStakeState({ address: oldAddress });
+      if (oldState) {
+        logger.info('wallet-migration: found app stake in migratedFrom', {
+          oldAppDid,
+          oldAddress,
+        });
+        return { address: oldAddress, needsBackfill: false, source: 'migrated' };
+      }
+    } catch (err) {
+      logger.warn('wallet-migration: failed to query migrated app stake state', {
+        address: oldAddress,
+        oldAppDid,
+        error: err,
+      });
+    }
+  }
+
+  // Not found
+  return null;
+}
+
+/**
+ * Backfill delegation_address to subscription's payment_details (with optimistic locking)
+ *
+ * @param subscription - The subscription to update
+ * @param address - The delegation address to store
+ * @returns true if backfilled, false if already had a value
+ */
+export async function backfillDelegationAddress(subId: string, address: string): Promise<boolean> {
+  // Optimistic lock: check if already has a value
+  // Use fresh read to avoid race conditions
+  if (!subId) {
+    return false;
+  }
+  try {
+    const subscription = await Subscription.findByPk(subId);
+    if (!subscription) {
+      return false;
+    }
+    if (subscription.payment_details?.arcblock?.delegation_address) {
+      // Already backfilled by another request
+      return false;
+    }
+
+    // Backfill the address (only if arcblock payment_details exists with required fields)
+    const existingArcblock = subscription.payment_details?.arcblock;
+    if (!existingArcblock?.tx_hash || !existingArcblock?.payer) {
+      logger.warn('wallet-migration: cannot backfill delegation_address - missing arcblock payment_details', {
+        subscriptionId: subscription.id,
+      });
+      return false;
+    }
+
+    await subscription.update({
+      payment_details: {
+        ...subscription.payment_details,
+        arcblock: {
+          ...existingArcblock,
+          delegation_address: address,
+        },
+      },
+    });
+
+    logger.info('wallet-migration: backfilled delegation_address', {
+      subscriptionId: subscription.id,
+      address,
+    });
+
+    return true;
+  } catch (err) {
+    logger.error('wallet-migration: failed to backfill delegation_address', {
+      subscriptionId: subId,
+      address,
+      error: err,
+    });
+    return false;
+  }
+}

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

@@ -528,6 +528,7 @@ async function executeAutoRecharge(
         paymentCurrency: rechargeCurrency,
         userDid: payer,
         amount: totalAmount,
+        storedDelegationAddress: config.payment_details?.arcblock?.delegation_address,
       });
 
       if (!balanceCheck.sufficient) {

package/api/src/queues/payment.ts

@@ -725,7 +725,7 @@ const handleStakeSlash = async (
     return;
   }
 
-  const address = await getSubscriptionStakeAddress(subscription, customer.did);
+  const address = await getSubscriptionStakeAddress(subscription, customer.did, paymentMethod);
   const slashAmount = paymentIntent.amount;
   const stakeEnough = await checkRemainingStake(paymentMethod, paymentCurrency, address, slashAmount);
   if (!stakeEnough.enough) {
@@ -859,6 +859,8 @@ export const handlePayment = async (job: PaymentJob) => {
   }
 
   const invoice = await Invoice.findByPk(paymentIntent.invoice_id);
+  // Fetch subscription early for migration fallback support and overdraft protection check
+  const subscription = invoice?.subscription_id ? await Subscription.findByPk(invoice.subscription_id) : null;
 
   if (invoice?.status === 'void') {
     await paymentIntent.update({
@@ -870,20 +872,17 @@ export const handlePayment = async (job: PaymentJob) => {
     return;
   }
 
-  if (invoice && invoice.subscription_id) {
-    const subscription = await Subscription.findByPk(invoice.subscription_id);
-    if (
-      subscription &&
-      subscription.isActive() &&
-      subscription.overdraft_protection?.enabled &&
-      invoice?.billing_reason === 'overdraft_protection'
-    ) {
-      logger.info('PaymentIntent capture skipped because of overdraft protection', {
-        id: paymentIntent.id,
-        subscription: subscription.id,
-      });
-      return;
-    }
+  if (
+    subscription &&
+    subscription.isActive() &&
+    subscription.overdraft_protection?.enabled &&
+    invoice?.billing_reason === 'overdraft_protection'
+  ) {
+    logger.info('PaymentIntent capture skipped because of overdraft protection', {
+      id: paymentIntent.id,
+      subscription: subscription.id,
+    });
+    return;
   }
 
   // check max retry before doing any hard work
@@ -1006,18 +1005,19 @@ export const handlePayment = async (job: PaymentJob) => {
         paymentCurrency,
         userDid: payer || customer.did,
         amount: paymentIntent.amount,
+        subscription,
       });
 
       if (result.sufficient === false) {
         logger.error('PaymentIntent capture aborted - insufficient balance/delegation', {
           paymentIntentId: paymentIntent.id,
           invoiceId: paymentIntent.invoice_id,
-          failureReason: 'INSUFFICIENT_BALANCE',
+          failureReason: result.reason,
           result,
           queueDelayMs,
           delaySeconds: Math.round(queueDelayMs / 1000),
         });
-        throw new CustomError('INSUFFICIENT_BALANCE', 'Payer balance or delegation not sufficient for this payment');
+        throw new CustomError(result.reason, 'Payer balance or delegation not sufficient for this payment');
       }
 
       const signed = await client.signTransferV2Tx({
@@ -1245,7 +1245,6 @@ export const handlePayment = async (job: PaymentJob) => {
       logger.warn('catch:PaymentIntent capture failed', { id: paymentIntent.id, attemptCount, minRetryMail, invoice });
 
       if (needSendMail && invoice.billing_reason === 'subscription_cycle') {
-        const subscription = await Subscription.findByPk(invoice.subscription_id);
         if (subscription) {
           await subscription.update({
             metadata: Object.assign(subscription.metadata, {

package/api/src/queues/refund.ts

@@ -3,7 +3,7 @@ import { isRefundReasonSupportedByStripe } from '../libs/refund';
 import { checkRemainingStake, getSubscriptionStakeAddress } from '../libs/subscription';
 import { sendErc20ToUser } from '../integrations/ethereum/token';
 import { wallet } from '../libs/auth';
-import CustomError from '../libs/error';
+import CustomError, { NonRetryableError } from '../libs/error';
 import { events } from '../libs/event';
 import logger from '../libs/logger';
 import { getGasPayerExtra, isBalanceSufficientForRefund } from '../libs/payment';
@@ -35,6 +35,21 @@ type Updates = {
   };
 };
 
+const markRefundNonRetryable = async (refund: Refund, code: string, message: string, paymentMethod?: PaymentMethod) => {
+  await refund.update({
+    status: 'requires_action',
+    last_attempt_error: {
+      type: 'invalid_request_error',
+      code,
+      message,
+      payment_method_id: paymentMethod?.id,
+      payment_method_type: paymentMethod?.type,
+    },
+    attempt_count: refund.attempt_count + 1,
+    attempted: true,
+  });
+};
+
 export const handleRefundFailed = (refund: Refund, error: PaymentError) => {
   const attemptCount = refund.attempt_count + 1;
   const updates: Updates = {
@@ -94,24 +109,27 @@ export const handleRefund = async (job: RefundJob) => {
   const paymentCurrency = await PaymentCurrency.findByPk(refund.currency_id);
   if (!paymentCurrency) {
     logger.warn(`PaymentCurrency not found: ${refund.currency_id}`);
+    await markRefundNonRetryable(refund, 'CURRENCY_NOT_FOUND', 'Payment currency not found');
     return;
   }
   const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
   if (!paymentMethod) {
     logger.warn(`PaymentMethod not found: ${paymentCurrency.payment_method_id}`);
+    await markRefundNonRetryable(refund, 'PAYMENT_METHOD_NOT_FOUND', 'Payment method not found');
     return;
   }
 
   const customer = await Customer.findByPk(refund.customer_id);
   if (!customer) {
     logger.warn(`Customer not found: ${refund.customer_id}`);
+    await markRefundNonRetryable(refund, 'CUSTOMER_NOT_FOUND', 'Customer not found', paymentMethod);
     return;
   }
 
   if (refund?.type === 'stake_return') {
-    handleStakeReturnJob(job, refund, paymentCurrency, paymentMethod, customer);
+    await handleStakeReturnJob(job, refund, paymentCurrency, paymentMethod, customer);
   } else if (paymentMethod) {
-    handleRefundJob(job, refund, paymentCurrency, paymentMethod, customer);
+    await handleRefundJob(job, refund, paymentCurrency, paymentMethod, customer);
   }
 };
 
@@ -164,18 +182,26 @@ const handleRefundJob = async (
   const refundSupport = ['arcblock', 'ethereum', 'stripe', 'base'].includes(paymentMethod.type);
   if (refundSupport === false) {
     logger.warn(`PaymentMethod does not support auto charge: ${paymentCurrency.payment_method_id}`);
+    await markRefundNonRetryable(
+      refund,
+      'PAYMENT_METHOD_NOT_SUPPORTED',
+      'Payment method does not support refund',
+      paymentMethod
+    );
     return;
   }
 
   // try refund transfer and reschedule on error
   logger.info('Refund transfer attempt', { id: refund.id, attempt: refund.attempt_count });
-  let result;
-  const paymentIntent = await PaymentIntent.findByPk(refund.payment_intent_id);
-  if (!paymentIntent) {
-    throw new Error('PaymentIntent not found');
-  }
-
   try {
+    if (!refund.payment_intent_id) {
+      throw new NonRetryableError('PAYMENT_INTENT_NOT_FOUND', 'payment_intent_id is missing for refund');
+    }
+    const paymentIntent = await PaymentIntent.findByPk(refund.payment_intent_id);
+    if (!paymentIntent) {
+      throw new NonRetryableError('PAYMENT_INTENT_NOT_FOUND', 'PaymentIntent not found');
+    }
+    let result;
     if (paymentMethod.type === 'arcblock') {
       const client = paymentMethod.getOcapClient();
       // check balance before transfer with transaction
@@ -288,6 +314,12 @@ const handleRefundJob = async (
   } catch (err) {
     logger.error('refund transfer failed', { error: err, id: refund.id });
 
+    if (err instanceof NonRetryableError || err?.nonRetryable === true) {
+      await markRefundNonRetryable(refund, err.code, err.message, paymentMethod);
+      logger.error('refund transfer aborted: non-retryable error', { id: refund.id, code: err.code });
+      return;
+    }
+
     const error: PaymentError = {
       type: 'card_error',
       code: err.code,
@@ -348,7 +380,8 @@ const handleStakeReturnJob = async (
       const client = paymentMethod.getOcapClient();
       const subscription = await Subscription.findByPk(refund.subscription_id);
       const address =
-        arcblockDetail?.staking?.address || (await getSubscriptionStakeAddress(subscription!, customer.did));
+        arcblockDetail?.staking?.address ||
+        (await getSubscriptionStakeAddress(subscription!, customer.did, paymentMethod));
       const stakeEnough = await checkRemainingStake(paymentMethod, paymentCurrency, address, refund.amount);
       if (!stakeEnough.enough) {
         logger.warn('Stake return aborted because stake is not enough ', {

package/api/src/queues/subscription.ts

@@ -814,6 +814,7 @@ const handleFinalInvoicePayment = async (
     paymentCurrency,
     userDid: payer || customer.did,
     amount: lastInvoice.amount_remaining,
+    subscription,
   });
 
   if (!hasSufficientBalance.sufficient) {
@@ -898,7 +899,7 @@ export const handleStakeSlashAfterCancel = async (subscription: Subscription, fo
 
     // check the staking
     const client = method.getOcapClient();
-    const address = await getSubscriptionStakeAddress(subscription, customer.did);
+    const address = await getSubscriptionStakeAddress(subscription, customer.did, method);
     const { state } = await client.getStakeState({ address });
     if (!state || !state.data?.value) {
       logger.warn('Stake slashing aborted because no staking state', {
@@ -1142,7 +1143,7 @@ const slashStakeOnCancel = async (subscription: Subscription) => {
     });
     return;
   }
-  const address = await getSubscriptionStakeAddress(subscription, customer.did);
+  const address = await getSubscriptionStakeAddress(subscription, customer.did, paymentMethod);
   const result = await getSubscriptionStakeSlashSetup(subscription, address, paymentMethod);
   const stakeEnough = await checkRemainingStake(paymentMethod, currency, address, result.return_amount);
   if (!stakeEnough.enough) {

package/api/src/routes/auto-recharge-configs.ts

@@ -365,6 +365,7 @@ async function checkSufficientBalance({
     paymentCurrency: rechargeCurrency,
     userDid: payer,
     amount: amount.toString(),
+    storedDelegationAddress: autoRechargeConfig.payment_details?.arcblock?.delegation_address,
   });
 
   return {

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

@@ -3133,7 +3133,7 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
     });
 
     const isPayment = checkoutSession.mode === 'payment';
-    let canFastPay = isPayment && canPayWithDelegation(paymentIntent?.beneficiaries || []);
+    let canFastPay = isPayment && (await canPayWithDelegation(paymentIntent?.beneficiaries || [], paymentMethod));
     let fastPayInfo = null;
     let delegation: SufficientForPaymentResult | null = null;
     let creditSufficient = false;
@@ -3651,7 +3651,7 @@ router.post('/:id/fast-checkout-confirm', user, ensureCheckoutSessionOpen, async
 
     const isPayment = checkoutSession.mode === 'payment';
     let fastPaid = false;
-    let canFastPay = isPayment && canPayWithDelegation(paymentIntent?.beneficiaries || []);
+    let canFastPay = isPayment && (await canPayWithDelegation(paymentIntent?.beneficiaries || [], paymentMethod));
     let delegation: SufficientForPaymentResult | null = null;
 
     // Handle credit payment directly

package/api/src/routes/connect/change-payer.ts

@@ -110,6 +110,7 @@ export default {
             type: 'delegate',
             payer: userDid,
             tx_hash: paymentDetails.tx_hash,
+            delegation_address: paymentDetails?.delegation_address,
           },
         },
       });

package/api/src/routes/connect/shared.ts

@@ -1631,6 +1631,7 @@ export async function executeOcapTransactions(
       tx_hash: delegationTxHash,
       payer: userDid,
       type: 'delegate',
+      delegation_address: delegation?.meta?.address, // Store delegation address for migration compatibility
       staking: {
         tx_hash: stakingTxHash,
         address: await getCustomerStakeAddress(userDid, nonce || subscriptionId || ''),

package/api/src/routes/subscriptions.ts

@@ -1592,6 +1592,7 @@ router.put('/:id', authPortal, async (req, res) => {
               paymentCurrency,
               userDid: payer,
               amount: due || '0',
+              subscription,
             });
             logger.info('delegation sufficient for payment', {
               subscription: subscription.id,
@@ -2214,6 +2215,7 @@ router.put('/:id/slippage', authPortal, async (req, res) => {
           paymentCurrency,
           userDid: payer,
           amount: requiredAmount,
+          subscription,
         });
 
         if (!delegation.sufficient) {
@@ -2485,6 +2487,7 @@ router.post('/:id/change-payment', authPortal, async (req, res) => {
         paymentCurrency,
         userDid: payer,
         amount: requiredAmount,
+        subscription,
       });
       const noStake = subscription.billing_thresholds?.no_stake;
       if (paymentMethod.type === 'arcblock' && delegation.sufficient && !noStake) {
@@ -2901,6 +2904,7 @@ router.get('/:id/delegation', authPortal, async (req, res) => {
       paymentCurrency: subscription.paymentCurrency,
       userDid: payer as string,
       amount: '0',
+      subscription,
     });
     if (
       !delegator.sufficient &&

package/api/src/store/models/types.ts

@@ -330,6 +330,7 @@ export type PaymentDetails = {
     payer: string;
     type?: LiteralUnion<'slash' | 'transfer' | 'delegate' | 'stake_return' | 'credit', string>;
     receiver?: string;
+    delegation_address?: string; // The delegation address at the time of authorization (for migration compatibility)
     staking?: {
       tx_hash: string;
       address: string;

package/api/tests/libs/wallet-migration.spec.ts

@@ -0,0 +1,271 @@
+import { toDelegateAddress, toStakeAddress } from '@arcblock/did-util';
+
+import {
+  getMigratedFromList,
+  getDelegationAddressWithFallback,
+  getStakingAddressWithFallback,
+  getAppStakeAddressWithFallback,
+  clearMigratedFromCache,
+} from '../../src/libs/wallet-migration';
+
+// Mock the auth module
+jest.mock('../../src/libs/auth', () => ({
+  wallet: {
+    address: 'zNKcF7wyrvAvn4YaADjr4p9gpFUSHnW2aQJa', // Current app DID
+  },
+}));
+
+// Mock logger
+jest.mock('../../src/libs/logger', () => ({
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+}));
+
+describe('wallet-migration', () => {
+  // Mock OcapClient
+  const createMockClient = (overrides: any = {}) => ({
+    getAccountState: jest.fn().mockResolvedValue({
+      state: {
+        migratedFrom: ['zNKq13Dr2TBHELpLDUJFGxepiGP7YHbAVxPn', 'zNKq6yG8AVbwdRBDJSNCDVJJUQD1AXdkK7Wp'],
+        address: 'zNKcF7wyrvAvn4YaADjr4p9gpFUSHnW2aQJa',
+      },
+    }),
+    getDelegateState: jest.fn().mockResolvedValue({ state: null }),
+    getStakeState: jest.fn().mockResolvedValue({ state: null }),
+    ...overrides,
+  });
+
+  beforeEach(() => {
+    clearMigratedFromCache();
+  });
+
+  describe('getMigratedFromList', () => {
+    it('should return migratedFrom list from chain', async () => {
+      const mockClient = createMockClient();
+      const result = await getMigratedFromList(mockClient as any);
+      expect(result).toEqual(['zNKq13Dr2TBHELpLDUJFGxepiGP7YHbAVxPn', 'zNKq6yG8AVbwdRBDJSNCDVJJUQD1AXdkK7Wp']);
+    });
+
+    it('should cache the result and not query again', async () => {
+      const mockClient = createMockClient();
+      await getMigratedFromList(mockClient as any);
+      await getMigratedFromList(mockClient as any);
+      expect(mockClient.getAccountState).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return empty array if no migratedFrom', async () => {
+      const mockClient = createMockClient({
+        getAccountState: jest.fn().mockResolvedValue({ state: {} }),
+      });
+      const result = await getMigratedFromList(mockClient as any);
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array on error', async () => {
+      const mockClient = createMockClient({
+        getAccountState: jest.fn().mockRejectedValue(new Error('Network error')),
+      });
+      const result = await getMigratedFromList(mockClient as any);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('getDelegationAddressWithFallback', () => {
+    const delegator = 'zNKtCNqYWLYWYW3gWRA1vnRNdWLrFXfPxRKW';
+    const currentWalletAddress = 'zNKcF7wyrvAvn4YaADjr4p9gpFUSHnW2aQJa';
+    const oldAppDid = 'zNKq13Dr2TBHELpLDUJFGxepiGP7YHbAVxPn';
+
+    it('should return stored address if available', async () => {
+      const mockClient = createMockClient();
+
+      const result = await getDelegationAddressWithFallback({
+        storedAddress: 'stored_delegation_address',
+        delegator,
+        client: mockClient as any,
+      });
+
+      expect(result).toEqual({
+        address: 'stored_delegation_address',
+        needsBackfill: false,
+        source: 'stored',
+      });
+      // Should not query chain if stored
+      expect(mockClient.getDelegateState).not.toHaveBeenCalled();
+    });
+
+    it('should return current address if delegation exists on current wallet', async () => {
+      const currentAddress = toDelegateAddress(delegator, currentWalletAddress);
+      const mockClient = createMockClient({
+        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+          if (address === currentAddress) {
+            return { state: { ops: [{ key: 'fg:x:transfer' }] } };
+          }
+          return { state: null };
+        }),
+      });
+
+      const result = await getDelegationAddressWithFallback({
+        delegator,
+        client: mockClient as any,
+      });
+
+      expect(result).toEqual({
+        address: currentAddress,
+        needsBackfill: true,
+        source: 'current',
+      });
+    });
+
+    it('should fallback to migratedFrom addresses', async () => {
+      const oldAddress = toDelegateAddress(delegator, oldAppDid);
+      const mockClient = createMockClient({
+        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+          if (address === oldAddress) {
+            return { state: { ops: [{ key: 'fg:x:transfer' }] } };
+          }
+          return { state: null };
+        }),
+      });
+
+      const result = await getDelegationAddressWithFallback({
+        delegator,
+        client: mockClient as any,
+      });
+
+      expect(result).toEqual({
+        address: oldAddress,
+        needsBackfill: true,
+        source: 'migrated',
+      });
+    });
+
+    it('should return null if no delegation found', async () => {
+      const mockClient = createMockClient();
+
+      const result = await getDelegationAddressWithFallback({
+        delegator,
+        client: mockClient as any,
+      });
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('getStakingAddressWithFallback', () => {
+    const userDid = 'zNKtCNqYWLYWYW3gWRA1vnRNdWLrFXfPxRKW';
+    const nonce = 'sub_123';
+    const currentWalletAddress = 'zNKcF7wyrvAvn4YaADjr4p9gpFUSHnW2aQJa';
+    const oldAppDid = 'zNKq13Dr2TBHELpLDUJFGxepiGP7YHbAVxPn';
+
+    it('should return stored address if available', async () => {
+      const mockClient = createMockClient();
+
+      const result = await getStakingAddressWithFallback({
+        storedAddress: 'stored_stake_address',
+        userDid,
+        nonce,
+        client: mockClient as any,
+      });
+
+      expect(result).toEqual({
+        address: 'stored_stake_address',
+        needsBackfill: false,
+        source: 'stored',
+      });
+    });
+
+    it('should return current address if stake exists on current wallet', async () => {
+      const currentAddress = toStakeAddress(userDid, currentWalletAddress, nonce);
+      const mockClient = createMockClient({
+        getStakeState: jest.fn().mockImplementation(({ address }) => {
+          if (address === currentAddress) {
+            return { state: { tokens: [] } };
+          }
+          return { state: null };
+        }),
+      });
+
+      const result = await getStakingAddressWithFallback({
+        userDid,
+        nonce,
+        client: mockClient as any,
+      });
+
+      expect(result).toEqual({
+        address: currentAddress,
+        needsBackfill: true,
+        source: 'current',
+      });
+    });
+
+    it('should fallback to migratedFrom addresses', async () => {
+      const oldAddress = toStakeAddress(userDid, oldAppDid, nonce);
+      const mockClient = createMockClient({
+        getStakeState: jest.fn().mockImplementation(({ address }) => {
+          if (address === oldAddress) {
+            return { state: { tokens: [] } };
+          }
+          return { state: null };
+        }),
+      });
+
+      const result = await getStakingAddressWithFallback({
+        userDid,
+        nonce,
+        client: mockClient as any,
+      });
+
+      expect(result).toEqual({
+        address: oldAddress,
+        needsBackfill: true,
+        source: 'migrated',
+      });
+    });
+  });
+
+  describe('getAppStakeAddressWithFallback', () => {
+    const currentWalletAddress = 'zNKcF7wyrvAvn4YaADjr4p9gpFUSHnW2aQJa';
+    const oldAppDid = 'zNKq13Dr2TBHELpLDUJFGxepiGP7YHbAVxPn';
+
+    it('should return current address if app stake exists', async () => {
+      const currentAddress = toStakeAddress(currentWalletAddress, currentWalletAddress);
+      const mockClient = createMockClient({
+        getStakeState: jest.fn().mockImplementation(({ address }) => {
+          if (address === currentAddress) {
+            return { state: { tokens: [] } };
+          }
+          return { state: null };
+        }),
+      });
+
+      const result = await getAppStakeAddressWithFallback({ client: mockClient as any });
+
+      expect(result).toEqual({
+        address: currentAddress,
+        needsBackfill: false,
+        source: 'current',
+      });
+    });
+
+    it('should fallback to migratedFrom addresses for app stake', async () => {
+      const oldAddress = toStakeAddress(oldAppDid, oldAppDid);
+      const mockClient = createMockClient({
+        getStakeState: jest.fn().mockImplementation(({ address }) => {
+          if (address === oldAddress) {
+            return { state: { tokens: [] } };
+          }
+          return { state: null };
+        }),
+      });
+
+      const result = await getAppStakeAddressWithFallback({ client: mockClient as any });
+
+      expect(result).toEqual({
+        address: oldAddress,
+        needsBackfill: false,
+        source: 'migrated',
+      });
+    });
+  });
+});

package/blocklet.yml

@@ -14,7 +14,7 @@ repository:
   type: git
   url: git+https://github.com/blocklet/payment-kit.git
 specVersion: 1.2.8
-version: 1.25.0
+version: 1.25.2
 logo: logo.png
 files:
   - dist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.25.0",
+  "version": "1.25.2",
   "scripts": {
     "dev": "blocklet dev --open",
     "prelint": "npm run types",
@@ -59,9 +59,9 @@
     "@blocklet/error": "^0.3.5",
     "@blocklet/js-sdk": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@blocklet/logger": "^1.17.8-beta-20260104-120132-cb5b1914",
-    "@blocklet/payment-broker-client": "1.25.0",
-    "@blocklet/payment-react": "1.25.0",
-    "@blocklet/payment-vendor": "1.25.0",
+    "@blocklet/payment-broker-client": "1.25.2",
+    "@blocklet/payment-react": "1.25.2",
+    "@blocklet/payment-vendor": "1.25.2",
     "@blocklet/sdk": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@blocklet/ui-react": "^3.4.7",
     "@blocklet/uploader": "^0.3.19",
@@ -132,7 +132,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.25.0",
+    "@blocklet/payment-types": "1.25.2",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -179,5 +179,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "00a94943fea21487c042a7b484f4649add502bc9"
+  "gitHead": "11621a1c925f94bf4f73644de70088e5f0580f74"
 }