mppx 0.4.10 → 0.4.12

package/src/tempo/Methods.ts

@@ -1,9 +1,18 @@
-import type { Account } from 'viem'
+import type { Account, Address } from 'viem'
 import { parseUnits } from 'viem'
 
 import * as Method from '../Method.js'
 import * as z from '../zod.js'
 
+const split = z.object({
+  amount: z.amount(),
+  memo: z.optional(z.hash()),
+  recipient: z.pipe(
+    z.string(),
+    z.transform((v) => v as Address),
+  ),
+})
+
 /**
  * Tempo charge intent for one-time TIP-20 token transfers.
  *
@@ -20,31 +29,58 @@ export const charge = Method.from({
       ]),
     },
     request: z.pipe(
-      z.object({
-        amount: z.amount(),
-        chainId: z.optional(z.number()),
-        currency: z.string(),
-        decimals: z.number(),
-        description: z.optional(z.string()),
-        externalId: z.optional(z.string()),
-        feePayer: z.optional(
-          z.pipe(
-            z.union([z.boolean(), z.custom<Account>()]),
-            z.transform((v): boolean => (typeof v === 'object' ? true : v)),
+      z
+        .object({
+          amount: z.amount(),
+          chainId: z.optional(z.number()),
+          currency: z.string(),
+          decimals: z.number(),
+          description: z.optional(z.string()),
+          externalId: z.optional(z.string()),
+          feePayer: z.optional(
+            z.pipe(
+              z.union([z.boolean(), z.custom<Account>()]),
+              z.transform((v): boolean => (typeof v === 'object' ? true : v)),
+            ),
           ),
+          memo: z.optional(z.hash()),
+          recipient: z.optional(z.string()),
+          splits: z.optional(z.array(split).check(z.minLength(1), z.maxLength(10))),
+        })
+        .check(
+          z.refine(({ amount, decimals, splits }) => {
+            if (!splits) return true
+
+            const totalAmount = parseUnits(amount, decimals)
+            const splitTotal = splits.reduce(
+              (sum, split) => sum + parseUnits(split.amount, decimals),
+              0n,
+            )
+
+            return (
+              splits.every((split) => parseUnits(split.amount, decimals) > 0n) &&
+              splitTotal < totalAmount
+            )
+          }, 'Invalid splits'),
         ),
-        memo: z.optional(z.hash()),
-        recipient: z.optional(z.string()),
-      }),
-      z.transform(({ amount, chainId, decimals, feePayer, memo, ...rest }) => ({
+      z.transform(({ amount, chainId, decimals, feePayer, memo, splits, ...rest }) => ({
         ...rest,
         amount: parseUnits(amount, decimals).toString(),
-        ...(chainId !== undefined || feePayer !== undefined || memo !== undefined
+        ...(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(),
+                  })),
+                }),
               },
             }
           : {}),

package/src/tempo/client/Charge.ts

@@ -11,6 +11,7 @@ import * as Client from '../../viem/Client.js'
 import * as z from '../../zod.js'
 import * as Attribution from '../Attribution.js'
 import * as AutoSwap from '../internal/auto-swap.js'
+import * as Charge_internal from '../internal/charge.js'
 import * as defaults from '../internal/defaults.js'
 import * as Methods from '../Methods.js'
 
@@ -54,18 +55,37 @@ export function charge(parameters: charge.Parameters = {}) {
       const { request } = challenge
       const { amount, methodDetails } = request
       const currency = request.currency as Address
-      const recipient = request.recipient as Address
+
+      if (parameters.expectedRecipients) {
+        const allowed = new Set(parameters.expectedRecipients.map((a) => a.toLowerCase()))
+        const splits = methodDetails?.splits as readonly { recipient: string }[] | undefined
+        if (splits) {
+          for (const split of splits) {
+            if (!allowed.has(split.recipient.toLowerCase()))
+              throw new Error(`Unexpected split recipient: ${split.recipient}`)
+          }
+        }
+      }
 
       const memo = methodDetails?.memo
         ? (methodDetails.memo as Hex.Hex)
         : Attribution.encode({ serverId: challenge.realm, clientId })
-
-      const transferCall = Actions.token.transfer.call({
-        amount: BigInt(amount),
-        memo,
-        to: recipient,
-        token: currency,
+      const transfers = Charge_internal.getTransfers({
+        amount,
+        methodDetails: {
+          ...methodDetails,
+          memo,
+        },
+        recipient: request.recipient as Address,
       })
+      const transferCalls = transfers.map((transfer) =>
+        Actions.token.transfer.call({
+          amount: BigInt(transfer.amount),
+          ...(transfer.memo && { memo: transfer.memo as Hex.Hex }),
+          to: transfer.recipient as Address,
+          token: currency,
+        }),
+      )
 
       const autoSwap = AutoSwap.resolve(
         context?.autoSwap ?? parameters.autoSwap,
@@ -82,7 +102,14 @@ export function charge(parameters: charge.Parameters = {}) {
           })
         : undefined
 
-      const calls = [...(swapCalls ?? []), transferCall]
+      const calls = [...(swapCalls ?? []), ...transferCalls]
+
+      const validBefore = (() => {
+        const defaultExpiry = Math.floor(Date.now() / 1000) + 25
+        if (!challenge.expires) return defaultExpiry
+        const challengeExpiry = Math.floor(new Date(challenge.expires).getTime() / 1000)
+        return Math.min(defaultExpiry, challengeExpiry)
+      })()
 
       if (mode === 'push') {
         const { receipts } = await sendCallsSync(client, {
@@ -104,6 +131,7 @@ export function charge(parameters: charge.Parameters = {}) {
         calls,
         ...(methodDetails?.feePayer && { feePayer: true }),
         nonceKey: 'expiring',
+        validBefore,
       } as never)
       // FIXME: figure out gas estimation issue for fee payer tx
       prepared.gas = prepared.gas! + 5_000n
@@ -131,6 +159,11 @@ export declare namespace charge {
     autoSwap?: AutoSwap | undefined
     /** Client identifier used to derive the client fingerprint in attribution memos. */
     clientId?: string | undefined
+    /**
+     * Allowlist of expected split recipient addresses. When set, the client
+     * rejects any challenge whose split recipients are not in this list.
+     */
+    expectedRecipients?: readonly Address[] | undefined
     /**
      * Controls how the charge transaction is submitted.
      *

package/src/tempo/internal/account.ts

@@ -33,18 +33,11 @@ export function resolve(parameters: resolve.Parameters) {
 }
 
 export declare namespace resolve {
-  type Parameters = { recipient?: Address | undefined } & (
-    | {
-        /** Account that performs payment operations. */
-        account?: Account | undefined
-        /** When true, the account also sponsors (pays) transaction fees. */
-        feePayer?: true | undefined
-      }
-    | {
-        /** Address that receives payment. */
-        account?: Address | undefined
-        /** Optional fee payer account or fee payer URL for covering transaction fees. */
-        feePayer?: Account | string | undefined
-      }
-  )
+  type Parameters = {
+    recipient?: Address | undefined
+    /** Account or address that performs payment operations / receives payment. */
+    account?: Account | Address | undefined
+    /** When `true`, the account also sponsors fees. An `Account` object or URL string can also be provided as a dedicated fee payer. */
+    feePayer?: Account | string | true | undefined
+  }
 }

package/src/tempo/internal/charge.ts

@@ -0,0 +1,43 @@
+import type { Address } from 'viem'
+
+export type Split = {
+  amount: string
+  memo?: string | undefined
+  recipient: Address
+}
+
+export type Transfer = {
+  amount: string
+  memo?: string | undefined
+  recipient: Address
+}
+
+export function getTransfers(request: {
+  amount: string
+  methodDetails?: { memo?: string | undefined; splits?: readonly Split[] | undefined }
+  recipient: Address
+}): Transfer[] {
+  const totalAmount = BigInt(request.amount)
+  const splits = request.methodDetails?.splits ?? []
+
+  const splitTotal = splits.reduce((sum, split) => sum + BigInt(split.amount), 0n)
+  if (splitTotal >= totalAmount)
+    throw new Error('Invalid charge request: split total must be less than total amount.')
+
+  const primaryAmount = totalAmount - splitTotal
+  if (primaryAmount <= 0n)
+    throw new Error('Invalid charge request: primary transfer amount must be positive.')
+
+  return [
+    {
+      amount: primaryAmount.toString(),
+      memo: request.methodDetails?.memo,
+      recipient: request.recipient,
+    },
+    ...splits.map((split) => ({
+      amount: split.amount,
+      memo: split.memo,
+      recipient: split.recipient,
+    })),
+  ]
+}

package/src/tempo/internal/fee-payer.test.ts

@@ -70,17 +70,7 @@ describe('validateCalls', () => {
     ).not.toThrow()
   })
 
-  test('error: rejects empty calls', () => {
-    expect(() => validateCalls([], details)).toThrow(FeePayerValidationError)
-  })
-
-  test('error: rejects unknown selector', () => {
-    expect(() => validateCalls([{ data: '0xdeadbeef' as `0x${string}` }], details)).toThrow(
-      'disallowed call pattern',
-    )
-  })
-
-  test('error: rejects extra calls beyond allowed patterns', () => {
+  test('accepts multiple transfers after swap prefix', () => {
     const swapSelector = Selectors.swapExactAmountOut
     expect(() =>
       validateCalls(
@@ -100,19 +90,48 @@ describe('validateCalls', () => {
             data: encodeFunctionData({
               abi: Abis.tip20,
               functionName: 'transfer',
-              args: [bogus, 100n],
+              args: [bogus, 90n],
             }),
           },
           {
             data: encodeFunctionData({
               abi: Abis.tip20,
-              functionName: 'transfer',
-              args: [bogus, 100n],
+              functionName: 'transferWithMemo',
+              args: [
+                '0x0000000000000000000000000000000000000002',
+                10n,
+                '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+              ],
             }),
           },
         ],
         details,
       ),
+    ).not.toThrow()
+  })
+
+  test('error: rejects empty calls', () => {
+    expect(() => validateCalls([], details)).toThrow(FeePayerValidationError)
+  })
+
+  test('error: rejects unknown selector', () => {
+    expect(() => validateCalls([{ data: '0xdeadbeef' as `0x${string}` }], details)).toThrow(
+      'disallowed call pattern',
+    )
+  })
+
+  test('error: rejects more than 11 transfers', () => {
+    expect(() =>
+      validateCalls(
+        Array.from({ length: 12 }, (_, index) => ({
+          data: encodeFunctionData({
+            abi: Abis.tip20,
+            functionName: 'transfer',
+            args: [`0x${(index + 1).toString(16).padStart(40, '0')}`, 100n],
+          }),
+        })),
+        details,
+      ),
     ).toThrow('disallowed call pattern')
   })
 

package/src/tempo/internal/fee-payer.ts

@@ -30,14 +30,29 @@ export function validateCalls(
   calls: readonly { data?: `0x${string}` | undefined; to?: TempoAddress.Address | undefined }[],
   details: Record<string, string>,
 ) {
+  if (calls.length === 0)
+    throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
+
   const callSelectors = calls.map((c) => c.data?.slice(0, 10))
-  const allowed = callScopes.some(
-    (pattern) =>
-      pattern.length === callSelectors.length &&
-      pattern.every((sel, i) => sel === callSelectors[i]),
-  )
-  if (!allowed)
+  const hasSwapPrefix = callSelectors[0] === Selectors.approve
+
+  if (hasSwapPrefix) {
+    if (callSelectors[1] !== Selectors.swapExactAmountOut)
+      throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
+  } else if (callSelectors[0] === Selectors.swapExactAmountOut) {
+    throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
+  }
+
+  const transferSelectors = callSelectors.slice(hasSwapPrefix ? 2 : 0)
+  if (
+    transferSelectors.length === 0 ||
+    transferSelectors.length > 11 ||
+    transferSelectors.some(
+      (selector) => selector !== Selectors.transfer && selector !== Selectors.transferWithMemo,
+    )
+  ) {
     throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
+  }
 
   // Validate approve spender and buy target are the DEX.
   const approveCall = calls.find((c) => c.data?.slice(0, 10) === Selectors.approve)

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

@@ -650,6 +650,107 @@ describe('tempo', () => {
       httpServer.close()
     })
 
+    test('behavior: accepts split payments', async () => {
+      const mppx = Mppx_client.create({
+        polyfill: false,
+        methods: [
+          tempo_client({
+            account: accounts[1],
+            getClient: () => client,
+          }),
+        ],
+      })
+
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          server.charge({
+            amount: '1',
+            currency: asset,
+            recipient: accounts[0].address,
+            splits: [
+              { amount: '0.2', recipient: accounts[2].address },
+              {
+                amount: '0.1',
+                memo: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+                recipient: accounts[3].address,
+              },
+            ],
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await mppx.fetch(httpServer.url)
+      expect(response.status).toBe(200)
+
+      httpServer.close()
+    })
+
+    test('behavior: accepts transaction when split transfers are out of order', async () => {
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          server.charge({
+            amount: '1',
+            currency: asset,
+            recipient: accounts[0].address,
+            splits: [
+              { amount: '0.2', recipient: accounts[2].address },
+              { amount: '0.1', recipient: accounts[3].address },
+            ],
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await fetch(httpServer.url)
+      expect(response.status).toBe(402)
+
+      const challenge = Challenge.fromResponse(response, {
+        methods: [tempo_client.charge()],
+      })
+      const splits = challenge.request.methodDetails?.splits ?? []
+      const primaryAmount =
+        BigInt(challenge.request.amount) - BigInt(splits[0]!.amount) - BigInt(splits[1]!.amount)
+
+      const prepared = await prepareTransactionRequest(client, {
+        account: accounts[1]!,
+        calls: [
+          Actions.token.transfer.call({
+            amount: BigInt(splits[1]!.amount),
+            to: splits[1]!.recipient as Hex.Hex,
+            token: challenge.request.currency as Hex.Hex,
+          }),
+          Actions.token.transfer.call({
+            amount: primaryAmount,
+            to: challenge.request.recipient as Hex.Hex,
+            token: challenge.request.currency as Hex.Hex,
+          }),
+          Actions.token.transfer.call({
+            amount: BigInt(splits[0]!.amount),
+            to: splits[0]!.recipient as Hex.Hex,
+            token: challenge.request.currency as Hex.Hex,
+          }),
+        ],
+        nonceKey: 'expiring',
+      } as never)
+      prepared.gas = prepared.gas! + 5_000n
+      const signature = await signTransaction(client, prepared as never)
+
+      const credential = Credential.from({
+        challenge,
+        payload: { signature, type: 'transaction' as const },
+      })
+
+      const authResponse = await fetch(httpServer.url, {
+        headers: { Authorization: Credential.serialize(credential) },
+      })
+      expect(authResponse.status).toBe(200)
+
+      httpServer.close()
+    })
+
     test('behavior: rejects expired request', async () => {
       const httpServer = await Http.createServer(async (req, res) => {
         const result = await Mppx_server.toNodeListener(
@@ -1156,6 +1257,39 @@ describe('tempo', () => {
       httpServer.close()
     })
 
+    test('behavior: fee payer with splits', async () => {
+      const mppx = Mppx_client.create({
+        polyfill: false,
+        methods: [
+          tempo_client({
+            account: accounts[1],
+            getClient() {
+              return client
+            },
+          }),
+        ],
+      })
+
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          server.charge({
+            feePayer: accounts[0],
+            amount: '1',
+            currency: asset,
+            recipient: accounts[0].address,
+            splits: [{ amount: '0.2', recipient: accounts[2].address }],
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await mppx.fetch(httpServer.url)
+      expect(response.status).toBe(200)
+
+      httpServer.close()
+    })
+
     test('behavior: fee payer (hoisted)', async () => {
       const mppx = Mppx_client.create({
         polyfill: false,
@@ -1658,6 +1792,70 @@ describe('tempo', () => {
 
       httpServer.close()
     })
+
+    test('behavior: accepts split transaction when transfers are out of order', async () => {
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          server.charge({
+            amount: '1',
+            currency: asset,
+            recipient: accounts[0].address,
+            splits: [
+              { amount: '0.2', recipient: accounts[2].address },
+              { amount: '0.1', recipient: accounts[3].address },
+            ],
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await fetch(httpServer.url)
+      expect(response.status).toBe(402)
+
+      const challenge = Challenge.fromResponse(response, {
+        methods: [tempo_client.charge()],
+      })
+      const splits = challenge.request.methodDetails?.splits ?? []
+      const primaryAmount =
+        BigInt(challenge.request.amount) - BigInt(splits[0]!.amount) - BigInt(splits[1]!.amount)
+
+      const prepared = await prepareTransactionRequest(client, {
+        account: accounts[1]!,
+        calls: [
+          Actions.token.transfer.call({
+            amount: BigInt(splits[0]!.amount),
+            to: splits[0]!.recipient as Hex.Hex,
+            token: challenge.request.currency as Hex.Hex,
+          }),
+          Actions.token.transfer.call({
+            amount: primaryAmount,
+            to: challenge.request.recipient as Hex.Hex,
+            token: challenge.request.currency as Hex.Hex,
+          }),
+          Actions.token.transfer.call({
+            amount: BigInt(splits[1]!.amount),
+            to: splits[1]!.recipient as Hex.Hex,
+            token: challenge.request.currency as Hex.Hex,
+          }),
+        ],
+        nonceKey: 'expiring',
+      } as never)
+      prepared.gas = prepared.gas! + 5_000n
+      const signature = await signTransaction(client, prepared as never)
+
+      const credential = Credential.from({
+        challenge,
+        payload: { signature, type: 'transaction' as const },
+      })
+
+      const authResponse = await fetch(httpServer.url, {
+        headers: { Authorization: Credential.serialize(credential) },
+      })
+      expect(authResponse.status).toBe(200)
+
+      httpServer.close()
+    })
   })
 
   describe('intent: charge; type: transaction; waitForConfirmation: false', () => {
@@ -2295,6 +2493,39 @@ describe('tempo', () => {
       httpServer.close()
     })
 
+    test('swaps via DEX when user lacks target currency for split payments', async () => {
+      const mppx = Mppx_client.create({
+        polyfill: false,
+        methods: [
+          tempo_client({
+            account: swapPayer,
+            autoSwap: true,
+            getClient() {
+              return client
+            },
+          }),
+        ],
+      })
+
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          server.charge({
+            amount: '1',
+            currency: asset,
+            recipient: accounts[0]!.address,
+            splits: [{ amount: '0.2', recipient: accounts[2]!.address }],
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await mppx.fetch(httpServer.url)
+      expect(response.status).toBe(200)
+
+      httpServer.close()
+    })
+
     test('custom slippage and tokenIn', async () => {
       const mppx = Mppx_client.create({
         polyfill: false,