payment-kit 1.29.4 → 1.29.6

package/api/src/crons/index.ts

@@ -169,7 +169,10 @@ function init() {
       {
         name: 'deposit.vault',
         time: depositVaultCronTime(),
-        fn: () => startDepositVaultQueue(),
+        // startDepositVaultQueue uses a SCOPED findAll (not systemFindAll), so it
+        // must run inside a tenant — perTenant fans it out per provisioned tenant
+        // (multi) or runs it once for the default tenant (single).
+        fn: perTenant('deposit.vault', () => startDepositVaultQueue()),
         options: { runOnInit: true },
       },
       {

package/api/src/libs/env.ts

@@ -180,6 +180,22 @@ export const sqlBenchmark = (): boolean => readConfig('SQL_BENCHMARK') === '1';
 export const cfEnv = (): any => (globalThis as any).__CF_ENV__;
 export const isCfWorker = (): boolean => !!cfEnv();
 
+/**
+ * THE single, reusable gate for Blocklet-Server-ONLY features.
+ *
+ * True only under Blocklet Server, where the full @blocklet/sdk host runtime is
+ * present — BLOCKLET_APP_ID plus the rest of the env the SDK's
+ * `checkBlockletEnvironment` requires (BLOCKLET_DID / BLOCKLET_APP_EK / ABT_NODE_*).
+ * BLOCKLET_APP_ID is the canonical marker; arc-node and the CF worker run the
+ * embedded core with NONE of it.
+ *
+ * Any integration that only works on Blocklet Server (the @blocklet/sdk
+ * notification / eventbus / relay transports, and any future host-service feature)
+ * MUST gate on this and skip itself off Blocklet Server — never branch on
+ * isCfWorker()/hasDynamicIdentity() ad hoc, so "what is BS-only" stays in one place.
+ */
+export const isBlockletServer = (): boolean => hasConfig('BLOCKLET_APP_ID');
+
 export default {
   ...env,
 };

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

@@ -3,10 +3,53 @@ import BlockletNotification from '@blocklet/sdk/service/notification';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './template/base';
 import { CheckoutSession, CreditGrant, Invoice, Meter, MeterEvent, Subscription } from '../../store/models';
 import { getNotificationSettings, shouldSendSystemNotification } from '../setting';
+import { isBlockletServer } from '../env';
 import logger from '../logger';
 import { events } from '../event';
 import { createFlexibleEvent } from '../audit';
 
+let blockletSdkTransportGuarded = false;
+
+/** Replace `fns` with no-ops on both the module namespace and its `default` export. */
+function noopSdkTransport(mod: any, fns: string[]): void {
+  const noop = async (): Promise<undefined> => undefined;
+  for (const target of [mod, mod?.default]) {
+    if (!target) continue;
+    for (const fn of fns) target[fn] = noop;
+  }
+}
+
+/**
+ * Several @blocklet/sdk service transports run `checkBlockletEnvironment`, which
+ * throws `BLOCKLET_APP_ID does not exist in environments` when that env is absent:
+ *   - service/notification → sendToUser / sendToRelay / sendToMail
+ *   - service/eventbus     → publish / subscribe / unsubscribe
+ * BLOCKLET_APP_ID only exists under blocklet-server; arc-node and the CF worker have
+ * NO such transport, so the post-payment notification job crashed and every event
+ * broadcast logged a "Failed to publish event via EventBus" error.
+ *
+ * Off blocklet-server we replace those transport functions with no-ops — at the SDK
+ * module level, not the call sites, so the app-side logic (notification settings
+ * check, the `events` emit that drives `broadcast`) still runs and only the actual
+ * send/publish is skipped. One patch covers every caller: __esModule is true, so
+ * esbuild's __toESM keeps live getters and every `import … from '@blocklet/sdk/...'`
+ * (default OR namespace) resolves to this same module object at call time — hence
+ * patching both `mod` and `mod.default`.
+ *
+ * Idempotent; gated on the exact env the SDK checks, so blocklet-server is byte-for-
+ * byte unchanged (it returns before requiring/mutating anything).
+ */
+export function ensureBlockletSdkTransportGuard(): void {
+  if (blockletSdkTransportGuarded) return;
+  blockletSdkTransportGuarded = true;
+  if (isBlockletServer()) return; // Blocklet Server: real transports, leave them intact
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  noopSdkTransport(require('@blocklet/sdk/service/notification'), ['sendToUser', 'sendToRelay', 'sendToMail']);
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  noopSdkTransport(require('@blocklet/sdk/service/eventbus'), ['publish', 'subscribe', 'unsubscribe']);
+  logger.info('[blocklet-sdk] notification + eventbus transport disabled — no BLOCKLET_APP_ID (off blocklet-server)');
+}
+
 export class Notification {
   template: BaseEmailTemplate;
   type?: string;

package/api/src/libs/payment.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/indent */
 import { isEthereumDid } from '@arcblock/did';
 import { getWalletDid } from '@blocklet/sdk/lib/did';
+import type OcapClient from '@ocap/client';
 import type { DelegateState, TokenLimit } from '@ocap/client';
 import { toTxHash } from '@ocap/mcrypto';
 import { BN, fromUnitToToken } from '@ocap/util';
@@ -21,7 +22,12 @@ import {
   Customer,
   Subscription,
 } from '../store/models';
-import { getDelegationAddressWithFallback, backfillDelegationAddress, getMigratedFromList } from './wallet-migration';
+import {
+  getDelegationAddressWithFallback,
+  backfillDelegationAddress,
+  getMigratedFromList,
+  getAppStakeAddressWithFallback,
+} from './wallet-migration';
 import type { TPaymentCurrency } from '../store/models/payment-currency';
 import { blocklet, ethWallet, wallet, getVaultAddress } from './auth';
 import logger from './logger';
@@ -520,8 +526,27 @@ export function isCreditSufficientForPayment(args: {
   return { sufficient: true, balance };
 }
 
-export async function getGasPayerExtra(txBuffer: Buffer, headers?: { [key: string]: string }) {
-  if (headers && headers['x-gas-payer-sig'] && headers['x-gas-payer-pk']) {
+export async function getGasPayerExtra(
+  txBuffer: Buffer,
+  headers?: { [key: string]: string },
+  // The ocap client for the tx's chain. When provided AND the app has staked for
+  // gas, the app is the deliberate sponsor for this method's payments: use ITS OWN
+  // gas-payer header and IGNORE any wallet-provided one. ArcWallet attaches a
+  // gas-payer header to every wallet-initiated tx, so without this gate the app's
+  // staked sponsor (the self-sign branch below) is never reached — the chain
+  // rejects the wallet's header and falls back to charging `from` (the user's
+  // possibly-empty account) → GAS_PAYER_NOT_ON_CHAIN. Best-effort: any stake-check
+  // error keeps the wallet header (prior behavior), so a flaky chain read never
+  // blocks a payment.
+  client?: OcapClient
+) {
+  const appStaked = client
+    ? await getAppStakeAddressWithFallback({ client })
+        .then((r) => !!r)
+        .catch(() => false)
+    : false;
+
+  if (!appStaked && headers && headers['x-gas-payer-sig'] && headers['x-gas-payer-pk']) {
     return { headers };
   }
 

package/api/src/middlewares/hono/context.ts

@@ -55,16 +55,28 @@ export function contextMiddleware(): MiddlewareHandler {
       requestedBy = user.did;
     }
 
-    // Resolve tenant from the raw Host (single point). Multi-mode unknown host →
-    // 4xx fail-closed, no default-tenant fallback.
+    // Resolve tenant from the raw Host (single point) — UNLESS the host already
+    // scoped this request (e.g. the CF worker wrapped /.well-known/payment/* in
+    // withTenant before the core ran, and set its identity driver's
+    // resolveInstanceDidForHost to null on purpose). Honor that pre-established
+    // context instead of re-resolving, mirroring the DID-Connect tenant middleware
+    // (service.ts buildConnectRoutesHono) so native and connect routes behave
+    // identically. blocklet-server / arc-node never pre-wrap → peek is undefined →
+    // the Host resolution path is unchanged. Multi-mode unknown host → 4xx
+    // fail-closed, no default-tenant fallback.
     let instanceDid: string;
-    try {
-      instanceDid = await resolveTenantForHost(c.req.header('host'));
-    } catch (err) {
-      if (err instanceof TenantError && err.code === TENANT_HOST_UNRESOLVED) {
-        return c.json({ error: { code: err.code, message: err.message } }, 400);
+    const preResolved = context.peekInstanceDid();
+    if (preResolved) {
+      instanceDid = preResolved;
+    } else {
+      try {
+        instanceDid = await resolveTenantForHost(c.req.header('host'));
+      } catch (err) {
+        if (err instanceof TenantError && err.code === TENANT_HOST_UNRESOLVED) {
+          return c.json({ error: { code: err.code, message: err.message } }, 400);
+        }
+        throw err;
       }
-      throw err;
     }
 
     return context.run({ requestId, requestedBy, instanceDid }, async () => {

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

@@ -6,6 +6,7 @@ import pAll from 'p-all';
 import dayjs from '../libs/dayjs';
 import createQueue, { assertJobObjectTenant } from '../libs/queue';
 import { systemFindAll, systemFindByPk } from '../store/scoped';
+import { withTenant } from '../libs/context';
 import {
   AutoRechargeConfig,
   CreditGrant,
@@ -440,7 +441,10 @@ export const startCreditGrantQueue = async () => {
 
   const invoiceResults = await Promise.allSettled(
     invoicesToSchedule.map(async (invoice) => {
-      await addInvoiceCreditJob(invoice.id);
+      // Cross-tenant scan → enqueue in the invoice's own tenant (push stamps the job
+      // tenant via getInstanceDid, fail-closed in multi otherwise).
+      const dispatch = () => addInvoiceCreditJob(invoice.id);
+      await (invoice.instance_did ? withTenant(invoice.instance_did, dispatch) : dispatch());
       return invoice.id;
     })
   );
@@ -454,7 +458,8 @@ export const startCreditGrantQueue = async () => {
 
   const results = await Promise.allSettled(
     grantsToSchedule.map(async (grant) => {
-      await scheduleCreditGrantJobs(grant);
+      const dispatch = () => scheduleCreditGrantJobs(grant);
+      await (grant.instance_did ? withTenant(grant.instance_did, dispatch) : dispatch());
       return grant.id;
     })
   );

package/api/src/queues/discount-status.ts

@@ -1,4 +1,5 @@
 import pAll from 'p-all';
+import { withTenant } from '../libs/context';
 import createQueue, { assertJobObjectTenant } from '../libs/queue';
 import { Coupon, PromotionCode } from '../store/models';
 import logger from '../libs/logger';
@@ -151,21 +152,26 @@ export const startDiscountStatusQueue = async () => {
 
   const coupons = await systemFindAll(Coupon, { where: { valid: true } });
   const promotionCodes = await systemFindAll(PromotionCode, { where: { active: true } });
+
+  // Cross-tenant scan: addDiscountStatusJob pushes, which stamps the job tenant via
+  // getInstanceDid (fails closed in multi mode without context). Run each enqueue in
+  // its record's tenant; per-record catch isolates one bad row from the whole pass.
+  const enqueue = (record: Coupon | PromotionCode, type: DiscountType, options: { runAt?: number }) => async () => {
+    const dispatch = () => addDiscountStatusJob(record, type, false, options);
+    try {
+      await (record.instance_did ? withTenant(record.instance_did, dispatch) : dispatch());
+    } catch (error) {
+      logger.error('startDiscountStatusQueue: enqueue failed', { type, id: record.id, error });
+    }
+  };
+
   await pAll(
-    coupons.map(
-      (coupon) => () =>
-        addDiscountStatusJob(coupon, 'coupon', false, {
-          runAt: coupon.redeem_by,
-        })
-    ),
+    coupons.map((coupon) => enqueue(coupon, 'coupon', { runAt: coupon.redeem_by })),
     { concurrency: 5 }
   );
   await pAll(
-    promotionCodes.map(
-      (promotionCode) => () =>
-        addDiscountStatusJob(promotionCode, 'promotion-code', false, {
-          runAt: promotionCode.expires_at,
-        })
+    promotionCodes.map((promotionCode) =>
+      enqueue(promotionCode, 'promotion-code', { runAt: promotionCode.expires_at })
     ),
     { concurrency: 5 }
   );

package/api/src/queues/invoice.ts

@@ -1,5 +1,7 @@
 import { Op } from 'sequelize';
 import { systemFindAll, systemFindByPk } from '../store/scoped';
+import { withTenant } from '../libs/context';
+import { perTenant } from '../crons/tenant-fanout';
 
 import { getInvoiceShouldPayTotal, handleOverdraftProtectionInvoiceAfterPayment } from '../libs/invoice';
 import { createEvent, reportAuditFailure } from '../libs/audit';
@@ -231,15 +233,20 @@ export const startInvoiceQueue = async () => {
     });
 
     const results = await Promise.allSettled(
-      invoices.map(async (x) => {
-        const supportAutoCharge = await PaymentMethod.supportAutoCharge(x.default_payment_method_id);
-        if (supportAutoCharge === false) {
-          return;
-        }
-        const exist = await invoiceQueue.get(x.id);
-        if (!exist) {
-          await invoiceQueue.push({ id: x.id, job: { invoiceId: x.id, retryOnError: true } });
-        }
+      invoices.map((x) => {
+        const dispatch = async () => {
+          const supportAutoCharge = await PaymentMethod.supportAutoCharge(x.default_payment_method_id);
+          if (supportAutoCharge === false) {
+            return;
+          }
+          const exist = await invoiceQueue.get(x.id);
+          if (!exist) {
+            await invoiceQueue.push({ id: x.id, job: { invoiceId: x.id, retryOnError: true } });
+          }
+        };
+        // Cross-tenant scan → run each invoice's enqueue in its own tenant: the push
+        // stamps the job tenant via getInstanceDid, fail-closed in multi otherwise.
+        return x.instance_did ? withTenant(x.instance_did, dispatch) : dispatch();
       })
     );
 
@@ -248,7 +255,10 @@ export const startInvoiceQueue = async () => {
       logger.warn(`Failed to process ${failed} invoices in startInvoiceQueue`);
     }
 
-    await batchHandleStripeInvoices();
+    // batchHandleStripeInvoices uses scoped findAll → run once per provisioned
+    // tenant (perTenant) so its queries resolve a tenant; the stripe.invoice.sync
+    // cron uses the same wrapper. Single mode runs it once, unchanged.
+    await perTenant('startInvoiceQueue.stripe', batchHandleStripeInvoices)();
   } catch (error) {
     logger.error('Error in startInvoiceQueue:', error);
   } finally {

package/api/src/queues/subscription.ts

@@ -4,6 +4,8 @@ import { BN } from '@ocap/util';
 import { Op } from 'sequelize';
 import { paymentReloadSubscriptionJobs } from '../libs/env';
 import { systemFindAll, systemFindByPk, systemFindOne } from '../store/scoped';
+import { withTenant } from '../libs/context';
+import { perTenant } from '../crons/tenant-fanout';
 import { createEvent, reportAuditFailure } from '../libs/audit';
 import { ensurePassportRevoked } from '../integrations/blocklet/passport';
 // eslint-disable-next-line import/no-cycle
@@ -1603,27 +1605,32 @@ export const startSubscriptionQueue = async () => {
     });
 
     const results = await Promise.allSettled(
-      subscriptions.map(async (x) => {
-        const supportAutoCharge = await PaymentMethod.supportAutoCharge(x.default_payment_method_id);
-        if (supportAutoCharge === false) {
-          return;
-        }
-        if (['past_due', 'paused'].includes(x.status)) {
-          const willCancel = x.cancel_at || x.cancel_at_period_end;
-          if (x.status === 'past_due' && willCancel) {
-            const existingJob = await subscriptionQueue.get(`cancel-${x.id}`);
-            if (!existingJob) {
-              await addSubscriptionJob(x, 'cancel', true, x.cancel_at || x.current_period_end);
+      subscriptions.map((x) => {
+        const dispatch = async () => {
+          const supportAutoCharge = await PaymentMethod.supportAutoCharge(x.default_payment_method_id);
+          if (supportAutoCharge === false) {
+            return;
+          }
+          if (['past_due', 'paused'].includes(x.status)) {
+            const willCancel = x.cancel_at || x.cancel_at_period_end;
+            if (x.status === 'past_due' && willCancel) {
+              const existingJob = await subscriptionQueue.get(`cancel-${x.id}`);
+              if (!existingJob) {
+                await addSubscriptionJob(x, 'cancel', true, x.cancel_at || x.current_period_end);
+              }
             }
+            logger.info(`skip add cycle subscription job because status is ${x.status}`, {
+              subscription: x.id,
+              action: 'cycle',
+            });
+            return;
           }
-          logger.info(`skip add cycle subscription job because status is ${x.status}`, {
-            subscription: x.id,
-            action: 'cycle',
-          });
-          return;
-        }
-        logger.info('add subscription job', { subscription: x.id, action: 'cycle' });
-        await addSubscriptionJob(x, 'cycle', paymentReloadSubscriptionJobs());
+          logger.info('add subscription job', { subscription: x.id, action: 'cycle' });
+          await addSubscriptionJob(x, 'cycle', paymentReloadSubscriptionJobs());
+        };
+        // Cross-tenant scan → run each subscription's enqueue in its own tenant: the
+        // push stamps the job tenant via getInstanceDid, fail-closed in multi otherwise.
+        return x.instance_did ? withTenant(x.instance_did, dispatch) : dispatch();
       })
     );
 
@@ -1632,7 +1639,9 @@ export const startSubscriptionQueue = async () => {
       logger.warn(`Failed to process ${failed} subscriptions in startSubscriptionQueue`);
     }
 
-    await batchHandleStripeSubscriptions();
+    // batchHandleStripeSubscriptions uses scoped findAll → run once per provisioned
+    // tenant (perTenant); the stripe.subscription.sync cron uses the same wrapper.
+    await perTenant('startSubscriptionQueue.stripe', batchHandleStripeSubscriptions)();
   } catch (error) {
     logger.error('Error in startSubscriptionQueue:', error);
   } finally {

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

@@ -1,4 +1,5 @@
 import { BN } from '@ocap/util';
+import { withTenant } from '../libs/context';
 import logger from '../libs/logger';
 import createQueue, { assertJobObjectTenant } from '../libs/queue';
 import { getAccountState, transferTokenFromCustomer, getCustomerTokenBalance } from '../integrations/arcblock/token';
@@ -313,7 +314,7 @@ export async function startTokenTransferQueue(): Promise<void> {
     // Process in batches to add jobs
     await Promise.all(
       pendingTransactions.map(async (transaction) => {
-        try {
+        const dispatch = async () => {
           const customer = (await systemFindByPk(Customer, transaction.customer_id))!;
           const creditGrant = (await systemFindByPk(CreditGrant, transaction.credit_grant_id))!;
 
@@ -326,6 +327,11 @@ export async function startTokenTransferQueue(): Promise<void> {
             meterEventId: transaction.source!,
             subscriptionId: transaction.subscription_id || undefined,
           });
+        };
+        try {
+          // Cross-tenant scan: run each transaction's enqueue in its own tenant so the
+          // push (injectJobTenant -> getInstanceDid) is stamped, not fail-closed in multi.
+          await (transaction.instance_did ? withTenant(transaction.instance_did, dispatch) : dispatch());
         } catch (error: any) {
           logger.error('Failed to add pending transfer job', {
             transactionId: transaction.id,

package/api/src/queues/vendors/commission.ts

@@ -1,3 +1,4 @@
+import { withTenant } from '../../libs/context';
 import { events } from '../../libs/event';
 import logger from '../../libs/logger';
 import createQueue, { assertJobObjectTenant } from '../../libs/queue';
@@ -157,13 +158,28 @@ export const startVendorCommissionQueue = async () => {
     },
   });
 
-  payments.forEach(async (x) => {
-    const id = `vendor-commission-${x.invoice_id}`;
-    const exist = await vendorCommissionQueue.get(id);
-    if (!exist && x.invoice_id) {
-      vendorCommissionQueue.push({ id, job: { invoiceId: x.invoice_id, retryOnError: true } });
+  // Each pending intent belongs to a tenant: the queue push stamps the job tenant
+  // via getInstanceDid, which fails closed in multi mode without a tenant context.
+  // for-of + await, NOT forEach(async): a fire-and-forget rejection here becomes an
+  // unhandledRejection -> FATAL on boot. Per-record try/catch isolates one bad row.
+  for (const x of payments) {
+    const invoiceId = x.invoice_id;
+    if (invoiceId) {
+      const dispatch = async () => {
+        const id = `vendor-commission-${invoiceId}`;
+        const exist = await vendorCommissionQueue.get(id);
+        if (!exist) {
+          vendorCommissionQueue.push({ id, job: { invoiceId, retryOnError: true } });
+        }
+      };
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await (x.instance_did ? withTenant(x.instance_did, dispatch) : dispatch());
+      } catch (error) {
+        logger.error('startVendorCommissionQueue: re-queue failed', { invoiceId, error });
+      }
     }
-  });
+  }
 };
 
 events.on('invoice.paid', async (invoice) => {

package/api/src/queues/vendors/status-check.ts

@@ -1,5 +1,6 @@
 import { joinURL } from 'ufo';
 import { Auth as VendorAuth } from '@blocklet/payment-vendor';
+import { withTenant } from '../../libs/context';
 import createQueue, { assertJobObjectTenant } from '../../libs/queue';
 import { CheckoutSession } from '../../store/models/checkout-session';
 import { ProductVendor } from '../../store/models';
@@ -18,20 +19,34 @@ export const startVendorStatusCheckSchedule = async () => {
     return;
   }
 
+  // Cross-tenant scan: each push stamps the job tenant via getInstanceDid, which
+  // fails closed in multi mode without a tenant context. Wrap each session's pushes
+  // in withTenant; per-session try/catch isolates one bad row. (`continue`, not
+  // `return`: a session with no vendor_info must skip — not abort the whole scan.)
   for (const checkoutSession of checkoutSessions) {
     const vendorInfo = checkoutSession.vendor_info;
-    if (!vendorInfo?.length) {
-      return;
-    }
-
-    for (const vendor of vendorInfo) {
-      if (vendor.status === 'sent') {
-        vendorStatusCheckQueue.push({
-          id: `vendor-status-check-${checkoutSession.id}-${vendor.vendor_id}`,
-          job: {
-            checkoutSessionId: checkoutSession.id,
-            vendorId: vendor.vendor_id,
-          },
+    if (vendorInfo?.length) {
+      const dispatch = () => {
+        for (const vendor of vendorInfo) {
+          if (vendor.status === 'sent') {
+            vendorStatusCheckQueue.push({
+              id: `vendor-status-check-${checkoutSession.id}-${vendor.vendor_id}`,
+              job: {
+                checkoutSessionId: checkoutSession.id,
+                vendorId: vendor.vendor_id,
+              },
+            });
+          }
+        }
+      };
+
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await (checkoutSession.instance_did ? withTenant(checkoutSession.instance_did, dispatch) : dispatch());
+      } catch (error) {
+        logger.error('startVendorStatusCheckSchedule: enqueue failed', {
+          checkoutSessionId: checkoutSession.id,
+          error,
         });
       }
     }

package/api/src/routes/connect/collect-batch.ts

@@ -136,7 +136,7 @@ export default {
       const txHash = await client.sendTransferV3Tx(
         // @ts-ignore
         { tx, wallet: fromAddress(userDid) },
-        await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request))
+        await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request), client)
       );
       await afterTxExecution({ tx_hash: txHash, payer: userDid, type: 'transfer' });
 

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

@@ -158,7 +158,7 @@ export default {
         const txHash = await client.sendTransferV3Tx(
           // @ts-ignore
           { tx, wallet: fromAddress(userDid) },
-          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request))
+          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request), client)
         );
 
         await afterTxExecution({

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

@@ -145,7 +145,7 @@ export default {
         const txHash = await client.sendTransferV3Tx(
           // @ts-ignore
           { tx, wallet: fromAddress(userDid) },
-          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request))
+          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request), client)
         );
 
         const quoteValidation = await validateQuoteForPayment({

package/api/src/routes/connect/recharge-account.ts

@@ -201,7 +201,7 @@ export default {
         const txHash = await client.sendTransferV3Tx(
           // @ts-ignore
           { tx, wallet: fromAddress(userDid) },
-          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request))
+          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request), client)
         );
 
         await afterTxExecution({

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

@@ -128,7 +128,7 @@ export default {
         const txHash = await client.sendTransferV3Tx(
           // @ts-ignore
           { tx, wallet: fromAddress(userDid) },
-          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request))
+          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request), client)
         );
 
         logger.info('Recharge successful', {

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

@@ -1573,7 +1573,7 @@ async function executeSingleTransaction(
   const { buffer } = await client[`encode${type}Tx`]({ tx });
   return client[`send${type}Tx`](
     { tx, wallet: fromPublicKey(userPk, toTypeInfo(userDid)) },
-    await getGasPayerExtra(buffer, gasPayerHeaders)
+    await getGasPayerExtra(buffer, gasPayerHeaders, client)
   );
 }
 

package/api/src/routes/hono/bootstrap.ts

@@ -0,0 +1,65 @@
+// On-demand, idempotent per-tenant bootstrap — mounted at /api/bootstrap.
+//
+// blocklet-server runs `bootstrapTenant` automatically at startup (service.ts
+// start → single-mode default tenant, or multi-mode via the listInstanceDids
+// hook). The arc-node daemon and the CF worker do NOT: they only wire the
+// lightweight `provisionTenant` (DB seed) into the request path and never call
+// `bootstrapTenant`, so the heavy per-tenant integrations — chiefly
+// `ensureStakedForGas` (declare + stake the app wallet for gas) — never run, and
+// the app can't sponsor on-chain gas.
+//
+// This route exposes the SAME idempotent bootstrap so ANY runtime can trigger it
+// on demand (a one-off curl, an ops cron, an admin button) WITHOUT putting it on
+// the startup path. Every step is idempotent (ensureStakedForGas skips when
+// already staked or under-funded), so repeated calls are safe.
+import { Hono } from 'hono';
+
+import { authenticate } from '../../middlewares/hono/security';
+import { getInstanceDid } from '../../libs/context';
+import { wallet } from '../../libs/auth';
+import { hasStakedForGas } from '../../integrations/arcblock/stake';
+import { PaymentMethod } from '../../store/models';
+import logger from '../../libs/logger';
+
+const app = new Hono();
+
+// Triggers an on-chain stake (spends gas tokens) → restrict to owner/admin or a
+// signed component call. Relax only if a runtime needs to drive it unauthenticated.
+const authAdmin = authenticate<PaymentMethod>({ component: true, roles: ['owner', 'admin'] });
+
+app.get('/', authAdmin, async (c) => {
+  const instanceDid = getInstanceDid();
+  try {
+    // The SAME idempotent per-tenant bootstrap the startup path runs on
+    // blocklet-server. Lazy require: a top-level import would close a load-time
+    // cycle (service.ts → routes/hono → here). bootstrapTenant re-enters
+    // withTenant + warmTenantIdentity, so calling it from the request context is safe.
+    // eslint-disable-next-line global-require
+    const { bootstrapTenant } = require('../../service');
+    await bootstrapTenant(instanceDid);
+
+    // Report the resulting on-chain status per arcblock method (idempotent read)
+    // so the caller can verify the stake actually landed.
+    const methods = await PaymentMethod.findAll({ where: { type: 'arcblock', active: true } });
+    const chains = await Promise.all(
+      methods.map(async (method) => {
+        const host = method.settings?.arcblock?.api_host;
+        try {
+          const client = method.getOcapClient();
+          const { state } = await client.getAccountState({ address: wallet.address });
+          const stakedForGas = await hasStakedForGas(method);
+          return { method: method.name, host, declared: !!state, balance: state?.balance ?? null, stakedForGas };
+        } catch (err) {
+          return { method: method.name, host, error: (err as Error).message };
+        }
+      })
+    );
+
+    return c.json({ ok: true, instanceDid, appWallet: wallet.address, chains });
+  } catch (err) {
+    logger.error('bootstrap endpoint failed', { instanceDid, error: err });
+    return c.json({ ok: false, instanceDid, error: (err as Error).message }, 500);
+  }
+});
+
+export default app;

package/api/src/routes/hono/index.ts

@@ -48,6 +48,7 @@ import vendor from './vendor';
 import webhookAttempts from './webhook-attempts';
 import webhookEndpoints from './webhook-endpoints';
 import archive from './archive';
+import bootstrap from './bootstrap';
 
 export function mountMigratedResources(native: Hono, opts: { appShell?: MiddlewareHandler[] } = {}): void {
   // The node host passes its full app-shell pipeline (cors/xss/csrf/cdn/i18n/
@@ -110,6 +111,11 @@ export function mountMigratedResources(native: Hono, opts: { appShell?: Middlewa
   g('/api/webhook-attempts', webhookAttempts);
   g('/api/webhook-endpoints', webhookEndpoints);
   g('/api/archive', archive);
+
+  // On-demand idempotent per-tenant bootstrap (declare/stake the app wallet for
+  // gas). arc-node/CF never run the startup bootstrapTenant, so this is the
+  // runtime-agnostic trigger — see routes/hono/bootstrap.ts.
+  g('/api/bootstrap', bootstrap);
 }
 
 export default mountMigratedResources;

package/api/src/service.ts

@@ -402,7 +402,7 @@ let listInstanceDidsHook: (() => Promise<string[]> | string[]) | undefined;
  * tenancy.listInstanceDids). Single mode bootstraps the default tenant from
  * start() automatically (original behavior preserved).
  */
-async function bootstrapTenant(instanceDid: string): Promise<void> {
+export async function bootstrapTenant(instanceDid: string): Promise<void> {
   if (!instanceDid || typeof instanceDid !== 'string') {
     throw new TenantError(TENANT_CONTEXT_MISSING, 'bootstrapTenant requires an instanceDid');
   }
@@ -518,6 +518,12 @@ async function startBackgroundServices(): Promise<void> {
   }
   servicesStarted = true;
 
+  // Disable @blocklet/sdk host transports (notification + eventbus) off Blocklet
+  // Server — arc-node / CF have no BLOCKLET_APP_ID, so sendToUser/publish would
+  // crash/spam. Gated on isBlockletServer(); runs in EVERY runtime via
+  // lifecycle.start(); no-op on Blocklet Server.
+  require('./libs/notification').ensureBlockletSdkTransportGuard();
+
   const crons = require('./crons/index').default;
   const { initResourceHandler } = require('./integrations/blocklet/resource');
   const { initUserHandler } = require('./integrations/blocklet/user');
@@ -547,7 +553,14 @@ async function startBackgroundServices(): Promise<void> {
     ['discount status', require('./queues/discount-status').startDiscountStatusQueue],
   ];
   for (const [name, start] of starters) {
-    Promise.resolve(start()).then(() => logger.info(`${name} queue started`));
+    // .catch() is load-bearing: a starter that does a cross-tenant systemFindAll
+    // then enqueues without a tenant context rejects in multi mode (injectJobTenant
+    // -> getInstanceDid -> TENANT_CONTEXT_MISSING). Fire-and-forget without .catch()
+    // turns that into an unhandledRejection -> FATAL on boot. Degrade + log instead;
+    // per-starter tenant correctness is handled inside each starter (L2).
+    Promise.resolve(start())
+      .then(() => logger.info(`${name} queue started`))
+      .catch((error: unknown) => logger.error(`${name} queue failed to start`, { error }));
   }
 
   // cron + global handlers (tenant-agnostic; runOnInit is skipped in multi mode)

package/api/tests/libs/gas-payer-extra.spec.ts

@@ -0,0 +1,74 @@
+// getGasPayerExtra gas-payer selection (libs/payment.ts).
+//
+// Policy (decided 2026-06): when the app has staked for gas it is the deliberate
+// sponsor, so its OWN gas-payer header must win over any wallet-provided one —
+// otherwise ArcWallet's header (attached to every wallet tx) always wins, the
+// app's stake is never used, and the chain falls back to charging `from`
+// (GAS_PAYER_NOT_ON_CHAIN). These tests pin that gate. The heavy payment.ts deps
+// are mocked so the suite stays DB-free.
+const getAppStakeAddressWithFallback = jest.fn();
+jest.mock('../../src/libs/wallet-migration', () => ({
+  getAppStakeAddressWithFallback,
+  getDelegationAddressWithFallback: jest.fn(),
+  backfillDelegationAddress: jest.fn(),
+  getMigratedFromList: jest.fn(),
+}));
+
+const wallet = { signJWT: jest.fn(async () => 'APP_SIG'), publicKey: 'APP_PK', address: 'zApp' };
+jest.mock('../../src/libs/auth', () => ({
+  wallet,
+  ethWallet: {},
+  blocklet: {},
+  getVaultAddress: jest.fn(),
+}));
+
+jest.mock('@ocap/mcrypto', () => ({
+  ...jest.requireActual('@ocap/mcrypto'),
+  toTxHash: () => 'TXHASH',
+}));
+
+import { getGasPayerExtra } from '../../src/libs/payment';
+
+const buffer = Buffer.from('tx-bytes');
+const walletHeaders = { 'x-gas-payer-sig': 'WALLET_SIG', 'x-gas-payer-pk': 'WALLET_PK' };
+const fakeClient = {} as any;
+
+beforeEach(() => {
+  getAppStakeAddressWithFallback.mockReset();
+  wallet.signJWT.mockClear();
+});
+
+describe('getGasPayerExtra — app-staked gas-payer preference', () => {
+  it('no client: wallet header wins (prior behavior)', async () => {
+    const out = await getGasPayerExtra(buffer, walletHeaders);
+    expect(out).toEqual({ headers: walletHeaders });
+    expect(getAppStakeAddressWithFallback).not.toHaveBeenCalled();
+    expect(wallet.signJWT).not.toHaveBeenCalled();
+  });
+
+  it('client + app NOT staked: wallet header still wins', async () => {
+    getAppStakeAddressWithFallback.mockResolvedValue(null);
+    const out = await getGasPayerExtra(buffer, walletHeaders, fakeClient);
+    expect(out).toEqual({ headers: walletHeaders });
+    expect(wallet.signJWT).not.toHaveBeenCalled();
+  });
+
+  it('client + app STAKED: app self-sponsors, ignoring the wallet header', async () => {
+    getAppStakeAddressWithFallback.mockResolvedValue({ address: 'zStake', source: 'current' });
+    const out = await getGasPayerExtra(buffer, walletHeaders, fakeClient);
+    expect(out).toEqual({ headers: { 'x-gas-payer-sig': 'APP_SIG', 'x-gas-payer-pk': 'APP_PK' } });
+    expect(wallet.signJWT).toHaveBeenCalledWith({ txHash: 'TXHASH' });
+  });
+
+  it('no wallet header: app self-signs regardless', async () => {
+    const out = await getGasPayerExtra(buffer);
+    expect(out).toEqual({ headers: { 'x-gas-payer-sig': 'APP_SIG', 'x-gas-payer-pk': 'APP_PK' } });
+  });
+
+  it('stake check error: keeps the wallet header (best-effort, never blocks a payment)', async () => {
+    getAppStakeAddressWithFallback.mockRejectedValue(new Error('chain timeout'));
+    const out = await getGasPayerExtra(buffer, walletHeaders, fakeClient);
+    expect(out).toEqual({ headers: walletHeaders });
+    expect(wallet.signJWT).not.toHaveBeenCalled();
+  });
+});

package/api/tests/libs/notification-guard.spec.ts

@@ -0,0 +1,61 @@
+// ensureBlockletSdkTransportGuard (libs/notification/index.ts).
+//
+// @blocklet/sdk's notification (sendToUser/sendToRelay/sendToMail) and eventbus
+// (publish/subscribe/unsubscribe) throw "BLOCKLET_APP_ID does not exist in
+// environments" off Blocklet Server (arc-node / CF). The guard no-ops both SDK
+// transports there — at the module level, so app-side logic still runs and only
+// the send/publish is skipped — and leaves Blocklet Server untouched. Gated on the
+// single reusable predicate isBlockletServer() (= BLOCKLET_APP_ID present).
+describe('ensureBlockletSdkTransportGuard', () => {
+  const ORIG = process.env.BLOCKLET_APP_ID;
+
+  afterEach(() => {
+    if (ORIG === undefined) delete process.env.BLOCKLET_APP_ID;
+    else process.env.BLOCKLET_APP_ID = ORIG;
+    jest.resetModules();
+  });
+
+  // Fresh module registry per case so the once-only guard flag resets; fresh mock
+  // SDK modules are patched in isolation (no global @blocklet/sdk pollution).
+  function loadAndGuard(): { notification: any; eventbus: any } {
+    let notification: any;
+    let eventbus: any;
+    jest.isolateModules(() => {
+      const notif = { sendToUser: 'REAL', sendToRelay: 'REAL', sendToMail: 'REAL' };
+      notification = { ...notif, default: { ...notif }, getSender: () => ({}) };
+      const evt = { publish: 'REAL', subscribe: 'REAL', unsubscribe: 'REAL' };
+      eventbus = { ...evt, default: { ...evt } };
+      jest.doMock('@blocklet/sdk/service/notification', () => notification);
+      jest.doMock('@blocklet/sdk/service/eventbus', () => eventbus);
+      // eslint-disable-next-line global-require
+      require('../../src/libs/notification').ensureBlockletSdkTransportGuard();
+    });
+    return { notification, eventbus };
+  }
+
+  it('off Blocklet Server (no BLOCKLET_APP_ID): no-ops notification + eventbus on module + default', async () => {
+    delete process.env.BLOCKLET_APP_ID;
+    const { notification, eventbus } = loadAndGuard();
+    for (const target of [notification, notification.default]) {
+      expect(target.sendToUser).not.toBe('REAL');
+      expect(target.sendToRelay).not.toBe('REAL');
+      expect(target.sendToMail).not.toBe('REAL');
+      await expect(target.sendToUser('zUser', { title: 't' })).resolves.toBeUndefined();
+    }
+    for (const target of [eventbus, eventbus.default]) {
+      expect(target.publish).not.toBe('REAL');
+      expect(target.subscribe).not.toBe('REAL');
+      expect(target.unsubscribe).not.toBe('REAL');
+      await expect(target.publish('invoice.paid', {})).resolves.toBeUndefined();
+    }
+  });
+
+  it('on Blocklet Server (BLOCKLET_APP_ID set): leaves both transports intact', () => {
+    process.env.BLOCKLET_APP_ID = 'z_app_pid';
+    const { notification, eventbus } = loadAndGuard();
+    expect(notification.sendToUser).toBe('REAL');
+    expect(notification.default.sendToUser).toBe('REAL');
+    expect(eventbus.publish).toBe('REAL');
+    expect(eventbus.default.publish).toBe('REAL');
+  });
+});

package/api/tests/middlewares/hono/context.spec.ts

@@ -4,7 +4,7 @@
 // header (the fork reads c.req.header('host') — never a proxy header).
 import { Hono } from 'hono';
 import { ensureI18n, contextMiddleware } from '../../../src/middlewares/hono/context';
-import { getInstanceDid } from '../../../src/libs/context';
+import { context, getInstanceDid } from '../../../src/libs/context';
 import { getDefaultInstanceDid } from '../../../src/libs/tenant';
 import {
   setIdentityDriver,
@@ -111,3 +111,31 @@ describe('hono contextMiddleware — multi mode (Host→tenant, fail-closed)', (
     expect(handlerRuns).toBe(0);
   });
 });
+
+describe('hono contextMiddleware — pre-scoped request (CF worker withTenant)', () => {
+  // The CF worker pre-resolves Host→tenant and wraps the core in withTenant, then
+  // sets its identity driver's resolveInstanceDidForHost to null on purpose. A host
+  // that the driver CANNOT resolve must still succeed when a tenant context is
+  // already established — otherwise native routes (/api/settings) 400 with
+  // TENANT_HOST_UNRESOLVED while connect routes (which already honor the context)
+  // work. This pins the native+connect parity.
+  const nullDriver: IdentityDriver = { resolveInstanceDidForHost: () => null };
+
+  beforeEach(() => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    setIdentityDriver(nullDriver);
+  });
+
+  it('honors the pre-established tenant context instead of re-resolving the host', async () => {
+    const app = buildApp();
+    const res = await context.withTenant(TENANT_A, () => get(app, 'todo.localhost:8787'));
+    expect(res.status).toBe(200);
+    expect((await res.json()).tenant).toBe(TENANT_A);
+  });
+
+  it('still fails closed 400 when NO context is pre-established and the host is unresolvable', async () => {
+    const r = await get(buildApp(), 'todo.localhost:8787');
+    expect(r.status).toBe(400);
+    expect((await r.json()).error.code).toBe('TENANT_HOST_UNRESOLVED');
+  });
+});

package/api/tests/queues/starter-tenant-dispatch.spec.ts

@@ -0,0 +1,171 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+
+import { withTenant } from '../../src/libs/context';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+// Layer-2 (build-phases) regression coverage for the boot/cron starter dispatch
+// fix (commit "fix(payment-core): tenant-context safety for boot/cron queue
+// dispatch"). Mirrors event-tenant.spec.ts's startEventQueue case for the FATAL
+// site: startVendorCommissionQueue used forEach(async) + a push outside
+// withTenant, so in multi mode injectJobTenant -> getInstanceDid threw
+// TENANT_CONTEXT_MISSING as an unhandled rejection -> daemon crash on boot.
+
+jest.mock('../../src/libs/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+}));
+
+// neutralize the queue engine (real createQueue scans the jobs table on import,
+// racing the temp DB lifecycle) — same shim event-tenant.spec.ts uses.
+jest.mock('../../src/libs/queue', () => ({
+  __esModule: true,
+  default: () => ({
+    push: jest.fn(),
+    pushAndWait: jest.fn(),
+    cancel: jest.fn(),
+    on: jest.fn(),
+    get: jest.fn().mockResolvedValue(null),
+  }),
+  assertJobObjectTenant: jest.fn(),
+}));
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'starter-dispatch-'));
+const sequelize = new Sequelize({ dialect: 'sqlite', storage: path.join(dir, 'test.db'), logging: false });
+const umzug = new Umzug({
+  migrations: {
+    glob: ['migrations/*.ts', { cwd: STORE_DIR }],
+    resolve: ({ name, path: p, context }) => {
+      // eslint-disable-next-line import/no-dynamic-require, global-require
+      const migration = require(p!);
+      return {
+        name: name.replace(/\.ts$/, '.js'),
+        up: () => migration.up({ context }),
+        down: () => migration.down({ context }),
+      };
+    },
+  },
+  context: sequelize.getQueryInterface(),
+  storage: new SequelizeStorage({ sequelize }),
+  logger: undefined,
+});
+
+let models: any;
+let startVendorCommissionQueue: any;
+let vendorCommissionQueue: any;
+let getInstanceDid: any;
+let logger: any;
+
+beforeAll(async () => {
+  await umzug.up();
+  // eslint-disable-next-line global-require
+  models = require('../../src/store/models');
+  models.initialize(sequelize);
+  // eslint-disable-next-line global-require
+  ({ startVendorCommissionQueue, vendorCommissionQueue } = require('../../src/queues/vendors/commission'));
+  // eslint-disable-next-line global-require
+  ({ getInstanceDid } = require('../../src/libs/context'));
+  // eslint-disable-next-line global-require
+  logger = require('../../src/libs/logger').default;
+}, 120000);
+
+afterAll(async () => {
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const seedPI = (tenant: string, invoiceId: string) =>
+  withTenant(tenant, () =>
+    models.PaymentIntent.create({
+      instance_did: tenant,
+      livemode: false,
+      amount: '100',
+      currency_id: 'cur_test',
+      payment_method_id: 'pm_test',
+      status: 'requires_capture',
+      capture_method: 'automatic',
+      confirmation_method: 'automatic',
+      invoice_id: invoiceId,
+    })
+  );
+
+const ORIGINAL_MODE = process.env.PAYMENT_TENANT_MODE;
+beforeEach(async () => {
+  jest.clearAllMocks();
+  await sequelize.query('DELETE FROM payment_intents');
+});
+afterEach(() => {
+  if (ORIGINAL_MODE === undefined) delete process.env.PAYMENT_TENANT_MODE;
+  else process.env.PAYMENT_TENANT_MODE = ORIGINAL_MODE;
+});
+
+describe('startVendorCommissionQueue — per-tenant boot dispatch (multi-tenant)', () => {
+  it('multi mode: each tenant intent is enqueued INSIDE its own tenant (no crash, correct stamp)', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    await seedPI(TENANT_A, 'inv_a');
+    await seedPI(TENANT_B, 'inv_b');
+
+    // the push captures the tenant injectJobTenant would read (getInstanceDid).
+    // would THROW in multi mode if the push ran outside withTenant (the old bug).
+    const stamps: Record<string, string> = {};
+    let threw = false;
+    (vendorCommissionQueue.push as jest.Mock).mockImplementation((arg: any) => {
+      try {
+        stamps[arg.id] = getInstanceDid();
+      } catch {
+        threw = true;
+      }
+    });
+
+    await expect(startVendorCommissionQueue()).resolves.toBeUndefined();
+
+    expect(threw).toBe(false);
+    expect(vendorCommissionQueue.push).toHaveBeenCalledTimes(2);
+    expect(stamps['vendor-commission-inv_a']).toBe(TENANT_A);
+    expect(stamps['vendor-commission-inv_b']).toBe(TENANT_B);
+  });
+
+  it('multi mode: a tenant-less intent is isolated by the per-row catch — pass does not crash', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    const pi = await seedPI(TENANT_A, 'inv_a');
+    // null the tenant directly (bypass the scoped writer)
+    await sequelize.query('UPDATE payment_intents SET instance_did = NULL WHERE id = $id', {
+      bind: { id: pi.id },
+    });
+
+    // a tenant-less row runs dispatch() with NO withTenant; the real push's
+    // injectJobTenant -> getInstanceDid throws in multi mode. Simulate that here.
+    (vendorCommissionQueue.push as jest.Mock).mockImplementation(() => {
+      getInstanceDid();
+    });
+
+    // the per-row try/catch must absorb it — the starter resolves, never rejects.
+    await expect(startVendorCommissionQueue()).resolves.toBeUndefined();
+    expect(logger.error).toHaveBeenCalledWith(
+      'startVendorCommissionQueue: re-queue failed',
+      expect.objectContaining({ invoiceId: 'inv_a' })
+    );
+  });
+
+  it('single mode: enqueues without a tenant context (default tenant), no throw', async () => {
+    delete process.env.PAYMENT_TENANT_MODE; // single
+    await seedPI(TENANT_A, 'inv_a');
+
+    let threw = false;
+    (vendorCommissionQueue.push as jest.Mock).mockImplementation(() => {
+      try {
+        getInstanceDid();
+      } catch {
+        threw = true;
+      }
+    });
+
+    await expect(startVendorCommissionQueue()).resolves.toBeUndefined();
+    expect(threw).toBe(false);
+    expect(vendorCommissionQueue.push).toHaveBeenCalledTimes(1);
+  });
+});

package/api/tests/routes/hono/bootstrap.spec.ts

@@ -0,0 +1,87 @@
+// Unit test for the on-demand bootstrap endpoint (routes/hono/bootstrap.ts).
+// The handler is isolated from its heavy deps: bootstrapTenant (service), the
+// arcblock stake helpers, the models, the business wallet, and tenant context are
+// mocked, and `authenticate` is stubbed to a pass-through (auth gating itself is
+// covered by middlewares/hono/security.spec.ts). This keeps the test DB-free while
+// pinning the handler contract: it runs the idempotent bootstrap for the current
+// tenant and reports per-chain stake status.
+const bootstrapTenant = jest.fn(async () => {});
+jest.mock('../../../src/service', () => ({ bootstrapTenant }));
+
+const findAll = jest.fn(async () => [] as any[]);
+jest.mock('../../../src/store/models', () => ({ PaymentMethod: { findAll } }));
+
+const hasStakedForGas = jest.fn(async () => false);
+jest.mock('../../../src/integrations/arcblock/stake', () => ({ hasStakedForGas }));
+
+jest.mock('../../../src/libs/auth', () => ({ wallet: { address: 'zAppWalletTest' } }));
+jest.mock('../../../src/libs/context', () => ({ getInstanceDid: () => 'did:abt:zTenantTest' }));
+jest.mock('../../../src/middlewares/hono/security', () => ({
+  authenticate: () => (_c: any, next: any) => next(),
+}));
+
+import { Hono } from 'hono';
+import bootstrap from '../../../src/routes/hono/bootstrap';
+
+const app = new Hono();
+app.route('/api/bootstrap', bootstrap);
+const get = () => app.fetch(new Request('http://app.local/api/bootstrap', { headers: { host: 'app.local' } }));
+
+beforeEach(() => {
+  bootstrapTenant.mockClear();
+  findAll.mockReset().mockResolvedValue([]);
+  hasStakedForGas.mockReset().mockResolvedValue(false);
+});
+
+describe('GET /api/bootstrap — on-demand idempotent bootstrap', () => {
+  it('runs bootstrapTenant for the current tenant and returns a status report', async () => {
+    const r = await get();
+    expect(r.status).toBe(200);
+    const body = await r.json();
+    expect(body).toMatchObject({
+      ok: true,
+      instanceDid: 'did:abt:zTenantTest',
+      appWallet: 'zAppWalletTest',
+      chains: [],
+    });
+    expect(bootstrapTenant).toHaveBeenCalledWith('did:abt:zTenantTest');
+    expect(bootstrapTenant).toHaveBeenCalledTimes(1);
+  });
+
+  it('is idempotent — repeated calls re-run the bootstrap and keep succeeding', async () => {
+    await get();
+    const r2 = await get();
+    expect(r2.status).toBe(200);
+    expect((await r2.json()).ok).toBe(true);
+    expect(bootstrapTenant).toHaveBeenCalledTimes(2);
+  });
+
+  it('reports declared/balance/stakedForGas per arcblock method', async () => {
+    const getAccountState = jest.fn(async () => ({ state: { balance: '100' } }));
+    findAll.mockResolvedValueOnce([
+      {
+        name: 'ArcBlock Beta',
+        settings: { arcblock: { api_host: 'https://beta.abtnetwork.io/api/' } },
+        getOcapClient: () => ({ getAccountState }),
+      } as any,
+    ]);
+    hasStakedForGas.mockResolvedValueOnce(true);
+
+    const r = await get();
+    const body = await r.json();
+    expect(body.chains[0]).toMatchObject({
+      method: 'ArcBlock Beta',
+      host: 'https://beta.abtnetwork.io/api/',
+      declared: true,
+      balance: '100',
+      stakedForGas: true,
+    });
+  });
+
+  it('fails closed with 500 + message when the bootstrap throws', async () => {
+    bootstrapTenant.mockRejectedValueOnce(new Error('chain down'));
+    const r = await get();
+    expect(r.status).toBe(500);
+    expect(await r.json()).toMatchObject({ ok: false, instanceDid: 'did:abt:zTenantTest', error: 'chain down' });
+  });
+});

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.29.4
+version: 1.29.6
 logo: logo.png
 files:
   - dist

package/cloudflare/cf-adapter.ts

@@ -39,6 +39,7 @@ import crons from '../api/src/crons/index';
 import { createEmbeddedPaymentService } from '../api/src/service';
 import type { EmbeddedPaymentService } from '../api/src/service';
 import { context as requestContext } from '../api/src/libs/context';
+import { warmTenantIdentity } from '../api/src/libs/did-connect/tenant-identity';
 import {
   createD1DbDriver,
   createD1LocksDriver,
@@ -231,7 +232,19 @@ export function buildFetch(deps: FetchDeps) {
     // the core's connect/context middleware then resolves via the identity driver,
     // which returns null → TENANT_HOST_UNRESOLVED 4xx (multi-mode fail-closed). The
     // bare health route still answers without a tenant.
-    const run = () => deps.svc.http.fetch(forwarded, { basePath: deps.basePath });
+    //
+    // Warm the tenant identity (app:ek + business wallets) INSIDE the withTenant
+    // scope before any route handler runs. The CF resource pipeline is the LITE
+    // app-shell (no contextMiddleware), so unlike the node host nothing else warms
+    // it — and wallet field access (e.g. `wallet.publicKey` in GET /api/vendors) is
+    // a SYNCHRONOUS getCachedTenantIdentity() that fails-closed on a cold cache.
+    // Best-effort (warmTenantIdentity swallows errors); cached 5 min per tenant so
+    // only the first request per window pays the RPC. Queue jobs / bootstrapTenant
+    // already warm on their own paths.
+    const run = async () => {
+      if (instanceDid) await warmTenantIdentity(instanceDid);
+      return deps.svc.http.fetch(forwarded, { basePath: deps.basePath });
+    };
     const res = instanceDid ? await requestContext.withTenant(instanceDid, run) : await run();
 
     await deps.flush(); // drain workerd deferred queue work before responding

package/cloudflare/esbuild-cf-config.cjs

@@ -288,8 +288,17 @@ const alias = {
   'crypto-js/enc-utf8': s('shims/noop.ts'),
   'crypto-js/enc-utf16': s('shims/noop.ts'),
 
-  // Force ESM-only to avoid CJS+ESM double-bundling
+  // Force ESM-only to avoid CJS+ESM double-bundling. These packages ship an
+  // exports map with separate import/require conditions, so esbuild picks the
+  // condition by call kind — and the payment graph reaches them via BOTH `import`
+  // (business code) and `require` (source require('ethers') + CJS @ocap/* deps),
+  // pulling two full copies. Pinning each bare specifier straight at its ESM
+  // entry (bypassing the exports map, like require.resolve can't — see valibot)
+  // collapses the duplicate. Measured on dist/cf.js: 1236KB → 1028KB gzip (-17%).
   valibot: path.resolve(cfDir, '../../..', 'node_modules/valibot/dist/index.mjs'), // 396KB → ~200KB
+  ethers: path.resolve(cfDir, '../../..', 'node_modules/ethers/lib.esm/index.js'), // 767KB(cjs406+esm267) → 299KB; also drops the lib.commonjs/wordlists the esm-only dropEthersWordlists plugin never matched
+  'aes-js': path.resolve(cfDir, '../../..', 'node_modules/aes-js/lib.esm/index.js'), // 90KB → 42KB (CJS copy pulled by ethers/json-keystore + @ocap)
+  '@adraffy/ens-normalize': path.resolve(cfDir, '../../..', 'node_modules/@adraffy/ens-normalize/dist/index.mjs'), // 73KB → 36KB (CJS copy pulled by ethers/hash/namehash)
   // CF Workers: noop modules not useful in Workers environment
   phoenix: s('shims/noop.ts'), // 36KB — Phoenix channels, only used by @arcblock/ws
   numbro: s('shims/noop.ts'), // 49KB — number formatting, replaced inline in util.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.29.4",
+  "version": "1.29.6",
   "scripts": {
     "dev": "blocklet dev --open",
     "prelint": "npm run types",
@@ -49,7 +49,7 @@
     "@abtnode/cron": "^1.17.13-beta-20260613-094425-b81920c8",
     "@apple/app-store-server-library": "^3.1.0",
     "@arcblock/did": "^1.30.24",
-    "@arcblock/did-connect-js": "^4.0.6",
+    "@arcblock/did-connect-js": "^4.0.7",
     "@arcblock/did-connect-react": "^3.5.4",
     "@arcblock/did-connect-storage-nedb": "^1.8.0",
     "@arcblock/did-util": "^1.30.24",
@@ -61,9 +61,9 @@
     "@blocklet/error": "^0.3.5",
     "@blocklet/js-sdk": "^1.17.13-beta-20260613-094425-b81920c8",
     "@blocklet/logger": "^1.17.13-beta-20260613-094425-b81920c8",
-    "@blocklet/payment-broker-client": "1.29.4",
-    "@blocklet/payment-react": "1.29.4",
-    "@blocklet/payment-vendor": "1.29.4",
+    "@blocklet/payment-broker-client": "1.29.6",
+    "@blocklet/payment-react": "1.29.6",
+    "@blocklet/payment-vendor": "1.29.6",
     "@blocklet/sdk": "^1.17.13-beta-20260613-094425-b81920c8",
     "@blocklet/ui-react": "^3.5.4",
     "@blocklet/uploader": "^0.3.20",
@@ -135,7 +135,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.17.13-beta-20260613-094425-b81920c8",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.29.4",
+    "@blocklet/payment-types": "1.29.6",
     "@types/connect": "^3.4.38",
     "@types/debug": "^4.1.12",
     "@types/dotenv-flow": "^3.3.3",
@@ -183,5 +183,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "ffde8059827d7688a7e5a1e65830912e9093bb7c"
+  "gitHead": "ee97756d3e9ba56def933580a6cb6bb93d97b55c"
 }