mppx 0.3.11 → 0.3.12

package/src/tempo/internal/auto-swap.test.ts

@@ -0,0 +1,113 @@
+import type { Address } from 'viem'
+import { describe, expect, test } from 'vitest'
+import { defaultCurrencies, InsufficientFundsError, resolve } from './auto-swap.js'
+
+describe('defaultCurrencies', () => {
+  test('default', () => {
+    expect(defaultCurrencies).toMatchInlineSnapshot(`
+      [
+        "0x20c0000000000000000000000000000000000000",
+        "0x20C000000000000000000000b9537d11c60E8b50",
+      ]
+    `)
+  })
+})
+
+describe('resolve', () => {
+  const defaults = defaultCurrencies
+
+  test('returns false for undefined', () => {
+    expect(resolve(undefined, defaults)).toMatchInlineSnapshot(`false`)
+  })
+
+  test('returns false for false', () => {
+    expect(resolve(false, defaults)).toMatchInlineSnapshot(`false`)
+  })
+
+  test('true resolves to defaults with 1% slippage', () => {
+    expect(resolve(true, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('empty options resolves to defaults with 1% slippage', () => {
+    expect(resolve({}, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom slippage', () => {
+    expect(resolve({ slippage: 5 }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 5,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn prepends to defaults', () => {
+    const custom = '0x0000000000000000000000000000000000000099' as Address
+    expect(resolve({ tokenIn: [custom] }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x0000000000000000000000000000000000000099",
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn deduplicates against defaults', () => {
+    expect(resolve({ tokenIn: [defaults[0]!] }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn + custom slippage', () => {
+    const custom = '0x0000000000000000000000000000000000000099' as Address
+    expect(resolve({ tokenIn: [custom], slippage: 3 }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 3,
+        "tokenIn": [
+          "0x0000000000000000000000000000000000000099",
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+})
+
+describe('InsufficientFundsError', () => {
+  test('default', () => {
+    const error = new InsufficientFundsError({
+      currency: '0x0000000000000000000000000000000000000001',
+    })
+    expect(error).toMatchInlineSnapshot(
+      `[InsufficientFundsError: Insufficient funds: no balance in 0x0000000000000000000000000000000000000001 and no viable swap route from fallback currencies.]`,
+    )
+  })
+})

package/src/tempo/internal/auto-swap.ts

@@ -0,0 +1,141 @@
+import type { Address, Client } from 'viem'
+import { isAddressEqual } from 'viem'
+import { readContract } from 'viem/actions'
+import { Actions, Addresses } from 'viem/tempo'
+import * as defaults from './defaults.js'
+
+/** Basis-point denominator (100% = 10 000 bps). */
+const bps = 10_000n
+
+/** Default fallback currencies for auto-swap, in priority order. */
+export const defaultCurrencies: readonly Address[] = [
+  defaults.tokens.pathUsd as Address,
+  defaults.tokens.usdc as Address,
+]
+
+/**
+ * Finds the optimal swap calls to acquire `amountOut` of `tokenOut`,
+ * returning an approve + buy call sequence if a viable route is found.
+ *
+ * Returns `undefined` if the account already holds enough of `tokenOut`
+ * or no viable swap route exists from the given input tokens.
+ */
+export async function findCalls(
+  client: Client,
+  parameters: findCalls.Parameters,
+): Promise<findCalls.ReturnType> {
+  const { account, amountOut, tokenOut, tokenIn, slippage } = parameters
+
+  const candidates = tokenIn.filter((t) => !isAddressEqual(t, tokenOut))
+
+  const balanceResults = await Promise.allSettled([
+    readContract(client, Actions.token.getBalance.call({ account, token: tokenOut }) as never),
+    ...candidates.map((t) =>
+      readContract(client, Actions.token.getBalance.call({ account, token: t }) as never),
+    ),
+  ])
+
+  // If the account already has enough of the target token, no swap needed.
+  const targetBalance = balanceResults[0]!
+  if (targetBalance.status === 'fulfilled' && (targetBalance.value as bigint) >= amountOut)
+    return undefined
+
+  // Find first candidate with enough balance to cover a swap.
+  for (let i = 0; i < candidates.length; i++) {
+    const result = balanceResults[i + 1]!
+    if (result.status !== 'fulfilled') continue
+
+    const balance = result.value as bigint
+    if (balance <= 0n) continue
+
+    const tokenIn = candidates[i]!
+
+    try {
+      const quotedAmountIn = await Actions.dex.getBuyQuote(client as never, {
+        tokenIn,
+        tokenOut,
+        amountOut,
+      })
+
+      if (balance >= quotedAmountIn) {
+        const maxAmountIn =
+          quotedAmountIn + (quotedAmountIn * BigInt(Math.round(slippage * 100))) / bps
+        return [
+          Actions.token.approve.call({
+            token: tokenIn,
+            spender: Addresses.stablecoinDex,
+            amount: maxAmountIn,
+          }),
+          Actions.dex.buy.call({
+            tokenIn,
+            tokenOut,
+            amountOut,
+            maxAmountIn,
+          }),
+        ]
+      }
+    } catch {}
+  }
+
+  throw new InsufficientFundsError({ currency: tokenOut })
+}
+
+export declare namespace findCalls {
+  type Parameters = {
+    /** Address of the account to check balances for. */
+    account: Address
+    /** Amount of the target token needed. */
+    amountOut: bigint
+    /** Candidate input tokens to swap from, in priority order. */
+    tokenIn: readonly Address[]
+    /** Max slippage tolerance as a percentage (e.g. `1` = 1%). */
+    slippage: number
+    /** Address of the target token to acquire. */
+    tokenOut: Address
+  }
+
+  /** `undefined` when no swap is needed (account has sufficient balance). */
+  type ReturnType = readonly object[] | undefined
+}
+
+/** Resolves an auto-swap configuration value into concrete currencies and slippage. */
+export function resolve(
+  value: resolve.Value | undefined,
+  defaultCurrencies: readonly Address[],
+): resolve.Resolved | false {
+  if (!value) return false
+  if (value === true) return { tokenIn: defaultCurrencies, slippage: 1 }
+  const tokenIn = value.tokenIn
+    ? [
+        ...value.tokenIn,
+        ...defaultCurrencies.filter((d) => !value.tokenIn!.some((c) => isAddressEqual(c, d))),
+      ]
+    : defaultCurrencies
+  return {
+    tokenIn,
+    slippage: value.slippage ?? 1,
+  }
+}
+
+export declare namespace resolve {
+  type Options = {
+    /** Fallback tokens to try swapping from, in priority order. */
+    tokenIn?: Address[] | undefined
+    /** Max slippage tolerance as a percentage (e.g. `1` = 1%). @default 1 */
+    slippage?: number | undefined
+  }
+
+  type Value = boolean | Options
+
+  type Resolved = { tokenIn: readonly Address[]; slippage: number }
+}
+
+export class InsufficientFundsError extends Error {
+  override readonly name = 'InsufficientFundsError'
+
+  constructor({ currency }: { currency: Address }) {
+    super(
+      `Insufficient funds: no balance in ${currency} and no viable swap route from fallback currencies.`,
+    )
+  }
+}

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

@@ -0,0 +1,223 @@
+import { encodeFunctionData } from 'viem'
+import { Abis, Addresses } from 'viem/tempo'
+import { describe, expect, test } from 'vitest'
+import { callScopes, FeePayerValidationError, validateCalls } from './fee-payer.js'
+import * as Selectors from './selectors.js'
+
+const details = { amount: '1', currency: '0x01', recipient: '0x02' }
+const bogus = '0x0000000000000000000000000000000000000001' as const
+
+describe('callScopes', () => {
+  test('has 4 allowed patterns', () => {
+    expect(callScopes).toHaveLength(4)
+  })
+
+  test('patterns use correct selectors', () => {
+    expect(callScopes).toEqual([
+      [Selectors.transfer],
+      [Selectors.transferWithMemo],
+      [Selectors.approve, Selectors.swapExactAmountOut, Selectors.transfer],
+      [Selectors.approve, Selectors.swapExactAmountOut, Selectors.transferWithMemo],
+    ])
+  })
+})
+
+describe('validateCalls', () => {
+  test('accepts single transfer', () => {
+    expect(() =>
+      validateCalls(
+        [
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'transfer',
+              args: [bogus, 100n],
+            }),
+          },
+        ],
+        details,
+      ),
+    ).not.toThrow()
+  })
+
+  test('accepts approve + buy + transfer', () => {
+    const swapSelector = Selectors.swapExactAmountOut
+    expect(() =>
+      validateCalls(
+        [
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'approve',
+              args: [Addresses.stablecoinDex, 100n],
+            }),
+          },
+          {
+            to: Addresses.stablecoinDex,
+            data: `${swapSelector}${'00'.repeat(128)}` as `0x${string}`,
+          },
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'transfer',
+              args: [bogus, 100n],
+            }),
+          },
+        ],
+        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 extra calls beyond allowed patterns', () => {
+    const swapSelector = Selectors.swapExactAmountOut
+    expect(() =>
+      validateCalls(
+        [
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'approve',
+              args: [Addresses.stablecoinDex, 100n],
+            }),
+          },
+          {
+            to: Addresses.stablecoinDex,
+            data: `${swapSelector}${'00'.repeat(128)}` as `0x${string}`,
+          },
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'transfer',
+              args: [bogus, 100n],
+            }),
+          },
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'transfer',
+              args: [bogus, 100n],
+            }),
+          },
+        ],
+        details,
+      ),
+    ).toThrow('disallowed call pattern')
+  })
+
+  test('error: rejects wrong order (transfer before approve + buy)', () => {
+    const swapSelector = Selectors.swapExactAmountOut
+    expect(() =>
+      validateCalls(
+        [
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'transfer',
+              args: [bogus, 100n],
+            }),
+          },
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'approve',
+              args: [Addresses.stablecoinDex, 100n],
+            }),
+          },
+          {
+            to: Addresses.stablecoinDex,
+            data: `${swapSelector}${'00'.repeat(128)}` as `0x${string}`,
+          },
+        ],
+        details,
+      ),
+    ).toThrow('disallowed call pattern')
+  })
+
+  test('error: rejects approve with non-DEX spender', () => {
+    const swapSelector = Selectors.swapExactAmountOut
+    expect(() =>
+      validateCalls(
+        [
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'approve',
+              args: [bogus, 100n],
+            }),
+          },
+          {
+            to: Addresses.stablecoinDex,
+            data: `${swapSelector}${'00'.repeat(128)}` as `0x${string}`,
+          },
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'transfer',
+              args: [bogus, 100n],
+            }),
+          },
+        ],
+        details,
+      ),
+    ).toThrow('approve spender is not the DEX')
+  })
+
+  test('error: rejects buy targeting non-DEX address', () => {
+    const swapSelector = Selectors.swapExactAmountOut
+    expect(() =>
+      validateCalls(
+        [
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'approve',
+              args: [Addresses.stablecoinDex, 100n],
+            }),
+          },
+          { to: bogus, data: `${swapSelector}${'00'.repeat(128)}` as `0x${string}` },
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'transfer',
+              args: [bogus, 100n],
+            }),
+          },
+        ],
+        details,
+      ),
+    ).toThrow('buy target is not the DEX')
+  })
+
+  test('error: rejects approve + buy without transfer', () => {
+    const swapSelector = Selectors.swapExactAmountOut
+    expect(() =>
+      validateCalls(
+        [
+          {
+            data: encodeFunctionData({
+              abi: Abis.tip20,
+              functionName: 'approve',
+              args: [Addresses.stablecoinDex, 100n],
+            }),
+          },
+          {
+            to: Addresses.stablecoinDex,
+            data: `${swapSelector}${'00'.repeat(128)}` as `0x${string}`,
+          },
+        ],
+        details,
+      ),
+    ).toThrow('disallowed call pattern')
+  })
+})

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

@@ -0,0 +1,53 @@
+import { decodeFunctionData, isAddressEqual } from 'viem'
+import { Abis, Addresses } from 'viem/tempo'
+import * as Selectors from './selectors.js'
+
+/**
+ * Allowed call patterns for fee-payer sponsored transactions.
+ * Each inner array is an ordered list of function selectors.
+ */
+export const callScopes = [
+  [Selectors.transfer],
+  [Selectors.transferWithMemo],
+  [Selectors.approve, Selectors.swapExactAmountOut, Selectors.transfer],
+  [Selectors.approve, Selectors.swapExactAmountOut, Selectors.transferWithMemo],
+]
+
+/** Validates that a set of transaction calls matches an allowed fee-payer pattern. */
+export function validateCalls(
+  calls: readonly { data?: `0x${string}` | undefined; to?: `0x${string}` | undefined }[],
+  details: Record<string, string>,
+) {
+  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)
+    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)
+  if (approveCall) {
+    const { args } = decodeFunctionData({ abi: Abis.tip20, data: approveCall.data! })
+    if (!isAddressEqual((args as [`0x${string}`])[0]!, Addresses.stablecoinDex))
+      throw new FeePayerValidationError('approve spender is not the DEX', details)
+  }
+  const buyCall = calls.find((c) => c.data?.slice(0, 10) === Selectors.swapExactAmountOut)
+  if (buyCall && (!buyCall.to || !isAddressEqual(buyCall.to, Addresses.stablecoinDex)))
+    throw new FeePayerValidationError('buy target is not the DEX', details)
+}
+
+export class FeePayerValidationError extends Error {
+  override readonly name = 'FeePayerValidationError'
+
+  constructor(reason: string, details: Record<string, string>) {
+    super(
+      [
+        `Invalid transaction: ${reason}`,
+        ...Object.entries(details).map(([k, v]) => `  - ${k}: ${v}`),
+      ].join('\n'),
+    )
+  }
+}

package/src/tempo/internal/selectors.ts

@@ -0,0 +1,10 @@
+import { AbiItem } from 'ox'
+import { Abis } from 'viem/tempo'
+
+export const approve = /*#__PURE__*/ AbiItem.getSelector(Abis.tip20, 'approve')
+export const transfer = /*#__PURE__*/ AbiItem.getSelector(Abis.tip20, 'transfer')
+export const transferWithMemo = /*#__PURE__*/ AbiItem.getSelector(Abis.tip20, 'transferWithMemo')
+export const swapExactAmountOut = /*#__PURE__*/ AbiItem.getSelector(
+  Abis.stablecoinDex,
+  'swapExactAmountOut',
+)