feat: support advertised tempo charge modes

.changeset/tempo-supported-modes.md

@@ -0,0 +1,5 @@
+---
+'mppx': patch
+---
+
+Add Tempo charge `supportedModes` request support so clients and servers can explicitly negotiate `push` vs `pull` settlement.

pnpm-workspace.yaml

@@ -37,6 +37,7 @@ overrides:
   elysia@<1.4.26: '1.4.26'
   file-type: '21.3.2'
   flatted@<=3.4.1: '>=3.4.2'
+  follow-redirects@<=1.15.11: '1.16.0'
   undici@>=7.0.0 <7.24.0: '7.24.0'
   socket.io-parser@>=4.0.0 <4.2.6: '>=4.2.6'
   yaml@<2.8.3: '>=2.8.3'

src/tempo/Methods.test.ts

@@ -39,6 +39,31 @@ describe('charge', () => {
     expect(result.success).toBe(true)
   })
 
+  test('schema: validates request with supportedModes', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      supportedModes: ['pull'],
+    })
+    expect(result.success).toBe(true)
+    if (!result.success) return
+
+    expect(result.data.methodDetails?.supportedModes).toEqual(['pull'])
+  })
+
+  test('schema: rejects empty supportedModes', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      supportedModes: [],
+    })
+    expect(result.success).toBe(false)
+  })
+
   test('schema: validates request with memo', () => {
     const result = Methods.charge.schema.request.safeParse({
       amount: '1',

src/tempo/Methods.ts

@@ -4,6 +4,9 @@ import { parseUnits } from 'viem'
 import * as Method from '../Method.js'
 import * as z from '../zod.js'
 
+export const chargeModes = ['push', 'pull'] as const
+export type ChargeMode = (typeof chargeModes)[number]
+
 const split = z.object({
   amount: z.amount(),
   memo: z.optional(z.hash()),
@@ -47,6 +50,7 @@ export const charge = Method.from({
           memo: z.optional(z.hash()),
           recipient: z.optional(z.string()),
           splits: z.optional(z.array(split).check(z.minLength(1), z.maxLength(10))),
+          supportedModes: z.optional(z.array(z.enum(chargeModes)).check(z.minLength(1))),
         })
         .check(
           z.refine(({ amount, decimals, splits }) => {
@@ -64,28 +68,32 @@ export const charge = Method.from({
             )
           }, 'Invalid splits'),
         ),
-      z.transform(({ amount, chainId, decimals, feePayer, memo, splits, ...rest }) => ({
-        ...rest,
-        amount: parseUnits(amount, decimals).toString(),
-        ...(chainId !== undefined ||
-        feePayer !== undefined ||
-        memo !== undefined ||
-        splits !== undefined
-          ? {
-              methodDetails: {
-                ...(chainId !== undefined && { chainId }),
-                ...(feePayer !== undefined && { feePayer }),
-                ...(memo !== undefined && { memo }),
-                ...(splits !== undefined && {
-                  splits: splits.map((split) => ({
-                    ...split,
-                    amount: parseUnits(split.amount, decimals).toString(),
-                  })),
-                }),
-              },
-            }
-          : {}),
-      })),
+      z.transform(
+        ({ amount, chainId, decimals, feePayer, memo, splits, supportedModes, ...rest }) => ({
+          ...rest,
+          amount: parseUnits(amount, decimals).toString(),
+          ...(chainId !== undefined ||
+          feePayer !== undefined ||
+          memo !== undefined ||
+          splits !== undefined ||
+          supportedModes !== undefined
+            ? {
+                methodDetails: {
+                  ...(chainId !== undefined && { chainId }),
+                  ...(feePayer !== undefined && { feePayer }),
+                  ...(memo !== undefined && { memo }),
+                  ...(splits !== undefined && {
+                    splits: splits.map((split) => ({
+                      ...split,
+                      amount: parseUnits(split.amount, decimals).toString(),
+                    })),
+                  }),
+                  ...(supportedModes !== undefined && { supportedModes }),
+                },
+              }
+            : {}),
+        }),
+      ),
     ),
   },
 })

src/tempo/client/Charge.ts

@@ -47,7 +47,7 @@ export function charge(parameters: charge.Parameters = {}) {
     context: z.object({
       account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
       autoSwap: z.optional(z.custom<charge.AutoSwap>()),
-      mode: z.optional(z.enum(['push', 'pull'])),
+      mode: z.optional(z.enum(Methods.chargeModes)),
     }),
 
     async createCredential({ challenge, context }) {
@@ -74,11 +74,7 @@ export function charge(parameters: charge.Parameters = {}) {
         })
       }
 
-      const mode =
-        context?.mode ?? parameters.mode ?? (account.type === 'json-rpc' ? 'push' : 'pull')
-
       const currency = request.currency as Address
-
       if (parameters.expectedRecipients) {
         const allowed = new Set(parameters.expectedRecipients.map((a) => a.toLowerCase()))
         const splits = methodDetails?.splits as readonly { recipient: string }[] | undefined
@@ -89,6 +85,21 @@ export function charge(parameters: charge.Parameters = {}) {
           }
         }
       }
+      const supportedModes = (methodDetails?.supportedModes as
+        | readonly Methods.ChargeMode[]
+        | undefined) ?? ['pull', 'push']
+      const mode = (() => {
+        const explicitMode = context?.mode ?? parameters.mode
+        if (explicitMode) {
+          if (!supportedModes.includes(explicitMode))
+            throw new Error(`Challenge does not support ${explicitMode} mode.`)
+          return explicitMode
+        }
+
+        const preferredMode = account.type === 'json-rpc' ? 'push' : 'pull'
+        if (supportedModes.includes(preferredMode)) return preferredMode
+        return supportedModes[0]!
+      })()
 
       const memo = methodDetails?.memo
         ? (methodDetails.memo as Hex.Hex)
@@ -193,9 +204,12 @@ export declare namespace charge {
      * - `'push'`: Client broadcasts the transaction and sends the tx hash to the server.
      * - `'pull'`: Client signs the transaction and sends the serialized tx to the server for broadcast.
      *
+     * If the server advertises `supportedModes`, this setting must be one of
+     * the supported values for the challenge.
+     *
      * @default `'push'` for JSON-RPC accounts, `'pull'` for local accounts.
      */
-    mode?: 'push' | 'pull' | undefined
+    mode?: Methods.ChargeMode | undefined
   } & Account.getResolver.Parameters &
     Client.getResolver.Parameters
 }