mppx 0.17.1 → 0.17.4

package/dist/tempo/server/Charge.js

@@ -3,7 +3,7 @@ import { decodeFunctionData, formatUnits, keccak256, parseEventLogs, WaitForTran
 import { getTransaction, getTransactionReceipt, sendRawTransaction, sendRawTransactionSync, signTransaction, verifyTypedData, waitForTransactionReceipt, call as viem_call, } from 'viem/actions';
 import { Abis, Actions, Transaction } from 'viem/tempo';
 import { tempo as tempo_chain } from 'viem/tempo/chains';
-import { CredentialReplayedError, PaymentError, VerificationFailedError } from '../../Errors.js';
+import { BroadcastOutcomeUnknownError, CredentialReplayedError, PaymentError, VerificationFailedError, } from '../../Errors.js';
 import * as Expires from '../../Expires.js';
 import * as Method from '../../Method.js';
 import * as Store from '../../Store.js';
@@ -18,9 +18,9 @@ import { resolveFeeToken } from '../internal/fee-token.js';
 import * as MachineTokenCharge from '../internal/machine-token-charge.js';
 import * as Proof from '../internal/proof.js';
 import * as Selectors from '../internal/selectors.js';
+import * as Zone from '../internal/zone.js';
 import * as Methods from '../Methods.js';
 import { fallbackStore } from './internal/fallback-store.js';
-import { html as htmlContent } from './internal/html.gen.js';
 import * as Relay from './Relay.js';
 import * as SponsorBudget from './SponsorBudget.js';
 /**
@@ -34,7 +34,7 @@ import * as SponsorBudget from './SponsorBudget.js';
  * ```
  */
 export function charge(parameters = {}) {
-    const { machineTokenEnabled, allowedFeeTokens: configuredAllowedFeeTokens, amount, confirmationTimeoutMs = 30_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, description, externalId, feeToken: configuredFeeToken, feePayerPolicy, html, relay, sponsorBudget, splits, supportedModes, validateSender, waitForConfirmation = true, } = parameters;
+    const { machineTokenEnabled, allowedFeeTokens: configuredAllowedFeeTokens, amount, confirmationTimeoutMs = 30_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, description, externalId, feeToken: configuredFeeToken, feePayerPolicy, html, relay, sponsorBudget, splits, supportedModes, validateSender, waitForConfirmation = true, zones, } = parameters;
     if (configuredAllowedFeeTokens?.length === 0)
         throw new Error('`allowedFeeTokens` must contain at least one token.');
     const storeKeyPrefix = parameters.storeKeyPrefix ?? '';
@@ -188,6 +188,55 @@ export function charge(parameters = {}) {
         const payer = payers.size === 1 ? [...payers][0] : undefined;
         return { payer, receipt, sender, transfers };
     }
+    /**
+     * Validates a payment that a Zone withdrawal settled on Tempo: the portal's
+     * `WithdrawalProcessed` event pays the recipient, and the withdrawal's memo in
+     * the `processWithdrawals` calldata binds it to this challenge.
+     */
+    async function validateZoneCredential(payload, context) {
+        const { amount, challenge, client, currency, methodDetails, recipient, supportedModes } = context;
+        if (supportedModes && !supportedModes.includes('push'))
+            throw new MismatchError('Zone credentials are not supported for this challenge.', {});
+        if (!Zone.isAccepted(methodDetails?.zones, payload.zoneId))
+            throw new MismatchError('Zone is not accepted for this challenge.', {
+                zoneId: String(payload.zoneId),
+            });
+        if (methodDetails?.splits)
+            throw new MismatchError('Zone credentials do not support split payments.', {});
+        const portal = Zone.portalAddress(payload.zoneId);
+        const senderTag = payload.senderTag;
+        const hash = payload.hash;
+        const receipt = await getTransactionReceipt(client, { hash });
+        if (receipt.status !== 'success')
+            throw new MismatchError('Payment verification failed: settlement transaction reverted.', {
+                hash,
+            });
+        const event = Zone.findProcessedEvent(receipt, { portal, senderTag });
+        if (!event)
+            throw new MismatchError('Payment verification failed: Zone withdrawal not settled.', {
+                senderTag,
+            });
+        if (!event.callbackSuccess)
+            throw new MismatchError('Payment verification failed: Zone withdrawal bounced.', {
+                senderTag,
+            });
+        // The event has no memo, so the calldata's withdrawal shows what was paid and for which challenge.
+        const transaction = await getTransaction(client, { hash });
+        const calls = transaction.calls ??
+            (transaction.to ? [{ to: transaction.to, data: transaction.input }] : []);
+        const withdrawal = Zone.findWithdrawal(calls, { portal, senderTag });
+        if (!withdrawal ||
+            withdrawal.gasLimit !== 0n ||
+            !TempoAddress.isEqual(withdrawal.to, recipient) ||
+            !TempoAddress.isEqual(withdrawal.token, currency) ||
+            withdrawal.amount.toString() !== amount)
+            throw new MismatchError('Payment verification failed: Zone withdrawal not found.', {
+                senderTag,
+            });
+        if (!isChallengeBound([withdrawal.memo], { challengeId: challenge.id, realm: challenge.realm }))
+            throw new CredentialReplayedError({ reason: 'memo is not bound to this challenge' });
+        return { hash, portal, receipt, senderTag };
+    }
     async function validateProofCredential(credential, payload, context) {
         const { chainId, challenge, client, isZeroAmount } = context;
         if (!isZeroAmount)
@@ -283,6 +332,18 @@ export function charge(parameters = {}) {
                     type: 'proof',
                 };
             }
+            case 'zone': {
+                const { hash, portal, receipt, senderTag } = await validateZoneCredential(context.payload, context);
+                return {
+                    details: { mode: 'push' },
+                    hash,
+                    payer: undefined,
+                    portal,
+                    receipt,
+                    senderTag,
+                    type: 'zone',
+                };
+            }
             case 'transaction': {
                 const { fundingCurrency, isFeePayerTx, serializedTransaction, settlementSenders, transaction, transfers, } = await validateTransactionCredential(credential, context.payload, request, context);
                 return {
@@ -317,12 +378,13 @@ export function charge(parameters = {}) {
             recipient,
             splits,
             supportedModes,
+            zones,
         },
         stableBinding: chargeBinding,
         html: html
             ? {
                 config: {},
-                content: htmlContent,
+                content: async () => (await import('./internal/html.gen.js')).html,
                 formatAmount: async (request) => {
                     try {
                         const chainId = request.methodDetails?.chainId;
@@ -451,6 +513,15 @@ export function charge(parameters = {}) {
                     }
                     return toReceipt(receipt.transactionHash, fundingCurrency);
                 }
+                case 'zone': {
+                    const { portal, receipt, senderTag } = validated;
+                    if (!(await tryClaimZoneWithdrawal(store, portal, senderTag, replayExpires))) {
+                        throw new CredentialReplayedError({
+                            reason: 'Zone withdrawal has already been used',
+                        });
+                    }
+                    return toReceipt(receipt.transactionHash);
+                }
                 case 'proof': {
                     if (proofStore && !(await tryClaimProof(proofStore, challenge.id, replayExpires))) {
                         throw new CredentialReplayedError({
@@ -481,6 +552,7 @@ export function charge(parameters = {}) {
                             if (feePayerAccount && methodDetails?.feePayer !== false) {
                                 const selectableFeeTokens = allowedFeeTokens ?? FeePayer.defaultAllowedFeeTokens(chainId);
                                 const completed = await FeePayer.preflightSponsorship({
+                                    policy: transactionFeePayerPolicy,
                                     transaction,
                                     simulate: (request) => viem_call(client, request),
                                     async complete() {
@@ -639,7 +711,11 @@ export function charge(parameters = {}) {
                                 if (!recovered && validUntil < deadline)
                                     recovered = await withDeadline(getTransactionReceipt(client, { hash: finalHash }), Math.max(deadline, Date.now() + client.pollingInterval), broadcastError).catch(() => undefined);
                                 if (!recovered)
-                                    throw broadcastError;
+                                    throw new BroadcastOutcomeUnknownError({
+                                        cause: broadcastError,
+                                        transactionHash: finalHash,
+                                        validBefore: transaction.validBefore,
+                                    });
                                 receipt = recovered;
                             }
                             if (reservation)
@@ -663,8 +739,18 @@ export function charge(parameters = {}) {
                         // Optimistic path: broadcast without waiting for confirmation
                         // (simulation above already ran). The returned receipt assumes
                         // success — callers opt in via waitForConfirmation: false.
+                        const transactionHash = finalHash;
                         const reference = await sendRawTransaction(client, {
                             serializedTransaction: serializedTransaction_final,
+                        }).catch((broadcastError) => {
+                            // Without a receipt wait, an ambiguous failure leaves the outcome to the caller.
+                            if (!isAmbiguousBroadcastError(broadcastError))
+                                throw broadcastError;
+                            throw new BroadcastOutcomeUnknownError({
+                                cause: broadcastError,
+                                transactionHash,
+                                validBefore: transaction.validBefore,
+                            });
                         });
                         if (reference.toLowerCase() !== finalHash.toLowerCase())
                             throw new VerificationFailedError({
@@ -711,7 +797,7 @@ function chargeBinding(request) {
     // Exhaustively destructure so new charge request fields require an explicit binding decision.
     const { amount, currency, description, externalId, methodDetails, recipient, ...requestRest } = request;
     requestRest;
-    const { chainId, feePayer, machineTokenEnabled, splits, supportedModes, ...methodDetailsRest } = methodDetails ?? {};
+    const { chainId, feePayer, machineTokenEnabled, splits, supportedModes, zones, ...methodDetailsRest } = methodDetails ?? {};
     methodDetailsRest;
     void feePayer;
     return {
@@ -724,6 +810,7 @@ function chargeBinding(request) {
         recipient,
         splits,
         supportedModes,
+        zones,
     };
 }
 function getExpectedTransfers(parameters) {
@@ -953,6 +1040,13 @@ function getHashStoreKey(hash) {
 function getProofStoreKey(challengeId) {
     return `mppx:charge:proof:${challengeId}`;
 }
+/** @internal */
+function getZoneWithdrawalStoreKey(portal, senderTag) {
+    return `mppx:charge:zone:${portal.toLowerCase()}:${senderTag.toLowerCase()}`;
+}
+async function tryClaimZoneWithdrawal(store, portal, senderTag, expires) {
+    return Store.tryClaim(store, getZoneWithdrawalStoreKey(portal, senderTag), expires);
+}
 async function tryClaimHash(store, hash, expires) {
     return Store.tryClaim(store, getHashStoreKey(hash), expires);
 }

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

@@ -51,6 +51,11 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
             }, 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<{
@@ -73,6 +78,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                 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;
@@ -89,6 +95,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -107,6 +114,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
 }, charge_.DeriveDefaults<NoExtraKeys<parameters, tempo.Parameters>>, undefined, {}, string | undefined>, import("../../Method.js").Server<{
@@ -213,6 +221,11 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
             }, 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<{
@@ -235,6 +248,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                 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;
@@ -251,6 +265,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -269,6 +284,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
 }, charge_.DeriveDefaults<Omit<parameters, "chainId" | "currencies" | "currency" | "decimals"> & {
@@ -2323,6 +2339,11 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
             }, 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<{
@@ -2345,6 +2366,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                 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;
@@ -2361,6 +2383,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -2379,6 +2402,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
 }, charge_.DeriveDefaults<Omit<parameters, "chainId" | "currencies" | "currency" | "decimals"> & {
@@ -2467,6 +2491,11 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
             }, 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<{
@@ -2489,6 +2518,7 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
                 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;
@@ -2505,6 +2535,7 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -2523,6 +2554,7 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
 }, charge_.DeriveDefaults<Omit<parameters, "chainId" | "currencies" | "currency" | "decimals"> & {
@@ -2543,6 +2575,11 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
             }, 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<{
@@ -2565,6 +2602,7 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
                 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;
@@ -2581,6 +2619,7 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -2599,6 +2638,7 @@ declare function chargeOffers<const parameters extends CurrencyParameters<charge
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
 }, charge_.DeriveDefaults<Omit<parameters, "chainId" | "currencies" | "currency" | "decimals"> & {

package/dist/tempo/server/Subscription.js

@@ -713,6 +713,7 @@ async function submitSubscriptionPayment(parameters) {
         const userSerialized = await signTransaction(client, prepared);
         const userTransaction = Transaction.deserialize(userSerialized);
         const completed = await FeePayer.preflightSponsorship({
+            policy: feePayerPolicy,
             transaction: userTransaction,
             simulate: (request) => viem_call(client, request),
             async complete() {