mppx 0.8.15 → 0.8.18

package/src/tempo/server/Charge.ts

@@ -1,1351 +0,0 @@
-import * as SignatureEnvelope from 'ox/tempo/SignatureEnvelope'
-import {
-  decodeFunctionData,
-  formatUnits,
-  keccak256,
-  parseEventLogs,
-  type TransactionReceipt,
-} 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'
-
-import { PaymentError, VerificationFailedError } from '../../Errors.js'
-import * as Expires from '../../Expires.js'
-import type { LooseOmit, NoExtraKeys } from '../../internal/types.js'
-import * as Method from '../../Method.js'
-import type * as Html from '../../server/internal/html/config.ts'
-import * as Store from '../../Store.js'
-import * as Client from '../../viem/Client.js'
-import type * as z from '../../zod.js'
-import * as Attribution from '../Attribution.js'
-import * as Account from '../internal/account.js'
-import * as TempoAddress from '../internal/address.js'
-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 Proof from '../internal/proof.js'
-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.
- *
- * @example
- * ```ts
- * import { tempo } from 'mppx/server'
- *
- * const charge = tempo.charge()
- * ```
- */
-export function charge<const parameters extends charge.Parameters>(
-  parameters: NoExtraKeys<parameters, charge.Parameters> = {} as NoExtraKeys<
-    parameters,
-    charge.Parameters
-  >,
-): Method.Server<typeof Methods.charge, charge.DeriveDefaults<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 storeKeyPrefix = parameters.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,
-      })
-    : undefined
-
-  const { recipient, feePayer, feePayerUrl } = Account.resolve(parameters)
-  if (configuredFeeToken && feePayerUrl)
-    throw new Error('`feeToken` can only be configured for a local fee payer.')
-
-  const getClient = Client.getResolver({
-    chain: { ...tempo_chain, experimental_preconfirmationTime: 500 },
-    feePayerUrl,
-    getClient: parameters.getClient,
-    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>
-  const method = Method.toServer<typeof Methods.charge, Defaults>(Methods.charge, {
-    defaults: {
-      amount,
-      currency,
-      decimals,
-      description,
-      externalId,
-      memo,
-      recipient,
-      splits,
-      supportedModes,
-    } as unknown as Defaults,
-
-    stableBinding: chargeBinding,
-
-    html: html
-      ? {
-          config: {},
-          content: htmlContent,
-          formatAmount: async (request: z.output<typeof Methods.charge.schema.request>) => {
-            try {
-              const chainId = request.methodDetails?.chainId
-              if (chainId === undefined) throw new Error('no chainId')
-              const client = await getClient({ chainId })
-              const metadata = await Actions.token.getMetadata(client, {
-                token: request.currency as `0x${string}`,
-              })
-              const symbol =
-                new Intl.NumberFormat('en', {
-                  style: 'currency',
-                  currency: metadata.currency,
-                  currencyDisplay: 'narrowSymbol',
-                })
-                  .formatToParts(0)
-                  .find((p) => p.type === 'currency')?.value ?? metadata.currency
-              return `${symbol}${formatUnits(BigInt(request.amount), metadata.decimals)}`
-            } catch {
-              return `$${request.amount}`
-            }
-          },
-          text: typeof html === 'object' ? html.text : undefined,
-          theme: typeof html === 'object' ? html.theme : undefined,
-        }
-      : undefined,
-
-    // TODO: dedupe `{charge,session}.request`
-    async request({ credential, request }) {
-      const chainId = await (async () => {
-        if (request.chainId) return request.chainId
-        if (parameters.testnet) return defaults.chainId.testnet
-        return (await getClient({})).chain?.id
-      })()
-
-      const client = await (async () => {
-        try {
-          return await getClient({ chainId })
-        } catch {
-          throw new Error(`No client configured with chainId ${chainId}.`)
-        }
-      })()
-      if (client.chain?.id !== chainId)
-        throw new Error(`Client not configured with chainId ${chainId}.`)
-
-      const resolvedFeePayer = (() => {
-        if (request.feePayer === false) return credential ? false : undefined
-        const account = typeof request.feePayer === 'object' ? request.feePayer : feePayer
-        const requested = account ?? feePayer ?? feePayerUrl
-        if (credential) return account ?? (feePayerUrl ? true : undefined)
-        if (requested) return true
-        return undefined
-      })()
-
-      return {
-        ...request,
-        chainId,
-        feePayer: resolvedFeePayer,
-        memo: request.memo || undefined,
-      }
-    },
-
-    async validate({ credential, request }) {
-      const context = await resolveCredentialContext({ credential, request })
-      const validated = await validateCredential(credential, request, context)
-
-      return {
-        challenge: context.challenge,
-        credential,
-        details: validated.details,
-        intent: 'charge',
-        method: 'tempo',
-        request: context.resolvedRequest,
-        source: credential.source,
-      }
-    },
-
-    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'
-            ? request.feePayer
-            : feePayer
-          : undefined
-      const expires = challenge.expires
-
-      switch (validated.type) {
-        case 'hash': {
-          const { hash, receipt } = validated
-          if (!(await markHashUsed(store, hash))) {
-            throw new VerificationFailedError({
-              reason: 'Transaction hash has already been used',
-            })
-          }
-          return receipt
-        }
-
-        case 'proof': {
-          if (proofStore && !(await markProofUsed(proofStore, challenge.id))) {
-            throw new VerificationFailedError({
-              reason: 'Proof credential has already been used',
-            })
-          }
-
-          return {
-            method: 'tempo',
-            status: 'success',
-            timestamp: new Date().toISOString(),
-            reference: challenge.id,
-          } as const
-        }
-
-        case 'transaction': {
-          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',
-            })
-          }
-
-          let broadcastAttempted = false
-          let finalHash: `0x${string}` | undefined
-          let reservation: SponsorBudget.Handle | undefined
-
-          try {
-            const allowedFeeTokens = FeePayer.defaultAllowedFeeTokens(chainId)
-            if (isFeePayerTx) FeePayer.assertAllowedFeeToken(transaction, allowedFeeTokens)
-            const selectableFeeTokens = allowedFeeTokens as readonly `0x${string}`[]
-
-            const completedTransaction = await (async () => {
-              if (feePayerAccount && methodDetails?.feePayer !== false) {
-                const completed = await FeePayer.preflightSponsorship({
-                  transaction,
-                  simulate: (request) => viem_call(client, request as never),
-                  async complete() {
-                    const feeToken =
-                      configuredFeeToken ??
-                      (await resolveFeeToken({
-                        account: feePayerAccount.address,
-                        allowedTokens: selectableFeeTokens,
-                        candidateTokens: selectableFeeTokens,
-                        client,
-                        prioritizeCandidates: true,
-                      }))
-                    const sponsored = FeePayer.prepareSponsoredTransaction({
-                      account: feePayerAccount,
-                      allowedFeeTokens,
-                      challengeExpires: expires,
-                      chainId: chainId ?? client.chain!.id,
-                      details: { amount, currency, recipient },
-                      policy: transactionFeePayerPolicy,
-                      transaction: {
-                        ...transaction,
-                        ...(feeToken ? { feeToken } : {}),
-                      },
-                    })
-                    return { feePayer: feePayerAccount.address, transaction: sponsored }
-                  },
-                })
-                return {
-                  serializedTransaction: await signTransaction(
-                    client,
-                    completed.transaction as never,
-                  ),
-                  sponsor: completed.feePayer,
-                }
-              }
-              if (feePayerUrl && isFeePayerTx) {
-                const completed = await FeePayer.preflightSponsorship({
-                  transaction,
-                  simulate: (request) => viem_call(client, request as never),
-                  async complete() {
-                    const hosted = await FeePayer.fillHostedFeePayerTransaction({
-                      allowedFeeTokens,
-                      challengeExpires: expires,
-                      chainId: chainId ?? client.chain!.id,
-                      details: { amount, currency, recipient },
-                      policy: transactionFeePayerPolicy,
-                      transaction,
-                      url: feePayerUrl,
-                    })
-                    return { ...hosted, transaction }
-                  },
-                })
-                return {
-                  serializedTransaction: completed.serializedTransaction,
-                  sponsor: completed.feePayer,
-                }
-              }
-              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)
-              await viem_call(
-                client,
-                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}`,
-                transfers,
-              })
-              if (!memo)
-                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',
-                })
-              return toReceipt(receipt)
-            }
-
-            // 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, {
-              serializedTransaction: serializedTransaction_final,
-            })
-            if (reference.toLowerCase() !== finalHash.toLowerCase())
-              throw new VerificationFailedError({
-                reason: 'Broadcast transaction hash does not match the signed transaction',
-              })
-            if (
-              reservation &&
-              !(await SponsorBudget.transition(sponsorBudgetStore, reservation, 'pending'))
-            )
-              throw new VerificationFailedError({
-                reason: 'Sponsor budget reservation ownership was lost after broadcast',
-              })
-            return {
-              method: 'tempo',
-              status: 'success',
-              timestamp: new Date().toISOString(),
-              reference,
-            } as const
-          } catch (error) {
-            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
-          }
-        }
-      }
-    },
-  })
-  return relay ? (Relay.configure(method, relay) as typeof method) : method
-}
-
-export declare namespace charge {
-  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}`
-    /** Address that mppx would normally require as the sender. */
-    expectedSender: `0x${string}`
-    /** Parsed hash credential source when the credential includes one. */
-    source?: { address: `0x${string}`; chainId: number } | undefined
-  }
-
-  type Parameters = {
-    /** 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`.
-     */
-    feePayerPolicy?: FeePayerPolicy | undefined
-    /**
-     * Token a local fee payer uses to pay gas. If omitted, mppx selects a
-     * funded allowed token, preferring pathUSD.
-     *
-     * This option is not supported with a remote fee-payer URL, which selects
-     * its own token.
-     */
-    feeToken?: `0x${string}` | undefined
-    /** Testnet mode. */
-    testnet?: boolean | undefined
-    /**
-     * Store for charge replay protection.
-     *
-     * Non-zero charge flows default to an in-memory store if omitted. For
-     * zero-dollar proof auth, replay prevention is enabled only when a store
-     * is explicitly provided; otherwise proofs remain reusable until the
-     * challenge expires.
-     *
-     * Replay protection requires a {@link Store.AtomicStore} so replay markers
-     * can be written atomically.
-     *
-     * Use a shared store in multi-instance deployments so consumed hashes and
-     * proofs are visible across all server instances.
-     */
-    store?: Store.AtomicStore | undefined
-    /**
-     * Validates a TIP-20 transfer sender when it differs from the credential
-     * source. Core verification still validates amount, currency, recipient,
-     * memo binding, transaction success, and replay protection.
-     */
-    validateSender?: ValidateSender | undefined
-    /**
-     * Prefix prepended to charge replay-protection store keys.
-     *
-     * By default, no prefix is applied.
-     */
-    storeKeyPrefix?: string | undefined
-    /**
-     * Delegates Tempo charge credential validation and broadcast to Tempo API
-     * or a compatible MPP relay.
-     *
-     * The adapter delegates finalization to the relay for both modes. The
-     * relay broadcasts pull credentials, while it recognizes a push
-     * credential as already broadcast and returns its receipt without sending
-     * it again.
-     */
-    relay?: RelayOptions | undefined
-    /**
-     * Whether to wait for the charge transaction to confirm on-chain before
-     * responding. @default true
-     *
-     * When `false`, the transaction is simulated via `eth_estimateGas` and
-     * broadcast without waiting for inclusion. The receipt will optimistically
-     * report `status: 'success'` based on simulation alone — if the
-     * transaction reverts on-chain after broadcast (e.g. due to a state
-     * change between simulation and inclusion), the receipt will not reflect
-     * the failure.
-     */
-    waitForConfirmation?: boolean | undefined
-  } & Client.getResolver.Parameters &
-    Account.resolve.Parameters &
-    Defaults
-
-  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 */
-    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>
-
-function chargeBinding(request: ChargeRequest) {
-  // Exhaustively destructure so new charge request fields require an explicit binding decision.
-  const { amount, currency, description, externalId, methodDetails, recipient, ...requestRest } =
-    request
-  requestRest satisfies Record<string, never>
-
-  const { chainId, feePayer, memo, splits, supportedModes, ...methodDetailsRest } =
-    methodDetails ?? {}
-  methodDetailsRest satisfies Record<string, never>
-  void feePayer
-
-  return {
-    amount,
-    chainId,
-    currency,
-    description,
-    externalId,
-    memo,
-    recipient,
-    splits,
-    supportedModes,
-  }
-}
-
-type ExpectedTransfer = {
-  amount: string
-  allowAnyMemo?: boolean | undefined
-  memo?: `0x${string}` | undefined
-  recipient: `0x${string}`
-}
-
-function getExpectedTransfers(parameters: {
-  amount: string
-  memo: `0x${string}` | undefined
-  methodDetails: { splits?: readonly Charge_internal.Split[] | undefined } | undefined
-  recipient: `0x${string}`
-}): ExpectedTransfer[] {
-  return Charge_internal.getTransfers({
-    amount: parameters.amount,
-    methodDetails: {
-      memo: parameters.memo,
-      splits: parameters.methodDetails?.splits,
-    },
-    recipient: parameters.recipient,
-  }).map((transfer) => ({
-    ...transfer,
-    ...(!transfer.memo ? { allowAnyMemo: true } : {}),
-  })) as ExpectedTransfer[]
-}
-
-function assertTransferCalls(
-  calls: readonly { data?: `0x${string}` | undefined; to?: `0x${string}` | undefined }[],
-  parameters: {
-    currency: `0x${string}`
-    exactCount?: boolean | undefined
-    transfers: readonly ExpectedTransfer[]
-  },
-) {
-  const transferCalls = getTransferCalls(calls)
-
-  if (parameters.exactCount && transferCalls.length !== parameters.transfers.length)
-    throw new MismatchError('Invalid transaction: no matching payment call found', {
-      expectedCalls: String(parameters.transfers.length),
-      actualCalls: String(transferCalls.length),
-    })
-
-  // Match memo-specific transfers before wildcards to avoid greedy
-  // consumption of memo-bearing calls by allowAnyMemo entries.
-  const sorted = [...parameters.transfers].sort((a, b) => {
-    if (a.memo && !b.memo) return -1
-    if (!a.memo && b.memo) return 1
-    return 0
-  })
-
-  const used = new Set<number>()
-  const matched: Charge_internal.Transfer[] = []
-  for (const expected of sorted) {
-    const matchIndex = transferCalls.findIndex((call, index) => {
-      if (used.has(index)) return false
-      const decoded = decodeTransferCall(call, parameters.currency)
-      if (!decoded) return false
-
-      if (!TempoAddress.isEqual(decoded.recipient, expected.recipient)) return false
-      if (decoded.amount !== expected.amount) return false
-      if (expected.memo) {
-        return decoded.memo?.toLowerCase() === expected.memo.toLowerCase()
-      }
-      if (expected.allowAnyMemo) return true
-      return decoded.memo === undefined
-    })
-
-    if (matchIndex === -1) {
-      throw new MismatchError('Invalid transaction: no matching payment call found', {
-        amount: expected.amount,
-        currency: parameters.currency,
-        recipient: expected.recipient,
-      })
-    }
-
-    used.add(matchIndex)
-    matched.push(decodeTransferCall(transferCalls[matchIndex]!, parameters.currency)!)
-  }
-
-  return matched
-}
-
-function getTransferCalls(
-  calls: readonly { data?: `0x${string}` | undefined; to?: `0x${string}` | undefined }[],
-) {
-  const selectors = calls.map((call) => call.data?.slice(0, 10))
-  const offset =
-    selectors[0] === Selectors.approve && selectors[1] === Selectors.swapExactAmountOut ? 2 : 0
-  const transferCalls = calls.slice(offset)
-
-  if (
-    transferCalls.length === 0 ||
-    selectors
-      .slice(offset)
-      .some(
-        (selector) => selector !== Selectors.transfer && selector !== Selectors.transferWithMemo,
-      )
-  ) {
-    throw new MismatchError('Invalid transaction: no matching payment call found', {})
-  }
-
-  return transferCalls
-}
-
-function decodeTransferCall(
-  call: { data?: `0x${string}` | undefined; to?: `0x${string}` | undefined },
-  currency: `0x${string}`,
-) {
-  if (!call.to || !TempoAddress.isEqual(call.to, currency) || !call.data) return null
-
-  try {
-    const selector = call.data.slice(0, 10)
-    if (selector === Selectors.transfer) {
-      const { args } = decodeFunctionData({ abi: Abis.tip20, data: call.data })
-      const [recipient, amount] = args as [`0x${string}`, bigint]
-      return { amount: amount.toString(), recipient }
-    }
-
-    if (selector === Selectors.transferWithMemo) {
-      const { args } = decodeFunctionData({ abi: Abis.tip20, data: call.data })
-      const [recipient, amount, memo] = args as [`0x${string}`, bigint, `0x${string}`]
-      return { amount: amount.toString(), memo, recipient }
-    }
-  } catch {
-    return null
-  }
-
-  return null
-}
-
-type TransferLog =
-  | {
-      kind: 'transfer'
-      args: { from: `0x${string}`; to: `0x${string}`; amount: bigint }
-      address: `0x${string}`
-    }
-  | {
-      kind: 'memo'
-      args: { from: `0x${string}`; to: `0x${string}`; amount: bigint; memo: `0x${string}` }
-      address: `0x${string}`
-    }
-
-async function assertTransferLogs(
-  receipt: TransactionReceipt,
-  parameters: {
-    currency: `0x${string}`
-    sender: `0x${string}`
-    source?: { address: `0x${string}`; chainId: number } | undefined
-    transfers: readonly ExpectedTransfer[]
-    validateSender?: charge.ValidateSender | undefined
-  },
-): Promise<TransferLog[]> {
-  const logs = getTransferLogEffects(receipt)
-  const used = new Set<number>()
-  const matched: TransferLog[] = []
-
-  // Match memo-specific transfers before wildcards to avoid greedy
-  // consumption of memo-bearing logs by allowAnyMemo entries.
-  const sorted = [...parameters.transfers].sort((a, b) => {
-    if (a.memo && !b.memo) return -1
-    if (!a.memo && b.memo) return 1
-    return 0
-  })
-
-  for (const transfer of sorted) {
-    let matchIndex = -1
-    for (const [index, log] of logs.entries()) {
-      if (used.has(index)) continue
-      if (!TempoAddress.isEqual(log.address, parameters.currency)) continue
-      if (!TempoAddress.isEqual(log.args.to, transfer.recipient)) continue
-      if (log.args.amount.toString() !== transfer.amount) continue
-      const memoMatches = (() => {
-        if (transfer.memo)
-          return log.kind === 'memo' && log.args.memo.toLowerCase() === transfer.memo.toLowerCase()
-        if (transfer.allowAnyMemo) return log.kind === 'transfer' || log.kind === 'memo'
-        return log.kind === 'transfer'
-      })()
-      if (!memoMatches) continue
-      if (
-        !(await isValidTransferSender({
-          expectedSender: parameters.sender,
-          sender: log.args.from,
-          source: parameters.source,
-          validateSender: parameters.validateSender,
-        }))
-      )
-        continue
-      matchIndex = index
-      break
-    }
-
-    if (matchIndex === -1) {
-      throw new MismatchError('Payment verification failed: no matching transfer found.', {
-        amount: transfer.amount,
-        currency: parameters.currency,
-        recipient: transfer.recipient,
-      })
-    }
-
-    used.add(matchIndex)
-    matched.push(logs[matchIndex]! as TransferLog)
-  }
-
-  return matched
-}
-
-type ParsedTransferLog =
-  | {
-      kind: 'transfer'
-      args: { from: `0x${string}`; to: `0x${string}`; amount: bigint }
-      address: `0x${string}`
-      logIndex: number
-    }
-  | {
-      kind: 'memo'
-      args: { from: `0x${string}`; to: `0x${string}`; amount: bigint; memo: `0x${string}` }
-      address: `0x${string}`
-      logIndex: number
-    }
-
-function getTransferLogEffects(receipt: TransactionReceipt): TransferLog[] {
-  const transferLogs = parseEventLogs({
-    abi: Abis.tip20,
-    eventName: 'Transfer',
-    logs: receipt.logs,
-  }).map(
-    (log) =>
-      ({
-        address: log.address,
-        args: log.args,
-        kind: 'transfer',
-        logIndex: log.logIndex,
-      }) as ParsedTransferLog,
-  )
-
-  const memoLogs = parseEventLogs({
-    abi: Abis.tip20,
-    eventName: 'TransferWithMemo',
-    logs: receipt.logs,
-  }).map(
-    (log) =>
-      ({
-        address: log.address,
-        args: log.args,
-        kind: 'memo',
-        logIndex: log.logIndex,
-      }) as ParsedTransferLog,
-  )
-
-  const logs = [...transferLogs, ...memoLogs].sort((a, b) => a.logIndex - b.logIndex)
-  const effects: TransferLog[] = []
-
-  for (let index = 0; index < logs.length; index++) {
-    const log = logs[index]!
-    const next = logs[index + 1]
-    if (next && log.kind !== next.kind && isSameTransferLog(log, next)) {
-      const memoLog = log.kind === 'memo' ? log : next.kind === 'memo' ? next : undefined
-      if (!memoLog) continue
-      effects.push({
-        address: memoLog.address,
-        args: memoLog.args,
-        kind: 'memo',
-      })
-      index++
-      continue
-    }
-
-    effects.push({
-      address: log.address,
-      args: log.args,
-      kind: log.kind,
-    } as TransferLog)
-  }
-
-  return effects
-}
-
-function isSameTransferLog(a: ParsedTransferLog, b: ParsedTransferLog): boolean {
-  return (
-    TempoAddress.isEqual(a.address, b.address) &&
-    TempoAddress.isEqual(a.args.from, b.args.from) &&
-    TempoAddress.isEqual(a.args.to, b.args.to) &&
-    a.args.amount === b.args.amount &&
-    Math.abs(a.logIndex - b.logIndex) === 1
-  )
-}
-
-async function isValidTransferSender(parameters: {
-  expectedSender: `0x${string}`
-  sender: `0x${string}`
-  source?: { address: `0x${string}`; chainId: number } | undefined
-  validateSender?: charge.ValidateSender | undefined
-}): Promise<boolean> {
-  if (TempoAddress.isEqual(parameters.sender, parameters.expectedSender)) return true
-  if (!parameters.validateSender) return false
-  return parameters.validateSender({
-    expectedSender: parameters.expectedSender,
-    sender: parameters.sender,
-    source: parameters.source,
-  })
-}
-
-/** @internal */
-function getHashStoreKey(hash: `0x${string}`): `mppx:charge:${string}` {
-  return `mppx:charge:${hash.toLowerCase()}`
-}
-
-/** @internal */
-function getProofStoreKey(challengeId: string): `mppx:charge:${string}` {
-  return `mppx:charge:proof:${challengeId}`
-}
-
-async function markHashUsed(
-  store: Store.AtomicStore<charge.StoreItemMap>,
-  hash: `0x${string}`,
-): Promise<boolean> {
-  return store.update(getHashStoreKey(hash), (current) => {
-    if (current !== null) return { op: 'noop', result: false }
-    return { op: 'set', value: Date.now(), result: true }
-  })
-}
-
-/** @internal */
-async function releaseHashUse(
-  store: Store.AtomicStore<charge.StoreItemMap>,
-  hash: `0x${string}`,
-): Promise<void> {
-  await store.delete(getHashStoreKey(hash))
-}
-
-function parseHashCredentialSource(parameters: {
-  chainId: number | undefined
-  source: string | undefined
-}): { address: `0x${string}`; chainId: number } | undefined {
-  const { chainId, source } = parameters
-  if (!source) return undefined
-
-  const parsed = Proof.parsePkhSource(source)
-  if (!parsed || (chainId !== undefined && parsed.chainId !== chainId)) {
-    throw new MismatchError('Hash credential source is invalid.', {})
-  }
-
-  return parsed
-}
-
-/** @internal */
-async function markProofUsed(
-  store: Store.AtomicStore<charge.StoreItemMap>,
-  challengeId: string,
-): Promise<boolean> {
-  return store.update(getProofStoreKey(challengeId), (current) => {
-    if (current !== null) return { op: 'noop', result: false }
-    return { op: 'set', value: Date.now(), result: true }
-  })
-}
-
-function recoverAuthorizedProofSigner(parameters: {
-  chainId: number
-  challengeId: string
-  realm: string
-  signature: `0x${string}`
-  sourceAddress: `0x${string}`
-}): `0x${string}` | null {
-  const { chainId, challengeId, realm, signature, sourceAddress } = parameters
-
-  try {
-    const envelope = SignatureEnvelope.from(signature)
-    const proofHash = Proof.hash({ account: sourceAddress, chainId, challengeId, realm })
-
-    if (envelope.type === 'keychain') {
-      if (!TempoAddress.isEqual(envelope.userAddress, sourceAddress)) return null
-
-      const keychainPayload =
-        envelope.version === 'v2'
-          ? keccak256(`0x04${proofHash.slice(2)}${sourceAddress.slice(2)}` as `0x${string}`)
-          : proofHash
-
-      const signer = SignatureEnvelope.extractAddress({
-        payload: keychainPayload,
-        signature: envelope.inner,
-      })
-      const valid = SignatureEnvelope.verify(envelope.inner, {
-        address: signer,
-        payload: keychainPayload,
-      })
-      if (!valid) return null
-
-      return signer
-    }
-
-    const signer = SignatureEnvelope.extractAddress({
-      payload: proofHash,
-      signature: envelope,
-    })
-    const valid = SignatureEnvelope.verify(envelope, {
-      address: signer,
-      payload: proofHash,
-    })
-    if (!valid) return null
-
-    return signer
-  } catch {
-    return null
-  }
-}
-
-async function isActiveAccessKey(
-  client: Awaited<ReturnType<ReturnType<typeof Client.getResolver>>>,
-  parameters: { account: `0x${string}`; accessKey: `0x${string}` },
-): Promise<boolean> {
-  try {
-    const metadata = await Actions.accessKey.getMetadata(client, parameters)
-    const nowSeconds = BigInt(Math.floor(Date.now() / 1000))
-    return !metadata.isRevoked && metadata.expiry > nowSeconds
-  } catch {
-    return false
-  }
-}
-
-/** @internal */
-function toReceipt(receipt: TransactionReceipt) {
-  const { status, transactionHash } = receipt
-  if (status !== 'success') {
-    throw new Error(`Transaction reverted: ${transactionHash}`)
-  }
-  return {
-    method: 'tempo',
-    status: 'success',
-    timestamp: new Date().toISOString(),
-    reference: transactionHash,
-  } as const
-}
-
-/**
- * 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: readonly TransferLog[],
-  parameters: { challengeId: string; realm: string },
-) {
-  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.', {})
-}
-
-function assertChallengeBoundCallMemo(
-  matchedCalls: readonly Charge_internal.Transfer[],
-  parameters: { challengeId: string; realm: string },
-) {
-  const bound = matchedCalls.some((call) => {
-    if (!call.memo) return false
-    const memo = call.memo as `0x${string}`
-    if (!Attribution.verifyServer(memo, parameters.realm)) return false
-    return Attribution.verifyChallengeBinding(memo, parameters.challengeId)
-  })
-
-  if (!bound)
-    throw new MismatchError('Payment verification failed: memo is not bound to this challenge.', {})
-}
-
-/** @internal */
-class MismatchError extends PaymentError {
-  override readonly name = 'MismatchError'
-  readonly title = 'Verification Failed'
-  readonly type = 'https://paymentauth.org/problems/verification-failed'
-
-  constructor(reason: string, details: Record<string, string>) {
-    super(
-      [
-        reason.startsWith('Payment verification failed')
-          ? reason
-          : `Payment verification failed: ${reason}`,
-        ...Object.entries(details).map(([k, v]) => `  - ${k}: ${v}`),
-      ].join('\n'),
-      { details },
-    )
-  }
-}