tapimo 0.7.0 → 0.7.2

package/src/internal/funding/Action.test.ts

@@ -0,0 +1,138 @@
+import * as Action from './Action.js'
+
+const sourceToken = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
+const spender = `0x${'44'.repeat(20)}`
+
+function approveCall(amount: bigint): Action.Call {
+  return {
+    data: `0x095ea7b3${spender.slice(2).padStart(64, '0')}${amount.toString(16).padStart(64, '0')}`,
+    to: sourceToken,
+    value: '0x0',
+  }
+}
+
+const depositCall: Action.Call = { data: '0xe8017952', to: spender, value: '0x0' }
+
+describe('validateEvmCalls', () => {
+  test('accepts approvals bounded to the route amount', () => {
+    Action.validateEvmCalls({
+      action: { calls: [approveCall(1_000_000n), depositCall], type: 'evm:calls' },
+      sourceAmount: '1000000',
+      sourceTokenAddress: sourceToken,
+    })
+  })
+
+  test('rejects unlimited approvals', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [approveCall((1n << 256n) - 1n), depositCall], type: 'evm:calls' },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Approval must stay bounded to the route amount.]`,
+    )
+  })
+
+  test('rejects approvals above the route amount', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [approveCall(1_000_001n)], type: 'evm:calls' },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrow(Action.InvalidActionError)
+  })
+
+  test('rejects approvals targeting another token', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: {
+          calls: [{ ...approveCall(1n), to: `0x${'99'.repeat(20)}` }],
+          type: 'evm:calls',
+        },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Approval must target the source token.]`,
+    )
+  })
+
+  test('rejects approval spenders that do not execute a prepared call', () => {
+    const attacker = `0x${'99'.repeat(20)}`
+    expect(() =>
+      Action.validateEvmCalls({
+        action: {
+          calls: [
+            {
+              data: `0x095ea7b3${attacker.slice(2).padStart(64, '0')}${(1_000_000).toString(16).padStart(64, '0')}`,
+              to: sourceToken,
+              value: '0x0',
+            },
+            depositCall,
+          ],
+          type: 'evm:calls',
+        },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Approval spender must match a later prepared executor.]`,
+    )
+  })
+
+  test('rejects truncated approval calldata', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: {
+          calls: [{ data: '0x095ea7b3', to: sourceToken, value: '0x0' }],
+          type: 'evm:calls',
+        },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Malformed approval calldata.]`,
+    )
+  })
+
+  test('rejects odd-length calldata', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [{ data: '0x1', to: spender, value: '0x0' }], type: 'evm:calls' },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Malformed EVM calls.]`,
+    )
+  })
+
+  test('rejects unsupported source token calls', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: {
+          calls: [{ data: '0xa9059cbb', to: sourceToken, value: '0x0' }],
+          type: 'evm:calls',
+        },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Unsupported source token call.]`,
+    )
+  })
+
+  test('rejects calls carrying native value', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [{ ...depositCall, value: '0x1' }], type: 'evm:calls' },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Stablecoin funding calls must not carry native value.]`,
+    )
+  })
+})

package/src/internal/funding/Action.ts

@@ -0,0 +1,117 @@
+import { AbiFunction, Address, type Hex, Solidity } from 'ox'
+import * as z from 'zod/mini'
+
+/**
+ * Executable source-chain actions returned by funding transfer creation. A
+ * strict discriminated union: transfer reads never include an action.
+ */
+
+const approve = AbiFunction.from('function approve(address spender, uint256 amount)')
+const approveSelector = AbiFunction.getSelector(approve)
+
+/** Zod schemas owned by funding actions. */
+export namespace schema {
+  /** One unsigned EVM call, in the exchange quote API's call shape. */
+  export const Call = z
+    .object({
+      data: z
+        .string()
+        .check(
+          z.regex(/^0x(?:[0-9a-fA-F]{2})*$/),
+          z.describe('ABI-encoded calldata.'),
+          z.meta({ examples: ['0x095ea7b3'] }),
+        ),
+      to: z
+        .string()
+        .check(
+          z.regex(/^0x[0-9a-fA-F]{40}$/),
+          z.describe('Contract the call targets.'),
+          z.meta({ examples: [`0x${'44'.repeat(20)}`] }),
+        ),
+      value: z
+        .string()
+        .check(
+          z.regex(/^0x[0-9a-fA-F]+$/),
+          z.describe('Native value to send, as hex.'),
+          z.meta({ examples: ['0x0'] }),
+        ),
+    })
+    .check(z.describe('One unsigned EVM call.'))
+
+  /** Ordered unsigned EVM calls the caller signs and submits on the source chain. */
+  export const EvmCalls = z
+    .object({
+      calls: z
+        .array(Call)
+        .check(
+          z.minLength(1),
+          z.describe('Calls in submission order; they may require separate transactions.'),
+        ),
+      type: z.literal('evm:calls').check(z.describe('Action kind.')),
+    })
+    .check(z.describe('Ordered unsigned EVM calls to sign and submit on the source chain.'))
+
+  /** Executable source-chain action attached to a creation response. */
+  export const Action = z
+    .discriminatedUnion('type', [EvmCalls])
+    .check(z.describe('Executable source-chain action. Never returned by transfer reads.'))
+}
+
+/** One unsigned EVM call (see {@link schema.Call}). */
+export type Call = z.output<typeof schema.Call>
+
+/** Ordered unsigned EVM calls (see {@link schema.EvmCalls}). */
+export type EvmCalls = z.output<typeof schema.EvmCalls>
+
+/** Executable source-chain action (see {@link schema.Action}). */
+export type Action = z.output<typeof schema.Action>
+
+/**
+ * Validates prepared EVM calls before persistence. Token calls, approval
+ * targets, spenders, amounts, selectors, and native value must match the route.
+ */
+export function validateEvmCalls(options: validateEvmCalls.Options): void {
+  const action = schema.EvmCalls.safeParse(options.action)
+  if (!action.success) throw new InvalidActionError('Malformed EVM calls.')
+  for (const [index, call] of action.data.calls.entries()) {
+    if (BigInt(call.value) !== 0n)
+      throw new InvalidActionError('Stablecoin funding calls must not carry native value.')
+    const targetsSourceToken = Address.isEqual(
+      call.to as Address.Address,
+      options.sourceTokenAddress as Address.Address,
+    )
+    const selector = call.data.slice(0, approveSelector.length).toLowerCase()
+    if (targetsSourceToken && selector !== approveSelector)
+      throw new InvalidActionError('Unsupported source token call.')
+    if (selector !== approveSelector) continue
+    if (!targetsSourceToken) throw new InvalidActionError('Approval must target the source token.')
+    if (call.data.length !== approveSelector.length + 128)
+      throw new InvalidActionError('Malformed approval calldata.')
+    const [spender, amount] = AbiFunction.decodeData(approve, call.data as Hex.Hex)
+    if (
+      !action.data.calls
+        .slice(index + 1)
+        .some((next) => Address.isEqual(next.to as Address.Address, spender))
+    )
+      throw new InvalidActionError('Approval spender must match a later prepared executor.')
+    if (amount >= Solidity.maxUint256 || amount > BigInt(options.sourceAmount))
+      throw new InvalidActionError('Approval must stay bounded to the route amount.')
+  }
+}
+
+export declare namespace validateEvmCalls {
+  /** Expected route terms the calls must stay bounded to. */
+  type Options = {
+    /** The prepared action to validate. */
+    action: EvmCalls
+    /** Source amount in base units. */
+    sourceAmount: string
+    /** Source token contract address. */
+    sourceTokenAddress: string
+  }
+}
+
+/** Error thrown when a provider returns an action outside the route's bounds. */
+export class InvalidActionError extends Error {
+  override name = 'Funding.Action.InvalidActionError'
+}

package/src/internal/funding/Catalog.test.ts

@@ -0,0 +1,311 @@
+import type { Context } from 'hono'
+
+import * as TestApp from '../../../test/App.js'
+import type * as App from '../../App.js'
+import * as Db from '../../db/Db.js'
+import * as core_Catalog from '../../db/tables/fundingCatalog.js'
+import * as Catalog from './Catalog.js'
+
+const data = {
+  chains: [
+    {
+      aliases: ['eth'],
+      id: 'eip155:1',
+      name: 'Ethereum',
+      parentChainId: null,
+      rpcUrls: ['https://ethereum.example'],
+      slug: 'ethereum',
+    },
+    {
+      aliases: [],
+      id: 'eip155:4217',
+      name: 'Tempo',
+      parentChainId: null,
+      rpcUrls: ['https://tempo.example'],
+      slug: 'tempo',
+    },
+  ],
+  chainTokens: [
+    {
+      address: '0xA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48',
+      chainId: 'eip155:1',
+      decimals: 6,
+      name: null,
+      standard: 'ERC-20',
+      tokenId: 'usdc',
+    },
+    {
+      address: '0x20C000000000000000000000B9537D11C60E8B50',
+      chainId: 'eip155:4217',
+      decimals: 6,
+      name: null,
+      standard: 'TIP-20',
+      tokenId: 'usdce',
+    },
+  ],
+  routes: [
+    {
+      destinationChainId: 'eip155:4217',
+      destinationTokenId: 'usdce',
+      providerId: 'relay',
+      sourceChainId: 'eip155:1',
+      sourceTokenId: 'usdc',
+    },
+  ],
+  tokens: [
+    {
+      currency: 'USD',
+      id: 'usdc',
+      name: 'USD Coin',
+      symbol: 'USDC',
+    },
+    {
+      currency: 'USD',
+      id: 'usdce',
+      name: 'Bridged USDC (Stargate)',
+      symbol: 'USDC.e',
+    },
+  ],
+} as const satisfies Catalog.publish.Input
+
+function rows(options: Partial<core_Catalog.Rows> = {}): core_Catalog.Rows {
+  return {
+    catalog: {
+      id: 'default',
+      updatedAt: '2026-01-01T00:00:00.000Z',
+      version: 'test',
+    },
+    ...data,
+    ...options,
+  }
+}
+
+function context(db: Db.Db): Context<App.Environment> {
+  return {
+    get: (key: string) => (key === 'dbCached' ? db : undefined),
+  } as unknown as Context<App.Environment>
+}
+
+describe('compile', () => {
+  test('hydrates and indexes catalog routes', () => {
+    const snapshot = Catalog.compile(rows())
+    expect({
+      chain: snapshot.chainsByKey.get('eth')?.id,
+      destination: snapshot.routes[0]?.route.destination.address,
+      rpcUrls: snapshot.chainsByKey.get('eth')?.rpcUrls,
+      source: snapshot.routes[0]?.route.source.address,
+      token: snapshot.tokensById.get('usdc')?.symbol,
+    }).toMatchInlineSnapshot(`
+      {
+        "chain": "eip155:1",
+        "destination": "0x20c000000000000000000000b9537d11c60e8b50",
+        "rpcUrls": [
+          "https://ethereum.example",
+        ],
+        "source": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+        "token": "USDC",
+      }
+    `)
+  })
+
+  test('compiles an empty database to an empty catalog', () => {
+    const snapshot = Catalog.compile({
+      catalog: undefined,
+      chainTokens: [],
+      chains: [],
+      routes: [],
+      tokens: [],
+    })
+    expect({ routes: snapshot.routes, version: snapshot.version }).toMatchInlineSnapshot(`
+      {
+        "routes": [],
+        "version": "empty",
+      }
+    `)
+  })
+
+  test('rejects duplicate chain aliases', () => {
+    expect(() =>
+      Catalog.compile(
+        rows({
+          chains: [
+            ...data.chains,
+            {
+              aliases: ['ETH'],
+              id: 'eip155:8453',
+              name: 'Base',
+              parentChainId: null,
+              rpcUrls: ['https://base.example'],
+              slug: 'base',
+            },
+          ],
+        }),
+      ),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Catalog.InvalidCatalogError: Duplicate chain key "ETH".]`,
+    )
+  })
+
+  test('rejects dangling route placements', () => {
+    expect(() =>
+      Catalog.compile(
+        rows({
+          routes: [
+            {
+              ...data.routes[0],
+              destinationTokenId: 'missing',
+            },
+          ],
+        }),
+      ),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Catalog.InvalidCatalogError: Unknown route token "missing".]`,
+    )
+  })
+
+  test('rejects malformed chain ids', () => {
+    expect(() =>
+      Catalog.compile(
+        rows({
+          chains: [
+            {
+              aliases: [],
+              id: 'eip155:not-a-number',
+              name: 'Invalid',
+              parentChainId: null,
+              rpcUrls: [],
+              slug: 'invalid',
+            },
+          ],
+        }),
+      ),
+    ).toThrowErrorMatchingInlineSnapshot(`
+      [$ZodError: [
+        {
+          "origin": "string",
+          "code": "invalid_format",
+          "format": "regex",
+          "pattern": "/^(?:eip155:\\\\d+|solana:[^:]+|tron:[^:]+)$/",
+          "path": [
+            "chains",
+            0,
+            "id"
+          ],
+          "message": "Invalid string: must match pattern /^(?:eip155:\\\\d+|solana:[^:]+|tron:[^:]+)$/"
+        }
+      ]]
+    `)
+  })
+})
+
+describe('snapshot', () => {
+  test('cold-loads a repository publish', async () => {
+    const db = TestApp.database()
+    const catalog = await core_Catalog.publish(db, data)
+    const snapshot = await Catalog.snapshot(context(db))
+    expect(snapshot.version).toBe(catalog.version)
+  })
+
+  test('isolates snapshots by database source', async () => {
+    const first = TestApp.database()
+    const second = TestApp.database()
+    await Catalog.publish(first, data)
+    await Catalog.publish(second, {
+      ...data,
+      routes: [],
+    })
+
+    expect((await Catalog.snapshot(context(first))).routes).toHaveLength(1)
+    expect((await Catalog.snapshot(context(second))).routes).toHaveLength(0)
+  })
+})
+
+describe('publish', () => {
+  test('round-trips and primes the current isolate', async () => {
+    const db = TestApp.database()
+    const published = await Catalog.publish(db, data)
+    const current = await Catalog.snapshot(context(db))
+    expect(current).toBe(published)
+    expect((await Catalog.read(db)).version).toBe(published.version)
+  })
+
+  test('primes the same route order returned by database reads', async () => {
+    const db = TestApp.database()
+    const published = await Catalog.publish(db, {
+      ...data,
+      routes: [
+        data.routes[0],
+        {
+          ...data.routes[0],
+          providerId: 'across',
+        },
+      ],
+    })
+
+    expect(published.routes.map((entry) => entry.providerId)).toEqual(['across', 'relay'])
+    expect((await Catalog.read(db)).routes.map((entry) => entry.providerId)).toEqual([
+      'across',
+      'relay',
+    ])
+  })
+
+  test('advances the catalog version', async () => {
+    const db = TestApp.database()
+    const first = await Catalog.publish(db, data)
+    const second = await Catalog.publish(db, {
+      chainTokens: [],
+      chains: [],
+      routes: [],
+      tokens: [],
+    })
+    expect(second.version > first.version).toBe(true)
+  })
+})
+
+describe('route capabilities', () => {
+  const capabilities = {
+    transfer: { modes: ['exactSource'] },
+  } as const
+
+  test('carries capabilities into hydrated provider routes', () => {
+    const snapshot = Catalog.compile(rows({ routes: [{ ...data.routes[0]!, capabilities }] }))
+    expect(snapshot.routes[0]?.capabilities).toStrictEqual(capabilities)
+  })
+
+  test('omits capabilities for indicative-only routes', () => {
+    const absent = Catalog.compile(rows())
+    const nulled = Catalog.compile(rows({ routes: [{ ...data.routes[0]!, capabilities: null }] }))
+    expect('capabilities' in absent.routes[0]!).toBe(false)
+    expect('capabilities' in nulled.routes[0]!).toBe(false)
+  })
+
+  test('publishes capabilities through the write boundary', async () => {
+    const db = TestApp.database()
+    const snapshot = await Catalog.publish(db, {
+      ...data,
+      routes: [{ ...data.routes[0]!, capabilities }],
+    })
+    expect(snapshot.routes[0]?.capabilities).toStrictEqual(capabilities)
+  })
+
+  test('rejects invalid capability entries', () => {
+    expect(() =>
+      Catalog.compile(rows({ routes: [{ ...data.routes[0]!, capabilities: {} }] })),
+    ).toThrow()
+    expect(() =>
+      Catalog.compile(
+        rows({ routes: [{ ...data.routes[0]!, capabilities: { transfer: undefined } }] }),
+      ),
+    ).toThrow()
+    expect(() =>
+      Catalog.compile(
+        rows({ routes: [{ ...data.routes[0]!, capabilities: { transfer: { modes: [] } } }] }), // prettier-ignore
+      ),
+    ).toThrow()
+    expect(() =>
+      Catalog.compile(
+        rows({ routes: [{ ...data.routes[0]!, capabilities: { depositAddress: false as never } }] }), // prettier-ignore
+      ),
+    ).toThrow()
+  })
+})