mppx 0.10.0 → 0.11.0

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,8 @@ export declare namespace charge {
         } | undefined;
     };
     type Parameters = {
+        /** 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;
         /**
@@ -99,6 +101,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;
         /**

package/dist/tempo/server/Charge.js

@@ -15,6 +15,7 @@ import * as Charge_internal from '../internal/charge.js';
 import * as defaults from '../internal/defaults.js';
 import * as FeePayer from '../internal/fee-payer.js';
 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 Methods from '../Methods.js';
@@ -32,7 +33,7 @@ import * as SponsorBudget from './SponsorBudget.js';
  * ```
  */
 export function charge(parameters = {}) {
-    const { amount, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, description, externalId, feeToken: configuredFeeToken, feePayerPolicy, html, memo, relay, sponsorBudget, splits, supportedModes, validateSender, waitForConfirmation = true, } = parameters;
+    const { machineTokenEnabled, amount, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, description, externalId, feeToken: configuredFeeToken, feePayerPolicy, html, relay, sponsorBudget, splits, supportedModes, validateSender, waitForConfirmation = true, } = parameters;
     const storeKeyPrefix = parameters.storeKeyPrefix ?? '';
     const rawStore = (parameters.store ?? Store.memory());
     const store = Store.from(rawStore, { keyPrefix: storeKeyPrefix });
@@ -83,36 +84,40 @@ export function charge(parameters = {}) {
         const supportedModes = methodDetails?.supportedModes;
         const currency = resolvedRequest.currency;
         const recipient = resolvedRequest.recipient;
-        const memo = methodDetails?.memo;
+        const machineTokenEnabled = methodDetails?.machineTokenEnabled === true;
+        const settlementSender = machineTokenEnabled
+            ? MachineTokenCharge.getSettlementSender(chainId)
+            : undefined;
         const isZeroAmount = BigInt(amount) === 0n;
         Expires.assert(challenge.expires, challenge.id);
         if (isZeroAmount && payload.type !== 'proof')
             throw new MismatchError('Zero-amount challenges require a proof credential.', {});
         return {
             amount,
+            machineTokenEnabled,
             chainId,
             challenge,
             client: await getClient({ chainId }),
             currency,
             isZeroAmount,
-            memo,
             methodDetails,
             payload,
             recipient,
             requestAllowsFeePayer: request.feePayer !== false,
             resolvedRequest,
+            settlementSenders: settlementSender ? [settlementSender] : [],
             supportedModes,
         };
     }
     async function validateHashCredential(credential, payload, context) {
-        const { amount, chainId, challenge, client, currency, memo, methodDetails, recipient, supportedModes, } = context;
+        const { amount, chainId, challenge, client, currency, methodDetails, recipient, settlementSenders, supportedModes, } = context;
         if (supportedModes && !supportedModes.includes('push'))
             throw new MismatchError('Hash credentials are not supported for this challenge.', {});
         const source = parseHashCredentialSource({
             chainId: chainId ?? client.chain?.id,
             source: credential.source,
         });
-        const transfers = getExpectedTransfers({ amount, memo, methodDetails, recipient });
+        const transfers = getExpectedTransfers({ amount, methodDetails, recipient });
         const receipt = await getTransactionReceipt(client, {
             hash: payload.hash,
         });
@@ -120,15 +125,15 @@ export function charge(parameters = {}) {
         const matchedLogs = await assertTransferLogs(receipt, {
             currency,
             sender,
+            settlementSenders,
             source,
             transfers,
             validateSender,
         });
-        if (!memo)
-            assertChallengeBoundMemo(matchedLogs, {
-                challengeId: challenge.id,
-                realm: challenge.realm,
-            });
+        assertChallengeBoundMemo(matchedLogs, {
+            challengeId: challenge.id,
+            realm: challenge.realm,
+        });
         return { receipt: toReceipt(receipt), sender, transfers };
     }
     async function validateProofCredential(credential, payload, context) {
@@ -169,7 +174,7 @@ export function charge(parameters = {}) {
         return { sender: source.address };
     }
     async function validateTransactionCredential(credential, payload, request, context) {
-        const { amount, chainId, challenge, client, currency, memo, methodDetails, recipient, requestAllowsFeePayer, supportedModes, } = context;
+        const { machineTokenEnabled, amount, chainId, challenge, client, currency, methodDetails, recipient, requestAllowsFeePayer, supportedModes, } = context;
         if (supportedModes && !supportedModes.includes('pull'))
             throw new MismatchError('Transaction credentials are not supported for this challenge.', {});
         const serializedTransaction = payload.signature;
@@ -181,25 +186,40 @@ export function charge(parameters = {}) {
         const isFeePayerTx = methodDetails?.feePayer === true &&
             requestAllowsFeePayer &&
             !!(Account.is(request.feePayer) ? request.feePayer : feePayer || remoteFeePayer);
-        const transfers = getExpectedTransfers({ amount, memo, methodDetails, recipient });
-        const matchedCalls = assertTransferCalls(transaction.calls ?? [], {
-            currency,
-            exactCount: isFeePayerTx,
-            transfers,
-        });
-        if (!memo)
-            assertChallengeBoundCallMemo(matchedCalls, {
-                challengeId: challenge.id,
-                realm: challenge.realm,
+        const transfers = getExpectedTransfers({ amount, methodDetails, recipient });
+        const machineTokenRoute = machineTokenEnabled
+            ? MachineTokenCharge.matchRoute({
+                calls: transaction.calls ?? [],
+                chainId: chainId ?? client.chain?.id,
+                currency,
+                transfers,
+            })
+            : undefined;
+        const matchedCalls = machineTokenRoute?.transfers ??
+            assertTransferCalls(transaction.calls ?? [], {
+                currency,
+                exactCount: isFeePayerTx,
+                transfers,
             });
+        assertChallengeBoundCallMemo(matchedCalls, {
+            challengeId: challenge.id,
+            realm: challenge.realm,
+        });
         if (isFeePayerTx) {
-            FeePayer.validateCalls(transaction.calls, { amount, currency, recipient }, { currency, expectedTransfers: transfers });
+            if (!machineTokenRoute)
+                FeePayer.validateCalls(transaction.calls, { amount, currency, recipient }, { currency, expectedTransfers: transfers });
             FeePayer.assertAllowedFeeToken(transaction, FeePayer.defaultAllowedFeeTokens(chainId));
         }
         else {
             await viem_call(client, FeePayer.simulationTransaction(transaction, { feePayer: false }));
         }
-        return { isFeePayerTx, serializedTransaction, transaction, transfers };
+        return {
+            isFeePayerTx,
+            serializedTransaction,
+            settlementSenders: machineTokenRoute ? [machineTokenRoute.settlementSender] : [],
+            transaction,
+            transfers,
+        };
     }
     async function validateCredential(credential, request, context) {
         switch (context.payload.type) {
@@ -217,7 +237,7 @@ export function charge(parameters = {}) {
                 return { details: { mode: 'proof', sender }, type: 'proof' };
             }
             case 'transaction': {
-                const { isFeePayerTx, serializedTransaction, transaction, transfers } = await validateTransactionCredential(credential, context.payload, request, context);
+                const { isFeePayerTx, serializedTransaction, settlementSenders, transaction, transfers } = await validateTransactionCredential(credential, context.payload, request, context);
                 return {
                     details: {
                         mode: 'pull',
@@ -227,6 +247,7 @@ export function charge(parameters = {}) {
                     },
                     isFeePayerTx,
                     serializedTransaction,
+                    settlementSenders,
                     transaction,
                     transfers,
                     type: 'transaction',
@@ -238,12 +259,12 @@ export function charge(parameters = {}) {
         canOffer: parameters.canOffer,
         onPaymentSuccess: parameters.onPaymentSuccess,
         defaults: {
+            machineTokenEnabled,
             amount,
             currency,
             decimals,
             description,
             externalId,
-            memo,
             recipient,
             splits,
             supportedModes,
@@ -298,6 +319,13 @@ export function charge(parameters = {}) {
             })();
             if (client.chain?.id !== chainId)
                 throw new Error(`Client not configured with chainId ${chainId}.`);
+            if (MachineTokenCharge.isMachineToken({
+                chainId,
+                currency: request.currency,
+            }))
+                throw new Error('MACH cannot be advertised as a charge currency. Advertise the settlement currency with `machineTokenEnabled: true`.');
+            if (request.machineTokenEnabled && !MachineTokenCharge.isSupported(chainId))
+                throw new Error(`Machine tokens are not supported on chainId ${chainId}.`);
             const resolvedFeePayer = (() => {
                 if (request.feePayer === false)
                     return credential ? false : undefined;
@@ -308,9 +336,9 @@ export function charge(parameters = {}) {
             })();
             return {
                 ...request,
+                machineTokenEnabled: request.machineTokenEnabled || undefined,
                 chainId,
                 feePayer: resolvedFeePayer,
-                memo: request.memo || undefined,
             };
         },
         async validate({ credential, request }) {
@@ -328,7 +356,7 @@ export function charge(parameters = {}) {
         },
         async broadcast({ credential, request }) {
             const context = await resolveCredentialContext({ credential, request });
-            const { amount, chainId, challenge, client, currency, memo, methodDetails, recipient, requestAllowsFeePayer, } = context;
+            const { amount, chainId, challenge, client, currency, methodDetails, recipient, requestAllowsFeePayer, } = context;
             const validated = await validateCredential(credential, request, context);
             const feePayerAccount = methodDetails?.feePayer === true && requestAllowsFeePayer
                 ? Account.is(request.feePayer)
@@ -362,7 +390,7 @@ export function charge(parameters = {}) {
                     };
                 }
                 case 'transaction': {
-                    const { isFeePayerTx, serializedTransaction, transaction, transfers } = validated;
+                    const { isFeePayerTx, serializedTransaction, settlementSenders, transaction, transfers } = validated;
                     // Pre-broadcast dedup: catch exact byte-for-byte replays early.
                     const hash = keccak256(serializedTransaction);
                     if (!(await tryClaimHash(store, hash, replayExpires))) {
@@ -495,13 +523,13 @@ export function charge(parameters = {}) {
                             const matchedLogs = await assertTransferLogs(receipt, {
                                 currency,
                                 sender: transaction.from,
+                                settlementSenders,
                                 transfers,
                             });
-                            if (!memo)
-                                assertChallengeBoundMemo(matchedLogs, {
-                                    challengeId: challenge.id,
-                                    realm: challenge.realm,
-                                });
+                            assertChallengeBoundMemo(matchedLogs, {
+                                challengeId: challenge.id,
+                                realm: challenge.realm,
+                            });
                             if (receipt.transactionHash.toLowerCase() !== finalHash.toLowerCase())
                                 throw new VerificationFailedError({
                                     reason: 'Broadcast transaction hash does not match the signed transaction',
@@ -550,16 +578,16 @@ 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, memo, splits, supportedModes, ...methodDetailsRest } = methodDetails ?? {};
+    const { chainId, feePayer, machineTokenEnabled, splits, supportedModes, ...methodDetailsRest } = methodDetails ?? {};
     methodDetailsRest;
     void feePayer;
     return {
+        machineTokenEnabled,
         amount,
         chainId,
         currency,
         description,
         externalId,
-        memo,
         recipient,
         splits,
         supportedModes,
@@ -569,7 +597,6 @@ function getExpectedTransfers(parameters) {
     return Charge_internal.getTransfers({
         amount: parameters.amount,
         methodDetails: {
-            memo: parameters.memo,
             splits: parameters.methodDetails?.splits,
         },
         recipient: parameters.recipient,
@@ -695,7 +722,9 @@ async function assertTransferLogs(receipt, parameters) {
             if (!(await isValidTransferSender({
                 expectedSender: parameters.sender,
                 sender: log.args.from,
+                settlementSenders: parameters.settlementSenders,
                 source: parameters.source,
+                transactionSender: receipt.from,
                 validateSender: parameters.validateSender,
             })))
                 continue;
@@ -770,6 +799,9 @@ function isSameTransferLog(a, b) {
 async function isValidTransferSender(parameters) {
     if (TempoAddress.isEqual(parameters.sender, parameters.expectedSender))
         return true;
+    if (TempoAddress.isEqual(parameters.transactionSender, parameters.expectedSender) &&
+        parameters.settlementSenders?.some((sender) => TempoAddress.isEqual(parameters.sender, sender)))
+        return true;
     if (!parameters.validateSender)
         return false;
     return parameters.validateSender({

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

@@ -37,6 +37,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
             }, 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<const parameters extends tempo.Parameters>(paramet
             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<const parameters extends tempo.Parameters>(paramet
             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<const parameters extends tempo.Parameters>(paramet
                 supportedModes?: ("pull" | "push")[] | undefined;
             } | undefined;
         }, {
+            machineTokenEnabled?: boolean | undefined;
             amount: string;
             chainId?: number | undefined;
             currency: string;
@@ -80,7 +82,7 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
             description?: string | undefined;
             externalId?: string | undefined;
             feePayer?: boolean | undefined;
-            memo?: string | undefined;
+            memo?: undefined;
             recipient?: string | undefined;
             splits?: {
                 amount: string;
@@ -181,7 +183,10 @@ export declare function tempo<const parameters extends tempo.Parameters>(paramet
     };
 }, session_.DeriveDefaults<parameters>, parameters["sse"] extends false | undefined ? undefined : import("./internal/transport.js").Sse, session_.Extensions, undefined>];
 export declare namespace tempo {
-    type Parameters = charge_.Parameters & session_.Parameters;
+    type Parameters = Omit<charge_.Parameters, 'machineTokenEnabled'> & session_.Parameters & {
+        /** Enables MACH funding for compatible Tempo methods. Currently applies to `charge`. */
+        machineTokenEnabled?: boolean | undefined;
+    };
     /** Tempo API relay configuration for server-side charges. */
     type RelayOptions = charge_.RelayOptions;
     /** Stable failure codes returned by Tempo API's MPP relay. */

package/dist/tempo/server/Methods.js

@@ -14,8 +14,11 @@ function createChargeMethod(parameters) {
     return tempo.charge(parameters);
 }
 function createSessionMethod(parameters) {
-    // See `createChargeMethod()`: session receives the same shared parameter bag.
-    return sessionServer(parameters);
+    // Machine-token funding is configured at the Tempo family level, but only
+    // charge implements it today. Keep it out of session configuration until
+    // session routing has its own complete lifecycle support.
+    const { machineTokenEnabled: _machineTokenEnabled, ...sessionParameters } = parameters ?? {};
+    return sessionServer(sessionParameters);
 }
 /**
  * Creates the common Tempo `charge` and `session` methods from shared parameters.