mppx 0.4.11 → 0.5.0

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({
@@ -843,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/server/internal/transport.test.ts

@@ -82,6 +82,19 @@ function makeReceipt() {
   }
 }
 
+async function readResponseText(response: Response): Promise<string> {
+  if (!response.body) return ''
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  let result = ''
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    result += decoder.decode(value, { stream: true })
+  }
+  return result
+}
+
 describe('sse transport', () => {
   test('getCredential returns null when no Authorization header', () => {
     const store = memoryStore()
@@ -152,6 +165,19 @@ describe('sse transport', () => {
       challengeId,
     })
     expect(response.headers.get('Content-Type')).toContain('text/event-stream')
+
+    const body = await readResponseText(response)
+    const receiptRaw = body.split('event: payment-receipt\ndata: ')[1]?.split('\n\n')[0]
+    const terminalReceipt = JSON.parse(receiptRaw!)
+
+    expect(response.headers.get('Payment-Receipt')).toBeNull()
+    expect(body).toContain('event: message\ndata: hello\n\n')
+    expect(body).toContain('event: message\ndata: world\n\n')
+    expect(body).toContain('event: payment-receipt\n')
+    expect(terminalReceipt.challengeId).toBe(challengeId)
+    expect(terminalReceipt.channelId).toBe(channelId)
+    expect(terminalReceipt.units).toBe(2)
+    expect(terminalReceipt.spent).toBe('2000000')
   })
 
   test('respondReceipt with AsyncGeneratorFunction passes stream controller', async () => {
@@ -197,6 +223,12 @@ describe('sse transport', () => {
       challengeId,
     })
     expect(response.headers.get('Content-Type')).toContain('text/event-stream')
+
+    const body = await readResponseText(response)
+    expect(response.headers.get('Payment-Receipt')).toBeNull()
+    expect(body).toContain('event: message\ndata: chunk1\n\n')
+    expect(body).toContain('event: message\ndata: chunk2\n\n')
+    expect(body).toContain('event: payment-receipt\n')
   })
 
   test('respondReceipt with plain Response delegates to base http transport', () => {

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

@@ -539,6 +539,41 @@ describe.runIf(isLocalnet)('on-chain', () => {
       ).rejects.toThrow('topUp transaction amount')
     })
 
+    test('rejects when post-broadcast deposit does not exceed declared previousDeposit', async () => {
+      const salt = nextSalt()
+      const deposit = 5_000_000n
+      const topUpAmount = 1_000_000n
+
+      const { channelId } = await openChannel({
+        escrow: escrowContract,
+        payer,
+        payee: recipient,
+        token: currency,
+        deposit,
+        salt,
+      })
+
+      const { serializedTransaction } = await signTopUpChannel({
+        escrow: escrowContract,
+        payer,
+        channelId,
+        token: currency,
+        amount: topUpAmount,
+      })
+
+      await expect(
+        broadcastTopUpTransaction({
+          client,
+          serializedTransaction,
+          escrowContract,
+          channelId,
+          currency: asset,
+          declaredDeposit: topUpAmount,
+          previousDeposit: deposit + topUpAmount,
+        }),
+      ).rejects.toThrow('channel deposit did not increase after topUp')
+    })
+
     test('successful broadcast returns txHash and newDeposit', async () => {
       const salt = nextSalt()
       const deposit = 5_000_000n
@@ -730,7 +765,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 +789,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 +798,7 @@ describe.runIf(isLocalnet)('on-chain', () => {
           cumulativeAmount: settleAmount,
           signature,
         },
-        accounts[0],
+        { account: accounts[0] },
       )
 
       expect(txHash).toBeDefined()
@@ -769,6 +807,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 +859,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 +883,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 +892,7 @@ describe.runIf(isLocalnet)('on-chain', () => {
           cumulativeAmount: closeAmount,
           signature,
         },
-        undefined,
-        accounts[0],
+        { account: accounts[0] },
       )
 
       expect(txHash).toBeDefined()

package/src/tempo/session/Chain.ts

@@ -93,6 +93,11 @@ function assertUint128(amount: bigint): void {
   }
 }
 
+/** Options for {@link settleOnChain}. */
+export type SettleOptions =
+  | { feePayer: Account; account: Account }
+  | { feePayer?: undefined; account?: Account | undefined }
+
 /**
  * Submit a settle transaction on-chain.
  */
@@ -100,16 +105,21 @@ export async function settleOnChain(
   client: Client,
   escrowContract: Address,
   voucher: SignedVoucher,
-  feePayer?: Account | undefined,
+  options?: SettleOptions,
 ): Promise<Hex> {
   assertUint128(voucher.cumulativeAmount)
+  const resolved = options?.account ?? client.account
+  if (!resolved)
+    throw new Error(
+      'Cannot settle channel: no account available. Pass an `account` to tempo.settle(), or provide a `getClient` that returns an account-bearing client.',
+    )
   const args = [voucher.channelId, voucher.cumulativeAmount, voucher.signature] as const
-  if (feePayer) {
+  if (options?.feePayer) {
     const data = encodeFunctionData({ abi: escrowAbi, functionName: 'settle', args })
-    return sendFeePayerTx(client, feePayer, escrowContract, data, 'settle')
+    return sendFeePayerTx(client, resolved, options.feePayer, escrowContract, data, 'settle')
   }
   return writeContract(client, {
-    account: client.account!,
+    account: resolved,
     chain: client.chain,
     address: escrowContract,
     abi: escrowAbi,
@@ -118,6 +128,11 @@ export async function settleOnChain(
   })
 }
 
+/** Options for {@link closeOnChain}. */
+export type CloseOptions =
+  | { feePayer: Account; account: Account }
+  | { feePayer?: undefined; account?: Account | undefined }
+
 /**
  * Submit a close transaction on-chain.
  */
@@ -125,19 +140,18 @@ export async function closeOnChain(
   client: Client,
   escrowContract: Address,
   voucher: SignedVoucher,
-  account?: Account,
-  feePayer?: Account | undefined,
+  options?: CloseOptions,
 ): Promise<Hex> {
   assertUint128(voucher.cumulativeAmount)
-  const resolved = account ?? client.account
+  const resolved = options?.account ?? client.account
   if (!resolved)
     throw new Error(
       'Cannot close channel: no account available. Pass an `account` (viem Account, e.g. privateKeyToAccount("0x...")) to tempo.session(), or provide a `getClient` that returns an account-bearing client.',
     )
   const args = [voucher.channelId, voucher.cumulativeAmount, voucher.signature] as const
-  if (feePayer) {
+  if (options?.feePayer) {
     const data = encodeFunctionData({ abi: escrowAbi, functionName: 'close', args })
-    return sendFeePayerTx(client, feePayer, escrowContract, data, 'close')
+    return sendFeePayerTx(client, resolved, options.feePayer, escrowContract, data, 'close')
   }
   return writeContract(client, {
     account: resolved,
@@ -155,9 +169,13 @@ export async function closeOnChain(
  * Follows the same signTransaction + sendRawTransactionSync pattern used
  * by broadcastOpenTransaction / broadcastTopUpTransaction, but originates
  * the transaction server-side (estimating gas and fees first).
+ *
+ * @param account - The logical sender / msg.sender (e.g. the payee).
+ * @param feePayer - The gas sponsor — only co-signs to cover fees.
  */
 async function sendFeePayerTx(
   client: Client,
+  account: Account,
   feePayer: Account,
   to: Address,
   data: Hex,
@@ -167,12 +185,10 @@ async function sendFeePayerTx(
   // token.  `feePayer: true` tells the prepare hook to use expiring nonces but
   // does NOT set feeToken automatically, so we must provide it explicitly.
   const chainId = client.chain?.id
-  const feeToken = chainId
-    ? defaults.currency[chainId as keyof typeof defaults.currency]
-    : undefined
+  const feeToken = chainId ? defaults.resolveCurrency({ chainId }) : undefined
 
   const prepared = await prepareTransactionRequest(client, {
-    account: feePayer,
+    account,
     calls: [{ to, data }],
     feePayer: true,
     ...(feeToken ? { feeToken } : {}),
@@ -180,7 +196,7 @@ async function sendFeePayerTx(
 
   const serialized = (await signTransaction(client, {
     ...prepared,
-    account: feePayer,
+    account,
     feePayer,
   } as never)) as Hex
 

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

@@ -366,6 +366,37 @@ describe('serve', () => {
     expect(receipt.challengeId).toBe(challengeId)
   })
 
+  test('emits exactly one terminal payment-receipt event at stream end', async () => {
+    const storage = memoryStore()
+    await seedChannel(storage, 2000000n)
+
+    const stream = serve({
+      store: storage,
+      channelId,
+      challengeId,
+      tickCost: 1000000n,
+      generate: generate(['one', 'two']),
+    })
+
+    const output = await readStream(stream)
+    const events = output
+      .trim()
+      .split('\n\n')
+      .filter((chunk) => chunk.length > 0)
+      .map((chunk) => parseEvent(`${chunk}\n\n`))
+      .filter((event): event is NonNullable<typeof event> => event !== null)
+
+    const terminal = events.at(-1)
+    expect(terminal?.type).toBe('payment-receipt')
+    if (terminal?.type !== 'payment-receipt') throw new Error('expected terminal payment receipt')
+
+    expect(events.filter((event) => event.type === 'payment-receipt')).toHaveLength(1)
+    expect(terminal.data.challengeId).toBe(challengeId)
+    expect(terminal.data.channelId).toBe(channelId)
+    expect(terminal.data.units).toBe(2)
+    expect(terminal.data.spent).toBe('2000000')
+  })
+
   test('handles empty generator', async () => {
     const storage = memoryStore()
     await seedChannel(storage, 1000000n)