mppx 0.8.14 → 0.8.17

package/src/tempo/internal/address.test.ts

@@ -0,0 +1,42 @@
+import { TempoAddress } from 'ox/tempo'
+import { describe, expect, test } from 'vp/test'
+
+import { isEqual } from './address.js'
+
+const address = '0x742d35Cc6634C0532925a3b844Bc9e7595F2bD28'
+const otherAddress = '0x52908400098527886E0F7030069857D2E4169EE7'
+
+describe('isEqual', () => {
+  const representations = [
+    { name: 'mixed-case hex', value: address },
+    { name: 'lowercase hex', value: address.toLowerCase() as `0x${string}` },
+    { name: 'Tempo-formatted', value: TempoAddress.format(address) },
+  ] as const
+
+  const otherRepresentations = [
+    { name: 'mixed-case hex', value: otherAddress },
+    { name: 'lowercase hex', value: otherAddress.toLowerCase() as `0x${string}` },
+    { name: 'Tempo-formatted', value: TempoAddress.format(otherAddress) },
+  ] as const
+
+  test.each([
+    ...representations.flatMap((a) =>
+      representations.map((b) => ({
+        a: a.value,
+        b: b.value,
+        expected: true,
+        name: `${a.name} and ${b.name} representations of the same address`,
+      })),
+    ),
+    ...representations.flatMap((a) =>
+      otherRepresentations.map((b) => ({
+        a: a.value,
+        b: b.value,
+        expected: false,
+        name: `${a.name} and ${b.name} representations of different addresses`,
+      })),
+    ),
+  ])('$name', ({ a, b, expected }) => {
+    expect(isEqual(a, b)).toBe(expected)
+  })
+})

package/src/tempo/internal/address.ts

@@ -1,6 +1,6 @@
-// TODO: Add `isEqual` to `TempoAddress`.
-import type { TempoAddress } from 'ox/tempo'
+import { TempoAddress } from 'ox/tempo'
 
+/** Returns whether two hex or Tempo-formatted addresses resolve to the same address. */
 export function isEqual(a: TempoAddress.Address, b: TempoAddress.Address) {
-  return a.toLowerCase() === b.toLowerCase()
+  return TempoAddress.resolve(a).toLowerCase() === TempoAddress.resolve(b).toLowerCase()
 }

package/src/tempo/internal/auto-swap.test.ts

@@ -103,7 +103,7 @@ describe('resolve', () => {
 })
 
 describe('findCalls', () => {
-  test('passes the client to viem 2.54 Tempo token call builders', async () => {
+  test('uses current viem Tempo call builder signatures', async () => {
     vi.resetModules()
     const account = '0x1111111111111111111111111111111111111111' as Address
     const tokenOut = '0x2222222222222222222222222222222222222222' as Address
@@ -122,8 +122,8 @@ describe('findCalls', () => {
       return { kind: 'approve' }
     }
 
-    function buyCall(client: unknown, parameters: Record<string, unknown>) {
-      builderCalls.push({ client, name: 'buy', parameters })
+    function buyCall(parameters: Record<string, unknown>) {
+      builderCalls.push({ client: undefined, name: 'buy', parameters })
       return { kind: 'buy' }
     }
 
@@ -158,7 +158,7 @@ describe('findCalls', () => {
       })
 
       expect(calls).toHaveLength(2)
-      expect(builderCalls.map((call) => call.client)).toEqual([client, client, client, client])
+      expect(builderCalls.map((call) => call.client)).toEqual([client, client, client, undefined])
       expect(builderCalls.map((call) => call.name)).toEqual([
         'getBalance',
         'getBalance',

package/src/tempo/internal/auto-swap.ts

@@ -1,7 +1,6 @@
 import type { Address, Client } from 'viem'
 import { readContract } from 'viem/actions'
 import { Actions, Addresses } from 'viem/tempo'
-import type { dex as viem_dex, token as viem_token } from 'viem/tempo/actions'
 
 import * as TempoAddress from './address.js'
 import * as defaults from './defaults.js'
@@ -15,51 +14,6 @@ export const defaultCurrencies: readonly Address[] = [
   defaults.tokens.usdc as Address,
 ]
 
-// TODO: Remove once the minimum viem version is >=2.54.0, which uses client-first Tempo call builders.
-function getBalanceCall(
-  client: Client,
-  parameters: viem_token.getBalance.Args,
-): ReturnType<typeof viem_token.getBalance.call> {
-  const call = Actions.token.getBalance.call as unknown as {
-    length: number
-    (parameters: viem_token.getBalance.Args): ReturnType<typeof viem_token.getBalance.call>
-    (
-      client: Client,
-      parameters: viem_token.getBalance.Args,
-    ): ReturnType<typeof viem_token.getBalance.call>
-  }
-  return call.length >= 2 ? call(client, parameters) : call(parameters)
-}
-
-// TODO: Remove once the minimum viem version is >=2.54.0, which uses client-first Tempo call builders.
-function getApproveCall(
-  client: Client,
-  parameters: viem_token.approve.Args,
-): ReturnType<typeof viem_token.approve.call> {
-  const call = Actions.token.approve.call as unknown as {
-    length: number
-    (parameters: viem_token.approve.Args): ReturnType<typeof viem_token.approve.call>
-    (
-      client: Client,
-      parameters: viem_token.approve.Args,
-    ): ReturnType<typeof viem_token.approve.call>
-  }
-  return call.length >= 2 ? call(client, parameters) : call(parameters)
-}
-
-// TODO: Remove once the minimum viem version is >=2.54.0, which uses client-first Tempo call builders.
-function getBuyCall(
-  client: Client,
-  parameters: viem_dex.buy.Args,
-): ReturnType<typeof viem_dex.buy.call> {
-  const call = Actions.dex.buy.call as unknown as {
-    length: number
-    (parameters: viem_dex.buy.Args): ReturnType<typeof viem_dex.buy.call>
-    (client: Client, parameters: viem_dex.buy.Args): ReturnType<typeof viem_dex.buy.call>
-  }
-  return call.length >= 2 ? call(client, parameters) : call(parameters)
-}
-
 /**
  * Finds the optimal swap calls to acquire `amountOut` of `tokenOut`,
  * returning an approve + buy call sequence if a viable route is found.
@@ -76,9 +30,12 @@ export async function findCalls(
   const candidates = tokenIn.filter((t) => !TempoAddress.isEqual(t, tokenOut))
 
   const balanceResults = await Promise.allSettled([
-    readContract(client, getBalanceCall(client, { account, token: tokenOut }) as never),
+    readContract(
+      client,
+      Actions.token.getBalance.call(client, { account, token: tokenOut }) as never,
+    ),
     ...candidates.map((t) =>
-      readContract(client, getBalanceCall(client, { account, token: t }) as never),
+      readContract(client, Actions.token.getBalance.call(client, { account, token: t }) as never),
     ),
   ])
 
@@ -108,12 +65,12 @@ export async function findCalls(
         const maxAmountIn =
           quotedAmountIn + (quotedAmountIn * BigInt(Math.round(slippage * 100))) / bps
         return [
-          getApproveCall(client, {
+          Actions.token.approve.call(client, {
             amount: maxAmountIn,
             spender: Addresses.stablecoinDex,
             token: tokenIn,
           }),
-          getBuyCall(client, {
+          Actions.dex.buy.call({
             tokenIn,
             tokenOut,
             amountOut,

package/src/tempo/legacy/README.md

@@ -1,9 +1,9 @@
 # Tempo Legacy Session
 
-This directory contains the legacy smart-contract-backed `tempo/session`
-implementation.
+This directory contains the retained client for the legacy smart-contract-backed
+`tempo/session` implementation.
 
 The default `tempo.session` implementation is TIP-1034 precompile-backed and
-lives under `src/tempo/session/precompile`. Legacy code may import shared transport and
-accounting helpers from `src/tempo/session`, but legacy chain, channel, voucher,
-client, and server implementations should stay inside this directory.
+lives under `src/tempo/session/precompile`. The legacy server implementation has
+been removed, while legacy chain, channel, voucher, and client code remains here
+for clients migrating existing sessions.

package/src/tempo/legacy/index.ts

@@ -1,6 +1,4 @@
 /** Legacy contract-backed session client surface. */
 export * as Client from './client/index.js'
-/** Legacy contract-backed session server surface. */
-export * as Server from './server/index.js'
-/** Legacy contract-backed session channel primitives. */
+/** Legacy contract-backed session channel primitives used by the client. */
 export * as Session from './session/index.js'

package/src/tempo/server/AtomicStore.test-d.ts

@@ -19,6 +19,19 @@ test('tempo.charge store parameter requires AtomicStore', () => {
   tempo.charge({ store: Store.memory() })
 })
 
+test('tempo.charge sponsor budget store requires AtomicStore', () => {
+  const nonAtomic = Store.from({
+    get: async () => null,
+    put: async () => {},
+    delete: async () => {},
+  })
+
+  tempo.charge({ sponsorBudget: false })
+  // @ts-expect-error — sponsor budget coordination requires AtomicStore
+  tempo.charge({ sponsorBudget: { store: nonAtomic } })
+  tempo.charge({ sponsorBudget: { store: Store.memory() } })
+})
+
 test('tempo.session store parameter requires AtomicStore', () => {
   type SessionParameters = NonNullable<Parameters<typeof tempo.session>[0]>
   expectTypeOf<SessionParameters['store']>().toEqualTypeOf<Store.AtomicStore | undefined>()

package/src/tempo/server/Charge.test.ts

@@ -16,12 +16,6 @@ import { Abis, Account, Actions, Addresses, Secp256k1, Tick, Transaction } from
 import type { token as viem_token } from 'viem/tempo/actions'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as Http from '~test/Http.js'
-import {
-  closeChannelOnChain,
-  deployEscrow,
-  openChannel,
-  signVoucher,
-} from '~test/tempo/legacy/session.js'
 import { accounts, asset, chain, client, fundAccount, http } from '~test/tempo/viem.js'
 
 import * as Store from '../../Store.js'
@@ -58,18 +52,8 @@ function sponsoredFeeExposure(credential: string) {
   return transaction.gas * transaction.maxFeePerGas
 }
 
-// TODO: Remove once the minimum viem version is >=2.54.0, which uses client-first Tempo call builders.
 function tokenTransferCall(parameters: viem_token.transfer.Args) {
-  const call = Actions.token.transfer.call as unknown as {
-    length: number
-    (parameters: viem_token.transfer.Args): ReturnType<typeof viem_token.transfer.call>
-    (
-      client: unknown,
-      parameters: viem_token.transfer.Args,
-    ): ReturnType<typeof viem_token.transfer.call>
-  }
-  if (call.length >= 2) return call(client, parameters)
-  return call(parameters)
+  return Actions.token.transfer.call(client, parameters)
 }
 
 type ProofAccessKeyContext = {
@@ -92,6 +76,21 @@ const server = Mppx_server.create({
 })
 
 describe('tempo', () => {
+  describe('sponsor budget configuration', () => {
+    test('validates structured limits', () => {
+      expect(() => tempo_server.charge({ sponsorBudget: { maxInFlightReservations: 0 } })).toThrow(
+        '`sponsorBudget.maxInFlightReservations` must be a positive safe integer.',
+      )
+      expect(() => tempo_server.charge({ sponsorBudget: { maxInFlightTotalFee: 0n } })).toThrow(
+        '`sponsorBudget.maxInFlightTotalFee` must be greater than zero.',
+      )
+    })
+
+    test('allows aggregate exposure to be enforced externally', () => {
+      expect(() => tempo_server.charge({ sponsorBudget: false })).not.toThrow()
+    })
+  })
+
   describe('intent: charge; type: hash', () => {
     test('default', async () => {
       const mppx = Mppx_client.create({
@@ -581,72 +580,6 @@ describe('tempo', () => {
       httpServer.close()
     })
 
-    test('behavior: rejects session settlement tx hash used as charge credential', async () => {
-      const chargeAmount = parseUnits('1', 6)
-      const recipient = accounts[0].address
-      const external = accounts[3]
-
-      const escrow = await deployEscrow()
-
-      await fundAccount({ address: external.address, token: Addresses.pathUsd })
-      await fundAccount({ address: external.address, token: asset })
-
-      const salt = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex.Hex
-      const { channelId } = await openChannel({
-        escrow,
-        payer: external,
-        payee: recipient,
-        token: asset,
-        deposit: chargeAmount,
-        salt,
-      })
-
-      const voucherSig = await signVoucher(
-        client,
-        external,
-        { channelId, cumulativeAmount: chargeAmount },
-        escrow,
-        chain.id,
-      )
-
-      const { txHash: settleTxHash } = await closeChannelOnChain({
-        escrow,
-        payee: accounts[0],
-        channelId,
-        cumulativeAmount: chargeAmount,
-        signature: voucherSig,
-      })
-
-      const httpServer = await Http.createServer(async (req, res) => {
-        const result = await Mppx_server.toNodeListener(server.charge({ amount: '1' }))(req, res)
-        if (result.status === 402) return
-        res.end('OK')
-      })
-
-      const response = await fetch(httpServer.url)
-      expect(response.status).toBe(402)
-
-      const challenge = Challenge.fromResponse(response, {
-        methods: [tempo_client.charge()],
-      })
-
-      const credential = Credential.from({
-        challenge,
-        payload: { hash: settleTxHash, type: 'hash' as const },
-      })
-
-      {
-        const response = await fetch(httpServer.url, {
-          headers: { Authorization: Credential.serialize(credential) },
-        })
-        expect(response.status).toBe(402)
-        const body = (await response.json()) as { detail: string }
-        expect(body.detail).toContain('Payment verification failed: no matching transfer found.')
-      }
-
-      httpServer.close()
-    })
-
     test('behavior: rejects replayed transaction hash', async () => {
       const dedupServer = Mppx_server.create({
         methods: [
@@ -1976,6 +1909,7 @@ describe('tempo', () => {
         }),
       })
 
+      const replayStore = Store.memory()
       const sponsoredStore = Store.memory()
       const serverWithSlowSimulation = Mppx_server.create({
         methods: [
@@ -1985,7 +1919,8 @@ describe('tempo', () => {
             },
             currency: asset,
             account: accounts[0],
-            store: sponsoredStore,
+            sponsorBudget: { store: sponsoredStore },
+            store: replayStore,
             storeKeyPrefix: 'tenant:',
           }),
         ],

package/src/tempo/server/Charge.ts

@@ -67,6 +67,7 @@ export function charge<const parameters extends charge.Parameters>(
     html,
     memo,
     relay,
+    sponsorBudget,
     splits,
     supportedModes,
     validateSender,
@@ -75,21 +76,31 @@ export function charge<const parameters extends charge.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,
+    maxInFlightReservations: legacyMaxInFlightReservations,
+    maxInFlightTotalFee: legacyMaxInFlightTotalFee,
     ...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 sponsorBudgetConfig = sponsorBudget === false ? undefined : (sponsorBudget ?? {})
+  const maxInFlightReservations =
+    sponsorBudgetConfig?.maxInFlightReservations ?? legacyMaxInFlightReservations ?? 100
+  const maxInFlightTotalFee =
+    sponsorBudgetConfig?.maxInFlightTotalFee ??
+    legacyMaxInFlightTotalFee ??
+    (feePayerPolicy?.maxTotalFee ?? 50_000_000_000_000_000n) * 10n
+  if (sponsorBudgetConfig) {
+    if (!Number.isSafeInteger(maxInFlightReservations) || maxInFlightReservations <= 0)
+      throw new Error('`sponsorBudget.maxInFlightReservations` must be a positive safe integer.')
+    if (maxInFlightTotalFee <= 0n)
+      throw new Error('`sponsorBudget.maxInFlightTotalFee` must be greater than zero.')
+  }
+  // Aggregate exposure belongs to the actual sponsor, not a caller-specific replay namespace.
+  // Keep it unprefixed and shared across every tenant/process using the sponsor.
+  const sponsorBudgetStore = sponsorBudgetConfig
+    ? (Store.from(sponsorBudgetConfig.store ?? rawStore) as Store.AtomicStore<{
+        [key: `mppx:charge:sponsor-budget:${string}`]: SponsorBudget.State
+      }>)
+    : undefined
   const proofStore = parameters.store
     ? Store.from(parameters.store as Store.AtomicStore<charge.StoreItemMap>, {
         keyPrefix: storeKeyPrefix,
@@ -360,6 +371,8 @@ export function charge<const parameters extends charge.Parameters>(
 
   type Defaults = charge.DeriveDefaults<parameters>
   const method = Method.toServer<typeof Methods.charge, Defaults>(Methods.charge, {
+    canOffer: parameters.canOffer,
+    onPaymentSuccess: parameters.onPaymentSuccess,
     defaults: {
       amount,
       currency,
@@ -475,11 +488,13 @@ export function charge<const parameters extends charge.Parameters>(
             : feePayer
           : undefined
       const expires = challenge.expires
+      Expires.assert(expires, challenge.id)
+      const replayExpires = Date.parse(expires)
 
       switch (validated.type) {
         case 'hash': {
           const { hash, receipt } = validated
-          if (!(await markHashUsed(store, hash))) {
+          if (!(await tryClaimHash(store, hash, replayExpires))) {
             throw new VerificationFailedError({
               reason: 'Transaction hash has already been used',
             })
@@ -488,7 +503,7 @@ export function charge<const parameters extends charge.Parameters>(
         }
 
         case 'proof': {
-          if (proofStore && !(await markProofUsed(proofStore, challenge.id))) {
+          if (proofStore && !(await tryClaimProof(proofStore, challenge.id, replayExpires))) {
             throw new VerificationFailedError({
               reason: 'Proof credential has already been used',
             })
@@ -507,7 +522,7 @@ export function charge<const parameters extends charge.Parameters>(
 
           // Pre-broadcast dedup: catch exact byte-for-byte replays early.
           const hash = keccak256(serializedTransaction)
-          if (!(await markHashUsed(store, hash))) {
+          if (!(await tryClaimHash(store, hash, replayExpires))) {
             throw new VerificationFailedError({
               reason: 'Transaction hash has already been used',
             })
@@ -589,7 +604,7 @@ export function charge<const parameters extends charge.Parameters>(
 
             if (
               finalHash.toLowerCase() !== hash.toLowerCase() &&
-              !(await markHashUsed(store, finalHash))
+              !(await tryClaimHash(store, finalHash, replayExpires))
             )
               throw new VerificationFailedError({
                 reason: 'Transaction hash has already been used',
@@ -614,20 +629,21 @@ export function charge<const parameters extends charge.Parameters>(
                 expiresAt,
                 expires ? Date.parse(expires) : Number.MAX_SAFE_INTEGER,
               )
-              reservation = await SponsorBudget.reserve(sponsorBudgetStore, {
-                chainId: reservationChainId,
-                expiresAt,
-                fee: totalFee,
-                getReceipt: (transactionHash) =>
-                  getTransactionReceipt(client, { hash: transactionHash }),
-                id: finalHash.toLowerCase(),
-                maxReservations: maxInFlightReservations,
-                maxTotalFee: maxInFlightTotalFee,
-                owner: globalThis.crypto.randomUUID(),
-                sponsor,
-                transactionHash: finalHash,
-                waitUntil,
-              })
+              if (sponsorBudgetStore)
+                reservation = await SponsorBudget.reserve(sponsorBudgetStore, {
+                  chainId: reservationChainId,
+                  expiresAt,
+                  fee: totalFee,
+                  getReceipt: (transactionHash) =>
+                    getTransactionReceipt(client, { hash: transactionHash }),
+                  id: finalHash.toLowerCase(),
+                  maxReservations: maxInFlightReservations,
+                  maxTotalFee: maxInFlightTotalFee,
+                  owner: globalThis.crypto.randomUUID(),
+                  sponsor,
+                  transactionHash: finalHash,
+                  waitUntil,
+                })
               Expires.assert(challenge.expires, challenge.id)
             }
 
@@ -640,7 +656,7 @@ export function charge<const parameters extends charge.Parameters>(
 
             if (
               reservation &&
-              !(await SponsorBudget.transition(sponsorBudgetStore, reservation, 'broadcasting'))
+              !(await SponsorBudget.transition(sponsorBudgetStore!, reservation, 'broadcasting'))
             )
               throw new VerificationFailedError({
                 reason: 'Sponsor budget reservation ownership was lost before broadcast',
@@ -651,7 +667,7 @@ export function charge<const parameters extends charge.Parameters>(
               const receipt = await sendRawTransactionSync(client, {
                 serializedTransaction: serializedTransaction_final,
               })
-              if (reservation) await SponsorBudget.release(sponsorBudgetStore, reservation)
+              if (reservation) await SponsorBudget.release(sponsorBudgetStore!, reservation)
               const matchedLogs = await assertTransferLogs(receipt, {
                 currency,
                 sender: transaction.from! as `0x${string}`,
@@ -681,7 +697,7 @@ export function charge<const parameters extends charge.Parameters>(
               })
             if (
               reservation &&
-              !(await SponsorBudget.transition(sponsorBudgetStore, reservation, 'pending'))
+              !(await SponsorBudget.transition(sponsorBudgetStore!, reservation, 'pending'))
             )
               throw new VerificationFailedError({
                 reason: 'Sponsor budget reservation ownership was lost after broadcast',
@@ -694,7 +710,7 @@ export function charge<const parameters extends charge.Parameters>(
             } as const
           } catch (error) {
             if (!broadcastAttempted) {
-              if (reservation) await SponsorBudget.release(sponsorBudgetStore, reservation)
+              if (reservation) await SponsorBudget.release(sponsorBudgetStore!, reservation)
               if (finalHash && finalHash.toLowerCase() !== hash.toLowerCase())
                 await releaseHashUse(store, finalHash)
               await releaseHashUse(store, hash)
@@ -710,7 +726,7 @@ export function charge<const parameters extends charge.Parameters>(
 
 export declare namespace charge {
   type StoreItemMap = {
-    [key: `mppx:charge:${string}`]: number | SponsorBudget.State
+    [key: `mppx:charge:${string}`]: number | SponsorBudget.State | Store.ReplayMarker
   }
 
   type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.charge>, 'feePayer' | 'recipient'>
@@ -739,13 +755,8 @@ 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 and a bounded aggregate in-flight fee
-     * budget. Sponsored transactions reserve their declared maximum fee
-     * atomically; independent expiring-nonce transactions run concurrently
-     * while capacity remains and wait for capacity when the budget is full.
-     *
-     * If you increase `maxGas`, `maxFeePerGas`, or `maxTotalFee`, you may also
-     * need to raise `maxInFlightTotalFee`.
+     * priority-fee ceiling on Moderato. Aggregate in-flight exposure is
+     * configured separately with `sponsorBudget`.
      */
     feePayerPolicy?: FeePayerPolicy | undefined
     /**
@@ -785,8 +796,24 @@ 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. */
+    /**
+     * 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
+    /**
+     * Configures aggregate in-flight fee exposure for sponsored transactions.
+     *
+     * Set to `false` only when aggregate exposure is enforced outside mppx.
+     * The configured store must be shared by every process using the sponsor.
+     * @default `{}`
+     */
+    sponsorBudget?: SponsorBudgetConfig | false | undefined
     /**
      * Whether to wait for the charge transaction to confirm on-chain before
      * responding. @default true
@@ -801,7 +828,8 @@ export declare namespace charge {
     waitForConfirmation?: boolean | undefined
   } & Client.getResolver.Parameters &
     Account.resolve.Parameters &
-    Defaults
+    Defaults &
+    Method.ComposableHooks<typeof Methods.charge>
 
   type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<
     parameters,
@@ -813,16 +841,28 @@ export declare namespace charge {
   >
 
   type FeePayerPolicy = Partial<FeePayer.Policy> & {
-    /** Maximum number of sponsored transactions awaiting a terminal receipt. @default 100 */
+    /**
+     * Maximum number of sponsored transactions awaiting a terminal receipt.
+     * @deprecated Use `sponsorBudget.maxInFlightReservations`.
+     */
     maxInFlightReservations?: number | undefined
     /**
      * Maximum aggregate declared fee exposure awaiting terminal receipts.
      *
-     * @default `maxTotalFee * 10`
+     * @deprecated Use `sponsorBudget.maxInFlightTotalFee`.
      */
     maxInFlightTotalFee?: bigint | undefined
   }
 
+  type SponsorBudgetConfig = {
+    /** Maximum number of sponsored transactions awaiting a terminal receipt. @default 100 */
+    maxInFlightReservations?: number | undefined
+    /** Maximum aggregate declared fee exposure. @default `feePayerPolicy.maxTotalFee * 10` */
+    maxInFlightTotalFee?: bigint | undefined
+    /** Atomic store shared by every process using the sponsor. Defaults to `store`. */
+    store?: Store.AtomicStore | undefined
+  }
+
   /** Tempo API relay configuration for server-side charges. */
   type RelayOptions = Relay.configure.Options
 }
@@ -1165,14 +1205,12 @@ function getProofStoreKey(challengeId: string): `mppx:charge:${string}` {
   return `mppx:charge:proof:${challengeId}`
 }
 
-async function markHashUsed(
+async function tryClaimHash(
   store: Store.AtomicStore<charge.StoreItemMap>,
   hash: `0x${string}`,
+  expires: number,
 ): Promise<boolean> {
-  return store.update(getHashStoreKey(hash), (current) => {
-    if (current !== null) return { op: 'noop', result: false }
-    return { op: 'set', value: Date.now(), result: true }
-  })
+  return Store.tryClaim(store, getHashStoreKey(hash), expires)
 }
 
 /** @internal */
@@ -1199,14 +1237,12 @@ function parseHashCredentialSource(parameters: {
 }
 
 /** @internal */
-async function markProofUsed(
+async function tryClaimProof(
   store: Store.AtomicStore<charge.StoreItemMap>,
   challengeId: string,
+  expires: number,
 ): Promise<boolean> {
-  return store.update(getProofStoreKey(challengeId), (current) => {
-    if (current !== null) return { op: 'noop', result: false }
-    return { op: 'set', value: Date.now(), result: true }
-  })
+  return Store.tryClaim(store, getProofStoreKey(challengeId), expires)
 }
 
 function recoverAuthorizedProofSigner(parameters: {