mppx 0.10.1 → 0.12.0

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,9 @@ 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, allowedFeeTokens: configuredAllowedFeeTokens, amount, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, description, externalId, feeToken: configuredFeeToken, feePayerPolicy, html, relay, sponsorBudget, splits, supportedModes, validateSender, waitForConfirmation = true, } = parameters;
+    if (configuredAllowedFeeTokens?.length === 0)
+        throw new Error('`allowedFeeTokens` must contain at least one token.');
     const storeKeyPrefix = parameters.storeKeyPrefix ?? '';
     const rawStore = (parameters.store ?? Store.memory());
     const store = Store.from(rawStore, { keyPrefix: storeKeyPrefix });
@@ -83,36 +86,45 @@ 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.', {});
+        // Request-level local sponsorship takes precedence over the hosted provider.
+        const localFeePayer = Account.is(request.feePayer) ? request.feePayer : feePayer;
+        const allowedFeeTokens = configuredAllowedFeeTokens ??
+            (localFeePayer || !remoteFeePayer ? FeePayer.defaultAllowedFeeTokens(chainId) : undefined);
         return {
+            allowedFeeTokens,
             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 +132,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 +181,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 +193,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 });
-            FeePayer.assertAllowedFeeToken(transaction, FeePayer.defaultAllowedFeeTokens(chainId));
+            if (!machineTokenRoute)
+                FeePayer.validateCalls(transaction.calls, { amount, currency, recipient }, { currency, expectedTransfers: transfers });
+            FeePayer.assertAllowedFeeToken(transaction, context.allowedFeeTokens);
         }
         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 +244,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 +254,7 @@ export function charge(parameters = {}) {
                     },
                     isFeePayerTx,
                     serializedTransaction,
+                    settlementSenders,
                     transaction,
                     transfers,
                     type: 'transaction',
@@ -238,12 +266,12 @@ export function charge(parameters = {}) {
         canOffer: parameters.canOffer,
         onPaymentSuccess: parameters.onPaymentSuccess,
         defaults: {
+            machineTokenEnabled,
             amount,
             currency,
             decimals,
             description,
             externalId,
-            memo,
             recipient,
             splits,
             supportedModes,
@@ -284,6 +312,8 @@ export function charge(parameters = {}) {
             const chainId = await (async () => {
                 if (request.chainId)
                     return request.chainId;
+                if (parameters.chainId !== undefined)
+                    return parameters.chainId;
                 if (parameters.testnet)
                     return defaults.chainId.testnet;
                 return (await getClient({})).chain?.id;
@@ -298,6 +328,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 +345,9 @@ export function charge(parameters = {}) {
             })();
             return {
                 ...request,
+                machineTokenEnabled: request.machineTokenEnabled || undefined,
                 chainId,
                 feePayer: resolvedFeePayer,
-                memo: request.memo || undefined,
             };
         },
         async validate({ credential, request }) {
@@ -328,7 +365,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 +399,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))) {
@@ -374,12 +411,10 @@ export function charge(parameters = {}) {
                     let finalHash;
                     let reservation;
                     try {
-                        const allowedFeeTokens = FeePayer.defaultAllowedFeeTokens(chainId);
-                        if (isFeePayerTx)
-                            FeePayer.assertAllowedFeeToken(transaction, allowedFeeTokens);
-                        const selectableFeeTokens = allowedFeeTokens;
+                        const { allowedFeeTokens } = context;
                         const completedTransaction = await (async () => {
                             if (feePayerAccount && methodDetails?.feePayer !== false) {
+                                const selectableFeeTokens = allowedFeeTokens ?? FeePayer.defaultAllowedFeeTokens(chainId);
                                 const completed = await FeePayer.preflightSponsorship({
                                     transaction,
                                     simulate: (request) => viem_call(client, request),
@@ -394,7 +429,7 @@ export function charge(parameters = {}) {
                                             }));
                                         const sponsored = FeePayer.prepareSponsoredTransaction({
                                             account: feePayerAccount,
-                                            allowedFeeTokens,
+                                            allowedFeeTokens: selectableFeeTokens,
                                             challengeExpires: expires,
                                             chainId: chainId ?? client.chain.id,
                                             details: { amount, currency, recipient },
@@ -495,13 +530,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 +585,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 +604,6 @@ function getExpectedTransfers(parameters) {
     return Charge_internal.getTransfers({
         amount: parameters.amount,
         methodDetails: {
-            memo: parameters.memo,
             splits: parameters.methodDetails?.splits,
         },
         recipient: parameters.recipient,
@@ -695,7 +729,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 +806,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({
@@ -869,34 +908,29 @@ function toReceipt(receipt) {
         reference: transactionHash,
     };
 }
-/**
- * Asserts that at least one of the matched payment logs carries a
- * challenge-bound memo nonce (keccak256(challengeId)[0..6] in bytes 25–31).
- * Only checks logs that were matched by `assertTransferLogs`, not the
- * entire receipt — preventing unrelated dust transfers from satisfying
- * the binding.
- * @internal
- */
 function assertChallengeBoundMemo(matchedLogs, parameters) {
-    const bound = matchedLogs.some((log) => {
-        if (log.kind !== 'memo')
-            return false;
-        if (!Attribution.verifyServer(log.args.memo, parameters.realm))
-            return false;
-        return Attribution.verifyChallengeBinding(log.args.memo, parameters.challengeId);
-    });
-    if (!bound)
-        throw new MismatchError('Payment verification failed: memo is not bound to this challenge.', {});
+    assertChallengeBoundMemos(matchedLogs.map((log) => (log.kind === 'memo' ? log.args.memo : undefined)), parameters);
 }
 function assertChallengeBoundCallMemo(matchedCalls, parameters) {
-    const bound = matchedCalls.some((call) => {
-        if (!call.memo)
-            return false;
-        const memo = call.memo;
-        if (!Attribution.verifyServer(memo, parameters.realm))
-            return false;
-        return Attribution.verifyChallengeBinding(memo, parameters.challengeId);
-    });
+    assertChallengeBoundMemos(matchedCalls.map((call) => call.memo), parameters);
+}
+/**
+ * Requires a challenge-bound attribution memo and rejects conflicting attribution
+ * on matched payment transfers. Otherwise, a split payment could authorize another
+ * challenge after the first challenge's replay marker expires. Unmatched transfers
+ * cannot establish the binding; plain transfers and non-MPP memos remain allowed.
+ * @internal
+ */
+function assertChallengeBoundMemos(memos, parameters) {
+    let bound = false;
+    for (const memo of memos) {
+        if (!memo || !Attribution.isMppMemo(memo))
+            continue;
+        if (!Attribution.verifyServer(memo, parameters.realm) ||
+            !Attribution.verifyChallengeBinding(memo, parameters.challengeId))
+            throw new MismatchError('Payment verification failed: memo is not bound to this challenge.', {});
+        bound = true;
+    }
     if (!bound)
         throw new MismatchError('Payment verification failed: memo is not bound to this challenge.', {});
 }