mppx 0.8.14 → 0.8.17

package/src/tempo/server/Methods.ts

@@ -1,5 +1,4 @@
 import type { NoExtraKeys } from '../../internal/types.js'
-import { session as sessionLegacy_, settle as settleLegacy_ } from '../legacy/server/index.js'
 import {
   charge as sessionCharge_,
   session as session_,
@@ -18,23 +17,6 @@ const sessionServer = Object.assign(session_, {
   settleBatch: settleBatch_,
 })
 
-function createSessionLegacyMethod<
-  const parameters extends NonNullable<Parameters<typeof sessionLegacy_>[0]>,
->(parameters?: parameters) {
-  return Object.assign(sessionLegacy_(parameters as never), { alias: 'sessionLegacy' as const })
-}
-
-const sessionLegacyServer = Object.assign(createSessionLegacyMethod, {
-  settle: settleLegacy_,
-  Ws: Ws_,
-})
-
-/** Creates a legacy contract-backed Tempo `session` server method. */
-export const sessionLegacy = sessionLegacyServer
-
-/** Settles a legacy contract-backed Tempo session channel. */
-export const settleLegacy = settleLegacy_
-
 function createChargeMethod<const parameters extends tempo.Parameters>(
   parameters: parameters | undefined,
 ) {
@@ -86,8 +68,6 @@ export namespace tempo {
   export const common = tempo
   /** Creates a TIP-1034 Tempo `session` method for session-based TIP-20 token payments. */
   export const session = sessionServer
-  /** @deprecated Use `tempo.session()` for the TIP-1034 session server method. */
-  export const sessionLegacy = sessionLegacyServer
   /** Creates a Tempo `subscription` method for recurring TIP-20 token payments. */
   export const subscription = subscription_
   /** Renews an overdue Tempo subscription outside of the HTTP request path. */

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

@@ -4,6 +4,8 @@ import * as Http from '~test/Http.js'
 
 import * as Challenge from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
+import * as Method from '../../Method.js'
+import * as Receipt from '../../Receipt.js'
 import * as Mppx from '../../server/Mppx.js'
 import { tempo } from './Methods.js'
 
@@ -23,6 +25,11 @@ const credential = {
   source: 'did:pkh:eip155:42431:0x123',
 } as const
 
+const pushedPayload = {
+  hash: '0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890',
+  type: 'hash',
+} as const
+
 type RelayHandler = (url: URL, init: RequestInit) => Response | Promise<Response>
 
 function mockRelay(handler: RelayHandler): typeof globalThis.fetch {
@@ -52,7 +59,10 @@ function successReceipt() {
   })
 }
 
-async function createPaymentServer(fetch: typeof globalThis.fetch) {
+async function createPaymentServer(
+  fetch: typeof globalThis.fetch,
+  payload: typeof credential.payload | typeof pushedPayload = credential.payload,
+) {
   const [method] = methods(fetch, apiBaseUrl)
   const mppx = Mppx.create({ methods: [method], realm, secretKey })
   const handle = mppx.tempo.charge({ amount: '1', decimals: 6 })
@@ -65,7 +75,7 @@ async function createPaymentServer(fetch: typeof globalThis.fetch) {
   const challenge = Challenge.fromResponse(challengeResponse)
   const paymentCredential = Credential.from({
     challenge,
-    payload: credential.payload,
+    payload,
     source: credential.source,
   })
 
@@ -186,7 +196,7 @@ describe('relay boundary', () => {
           headers: expect.objectContaining({
             Accept: 'application/json',
             'content-type': 'application/json',
-            'idempotency-key': expect.stringMatching(/^mppx_0x/),
+            'idempotency-key': expect.stringMatching(/^mpp_0x/),
             'tempo-api-key': 'tempo_api_key',
           }),
           method: 'POST',
@@ -196,6 +206,65 @@ describe('relay boundary', () => {
     ])
   })
 
+  test('delegates pushed transaction finalization to the relay', async () => {
+    const calls: Array<{ init: RequestInit; url: URL }> = []
+    const fetch = mockRelay((url, init) => {
+      calls.push({ init, url })
+      return url.pathname === '/v1/mpp/validate'
+        ? Response.json({ success: true })
+        : successReceipt()
+    })
+    const [method] = methods(fetch)
+    const pushedCredential = { ...credential, payload: pushedPayload }
+
+    await expect(
+      method.verify({
+        credential: pushedCredential,
+        request: credential.challenge.request,
+      } as never),
+    ).resolves.toMatchObject({
+      method: 'tempo',
+      reference: '0xabc',
+      status: 'success',
+    })
+    expect(calls).toEqual([
+      expect.objectContaining({ url: new URL(`${apiBaseUrl}/v1/mpp/validate`) }),
+      expect.objectContaining({
+        init: expect.objectContaining({ body: JSON.stringify(pushedCredential) }),
+        url: new URL(`${apiBaseUrl}/v1/mpp/broadcast`),
+      }),
+    ])
+  })
+
+  test('validates a pushed transaction before returning its receipt', async () => {
+    const calls: string[] = []
+    const fetch = mockRelay((url) => {
+      calls.push(url.pathname)
+      return url.pathname === '/v1/mpp/validate'
+        ? Response.json({ success: true })
+        : successReceipt()
+    })
+    const [method] = methods(fetch)
+    const pushedCredential = {
+      ...credential,
+      challenge: {
+        ...credential.challenge,
+        expires: new Date(Date.now() + 60_000).toISOString(),
+      },
+      payload: pushedPayload,
+    }
+
+    await expect(
+      Method.broadcastCredential([method], pushedCredential as never),
+    ).resolves.toMatchObject({
+      method: 'tempo',
+      reference: '0xabc',
+      status: 'success',
+    })
+
+    expect(calls).toEqual(['/v1/mpp/validate', '/v1/mpp/broadcast'])
+  })
+
   test('uses the transaction hash as the transaction broadcast idempotency key', async () => {
     const calls: RequestInit[] = []
     const fetch = mockRelay((_url, init) => {
@@ -213,9 +282,9 @@ describe('relay boundary', () => {
 
     const keys = calls.map((init) => (init.headers as Record<string, string>)['idempotency-key'])
     expect(keys).toEqual([
-      `mppx_${Hash.keccak256(Hex.toBytes(credential.payload.signature), { as: 'Hex' })}`,
-      `mppx_${Hash.keccak256(Hex.toBytes(credential.payload.signature), { as: 'Hex' })}`,
-      `mppx_${Hash.keccak256(Hex.toBytes('0x5678'), { as: 'Hex' })}`,
+      `mpp_${Hash.keccak256(Hex.toBytes(credential.payload.signature), { as: 'Hex' })}`,
+      `mpp_${Hash.keccak256(Hex.toBytes(credential.payload.signature), { as: 'Hex' })}`,
+      `mpp_${Hash.keccak256(Hex.toBytes('0x5678'), { as: 'Hex' })}`,
     ])
   })
 
@@ -247,7 +316,7 @@ describe('relay boundary', () => {
       ),
       { as: 'Hex' },
     )
-    expect(headers['idempotency-key']).toBe(`mppx_${expected}`)
+    expect(headers['idempotency-key']).toBe(`mpp_${expected}`)
   })
 
   test('preserves the legacy combined verify hook', async () => {
@@ -433,6 +502,91 @@ describe('relay HTTP flow', () => {
     }
   })
 
+  test('delegates pushed transaction finalization to the relay', async () => {
+    const calls: string[] = []
+    const fetch = mockRelay((url) => {
+      calls.push(url.pathname)
+      return url.pathname === '/v1/mpp/validate'
+        ? Response.json({ success: true })
+        : successReceipt()
+    })
+    const { pay, server } = await createPaymentServer(fetch, pushedPayload)
+
+    try {
+      const response = await pay()
+
+      expect(response.status).toBe(200)
+      expect(Receipt.fromResponse(response)).toMatchObject({
+        method: 'tempo',
+        reference: '0xabc',
+        status: 'success',
+      })
+      expect(calls).toEqual(['/v1/mpp/validate', '/v1/mpp/broadcast'])
+    } finally {
+      server.close()
+    }
+  })
+
+  test('does not issue a receipt when relay validation rejects a pushed transaction', async () => {
+    const calls: string[] = []
+    const fetch = mockRelay((url) => {
+      calls.push(url.pathname)
+      return Response.json({
+        error: { code: 'policy_denied', message: 'private detail' },
+        success: false,
+      })
+    })
+    const { pay, server } = await createPaymentServer(fetch, pushedPayload)
+
+    try {
+      const response = await pay()
+      const body = (await response.json()) as Record<string, unknown>
+
+      expect(response.status).toBe(402)
+      expect(response.headers.get('Payment-Receipt')).toBeNull()
+      expect(body).toMatchObject({
+        detail: 'Payment verification failed.',
+        type: 'https://paymentauth.org/problems/verification-failed',
+      })
+      expect(JSON.stringify(body)).not.toContain('policy_denied')
+      expect(JSON.stringify(body)).not.toContain('private detail')
+      expect(calls).toEqual(['/v1/mpp/validate'])
+    } finally {
+      server.close()
+    }
+  })
+
+  test('does not issue a receipt when relay finalization rejects a pushed transaction', async () => {
+    const calls: string[] = []
+    const fetch = mockRelay((url) => {
+      calls.push(url.pathname)
+      return url.pathname === '/v1/mpp/validate'
+        ? Response.json({ success: true })
+        : Response.json({
+            error: { code: 'already_used', message: 'private detail' },
+            success: false,
+          })
+    })
+    const { pay, server } = await createPaymentServer(fetch, pushedPayload)
+
+    try {
+      const response = await pay()
+      const body = (await response.json()) as Record<string, unknown>
+
+      expect(response.status).toBe(402)
+      expect(response.headers.get('Payment-Receipt')).toBeNull()
+      expect(body).toMatchObject({
+        detail: 'Payment verification failed.',
+        details: { code: 'already_used' },
+        type: 'https://paymentauth.org/problems/verification-failed',
+      })
+      expect(JSON.stringify(body)).not.toContain('private detail')
+      expect(calls).toEqual(['/v1/mpp/validate', '/v1/mpp/broadcast'])
+    } finally {
+      server.close()
+    }
+  })
+
   test.each([
     ['validation network failure', () => Promise.reject(new TypeError('tempo api unavailable')), 1],
     [

package/src/tempo/server/Relay.ts

@@ -64,8 +64,10 @@ type BroadcastResponse =
  * Configures a Tempo payment method to use Tempo API's MPP relay.
  *
  * The adapter preserves the supplied method's challenge configuration while
- * delegating credential validation and terminal broadcast to
- * `/v1/mpp/validate` and `/v1/mpp/broadcast` respectively.
+ * delegating validation and finalization to `/v1/mpp/validate` and
+ * `/v1/mpp/broadcast`. The relay receives every submitted credential: it
+ * broadcasts pull transactions and finalizes push transaction hashes without
+ * sending them again.
  *
  * @internal
  */
@@ -127,13 +129,20 @@ export declare namespace configure {
     Method.Server<intent>,
     'broadcast' | 'validate'
   > & {
-    /** Broadcasts the credential through Tempo API. */
+    /** Delegates payment finalization to Tempo API's relay. */
     broadcast: Method.BroadcastFn<intent>
     /** Validates the credential through Tempo API. */
     validate: Method.ValidateFn<intent>
   }
 
-  /** Tempo API relay configuration for server-side Tempo charges. */
+  /**
+   * Tempo API relay configuration for server-side Tempo charges.
+   *
+   * The adapter sends every credential to the relay for finalization. The
+   * relay broadcasts pull credentials, while it recognizes a push credential
+   * as an already-broadcast transaction and returns its receipt without
+   * sending it again.
+   */
   type Options = {
     /** Tempo API key with the `mpp:write` scope. */
     apiKey: string
@@ -223,11 +232,11 @@ function idempotencyKey(input: RelayInput): string {
     Hex.validate(payload.signature)
   ) {
     const transactionHash = Hash.keccak256(Hex.toBytes(payload.signature), { as: 'Hex' })
-    return `mppx_${transactionHash}`
+    return `mpp_${transactionHash}`
   }
 
   const hash = Hash.sha256(Bytes.fromString(Json.canonicalize(input)), { as: 'Hex' })
-  return `mppx_${hash}`
+  return `mpp_${hash}`
 }
 
 function failure(value?: unknown) {

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

@@ -74,6 +74,35 @@ describe('SponsorBudget', () => {
     expect(Object.keys(state!.reservations)).toEqual([hash2])
   })
 
+  test('does not reconcile a broadcasting reservation before its owner publishes pending', async () => {
+    const store = memoryStore()
+    const getReceipt = async (hash: Hex) => {
+      if (hash === hash1) return {}
+      throw new Error('not found')
+    }
+    const first = await SponsorBudget.reserve(store, parameters({ getReceipt }))
+    expect(await SponsorBudget.transition(store, first, 'broadcasting')).toBe(true)
+
+    const second = SponsorBudget.reserve(
+      store,
+      parameters({
+        getReceipt,
+        id: hash2,
+        owner: 'worker-2',
+        transactionHash: hash2,
+      }),
+    )
+    expect(
+      await Promise.race([
+        second.then(() => 'reserved' as const),
+        new Promise<'waiting'>((resolve) => setTimeout(() => resolve('waiting'), 40)),
+      ]),
+    ).toBe('waiting')
+
+    expect(await SponsorBudget.transition(store, first, 'pending')).toBe(true)
+    await expect(second).resolves.toMatchObject({ id: hash2, owner: 'worker-2' })
+  })
+
   test('fences release and transition by reservation owner', async () => {
     const store = memoryStore()
     const handle = await SponsorBudget.reserve(store, parameters())

package/src/tempo/server/SponsorBudget.ts

@@ -99,7 +99,13 @@ async function reconcile(
         await release(store, handle)
         return
       }
-      if (reservation.phase === 'prepared') return
+      // The broadcasting owner has submitted (or is about to submit) the
+      // transaction but has not yet published that outcome to this store.
+      // Releasing its reservation here races the owner's transition to
+      // `pending`: the transaction can settle while the owner observes a lost
+      // reservation and reports a retryable payment failure. Only reconcile
+      // receipts after the owner has completed that hand-off.
+      if (reservation.phase !== 'pending') return
 
       try {
         await parameters.getReceipt(reservation.transactionHash)

package/src/tempo/server/Subscription.ts

@@ -94,6 +94,8 @@ export function subscription<const parameters extends subscription.Parameters>(
     undefined,
     subscription.Extensions
   >(Methods.subscription, {
+    canOffer: parameters.canOffer,
+    onPaymentSuccess: parameters.onPaymentSuccess,
     defaults: {
       amount,
       currency,
@@ -1281,7 +1283,8 @@ export declare namespace subscription {
       storeKeyPrefix?: string | undefined
       testnet?: boolean | undefined
       waitForConfirmation?: boolean | undefined
-    } & Defaults
+    } & Defaults &
+    Method.ComposableHooks<typeof Methods.subscription>
 
   /** Derived defaults after account and chain configuration are applied. */
   type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<

package/src/tempo/server/index.ts

@@ -2,7 +2,7 @@ export * as ChannelStore from '../session/server/ChannelStore.js'
 export * as Sse from '../session/server/Sse.js'
 export * as Ws from '../session/server/Ws.js'
 export { charge } from './Charge.js'
-export { sessionLegacy, settleLegacy, tempo } from './Methods.js'
+export { tempo } from './Methods.js'
 export { session, settle, settleBatch } from '../session/server/Session.js'
 export type {
   OnSessionSettlement,

package/src/tempo/server/internal/html/node_modules/.bin/mppx

@@ -15,8 +15,8 @@ else
   export NODE_PATH="/home/runner/work/mppx/mppx/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../mppx/dist/bin.js" "$@"
+  exec "$basedir/node"  "$basedir/../mppx/src/bin.js" "$@"
 else
-  exec node  "$basedir/../mppx/dist/bin.js" "$@"
+  exec node  "$basedir/../mppx/src/bin.js" "$@"
 fi
-# cmd-shim-target=/home/runner/work/mppx/mppx/src/tempo/server/internal/html/node_modules/mppx/dist/bin.js
+# cmd-shim-target=/home/runner/work/mppx/mppx/src/tempo/server/internal/html/node_modules/mppx/src/bin.js

package/src/tempo/server/internal/html/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "accounts": "0.14.11",
+    "accounts": "0.16.0",
     "mppx": "workspace:*",
     "viem": "2.54.4"
   }