mppx 0.4.10 → 0.4.12

package/src/tempo/server/Charge.ts

@@ -1,4 +1,3 @@
-import type { TempoAddress as TempoAddress_types } from 'ox/tempo'
 import { decodeFunctionData, keccak256, parseEventLogs, type TransactionReceipt } from 'viem'
 import {
   getTransactionReceipt,
@@ -11,12 +10,13 @@ import { tempo as tempo_chain } from 'viem/chains'
 import { Abis, Transaction } from 'viem/tempo'
 
 import { PaymentExpiredError } from '../../Errors.js'
-import type { LooseOmit } from '../../internal/types.js'
+import type { LooseOmit, NoExtraKeys } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import * as Store from '../../Store.js'
 import * as Client from '../../viem/Client.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 * as Selectors from '../internal/selectors.js'
@@ -34,7 +34,10 @@ import * as Methods from '../Methods.js'
  * ```
  */
 export function charge<const parameters extends charge.Parameters>(
-  parameters: parameters = {} as parameters,
+  parameters: NoExtraKeys<parameters, charge.Parameters> = {} as NoExtraKeys<
+    parameters,
+    charge.Parameters
+  >,
 ) {
   const {
     amount,
@@ -126,16 +129,12 @@ export function charge<const parameters extends charge.Parameters>(
           const hash = payload.hash as `0x${string}`
           await assertHashUnused(store, hash)
 
-          const receipt = await getTransactionReceipt(client, {
-            hash,
-          })
-
-          assertTransferLog(receipt, {
-            amount,
+          const expectedTransfers = getExpectedTransfers({ amount, memo, methodDetails, recipient })
+          const receipt = await getTransactionReceipt(client, { hash })
+          assertTransferLogs(receipt, {
             currency,
-            from: receipt.from,
-            memo,
-            recipient,
+            sender: receipt.from,
+            transfers: expectedTransfers,
           })
 
           await markHashUsed(store, hash)
@@ -161,58 +160,15 @@ export function charge<const parameters extends charge.Parameters>(
               {},
             )
 
-          const call = transaction.calls.find((call) => {
-            if (!call.to || !TempoAddress.isEqual(call.to, currency)) return false
-            if (!call.data) return false
-
-            const selector = call.data.slice(0, 10)
-
-            if (memo) {
-              if (selector !== Selectors.transferWithMemo) return false
-              try {
-                const { args } = decodeFunctionData({ abi: Abis.tip20, data: call.data })
-                const [to, amount_, memo_] = args as [`0x${string}`, bigint, `0x${string}`]
-                return (
-                  TempoAddress.isEqual(to, recipient) &&
-                  amount_.toString() === amount &&
-                  memo_.toLowerCase() === memo.toLowerCase()
-                )
-              } catch {
-                return false
-              }
-            }
-
-            if (selector === Selectors.transfer) {
-              try {
-                const { args } = decodeFunctionData({ abi: Abis.tip20, data: call.data })
-                const [to, amount_] = args as [`0x${string}`, bigint]
-                return TempoAddress.isEqual(to, recipient) && amount_.toString() === amount
-              } catch {
-                return false
-              }
-            }
-
-            if (selector === Selectors.transferWithMemo) {
-              try {
-                const { args } = decodeFunctionData({ abi: Abis.tip20, data: call.data })
-                const [to, amount_] = args as [`0x${string}`, bigint, `0x${string}`]
-                return TempoAddress.isEqual(to, recipient) && amount_.toString() === amount
-              } catch {
-                return false
-              }
-            }
-
-            return false
-          })
+          const calls = (transaction.calls ?? []) as readonly {
+            data?: `0x${string}` | undefined
+            to?: `0x${string}` | undefined
+          }[]
+          const transfers = getExpectedTransfers({ amount, memo, methodDetails, recipient })
+          const isFeePayerTx = !!(feePayer || feePayerUrl) && methodDetails?.feePayer !== false
+          assertTransferCalls(calls, { currency, exactCount: isFeePayerTx, transfers })
 
-          if (!call)
-            throw new MismatchError('Invalid transaction: no matching payment call found', {
-              amount,
-              currency,
-              recipient,
-            })
-
-          if ((feePayer || feePayerUrl) && methodDetails?.feePayer !== false)
+          if (isFeePayerTx)
             FeePayer.validateCalls(transaction.calls, { amount, currency, recipient })
 
           const resolvedFeeToken =
@@ -234,12 +190,10 @@ export function charge<const parameters extends charge.Parameters>(
             const receipt = await sendRawTransactionSync(client, {
               serializedTransaction: serializedTransaction_final,
             })
-            assertTransferLog(receipt, {
-              amount,
+            assertTransferLogs(receipt, {
               currency,
-              from: transaction.from,
-              memo,
-              recipient,
+              sender: transaction.from! as `0x${string}`,
+              transfers,
             })
             // Post-broadcast dedup: catch malleable input variants
             // (different serialized bytes, same underlying tx) that
@@ -323,72 +277,187 @@ export declare namespace charge {
   }
 }
 
-/** @internal */
-function assertTransferLog(
-  receipt: TransactionReceipt,
+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: {
-    amount: string
-    currency: TempoAddress_types.Address
-    from: TempoAddress_types.Address
-    memo: `0x${string}` | undefined
-    recipient: TempoAddress_types.Address
+    currency: `0x${string}`
+    exactCount?: boolean | undefined
+    transfers: readonly ExpectedTransfer[]
   },
-): void {
-  const { amount, currency, from, memo, recipient } = parameters
-
-  if (memo) {
-    const memoLogs = parseEventLogs({
-      abi: Abis.tip20,
-      eventName: 'TransferWithMemo',
-      logs: receipt.logs,
-    })
+) {
+  const transferCalls = getTransferCalls(calls)
 
-    const match = memoLogs.find(
-      (log) =>
-        TempoAddress.isEqual(log.address, currency) &&
-        TempoAddress.isEqual(log.args.from, from) &&
-        TempoAddress.isEqual(log.args.to, recipient) &&
-        log.args.amount.toString() === amount &&
-        log.args.memo.toLowerCase() === memo.toLowerCase(),
-    )
-
-    if (!match)
-      throw new MismatchError(
-        'Payment verification failed: no matching transfer with memo found.',
-        {
-          amount,
-          currency,
-          memo,
-          recipient,
-        },
-      )
-  } else {
-    const transferLogs = parseEventLogs({
-      abi: Abis.tip20,
-      eventName: 'Transfer',
-      logs: receipt.logs,
+  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),
     })
 
-    const memoLogs = parseEventLogs({
-      abi: Abis.tip20,
-      eventName: 'TransferWithMemo',
-      logs: receipt.logs,
+  const used = new Set<number>()
+
+  // 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
+  })
+
+  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
     })
 
-    const match = [...transferLogs, ...memoLogs].find(
-      (log) =>
-        TempoAddress.isEqual(log.address, currency) &&
-        TempoAddress.isEqual(log.args.from, from) &&
-        TempoAddress.isEqual(log.args.to, recipient) &&
-        log.args.amount.toString() === amount,
-    )
+    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)
+  }
+}
+
+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
+}
 
-    if (!match)
+function assertTransferLogs(
+  receipt: TransactionReceipt,
+  parameters: {
+    currency: `0x${string}`
+    sender: `0x${string}`
+    transfers: readonly ExpectedTransfer[]
+  },
+) {
+  const transferLogs = parseEventLogs({
+    abi: Abis.tip20,
+    eventName: 'Transfer',
+    logs: receipt.logs,
+  }).map((log) => ({ ...log, kind: 'transfer' as const }))
+
+  const memoLogs = parseEventLogs({
+    abi: Abis.tip20,
+    eventName: 'TransferWithMemo',
+    logs: receipt.logs,
+  }).map((log) => ({ ...log, kind: 'memo' as const }))
+
+  const logs = [...transferLogs, ...memoLogs]
+  const used = new Set<number>()
+
+  // 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) {
+    const matchIndex = logs.findIndex((log, index) => {
+      if (used.has(index)) return false
+      if (!TempoAddress.isEqual(log.address, parameters.currency)) return false
+      if (!TempoAddress.isEqual(log.args.from, parameters.sender)) return false
+      if (!TempoAddress.isEqual(log.args.to, transfer.recipient)) return false
+      if (log.args.amount.toString() !== transfer.amount) return false
+      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 (matchIndex === -1) {
       throw new MismatchError('Payment verification failed: no matching transfer found.', {
-        amount,
-        currency,
-        recipient,
+        amount: transfer.amount,
+        currency: parameters.currency,
+        recipient: transfer.recipient,
       })
+    }
+
+    used.add(matchIndex)
   }
 }
 

package/src/tempo/server/Methods.ts

@@ -14,7 +14,10 @@ import { session as session_, settle as settle_ } from './Session.js'
  * ```
  */
 export function tempo<const parameters extends tempo.Parameters>(parameters?: parameters) {
-  return [tempo.charge(parameters), tempo.session(parameters)] as const
+  return [
+    tempo.charge(parameters as charge_.Parameters as never),
+    tempo.session(parameters as session_.Parameters as never),
+  ] as const
 }
 
 export namespace tempo {

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

@@ -885,6 +885,34 @@ describe.runIf(isLocalnet)('session', () => {
         }),
       ).rejects.toThrow(ChannelClosedError)
     })
+
+    test('rejects voucher when deposit is zero (settled race window)', async () => {
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      // Use a large TTL so the voucher path uses the cached store state
+      // instead of reading on-chain. This lets us simulate the settlement
+      // race where deposit=0 but finalized=false by manipulating the store.
+      const server = createServer({ channelStateTtl: 60_000 })
+      await openServerChannel(server, channelId, serializedTransaction)
+
+      // Simulate the escrow contract zeroing the deposit before setting
+      // finalized (the race window this PR guards against).
+      await store.updateChannel(channelId, (ch) => (ch ? { ...ch, deposit: 0n } : null))
+
+      await expect(
+        server.verify({
+          credential: {
+            challenge: makeChallenge({ id: 'challenge-after-settle', channelId }),
+            payload: {
+              action: 'voucher' as const,
+              channelId,
+              cumulativeAmount: '2000000',
+              signature: await signTestVoucher(channelId, 2000000n),
+            },
+          },
+          request: makeRequest(),
+        }),
+      ).rejects.toThrow(ChannelClosedError)
+    })
   })
 
   describe('topUp', () => {
@@ -1143,6 +1171,35 @@ describe.runIf(isLocalnet)('session', () => {
       ).rejects.toThrow('close voucher amount must be >=')
     })
 
+    test('rejects close equal to on-chain settled amount', async () => {
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer()
+
+      // Open with 1M voucher (matches openServerChannel default)
+      await openServerChannel(server, channelId, serializedTransaction)
+
+      // Settle on-chain so settled becomes 1000000
+      const settleTxHash = await settle(store, client, channelId, { escrowContract })
+      await waitForTransactionReceipt(client, { hash: settleTxHash })
+
+      // Try to close with voucher == on-chain settled — should be rejected
+      // because replaying the settled amount doesn't commit new funds
+      await expect(
+        server.verify({
+          credential: {
+            challenge: makeChallenge({ id: 'challenge-2', channelId }),
+            payload: {
+              action: 'close' as const,
+              channelId,
+              cumulativeAmount: '1000000',
+              signature: await signTestVoucher(channelId, 1000000n),
+            },
+          },
+          request: makeRequest(),
+        }),
+      ).rejects.toThrow('close voucher amount must be >')
+    })
+
     test('rejects close exceeding on-chain deposit', async () => {
       const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
       const server = createServer()

package/src/tempo/server/Session.ts

@@ -14,6 +14,7 @@ import {
   type Address,
   type Hex,
   parseUnits,
+  zeroAddress,
   type Account as viem_Account,
   type Client as viem_Client,
 } from 'viem'
@@ -30,7 +31,7 @@ import {
   VerificationFailedError,
 } from '../../Errors.js'
 import type { Challenge, Credential } from '../../index.js'
-import type { LooseOmit } from '../../internal/types.js'
+import type { LooseOmit, NoExtraKeys } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import * as Store from '../../Store.js'
 import * as Client from '../../viem/Client.js'
@@ -82,7 +83,9 @@ type SessionMethodDetails = {
  * })
  * ```
  */
-export function session<const parameters extends session.Parameters>(p?: parameters) {
+export function session<const parameters extends session.Parameters>(
+  p?: NoExtraKeys<parameters, session.Parameters>,
+) {
   const parameters = p as parameters
   const {
     amount,
@@ -340,8 +343,10 @@ export async function settle(
   channelId: Hex,
   options?: {
     escrowContract?: Address | undefined
-    feePayer?: viem_Account | undefined
-  },
+  } & (
+    | { feePayer: viem_Account; account: viem_Account }
+    | { feePayer?: undefined; account?: viem_Account | undefined }
+  ),
 ): Promise<Hex> {
   const channel = await store.getChannel(channelId)
   if (!channel) throw new ChannelNotFoundError({ reason: 'channel not found' })
@@ -354,12 +359,11 @@ export async function settle(
   if (!resolvedEscrow) throw new Error(`No escrow contract for chainId ${chainId}.`)
 
   const settledAmount = channel.highestVoucher.cumulativeAmount
-  const txHash = await settleOnChain(
-    client,
-    resolvedEscrow,
-    channel.highestVoucher,
-    options?.feePayer,
-  )
+  const txHash = await settleOnChain(client, resolvedEscrow, channel.highestVoucher, {
+    ...(options?.feePayer && options?.account
+      ? { feePayer: options.feePayer, account: options.account }
+      : { account: options?.account }),
+  })
 
   await store.updateChannel(channelId, (current) => {
     if (!current) return null
@@ -456,6 +460,15 @@ async function verifyAndAcceptVoucher(parameters: {
   if (onChain.closeRequestedAt !== 0n) {
     throw new ChannelClosedError({ reason: 'channel has a pending close request' })
   }
+  // Treat a zero deposit on an existing channel as settled/closed.
+  // During settlement the escrow contract may zero the deposit before
+  // setting the finalized flag, creating a brief window where
+  // finalized=false but deposit=0. Without this guard the voucher
+  // check below would return a 402 (AmountExceedsDepositError) instead
+  // of the correct 410 (ChannelClosedError).
+  if (onChain.deposit === 0n && onChain.payer !== zeroAddress) {
+    throw new ChannelClosedError({ reason: 'channel deposit is zero (settled)' })
+  }
 
   if (voucher.cumulativeAmount <= onChain.settled) {
     throw new VerificationFailedError({
@@ -815,10 +828,14 @@ async function handleClose(
     throw new ChannelClosedError({ reason: 'channel is finalized on-chain' })
   }
 
-  const minCloseAmount = channel.spent > onChain.settled ? channel.spent : onChain.settled
-  if (voucher.cumulativeAmount < minCloseAmount) {
+  if (voucher.cumulativeAmount < channel.spent) {
+    throw new VerificationFailedError({
+      reason: `close voucher amount must be >= ${channel.spent} (spent)`,
+    })
+  }
+  if (voucher.cumulativeAmount <= onChain.settled) {
     throw new VerificationFailedError({
-      reason: `close voucher amount must be >= ${minCloseAmount} (max of spent and on-chain settled)`,
+      reason: `close voucher amount must be > ${onChain.settled} (on-chain settled)`,
     })
   }
 
@@ -839,13 +856,9 @@ async function handleClose(
     throw new InvalidSignatureError({ reason: 'invalid voucher signature' })
   }
 
-  const txHash = await closeOnChain(
-    client,
-    methodDetails.escrowContract,
-    voucher,
-    account,
-    feePayer,
-  )
+  const txHash = await closeOnChain(client, methodDetails.escrowContract, voucher, {
+    ...(feePayer && account ? { feePayer, account } : { account }),
+  })
 
   const updated = await store.updateChannel(payload.channelId, (current) => {
     if (!current) return null

package/src/tempo/session/Chain.test.ts

@@ -730,7 +730,9 @@ describe.runIf(isLocalnet)('on-chain', () => {
       expect(channel.finalized).toBe(false)
     })
 
-    test('settles a channel with fee payer', async () => {
+    test.todo('settles with distinct feePayer != account (fee-sponsored settle)')
+
+    test('settles with explicit account (no fee payer)', async () => {
       const salt = nextSalt()
       const deposit = 10_000_000n
       const settleAmount = 5_000_000n
@@ -752,6 +754,7 @@ describe.runIf(isLocalnet)('on-chain', () => {
         chain.id,
       )
 
+      // Pass account explicitly — should use it as sender instead of client.account
       const txHash = await settleOnChain(
         client,
         escrowContract,
@@ -760,7 +763,7 @@ describe.runIf(isLocalnet)('on-chain', () => {
           cumulativeAmount: settleAmount,
           signature,
         },
-        accounts[0],
+        { account: accounts[0] },
       )
 
       expect(txHash).toBeDefined()
@@ -769,6 +772,21 @@ describe.runIf(isLocalnet)('on-chain', () => {
       expect(channel.settled).toBe(settleAmount)
       expect(channel.finalized).toBe(false)
     })
+
+    test('throws when no account available', async () => {
+      const noAccountClient = { chain: { id: 42431 } } as any
+      const dummyEscrow = '0x0000000000000000000000000000000000000001' as Address
+      const dummyChannelId =
+        '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+
+      await expect(
+        settleOnChain(noAccountClient, dummyEscrow, {
+          channelId: dummyChannelId,
+          cumulativeAmount: 1_000_000n,
+          signature: '0xsig' as Hex,
+        }),
+      ).rejects.toThrow('no account available')
+    })
   })
 
   describe('closeOnChain', () => {
@@ -806,7 +824,9 @@ describe.runIf(isLocalnet)('on-chain', () => {
       expect(channel.finalized).toBe(true)
     })
 
-    test('closes a channel with fee payer', async () => {
+    test.todo('closes with distinct feePayer != account (fee-sponsored close)')
+
+    test('closes with explicit account (no fee payer)', async () => {
       const salt = nextSalt()
       const deposit = 10_000_000n
       const closeAmount = 5_000_000n
@@ -828,6 +848,7 @@ describe.runIf(isLocalnet)('on-chain', () => {
         chain.id,
       )
 
+      // Pass account explicitly — should use it as sender instead of client.account
       const txHash = await closeOnChain(
         client,
         escrowContract,
@@ -836,8 +857,7 @@ describe.runIf(isLocalnet)('on-chain', () => {
           cumulativeAmount: closeAmount,
           signature,
         },
-        undefined,
-        accounts[0],
+        { account: accounts[0] },
       )
 
       expect(txHash).toBeDefined()