tapimo 0.15.1 → 0.18.0

package/src/apps/routes/routes/propAmm.local.test.ts

@@ -0,0 +1,951 @@
+/** @module-tag localnet */
+
+import { Address, Hex } from 'ox'
+import { decodeFunctionData, encodeFunctionData, erc20Abi } from 'viem'
+import { getBlock, sendTransactionSync, writeContractSync } from 'viem/actions'
+import { Abis, Actions } from 'viem/tempo'
+
+import * as TestApp from '../../../../test/App.js'
+import * as Contracts from '../../../../test/contracts/propAmm.js'
+import * as TestPropAmm from '../../../../test/PropAmm.js'
+import * as TestRoutes from '../../../../test/Routes.js'
+import * as Runtime from '../../../../test/runtime.js'
+import * as Tempo from '../../../../test/Tempo.js'
+import * as Organizations from '../../../db/tables/organizations.js'
+import * as Policies from '../../../db/tables/routesPolicies.js'
+import * as TransferTransactions from '../../../db/tables/routesTransferTransactions.js'
+import * as Transfer from '../../../internal/routes/Transfer.js'
+import * as Reconciliation from '../../../internal/routes/TransferReconciliation.js'
+import * as TransfersTable from '../../../db/tables/routesTransfers.js'
+import * as Transfers from './transfers.js'
+import * as Catalog from '../../../internal/routes/Catalog.js'
+import * as Provider from '../../../internal/routes/Provider.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as PropAmm from '../../../internal/routes/providers/propAmm.js'
+import * as Quotes from './quotes.js'
+
+const db = TestApp.database()
+const client = Tempo.getClient({ account: Tempo.accounts[6] })
+const recipient = Tempo.accounts[7].address
+const sender = client.account.address
+const denied = Tempo.accounts[8].address
+const provider = PropAmm.propAmm()
+const app = TestApp.create({ auth: false, db, providers: [provider] })
+const writer = {
+  id: 'key_propamm_writer',
+  orgId: 'org_propamm_writer',
+  scopes: ['routes:read', 'routes:write'],
+  token: 'secret_propamm_writer',
+} satisfies TestApp.kvStore.Key
+const queued: Reconciliation.Message[] = []
+const transfersApp = TestApp.create({
+  auth: { keys: [writer] },
+  db,
+  providers: [provider],
+  routes: {
+    async dispatchTransferReconciliation(message) {
+      queued.push(message)
+    },
+  },
+})
+let pool: Awaited<ReturnType<typeof TestPropAmm.deploy>>
+let catalog: Catalog.Snapshot
+
+beforeAll(async () => {
+  if (Runtime.get().mode !== 'localnet') return
+  await Actions.faucet.fundSync(client, { account: client.account })
+  pool = await TestPropAmm.deploy({ client, recipient })
+  const chainId = `eip155:${pool.chainId}`
+  const data = Catalog.schema.Data.parse({
+    chains: [
+      {
+        aliases: [],
+        id: chainId,
+        name: 'Tempo',
+        parentChainId: null,
+        rpcUrls: [Tempo.rpcUrl],
+        slug: 'tempo',
+      },
+    ],
+    chainTokens: [
+      { address: pool.base, chainId, decimals: 6, name: null, standard: 'TIP-20', tokenId: 'usdy' },
+      {
+        address: pool.quote,
+        chainId,
+        decimals: 6,
+        name: null,
+        standard: 'TIP-20',
+        tokenId: 'usdce',
+      },
+    ],
+    routes: TestRoutes.data.routes
+      .filter(
+        (route) =>
+          route.providerId === 'propamm' &&
+          ['usdy', 'usdce'].includes(route.sourceTokenId) &&
+          ['usdy', 'usdce'].includes(route.destinationTokenId),
+      )
+      .map((route) => ({
+        ...route,
+        configuration: { poolAddress: pool.pool },
+        destinationChainId: chainId,
+        sourceChainId: chainId,
+      })),
+    tokens: TestRoutes.data.tokens.filter((token) => ['usdy', 'usdce'].includes(token.id)),
+  })
+  await Catalog.publish(db, data)
+  catalog = await Catalog.read(db)
+  await Organizations.upsert(db, { id: writer.orgId, name: writer.orgId })
+  await Policies.save(db, {
+    policy: { access: null },
+    scope: { environment: 'production', orgId: writer.orgId },
+    version: 0,
+  })
+})
+
+describe.skipIf(Runtime.get().mode !== 'localnet')('prepareTransfer', () => {
+  test.each(['tempo', `eip155:${client.chain.id}`, undefined])(
+    'defaults sourceChain to destinationChain (%s)',
+    async (destinationChain) => {
+      const response = await transfersApp.request('/v1/routes/transfers', {
+        body: JSON.stringify({
+          amount: '1000000',
+          destinationChain,
+          destinationToken: 'usdce',
+          mode: 'exactSource',
+          recipient,
+          sender,
+          sourceToken: 'usdy',
+        }),
+        headers: {
+          'content-type': 'application/json',
+          'idempotency-key': `propamm_default_source_${destinationChain}`,
+          'tempo-api-key': writer.token,
+        },
+        method: 'POST',
+      })
+      expect(response.status).toBe(200)
+      const transfer = await TestApp.json(response, Transfers.schema.createRoutesTransfer.Response)
+      expect(transfer.sourceChain.id).toBe(`eip155:${pool.chainId}`)
+      expect(transfer.destinationChain.id).toBe(`eip155:${pool.chainId}`)
+      expect(transfer.action.calls[1]!.to.toLowerCase()).toBe(pool.pool.toLowerCase())
+    },
+  )
+
+  test.each([
+    {
+      baseToQuote: true,
+      destinationToken: 'usdce',
+      expected: 2_500_000n,
+      sourceAmount: '2000000',
+      sourceToken: 'usdy',
+    },
+    {
+      baseToQuote: false,
+      destinationToken: 'usdy',
+      expected: 2_000_000n,
+      sourceAmount: '2500000',
+      sourceToken: 'usdce',
+    },
+  ])(
+    'prepares and executes $sourceToken to $destinationToken atomically',
+    async ({ baseToQuote, destinationToken, expected, sourceAmount, sourceToken }) => {
+      const response = await transfersApp.request('/v1/routes/transfers', {
+        body: JSON.stringify({
+          amount: sourceAmount,
+          destinationChain: 'tempo',
+          destinationToken,
+          mode: 'exactSource',
+          recipient,
+          sender,
+          slippageBps: 100,
+          sourceChain: 'tempo',
+          sourceToken,
+        }),
+        headers: {
+          'content-type': 'application/json',
+          'idempotency-key': `propamm_${sourceToken}`,
+          'tempo-api-key': writer.token,
+        },
+        method: 'POST',
+      })
+      expect(response.status).toBe(200)
+      const transfer = await TestApp.json(response, Transfers.schema.createRoutesTransfer.Response)
+      expect(transfer.action.type).toBe('evm:calls')
+      expect(transfer.action.calls).toHaveLength(2)
+      const [approval, swap] = transfer.action.calls
+      const decodedApproval = decodeFunctionData({ abi: erc20Abi, data: approval!.data as Hex.Hex })
+      expect(decodedApproval.functionName).toBe('approve')
+      expect(decodedApproval.args).toEqual([Address.checksum(pool.pool), BigInt(sourceAmount)])
+      const decoded = decodeFunctionData({ abi: Abis.directPropAmm, data: swap!.data as Hex.Hex })
+      if (decoded.functionName !== 'swapExactInput')
+        throw new Error('Expected an exact-input swap.')
+      const [
+        direction,
+        amountIn,
+        minimum,
+        beneficiary,
+        customerId,
+        tradeId,
+        deadline,
+        price,
+        tolerance,
+        updatedAt,
+      ] = decoded.args
+      expect([
+        direction,
+        amountIn,
+        minimum,
+        beneficiary.toLowerCase(),
+        customerId,
+        price,
+        tolerance,
+      ]).toEqual([
+        baseToQuote,
+        BigInt(sourceAmount),
+        (expected * 99n) / 100n,
+        recipient.toLowerCase(),
+        Hex.padLeft(sender, 32).toLowerCase(),
+        pool.price,
+        0n,
+      ])
+      expect(Number(deadline) * 1000).toBe(Date.parse(transfer.quote.expiresAt!))
+      expect(deadline).toBeLessThanOrEqual(updatedAt + pool.maxOracleAge)
+      const stored = await TransfersTable.get(db, transfer.id)
+      expect(stored?.providerState).toMatchObject({
+        propAmm: {
+          amountIn: sourceAmount,
+          baseToQuote,
+          customerId: Hex.padLeft(Address.checksum(sender), 32),
+          deadline: deadline.toString(),
+          expectedOraclePrice: price.toString(),
+          minAmountOut: minimum.toString(),
+          minimumOracleUpdatedAt: updatedAt.toString(),
+          oraclePriceToleranceBps: '0',
+          pool: pool.pool,
+          recipient: Address.checksum(recipient),
+          sender: Address.checksum(sender),
+          tradeId,
+        },
+      })
+
+      const token = baseToQuote ? pool.quote : pool.base
+      const before = await Actions.token.getBalance(client, { account: recipient, token })
+      const receipt = await sendTransactionSync(client, {
+        calls: transfer.action.calls.map((call) => ({
+          data: call.data as Hex.Hex,
+          to: call.to as Hex.Hex,
+          value: BigInt(call.value),
+        })),
+      })
+      expect(receipt.status).toBe('success')
+      const sourceChain = catalog.chainsByKey.get(`eip155:${pool.chainId}`)!
+      const verification = {
+        destinationChain: sourceChain,
+        providerState: stored!.providerState!,
+        sourceChain,
+        transactionHash: receipt.transactionHash,
+        transfer: stored!.snapshot,
+      }
+      await expect
+        .poll(
+          async () =>
+            (await provider.verifySourceTransaction!(verification, new AbortController().signal))
+              .type,
+          { timeout: 30_000 },
+        )
+        .toBe('verified')
+      for (const changed of [
+        { tradeId: Hex.random(32) },
+        { pool: denied },
+        { sender: denied },
+        { recipient: denied },
+        { amountIn: '1' },
+        { minAmountOut: '1' },
+        { expectedOraclePrice: '1' },
+        { minimumOracleUpdatedAt: '1' },
+        { oraclePriceToleranceBps: '1' },
+        { baseToQuote: !baseToQuote },
+      ])
+        expect(
+          await provider.verifySourceTransaction!(
+            {
+              ...verification,
+              providerState: {
+                ...stored!.providerState,
+                propAmm: {
+                  ...PropAmm.schema.ProviderState.parse(stored!.providerState).propAmm,
+                  ...changed,
+                },
+              },
+            },
+            new AbortController().signal,
+          ),
+        ).toEqual({ type: 'invalid' })
+
+      const registration = {
+        body: JSON.stringify({ transactionHash: receipt.transactionHash }),
+        headers: { 'content-type': 'application/json', 'tempo-api-key': writer.token },
+        method: 'POST',
+      }
+      const registered = await transfersApp.request(
+        `/v1/routes/transfers/${transfer.id}/source-transactions`,
+        registration,
+      )
+      expect(registered.status).toBe(200)
+      expect((await registered.json()).status).toBe('processing')
+      expect(queued.some((message) => message.transferId === transfer.id)).toBe(true)
+
+      // A fresh tracker loads all evidence from storage, as it would after a worker restart.
+      const tracker = Reconciliation.createTracker({ db, providers: [PropAmm.propAmm()] })
+      expect(
+        await tracker.reconcile({ transferId: transfer.id, type: 'routes:transfer:reconcile' }),
+      ).toEqual({ type: 'completed' })
+      expect(
+        await tracker.reconcile({ transferId: transfer.id, type: 'routes:transfer:reconcile' }),
+      ).toEqual({ type: 'ignored' })
+      const completed = await TransfersTable.get(db, transfer.id)
+      expect(completed?.snapshot).toMatchObject({
+        destinationTransactionHashes: [receipt.transactionHash],
+        sourceTransactionHashes: [receipt.transactionHash],
+      })
+      expect(completed?.status).toBe('completed')
+      expect(
+        (await TransferTransactions.listByTransfer(db, transfer.id)).map(
+          ({ role, transactionRef }) => ({ role, transactionRef }),
+        ),
+      ).toEqual([
+        { role: 'source', transactionRef: receipt.transactionHash },
+        { role: 'destination', transactionRef: receipt.transactionHash },
+      ])
+      const replay = await transfersApp.request(
+        `/v1/routes/transfers/${transfer.id}/source-transactions`,
+        registration,
+      )
+      expect(replay.status).toBe(200)
+      const duplicate = await Transfer.create(db, {
+        apiKeyId: writer.id,
+        environment: 'production',
+        orgId: writer.orgId,
+        providerState: stored!.providerState!,
+        snapshot: stored!.snapshot,
+      })
+      const conflict = await transfersApp.request(
+        `/v1/routes/transfers/${duplicate.id}/source-transactions`,
+        registration,
+      )
+      expect(conflict.status).toBe(409)
+      expect((await conflict.json()).error.code).toBe('source_transaction_conflict')
+
+      expect(
+        Actions.propAmm.swap.extractEvent(receipt.logs, { pool: pool.pool, tradeId }).args.tradeId,
+      ).toBe(tradeId)
+      const after = await Actions.token.getBalance(client, { account: recipient, token })
+      expect(after.amount - before.amount).toBe(expected)
+      expect(
+        (
+          await Actions.token.getAllowance(client, {
+            account: sender,
+            spender: pool.pool,
+            token: baseToQuote ? pool.base : pool.quote,
+          })
+        ).amount,
+      ).toBe(0n)
+    },
+  )
+
+  test('rejects altered batches before persistence', async () => {
+    const selected = (await prepareTransfer())!
+    const parameters = {
+      candidate: selected.candidate,
+      destinationAmountMin: selected.result.destinationAmountMin,
+      method: 'transaction' as const,
+      mode: 'exactSource' as const,
+      recipient,
+      sender,
+    }
+    const action = selected.result.action
+    expect(provider.validateTransferAction!({ ...parameters, action })).toEqual({})
+    const [approval, swap] = action.calls
+    for (const calls of [
+      [approval!, swap!, swap!],
+      [swap!, approval!],
+      [{ ...approval!, value: '0x1' }, swap!],
+      [{ ...approval!, to: denied }, swap!],
+      [approval!, { ...swap!, to: denied }],
+      [approval!, { ...swap!, data: swap!.data + '00' }],
+      [approval!],
+    ])
+      expect(() =>
+        provider.validateTransferAction!({ ...parameters, action: { calls, type: 'evm:calls' } }),
+      ).toThrow(Provider.ProviderPayloadError)
+    expect(() =>
+      provider.validateTransferAction!({ ...parameters, action, recipient: denied }),
+    ).toThrow(Provider.ProviderPayloadError)
+    expect(() =>
+      provider.validateTransferAction!({ ...parameters, action, destinationAmountMin: '1' }),
+    ).toThrow(Provider.ProviderPayloadError)
+  })
+
+  test('rejects extra calls, standalone approvals, and reverted swaps', async () => {
+    const selected = (await prepareTransfer())!
+    const snapshot = TestRoutes.transferSnapshot({
+      destinationAmount: { baseUnits: '1250000', currency: 'USD', decimals: 6, formatted: '1.25' },
+      destinationAmountMin: {
+        baseUnits: '1250000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '1.25',
+      },
+      destinationChain: selected.candidate.destinationChain,
+      destinationToken: selected.candidate.destinationToken,
+      provider: selected.candidate.provider,
+      quote: { expiresAt: selected.result.expiresAt, sampledAt: selected.result.sampledAt },
+      recipient,
+      sender,
+      sourceAmount: { baseUnits: '1000000', currency: 'USDY', decimals: 6, formatted: '1' },
+      sourceChain: selected.candidate.sourceChain,
+      sourceToken: selected.candidate.sourceToken,
+    })
+    const chain = catalog.chainsByKey.get(`eip155:${pool.chainId}`)!
+    const calls = selected.result.action.calls.map((call) => ({
+      data: call.data as Hex.Hex,
+      to: call.to as Address.Address,
+      value: BigInt(call.value),
+    }))
+    for (const batch of [[calls[0]!], [...calls, calls[0]!]]) {
+      const receipt = await sendTransactionSync(client, { calls: batch })
+      expect(receipt.status).toBe('success')
+      await expect
+        .poll(
+          async () =>
+            (
+              await provider.verifySourceTransaction!(
+                {
+                  destinationChain: chain,
+                  providerState: selected.result.providerState,
+                  sourceChain: chain,
+                  transactionHash: receipt.transactionHash,
+                  transfer: snapshot,
+                },
+                new AbortController().signal,
+              )
+            ).type,
+          { timeout: 30_000 },
+        )
+        .toBe('invalid')
+    }
+    await Actions.token.approveSync(client, { amount: 0n, spender: pool.pool, token: pool.base })
+    const decoded = decodeFunctionData({ abi: Abis.directPropAmm, data: calls[1]!.data })
+    if (decoded.functionName !== 'swapExactInput') throw new Error('Expected an exact-input swap.')
+    const args = decoded.args
+    const expired = encodeFunctionData({
+      abi: Abis.directPropAmm,
+      functionName: 'swapExactInput',
+      args: [args[0], args[1], args[2], args[3], args[4], args[5], 1n, args[7], args[8], args[9]],
+    })
+    const reverted = await sendTransactionSync(client, {
+      calls: [calls[0]!, { ...calls[1]!, data: expired }],
+      throwOnReceiptRevert: false,
+      gas: 500_000n,
+      maxFeePerGas: 10_000_000_000n,
+      maxPriorityFeePerGas: 0n,
+    })
+    expect(reverted.status).toBe('reverted')
+    expect(
+      (
+        await Actions.token.getAllowance(client, {
+          account: sender,
+          spender: pool.pool,
+          token: pool.base,
+        })
+      ).amount,
+    ).toBe(0n)
+    await expect
+      .poll(
+        async () =>
+          (
+            await provider.verifySourceTransaction!(
+              {
+                destinationChain: chain,
+                providerState: selected.result.providerState,
+                sourceChain: chain,
+                transactionHash: reverted.transactionHash,
+                transfer: snapshot,
+              },
+              new AbortController().signal,
+            )
+          ).type,
+        { timeout: 30_000 },
+      )
+      .toBe('invalid')
+  })
+
+  test('reopens orphaned source evidence without losing prepared terms', async () => {
+    const request = {
+      body: JSON.stringify({
+        amount: '1000000',
+        destinationChain: 'tempo',
+        destinationToken: 'usdce',
+        mode: 'exactSource',
+        recipient,
+        sender,
+        sourceChain: 'tempo',
+        sourceToken: 'usdy',
+      }),
+      headers: {
+        'content-type': 'application/json',
+        'idempotency-key': 'propamm_reorg',
+        'tempo-api-key': writer.token,
+      },
+      method: 'POST',
+    }
+    const response = await transfersApp.request('/v1/routes/transfers', request)
+    expect(response.status).toBe(200)
+    const created = await TestApp.json(response, Transfers.schema.createRoutesTransfer.Response)
+    const stored = (await TransfersTable.get(db, created.id))!
+    const transactionHash = Hex.random(32)
+    const chain = catalog.chainsByKey.get(`eip155:${pool.chainId}`)!
+    expect(
+      await provider.verifySourceTransaction!(
+        {
+          destinationChain: chain,
+          providerState: stored.providerState!,
+          sourceChain: chain,
+          transactionHash,
+          transfer: stored.snapshot,
+        },
+        new AbortController().signal,
+      ),
+    ).toEqual({ type: 'pending' })
+    const state = {
+      ...stored.providerState,
+      propAmmEvidence: {
+        amountOut: created.destinationAmount!.baseUnits,
+        blockHash: `0x${'aa'.repeat(32)}`,
+        blockNumber: '0',
+        transactionHash,
+      },
+    }
+    const registered = await Transfer.registerSourceTransactions(db, {
+      chainId: chain.id,
+      id: stored.id,
+      providerState: state,
+      transactionHashes: [transactionHash],
+    })
+    expect(registered.type).toBe('registered')
+    const tracker = Reconciliation.createTracker({ db, providers: [provider] })
+    expect(
+      await tracker.reconcile({ transferId: stored.id, type: 'routes:transfer:reconcile' }),
+    ).toEqual({ type: 'reopened' })
+    const reopened = (await TransfersTable.get(db, stored.id))!
+    expect(reopened.status).toBe('awaiting-source')
+    expect(reopened.providerState).toEqual(stored.providerState)
+    expect(reopened.snapshot.sourceTransactionHashes).toBeUndefined()
+    expect(await TransferTransactions.listByTransfer(db, stored.id)).toEqual([])
+  })
+
+  test('replays persisted preparation without requoting or generating another trade ID', async () => {
+    const request = {
+      body: JSON.stringify({
+        amount: '1000000',
+        destinationChain: 'tempo',
+        destinationToken: 'usdce',
+        mode: 'exactSource',
+        recipient,
+        sender,
+        sourceChain: 'tempo',
+        sourceToken: 'usdy',
+      }),
+      headers: {
+        'content-type': 'application/json',
+        'idempotency-key': 'propamm_replay',
+        'tempo-api-key': writer.token,
+      },
+      method: 'POST',
+    }
+    const first = await transfersApp.request('/v1/routes/transfers', request)
+    expect(first.status).toBe(200)
+    const expected = await first.json()
+    await writeContractSync(client, {
+      abi: Abis.directPropAmm,
+      address: pool.pool,
+      functionName: 'pause',
+    })
+    try {
+      const replay = await transfersApp.request('/v1/routes/transfers', request)
+      expect(replay.status).toBe(200)
+      expect(await replay.json()).toEqual(expected)
+    } finally {
+      await writeContractSync(client, {
+        abi: Abis.directPropAmm,
+        address: pool.pool,
+        functionName: 'unpause',
+      })
+    }
+  })
+
+  test('requotes changed oracle prices at preparation', async () => {
+    const previous = await getQuotes()
+    expect(previous[0]?.destinationAmount.baseUnits).toBe('1250000')
+    const timestamp = (await getBlock(client)).timestamp
+    await writeContractSync(client, {
+      abi: Contracts.pushPriceOracle.abi,
+      address: pool.oracle,
+      args: [1_255_000_000_000_000_000n, timestamp],
+      functionName: 'pushPrice',
+    })
+    try {
+      const selected = await prepareTransfer()
+      expect(selected?.result.destinationAmount).toBe('1255000')
+      expect(selected?.result.providerState).toMatchObject({
+        propAmm: { expectedOraclePrice: '1255000000000000000' },
+      })
+    } finally {
+      await expect.poll(async () => (await getBlock(client)).timestamp).toBeGreaterThan(timestamp)
+      await writeContractSync(client, {
+        abi: Contracts.pushPriceOracle.abi,
+        address: pool.oracle,
+        args: [pool.price, (await getBlock(client)).timestamp],
+        functionName: 'pushPrice',
+      })
+    }
+  })
+
+  test.each([{ sender: denied }, { recipient: denied }])(
+    'rejects ineligible preparation identities: %j',
+    async (identity) => {
+      const attempts: Provider.ProviderAttempt[] = []
+      expect(
+        await prepareTransfer({ ...identity, onAttempt: (attempt) => attempts.push(attempt) }),
+      ).toBeUndefined()
+      expect(attempts.map(({ operation, outcome }) => ({ operation, outcome }))).toEqual([
+        { operation: 'prepareTransfer', outcome: 'unavailable' },
+      ])
+    },
+  )
+
+  test('uses one RPC call for warm quotes and preparation', async () => {
+    const requests: string[] = []
+    const provider = PropAmm.propAmm({
+      async fetch(input, init) {
+        const { method } = JSON.parse(init!.body as string)
+        requests.push(method)
+        return fetch(input, init)
+      },
+    })
+    expect(await getQuotes({ providers: [provider] })).toHaveLength(1)
+    expect(requests).toMatchInlineSnapshot(`
+      [
+        "eth_call",
+        "eth_call",
+      ]
+    `)
+    requests.length = 0
+    expect(await getQuotes({ providers: [provider] })).toHaveLength(1)
+    expect(requests).toMatchInlineSnapshot(`
+      [
+        "eth_call",
+      ]
+    `)
+    requests.length = 0
+    expect(await prepareTransfer({ providers: [provider] })).toBeDefined()
+    expect(requests).toMatchInlineSnapshot(`
+      [
+        "eth_call",
+      ]
+    `)
+    requests.length = 0
+    expect(
+      await prepareTransfer({
+        destinationToken: 'usdy',
+        providers: [provider],
+        sourceToken: 'usdce',
+      }),
+    ).toBeDefined()
+    expect(requests).toMatchInlineSnapshot(`
+      [
+        "eth_call",
+      ]
+    `)
+  })
+
+  test.each([0, 10_000])('bounds minimum output at %i bps slippage', async (slippageBps) => {
+    const selected = await prepareTransfer({ slippageBps })
+    expect(selected?.result.destinationAmountMin).toBe(slippageBps === 0 ? '1250000' : '1')
+  })
+})
+
+describe.skipIf(Runtime.get().mode !== 'localnet')('quoteRoutes', () => {
+  test.each([
+    {
+      destinationToken: 'usdce',
+      expected: '2500000',
+      sourceAmount: '2000000',
+      sourceToken: 'usdy',
+    },
+    {
+      destinationToken: 'usdy',
+      expected: '2000000',
+      sourceAmount: '2500000',
+      sourceToken: 'usdce',
+    },
+  ])(
+    'quotes $sourceToken to $destinationToken with the supplied identities',
+    async ({ expected, ...query }) => {
+      const response = await app.request(
+        `/v1/routes/quotes?${new URLSearchParams({ ...query, recipient, sender, sourceChain: 'tempo' })}`,
+      )
+      expect(response.status).toBe(200)
+      expect(response.headers.get('cache-control')).toBe('no-store')
+      const { data } = Quotes.schema.quoteRoutes.Response.parse(await response.json())
+      expect(data).toHaveLength(1)
+      expect(data[0]!.destinationAmount.baseUnits).toBe(expected)
+      expect(data[0]!.provider).toMatchInlineSnapshot(`
+      {
+        "id": "propamm",
+        "name": "PropAMM",
+      }
+    `)
+      expect(Date.parse(data[0]!.quote.expiresAt!)).toBeGreaterThan(Date.now())
+    },
+  )
+
+  test.each([
+    {
+      identity: { recipient, sender: '' },
+      detail: {
+        message: 'Sender and recipient addresses are required. Provide both addresses and retry.',
+      },
+    },
+    {
+      identity: { recipient: '', sender },
+      detail: {
+        message: 'Sender and recipient addresses are required. Provide both addresses and retry.',
+      },
+    },
+    {
+      identity: { recipient, sender: denied },
+      detail: {
+        message:
+          'The sender is not authorized for this route. Use an approved sender address or request access before retrying.',
+        path: ['sender'],
+      },
+    },
+    {
+      identity: { recipient: denied, sender },
+      detail: {
+        message:
+          'The recipient is not authorized for this route. Use an approved recipient address or request access before retrying.',
+        path: ['recipient'],
+      },
+    },
+    {
+      identity: { recipient, sender: 'invalid' },
+      detail: {
+        message:
+          'A sender or recipient address is invalid. Check both addresses for the selected chains and retry.',
+      },
+    },
+  ])('returns an actionable error: $detail.message', async ({ identity, detail }) => {
+    const query = new URLSearchParams({
+      destinationToken: 'usdce',
+      sourceAmount: '1000000',
+      sourceChain: 'tempo',
+      sourceToken: 'usdy',
+    })
+    for (const [key, value] of Object.entries(identity)) if (value) query.set(key, value)
+    const response = await app.request(`/v1/routes/quotes?${query}`)
+    expect(response.status).toBe(400)
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(body.error).toEqual({
+      code: 'route_unavailable',
+      details: [detail],
+      message: 'No route is available for this request. Review the details and retry.',
+    })
+  })
+
+  test('does not advertise unavailable pool inventory', async () => {
+    expect(
+      await Provider.getQuotes({
+        catalog,
+        destinationToken: 'usdce',
+        providers: [provider],
+        recipient,
+        sender,
+        sourceAmount: '1000000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'tempo',
+        sourceToken: 'usdy',
+      }),
+    ).toEqual([])
+  })
+
+  test('does not advertise a paused pool', async () => {
+    await writeContractSync(client, {
+      abi: Abis.directPropAmm,
+      address: pool.pool,
+      functionName: 'pause',
+    })
+    try {
+      expect(await getQuotes()).toEqual([])
+    } finally {
+      await writeContractSync(client, {
+        abi: Abis.directPropAmm,
+        address: pool.pool,
+        functionName: 'unpause',
+      })
+    }
+  })
+
+  test('records unexpected RPC failures through existing provider observability', async () => {
+    const attempts: Provider.ProviderAttempt[] = []
+    await expect(
+      Provider.getQuotes({
+        catalog,
+        destinationToken: 'usdce',
+        onAttempt: (attempt) => attempts.push(attempt),
+        providers: [PropAmm.propAmm({ resolveRpcUrls: () => ['http://127.0.0.1:1'] })],
+        recipient,
+        sender,
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'tempo',
+        sourceToken: 'usdy',
+      }),
+    ).rejects.toBeInstanceOf(Provider.ProviderQuoteError)
+    expect(
+      attempts.map(({ operation, outcome, provider }) => ({ id: provider.id, operation, outcome })),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "id": "propamm",
+          "operation": "getQuote",
+          "outcome": "failed",
+        },
+      ]
+    `)
+  })
+
+  test('omits stale oracle quotes without treating them as RPC failures', async () => {
+    await writeContractSync(client, {
+      abi: Abis.directPropAmm,
+      address: pool.pool,
+      functionName: 'pause',
+    })
+    await writeContractSync(client, {
+      abi: Abis.directPropAmm,
+      address: pool.pool,
+      args: [10n],
+      functionName: 'setMaxOracleAge',
+    })
+    // Keep the oracle fresh while reopening the pool, then let it expire onchain.
+    const timestamp = (await getBlock(client)).timestamp
+    await writeContractSync(client, {
+      abi: Contracts.pushPriceOracle.abi,
+      address: pool.oracle,
+      args: [pool.price, timestamp],
+      functionName: 'pushPrice',
+    })
+    await writeContractSync(client, {
+      abi: Abis.directPropAmm,
+      address: pool.pool,
+      functionName: 'unpause',
+      // Explicit fees and gas avoid pending-block estimation beyond the short oracle lifetime.
+      gas: 500_000n,
+      maxFeePerGas: 10_000_000_000n,
+      maxPriorityFeePerGas: 0n,
+    })
+    await expect
+      .poll(async () => (await getBlock(client)).timestamp, { timeout: 15_000 })
+      .toBeGreaterThan(timestamp + 10n)
+    const attempts: Provider.ProviderAttempt[] = []
+    expect(await getQuotes({ onAttempt: (attempt) => attempts.push(attempt) })).toEqual([])
+    expect(attempts.map(({ outcome }) => outcome)).toEqual(['unavailable'])
+  })
+})
+
+describe.skipIf(Runtime.get().mode !== 'localnet')('getRoutesProviders', () => {
+  test('discovers PropAMM and its same-chain tokens', async () => {
+    const response = await app.request('/v1/routes/providers')
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "data": [
+          {
+            "id": "propamm",
+            "name": "PropAMM",
+          },
+        ],
+      }
+    `)
+    expect(
+      TestRoutes.data.routes.filter(
+        (route) =>
+          route.providerId === 'propamm' &&
+          ['usdy', 'usdce'].includes(route.sourceTokenId) &&
+          ['usdy', 'usdce'].includes(route.destinationTokenId),
+      ),
+    ).toHaveLength(2)
+    expect(
+      TestRoutes.data.routes
+        .filter(
+          (route) =>
+            route.providerId === 'propamm' &&
+            ['usdy', 'usdce'].includes(route.sourceTokenId) &&
+            ['usdy', 'usdce'].includes(route.destinationTokenId),
+        )
+        .every((route) => route.capabilities?.transfer?.modes.join() === 'exactSource'),
+    ).toBe(true)
+    const chains = await app.request('/v1/routes/chains')
+    expect(chains.status).toBe(200)
+    expect(JSON.stringify(await chains.json())).toContain('USDY')
+  })
+})
+
+describe.skipIf(Runtime.get().mode !== 'localnet')('getOpenApi', () => {
+  test('documents optional quote identities with examples', async () => {
+    const response = await app.request('/openapi.json')
+    const spec = await response.json()
+    const parameters = spec.paths['/v1/routes/quotes'].get.parameters
+    for (const name of ['sender', 'recipient']) {
+      const parameter = parameters.find((parameter: { name: string }) => parameter.name === name)
+      expect(parameter).toMatchObject({ in: 'query', name })
+      expect(parameter.required ?? false).toBe(false)
+      expect(parameter.schema.examples).toHaveLength(1)
+    }
+  })
+})
+
+async function getQuotes(
+  options: Partial<Pick<Provider.getQuotes.Options, 'onAttempt' | 'providers'>> = {},
+) {
+  return Provider.getQuotes({
+    catalog,
+    destinationToken: 'usdce',
+    providers: [provider],
+    recipient,
+    sender,
+    sourceAmount: '1000000',
+    sourceAmountUnits: 'baseUnits',
+    sourceChain: 'tempo',
+    sourceToken: 'usdy',
+    ...options,
+  })
+}
+
+async function prepareTransfer(options: Partial<Provider.prepareTransfer.Options> = {}) {
+  return Provider.prepareTransfer({
+    catalog,
+    destinationChain: 'tempo',
+    destinationToken: 'usdce',
+    method: 'transaction',
+    mode: 'exactSource',
+    providers: [provider],
+    recipient,
+    sender,
+    sourceAmount: '1000000',
+    sourceChain: 'tempo',
+    sourceToken: 'usdy',
+    ...options,
+  })
+}