mppx 0.17.1 → 0.17.4

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

@@ -1,7 +1,8 @@
-import { Address, Secp256k1 } from 'ox';
+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';
@@ -163,6 +164,12 @@ export async function fillHostedFeePayerTransaction(parameters) {
     })();
     return {
         feePayer,
+        // `Signature.fromRpc` rejects a yParity of 0 that arrives without `v`.
+        feePayerSignature: Signature.from({
+            r: BigInt(feePayerSignature.r),
+            s: BigInt(feePayerSignature.s),
+            yParity: feePayerSignature.yParity,
+        }),
         feeToken,
         serializedTransaction: await Transaction.serialize({
             ...transaction,
@@ -175,17 +182,36 @@ export async function fillHostedFeePayerTransaction(parameters) {
 /**
  * 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 function simulationTransaction(transaction, options) {
-    if (options.feePayer)
+    if (options.feePayer) {
+        const keyType = senderKeyType(transaction.signature);
         return {
             account: transaction.from,
             calls: transaction.calls,
+            ...(transaction.accessList?.length ? { accessList: transaction.accessList } : {}),
+            ...(transaction.gas !== undefined ? { gas: transaction.gas } : {}),
+            ...(transaction.keyAuthorization !== undefined
+                ? { keyAuthorization: transaction.keyAuthorization }
+                : {}),
+            ...(keyType ? { keyType } : {}),
+            maxFeePerGas: 0n,
+            maxPriorityFeePerGas: 0n,
+            ...(transaction.nonce !== undefined ? { nonce: transaction.nonce } : {}),
+            ...(transaction.nonceKey !== undefined ? { nonceKey: transaction.nonceKey } : {}),
+            ...(transaction.validAfter !== undefined ? { validAfter: transaction.validAfter } : {}),
+            ...(transaction.validBefore !== undefined ? { validBefore: transaction.validBefore } : {}),
         };
+    }
     return {
         ...transaction,
         account: transaction.from,
@@ -193,43 +219,228 @@ export function simulationTransaction(transaction, options) {
         feePayerSignature: undefined,
     };
 }
+/** The key type hint for a sender signature whose verification costs more than secp256k1. */
+function senderKeyType(signature) {
+    const envelope = signature;
+    const type = envelope?.type === 'keychain' ? envelope.inner?.type : envelope?.type;
+    return type === 'p256' || type === 'webAuthn' ? type : undefined;
+}
 /**
  * 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 function sponsoredSimulationTransaction(transaction, options) {
-    const { feePayer, feeToken } = options;
+    const { feePayer, feePayerSignature, feeToken } = options;
     return {
         ...transaction,
         account: transaction.from,
         calls: transaction.calls,
         feePayer,
-        feePayerSignature: undefined,
+        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,
     };
 }
 /**
- * Runs execution-only sender and final-envelope simulations around sponsorship.
+ * 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 async function signFeePayerSimulation(transaction) {
+    const { account: _account, feePayer, ...rest } = transaction;
+    if (typeof feePayer !== 'object' || feePayer === null)
+        return undefined;
+    const sign = feePayer.sign;
+    if (typeof sign !== 'function' || !rest.from)
+        return undefined;
+    const payload = TxEnvelopeTempo.getFeePayerSignPayload(TxEnvelopeTempo.from({
+        ...rest,
+        chainId: Number(rest.chainId),
+        feePayerSignature: undefined,
+        signature: undefined,
+        type: 'tempo',
+    }), { sender: rest.from });
+    return Signature.from(await sign({ hash: payload }));
+}
+/**
+ * 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.
  *
- * 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.
+ * 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 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, simulate, transaction } = parameters;
-    await simulate(simulationTransaction(transaction, { feePayer: true }));
+    const { complete, policy, simulate, transaction } = parameters;
+    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();
-    await simulate(sponsoredSimulationTransaction(completed.transaction, {
-        feePayer: completed.feePayer,
-        feeToken: completed.feeToken,
-    }));
+    const { gas } = completed.transaction;
+    const simulated = await (async () => {
+        if (completed.feePayerSignature)
+            return { feePayerSignature: completed.feePayerSignature, transaction: completed.transaction };
+        // The signature binds the gas limit, so a local fee payer signs a simulation-only copy
+        // with headroom for the node's sponsored `eth_call` overhead. The broadcast keeps its gas.
+        const padded = gas === undefined
+            ? completed.transaction
+            : {
+                ...completed.transaction,
+                gas: sponsoredSimulationGas(completed.transaction, policy),
+            };
+        const feePayerSignature = await signFeePayerSimulation(padded);
+        return feePayerSignature
+            ? { feePayerSignature, transaction: padded }
+            : { feePayerSignature: undefined, transaction: completed.transaction };
+    })();
+    const simulatedGas = simulated.transaction.gas;
+    try {
+        await simulate(sponsoredSimulationTransaction(simulated.transaction, {
+            feePayer: completed.feePayer,
+            feePayerSignature: simulated.feePayerSignature,
+            feeToken: completed.feeToken,
+        }));
+    }
+    catch (error) {
+        const unpadded = gas !== undefined &&
+            simulatedGas !== undefined &&
+            simulatedGas < gas + sponsoredSimulationGasBuffer;
+        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;
 }
+/**
+ * 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 function sponsoredSimulationGas(transaction, policyOverrides) {
+    const { chainId, gas, maxFeePerGas } = transaction;
+    if (gas === undefined)
+        throw new FeePayerValidationError('fee-sponsored transaction must declare gas', {});
+    const policy = getPolicy(Number(chainId), policyOverrides);
+    let cap = policy.maxGas;
+    if (maxFeePerGas !== undefined && maxFeePerGas > 0n) {
+        const feeCap = policy.maxTotalFee / maxFeePerGas;
+        if (feeCap < cap)
+            cap = feeCap;
+    }
+    if (gas > cap)
+        throw new FeePayerValidationError('fee-sponsored transaction gas exceeds sponsor policy', {
+            gas: gas.toString(),
+        });
+    const padded = gas + sponsoredSimulationGasBuffer;
+    return padded < cap ? padded : cap;
+}
+/**
+ * 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 function isOutOfGasError(error) {
+    let terminal;
+    let fallback;
+    for (let current = error, depth = 0; current && depth < 10; depth++) {
+        const { cause, data, details, message } = current;
+        if (typeof data === 'string' && data !== '0x')
+            return false;
+        if (typeof details === 'string')
+            terminal = details;
+        if (typeof message === 'string')
+            fallback = message;
+        current = cause;
+    }
+    const nodeMessage = (terminal ?? fallback)?.trim();
+    if (!nodeMessage)
+        return false;
+    return /^(?:out of gas(?::|$)|intrinsic gas too low(?::|$))/i.test(nodeMessage);
+}
+/**
+ * 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 const sponsoredSimulationGasBuffer = 10000n;
 /**
  * maxTotalFee must be high enough to cover `transferWithMemo` and
  * swap transactions at peak gas prices. Bumped from 0.01 ETH in #327.

package/dist/tempo/internal/zone.d.ts

@@ -0,0 +1,79 @@
+import { type Address, type Client, type Hex, type TransactionReceipt } from 'viem';
+/** Default time a payer waits for a Zone withdrawal to settle on Tempo. */
+export declare const defaultSettlementTimeoutMs = 60000;
+/** A withdrawal as `ZonePortal.processWithdrawals` receives it on Tempo. */
+export type Withdrawal = {
+    token: Address;
+    senderTag: Hex;
+    to: Address;
+    amount: bigint;
+    memo: Hex;
+    gasLimit: bigint;
+    fallbackNonce: bigint;
+    callbackData: Hex;
+    encryptedSender: Hex;
+};
+/** A `ZonePortal.WithdrawalProcessed` event. */
+export type ProcessedEvent = {
+    to: Address;
+    senderTag: Hex;
+    token: Address;
+    amount: bigint;
+    callbackSuccess: boolean;
+};
+/** Zones a challenge accepts: a list of Zone IDs, or `true` for any Zone. */
+export type Accepted = readonly number[] | true;
+/** Returns whether a value is a valid Zone ID: a positive integer below the Zone chain ID ranges. */
+export declare function isId(zoneId: number): boolean;
+/** Returns whether a challenge's `zones` accepts withdrawals from a Zone. */
+export declare function isAccepted(zones: Accepted | undefined, zoneId: number): boolean;
+/** Returns the Tempo portal address of a Zone. */
+export declare function portalAddress(zoneId: number): Address;
+/**
+ * Derives a Zone ID from a Zone chain ID.
+ *
+ * Zones on Tempo mainnet and Moderato use reserved bases (`421700000` and
+ * `1424310000`). Zones on any other parent chain use `(parentChainId << 32) | zoneId`.
+ */
+export declare function idFromChainId(chainId: number): number;
+/**
+ * Derives the parent Tempo chain ID of a Zone chain ID, or `undefined` when
+ * the chain ID doesn't follow a known Zone scheme.
+ */
+export declare function parentChainIdFromChainId(chainId: number): number | undefined;
+/**
+ * Derives a withdrawal's sender tag, which identifies it in the
+ * `WithdrawalProcessed` event on Tempo.
+ */
+export declare function senderTag(parameters: {
+    fallbackNonce: bigint;
+    sender: Address;
+    transactionHash: Hex;
+}): Hex;
+/** Returns the `WithdrawalProcessed` event a portal emitted for a sender tag. */
+export declare function findProcessedEvent(receipt: Pick<TransactionReceipt, 'logs'>, parameters: {
+    portal: Address;
+    senderTag: Hex;
+}): ProcessedEvent | undefined;
+/**
+ * Finds the withdrawal for a sender tag in the calldata of a settlement
+ * transaction's top-level `processWithdrawals` calls to the portal.
+ */
+export declare function findWithdrawal(calls: readonly {
+    to?: Address | null | undefined;
+    data?: Hex | undefined;
+}[], parameters: {
+    portal: Address;
+    senderTag: Hex;
+}): Withdrawal | undefined;
+/**
+ * Waits until a portal emits `WithdrawalProcessed` for a sender tag and
+ * returns the Tempo transaction hash that settled it.
+ */
+export declare function waitForSettlement(client: Client, parameters: {
+    portal: Address;
+    senderTag: Hex;
+    to?: Address | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<Hex>;
+//# sourceMappingURL=zone.d.ts.map

package/dist/tempo/internal/zone.js

@@ -0,0 +1,133 @@
+import { AbiParameters, Hash } from 'ox';
+import { decodeFunctionData, getAbiItem, parseEventLogs, } from 'viem';
+import { getBlockNumber, getLogs } from 'viem/actions';
+import { Abis, Addresses } from 'viem/tempo';
+import * as TempoAddress from './address.js';
+/** Default time a payer waits for a Zone withdrawal to settle on Tempo. */
+export const defaultSettlementTimeoutMs = 60_000;
+/** Number of Tempo blocks searched back for a settled Zone withdrawal. */
+const lookbackBlocks = 7200n;
+/** Time between polls for a settled Zone withdrawal. */
+const pollingIntervalMs = 500;
+const withdrawalProcessed = getAbiItem({ abi: Abis.zonePortal, name: 'WithdrawalProcessed' });
+/**
+ * Zone IDs from here up read as Zone chain IDs in viem's portal lookup, which
+ * would map them to another Zone's portal.
+ */
+const maxIdExclusive = 421_700_000;
+/** Returns whether a value is a valid Zone ID: a positive integer below the Zone chain ID ranges. */
+export function isId(zoneId) {
+    return Number.isInteger(zoneId) && zoneId > 0 && zoneId < maxIdExclusive;
+}
+/** Returns whether a challenge's `zones` accepts withdrawals from a Zone. */
+export function isAccepted(zones, zoneId) {
+    if (!isId(zoneId))
+        return false;
+    return zones === true || (zones?.includes(zoneId) ?? false);
+}
+/** Returns the Tempo portal address of a Zone. */
+export function portalAddress(zoneId) {
+    return Addresses.zonePortal(zoneId);
+}
+/**
+ * Derives a Zone ID from a Zone chain ID.
+ *
+ * Zones on Tempo mainnet and Moderato use reserved bases (`421700000` and
+ * `1424310000`). Zones on any other parent chain use `(parentChainId << 32) | zoneId`.
+ */
+export function idFromChainId(chainId) {
+    if (chainId >= 2 ** 32)
+        return chainId % 2 ** 32;
+    if (chainId > 1_424_310_000 && chainId < 1_424_320_000)
+        return chainId - 1_424_310_000;
+    if (chainId > 421_700_000 && chainId < 421_710_000)
+        return chainId - 421_700_000;
+    throw new Error(`Cannot derive a Zone ID from chain ID ${chainId}. Pass \`zoneId\`.`);
+}
+/**
+ * Derives the parent Tempo chain ID of a Zone chain ID, or `undefined` when
+ * the chain ID doesn't follow a known Zone scheme.
+ */
+export function parentChainIdFromChainId(chainId) {
+    if (chainId >= 2 ** 32)
+        return Math.floor(chainId / 2 ** 32);
+    if (chainId > 1_424_310_000 && chainId < 1_424_320_000)
+        return 42_431;
+    if (chainId > 421_700_000 && chainId < 421_710_000)
+        return 4_217;
+    return undefined;
+}
+/**
+ * Derives a withdrawal's sender tag, which identifies it in the
+ * `WithdrawalProcessed` event on Tempo.
+ */
+export function senderTag(parameters) {
+    return Hash.keccak256(AbiParameters.encodePacked(['address', 'bytes32', 'uint64'], [parameters.sender, parameters.transactionHash, parameters.fallbackNonce]));
+}
+/** Returns the `WithdrawalProcessed` event a portal emitted for a sender tag. */
+export function findProcessedEvent(receipt, parameters) {
+    const logs = parseEventLogs({ abi: [withdrawalProcessed], logs: receipt.logs });
+    const log = logs.find((log) => TempoAddress.isEqual(log.address, parameters.portal) &&
+        log.args.senderTag.toLowerCase() === parameters.senderTag.toLowerCase());
+    return log?.args;
+}
+/**
+ * Finds the withdrawal for a sender tag in the calldata of a settlement
+ * transaction's top-level `processWithdrawals` calls to the portal.
+ */
+export function findWithdrawal(calls, parameters) {
+    for (const call of calls) {
+        if (!call.to || !call.data || !TempoAddress.isEqual(call.to, parameters.portal))
+            continue;
+        let decoded;
+        try {
+            decoded = decodeFunctionData({ abi: Abis.zonePortal, data: call.data });
+        }
+        catch {
+            continue;
+        }
+        if (decoded.functionName !== 'processWithdrawals')
+            continue;
+        const [withdrawals] = decoded.args;
+        const withdrawal = withdrawals.find((withdrawal) => withdrawal.senderTag.toLowerCase() === parameters.senderTag.toLowerCase());
+        if (withdrawal)
+            return withdrawal;
+    }
+    return undefined;
+}
+/**
+ * Waits until a portal emits `WithdrawalProcessed` for a sender tag and
+ * returns the Tempo transaction hash that settled it.
+ */
+export async function waitForSettlement(client, parameters) {
+    const { timeoutMs = defaultSettlementTimeoutMs } = parameters;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw new Error('Zone settlement timeout must be a finite, non-negative number.');
+    let latest = await getBlockNumber(client, { cacheTime: 0 });
+    // Scan the lookback window once, then only blocks added since the previous poll.
+    let fromBlock = latest > lookbackBlocks ? latest - lookbackBlocks : 0n;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        if (fromBlock <= latest) {
+            const logs = await getLogs(client, {
+                address: parameters.portal,
+                event: withdrawalProcessed,
+                args: {
+                    senderTag: parameters.senderTag,
+                    ...(parameters.to ? { to: parameters.to } : {}),
+                },
+                fromBlock,
+                toBlock: latest,
+            });
+            const hash = logs[0]?.transactionHash;
+            if (hash)
+                return hash;
+            fromBlock = latest + 1n;
+        }
+        if (Date.now() + pollingIntervalMs > deadline)
+            throw new Error(`Zone withdrawal ${parameters.senderTag} did not settle on Tempo within ${timeoutMs}ms.`);
+        await new Promise((resolve) => setTimeout(resolve, pollingIntervalMs));
+        latest = await getBlockNumber(client, { cacheTime: 0 });
+    }
+}
+//# sourceMappingURL=zone.js.map

package/dist/tempo/legacy/session/Chain.js

@@ -355,6 +355,7 @@ export async function broadcastOpenTransaction(parameters) {
                     reason: 'transaction does not contain a valid escrow open call',
                 });
             const completed = await FeePayer.preflightSponsorship({
+                policy: feePayerPolicy,
                 transaction,
                 simulate: (request) => call(client, request),
                 async complete() {
@@ -470,6 +471,7 @@ export async function broadcastTopUpTransaction(parameters) {
                 });
             const defaultFeeToken = defaults.currency[client.chain?.id];
             const completed = await FeePayer.preflightSponsorship({
+                policy: feePayerPolicy,
                 transaction,
                 simulate: (request) => call(client, request),
                 async complete() {

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

@@ -61,8 +61,10 @@ export declare namespace charge {
          * two thirds of this budget. If it fails with an unknown outcome (e.g. a
          * timeout, a lost connection, or "already known"), mppx polls for the
          * receipt until the deadline, or until 2 seconds after the transaction's
-         * `validBefore` followed by one final lookup, before surfacing the broadcast
-         * error. Definitive rejections fail immediately.
+         * `validBefore` followed by one final lookup, before throwing
+         * `Errors.BroadcastOutcomeUnknownError` with the transaction hash and
+         * `validBefore`, and the broadcast error as `cause`. Definitive rejections
+         * fail immediately with the RPC error.
          * @default 30_000
          */
         confirmationTimeoutMs?: number | undefined;
@@ -143,7 +145,9 @@ export declare namespace charge {
          * report `status: 'success'` based on simulation alone — if the
          * transaction reverts on-chain after broadcast (e.g. due to a state
          * change between simulation and inclusion), the receipt will not reflect
-         * the failure.
+         * the failure. An ambiguous broadcast failure (a timeout, a lost
+         * connection, a 5xx) throws `Errors.BroadcastOutcomeUnknownError` without
+         * polling for a receipt.
          */
         waitForConfirmation?: boolean | undefined;
     } & Client.getResolver.Parameters & Account.resolve.Parameters & Defaults & Method.ComposableHooks<typeof Methods.charge>;