mppx 0.8.12 → 0.8.14

package/src/tempo/session/server/RequestState.test.ts

@@ -316,7 +316,11 @@ describe('SessionSnapshotHints', () => {
       escrowContract,
       expiringNonceHash: descriptor.expiringNonceHash,
       finalized: false,
-      highestVoucher: null,
+      highestVoucher: {
+        channelId,
+        cumulativeAmount: 500n,
+        signature: `0x${'44'.repeat(64)}`,
+      },
       highestVoucherAmount: 500n,
       operator: descriptor.operator,
       payee: descriptor.payee,
@@ -451,6 +455,11 @@ describe('SessionSnapshotHints', () => {
         deposit: '1000',
         descriptor,
         escrow: escrowContract,
+        highestVoucher: {
+          channelId,
+          cumulativeAmount: '500',
+          signature: `0x${'44'.repeat(64)}`,
+        },
         requiredCumulative: '350',
         settled: '100',
         spent: '300',
@@ -458,7 +467,7 @@ describe('SessionSnapshotHints', () => {
       })
     })
 
-    test('raises accepted cumulative when next request exceeds current authorization', async () => {
+    test('keeps accepted cumulative at the signed voucher when the next request needs more', async () => {
       const snapshot = await resolveSessionSnapshot({
         amount: 300n,
         channelId,
@@ -466,7 +475,34 @@ describe('SessionSnapshotHints', () => {
       })
 
       expect(snapshot?.requiredCumulative).toBe('600')
-      expect(snapshot?.acceptedCumulative).toBe('600')
+      expect(snapshot?.acceptedCumulative).toBe('500')
+      expect(snapshot?.highestVoucher?.cumulativeAmount).toBe('500')
+    })
+
+    test('omits reusable channel hints without a matching signed highest voucher', async () => {
+      await expect(
+        resolveSessionSnapshot({
+          amount: 50n,
+          channelId,
+          store: store(channel({ highestVoucher: null })),
+        }),
+      ).resolves.toBeUndefined()
+
+      await expect(
+        resolveSessionSnapshot({
+          amount: 50n,
+          channelId,
+          store: store(
+            channel({
+              highestVoucher: {
+                channelId,
+                cumulativeAmount: 499n,
+                signature: `0x${'44'.repeat(64)}`,
+              },
+            }),
+          ),
+        }),
+      ).resolves.toBeUndefined()
     })
 
     test('omits reusable channel hints when payment fields do not match', async () => {
@@ -508,10 +544,17 @@ describe('SessionSnapshotHints', () => {
       }
     })
 
-    test('omits hints for missing, non-precompile, or finalized channels', async () => {
+    test('omits hints for missing, non-precompile, closing, or finalized channels', async () => {
       await expect(
         resolveSessionSnapshot({ amount: 1n, channelId, store: store(null) }),
       ).resolves.toBe(undefined)
+      await expect(
+        resolveSessionSnapshot({
+          amount: 1n,
+          channelId,
+          store: store(channel({ closeRequestedAt: 1n })),
+        }),
+      ).resolves.toBe(undefined)
       await expect(
         resolveSessionSnapshot({
           amount: 1n,

package/src/tempo/session/server/RequestState.ts

@@ -80,7 +80,11 @@ export type ResolveSessionChannelIdParameters = {
   store: ChannelStore.ChannelStore
 }
 
-/** Application hook for mapping request identity to an existing session channel. */
+/**
+ * Application-owned lookup from authenticated identity and payment scope to an existing session
+ * channel. MPPx does not derive a storage key or scan the channel store; the returned channel ID is
+ * loaded and independently validated before its snapshot is advertised.
+ */
 export type ResolveSessionChannelId = (
   parameters: ResolveSessionChannelIdParameters,
 ) => Promise<string | null | undefined> | string | null | undefined
@@ -139,21 +143,24 @@ export async function resolveSessionSnapshot(
   const channel = await store.getChannel(ChannelStore.normalizeChannelId(channelId))
   if (!channel || !ChannelStore.isPrecompileState(channel)) return undefined
   if (channel.finalized) return undefined
+  if (channel.closeRequestedAt !== 0n) return undefined
+  if (!channel.highestVoucher) return undefined
+  if (channel.highestVoucher.cumulativeAmount !== channel.highestVoucherAmount) return undefined
   if (expected && !matchesSnapshotPaymentFields(channel, expected)) return undefined
   const requiredCumulative = channel.spent + amount
-  const acceptedCumulative =
-    channel.highestVoucherAmount > requiredCumulative
-      ? channel.highestVoucherAmount
-      : requiredCumulative
   return {
-    acceptedCumulative: acceptedCumulative.toString(),
+    acceptedCumulative: channel.highestVoucherAmount.toString(),
     chainId: channel.chainId,
     channelId: channel.channelId,
-    closeRequestedAt:
-      channel.closeRequestedAt === 0n ? undefined : channel.closeRequestedAt.toString(),
+    closeRequestedAt: undefined,
     deposit: channel.deposit.toString(),
     descriptor: channel.descriptor,
     escrow: channel.escrowContract,
+    highestVoucher: {
+      channelId: channel.highestVoucher.channelId,
+      cumulativeAmount: channel.highestVoucher.cumulativeAmount.toString(),
+      signature: channel.highestVoucher.signature,
+    },
     requiredCumulative: requiredCumulative.toString(),
     settled: channel.settledOnChain.toString(),
     spent: channel.spent.toString(),

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

@@ -556,8 +556,21 @@ describe('precompile server session unit guardrails', () => {
   test('request returns a server session snapshot for a known precompile channel', async () => {
     const { method, store } = createServer()
     const openPayload = await createOpenPayload({ initialAmount: 100n })
+    const highestVoucher = await ClientOps.createVoucherPayload(
+      createSigningClient(),
+      payer,
+      openPayload.descriptor,
+      Types.uint96(250n),
+      chainId,
+    )
+    if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
     await persistPrecompileChannel(store, openPayload, {
       highestVoucherAmount: 250n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 250n,
+        signature: highestVoucher.signature,
+      },
       spent: 200n,
       units: 2,
     })
@@ -585,6 +598,11 @@ describe('precompile server session unit guardrails', () => {
       deposit: '1000',
       descriptor: openPayload.descriptor,
       escrow: tip20ChannelEscrow,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: '250',
+        signature: highestVoucher.signature,
+      },
       requiredCumulative: '201',
       settled: '0',
       spent: '200',
@@ -594,6 +612,14 @@ describe('precompile server session unit guardrails', () => {
 
   test('request can resolve a server session snapshot from request identity', async () => {
     const openPayload = await createOpenPayload({ initialAmount: 100n })
+    const highestVoucher = await ClientOps.createVoucherPayload(
+      createSigningClient(),
+      payer,
+      openPayload.descriptor,
+      Types.uint96(250n),
+      chainId,
+    )
+    if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
     const { method, store } = createServer({
       resolveChannelId({ request, credential, paymentRequest, store: hookStore }) {
         expect(request?.headers.get('cookie')).toBe('sid=session-1')
@@ -605,6 +631,11 @@ describe('precompile server session unit guardrails', () => {
     })
     await persistPrecompileChannel(store, openPayload, {
       highestVoucherAmount: 250n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 250n,
+        signature: highestVoucher.signature,
+      },
       spent: 200n,
       units: 2,
     })
@@ -661,8 +692,21 @@ describe('precompile server session unit guardrails', () => {
   test('request uses zero effective amount for non-content snapshot hints', async () => {
     const { method, store } = createServer()
     const openPayload = await createOpenPayload({ initialAmount: 100n })
+    const highestVoucher = await ClientOps.createVoucherPayload(
+      createSigningClient(),
+      payer,
+      openPayload.descriptor,
+      Types.uint96(250n),
+      chainId,
+    )
+    if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
     await persistPrecompileChannel(store, openPayload, {
       highestVoucherAmount: 250n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 250n,
+        signature: highestVoucher.signature,
+      },
       spent: 250n,
       units: 2,
     })
@@ -2032,8 +2076,21 @@ describe('precompile server session unit guardrails', () => {
       const rawStore = Store.memory()
       const store = channelStore(rawStore)
       const openPayload = await createOpenPayload({ initialAmount: 1n })
+      const highestVoucher = await ClientOps.createVoucherPayload(
+        createSigningClient(),
+        payer,
+        openPayload.descriptor,
+        Types.uint96(5n),
+        chainId,
+      )
+      if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
       await persistPrecompileChannel(store, openPayload, {
         highestVoucherAmount: 5n,
+        highestVoucher: {
+          channelId: openPayload.channelId,
+          cumulativeAmount: 5n,
+          signature: highestVoucher.signature,
+        },
         spent: 3n,
         units: 3,
       })
@@ -2056,6 +2113,10 @@ describe('precompile server session unit guardrails', () => {
       expect(snapshot).toMatchObject({
         channelId: openPayload.channelId,
         acceptedCumulative: '5',
+        highestVoucher: {
+          channelId: openPayload.channelId,
+          cumulativeAmount: '5',
+        },
         requiredCumulative: '3',
         spent: '3',
       })
@@ -3337,3 +3398,403 @@ describe('precompile server session unit guardrails', () => {
     ).rejects.toThrow(/tx sender .* is not the channel payee/)
   })
 })
+
+describe('onSessionSettlement', () => {
+  function createSettleClient(channelId: Hex, settledAmount: bigint) {
+    return createClient({
+      account: payer,
+      chain: testChain,
+      transport: custom({
+        async request(args) {
+          if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
+          if (args.method === 'eth_getTransactionCount') return '0x0'
+          if (args.method === 'eth_estimateGas') return '0x5208'
+          if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+          if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+          if (args.method === 'eth_sendRawTransaction') return `0x${'cc'.repeat(32)}`
+          if (args.method === 'eth_sendTransaction') return `0x${'cc'.repeat(32)}`
+          if (args.method === 'eth_getTransactionReceipt')
+            return transactionReceipt([settledLog(channelId, settledAmount)])
+          if (args.method === 'eth_call') {
+            return encodeFunctionResult({
+              abi: escrowAbi,
+              functionName: 'getChannelState',
+              result: { settled: settledAmount, deposit: 1_000n, closeRequestedAt: 0 },
+            })
+          }
+          throw new Error(`unexpected rpc request: ${args.method}`)
+        },
+      }),
+    })
+  }
+
+  test('fires onSessionSettlement for explicit settle() calls', async () => {
+    const events: { trigger: string; txHash: string; amount: bigint; delta: bigint }[] = []
+    const store = Store.memory()
+    const openPayload = await createOpenPayload()
+    await persistPrecompileChannel(channelStore(store), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const { settle } = await import('./Session.js')
+    const client = createSettleClient(openPayload.channelId, 100n)
+    await settle(store, client, openPayload.channelId, {
+      onSessionSettlement: (ctx) => {
+        events.push({
+          trigger: ctx.trigger,
+          txHash: ctx.txHash,
+          amount: ctx.amount,
+          delta: ctx.delta,
+        })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'settle',
+      txHash: `0x${'cc'.repeat(32)}`,
+      amount: 100n,
+      delta: 100n,
+    })
+  })
+
+  test('fires onSessionSettlement for auto-scheduled settlements', async () => {
+    const events: { trigger: string; channelId: string; amount: bigint; delta: bigint }[] = []
+    const rawStore = Store.memory()
+    const openPayload = await createOpenPayload()
+    const store = channelStore(rawStore)
+    await persistPrecompileChannel(store, openPayload, {
+      payee: payer.address,
+      spent: 500n,
+      units: 10,
+      highestVoucherAmount: 500n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 500n,
+        signature: '0x1234',
+      },
+    })
+
+    const { maybeSettleScheduled } = await import('./Settlement.js')
+    const client = createSettleClient(openPayload.channelId, 500n)
+    const channel = await store.getChannel(openPayload.channelId)
+
+    await maybeSettleScheduled({
+      account: payer,
+      channel: channel!,
+      client,
+      schedule: { units: 5 },
+      store,
+      onSessionSettlement: (ctx) => {
+        events.push({
+          trigger: ctx.trigger,
+          channelId: ctx.channelId,
+          amount: ctx.amount,
+          delta: ctx.delta,
+        })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'scheduled',
+      channelId: openPayload.channelId,
+      amount: 500n,
+      delta: 500n,
+    })
+  })
+
+  test('delta reflects incremental scheduled settlement with prior on-chain settlement', async () => {
+    const events: { trigger: string; amount: bigint; delta: bigint }[] = []
+    const rawStore = Store.memory()
+    const openPayload = await createOpenPayload()
+    const store = channelStore(rawStore)
+    await persistPrecompileChannel(store, openPayload, {
+      payee: payer.address,
+      spent: 500n,
+      units: 10,
+      settledOnChain: 200n,
+      highestVoucherAmount: 500n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 500n,
+        signature: '0x1234',
+      },
+    })
+
+    const { maybeSettleScheduled } = await import('./Settlement.js')
+    const client = createSettleClient(openPayload.channelId, 500n)
+    const channel = await store.getChannel(openPayload.channelId)
+
+    await maybeSettleScheduled({
+      account: payer,
+      channel: channel!,
+      client,
+      schedule: { units: 5 },
+      store,
+      onSessionSettlement: (ctx) => {
+        events.push({ trigger: ctx.trigger, amount: ctx.amount, delta: ctx.delta })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'scheduled',
+      amount: 500n,
+      delta: 300n,
+    })
+  })
+
+  test('fires onSessionSettlement for cooperative close', async () => {
+    const events: { trigger: string; txHash: string; amount: bigint; delta: bigint }[] = []
+    const openPayload = await createOpenPayload()
+    const closedAmount = 100n
+    const refundedAmount = 900n
+    const rawStore = Store.memory()
+
+    const closeClient = createClient({
+      account: payer,
+      chain: testChain,
+      transport: custom({
+        async request(args) {
+          if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
+          if (args.method === 'eth_getTransactionCount') return '0x0'
+          if (args.method === 'eth_estimateGas') return '0x5208'
+          if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+          if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+          if (args.method === 'eth_sendRawTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_sendTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_getTransactionReceipt')
+            return transactionReceipt([
+              closedLog(openPayload.channelId, closedAmount, refundedAmount),
+            ])
+          if (args.method === 'eth_call') {
+            return encodeFunctionResult({
+              abi: escrowAbi,
+              functionName: 'getChannelState',
+              result: { settled: 0n, deposit: 1_000n, closeRequestedAt: 0 },
+            })
+          }
+          throw new Error(`unexpected rpc request: ${args.method}`)
+        },
+      }),
+    })
+
+    const method = session({
+      amount: '1',
+      chainId,
+      currency: token,
+      decimals: 0,
+      recipient: payee,
+      store: rawStore,
+      unitType: 'request',
+      getClient: () => closeClient,
+      onSessionSettlement: (ctx) => {
+        events.push({
+          trigger: ctx.trigger,
+          txHash: ctx.txHash,
+          amount: ctx.amount,
+          delta: ctx.delta,
+        })
+      },
+    })
+
+    await persistPrecompileChannel(channelStore(rawStore), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const closeSignature = await Voucher.signVoucher(
+      createSigningClient(),
+      payer,
+      { channelId: openPayload.channelId, cumulativeAmount: 100n },
+      tip20ChannelEscrow,
+      chainId,
+    )
+
+    await method.verify({
+      credential: {
+        challenge: makeChallenge(openPayload.channelId),
+        payload: {
+          action: 'close',
+          channelId: openPayload.channelId,
+          descriptor: openPayload.descriptor,
+          cumulativeAmount: '100',
+          signature: closeSignature,
+        },
+      },
+      request: verifyRequest(openPayload.channelId),
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'close',
+      txHash: `0x${'dd'.repeat(32)}`,
+      amount: closedAmount,
+      delta: closedAmount,
+    })
+  })
+
+  test('delta reflects incremental settlement when channel has prior on-chain settlement', async () => {
+    const events: { trigger: string; amount: bigint; delta: bigint }[] = []
+    const store = Store.memory()
+    const openPayload = await createOpenPayload()
+    await persistPrecompileChannel(channelStore(store), openPayload, {
+      payee: payer.address,
+      spent: 300n,
+      settledOnChain: 200n,
+      highestVoucherAmount: 300n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 300n,
+        signature: '0x1234',
+      },
+    })
+
+    const { settle } = await import('./Session.js')
+    const client = createSettleClient(openPayload.channelId, 300n)
+    await settle(store, client, openPayload.channelId, {
+      onSessionSettlement: (ctx) => {
+        events.push({ trigger: ctx.trigger, amount: ctx.amount, delta: ctx.delta })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'settle',
+      amount: 300n,
+      delta: 100n,
+    })
+  })
+
+  test('delta reflects incremental close when channel has prior on-chain settlement', async () => {
+    const events: { trigger: string; amount: bigint; delta: bigint }[] = []
+    const openPayload = await createOpenPayload()
+    const priorSettled = 50n
+    const closedAmount = 100n
+    const refundedAmount = 900n
+    const rawStore = Store.memory()
+
+    const closeClient = createClient({
+      account: payer,
+      chain: testChain,
+      transport: custom({
+        async request(args) {
+          if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
+          if (args.method === 'eth_getTransactionCount') return '0x0'
+          if (args.method === 'eth_estimateGas') return '0x5208'
+          if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+          if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+          if (args.method === 'eth_sendRawTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_sendTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_getTransactionReceipt')
+            return transactionReceipt([
+              closedLog(openPayload.channelId, closedAmount, refundedAmount),
+            ])
+          if (args.method === 'eth_call') {
+            return encodeFunctionResult({
+              abi: escrowAbi,
+              functionName: 'getChannelState',
+              result: { settled: priorSettled, deposit: 1_000n, closeRequestedAt: 0 },
+            })
+          }
+          throw new Error(`unexpected rpc request: ${args.method}`)
+        },
+      }),
+    })
+
+    const method = session({
+      amount: '1',
+      chainId,
+      currency: token,
+      decimals: 0,
+      recipient: payee,
+      store: rawStore,
+      unitType: 'request',
+      getClient: () => closeClient,
+      onSessionSettlement: (ctx) => {
+        events.push({ trigger: ctx.trigger, amount: ctx.amount, delta: ctx.delta })
+      },
+    })
+
+    await persistPrecompileChannel(channelStore(rawStore), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      settledOnChain: priorSettled,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const closeSignature = await Voucher.signVoucher(
+      createSigningClient(),
+      payer,
+      { channelId: openPayload.channelId, cumulativeAmount: 100n },
+      tip20ChannelEscrow,
+      chainId,
+    )
+
+    await method.verify({
+      credential: {
+        challenge: makeChallenge(openPayload.channelId),
+        payload: {
+          action: 'close',
+          channelId: openPayload.channelId,
+          descriptor: openPayload.descriptor,
+          cumulativeAmount: '100',
+          signature: closeSignature,
+        },
+      },
+      request: verifyRequest(openPayload.channelId),
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'close',
+      amount: closedAmount,
+      delta: closedAmount - priorSettled,
+    })
+  })
+
+  test('isolates errors in onSessionSettlement handler', async () => {
+    const store = Store.memory()
+    const openPayload = await createOpenPayload()
+    await persistPrecompileChannel(channelStore(store), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const { settle } = await import('./Session.js')
+    const client = createSettleClient(openPayload.channelId, 100n)
+
+    await expect(
+      settle(store, client, openPayload.channelId, {
+        onSessionSettlement: () => {
+          throw new Error('observer exploded')
+        },
+      }),
+    ).resolves.toBe(`0x${'cc'.repeat(32)}`)
+  })
+})