mppx 0.17.1 → 0.17.4

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

@@ -1,3 +1,4 @@
+import { Signature } from 'ox';
 import { TempoAddress } from 'ox/tempo';
 import type { Hex } from 'viem';
 import type { Account } from 'viem';
@@ -67,50 +68,99 @@ export declare function fillHostedFeePayerTransaction(parameters: {
     transaction: SponsoredTransaction;
 }): Promise<{
     feePayer: `0x${string}`;
+    feePayerSignature: {
+        readonly r: bigint;
+        readonly s: bigint;
+        readonly yParity: number;
+    };
     feeToken: TempoAddress.Address;
     serializedTransaction: `0x${string}`;
 }>;
 /**
  * Returns a transaction shape suitable for pre-broadcast simulation.
  *
- * Sponsored transactions are first simulated as calls from the sender with no
- * fee fields or signatures. This checks call execution without requiring the
- * sender to hold the fee token; transferred value and call-level balances are
- * still checked by the RPC.
+ * Sponsored transactions are first simulated as calls from the sender, without
+ * signatures, fee payer or fee token, and with zero fee fields: Tempo nodes
+ * (v1.18+) skip the fee-token balance check for a zero-fee `eth_call`, so the
+ * sender's fee balance is irrelevant. The call keeps the transaction's exact
+ * gas limit and the fields that set its intrinsic gas (nonce, nonce key,
+ * validity window, key authorization, signature type), so it is the gas-bounded
+ * check at the broadcast limit: a transaction whose gas is too low fails here
+ * with out of gas instead of reverting onchain at the sponsor's expense.
+ * Transferred value and call-level balances are still checked by the RPC.
  */
 export declare function simulationTransaction(transaction: SponsoredTransaction, options: {
     feePayer: boolean;
 }): any;
 /**
  * Returns the final fee-sponsored transaction shape for pre-broadcast
- * simulation. RPC `eth_call` does not carry either transaction signature.
+ * simulation.
+ *
+ * Tempo nodes recover the fee payer of an `eth_call` only from
+ * `feePayerSignature`; a bare `feePayer` address is ignored and the sender is
+ * billed instead. Pass the sponsor's signature so the node charges the fee
+ * token to the sponsor, not to a sender that may not hold it. The sender's own
+ * signature is never sent.
  */
 export declare function sponsoredSimulationTransaction(transaction: SponsoredTransaction, options: {
     feePayer: TempoAddress.Address;
+    feePayerSignature?: Signature.Signature | undefined;
     feeToken?: TempoAddress.Address | undefined;
 }): any;
 /** A completed sponsorship envelope that can be simulated before signing or broadcast. */
 export type PreflightSponsorship = {
     feePayer: TempoAddress.Address;
+    /**
+     * The sponsor's signature over the final envelope. Hosted sponsors return it
+     * from `eth_fillTransaction`; local accounts are signed in `preflightSponsorship`.
+     */
+    feePayerSignature?: Signature.Signature | undefined;
     feeToken?: TempoAddress.Address | undefined;
     transaction: SponsoredTransaction;
 };
 /**
- * Runs execution-only sender and final-envelope simulations around sponsorship.
- *
- * First, it simulates the calls with the sender as `from`, omitting fee fields
- * and signatures so the sender's fee balance is irrelevant. Next, `complete`
- * resolves the sponsor and produces the co-signed transaction. Finally, it
- * simulates that transaction with its concrete fee payer and fee token.
- *
- * `complete` runs only after sender-context execution succeeds, so a reverting
- * transaction never reaches a local signer or hosted fee-payer.
+ * Signs the fee-payer payload of a sponsored envelope with a local fee-payer
+ * account, the same payload `Transaction.serialize` signs before broadcast.
+ * Returns `undefined` when the envelope's fee payer cannot sign locally.
  */
+export declare function signFeePayerSimulation(transaction: SponsoredTransaction): Promise<Signature.Signature | undefined>;
 export declare function preflightSponsorship<sponsorship extends PreflightSponsorship>(parameters: {
     complete: () => Promise<sponsorship>;
+    /** The fee payer policy the completed transaction was checked against. */
+    policy?: Partial<Policy> | undefined;
     simulate: (request: Record<string, unknown>) => Promise<unknown>;
     transaction: SponsoredTransaction;
 }): Promise<sponsorship>;
+/**
+ * Returns the gas limit of a local fee payer's simulation-only copy: the
+ * transaction's gas plus {@link sponsoredSimulationGasBuffer}, clamped to the
+ * fee payer policy's `maxGas` and to `maxTotalFee / maxFeePerGas`, so the
+ * signed copy never exceeds a cap the real transaction is held to.
+ */
+export declare function sponsoredSimulationGas(transaction: Pick<SponsoredTransaction, 'chainId' | 'gas' | 'maxFeePerGas'>, policyOverrides?: Partial<Policy> | undefined): bigint;
+/**
+ * Returns true when a simulation failed only because it ran out of gas.
+ *
+ * Tempo nodes report out of gas as `out of gas: …` (code -32003, shared with
+ * `insufficient fee token balance`) or `intrinsic gas too low` (code -32000),
+ * so this reads the node's own message rather than the code. Only the terminal
+ * RPC failure counts: the deepest `details` in the cause chain (viem's
+ * `RpcRequestError` carries the node's message there), or the deepest message
+ * when no error has details. Wrapper messages are ignored, the match is anchored
+ * to the start of the node's message, and an error carrying revert data is never
+ * treated as gas exhaustion, so a revert reason or wrapper text that merely
+ * mentions gas cannot hide another failure.
+ */
+export declare function isOutOfGasError(error: unknown): boolean;
+/**
+ * Extra gas a local fee payer signs into its simulation-only envelope. Tempo's sponsored
+ * `eth_call` charges more gas than the same transaction uses when mined (about 6,000 for a
+ * session top-up on v1.18.1), so simulating at the signed limit would reject transactions
+ * that succeed onchain. The padding is clamped to the fee payer policy; hosted signatures
+ * cover the client's gas and are simulated as signed. In both cases the gas bound at the
+ * broadcast limit comes from the sender simulation.
+ */
+export declare const sponsoredSimulationGasBuffer = 10000n;
 /**
  * Validates an allowed fee-payer pattern. Returns the funding currency when the
  * calls are bound to the expected payment transfers.