mppx 0.8.13 → 0.8.14

package/src/tempo/server/Charge.ts

@@ -37,6 +37,8 @@ import * as Selectors from '../internal/selectors.js'
 import type * as types from '../internal/types.js'
 import * as Methods from '../Methods.js'
 import { html as htmlContent } from './internal/html.gen.js'
+import * as Relay from './Relay.js'
+import * as SponsorBudget from './SponsorBudget.js'
 
 /**
  * Creates a Tempo charge method intent for usage on the server.
@@ -53,7 +55,7 @@ export function charge<const parameters extends charge.Parameters>(
     parameters,
     charge.Parameters
   >,
-) {
+): Method.Server<typeof Methods.charge, charge.DeriveDefaults<parameters>> {
   const {
     amount,
     currency = defaults.resolveCurrency(parameters),
@@ -64,16 +66,30 @@ export function charge<const parameters extends charge.Parameters>(
     feePayerPolicy,
     html,
     memo,
+    relay,
     splits,
     supportedModes,
     validateSender,
     waitForConfirmation = true,
   } = parameters
   const storeKeyPrefix = parameters.storeKeyPrefix ?? ''
-  const store = Store.from(
-    (parameters.store ?? Store.memory()) as Store.AtomicStore<charge.StoreItemMap>,
-    { keyPrefix: storeKeyPrefix },
-  )
+  const rawStore = (parameters.store ?? Store.memory()) as Store.AtomicStore<charge.StoreItemMap>
+  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) as Store.AtomicStore<{
+    [key: `mppx:charge:sponsor-budget:${string}`]: SponsorBudget.State
+  }>
+  const {
+    maxInFlightReservations = 100,
+    maxInFlightTotalFee = (feePayerPolicy?.maxTotalFee ?? 50_000_000_000_000_000n) * 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 proofStore = parameters.store
     ? Store.from(parameters.store as Store.AtomicStore<charge.StoreItemMap>, {
         keyPrefix: storeKeyPrefix,
@@ -91,8 +107,259 @@ export function charge<const parameters extends charge.Parameters>(
     rpcUrl: defaults.rpcUrl,
   })
 
+  function resolveRequest(request: Method.VerifyContext<typeof Methods.charge>['request']) {
+    const parsed = Methods.charge.schema.request.safeParse(request)
+    if (parsed.success) return parsed.data
+    // Credential handlers receive the HMAC-bound request in canonical output
+    // form, so it must not be transformed a second time.
+    return request as unknown as z.output<typeof Methods.charge.schema.request>
+  }
+
+  async function resolveCredentialContext({
+    credential,
+    request,
+  }: {
+    credential: Method.VerifyContext<typeof Methods.charge>['credential']
+    request: Method.VerifyContext<typeof Methods.charge>['request']
+  }) {
+    const { challenge, payload } = credential
+    const resolvedRequest = resolveRequest(request)
+    const chainId = resolvedRequest.methodDetails?.chainId ?? request.chainId
+    const { amount, methodDetails } = resolvedRequest
+    const supportedModes = methodDetails?.supportedModes as
+      | readonly Methods.ChargeMode[]
+      | undefined
+    const currency = resolvedRequest.currency as `0x${string}`
+    const recipient = resolvedRequest.recipient as `0x${string}`
+    const memo = methodDetails?.memo as `0x${string}` | 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,
+      chainId,
+      challenge,
+      client: await getClient({ chainId }),
+      currency,
+      isZeroAmount,
+      memo,
+      methodDetails,
+      payload,
+      recipient,
+      requestAllowsFeePayer: request.feePayer !== false,
+      resolvedRequest,
+      supportedModes,
+    }
+  }
+
+  type CredentialContext = Awaited<ReturnType<typeof resolveCredentialContext>>
+  type Credential = Method.VerifyContext<typeof Methods.charge>['credential']
+  type HashPayload = Extract<Credential['payload'], { type: 'hash' }>
+  type ProofPayload = Extract<Credential['payload'], { type: 'proof' }>
+  type TransactionPayload = Extract<Credential['payload'], { type: 'transaction' }>
+
+  async function validateHashCredential(
+    credential: Credential,
+    payload: HashPayload,
+    context: CredentialContext,
+  ) {
+    const {
+      amount,
+      chainId,
+      challenge,
+      client,
+      currency,
+      memo,
+      methodDetails,
+      recipient,
+      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 receipt = await getTransactionReceipt(client, {
+      hash: payload.hash as `0x${string}`,
+    })
+    const sender = source?.address ?? receipt.from
+    const matchedLogs = await assertTransferLogs(receipt, {
+      currency,
+      sender,
+      source,
+      transfers,
+      validateSender,
+    })
+    if (!memo)
+      assertChallengeBoundMemo(matchedLogs, {
+        challengeId: challenge.id,
+        realm: challenge.realm,
+      })
+    return { receipt: toReceipt(receipt), sender, transfers }
+  }
+
+  async function validateProofCredential(
+    credential: Credential,
+    payload: ProofPayload,
+    context: CredentialContext,
+  ) {
+    const { chainId, challenge, client, isZeroAmount } = context
+    if (!isZeroAmount)
+      throw new MismatchError('Proof credentials are only valid for zero-amount challenges.', {})
+
+    const expectedSource = credential.source
+    if (!expectedSource) throw new MismatchError('Proof credential must include a source.', {})
+
+    const resolvedChainId = challenge.request.methodDetails?.chainId ?? chainId!
+    const source = Proof.parsePkhSource(expectedSource)
+    if (!source || source.chainId !== resolvedChainId)
+      throw new MismatchError('Proof credential source is invalid.', {})
+
+    const valid = await verifyTypedData(client, {
+      address: source.address,
+      ...Proof.typedData({
+        account: source.address,
+        chainId: resolvedChainId,
+        challengeId: challenge.id,
+        realm: challenge.realm,
+      }),
+      signature: payload.signature as `0x${string}`,
+    })
+    if (!valid) {
+      const proofSigner = recoverAuthorizedProofSigner({
+        chainId: resolvedChainId,
+        challengeId: challenge.id,
+        realm: challenge.realm,
+        signature: payload.signature as `0x${string}`,
+        sourceAddress: source.address,
+      })
+      const authorized = proofSigner
+        ? await isActiveAccessKey(client, { accessKey: proofSigner, account: source.address })
+        : false
+      if (!authorized) throw new MismatchError('Proof signature does not match source.', {})
+    }
+    return { sender: source.address }
+  }
+
+  async function validateTransactionCredential(
+    credential: Credential,
+    payload: TransactionPayload,
+    request: Method.VerifyContext<typeof Methods.charge>['request'],
+    context: CredentialContext,
+  ) {
+    const {
+      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 as Transaction.TransactionSerializedTempo
+    if (!FeePayer.isTempoTransaction(serializedTransaction))
+      throw new MismatchError('Only Tempo (0x76/0x78) transactions are supported.', {})
+
+    const transaction = Transaction.deserialize(serializedTransaction)
+    if (!transaction.signature || !transaction.from)
+      throw new MismatchError(
+        'Transaction must be signed by the sender before fee payer co-signing.',
+        {},
+      )
+
+    const isFeePayerTx =
+      methodDetails?.feePayer === true &&
+      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,
+    })
+    if (!memo)
+      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))
+    } else {
+      await viem_call(
+        client,
+        FeePayer.simulationTransaction(transaction, { feePayer: false }) as never,
+      )
+    }
+
+    return { isFeePayerTx, serializedTransaction, transaction, transfers }
+  }
+
+  async function validateCredential(
+    credential: Credential,
+    request: Method.VerifyContext<typeof Methods.charge>['request'],
+    context: CredentialContext,
+  ) {
+    switch (context.payload.type) {
+      case 'hash': {
+        const { receipt, sender, transfers } = await validateHashCredential(
+          credential,
+          context.payload,
+          context,
+        )
+        return {
+          details: { mode: 'push' as const, sender, transfers },
+          hash: context.payload.hash as `0x${string}`,
+          receipt,
+          type: 'hash' as const,
+        }
+      }
+
+      case 'proof': {
+        const { sender } = await validateProofCredential(credential, context.payload, context)
+        return { details: { mode: 'proof' as const, sender }, type: 'proof' as const }
+      }
+
+      case 'transaction': {
+        const { isFeePayerTx, serializedTransaction, transaction, transfers } =
+          await validateTransactionCredential(credential, context.payload, request, context)
+        return {
+          details: {
+            mode: 'pull' as const,
+            sender: transaction.from as `0x${string}`,
+            serializedTransaction,
+            transfers,
+          },
+          isFeePayerTx,
+          serializedTransaction,
+          transaction,
+          transfers,
+          type: 'transaction' as const,
+        }
+      }
+    }
+  }
+
   type Defaults = charge.DeriveDefaults<parameters>
-  return Method.toServer<typeof Methods.charge, Defaults>(Methods.charge, {
+  const method = Method.toServer<typeof Methods.charge, Defaults>(Methods.charge, {
     defaults: {
       amount,
       currency,
@@ -172,25 +439,35 @@ export function charge<const parameters extends charge.Parameters>(
       }
     },
 
-    async verify({ credential, request }) {
-      const { challenge } = credential
-      const resolvedRequest = (() => {
-        const parsed = Methods.charge.schema.request.safeParse(request)
-        if (parsed.success) return parsed.data
-        // verifyCredential() passes the HMAC-bound challenge request, which is
-        // already in canonical output form and should not be transformed again.
-        return request as unknown as z.output<typeof Methods.charge.schema.request>
-      })()
-      const chainId = resolvedRequest.methodDetails?.chainId ?? request.chainId
+    async validate({ credential, request }) {
+      const context = await resolveCredentialContext({ credential, request })
+      const validated = await validateCredential(credential, request, context)
 
-      const client = await getClient({ chainId })
+      return {
+        challenge: context.challenge,
+        credential,
+        details: validated.details,
+        intent: 'charge',
+        method: 'tempo',
+        request: context.resolvedRequest,
+        source: credential.source,
+      }
+    },
 
-      const { amount, methodDetails } = resolvedRequest
-      const requestAllowsFeePayer =
-        request.feePayer !== false &&
-        (request.feePayer === undefined ||
-          request.feePayer === true ||
-          typeof request.feePayer === 'object')
+    async broadcast({ credential, request }) {
+      const context = await resolveCredentialContext({ credential, request })
+      const {
+        amount,
+        chainId,
+        challenge,
+        client,
+        currency,
+        memo,
+        methodDetails,
+        recipient,
+        requestAllowsFeePayer,
+      } = context
+      const validated = await validateCredential(credential, request, context)
       const feePayerAccount =
         methodDetails?.feePayer === true && requestAllowsFeePayer
           ? typeof request.feePayer === 'object'
@@ -198,133 +475,23 @@ export function charge<const parameters extends charge.Parameters>(
             : feePayer
           : undefined
       const expires = challenge.expires
-      const supportedModes = methodDetails?.supportedModes as
-        | readonly Methods.ChargeMode[]
-        | undefined
-
-      const currency = resolvedRequest.currency as `0x${string}`
-      const recipient = resolvedRequest.recipient as `0x${string}`
-
-      Expires.assert(expires, challenge.id)
-
-      const memo = methodDetails?.memo as `0x${string}` | undefined
-
-      const payload = credential.payload
-      const isZeroAmount = BigInt(amount) === 0n
-
-      if (isZeroAmount && payload.type !== 'proof')
-        throw new MismatchError('Zero-amount challenges require a proof credential.', {})
 
-      switch (payload.type) {
+      switch (validated.type) {
         case 'hash': {
-          if (supportedModes && !supportedModes.includes('push'))
-            throw new MismatchError('Hash credentials are not supported for this challenge.', {})
-
-          const hash = payload.hash as `0x${string}`
-          // Validate client-supplied identity before reserving the hash so a
-          // malformed source cannot burn an otherwise valid payment attempt.
-          const source = parseHashCredentialSource({
-            chainId: chainId ?? client.chain?.id,
-            source: credential.source,
-          })
-          // Reserve the hash while we verify it. This blocks concurrent
-          // requests from racing to reuse the same on-chain payment.
+          const { hash, receipt } = validated
           if (!(await markHashUsed(store, hash))) {
-            throw new VerificationFailedError({ reason: 'Transaction hash has already been used' })
-          }
-
-          // If verification fails after reservation, release it so transient
-          // RPC/log-validation errors do not force the payer to pay again.
-          // Once we have proven the receipt is a successful matching payment,
-          // keep the marker to enforce single-use semantics.
-          let releaseReservation = true
-
-          try {
-            const expectedTransfers = getExpectedTransfers({
-              amount,
-              memo,
-              methodDetails,
-              recipient,
-            })
-            const receipt = await getTransactionReceipt(client, { hash })
-            const sender = source?.address ?? receipt.from
-            const matchedLogs = await assertTransferLogs(receipt, {
-              currency,
-              sender,
-              source,
-              transfers: expectedTransfers,
-              validateSender,
+            throw new VerificationFailedError({
+              reason: 'Transaction hash has already been used',
             })
-            // Only verify challenge binding when using auto-generated attribution memos.
-            // Explicit memos (set by the server) are strictly matched by assertTransferLogs
-            // but are NOT challenge-bound — callers that set explicit memos are responsible
-            // for ensuring memo uniqueness per challenge to prevent cross-challenge hash reuse.
-            if (!memo)
-              assertChallengeBoundMemo(matchedLogs, {
-                challengeId: challenge.id,
-                realm: challenge.realm,
-              })
-
-            const paymentReceipt = toReceipt(receipt)
-            // `toReceipt` can throw for reverted transactions. Only keep the
-            // reservation after it confirms the referenced transaction settled.
-            releaseReservation = false
-            return paymentReceipt
-          } catch (error) {
-            if (releaseReservation) await releaseHashUse(store, hash)
-            throw error
           }
+          return receipt
         }
 
         case 'proof': {
-          if (!isZeroAmount)
-            throw new MismatchError(
-              'Proof credentials are only valid for zero-amount challenges.',
-              {},
-            )
-
-          const expectedSource = credential.source
-          if (!expectedSource)
-            throw new MismatchError('Proof credential must include a source.', {})
-
-          const resolvedChainId = challenge.request.methodDetails?.chainId ?? chainId!
-          const source = Proof.parsePkhSource(expectedSource)
-
-          if (!source || source.chainId !== resolvedChainId) {
-            throw new MismatchError('Proof credential source is invalid.', {})
-          }
-
-          const valid = await verifyTypedData(client, {
-            // Bind verification to the claimed payer (`source.address`): the
-            // signer may be the payer itself or an access key authorized for it.
-            address: source.address,
-            ...Proof.typedData({
-              account: source.address,
-              chainId: resolvedChainId,
-              challengeId: challenge.id,
-              realm: challenge.realm,
-            }),
-            signature: payload.signature as `0x${string}`,
-          })
-          if (!valid) {
-            const proofSigner = recoverAuthorizedProofSigner({
-              chainId: resolvedChainId,
-              challengeId: challenge.id,
-              realm: challenge.realm,
-              signature: payload.signature as `0x${string}`,
-              sourceAddress: source.address,
-            })
-            const authorized = proofSigner
-              ? await isActiveAccessKey(client, {
-                  accessKey: proofSigner,
-                  account: source.address,
-                })
-              : false
-            if (!authorized) throw new MismatchError('Proof signature does not match source.', {})
-          }
-
           if (proofStore && !(await markProofUsed(proofStore, challenge.id))) {
-            throw new VerificationFailedError({ reason: 'Proof credential has already been used' })
+            throw new VerificationFailedError({
+              reason: 'Proof credential has already been used',
+            })
           }
 
           return {
@@ -336,82 +503,26 @@ export function charge<const parameters extends charge.Parameters>(
         }
 
         case 'transaction': {
-          if (supportedModes && !supportedModes.includes('pull'))
-            throw new MismatchError(
-              'Transaction credentials are not supported for this challenge.',
-              {},
-            )
-
-          const serializedTransaction = payload.signature as Transaction.TransactionSerializedTempo
+          const { isFeePayerTx, serializedTransaction, transaction, transfers } = validated
 
           // Pre-broadcast dedup: catch exact byte-for-byte replays early.
           const hash = keccak256(serializedTransaction)
           if (!(await markHashUsed(store, hash))) {
-            throw new VerificationFailedError({ reason: 'Transaction hash has already been used' })
+            throw new VerificationFailedError({
+              reason: 'Transaction hash has already been used',
+            })
           }
 
-          let releaseReservation = true
-          let sponsoredSenderReservation: { chainId: number; sender: `0x${string}` } | undefined
+          let broadcastAttempted = false
+          let finalHash: `0x${string}` | undefined
+          let reservation: SponsorBudget.Handle | undefined
 
           try {
-            if (!FeePayer.isTempoTransaction(serializedTransaction))
-              throw new MismatchError('Only Tempo (0x76/0x78) transactions are supported.', {})
-
-            const transaction = Transaction.deserialize(serializedTransaction)
-            if (!transaction.signature || !transaction.from)
-              throw new MismatchError(
-                'Transaction must be signed by the sender before fee payer co-signing.',
-                {},
-              )
-
-            const calls = (transaction.calls ?? []) as readonly {
-              data?: `0x${string}` | undefined
-              to?: `0x${string}` | undefined
-            }[]
-            const transfers = getExpectedTransfers({ amount, memo, methodDetails, recipient })
-            const isFeePayerTx =
-              methodDetails?.feePayer === true &&
-              requestAllowsFeePayer &&
-              !!(feePayerAccount || feePayerUrl)
-            const matchedCalls = assertTransferCalls(calls, {
-              currency,
-              exactCount: isFeePayerTx,
-              transfers,
-            })
-            if (!memo)
-              assertChallengeBoundCallMemo(matchedCalls, {
-                challengeId: challenge.id,
-                realm: challenge.realm,
-              })
-
-            if (isFeePayerTx) {
-              const reservationChainId = chainId ?? client.chain!.id
-              if (
-                !(await markSponsoredSenderInFlight(store, {
-                  chainId: reservationChainId,
-                  sender: transaction.from as `0x${string}`,
-                }))
-              ) {
-                throw new VerificationFailedError({
-                  reason: 'Sponsored transaction from this sender is already in flight',
-                })
-              }
-              sponsoredSenderReservation = {
-                chainId: reservationChainId,
-                sender: transaction.from as `0x${string}`,
-              }
-              FeePayer.validateCalls(
-                transaction.calls,
-                { amount, currency, recipient },
-                { currency, expectedTransfers: transfers },
-              )
-            }
-
             const allowedFeeTokens = FeePayer.defaultAllowedFeeTokens(chainId)
             if (isFeePayerTx) FeePayer.assertAllowedFeeToken(transaction, allowedFeeTokens)
             const selectableFeeTokens = allowedFeeTokens as readonly `0x${string}`[]
 
-            const serializedTransaction_final = await (async () => {
+            const completedTransaction = await (async () => {
               if (feePayerAccount && methodDetails?.feePayer !== false) {
                 const completed = await FeePayer.preflightSponsorship({
                   transaction,
@@ -432,7 +543,7 @@ export function charge<const parameters extends charge.Parameters>(
                       challengeExpires: expires,
                       chainId: chainId ?? client.chain!.id,
                       details: { amount, currency, recipient },
-                      policy: feePayerPolicy,
+                      policy: transactionFeePayerPolicy,
                       transaction: {
                         ...transaction,
                         ...(feeToken ? { feeToken } : {}),
@@ -441,7 +552,13 @@ export function charge<const parameters extends charge.Parameters>(
                     return { feePayer: feePayerAccount.address, transaction: sponsored }
                   },
                 })
-                return signTransaction(client, completed.transaction as never)
+                return {
+                  serializedTransaction: await signTransaction(
+                    client,
+                    completed.transaction as never,
+                  ),
+                  sponsor: completed.feePayer,
+                }
               }
               if (feePayerUrl && isFeePayerTx) {
                 const completed = await FeePayer.preflightSponsorship({
@@ -453,17 +570,66 @@ export function charge<const parameters extends charge.Parameters>(
                       challengeExpires: expires,
                       chainId: chainId ?? client.chain!.id,
                       details: { amount, currency, recipient },
-                      policy: feePayerPolicy,
+                      policy: transactionFeePayerPolicy,
                       transaction,
                       url: feePayerUrl,
                     })
                     return { ...hosted, transaction }
                   },
                 })
-                return completed.serializedTransaction
+                return {
+                  serializedTransaction: completed.serializedTransaction,
+                  sponsor: completed.feePayer,
+                }
               }
-              return serializedTransaction
+              return { serializedTransaction, sponsor: undefined }
             })()
+            const serializedTransaction_final = completedTransaction.serializedTransaction
+            finalHash = keccak256(serializedTransaction_final)
+
+            if (
+              finalHash.toLowerCase() !== hash.toLowerCase() &&
+              !(await markHashUsed(store, finalHash))
+            )
+              throw new VerificationFailedError({
+                reason: 'Transaction hash has already been used',
+              })
+
+            if (isFeePayerTx) {
+              const sponsor = completedTransaction.sponsor
+              if (!sponsor)
+                throw new VerificationFailedError({
+                  reason: 'Sponsored transaction has no configured fee payer',
+                })
+              const reservationChainId = chainId ?? client.chain!.id
+              const { totalFee, validBeforeValue } = FeePayer.assertTransactionPolicy({
+                challengeExpires: expires,
+                chainId: reservationChainId,
+                details: { amount, currency, recipient },
+                policy: transactionFeePayerPolicy,
+                transaction,
+              })
+              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,
+              })
+              Expires.assert(challenge.expires, challenge.id)
+            }
 
             // Pre-broadcast simulation for non-sponsored transactions.
             if (!isFeePayerTx)
@@ -472,10 +638,20 @@ export function charge<const parameters extends charge.Parameters>(
                 FeePayer.simulationTransaction(transaction, { feePayer: false }) as never,
               )
 
+            if (
+              reservation &&
+              !(await SponsorBudget.transition(sponsorBudgetStore, reservation, 'broadcasting'))
+            )
+              throw new VerificationFailedError({
+                reason: 'Sponsor budget reservation ownership was lost before broadcast',
+              })
+
+            broadcastAttempted = true
             if (waitForConfirmation) {
               const receipt = await sendRawTransactionSync(client, {
                 serializedTransaction: serializedTransaction_final,
               })
+              if (reservation) await SponsorBudget.release(sponsorBudgetStore, reservation)
               const matchedLogs = await assertTransferLogs(receipt, {
                 currency,
                 sender: transaction.from! as `0x${string}`,
@@ -486,19 +662,10 @@ export function charge<const parameters extends charge.Parameters>(
                   challengeId: challenge.id,
                   realm: challenge.realm,
                 })
-              // Post-broadcast dedup: catch malleable input variants
-              // (different serialized bytes, same underlying tx) that
-              // bypass the pre-broadcast check. Skip if the broadcast
-              // hash matches the input hash (already stored above).
-              if (
-                receipt.transactionHash.toLowerCase() !== hash.toLowerCase() &&
-                !(await markHashUsed(store, receipt.transactionHash))
-              ) {
+              if (receipt.transactionHash.toLowerCase() !== finalHash.toLowerCase())
                 throw new VerificationFailedError({
-                  reason: 'Transaction hash has already been used',
+                  reason: 'Broadcast transaction hash does not match the signed transaction',
                 })
-              }
-              releaseReservation = false
               return toReceipt(receipt)
             }
 
@@ -508,16 +675,17 @@ export function charge<const parameters extends charge.Parameters>(
             const reference = await sendRawTransaction(client, {
               serializedTransaction: serializedTransaction_final,
             })
-            // Post-broadcast dedup: same
+            if (reference.toLowerCase() !== finalHash.toLowerCase())
+              throw new VerificationFailedError({
+                reason: 'Broadcast transaction hash does not match the signed transaction',
+              })
             if (
-              reference.toLowerCase() !== hash.toLowerCase() &&
-              !(await markHashUsed(store, reference))
-            ) {
+              reservation &&
+              !(await SponsorBudget.transition(sponsorBudgetStore, reservation, 'pending'))
+            )
               throw new VerificationFailedError({
-                reason: 'Transaction hash has already been used',
+                reason: 'Sponsor budget reservation ownership was lost after broadcast',
               })
-            }
-            releaseReservation = false
             return {
               method: 'tempo',
               status: 'success',
@@ -525,28 +693,37 @@ export function charge<const parameters extends charge.Parameters>(
               reference,
             } as const
           } catch (error) {
-            if (releaseReservation) await releaseHashUse(store, hash)
+            if (!broadcastAttempted) {
+              if (reservation) await SponsorBudget.release(sponsorBudgetStore, reservation)
+              if (finalHash && finalHash.toLowerCase() !== hash.toLowerCase())
+                await releaseHashUse(store, finalHash)
+              await releaseHashUse(store, hash)
+            }
             throw error
-          } finally {
-            if (sponsoredSenderReservation)
-              await releaseSponsoredSenderInFlight(store, sponsoredSenderReservation)
           }
         }
-
-        default:
-          throw new Error(`Unsupported credential type "${(payload as { type: string }).type}".`)
       }
     },
   })
+  return relay ? (Relay.configure(method, relay) as typeof method) : method
 }
 
 export declare namespace charge {
-  type StoreItemMap = { [key: `mppx:charge:${string}`]: number }
+  type StoreItemMap = {
+    [key: `mppx:charge:${string}`]: number | SponsorBudget.State
+  }
 
   type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.charge>, 'feePayer' | 'recipient'>
 
   type ValidateSender = (parameters: ValidateSenderParameters) => boolean | Promise<boolean>
 
+  type ValidationDetails = {
+    mode: 'proof' | 'pull' | 'push'
+    sender?: `0x${string}` | undefined
+    serializedTransaction?: Transaction.TransactionSerializedTempo | undefined
+    transfers?: readonly ExpectedTransfer[] | undefined
+  }
+
   type ValidateSenderParameters = {
     /** Actual TIP-20 `Transfer.from` address. */
     sender: `0x${string}`
@@ -562,10 +739,13 @@ export declare namespace charge {
     /**
      * Override the fee-sponsor policy used when co-signing Tempo charge
      * transactions. Defaults resolve per chain, including a higher
-     * priority-fee ceiling on Moderato.
+     * 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` or `maxFeePerGas`, you may also need to raise
-     * `maxTotalFee` so the combined fee budget remains valid.
+     * If you increase `maxGas`, `maxFeePerGas`, or `maxTotalFee`, you may also
+     * need to raise `maxInFlightTotalFee`.
      */
     feePayerPolicy?: FeePayerPolicy | undefined
     /**
@@ -605,6 +785,8 @@ export declare namespace charge {
      * By default, no prefix is applied.
      */
     storeKeyPrefix?: string | undefined
+    /** Delegates Tempo charge credential validation and broadcast to Tempo API or a compatible MPP relay. */
+    relay?: RelayOptions | undefined
     /**
      * Whether to wait for the charge transaction to confirm on-chain before
      * responding. @default true
@@ -630,7 +812,19 @@ export declare namespace charge {
     }
   >
 
-  type FeePayerPolicy = Partial<FeePayer.Policy>
+  type FeePayerPolicy = Partial<FeePayer.Policy> & {
+    /** Maximum number of sponsored transactions awaiting a terminal receipt. @default 100 */
+    maxInFlightReservations?: number | undefined
+    /**
+     * Maximum aggregate declared fee exposure awaiting terminal receipts.
+     *
+     * @default `maxTotalFee * 10`
+     */
+    maxInFlightTotalFee?: bigint | undefined
+  }
+
+  /** Tempo API relay configuration for server-side charges. */
+  type RelayOptions = Relay.configure.Options
 }
 
 type ChargeRequest = z.output<typeof Methods.charge.schema.request>
@@ -971,14 +1165,6 @@ function getProofStoreKey(challengeId: string): `mppx:charge:${string}` {
   return `mppx:charge:proof:${challengeId}`
 }
 
-/** @internal */
-function getSponsoredSenderStoreKey(parameters: {
-  chainId: number
-  sender: `0x${string}`
-}): `mppx:charge:${string}` {
-  return `mppx:charge:sponsor:${parameters.chainId}:${parameters.sender.toLowerCase()}`
-}
-
 async function markHashUsed(
   store: Store.AtomicStore<charge.StoreItemMap>,
   hash: `0x${string}`,
@@ -1012,25 +1198,6 @@ function parseHashCredentialSource(parameters: {
   return parsed
 }
 
-/** @internal */
-async function markSponsoredSenderInFlight(
-  store: Store.AtomicStore<charge.StoreItemMap>,
-  parameters: { chainId: number; sender: `0x${string}` },
-): Promise<boolean> {
-  return store.update(getSponsoredSenderStoreKey(parameters), (current) => {
-    if (current !== null) return { op: 'noop', result: false }
-    return { op: 'set', value: Date.now(), result: true }
-  })
-}
-
-/** @internal */
-async function releaseSponsoredSenderInFlight(
-  store: Store.AtomicStore<charge.StoreItemMap>,
-  parameters: { chainId: number; sender: `0x${string}` },
-): Promise<void> {
-  await store.delete(getSponsoredSenderStoreKey(parameters))
-}
-
 /** @internal */
 async function markProofUsed(
   store: Store.AtomicStore<charge.StoreItemMap>,
@@ -1170,6 +1337,7 @@ class MismatchError extends PaymentError {
           : `Payment verification failed: ${reason}`,
         ...Object.entries(details).map(([k, v]) => `  - ${k}: ${v}`),
       ].join('\n'),
+      { details },
     )
   }
 }