mppx 0.17.3 → 0.17.4

package/dist/tempo/Methods.js

@@ -2,6 +2,7 @@ import { parseUnits } from 'viem';
 import * as Constants from '../Constants.js';
 import * as Method from '../Method.js';
 import * as z from '../zod.js';
+import * as Zone from './internal/zone.js';
 export const chargeModes = ['push', 'pull'];
 const split = z.object({
     amount: z.amount(),
@@ -79,6 +80,12 @@ export const charge = Method.from({
                 z.object({ hash: z.hash(), type: z.literal('hash') }),
                 z.object({ signature: z.signature(), type: z.literal('transaction') }),
                 z.object({ signature: z.signature(), type: z.literal('proof') }),
+                z.object({
+                    hash: z.hash(),
+                    senderTag: z.hash(),
+                    type: z.literal('zone'),
+                    zoneId: z.number().check(z.refine(Zone.isId, 'Invalid Zone ID')),
+                }),
             ]),
         },
         request: z.pipe(z
@@ -95,6 +102,13 @@ export const charge = Method.from({
             recipient: z.optional(z.string()),
             splits: z.optional(z.array(split).check(z.minLength(1), z.maxLength(10))),
             supportedModes: z.optional(z.array(z.enum(chargeModes)).check(z.minLength(1))),
+            // Zone IDs the payee accepts withdrawals from, or true for any Zone on the challenge's chain.
+            zones: z.optional(z.union([
+                z.literal(true),
+                z
+                    .array(z.number().check(z.refine(Zone.isId, 'Invalid Zone ID')))
+                    .check(z.minLength(1)),
+            ])),
         })
             .check(z.refine(({ amount, decimals, splits }) => {
             if (!splits)
@@ -103,14 +117,15 @@ export const charge = Method.from({
             const splitTotal = splits.reduce((sum, split) => sum + parseUnits(split.amount, decimals), 0n);
             return (splits.every((split) => parseUnits(split.amount, decimals) > 0n) &&
                 splitTotal < totalAmount);
-        }, 'Invalid splits')), z.transform(({ machineTokenEnabled, amount, chainId, decimals, feePayer, memo: _memo, splits, supportedModes, ...rest }) => ({
+        }, 'Invalid splits')), z.transform(({ machineTokenEnabled, amount, chainId, decimals, feePayer, memo: _memo, splits, supportedModes, zones, ...rest }) => ({
             ...rest,
             amount: parseUnits(amount, decimals).toString(),
             ...(machineTokenEnabled !== undefined ||
                 chainId !== undefined ||
                 feePayer !== undefined ||
                 splits !== undefined ||
-                supportedModes !== undefined
+                supportedModes !== undefined ||
+                zones !== undefined
                 ? {
                     methodDetails: {
                         ...(machineTokenEnabled !== undefined && { machineTokenEnabled }),
@@ -123,6 +138,7 @@ export const charge = Method.from({
                             })),
                         }),
                         ...(supportedModes !== undefined && { supportedModes }),
+                        ...(zones !== undefined && { zones }),
                     },
                 }
                 : {}),

package/dist/tempo/client/Charge.d.ts

@@ -1,4 +1,4 @@
-import { type Address } from 'viem';
+import { type Address, type Client as viem_Client } from 'viem';
 import * as Method from '../../Method.js';
 import * as Account from '../../viem/Account.js';
 import * as Client from '../../viem/Client.js';
@@ -61,6 +61,11 @@ export declare function charge(parameters?: charge.Parameters): {
             }, z.core.$strip>, z.ZodMiniObject<{
                 signature: z.ZodMiniString<string>;
                 type: z.ZodMiniLiteral<"proof">;
+            }, z.core.$strip>, z.ZodMiniObject<{
+                hash: z.ZodMiniString<string>;
+                senderTag: z.ZodMiniString<string>;
+                type: z.ZodMiniLiteral<"zone">;
+                zoneId: z.ZodMiniNumber<number>;
             }, z.core.$strip>], "type">;
         };
         request: z.ZodMiniPipe<z.ZodMiniObject<{
@@ -83,6 +88,7 @@ export declare function charge(parameters?: charge.Parameters): {
                 pull: "pull";
                 push: "push";
             }>>>;
+            zones: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniLiteral<true>, z.ZodMiniArray<z.ZodMiniNumber<number>>]>>;
         }, z.core.$strip>, z.ZodMiniTransform<{
             currency: string;
             description?: string | undefined;
@@ -99,6 +105,7 @@ export declare function charge(parameters?: charge.Parameters): {
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -117,6 +124,7 @@ export declare function charge(parameters?: charge.Parameters): {
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
     readonly createCredential: Method.CreateCredentialFn<{
@@ -133,6 +141,11 @@ export declare function charge(parameters?: charge.Parameters): {
                 }, z.core.$strip>, z.ZodMiniObject<{
                     signature: z.ZodMiniString<string>;
                     type: z.ZodMiniLiteral<"proof">;
+                }, z.core.$strip>, z.ZodMiniObject<{
+                    hash: z.ZodMiniString<string>;
+                    senderTag: z.ZodMiniString<string>;
+                    type: z.ZodMiniLiteral<"zone">;
+                    zoneId: z.ZodMiniNumber<number>;
                 }, z.core.$strip>], "type">;
             };
             request: z.ZodMiniPipe<z.ZodMiniObject<{
@@ -155,6 +168,7 @@ export declare function charge(parameters?: charge.Parameters): {
                     pull: "pull";
                     push: "push";
                 }>>>;
+                zones: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniLiteral<true>, z.ZodMiniArray<z.ZodMiniNumber<number>>]>>;
             }, z.core.$strip>, z.ZodMiniTransform<{
                 currency: string;
                 description?: string | undefined;
@@ -171,6 +185,7 @@ export declare function charge(parameters?: charge.Parameters): {
                         amount: string;
                     }[] | undefined;
                     supportedModes?: ("pull" | "push")[] | undefined;
+                    zones?: true | number[] | undefined;
                 } | undefined;
             }, {
                 machineTokenEnabled?: boolean | undefined;
@@ -189,6 +204,7 @@ export declare function charge(parameters?: charge.Parameters): {
                     recipient: `0x${string}`;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             }>>;
         };
     }, {
@@ -203,6 +219,15 @@ export declare namespace charge {
     type Context = ChargeContext;
     type ResolveAccount = AccountResolution.ResolveAccount;
     type ResolveAccountInfo = AccountResolution.ResolveAccountInfo;
+    /** Pays from a Zone balance when a challenge accepts that Zone. */
+    type Zone = {
+        /** Client for the Zone chain, with the paying account and Zone RPC authorization. */
+        client: viem_Client;
+        /** Zone ID. Derived from `client.chain.id` when omitted. */
+        zoneId?: number | undefined;
+        /** Milliseconds to wait for the withdrawal to settle on Tempo. @default 60_000 */
+        settlementTimeoutMs?: number | undefined;
+    };
     type Parameters = {
         /**
          * Automatically swap from a fallback currency (pathUsd, USDC.e) via the
@@ -277,6 +302,12 @@ export declare namespace charge {
         mode?: Methods.ChargeMode | undefined;
         /** Selects the account that signs this charge after the challenge and chain are known. */
         resolveAccount?: ResolveAccount | undefined;
+        /**
+         * Pays from a Zone balance instead of the account's Tempo balance when the
+         * challenge accepts this Zone (`methodDetails.zones`). Other challenges,
+         * and split payments, are paid on Tempo as usual.
+         */
+        zone?: Zone | undefined;
     } & Account.getResolver.Parameters & Client.getResolver.Parameters;
 }
 //# sourceMappingURL=Charge.d.ts.map

package/dist/tempo/client/Charge.js

@@ -1,10 +1,11 @@
 import { TxEnvelopeTempo } from 'ox/tempo';
-import { keccak256, parseUnits } from 'viem';
-import { prepareTransactionRequest, sendCallsSync, sendTransactionSync, signTypedData, signTransaction, } from 'viem/actions';
-import { Actions } from 'viem/tempo';
+import { keccak256, parseEventLogs, parseUnits, } from 'viem';
+import { prepareTransactionRequest, sendCallsSync, sendRawTransactionSync, sendTransactionSync, signTypedData, signTransaction, waitForTransactionReceipt, } from 'viem/actions';
+import { Abis, Actions, Addresses } from 'viem/tempo';
 import { tempo as tempo_chain } from 'viem/tempo/chains';
 import * as MethodResponse from '../../client/internal/MethodResponse.js';
 import * as Credential from '../../Credential.js';
+import * as Errors from '../../Errors.js';
 import * as Method from '../../Method.js';
 import * as Account from '../../viem/Account.js';
 import * as Client from '../../viem/Client.js';
@@ -16,6 +17,7 @@ import * as defaults from '../internal/defaults.js';
 import { defaultFeeTokens, resolveFeeToken } from '../internal/fee-token.js';
 import * as MachineTokenCharge from '../internal/machine-token-charge.js';
 import * as Proof from '../internal/proof.js';
+import * as Zone from '../internal/zone.js';
 import * as Methods from '../Methods.js';
 /**
  * Seconds from now the client sets as the expiring-nonce `validBefore`,
@@ -63,6 +65,9 @@ export function charge(parameters = {}) {
         rpcUrl: defaults.rpcUrl,
     });
     const getAccount = Account.getResolver({ account: parameters.account });
+    assertZone(parameters.zone);
+    // Zone withdrawals still settling, by challenge ID, so a retry resumes waiting instead of paying again.
+    const pendingZoneWithdrawals = new Map();
     const method = Method.toClient(Methods.charge, {
         // Skip offers that violate client policy so an acceptable offer can be chosen.
         canHandleChallenge({ challenge }) {
@@ -91,6 +96,36 @@ export function charge(parameters = {}) {
             const { request } = challenge;
             const { amount, methodDetails } = request;
             const supportedModes = methodDetails?.supportedModes ?? ['pull', 'push'];
+            const zoneChain = parameters.zone?.client.chain;
+            const zoneId = parameters.zone
+                ? (parameters.zone.zoneId ?? Zone.idFromChainId(zoneChain?.id ?? 0))
+                : undefined;
+            // A Zone ID is only unique per parent chain, so the Zone must settle on the challenge's chain.
+            const zoneParentChainId = zoneChain?.sourceId ??
+                (zoneChain ? Zone.parentChainIdFromChainId(zoneChain.id) : undefined);
+            const explicitMode = context?.mode ?? parameters.mode;
+            // Pay from a Zone balance when the challenge accepts the configured Zone.
+            // Zone payments are push payments, so they follow the challenge's and client's modes.
+            if (BigInt(amount) > 0n &&
+                parameters.zone &&
+                zoneId !== undefined &&
+                zoneParentChainId === chainId &&
+                supportedModes.includes('push') &&
+                (explicitMode === undefined || explicitMode === 'push') &&
+                Zone.isAccepted(methodDetails?.zones, zoneId) &&
+                !methodDetails?.splits &&
+                // A withdrawal can't be undone, so start one only when it can settle before the
+                // challenge expires; an expired challenge would invite another payment.
+                (pendingZoneWithdrawals.has(zoneWithdrawalKey(challenge)) ||
+                    settlesBeforeExpiry(challenge.expires, parameters.zone.settlementTimeoutMs)))
+                return createZoneCredential({
+                    challenge,
+                    clientId,
+                    client,
+                    pending: pendingZoneWithdrawals,
+                    zone: parameters.zone,
+                    zoneId,
+                });
             const defaultAccount = getAccount(client, context);
             const resolveAccount = async (operation) => (await parameters.resolveAccount?.({
                 account: defaultAccount,
@@ -326,6 +361,8 @@ function transactionHash(credential) {
     const payload = parsed.data;
     if (payload.type === 'hash')
         return payload.hash;
+    if (payload.type === 'zone')
+        return payload.hash;
     const serialized = payload.signature;
     if (payload.type !== 'transaction' || !serialized.startsWith(TxEnvelopeTempo.serializedType))
         return undefined;
@@ -337,6 +374,167 @@ function transactionHash(credential) {
         return undefined;
     return keccak256(serialized);
 }
+/**
+ * Pays a challenge from a Zone balance: requests a withdrawal to the recipient
+ * with the challenge-bound memo, and returns a `zone` credential that names it
+ * by sender tag and the Tempo transaction hash that settled it.
+ */
+async function createZoneCredential(options) {
+    const { challenge, client, pending, zone, zoneId } = options;
+    const request = challenge.request;
+    const recipient = request.recipient;
+    // The whole challenge, so a challenge from another realm or request with the same ID never matches.
+    const key = zoneWithdrawalKey(challenge);
+    // A withdrawal can't be undone, so a retry after a failed wait resumes it instead of paying again.
+    // Concurrent calls for one challenge share the request, which is stored before it is sent.
+    let withdrawalRequest = pending.get(key);
+    if (!withdrawalRequest) {
+        const state = { sent: false };
+        withdrawalRequest = requestZoneWithdrawal(options, state);
+        pending.set(key, withdrawalRequest);
+        // Only a failure before the transaction was sent is safe to retry. After that, the
+        // withdrawal may have gone through, so retries of this challenge keep failing.
+        withdrawalRequest.catch(() => {
+            if (!state.sent)
+                pending.delete(key);
+        });
+    }
+    const senderTag = await withdrawalRequest;
+    let hash;
+    try {
+        hash = await Zone.waitForSettlement(client, {
+            portal: Zone.portalAddress(zoneId),
+            senderTag,
+            timeoutMs: settlementTimeoutMs(challenge.expires, zone.settlementTimeoutMs),
+            to: recipient,
+        });
+    }
+    catch (cause) {
+        throw new Errors.ZoneSettlementPendingError({
+            cause,
+            challengeId: challenge.id,
+            senderTag,
+            zoneId,
+        });
+    }
+    pending.delete(key);
+    return Credential.serialize({
+        challenge,
+        payload: { hash, senderTag, type: 'zone', zoneId },
+    });
+}
+/**
+ * Throws on Zone options that would fail only after an irreversible withdrawal:
+ * a `settlementTimeoutMs` that is not a finite, non-negative number, or a
+ * `zoneId` that names a different Zone from the one `zone.client` serves.
+ */
+function assertZone(zone) {
+    const timeoutMs = zone?.settlementTimeoutMs;
+    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0))
+        throw new Error('`zone.settlementTimeoutMs` must be a finite, non-negative number.');
+    const chainId = zone?.client.chain?.id;
+    if (zone?.zoneId === undefined || chainId === undefined)
+        return;
+    // Only chain IDs that follow a known Zone scheme name their Zone.
+    if (Zone.parentChainIdFromChainId(chainId) === undefined)
+        return;
+    const derived = Zone.idFromChainId(chainId);
+    if (derived !== zone.zoneId)
+        throw new Error(`zone.zoneId ${zone.zoneId} does not match Zone ${derived} of the zone.client chain ${chainId}.`);
+}
+/** Time the client allows for sending a Zone withdrawal before it waits for settlement. */
+const zoneSubmissionMarginMs = 15_000;
+/**
+ * Returns whether a Zone withdrawal can be sent and waited on for up to
+ * `settlementTimeoutMs` before `expires`.
+ */
+function settlesBeforeExpiry(expires, settlementTimeoutMs) {
+    if (!expires)
+        return true;
+    const timeoutMs = settlementTimeoutMs ?? Zone.defaultSettlementTimeoutMs;
+    return new Date(expires).getTime() - Date.now() > timeoutMs + zoneSubmissionMarginMs;
+}
+/** Returns how long to wait for settlement: `settlementTimeoutMs`, cut short at `expires`. */
+function settlementTimeoutMs(expires, settlementTimeoutMs) {
+    const timeoutMs = settlementTimeoutMs ?? Zone.defaultSettlementTimeoutMs;
+    if (!expires)
+        return timeoutMs;
+    return Math.max(0, Math.min(timeoutMs, new Date(expires).getTime() - Date.now()));
+}
+/** Keys a Zone withdrawal by its whole Challenge. Unlike `Challenge.serialize`, it accepts any field value. */
+function zoneWithdrawalKey(challenge) {
+    return JSON.stringify(challenge);
+}
+/** How long to look for a withdrawal's receipt on the Zone after its send response fails. */
+const zoneReceiptRecoveryTimeoutMs = 15_000;
+/** Requests a Zone withdrawal of the challenge amount to its recipient, bound to the challenge by its memo. */
+async function requestZoneWithdrawal(options, state) {
+    const { challenge, clientId, zone } = options;
+    const request = challenge.request;
+    const account = zone.client.account;
+    if (!account)
+        throw new Error('`zone.client` requires an account.');
+    const amount = BigInt(request.amount);
+    const currency = request.currency;
+    const recipient = request.recipient;
+    const memo = Attribution.encode({
+        challengeId: challenge.id,
+        clientId,
+        serverId: challenge.realm,
+    });
+    // The outbox pulls the amount plus its withdrawal fee.
+    const fee = await Actions.zone.getWithdrawalFee(zone.client);
+    const [, withdrawal] = Actions.zone.requestWithdrawal.calls({
+        amount,
+        // A bounced payout refunds the payer, not the payee's Zone address.
+        fallbackRecipient: account.address,
+        memo,
+        to: recipient,
+        token: currency,
+    });
+    // Prepare and sign first: a failure there sent nothing, so the challenge may be retried.
+    const prepared = await prepareTransactionRequest(zone.client, {
+        account,
+        calls: [
+            Actions.token.approve.call({
+                amount: amount + fee,
+                spender: Addresses.zoneOutbox,
+                token: currency,
+            }),
+            withdrawal,
+        ],
+    });
+    const serializedTransaction = await signTransaction(zone.client, prepared);
+    state.sent = true;
+    // The signed transaction fixes its hash, so a lost send response can still be recovered from the Zone.
+    const hash = keccak256(serializedTransaction);
+    const receipt = await sendRawTransactionSync(zone.client, { serializedTransaction }).catch((cause) => waitForTransactionReceipt(zone.client, {
+        hash,
+        timeout: zoneReceiptRecoveryTimeoutMs,
+    }).catch(() => {
+        const error = new Error(`Zone withdrawal outcome is unknown: transaction ${hash} may have been sent. Retrying this challenge does not withdraw again.`);
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        Object.defineProperty(error, 'cause', { configurable: true, value: cause, writable: true });
+        throw error;
+    }));
+    // A reverted withdrawal moved nothing, so the challenge may be retried.
+    if (receipt.status === 'reverted') {
+        state.sent = false;
+        throw new Error(`Zone withdrawal transaction ${receipt.transactionHash} reverted.`);
+    }
+    const [requested] = parseEventLogs({
+        abi: Abis.zoneOutbox,
+        eventName: 'WithdrawalRequested',
+        logs: receipt.logs,
+    });
+    if (!requested)
+        throw new Error('Zone withdrawal request did not emit `WithdrawalRequested`.');
+    return Zone.senderTag({
+        fallbackNonce: requested.args.fallbackNonce,
+        sender: requested.args.sender,
+        transactionHash: receipt.transactionHash,
+    });
+}
 /** Parses `maxAmount` to base units, rejecting values that cannot be represented exactly. */
 function parseMaxAmount(maxAmount, decimals) {
     if (maxAmount === undefined)

package/dist/tempo/client/Methods.d.ts

@@ -43,6 +43,11 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
             }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniObject<{
                 signature: import("zod/mini").ZodMiniString<string>;
                 type: import("zod/mini").ZodMiniLiteral<"proof">;
+            }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniObject<{
+                hash: import("zod/mini").ZodMiniString<string>;
+                senderTag: import("zod/mini").ZodMiniString<string>;
+                type: import("zod/mini").ZodMiniLiteral<"zone">;
+                zoneId: import("zod/mini").ZodMiniNumber<number>;
             }, import("zod/v4/core").$strip>], "type">;
         };
         request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
@@ -65,6 +70,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
                 pull: "pull";
                 push: "push";
             }>>>;
+            zones: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniUnion<readonly [import("zod/mini").ZodMiniLiteral<true>, import("zod/mini").ZodMiniArray<import("zod/mini").ZodMiniNumber<number>>]>>;
         }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniTransform<{
             currency: string;
             description?: string | undefined;
@@ -81,6 +87,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -99,6 +106,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
     readonly createCredential: import("../../Method.js").CreateCredentialFn<{
@@ -115,6 +123,11 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
                 }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniObject<{
                     signature: import("zod/mini").ZodMiniString<string>;
                     type: import("zod/mini").ZodMiniLiteral<"proof">;
+                }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniObject<{
+                    hash: import("zod/mini").ZodMiniString<string>;
+                    senderTag: import("zod/mini").ZodMiniString<string>;
+                    type: import("zod/mini").ZodMiniLiteral<"zone">;
+                    zoneId: import("zod/mini").ZodMiniNumber<number>;
                 }, import("zod/v4/core").$strip>], "type">;
             };
             request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
@@ -137,6 +150,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
                     pull: "pull";
                     push: "push";
                 }>>>;
+                zones: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniUnion<readonly [import("zod/mini").ZodMiniLiteral<true>, import("zod/mini").ZodMiniArray<import("zod/mini").ZodMiniNumber<number>>]>>;
             }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniTransform<{
                 currency: string;
                 description?: string | undefined;
@@ -153,6 +167,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
                         amount: string;
                     }[] | undefined;
                     supportedModes?: ("pull" | "push")[] | undefined;
+                    zones?: true | number[] | undefined;
                 } | undefined;
             }, {
                 machineTokenEnabled?: boolean | undefined;
@@ -171,6 +186,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [{
                     recipient: `0x${string}`;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             }>>;
         };
     }, {

package/dist/tempo/internal/fee-payer.d.ts

@@ -124,31 +124,6 @@ export type PreflightSponsorship = {
  * Returns `undefined` when the envelope's fee payer cannot sign locally.
  */
 export declare function signFeePayerSimulation(transaction: SponsoredTransaction): Promise<Signature.Signature | undefined>;
-/**
- * Runs the sender and final-envelope simulations around sponsorship.
- *
- * First, it simulates the sender's calls at the transaction's exact gas limit
- * with zero fee fields (see {@link simulationTransaction}). This is the
- * gas-bounded check at the broadcast limit, and needs no fee-token balance.
- * Next, `complete` resolves the sponsor and produces the co-signed transaction.
- * Finally, it simulates that transaction with its concrete fee payer, fee token
- * and fee payer signature, so the node bills the sponsor rather than the sender
- * and checks the sponsor's fee balance.
- *
- * A sponsored `eth_call` charges more gas than the mined transaction uses. A
- * local fee payer therefore signs a simulation-only copy whose gas is raised by
- * up to {@link sponsoredSimulationGasBuffer}, clamped so the copy stays within
- * the same fee payer `policy` (`maxGas`, `maxTotalFee`) as the real
- * transaction. The copy is never returned or broadcast. When the final
- * simulation runs without the full buffer (hosted signatures cover the client's
- * gas and cannot be padded, or the padding was clamped), a failure that is only
- * out of gas is tolerated, since the sender simulation already bounded gas at
- * the broadcast limit. Every other failure, such as an insufficient fee balance
- * or a revert, is rethrown.
- *
- * `complete` runs only after sender-context execution succeeds, so a reverting
- * transaction never reaches a local signer or hosted fee-payer.
- */
 export declare function preflightSponsorship<sponsorship extends PreflightSponsorship>(parameters: {
     complete: () => Promise<sponsorship>;
     /** The fee payer policy the completed transaction was checked against. */

package/dist/tempo/internal/fee-payer.js

@@ -2,6 +2,7 @@ import { Address, Secp256k1, Signature } from 'ox';
 import { TempoAddress, TxEnvelopeTempo } from 'ox/tempo';
 import { decodeFunctionData, encodeFunctionData, maxUint256, toFunctionSelector, toHex } from 'viem';
 import { Abis, Addresses, Transaction } from 'viem/tempo';
+import { PaymentSimulationError } from '../../Errors.js';
 import { escrowAbi as legacyEscrowAbi } from '../legacy/session/escrow.abi.js';
 import { escrowAbi } from '../session/precompile/escrow.abi.js';
 import * as TempoAddress_internal from './address.js';
@@ -243,6 +244,10 @@ export function sponsoredSimulationTransaction(transaction, options) {
         feePayer,
         feePayerSignature: feePayerSignature ? Signature.toRpc(feePayerSignature) : undefined,
         ...(feeToken !== undefined ? { feeToken } : {}),
+        // A deserialized envelope omits a zero priority fee, which the signed envelope encodes as 0.
+        // The node rebuilds the fee payer payload from the request, so an absent fee fails signature
+        // recovery (or takes the node's own value) for a hosted sponsor's signature.
+        maxPriorityFeePerGas: transaction.maxPriorityFeePerGas ?? 0n,
         signature: undefined,
     };
 }
@@ -287,14 +292,48 @@ export async function signFeePayerSimulation(transaction) {
  * gas and cannot be padded, or the padding was clamped), a failure that is only
  * out of gas is tolerated, since the sender simulation already bounded gas at
  * the broadcast limit. Every other failure, such as an insufficient fee balance
- * or a revert, is rethrown.
+ * or a revert, is thrown as a `PaymentSimulationError` that names the failing
+ * phase, sender, fee payer and payment token, with the node's error as `cause`.
  *
  * `complete` runs only after sender-context execution succeeds, so a reverting
  * transaction never reaches a local signer or hosted fee-payer.
  */
+/** viem's errors for an RPC request that never got a node's answer, matched by name so wrapped copies match. */
+const transportErrorNames = new Set([
+    'HttpRequestError',
+    'SocketClosedError',
+    'TimeoutError',
+    'WebSocketRequestError',
+]);
+/** Whether an error or its cause chain is a transport failure, rather than the node rejecting the call. */
+function isTransportError(error) {
+    for (let current = error, depth = 0; current && depth < 10; depth++) {
+        if (current instanceof Error && transportErrorNames.has(current.name))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
 export async function preflightSponsorship(parameters) {
     const { complete, policy, simulate, transaction } = parameters;
-    await simulate(simulationTransaction(transaction, { feePayer: true }));
+    const paymentCall = transaction.calls.length === 1 ? transaction.calls[0] : undefined;
+    const paymentToken = paymentCall?.data?.startsWith(Selectors.transfer) ||
+        paymentCall?.data?.startsWith(Selectors.transferWithMemo)
+        ? paymentCall.to
+        : undefined;
+    try {
+        await simulate(simulationTransaction(transaction, { feePayer: true }));
+    }
+    catch (cause) {
+        if (isTransportError(cause))
+            throw cause;
+        throw new PaymentSimulationError({
+            cause,
+            paymentToken,
+            phase: 'sender',
+            sender: transaction.from,
+        });
+    }
     const completed = await complete();
     const { gas } = completed.transaction;
     const simulated = await (async () => {
@@ -325,8 +364,16 @@ export async function preflightSponsorship(parameters) {
         const unpadded = gas !== undefined &&
             simulatedGas !== undefined &&
             simulatedGas < gas + sponsoredSimulationGasBuffer;
-        if (!unpadded || !isOutOfGasError(error))
+        if (isTransportError(error))
             throw error;
+        if (!unpadded || !isOutOfGasError(error))
+            throw new PaymentSimulationError({
+                cause: error,
+                feePayer: TempoAddress.resolve(completed.feePayer),
+                paymentToken,
+                phase: 'sponsored',
+                sender: transaction.from,
+            });
     }
     return completed;
 }