mppx 0.13.3 → 0.13.5

package/dist/tempo/server/Charge.js

@@ -1,9 +1,9 @@
 import * as SignatureEnvelope from 'ox/tempo/SignatureEnvelope';
-import { decodeFunctionData, formatUnits, keccak256, parseEventLogs, } from 'viem';
-import { getTransaction, getTransactionReceipt, sendRawTransaction, sendRawTransactionSync, signTransaction, verifyTypedData, call as viem_call, } from 'viem/actions';
+import { decodeFunctionData, formatUnits, keccak256, parseEventLogs, WaitForTransactionReceiptTimeoutError, } from 'viem';
+import { getTransaction, getTransactionReceipt, sendRawTransaction, sendRawTransactionSync, signTransaction, verifyTypedData, waitForTransactionReceipt, call as viem_call, } from 'viem/actions';
 import { Abis, Actions, Transaction } from 'viem/tempo';
 import { tempo as tempo_chain } from 'viem/tempo/chains';
-import { PaymentError, VerificationFailedError } from '../../Errors.js';
+import { CredentialReplayedError, PaymentError, VerificationFailedError } from '../../Errors.js';
 import * as Expires from '../../Expires.js';
 import * as Method from '../../Method.js';
 import * as Store from '../../Store.js';
@@ -19,6 +19,7 @@ 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';
+import { fallbackStore } from './internal/fallback-store.js';
 import { html as htmlContent } from './internal/html.gen.js';
 import * as Relay from './Relay.js';
 import * as SponsorBudget from './SponsorBudget.js';
@@ -33,11 +34,12 @@ import * as SponsorBudget from './SponsorBudget.js';
  * ```
  */
 export function charge(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;
+    const { machineTokenEnabled, allowedFeeTokens: configuredAllowedFeeTokens, amount, confirmationTimeoutMs = 30_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, description, externalId, feeToken: configuredFeeToken, feePayerPolicy, html, relay, sponsorBudget, splits, supportedModes, validateSender, waitForConfirmation = true, } = parameters;
     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 rawStore = (parameters.store ??
+        fallbackStore('tempo.charge'));
     const store = Store.from(rawStore, { keyPrefix: storeKeyPrefix });
     const { maxInFlightReservations: legacyMaxInFlightReservations, maxInFlightTotalFee: legacyMaxInFlightTotalFee, ...transactionFeePayerPolicy } = feePayerPolicy ?? {};
     const sponsorBudgetConfig = sponsorBudget === false ? undefined : (sponsorBudget ?? {});
@@ -178,7 +180,13 @@ export function charge(parameters = {}) {
             challengeId: challenge.id,
             realm: challenge.realm,
         });
-        return { receipt, sender, transfers };
+        // The payer is the account the matched transfers debited, not the submitter.
+        // Settlement-contract transfers are funded by the transaction sender.
+        const payers = new Set(matchedLogs.map(({ args }) => (settlementSenders.some((settlementSender) => TempoAddress.isEqual(settlementSender, args.from))
+            ? receipt.from
+            : args.from).toLowerCase()));
+        const payer = payers.size === 1 ? [...payers][0] : undefined;
+        return { payer, receipt, sender, transfers };
     }
     async function validateProofCredential(credential, payload, context) {
         const { chainId, challenge, client, isZeroAmount } = context;
@@ -258,17 +266,22 @@ export function charge(parameters = {}) {
     async function validateCredential(credential, request, context) {
         switch (context.payload.type) {
             case 'hash': {
-                const { receipt, sender, transfers } = await validateHashCredential(credential, context.payload, context);
+                const { payer, receipt, sender, transfers } = await validateHashCredential(credential, context.payload, context);
                 return {
                     details: { mode: 'push', sender, transfers },
                     hash: context.payload.hash,
+                    payer,
                     receipt,
                     type: 'hash',
                 };
             }
             case 'proof': {
                 const { sender } = await validateProofCredential(credential, context.payload, context);
-                return { details: { mode: 'proof', sender }, type: 'proof' };
+                return {
+                    details: { mode: 'proof', sender },
+                    payer: sender,
+                    type: 'proof',
+                };
             }
             case 'transaction': {
                 const { fundingCurrency, isFeePayerTx, serializedTransaction, settlementSenders, transaction, transfers, } = await validateTransactionCredential(credential, context.payload, request, context);
@@ -281,6 +294,7 @@ export function charge(parameters = {}) {
                     },
                     fundingCurrency,
                     isFeePayerTx,
+                    payer: transaction.from,
                     serializedTransaction,
                     settlementSenders,
                     transaction,
@@ -387,6 +401,7 @@ export function charge(parameters = {}) {
                 details: validated.details,
                 intent: 'charge',
                 method: 'tempo',
+                payer: validated.payer,
                 request: context.resolvedRequest,
                 source: credential.source,
             };
@@ -407,7 +422,7 @@ export function charge(parameters = {}) {
                 case 'hash': {
                     const { hash, receipt } = validated;
                     if (!(await tryClaimHash(store, hash, replayExpires))) {
-                        throw new VerificationFailedError({
+                        throw new CredentialReplayedError({
                             reason: 'Transaction hash has already been used',
                         });
                     }
@@ -427,7 +442,7 @@ export function charge(parameters = {}) {
                 }
                 case 'proof': {
                     if (proofStore && !(await tryClaimProof(proofStore, challenge.id, replayExpires))) {
-                        throw new VerificationFailedError({
+                        throw new CredentialReplayedError({
                             reason: 'Proof credential has already been used',
                         });
                     }
@@ -438,7 +453,7 @@ export function charge(parameters = {}) {
                     // Pre-broadcast dedup: catch exact byte-for-byte replays early.
                     const hash = keccak256(serializedTransaction);
                     if (!(await tryClaimHash(store, hash, replayExpires))) {
-                        throw new VerificationFailedError({
+                        throw new CredentialReplayedError({
                             reason: 'Transaction hash has already been used',
                         });
                     }
@@ -480,6 +495,13 @@ export function charge(parameters = {}) {
                                         return { feePayer: feePayerAccount.address, transaction: sponsored };
                                     },
                                 });
+                                FeePayer.assertTransactionPolicy({
+                                    challengeExpires: expires,
+                                    chainId: chainId ?? client.chain.id,
+                                    details: { amount, currency, recipient },
+                                    policy: transactionFeePayerPolicy,
+                                    transaction: completed.transaction,
+                                });
                                 return {
                                     serializedTransaction: await signTransaction(client, completed.transaction),
                                     sponsor: completed.feePayer,
@@ -515,7 +537,7 @@ export function charge(parameters = {}) {
                         finalHash = keccak256(serializedTransaction_final);
                         if (finalHash.toLowerCase() !== hash.toLowerCase()) {
                             if (!(await tryClaimHash(store, finalHash, replayExpires)))
-                                throw new VerificationFailedError({
+                                throw new CredentialReplayedError({
                                     reason: 'Transaction hash has already been used',
                                 });
                             claimedFinalHash = finalHash;
@@ -560,11 +582,51 @@ export function charge(parameters = {}) {
                             throw new VerificationFailedError({
                                 reason: 'Sponsor budget reservation ownership was lost before broadcast',
                             });
+                        if (isFeePayerTx)
+                            FeePayer.assertTransactionPolicy({
+                                challengeExpires: expires,
+                                chainId: chainId ?? client.chain.id,
+                                details: { amount, currency, recipient },
+                                policy: transactionFeePayerPolicy,
+                                transaction,
+                            });
                         broadcastAttempted = true;
                         if (waitForConfirmation) {
-                            const receipt = await sendRawTransactionSync(client, {
-                                serializedTransaction: serializedTransaction_final,
-                            });
+                            const start = Date.now();
+                            // The sync send gets at most 2/3 of the budget, reserving the rest for recovery.
+                            const sendTimeoutMs = Math.floor((confirmationTimeoutMs * 2) / 3);
+                            const deadline = start + confirmationTimeoutMs;
+                            // An expiring transaction can no longer be included after this point.
+                            const validUntil = transaction.validBefore === undefined
+                                ? Number.POSITIVE_INFINITY
+                                : transaction.validBefore * 1_000 + 2_000;
+                            let receipt;
+                            try {
+                                receipt = await withDeadline(sendRawTransactionSync(client, {
+                                    serializedTransaction: serializedTransaction_final,
+                                    timeout: sendTimeoutMs,
+                                }), start + sendTimeoutMs, new WaitForTransactionReceiptTimeoutError({ hash: finalHash }));
+                            }
+                            catch (broadcastError) {
+                                if (!isAmbiguousBroadcastError(broadcastError))
+                                    throw broadcastError;
+                                // The node may have accepted the transaction, so poll for its receipt.
+                                const timeout = Math.min(deadline, validUntil) - Date.now();
+                                let recovered;
+                                if (timeout > 0)
+                                    recovered = await waitForTransactionReceipt(client, {
+                                        checkReplacement: false,
+                                        hash: finalHash,
+                                        timeout,
+                                    }).catch(() => undefined);
+                                // When the validity cap ends polling, a transaction mined just before
+                                // `validBefore` may only now be visible, so look it up exactly once more.
+                                if (!recovered && validUntil < deadline)
+                                    recovered = await withDeadline(getTransactionReceipt(client, { hash: finalHash }), Math.max(deadline, Date.now() + client.pollingInterval), broadcastError).catch(() => undefined);
+                                if (!recovered)
+                                    throw broadcastError;
+                                receipt = recovered;
+                            }
                             if (reservation)
                                 await SponsorBudget.release(sponsorBudgetStore, reservation);
                             const matchedLogs = await assertTransferLogs(receipt, {
@@ -601,13 +663,27 @@ export function charge(parameters = {}) {
                         return toReceipt(reference, fundingCurrency);
                     }
                     catch (error) {
-                        if (!broadcastAttempted) {
-                            if (reservation)
-                                await SponsorBudget.release(sponsorBudgetStore, reservation);
-                            if (claimedFinalHash)
-                                await releaseHashUse(store, claimedFinalHash);
-                            await releaseHashUse(store, hash);
+                        if (reservation) {
+                            try {
+                                // A broadcast transaction may still land, so its fee stays reserved
+                                // until reconciliation observes a receipt or the reservation expires.
+                                if (broadcastAttempted)
+                                    await SponsorBudget.transition(sponsorBudgetStore, reservation, 'pending');
+                                else
+                                    await SponsorBudget.release(sponsorBudgetStore, reservation);
+                            }
+                            catch (budgetError) {
+                                // The reservation expires on its own; the settlement error and
+                                // claim cleanup take precedence.
+                                console.error('mppx: sponsor budget cleanup error', budgetError);
+                            }
                         }
+                        // Only a successful settlement consumes the credential. A signed
+                        // transaction can be mined at most once, so a retry re-broadcasts it
+                        // and recovers the receipt instead of being rejected as a replay.
+                        if (claimedFinalHash)
+                            await releaseHashUse(store, claimedFinalHash);
+                        await releaseHashUse(store, hash);
                         throw error;
                     }
                 }
@@ -932,6 +1008,57 @@ async function isActiveAccessKey(client, parameters) {
         return false;
     }
 }
+const ambiguousErrorNames = new Set([
+    'AbortError',
+    'SocketClosedError',
+    'TimeoutError',
+    'WaitForTransactionReceiptTimeoutError',
+]);
+/**
+ * Whether a failed synchronous broadcast may still have reached the mempool,
+ * so its receipt is worth polling for. Every other error is a definitive
+ * rejection (e.g. method not found, invalid params, insufficient funds).
+ *
+ * Ambiguous outcomes, matched anywhere in the `cause` chain:
+ * - Timeouts and aborts: errors named `TimeoutError` or `AbortError`, or the
+ *   local confirmation deadline (`WaitForTransactionReceiptTimeoutError`).
+ * - Lost connections: `SocketClosedError`, or an `HttpRequestError` with no
+ *   status (network failure) or a 5xx status.
+ * - JSON-RPC code `4`: the EIP-7966 timeout for a pooled, unconfirmed transaction.
+ * - Messages containing the words "already known" or "known transaction": already
+ *   pooled ("unknown transaction type" does not match).
+ */
+function isAmbiguousBroadcastError(error) {
+    for (let cause = error; cause; cause = cause.cause) {
+        if (typeof cause !== 'object')
+            return false;
+        const { code, message, name, status } = cause;
+        if (name === 'HttpRequestError')
+            return status === undefined || Number(status) >= 500;
+        if (ambiguousErrorNames.has(name))
+            return true;
+        if (code === 4)
+            return true;
+        if (typeof message === 'string' && /\balready ?known\b|\bknown transaction\b/i.test(message))
+            return true;
+    }
+    return false;
+}
+/** Rejects with `error` if `promise` has not settled by `deadline` (epoch ms). */
+async function withDeadline(promise, deadline, error) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(error), deadline - Date.now());
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** @internal */
 function toReceipt(reference, fundingCurrency) {
     return {
@@ -943,30 +1070,34 @@ function toReceipt(reference, fundingCurrency) {
     };
 }
 function assertChallengeBoundMemo(matchedLogs, parameters) {
-    assertChallengeBoundMemos(matchedLogs.map((log) => (log.kind === 'memo' ? log.args.memo : undefined)), parameters);
+    const memos = matchedLogs.map((log) => (log.kind === 'memo' ? log.args.memo : undefined));
+    // The transfer already settled to the recipient, so another payment would not help.
+    if (!isChallengeBound(memos, parameters))
+        throw new CredentialReplayedError({ reason: 'memo is not bound to this challenge' });
 }
 function assertChallengeBoundCallMemo(matchedCalls, parameters) {
-    assertChallengeBoundMemos(matchedCalls.map((call) => call.memo), parameters);
+    const memos = matchedCalls.map((call) => call.memo);
+    if (!isChallengeBound(memos, parameters))
+        throw new MismatchError('Payment verification failed: memo is not bound to this challenge.', {});
 }
 /**
- * Requires a challenge-bound attribution memo and rejects conflicting attribution
- * on matched payment transfers. Otherwise, a split payment could authorize another
+ * Whether matched payment transfers carry a challenge-bound attribution memo and
+ * no conflicting attribution. 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) {
+function isChallengeBound(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.', {});
+            return false;
         bound = true;
     }
-    if (!bound)
-        throw new MismatchError('Payment verification failed: memo is not bound to this challenge.', {});
+    return bound;
 }
 /** @internal */
 class MismatchError extends PaymentError {

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

@@ -2,6 +2,7 @@ import type { NoExtraKeys } from '../../internal/types.js';
 import * as Store from '../../Store.js';
 import * as Currencies from '../internal/currencies.js';
 import { charge as sessionCharge_, session as session_, settle as settle_, settleBatch as settleBatch_ } from '../session/server/Session.js';
+import * as Settlement from '../session/server/Settlement.js';
 import type { SessionController as SessionController_ } from '../session/server/Sse.js';
 import * as Ws_ from '../session/server/Ws.js';
 import { charge as charge_ } from './Charge.js';
@@ -2425,6 +2426,10 @@ export declare namespace tempo {
     const settle: typeof settle_;
     /** Batch-settle precompile-backed session channels. */
     const settleBatch: typeof settleBatch_;
+    /** Raised by `settle` when its transaction confirmed but the channel store could not record it. */
+    const SettlementCheckpointError: typeof Settlement.SettlementCheckpointError;
+    /** Raised by `settle` when its transaction confirmed but the channel store could not record it. */
+    type SettlementCheckpointError = Settlement.SettlementCheckpointError;
     /** Types for Tempo session streams. */
     namespace Sse {
         /** Controller passed to manual-charge SSE generators. */

package/dist/tempo/server/Methods.js

@@ -5,6 +5,7 @@ import { charge as sessionCharge_, session as session_, settle as settle_, settl
 import * as Settlement from '../session/server/Settlement.js';
 import * as Ws_ from '../session/server/Ws.js';
 import { charge as charge_ } from './Charge.js';
+import { fallbackStore } from './internal/fallback-store.js';
 import { renew as renewSubscription_, subscription as subscription_ } from './Subscription.js';
 const sessionServer = Object.assign(session_, {
     charge: sessionCharge_,
@@ -58,9 +59,10 @@ export function tempo(parameters) {
     }
     const { currencies: _currencies, ...shared } = parameters ?? {};
     const [first, ...rest] = Currencies.resolve(parameters ?? {});
+    const sponsorBudget = sharedSponsorBudget(parameters);
     const sessions = sessionOffers(parameters);
     function createMethods(currency, index) {
-        const configured = { ...shared, ...currency };
+        const configured = { ...shared, ...currency, sponsorBudget };
         return [createChargeMethod(configured), sessions[index]];
     }
     return [
@@ -87,6 +89,8 @@ export function tempo(parameters) {
     tempo.settle = settle_;
     /** Batch-settle precompile-backed session channels. */
     tempo.settleBatch = settleBatch_;
+    /** Raised by `settle` when its transaction confirmed but the channel store could not record it. */
+    tempo.SettlementCheckpointError = Settlement.SettlementCheckpointError;
     /** Experimental websocket helpers for Tempo sessions. */
     tempo.Ws = Ws_;
 })(tempo || (tempo = {}));
@@ -99,12 +103,22 @@ function resolveCurrencies(parameters) {
         ...(parameters.currency === undefined ? {} : { currencies: [parameters.currency] }),
     });
 }
+/** Shares sponsor exposure across sibling offers without changing replay-store policy. */
+function sharedSponsorBudget(parameters = {}) {
+    if (parameters.sponsorBudget === false)
+        return false;
+    return {
+        ...parameters.sponsorBudget,
+        store: parameters.sponsorBudget?.store ?? parameters.store ?? Store.memory(),
+    };
+}
 /** Creates OUSD-first charge offers, with explicit currency lists replacing the defaults. */
 function chargeOffers(parameters) {
     const { currencies: _currencies, ...shared } = parameters ?? {};
     const [first, ...rest] = resolveCurrencies(parameters ?? {});
+    const sponsorBudget = sharedSponsorBudget(parameters);
     function create(currency) {
-        const configured = { ...shared, ...currency };
+        const configured = { ...shared, ...currency, sponsorBudget };
         return charge_(configured);
     }
     return [create(first), ...rest.map(create)];
@@ -113,7 +127,7 @@ function chargeOffers(parameters) {
 function sessionOffers(parameters) {
     const { currencies: _currencies, ...shared } = parameters ?? {};
     const [first, ...rest] = resolveCurrencies(parameters ?? {});
-    const store = parameters?.store ?? Store.memory();
+    const store = parameters?.store ?? fallbackStore('tempo.session');
     const settlements = new Map();
     const key = (chainId, currency) => `${chainId}:${currency.toLowerCase()}`;
     const settleScheduled = (channel) => {
@@ -143,7 +157,7 @@ function sessionOffers(parameters) {
 function subscriptionOffers(parameters) {
     const { currencies: _currencies, ...shared } = parameters;
     const [first, ...rest] = resolveCurrencies(parameters);
-    const store = parameters.store ?? Store.memory();
+    const store = parameters.store ?? fallbackStore('tempo.subscription');
     function create(currency) {
         const configured = { ...shared, ...currency, store };
         return subscription_(configured);

package/dist/tempo/server/Subscription.js

@@ -18,6 +18,7 @@ import * as Methods from '../Methods.js';
 import { assertSubscriptionTiming, toSubscriptionPeriodSeconds, verifySubscriptionKeyAuthorization, } from '../subscription/KeyAuthorization.js';
 import * as SubscriptionReceipt from '../subscription/Receipt.js';
 import * as SubscriptionStore from '../subscription/Store.js';
+import { fallbackStore } from './internal/fallback-store.js';
 /**
  * Creates a Tempo subscription method for recurring TIP-20 token payments.
  *
@@ -25,7 +26,7 @@ import * as SubscriptionStore from '../subscription/Store.js';
  */
 export function subscription(p) {
     const parameters = p;
-    const rawStore = (parameters.store ?? Store.memory());
+    const rawStore = (parameters.store ?? fallbackStore('tempo.subscription'));
     if (typeof rawStore.update !== 'function') {
         throw new Error('tempo.subscription() requires an atomic store with `update`.');
     }

package/dist/tempo/server/internal/fallback-store.d.ts

@@ -0,0 +1,9 @@
+import * as Store from '../../../Store.js';
+/**
+ * Creates the in-memory store used when a Tempo server method is configured without `store`.
+ *
+ * Replay protection backed by this store only covers the current instance, so this warns once
+ * per `method` per process.
+ */
+export declare function fallbackStore(method: string): Store.AtomicStore;
+//# sourceMappingURL=fallback-store.d.ts.map

package/dist/tempo/server/internal/fallback-store.js

@@ -0,0 +1,13 @@
+import { warnOnce } from '../../../internal/warnOnce.js';
+import * as Store from '../../../Store.js';
+/**
+ * Creates the in-memory store used when a Tempo server method is configured without `store`.
+ *
+ * Replay protection backed by this store only covers the current instance, so this warns once
+ * per `method` per process.
+ */
+export function fallbackStore(method) {
+    warnOnce(`memory-store:${method}`, `${method}() has no \`store\` configured and is using an in-memory store. Replay protection and payment state are scoped to this instance, so a credential accepted by one replica, serverless isolate, or per-request \`Mppx\` instance can be accepted again by another. Pass a shared atomic store (e.g. \`Store.redis()\`, \`Store.upstash()\`, or \`Store.cloudflare()\` with \`update\`) when running more than one instance.`);
+    return Store.memory();
+}
+//# sourceMappingURL=fallback-store.js.map