mppx 0.10.1 → 0.12.0

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

@@ -1,4 +1,4 @@
-import { type Address } from 'viem';
+import type { Address } from 'viem';
 import * as Method from '../../Method.js';
 import * as Account from '../../viem/Account.js';
 import * as Client from '../../viem/Client.js';
@@ -42,6 +42,7 @@ export declare function charge(parameters?: charge.Parameters): Method.Client<{
             }, z.core.$strip>], "type">;
         };
         request: z.ZodMiniPipe<z.ZodMiniObject<{
+            machineTokenEnabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
             amount: z.ZodMiniString<string>;
             chainId: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
             currency: z.ZodMiniString<string>;
@@ -49,7 +50,7 @@ export declare function charge(parameters?: charge.Parameters): Method.Client<{
             description: z.ZodMiniOptional<z.ZodMiniString<string>>;
             externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
             feePayer: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniUnion<readonly [z.ZodMiniBoolean<boolean>, z.ZodMiniCustom<import("viem").Account, import("viem").Account>]>, z.ZodMiniTransform<boolean, boolean | import("viem").Account>>>;
-            memo: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            memo: z.ZodMiniOptional<z.ZodMiniNever>;
             recipient: z.ZodMiniOptional<z.ZodMiniString<string>>;
             splits: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
                 amount: z.ZodMiniString<string>;
@@ -67,9 +68,9 @@ export declare function charge(parameters?: charge.Parameters): Method.Client<{
             recipient?: string | undefined;
             amount: string;
             methodDetails?: {
+                machineTokenEnabled?: boolean | undefined;
                 chainId?: number | undefined;
                 feePayer?: boolean | undefined;
-                memo?: string | undefined;
                 splits?: {
                     memo?: string | undefined;
                     recipient: `0x${string}`;
@@ -78,6 +79,7 @@ export declare function charge(parameters?: charge.Parameters): Method.Client<{
                 supportedModes?: ("pull" | "push")[] | undefined;
             } | undefined;
         }, {
+            machineTokenEnabled?: boolean | undefined;
             amount: string;
             chainId?: number | undefined;
             currency: string;
@@ -85,7 +87,7 @@ export declare function charge(parameters?: charge.Parameters): Method.Client<{
             description?: string | undefined;
             externalId?: string | undefined;
             feePayer?: boolean | undefined;
-            memo?: string | undefined;
+            memo?: undefined;
             recipient?: string | undefined;
             splits?: {
                 amount: string;

package/dist/tempo/client/Charge.js

@@ -1,4 +1,3 @@
-import { isAddressEqual } from 'viem';
 import { prepareTransactionRequest, sendCallsSync, sendTransactionSync, signTypedData, signTransaction, } from 'viem/actions';
 import { Actions } from 'viem/tempo';
 import { tempo as tempo_chain } from 'viem/tempo/chains';
@@ -12,9 +11,9 @@ import * as AutoSwap from '../internal/auto-swap.js';
 import * as Charge_internal from '../internal/charge.js';
 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 Methods from '../Methods.js';
-import { mach } from '../Tokens.js';
 const chargeContextSchema = z.object({
     account: z.optional(z.custom()),
     autoSwap: z.optional(z.custom()),
@@ -98,9 +97,12 @@ export function charge(parameters = {}) {
                 });
             }
             const currency = request.currency;
-            const memo = methodDetails?.memo
-                ? methodDetails.memo
-                : Attribution.encode({ challengeId: challenge.id, clientId, serverId: challenge.realm });
+            const isMachineTokenCurrency = MachineTokenCharge.isMachineToken({ chainId, currency });
+            const memo = Attribution.encode({
+                challengeId: challenge.id,
+                clientId,
+                serverId: challenge.realm,
+            });
             const transfers = Charge_internal.getTransfers({
                 amount,
                 methodDetails: {
@@ -116,14 +118,66 @@ export function charge(parameters = {}) {
                 token: currency,
             }));
             const autoSwap = AutoSwap.resolve(context?.autoSwap ?? parameters.autoSwap, AutoSwap.defaultCurrencies);
-            const account = (await parameters.resolveAccount?.({
+            const machineTokenEnabled = methodDetails?.machineTokenEnabled === true;
+            const resolveAccount = async (calls) => (await parameters.resolveAccount?.({
                 account: defaultAccount,
                 chainId,
                 operation: {
                     kind: 'executeCalls',
-                    ...(autoSwap ? {} : { calls: transferCalls }),
+                    ...(calls ? { calls } : {}),
                 },
             })) ?? defaultAccount;
+            const machineTokenCandidate = machineTokenEnabled
+                ? MachineTokenCharge.getRoute({ chainId, currency, transfers })
+                : undefined;
+            let account = defaultAccount;
+            let machineTokenRoute;
+            if (machineTokenCandidate) {
+                const machineTokenAccount = await (async () => {
+                    try {
+                        return await resolveAccount(machineTokenCandidate.calls);
+                    }
+                    catch {
+                        // A machine-token route is optional. A scoped account that cannot
+                        // execute it may still be able to satisfy the direct payment.
+                        return undefined;
+                    }
+                })();
+                if (machineTokenAccount) {
+                    machineTokenRoute = await MachineTokenCharge.findRoute(client, {
+                        account: machineTokenAccount.address,
+                        chainId,
+                        currency,
+                        transfers,
+                    });
+                    if (machineTokenRoute)
+                        account = machineTokenAccount;
+                }
+            }
+            let swapCalls;
+            if (!machineTokenRoute) {
+                account = await resolveAccount(autoSwap ? undefined : transferCalls);
+                swapCalls = autoSwap
+                    ? await AutoSwap.findCalls(client, {
+                        account: account.address,
+                        amountOut: BigInt(amount),
+                        tokenOut: currency,
+                        tokenIn: autoSwap.tokenIn,
+                        slippage: autoSwap.slippage,
+                    })
+                    : undefined;
+            }
+            const calls = machineTokenRoute?.calls ?? [...(swapCalls ?? []), ...transferCalls];
+            const allowedFeeTokens = defaultFeeTokens(chainId);
+            const feeToken = machineTokenRoute || isMachineTokenCurrency
+                ? await resolveFeeToken({
+                    account: account.address,
+                    allowedTokens: allowedFeeTokens,
+                    candidateTokens: allowedFeeTokens,
+                    client,
+                    prioritizeCandidates: true,
+                })
+                : undefined;
             const mode = (() => {
                 const explicitMode = context?.mode ?? parameters.mode;
                 if (explicitMode) {
@@ -136,27 +190,6 @@ export function charge(parameters = {}) {
                     return preferredMode;
                 return supportedModes[0];
             })();
-            const swapCalls = autoSwap
-                ? await AutoSwap.findCalls(client, {
-                    account: account.address,
-                    amountOut: BigInt(amount),
-                    tokenOut: currency,
-                    tokenIn: autoSwap.tokenIn,
-                    slippage: autoSwap.slippage,
-                })
-                : undefined;
-            const calls = [...(swapCalls ?? []), ...transferCalls];
-            const machAddress = mach.addresses[chainId];
-            const allowedFeeTokens = defaultFeeTokens(chainId);
-            const feeToken = machAddress && isAddressEqual(currency, machAddress)
-                ? await resolveFeeToken({
-                    account: account.address,
-                    allowedTokens: allowedFeeTokens,
-                    candidateTokens: allowedFeeTokens,
-                    client,
-                    prioritizeCandidates: true,
-                })
-                : undefined;
             const validBefore = (() => {
                 const defaultExpiry = Math.floor(Date.now() / 1000) + 25;
                 if (!challenge.expires)

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

@@ -37,6 +37,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [import("
             }, import("zod/v4/core").$strip>], "type">;
         };
         request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
+            machineTokenEnabled: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniBoolean<boolean>>;
             amount: import("zod/mini").ZodMiniString<string>;
             chainId: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniNumber<number>>;
             currency: import("zod/mini").ZodMiniString<string>;
@@ -44,7 +45,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [import("
             description: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             externalId: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             feePayer: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniUnion<readonly [import("zod/mini").ZodMiniBoolean<boolean>, import("zod/mini").ZodMiniCustom<import("viem").Account, import("viem").Account>]>, import("zod/mini").ZodMiniTransform<boolean, boolean | import("viem").Account>>>;
-            memo: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+            memo: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniNever>;
             recipient: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             splits: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniArray<import("zod/mini").ZodMiniObject<{
                 amount: import("zod/mini").ZodMiniString<string>;
@@ -62,9 +63,9 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [import("
             recipient?: string | undefined;
             amount: string;
             methodDetails?: {
+                machineTokenEnabled?: boolean | undefined;
                 chainId?: number | undefined;
                 feePayer?: boolean | undefined;
-                memo?: string | undefined;
                 splits?: {
                     memo?: string | undefined;
                     recipient: `0x${string}`;
@@ -73,6 +74,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [import("
                 supportedModes?: ("pull" | "push")[] | undefined;
             } | undefined;
         }, {
+            machineTokenEnabled?: boolean | undefined;
             amount: string;
             chainId?: number | undefined;
             currency: string;
@@ -80,7 +82,7 @@ export declare function tempo(parameters?: tempo.Parameters): readonly [import("
             description?: string | undefined;
             externalId?: string | undefined;
             feePayer?: boolean | undefined;
-            memo?: string | undefined;
+            memo?: undefined;
             recipient?: string | undefined;
             splits?: {
                 amount: string;

package/dist/tempo/index.d.ts

@@ -3,5 +3,6 @@ export * as Methods from './Methods.js';
 export * as Session from './session/index.js';
 export * as SessionLegacy from './legacy/index.js';
 export * as Subscription from './subscription/index.js';
-export { mach } from './Tokens.js';
+/** Canonical first-party machine-token deployments by Tempo chain ID. */
+export { machineToken as machineTokenDeployments } from './internal/defaults.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/tempo/index.js

@@ -3,5 +3,6 @@ export * as Methods from './Methods.js';
 export * as Session from './session/index.js';
 export * as SessionLegacy from './legacy/index.js';
 export * as Subscription from './subscription/index.js';
-export { mach } from './Tokens.js';
+/** Canonical first-party machine-token deployments by Tempo chain ID. */
+export { machineToken as machineTokenDeployments } from './internal/defaults.js';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,19 @@
+import type { Token } from 'viem/tokens';
+/** An explicit token address or a chain-indexed token definition. */
+export type Currency = string | Token;
+/** Resolves ordered USD offers without expanding acceptance from a live registry. */
+export declare function resolve(parameters: {
+    chainId?: number | undefined;
+    testnet?: boolean | undefined;
+    currencies?: readonly Currency[] | undefined;
+    decimals?: number | undefined;
+}): [({
+    currency: string;
+    decimals: number;
+    chainId: number;
+}[])[number], ...{
+    currency: string;
+    decimals: number;
+    chainId: number;
+}[]];
+//# sourceMappingURL=currencies.d.ts.map

package/dist/tempo/internal/currencies.js

@@ -0,0 +1,41 @@
+import { isAddress } from 'viem';
+import * as defaults from './defaults.js';
+/** Resolves ordered USD offers without expanding acceptance from a live registry. */
+export function resolve(parameters) {
+    const chainId = parameters.chainId ?? (parameters.testnet ? defaults.chainId.testnet : defaults.chainId.mainnet);
+    const currencies = parameters.currencies ??
+        (chainId === defaults.chainId.mainnet
+            ? [defaults.tokens.ousd, defaults.tokens.usdc]
+            : chainId === defaults.chainId.testnet
+                ? // TODO: Use viem's chain-specific OUSD definition once it includes Moderato (42431).
+                    [defaults.tokens.ousd, defaults.tokens.pathUsd]
+                : [defaults.resolveCurrency({ chainId })]);
+    const seen = new Set();
+    const resolved = [];
+    for (const token of currencies) {
+        // A shared USD price cannot also price EUR, BTC, or unknown denominations.
+        if (typeof token !== 'string' && token.currency !== 'USD')
+            continue;
+        const currency = typeof token === 'string' ? token : token.addresses[chainId];
+        if (currency === undefined)
+            continue;
+        if (!isAddress(currency, { strict: false }))
+            throw new Error(`Invalid Tempo currency address: ${currency}.`);
+        const decimals = typeof token === 'string' ? (parameters.decimals ?? defaults.decimals) : token.decimals;
+        if (typeof token !== 'string' &&
+            parameters.decimals !== undefined &&
+            parameters.decimals !== decimals)
+            throw new Error('Configured `decimals` must match each token definition.');
+        if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255)
+            throw new Error('Token decimals must be an integer between 0 and 255.');
+        const key = currency.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        resolved.push({ currency, decimals, chainId });
+    }
+    if (resolved.length === 0)
+        throw new Error(`No accepted USD currencies for chain ${chainId}.`);
+    return resolved;
+}
+//# sourceMappingURL=currencies.js.map

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

@@ -6,16 +6,29 @@ export declare const chainId: {
 export type ChainId = ValueOf<typeof chainId>;
 /** Token addresses. */
 export declare const tokens: {
+    /** OpenUSD (OUSD), deployed at the same address on Tempo mainnet and Moderato. */
+    readonly ousd: "0x20c0000000000000000000006a37DA5C996874BE";
     /** USDC (USDC.e) token address. */
-    readonly usdc: '0x20C000000000000000000000b9537d11c60E8b50';
+    readonly usdc: `0x${string}`;
     /** pathUSD token address. */
-    readonly pathUsd: '0x20c0000000000000000000000000000000000000';
+    readonly pathUsd: "0x20c0000000000000000000000000000000000000";
 };
 /** Chain ID → default currency. */
 export declare const currency: {
-    readonly 4217: "0x20C000000000000000000000b9537d11c60E8b50";
+    readonly 4217: `0x${string}`;
     readonly 42431: "0x20c0000000000000000000000000000000000000";
 };
+/** Immutable canonical first-party machine-token deployments used by charge routes. */
+export declare const machineToken: Readonly<{
+    readonly 4217: Readonly<{
+        swap: "0xF72E5107c32C655ffA7539a3C8e97B7C3cE16A3F";
+        token: "0x20c000000000000000000000f37de3740ADec032";
+    }>;
+    readonly 42431: Readonly<{
+        swap: "0xd05f8EdFBB54Da0d765C9fE9b2B3f7d2E3a8C466";
+        token: "0x20c000000000000000000000f37de3740ADec032";
+    }>;
+}>;
 /**
  * Default token decimals for TIP-20 stablecoins (e.g. pathUSD, USDC).
  *

package/dist/tempo/internal/defaults.js

@@ -1,19 +1,34 @@
+import { getAddress } from 'viem';
+import { ousd, pathusd, usdce } from 'viem/tokens';
 export const chainId = {
     mainnet: 4217,
     testnet: 42431,
 };
 /** Token addresses. */
 export const tokens = {
+    /** OpenUSD (OUSD), deployed at the same address on Tempo mainnet and Moderato. */
+    ousd: ousd(chainId.mainnet).address,
     /** USDC (USDC.e) token address. */
-    usdc: '0x20C000000000000000000000b9537d11c60E8b50',
+    usdc: getAddress(usdce(chainId.mainnet).address),
     /** pathUSD token address. */
-    pathUsd: '0x20c0000000000000000000000000000000000000',
+    pathUsd: pathusd(chainId.mainnet).address,
 };
 /** Chain ID → default currency. */
 export const currency = {
     [chainId.mainnet]: tokens.usdc,
     [chainId.testnet]: tokens.pathUsd,
 };
+/** Immutable canonical first-party machine-token deployments used by charge routes. */
+export const machineToken = Object.freeze({
+    [chainId.mainnet]: Object.freeze({
+        swap: '0xF72E5107c32C655ffA7539a3C8e97B7C3cE16A3F',
+        token: '0x20c000000000000000000000f37de3740ADec032',
+    }),
+    [chainId.testnet]: Object.freeze({
+        swap: '0xd05f8EdFBB54Da0d765C9fE9b2B3f7d2E3a8C466',
+        token: '0x20c000000000000000000000f37de3740ADec032',
+    }),
+});
 /**
  * Default token decimals for TIP-20 stablecoins (e.g. pathUSD, USDC).
  *

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

@@ -1,4 +1,4 @@
-import type { TempoAddress } from 'ox/tempo';
+import { TempoAddress } from 'ox/tempo';
 import type { Hex } from 'viem';
 import type { Account } from 'viem';
 import { Transaction } from 'viem/tempo';
@@ -27,10 +27,10 @@ type ExpectedTransfer = {
 };
 /** Returns fee tokens that mppx allows sponsored transactions to charge. */
 export declare function defaultAllowedFeeTokens(chainId: number | undefined): `0x${string}`[];
-/** Rejects a sponsored fee token outside the server's allowlist. */
+/** Validates the fee-token address and, when supplied, the server's allowlist. */
 export declare function assertAllowedFeeToken(transaction: {
     feeToken?: unknown;
-}, allowedFeeTokens: readonly TempoAddress.Address[]): void;
+}, allowedFeeTokens?: readonly TempoAddress.Address[] | undefined): void;
 declare function hostedFeePayerRequest(transaction: SponsoredTransaction): {
     accessList?: any;
     calls: any;
@@ -56,7 +56,8 @@ declare function hostedFeePayerRequest(transaction: SponsoredTransaction): {
  *   simulate the exact transaction the sponsor broadcasts.
  */
 export declare function fillHostedFeePayerTransaction(parameters: {
-    allowedFeeTokens: readonly TempoAddress.Address[];
+    /** Optional merchant restriction on the hosted sponsor's token choice. */
+    allowedFeeTokens?: readonly TempoAddress.Address[] | undefined;
     challengeExpires?: string | undefined;
     chainId: number;
     details: Record<string, string>;

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

@@ -1,5 +1,5 @@
-import { Secp256k1 } from 'ox';
-import { TxEnvelopeTempo } from 'ox/tempo';
+import { Address, Secp256k1 } from 'ox';
+import { TempoAddress, TxEnvelopeTempo } from 'ox/tempo';
 import { decodeFunctionData, encodeFunctionData, maxUint256, toHex } from 'viem';
 import { Abis, Addresses, Transaction } from 'viem/tempo';
 import * as TempoAddress_internal from './address.js';
@@ -63,15 +63,17 @@ const supportedTransactionKeys = new Set([
 export function defaultAllowedFeeTokens(chainId) {
     return defaultFeeTokens(chainId);
 }
-/** Rejects a sponsored fee token outside the server's allowlist. */
+/** Validates the fee-token address and, when supplied, the server's allowlist. */
 export function assertAllowedFeeToken(transaction, allowedFeeTokens) {
     const { feeToken } = transaction;
     if (feeToken === undefined)
         return;
-    if (typeof feeToken !== 'string')
+    if (typeof feeToken !== 'string' ||
+        !(Address.validate(feeToken, { strict: false }) || TempoAddress.validate(feeToken)))
         throw new FeePayerValidationError('fee-sponsored transaction feeToken is invalid', {});
     const normalized = feeToken;
-    if (!allowedFeeTokens.some((allowed) => TempoAddress_internal.isEqual(allowed, normalized)))
+    if (allowedFeeTokens &&
+        !allowedFeeTokens.some((allowed) => TempoAddress_internal.isEqual(allowed, normalized)))
         throw new FeePayerValidationError('fee-sponsored transaction feeToken is not allowed', {
             feeToken,
         });

package/dist/tempo/internal/machine-token-charge.d.ts

@@ -0,0 +1,56 @@
+import type * as Hex from 'ox/Hex';
+import { type Address, type Client } from 'viem';
+type Call = {
+    data?: Hex.Hex | undefined;
+    to?: Address | undefined;
+    value?: bigint | undefined;
+};
+type RouteCall = {
+    data: Hex.Hex;
+    to: Address;
+};
+type Route = {
+    calls: readonly [RouteCall, RouteCall];
+    settlementSender: Address;
+    transfers: readonly [{
+        amount: bigint;
+        memo: Hex.Hex;
+        recipient: Address;
+    }];
+};
+type Transfer = {
+    amount: bigint | string;
+    memo?: string | undefined;
+    recipient: Address;
+};
+/** Returns whether a first-party machine-token charge route is deployed on a chain. */
+export declare function isSupported(chainId: number | undefined): boolean;
+/** Returns whether a currency is the machine token for a supported chain. */
+export declare function isMachineToken(parameters: {
+    chainId: number | undefined;
+    currency: Address;
+}): boolean;
+/** Resolves the canonical first-party settlement route for a compatible charge. */
+export declare function getRoute(parameters: {
+    chainId: number | undefined;
+    currency: Address;
+    transfers: readonly Transfer[];
+}): Route | undefined;
+/** Builds and simulates the first-party settlement route. */
+export declare function findRoute(client: Client, parameters: {
+    account: Address;
+    chainId: number;
+    currency: Address;
+    transfers: readonly Transfer[];
+}): Promise<Route | undefined>;
+/** Matches an exact first-party settlement route. */
+export declare function matchRoute(parameters: {
+    calls: readonly Call[];
+    chainId: number | undefined;
+    currency: Address;
+    transfers: readonly Transfer[];
+}): Route | undefined;
+/** Returns the trusted sender that settles the configured charge route on a chain. */
+export declare function getSettlementSender(chainId: number | undefined): Address | undefined;
+export {};
+//# sourceMappingURL=machine-token-charge.d.ts.map

package/dist/tempo/internal/machine-token-charge.js

@@ -0,0 +1,108 @@
+import { decodeFunctionData, encodeFunctionData, isAddress, isAddressEqual, parseAbi, } from 'viem';
+import { call, readContract } from 'viem/actions';
+import { Abis, Actions } from 'viem/tempo';
+import * as defaults from './defaults.js';
+const machineTokenSwapperAbi = parseAbi([
+    'function swapTo(address inputToken,uint256 amount,address targetToken,address recipient,bytes32 memo)',
+]);
+function getDeployment(chainId) {
+    if (chainId === undefined)
+        return undefined;
+    return defaults.machineToken[chainId];
+}
+/** Returns whether a first-party machine-token charge route is deployed on a chain. */
+export function isSupported(chainId) {
+    return !!getDeployment(chainId);
+}
+/** Returns whether a currency is the machine token for a supported chain. */
+export function isMachineToken(parameters) {
+    const deployment = getDeployment(parameters.chainId);
+    return (!!deployment &&
+        isAddress(parameters.currency, { strict: false }) &&
+        isAddressEqual(parameters.currency, deployment.token));
+}
+/** Resolves the canonical first-party settlement route for a compatible charge. */
+export function getRoute(parameters) {
+    const deployment = getDeployment(parameters.chainId);
+    const transfer = parameters.transfers.length === 1 ? parameters.transfers[0] : undefined;
+    if (!deployment || !transfer?.memo)
+        return undefined;
+    const amount = BigInt(transfer.amount);
+    const memo = transfer.memo;
+    return {
+        calls: [
+            {
+                data: encodeFunctionData({
+                    abi: Abis.tip20,
+                    functionName: 'approve',
+                    args: [deployment.swap, amount],
+                }),
+                to: deployment.token,
+            },
+            {
+                data: encodeFunctionData({
+                    abi: machineTokenSwapperAbi,
+                    functionName: 'swapTo',
+                    args: [deployment.token, amount, parameters.currency, transfer.recipient, memo],
+                }),
+                to: deployment.swap,
+            },
+        ],
+        settlementSender: deployment.swap,
+        transfers: [{ amount, memo, recipient: transfer.recipient }],
+    };
+}
+/** Builds and simulates the first-party settlement route. */
+export async function findRoute(client, parameters) {
+    const route = getRoute(parameters);
+    if (!route)
+        return undefined;
+    try {
+        const balance = await readContract(client, Actions.token.getBalance.call(client, {
+            account: parameters.account,
+            token: route.calls[0].to,
+        }));
+        if (balance < route.transfers[0].amount)
+            return undefined;
+        await call(client, { account: parameters.account, calls: route.calls });
+        return route;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Matches an exact first-party settlement route. */
+export function matchRoute(parameters) {
+    const transfer = parameters.transfers.length === 1 ? parameters.transfers[0] : undefined;
+    const swap = parameters.calls[1];
+    if (!transfer || parameters.calls.length !== 2 || !swap?.data)
+        return undefined;
+    try {
+        const decoded = decodeFunctionData({ abi: machineTokenSwapperAbi, data: swap.data });
+        const route = getRoute({
+            ...parameters,
+            transfers: [{ ...transfer, memo: transfer.memo ?? decoded.args[4] }],
+        });
+        if (!route)
+            return undefined;
+        if (parameters.calls.some((call, index) => {
+            const expected = route.calls[index];
+            return (!call.data ||
+                !call.to ||
+                !expected ||
+                (call.value ?? 0n) !== 0n ||
+                !isAddressEqual(call.to, expected.to) ||
+                call.data.toLowerCase() !== expected.data.toLowerCase());
+        }))
+            return undefined;
+        return route;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Returns the trusted sender that settles the configured charge route on a chain. */
+export function getSettlementSender(chainId) {
+    return getDeployment(chainId)?.swap;
+}
+//# sourceMappingURL=machine-token-charge.js.map

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

@@ -45,6 +45,18 @@ export declare namespace charge {
         } | undefined;
     };
     type Parameters = {
+        /**
+         * Tokens permitted for sponsored charge transaction fees, including tokens
+         * selected by a remote fee payer. Local sponsorship defaults to pathUSD and
+         * USDC.e on mainnet, and pathUSD on other chains. Hosted sponsorship has no
+         * token allowlist by default and trusts the configured provider's choice.
+         * A custom list replaces the local defaults and restricts hosted sponsorship.
+         * It must contain at least one token. Address validation and other sponsorship
+         * checks still apply. This does not change the payment currency or sessions.
+         */
+        allowedFeeTokens?: readonly `0x${string}`[] | undefined;
+        /** Enables first-party machine-token funding through the canonical swapper. */
+        machineTokenEnabled?: boolean | undefined;
         /** Render payment page when Accept header is text/html (e.g. in browsers) */
         html?: boolean | Html.Config | undefined;
         /**
@@ -56,7 +68,8 @@ export declare namespace charge {
         feePayerPolicy?: FeePayerPolicy | undefined;
         /**
          * Token a local fee payer uses to pay gas. If omitted, mppx selects a
-         * funded allowed token, preferring pathUSD.
+         * funded allowed token in `allowedFeeTokens` order (pathUSD first by default).
+         * An explicit token must also be in the allowed list.
          *
          * This option is not supported with a remote fee-payer URL, which selects
          * its own token.
@@ -99,6 +112,7 @@ export declare namespace charge {
          * relay broadcasts pull credentials, while it recognizes a push
          * credential as already broadcast and returns its receipt without sending
          * it again.
+         *
          */
         relay?: RelayOptions | undefined;
         /**