mppx 0.8.15 → 0.8.18

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

@@ -23,7 +23,7 @@ import * as SponsorBudget from './SponsorBudget.js';
 export declare function charge<const parameters extends charge.Parameters>(parameters?: NoExtraKeys<parameters, charge.Parameters>): Method.Server<typeof Methods.charge, charge.DeriveDefaults<parameters>>;
 export declare namespace charge {
     type StoreItemMap = {
-        [key: `mppx:charge:${string}`]: number | SponsorBudget.State;
+        [key: `mppx:charge:${string}`]: number | SponsorBudget.State | Store.ReplayMarker;
     };
     type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.charge>, 'feePayer' | 'recipient'>;
     type ValidateSender = (parameters: ValidateSenderParameters) => boolean | Promise<boolean>;
@@ -45,18 +45,15 @@ export declare namespace charge {
         } | undefined;
     };
     type Parameters = {
+        /** Enables first-party machine-token settlement for supported Tempo charges. */
+        machineTokenEnabled?: boolean | undefined;
         /** Render payment page when Accept header is text/html (e.g. in browsers) */
         html?: boolean | Html.Config | undefined;
         /**
          * Override the fee-sponsor policy used when co-signing Tempo charge
          * transactions. Defaults resolve per chain, including a higher
-         * priority-fee ceiling on Moderato and a bounded aggregate in-flight fee
-         * budget. Sponsored transactions reserve their declared maximum fee
-         * atomically; independent expiring-nonce transactions run concurrently
-         * while capacity remains and wait for capacity when the budget is full.
-         *
-         * If you increase `maxGas`, `maxFeePerGas`, or `maxTotalFee`, you may also
-         * need to raise `maxInFlightTotalFee`.
+         * priority-fee ceiling on Moderato. Aggregate in-flight exposure is
+         * configured separately with `sponsorBudget`.
          */
         feePayerPolicy?: FeePayerPolicy | undefined;
         /**
@@ -104,8 +101,17 @@ 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;
+        /**
+         * Configures aggregate in-flight fee exposure for sponsored transactions.
+         *
+         * Set to `false` only when aggregate exposure is enforced outside mppx.
+         * The configured store must be shared by every process using the sponsor.
+         * @default `{}`
+         */
+        sponsorBudget?: SponsorBudgetConfig | false | undefined;
         /**
          * Whether to wait for the charge transaction to confirm on-chain before
          * responding. @default true
@@ -118,21 +124,32 @@ export declare namespace charge {
          * the failure.
          */
         waitForConfirmation?: boolean | undefined;
-    } & Client.getResolver.Parameters & Account.resolve.Parameters & Defaults;
+    } & Client.getResolver.Parameters & Account.resolve.Parameters & Defaults & Method.ComposableHooks<typeof Methods.charge>;
     type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<parameters, Defaults, {
         currency: string;
         decimals: number;
     }>;
     type FeePayerPolicy = Partial<FeePayer.Policy> & {
-        /** Maximum number of sponsored transactions awaiting a terminal receipt. @default 100 */
+        /**
+         * Maximum number of sponsored transactions awaiting a terminal receipt.
+         * @deprecated Use `sponsorBudget.maxInFlightReservations`.
+         */
         maxInFlightReservations?: number | undefined;
         /**
          * Maximum aggregate declared fee exposure awaiting terminal receipts.
          *
-         * @default `maxTotalFee * 10`
+         * @deprecated Use `sponsorBudget.maxInFlightTotalFee`.
          */
         maxInFlightTotalFee?: bigint | undefined;
     };
+    type SponsorBudgetConfig = {
+        /** Maximum number of sponsored transactions awaiting a terminal receipt. @default 100 */
+        maxInFlightReservations?: number | undefined;
+        /** Maximum aggregate declared fee exposure. @default `feePayerPolicy.maxTotalFee * 10` */
+        maxInFlightTotalFee?: bigint | undefined;
+        /** Atomic store shared by every process using the sponsor. Defaults to `store`. */
+        store?: Store.AtomicStore | undefined;
+    };
     /** Tempo API relay configuration for server-side charges. */
     type RelayOptions = Relay.configure.Options;
 }

package/dist/tempo/server/Charge.js

@@ -1,5 +1,5 @@
 import * as SignatureEnvelope from 'ox/tempo/SignatureEnvelope';
-import { decodeFunctionData, formatUnits, keccak256, parseEventLogs, } from 'viem';
+import { createClient, decodeFunctionData, formatUnits, http, keccak256, parseEventLogs, } from 'viem';
 import { getTransactionReceipt, sendRawTransaction, sendRawTransactionSync, signTransaction, verifyTypedData, call as viem_call, } from 'viem/actions';
 import { Abis, Actions, Transaction } from 'viem/tempo';
 import { tempo as tempo_chain } from 'viem/tempo/chains';
@@ -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,19 +33,27 @@ 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, splits, supportedModes, validateSender, waitForConfirmation = true, } = parameters;
+    const { machineTokenEnabled, amount, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, description, externalId, feeToken: configuredFeeToken, feePayerPolicy, html, memo, 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 });
-    // Aggregate exposure belongs to the actual sponsor, not a caller-specific
-    // replay namespace. Sharing the raw store gives every tenant/process the same
-    // atomic sponsor-wide budget.
-    const sponsorBudgetStore = Store.from(rawStore);
-    const { maxInFlightReservations = 100, maxInFlightTotalFee = (feePayerPolicy?.maxTotalFee ?? 50000000000000000n) * 10n, ...transactionFeePayerPolicy } = feePayerPolicy ?? {};
-    if (!Number.isSafeInteger(maxInFlightReservations) || maxInFlightReservations <= 0)
-        throw new Error('`feePayerPolicy.maxInFlightReservations` must be a positive safe integer.');
-    if (maxInFlightTotalFee <= 0n)
-        throw new Error('`feePayerPolicy.maxInFlightTotalFee` must be greater than zero.');
+    const { maxInFlightReservations: legacyMaxInFlightReservations, maxInFlightTotalFee: legacyMaxInFlightTotalFee, ...transactionFeePayerPolicy } = feePayerPolicy ?? {};
+    const sponsorBudgetConfig = sponsorBudget === false ? undefined : (sponsorBudget ?? {});
+    const maxInFlightReservations = sponsorBudgetConfig?.maxInFlightReservations ?? legacyMaxInFlightReservations ?? 100;
+    const maxInFlightTotalFee = sponsorBudgetConfig?.maxInFlightTotalFee ??
+        legacyMaxInFlightTotalFee ??
+        (feePayerPolicy?.maxTotalFee ?? 50000000000000000n) * 10n;
+    if (sponsorBudgetConfig) {
+        if (!Number.isSafeInteger(maxInFlightReservations) || maxInFlightReservations <= 0)
+            throw new Error('`sponsorBudget.maxInFlightReservations` must be a positive safe integer.');
+        if (maxInFlightTotalFee <= 0n)
+            throw new Error('`sponsorBudget.maxInFlightTotalFee` must be greater than zero.');
+    }
+    // Aggregate exposure belongs to the actual sponsor, not a caller-specific replay namespace.
+    // Keep it unprefixed and shared across every tenant/process using the sponsor.
+    const sponsorBudgetStore = sponsorBudgetConfig
+        ? Store.from(sponsorBudgetConfig.store ?? rawStore)
+        : undefined;
     const proofStore = parameters.store
         ? Store.from(parameters.store, {
             keyPrefix: storeKeyPrefix,
@@ -76,12 +85,17 @@ export function charge(parameters = {}) {
         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 }),
@@ -93,11 +107,12 @@ export function charge(parameters = {}) {
             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, memo, methodDetails, recipient, settlementSenders, supportedModes, } = context;
         if (supportedModes && !supportedModes.includes('push'))
             throw new MismatchError('Hash credentials are not supported for this challenge.', {});
         const source = parseHashCredentialSource({
@@ -112,6 +127,7 @@ export function charge(parameters = {}) {
         const matchedLogs = await assertTransferLogs(receipt, {
             currency,
             sender,
+            settlementSenders,
             source,
             transfers,
             validateSender,
@@ -161,7 +177,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, memo, 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;
@@ -174,24 +190,40 @@ export function charge(parameters = {}) {
             requestAllowsFeePayer &&
             !!(typeof request.feePayer === 'object' ? request.feePayer : feePayer || feePayerUrl);
         const transfers = getExpectedTransfers({ amount, memo, methodDetails, recipient });
-        const matchedCalls = assertTransferCalls(transaction.calls ?? [], {
-            currency,
-            exactCount: isFeePayerTx,
-            transfers,
-        });
+        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,
+            });
         if (!memo)
             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) {
@@ -209,7 +241,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',
@@ -219,6 +251,7 @@ export function charge(parameters = {}) {
                     },
                     isFeePayerTx,
                     serializedTransaction,
+                    settlementSenders,
                     transaction,
                     transfers,
                     type: 'transaction',
@@ -227,7 +260,10 @@ export function charge(parameters = {}) {
         }
     }
     const method = Method.toServer(Methods.charge, {
+        canOffer: parameters.canOffer,
+        onPaymentSuccess: parameters.onPaymentSuccess,
         defaults: {
+            machineTokenEnabled,
             amount,
             currency,
             decimals,
@@ -288,6 +324,8 @@ export function charge(parameters = {}) {
             })();
             if (client.chain?.id !== chainId)
                 throw new Error(`Client not configured with chainId ${chainId}.`);
+            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;
@@ -301,6 +339,7 @@ export function charge(parameters = {}) {
             })();
             return {
                 ...request,
+                machineTokenEnabled: request.machineTokenEnabled || undefined,
                 chainId,
                 feePayer: resolvedFeePayer,
                 memo: request.memo || undefined,
@@ -329,10 +368,12 @@ export function charge(parameters = {}) {
                     : feePayer
                 : undefined;
             const expires = challenge.expires;
+            Expires.assert(expires, challenge.id);
+            const replayExpires = Date.parse(expires);
             switch (validated.type) {
                 case 'hash': {
                     const { hash, receipt } = validated;
-                    if (!(await markHashUsed(store, hash))) {
+                    if (!(await tryClaimHash(store, hash, replayExpires))) {
                         throw new VerificationFailedError({
                             reason: 'Transaction hash has already been used',
                         });
@@ -340,7 +381,7 @@ export function charge(parameters = {}) {
                     return receipt;
                 }
                 case 'proof': {
-                    if (proofStore && !(await markProofUsed(proofStore, challenge.id))) {
+                    if (proofStore && !(await tryClaimProof(proofStore, challenge.id, replayExpires))) {
                         throw new VerificationFailedError({
                             reason: 'Proof credential has already been used',
                         });
@@ -353,10 +394,10 @@ 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 markHashUsed(store, hash))) {
+                    if (!(await tryClaimHash(store, hash, replayExpires))) {
                         throw new VerificationFailedError({
                             reason: 'Transaction hash has already been used',
                         });
@@ -365,6 +406,9 @@ export function charge(parameters = {}) {
                     let finalHash;
                     let reservation;
                     try {
+                        const broadcastClient = feePayerUrl && isFeePayerTx
+                            ? createClient({ chain: client.chain, transport: http(feePayerUrl) })
+                            : client;
                         const allowedFeeTokens = FeePayer.defaultAllowedFeeTokens(chainId);
                         if (isFeePayerTx)
                             FeePayer.assertAllowedFeeToken(transaction, allowedFeeTokens);
@@ -427,10 +471,12 @@ export function charge(parameters = {}) {
                             }
                             return { serializedTransaction, sponsor: undefined };
                         })();
-                        const serializedTransaction_final = completedTransaction.serializedTransaction;
+                        // Nodes normalize accepted signature encodings before deriving transaction hashes.
+                        // Broadcast the same canonical envelope so replay keys match the node reference.
+                        const serializedTransaction_final = await Transaction.serialize(Transaction.deserialize(completedTransaction.serializedTransaction));
                         finalHash = keccak256(serializedTransaction_final);
                         if (finalHash.toLowerCase() !== hash.toLowerCase() &&
-                            !(await markHashUsed(store, finalHash)))
+                            !(await tryClaimHash(store, finalHash, replayExpires)))
                             throw new VerificationFailedError({
                                 reason: 'Transaction hash has already been used',
                             });
@@ -450,19 +496,20 @@ export function charge(parameters = {}) {
                             });
                             const expiresAt = validBeforeValue * 1_000;
                             const waitUntil = Math.min(expiresAt, expires ? Date.parse(expires) : Number.MAX_SAFE_INTEGER);
-                            reservation = await SponsorBudget.reserve(sponsorBudgetStore, {
-                                chainId: reservationChainId,
-                                expiresAt,
-                                fee: totalFee,
-                                getReceipt: (transactionHash) => getTransactionReceipt(client, { hash: transactionHash }),
-                                id: finalHash.toLowerCase(),
-                                maxReservations: maxInFlightReservations,
-                                maxTotalFee: maxInFlightTotalFee,
-                                owner: globalThis.crypto.randomUUID(),
-                                sponsor,
-                                transactionHash: finalHash,
-                                waitUntil,
-                            });
+                            if (sponsorBudgetStore)
+                                reservation = await SponsorBudget.reserve(sponsorBudgetStore, {
+                                    chainId: reservationChainId,
+                                    expiresAt,
+                                    fee: totalFee,
+                                    getReceipt: (transactionHash) => getTransactionReceipt(client, { hash: transactionHash }),
+                                    id: finalHash.toLowerCase(),
+                                    maxReservations: maxInFlightReservations,
+                                    maxTotalFee: maxInFlightTotalFee,
+                                    owner: globalThis.crypto.randomUUID(),
+                                    sponsor,
+                                    transactionHash: finalHash,
+                                    waitUntil,
+                                });
                             Expires.assert(challenge.expires, challenge.id);
                         }
                         // Pre-broadcast simulation for non-sponsored transactions.
@@ -475,7 +522,7 @@ export function charge(parameters = {}) {
                             });
                         broadcastAttempted = true;
                         if (waitForConfirmation) {
-                            const receipt = await sendRawTransactionSync(client, {
+                            const receipt = await sendRawTransactionSync(broadcastClient, {
                                 serializedTransaction: serializedTransaction_final,
                             });
                             if (reservation)
@@ -483,6 +530,7 @@ export function charge(parameters = {}) {
                             const matchedLogs = await assertTransferLogs(receipt, {
                                 currency,
                                 sender: transaction.from,
+                                settlementSenders,
                                 transfers,
                             });
                             if (!memo)
@@ -499,7 +547,7 @@ 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 reference = await sendRawTransaction(client, {
+                        const reference = await sendRawTransaction(broadcastClient, {
                             serializedTransaction: serializedTransaction_final,
                         });
                         if (reference.toLowerCase() !== finalHash.toLowerCase())
@@ -538,10 +586,11 @@ 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, memo, splits, supportedModes, ...methodDetailsRest } = methodDetails ?? {};
     methodDetailsRest;
     void feePayer;
     return {
+        machineTokenEnabled,
         amount,
         chainId,
         currency,
@@ -683,7 +732,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;
@@ -758,6 +809,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({
@@ -774,12 +828,8 @@ function getHashStoreKey(hash) {
 function getProofStoreKey(challengeId) {
     return `mppx:charge:proof:${challengeId}`;
 }
-async function markHashUsed(store, hash) {
-    return store.update(getHashStoreKey(hash), (current) => {
-        if (current !== null)
-            return { op: 'noop', result: false };
-        return { op: 'set', value: Date.now(), result: true };
-    });
+async function tryClaimHash(store, hash, expires) {
+    return Store.tryClaim(store, getHashStoreKey(hash), expires);
 }
 /** @internal */
 async function releaseHashUse(store, hash) {
@@ -796,12 +846,8 @@ function parseHashCredentialSource(parameters) {
     return parsed;
 }
 /** @internal */
-async function markProofUsed(store, challengeId) {
-    return store.update(getProofStoreKey(challengeId), (current) => {
-        if (current !== null)
-            return { op: 'noop', result: false };
-        return { op: 'set', value: Date.now(), result: true };
-    });
+async function tryClaimProof(store, challengeId, expires) {
+    return Store.tryClaim(store, getProofStoreKey(challengeId), expires);
 }
 function recoverAuthorizedProofSigner(parameters) {
     const { chainId, challengeId, realm, signature, sourceAddress } = parameters;