tapimo 0.7.2 → 0.9.0

package/src/apps/funding/routes/transfers.test.ts

@@ -0,0 +1,1236 @@
+import { Value } from 'ox'
+import { decodeFunctionData, erc20Abi, maxUint256 } from 'viem'
+import { base } from 'viem/chains'
+import { tempoMainnet } from 'viem/tempo/chains'
+
+import * as Anvil from '../../../../test/Anvil.js'
+import * as FundingIdempotencyTable from '../../../db/tables/fundingIdempotency.js'
+
+import * as Cache from '../../../internal/Cache.js'
+
+import * as FundingProvider from '../../../internal/funding/Provider.js'
+
+import * as FundingTransfer from '../../../internal/funding/Transfer.js'
+
+import * as Idempotency from '../../../internal/Idempotency.js'
+
+import * as Relay from '../../../internal/funding/providers/relay.js'
+
+import * as TestApp from '../../../../test/App.js'
+
+import * as TestFunding from '../../../../test/Funding.js'
+
+import * as Funding from './transfers.js'
+
+const db = TestApp.database()
+
+/** Providers exercised against executable calls on a forked source chain. */
+const executableProviders = [
+  {
+    create: (sender: string) =>
+      Relay.relay({
+        ...(process.env.RELAY_API_KEY ? { apiKey: process.env.RELAY_API_KEY } : {}),
+        userAddress: sender,
+      }),
+    id: 'relay',
+  },
+] as const
+
+beforeAll(() => TestFunding.publish(db))
+
+function create(options: TestApp.create.Options = {}) {
+  return TestApp.create({ ...options, db })
+}
+
+describe('GET /funding/transfers', () => {
+  test('requires the funding:read scope', async () => {
+    const app = transfersApp()
+    expect((await app.request('/v1/funding/transfers')).status).toBe(401)
+    const forbidden = await app.request('/v1/funding/transfers', as(TestApp.key))
+    expect(forbidden.status).toBe(403)
+  })
+
+  test('pages own transfers newest-first', async () => {
+    const app = transfersApp()
+    const first = await seedTransfer()
+    const second = await seedTransfer()
+    const third = await seedTransfer()
+    await seedTransfer({ orgId: fundingForeign.orgId })
+
+    const response = await app.request('/v1/funding/transfers?limit=5', {
+      headers: { 'tempo-api-key': fundingReader.token },
+    })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe(Cache.policies.feed)
+    const etag = response.headers.get('etag') ?? ''
+    expect(etag).not.toBe('')
+    expect(response.headers.get('vary')).toBe(
+      'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key',
+    )
+    const body = await TestApp.json(response, Funding.schema.listFundingTransfers.Response)
+    expect(body.data.map((transfer) => transfer.id)).toEqual([third.id, second.id, first.id])
+    expect(body.nextCursor).toBeNull()
+    expect(body.meta).toBeUndefined()
+
+    const unchanged = await app.request('/v1/funding/transfers?limit=5', {
+      headers: { 'if-none-match': etag, 'tempo-api-key': fundingReader.token },
+    })
+    expect(unchanged.status).toBe(304)
+    expect(unchanged.headers.get('cache-control')).toBe(Cache.policies.feed)
+    expect(unchanged.headers.get('vary')).toBe(
+      'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key',
+    )
+
+    const paged = await TestApp.json(
+      await app.request(`/v1/funding/transfers?limit=5&cursor=${second.id}`, as(fundingReader)),
+      Funding.schema.listFundingTransfers.Response,
+    )
+    expect(paged.data.map((transfer) => transfer.id)).toEqual([first.id])
+  })
+
+  test('filters by status and embeds the capped count on request', async () => {
+    const app = transfersApp()
+    const expired = await seedTransfer()
+    await FundingTransfer.transition(db, {
+      expectedVersion: 1,
+      id: expired.id,
+      status: 'expired',
+    })
+
+    const response = await app.request(
+      '/v1/funding/transfers?status=expired&include=totalCount',
+      as(fundingReader),
+    )
+    const body = await TestApp.json(response, Funding.schema.listFundingTransfers.Response)
+    expect(body.data.map((transfer) => transfer.id)).toEqual([expired.id])
+    expect(body.data[0]?.status).toBe('expired')
+    expect(body.meta).toEqual({ totalCount: 1, totalCountCapped: false })
+  })
+
+  test('narrows project-attributed keys to their project', async () => {
+    const app = transfersApp()
+    const scoped = await seedTransfer({ projectId: fundingProjectReader.projectId })
+
+    const body = await TestApp.json(
+      await app.request('/v1/funding/transfers?limit=200', as(fundingProjectReader)),
+      Funding.schema.listFundingTransfers.Response,
+    )
+    expect(body.data.map((transfer) => transfer.id)).toEqual([scoped.id])
+
+    // The organization-attributed key sees the project row too.
+    const orgBody = await TestApp.json(
+      await app.request('/v1/funding/transfers?limit=200', as(fundingReader)),
+      Funding.schema.listFundingTransfers.Response,
+    )
+    expect(orgBody.data.map((transfer) => transfer.id)).toContain(scoped.id)
+  })
+
+  test('rejects invalid query parameters', async () => {
+    const app = transfersApp()
+    const response = await app.request('/v1/funding/transfers?status=bogus', as(fundingReader))
+    expect(response.status).toBe(400)
+  })
+})
+
+describe('GET /funding/transfers/:id', () => {
+  test('returns the owned transfer directly, without an action', async () => {
+    const app = transfersApp()
+    const record = await seedTransfer()
+    const response = await app.request(`/v1/funding/transfers/${record.id}`, {
+      headers: { 'tempo-api-key': fundingReader.token },
+    })
+    expect(response.status).toBe(200)
+    expect({
+      cacheControl: response.headers.get('cache-control'),
+      etag: response.headers.get('etag'),
+    }).toMatchInlineSnapshot(`
+      {
+        "cacheControl": "no-store",
+        "etag": null,
+      }
+    `)
+    expect(response.headers.get('vary')).toBe(
+      'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key',
+    )
+    const body = await TestApp.json(response, Funding.schema.getFundingTransfer.Response)
+    expect(body).toEqual(FundingTransfer.toPublic(record))
+    expect('action' in body).toBe(false)
+
+    const repeated = await app.request(`/v1/funding/transfers/${record.id}`, {
+      headers: { 'if-none-match': '"stale"', 'tempo-api-key': fundingReader.token },
+    })
+    expect({
+      cacheControl: repeated.headers.get('cache-control'),
+      etag: repeated.headers.get('etag'),
+      status: repeated.status,
+    }).toMatchInlineSnapshot(`
+      {
+        "cacheControl": "no-store",
+        "etag": null,
+        "status": 200,
+      }
+    `)
+  })
+
+  test('hides foreign and absent transfers behind the same 404', async () => {
+    const app = transfersApp()
+    const record = await seedTransfer()
+
+    const foreign = await app.request(`/v1/funding/transfers/${record.id}`, as(fundingForeign))
+    expect(foreign.status).toBe(404)
+    expect(((await foreign.json()) as { error: { code: string } }).error.code).toBe(
+      'funding_transfer_not_found',
+    )
+
+    const project = await app.request(
+      `/v1/funding/transfers/${record.id}`,
+      as(fundingProjectReader),
+    )
+    expect(project.status).toBe(404)
+
+    const absent = await app.request(
+      '/v1/funding/transfers/ftr_000000000000000_000000000000000000000000',
+      as(fundingReader),
+    )
+    expect(absent.status).toBe(404)
+  })
+})
+
+const createBody = {
+  amount: '1000000',
+  destinationToken: '0x20c0000000000000000000000000000000000000',
+  mode: 'exactSource',
+  recipient: `0x${'11'.repeat(20)}`,
+  sender: `0x${'22'.repeat(20)}`,
+  slippageBps: 300,
+  sourceChain: 'base',
+  sourceToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+}
+
+const vaultTransferBody = {
+  amount: createBody.amount,
+  mode: createBody.mode,
+  recipient: createBody.recipient,
+  sender: createBody.sender,
+  slippageBps: createBody.slippageBps,
+  sourceChain: createBody.sourceChain,
+  sourceToken: createBody.sourceToken,
+  vaultAddress: `0x${'f4'.repeat(20)}`,
+}
+
+const zoneTransferBody = {
+  amount: createBody.amount,
+  destinationChain: 'eip155:421700001',
+  destinationToken: createBody.destinationToken,
+  mode: createBody.mode,
+  recipient: createBody.recipient,
+  recipientFallback: `0x${'33'.repeat(20)}`,
+  sender: createBody.sender,
+  slippageBps: createBody.slippageBps,
+  sourceChain: createBody.sourceChain,
+  sourceToken: createBody.sourceToken,
+}
+
+function postTransfer(
+  app: ReturnType<typeof create>,
+  options: { body?: unknown; idempotencyKey?: string | undefined; key?: { token: string } } = {},
+) {
+  return app.request('/v1/funding/transfers', {
+    body: JSON.stringify(options.body ?? createBody),
+    headers: {
+      authorization: `Bearer ${(options.key ?? fundingWriter).token}`,
+      'content-type': 'application/json',
+      ...(options.idempotencyKey === undefined
+        ? {}
+        : { 'idempotency-key': options.idempotencyKey }),
+    },
+    method: 'POST',
+  })
+}
+
+describe('POST /funding/transfers', () => {
+  function providerResponse(): FundingProvider.prepareTransfer.ReturnType {
+    const spender = `0x${'44'.repeat(20)}`
+    return {
+      action: {
+        calls: [
+          {
+            data: `0x095ea7b3${spender.slice(2).padStart(64, '0')}${(1_000_000).toString(16).padStart(64, '0')}`,
+            to: createBody.sourceToken,
+            value: '0x0',
+          },
+          { data: '0xe8017952', to: spender, value: '0x0' },
+        ],
+        type: 'evm:calls',
+      },
+      correlation: { requestId: `0x${'ab'.repeat(32)}` },
+      fees: [{ amount: '21050', side: 'source' }],
+      destinationAmountMin: '980000',
+      destinationAmount: '990000',
+      quality: {
+        estimatedSeconds: 4,
+        liquiditySource: 'providerQuote',
+        sourceDetail: 'relay:quote-v2',
+        tier: 'liquid',
+      },
+      sampledAt: '2099-01-01T00:00:00.000Z',
+    }
+  }
+
+  function provider(
+    prepareTransfer: NonNullable<FundingProvider.Provider['prepareTransfer']> = async () =>
+      providerResponse(),
+  ) {
+    return FundingProvider.from({
+      ...Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+      prepareTransfer,
+    })
+  }
+
+  let idempotencySequence = 0
+  function nextIdempotencyKey() {
+    return `funding_test_${idempotencySequence++}`
+  }
+
+  test('requires funding:write and an Idempotency-Key', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const forbidden = await postTransfer(app, {
+      idempotencyKey: nextIdempotencyKey(),
+      key: fundingReader,
+    })
+    expect(forbidden.status).toBe(403)
+
+    const missing = await postTransfer(app)
+    expect(missing.status).toBe(400)
+    expect(((await missing.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_key_required',
+    )
+  })
+
+  test('creates a transfer with the selected executable quote', async () => {
+    const inputs: FundingProvider.prepareTransfer.Parameters[] = []
+    const app = transfersApp({
+      providers: [
+        provider(async (input) => {
+          inputs.push(input)
+          return providerResponse()
+        }),
+      ],
+    })
+    const response = await postTransfer(app, {
+      body: { ...createBody, destinationToken: 'pathusd', sourceToken: 'usdc' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    const body = await TestApp.json(response, Funding.schema.createFundingTransfer.Response)
+
+    expect(inputs[0]).toMatchObject({
+      method: 'transaction',
+      mode: 'exactSource',
+      recipient: createBody.recipient,
+      sender: createBody.sender,
+      slippageBps: 300,
+    })
+    expect(body).toMatchObject({
+      action: { type: 'evm:calls' },
+      destinationAmountMin: { baseUnits: '980000' },
+      method: 'transaction',
+      mode: 'exactSource',
+      provider: { id: 'relay' },
+      // The provider returned no expiry, so the default validity window applies.
+      quote: { expiresAt: '2099-01-01T00:01:00.000Z', sampledAt: '2099-01-01T00:00:00.000Z' },
+      sourceAmount: { baseUnits: '1000000' },
+      status: 'awaiting-source',
+      version: 1,
+    })
+    expect(body.fees[0]).toMatchObject({ side: 'source', token: { symbol: 'USDC' } })
+
+    // Reads return the same transfer without the action; the private
+    // correlation never leaves the row.
+    const read = await app.request(`/v1/funding/transfers/${body.id}`, as(fundingWriter))
+    const readBody = await TestApp.json(read, Funding.schema.getFundingTransfer.Response)
+    expect('action' in readBody).toBe(false)
+    expect(JSON.stringify(readBody)).not.toContain('ab'.repeat(32))
+    const row = await db.kysely
+      .selectFrom('funding_transfers')
+      .select(['providerState'])
+      .where('id', '=', body.id)
+      .executeTakeFirstOrThrow()
+    expect(row.providerState).toEqual({ requestId: `0x${'ab'.repeat(32)}` })
+  })
+
+  test('resolves token identifiers through the composed route', async () => {
+    const app = transfersApp({ providers: [provider()] })
+    const identifiers = [
+      { destinationToken: 'pathusd', name: 'alias', sourceToken: 'usdc' },
+      {
+        destinationToken: createBody.destinationToken,
+        name: 'address',
+        sourceToken: createBody.sourceToken,
+      },
+      {
+        destinationToken: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
+        name: 'token key',
+        sourceToken: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+      },
+    ] as const
+    const results = []
+    for (const identifier of identifiers) {
+      const response = await postTransfer(app, {
+        body: {
+          ...createBody,
+          destinationToken: identifier.destinationToken,
+          sourceToken: identifier.sourceToken,
+        },
+        idempotencyKey: nextIdempotencyKey(),
+      })
+      const body = await TestApp.json(response, Funding.schema.createFundingTransfer.Response)
+      results.push({
+        destinationToken: body.destinationToken.symbol,
+        name: identifier.name,
+        sourceToken: body.sourceToken.symbol,
+        status: response.status,
+      })
+    }
+
+    expect(results).toMatchInlineSnapshot(`
+      [
+        {
+          "destinationToken": "pathUSD",
+          "name": "alias",
+          "sourceToken": "USDC",
+          "status": 200,
+        },
+        {
+          "destinationToken": "pathUSD",
+          "name": "address",
+          "sourceToken": "USDC",
+          "status": 200,
+        },
+        {
+          "destinationToken": "pathUSD",
+          "name": "token key",
+          "sourceToken": "USDC",
+          "status": 200,
+        },
+      ]
+    `)
+  })
+
+  test('replays the exact response for the same key and body', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    const first = await postTransfer(app, { idempotencyKey })
+    const second = await postTransfer(app, { idempotencyKey })
+    expect(second.status).toBe(200)
+    expect(await second.json()).toEqual(await first.json())
+  })
+
+  test('rejects a reused key with different input', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    await postTransfer(app, { idempotencyKey })
+    const conflict = await postTransfer(app, {
+      body: { ...createBody, amount: '2000000' },
+      idempotencyKey,
+    })
+    expect(conflict.status).toBe(409)
+    expect(((await conflict.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_conflict',
+    )
+  })
+
+  test('rejects an equivalent request while the first is running', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    await FundingIdempotencyTable.claim(db, {
+      apiKeyId: fundingWriter.id,
+      keyHash: Idempotency.inputHash(idempotencyKey),
+      requestHash: Idempotency.inputHash(createBody),
+      ttlMs: 60_000,
+    })
+    const pending = await postTransfer(app, { idempotencyKey })
+    expect(pending.status).toBe(409)
+    expect(((await pending.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_in_progress',
+    )
+  })
+
+  test('rolls back creation after losing the idempotency lease', async () => {
+    const idempotencyKey = nextIdempotencyKey()
+    const keyHash = Idempotency.inputHash(idempotencyKey)
+    const before = await db.kysely
+      .selectFrom('funding_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    const app = transfersApp({
+      providers: [
+        provider(async () => {
+          await db.kysely
+            .updateTable('funding_idempotency_requests')
+            .set({ expiresAt: new Date(0).toISOString() })
+            .where('apiKeyId', '=', fundingWriter.id)
+            .where('keyHash', '=', keyHash)
+            .execute()
+          await FundingIdempotencyTable.claim(db, {
+            apiKeyId: fundingWriter.id,
+            keyHash,
+            requestHash: Idempotency.inputHash(createBody),
+            ttlMs: 60_000,
+          })
+          return providerResponse()
+        }),
+      ],
+    })
+
+    const response = await postTransfer(app, { idempotencyKey })
+    expect(response.status).toBe(500)
+    const after = await db.kysely
+      .selectFrom('funding_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    expect(after.count).toBe(before.count)
+  })
+
+  test('rejects non-account fields and gates disabled corridors and methods', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+
+    const ignoredRefund = await postTransfer(app, {
+      body: { ...createBody, refundAddress: createBody.sender },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(ignoredRefund.status).toBe(400)
+    expect(((await ignoredRefund.json()) as { error: { code: string } }).error.code).toBe(
+      'body_invalid',
+    )
+
+    const unsupportedDestination = await postTransfer(app, {
+      body: { ...createBody, destinationVault: `0x${'f4'.repeat(20)}`, type: 'vault' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(unsupportedDestination.status).toBe(400)
+    expect(((await unsupportedDestination.json()) as { error: { code: string } }).error.code).toBe(
+      'body_invalid',
+    )
+
+    const unknownToken = await postTransfer(app, {
+      body: { ...createBody, destinationToken: `0x${'99'.repeat(20)}` },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(unknownToken.status).toBe(404)
+  })
+
+  test('releases the claim after a provider failure', async () => {
+    const failing = transfersApp({
+      providers: [
+        provider(async () => {
+          throw new Error('upstream unavailable')
+        }),
+      ],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    const failed = await postTransfer(failing, { idempotencyKey })
+    expect(failed.status).toBe(502)
+    expect(((await failed.json()) as { error: { code: string } }).error.code).toBe('upstream_error')
+
+    // The key was released, so the same request retries successfully.
+    const working = transfersApp({
+      providers: [provider()],
+    })
+    expect((await postTransfer(working, { idempotencyKey })).status).toBe(200)
+  })
+
+  test('rejects preparations with unbounded approvals', async () => {
+    const app = transfersApp({
+      providers: [
+        provider(async () => {
+          const result = providerResponse()
+          const spender = `0x${'44'.repeat(20)}`
+          return {
+            ...result,
+            action: {
+              calls: [
+                {
+                  data: `0x095ea7b3${spender.slice(2).padStart(64, '0')}${'f'.repeat(64)}`,
+                  to: createBody.sourceToken,
+                  value: '0x0',
+                },
+              ],
+              type: 'evm:calls',
+            },
+          }
+        }),
+      ],
+    })
+    const response = await postTransfer(app, { idempotencyKey: nextIdempotencyKey() })
+    expect(response.status).toBe(502)
+  })
+})
+
+describe.skipIf(!Anvil.available)('POST /funding/transfers (forked localnet)', () => {
+  /**
+   * Storage slot of Circle FiatToken's `balanceAndBlacklistStates` mapping.
+   * `anvil_dealERC20` cannot probe it because balances pack a blacklist bit,
+   * so the fork suite writes the slot directly. Every curated USDC is a
+   * FiatToken.
+   */
+  const fiatTokenBalanceSlot = 9n
+
+  for (const executable of executableProviders) {
+    describe(executable.id, () => {
+      const route = TestFunding.snapshot.routes.find(
+        (entry) =>
+          entry.route.source.chain.id === `eip155:${base.id}` &&
+          entry.route.source.symbol === 'USDC' &&
+          entry.route.destination.slug === 'pathusd',
+      )!
+      const usdc = route.route.source
+      const amount = Value.from('10', usdc.decimals)
+      const sender = Anvil.getAccount(0)
+
+      let anvil: Anvil.start.ReturnType
+
+      beforeAll(async () => {
+        anvil = await Anvil.start({ chain: base, forkUrl: base.rpcUrls.default.http[0]! })
+      })
+
+      afterAll(async () => {
+        await anvil?.stop()
+      })
+
+      function createTransfer(idempotencyKey: string) {
+        const app = transfersApp({ providers: [executable.create(sender.address)] })
+        return postTransfer(app, {
+          body: { ...createBody, amount: amount.toString(), sender: sender.address },
+          idempotencyKey,
+        })
+      }
+
+      test('executes the prepared calls and returns successful receipts', async () => {
+        const { client } = anvil
+        await Anvil.setErc20Balance(client, {
+          address: sender.address,
+          amount,
+          slot: fiatTokenBalanceSlot,
+          token: usdc.address as `0x${string}`,
+        })
+
+        const response = await createTransfer(`bridge_${executable.id}_${sender.address}`)
+        expect(response.status).toBe(200)
+        const transfer = await TestApp.json(response, Funding.schema.createFundingTransfer.Response)
+        expect(transfer.action.type).toBe('evm:calls')
+        if (transfer.action.type !== 'evm:calls') return
+        expect(transfer.action.calls.length).toBeGreaterThan(0)
+
+        const receipts = []
+        for (const call of transfer.action.calls) {
+          receipts.push(
+            await client.sendTransactionSync({
+              account: sender,
+              data: call.data as `0x${string}`,
+              to: call.to as `0x${string}`,
+              value: BigInt(call.value),
+            }),
+          )
+        }
+
+        expect(receipts.map((receipt) => receipt.status)).toEqual(
+          transfer.action.calls.map(() => 'success'),
+        )
+        // The deposit is the last call and must emit; an approval alone proves nothing.
+        expect(receipts.at(-1)!.logs.length).toBeGreaterThan(0)
+      })
+
+      test('bounds the approval to the quoted source spend', async () => {
+        const response = await createTransfer(`bridge_bounds_${executable.id}_${sender.address}`)
+        expect(response.status).toBe(200)
+        const transfer = await TestApp.json(response, Funding.schema.createFundingTransfer.Response)
+        if (transfer.action.type !== 'evm:calls') return
+
+        const approval = transfer.action.calls.find((call) =>
+          call.data.toLowerCase().startsWith('0x095ea7b3'),
+        )
+        expect(approval).toBeDefined()
+        if (!approval) return
+
+        // Decoded from the live action, so a provider that starts returning
+        // an unlimited allowance fails here.
+        const decoded = decodeFunctionData({ abi: erc20Abi, data: approval.data as `0x${string}` })
+        expect(decoded.functionName).toBe('approve')
+        if (decoded.functionName !== 'approve') return
+        const [, approved] = decoded.args
+        expect(approved).toBeLessThanOrEqual(BigInt(transfer.sourceAmount.baseUnits))
+        expect(approved).toBeLessThan(maxUint256)
+      })
+    })
+  }
+})
+
+describe('POST /funding/transfers/{destination}', () => {
+  test.each([
+    { body: vaultTransferBody, destination: 'vault' },
+    { body: zoneTransferBody, destination: 'zone' },
+  ] as const)('validates and returns 501 for $destination transfers', async (options) => {
+    const app = transfersApp()
+    const before = await db.kysely
+      .selectFrom('funding_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    const response = await app.request(`/v1/funding/transfers/${options.destination}`, {
+      body: JSON.stringify(options.body),
+      headers: {
+        authorization: `Bearer ${fundingWriter.token}`,
+        'content-type': 'application/json',
+        'idempotency-key': `funding_${options.destination}_unimplemented`,
+      },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(501)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect(((await response.json()) as { error: { code: string } }).error.code).toBe(
+      'not_implemented',
+    )
+    const after = await db.kysely
+      .selectFrom('funding_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    expect(after.count).toBe(before.count)
+  })
+
+  test('requires the header and validates destination fields', async () => {
+    const app = transfersApp()
+    const missingHeader = await app.request('/v1/funding/transfers/vault', {
+      body: JSON.stringify(vaultTransferBody),
+      headers: {
+        authorization: `Bearer ${fundingWriter.token}`,
+        'content-type': 'application/json',
+      },
+      method: 'POST',
+    })
+    expect(missingHeader.status).toBe(400)
+    expect(((await missingHeader.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_key_required',
+    )
+
+    const invalidZone = await app.request('/v1/funding/transfers/zone', {
+      body: JSON.stringify({ ...zoneTransferBody, destinationChain: '421700001' }),
+      headers: {
+        authorization: `Bearer ${fundingWriter.token}`,
+        'content-type': 'application/json',
+        'idempotency-key': 'funding_zone_invalid',
+      },
+      method: 'POST',
+    })
+    expect(invalidZone.status).toBe(400)
+    expect(((await invalidZone.json()) as { error: { code: string } }).error.code).toBe(
+      'body_invalid',
+    )
+  })
+})
+
+describe('funding transfers OpenAPI', () => {
+  test('publishes an executable account transfer example', async () => {
+    const app = create({ auth: false })
+    type TokenSchema = { examples: string[] }
+    type TransferExample = { destinationToken: { address: string } }
+    type Operation = {
+      requestBody: {
+        content: Record<string, { schema: { properties: { destinationToken: TokenSchema } } }>
+      }
+      responses: Record<string, { content: Record<string, { example: TransferExample }> }>
+    }
+    type Spec = { paths: Record<string, { post: Operation }> }
+    const spec = (await (await app.request('/openapi.json')).json()) as Spec
+    const operation = spec.paths['/v1/funding/transfers']!.post
+
+    expect({
+      request:
+        operation.requestBody.content['application/json']!.schema.properties.destinationToken
+          .examples,
+      response:
+        operation.responses['200']!.content['application/json']!.example.destinationToken.address,
+    }).toEqual({
+      request: ['pathusd'],
+      response: '0x20c0000000000000000000000000000000000000',
+    })
+  })
+
+  test('publishes human-readable deposit address route examples', async () => {
+    const app = create({ auth: false })
+    type Property = { examples: string[] }
+    type Operation = {
+      requestBody: {
+        content: Record<
+          string,
+          {
+            schema: {
+              properties: {
+                destinationToken: Property
+                sourceChain: Property
+                sourceToken: Property
+              }
+            }
+          }
+        >
+      }
+    }
+    type Spec = { paths: Record<string, { post: Operation }> }
+    const spec = (await (await app.request('/openapi.json')).json()) as Spec
+    const properties =
+      spec.paths['/v1/funding/deposit-addresses']!.post.requestBody.content['application/json']!
+        .schema.properties
+
+    expect({
+      destinationToken: properties.destinationToken.examples,
+      sourceChain: properties.sourceChain.examples,
+      sourceToken: properties.sourceToken.examples,
+    }).toMatchInlineSnapshot(`
+      {
+        "destinationToken": [
+          "usdt0",
+        ],
+        "sourceChain": [
+          "tron",
+          "tron:0x2b6653dc",
+        ],
+        "sourceToken": [
+          "usdt",
+        ],
+      }
+    `)
+  })
+
+  test('publishes concise operation documentation', async () => {
+    const app = create({ auth: false })
+    type Operation = { description: string; summary: string; tags: string[] }
+    type Spec = {
+      paths: Record<string, { get?: Operation; post?: Operation }>
+      tags: { description?: string; name: string }[]
+      'x-tagGroups': { name: string; tags: string[] }[]
+    }
+    const spec = (await (await app.request('/openapi.json')).json()) as Spec
+    const detailPath = Object.keys(spec.paths).find((path) =>
+      path.includes('/v1/funding/transfers/{'),
+    )!
+    const depositAddressPath = Object.keys(spec.paths).find(
+      (path) =>
+        path.includes('/v1/funding/deposit-addresses/{') &&
+        !path.endsWith('/deposits') &&
+        !path.endsWith('/reconcile'),
+    )!
+    const depositPath = Object.keys(spec.paths).find((path) =>
+      path.includes('/v1/funding/deposits/{'),
+    )!
+    const reconcilePath = Object.keys(spec.paths).find((path) => path.endsWith('/reconcile'))!
+    const summarize = (operation: Operation) => ({
+      description: operation.description,
+      summary: operation.summary,
+    })
+    const operations = {
+      account: summarize(spec.paths['/v1/funding/transfers']!.post!),
+      chains: summarize(spec.paths['/v1/funding/chains']!.get!),
+      deposit: summarize(spec.paths[depositPath]!.get!),
+      depositAddress: summarize(spec.paths[depositAddressPath]!.get!),
+      depositAddressCreate: summarize(spec.paths['/v1/funding/deposit-addresses']!.post!),
+      depositAddressReconcile: summarize(spec.paths[reconcilePath]!.post!),
+      deposits: summarize(spec.paths['/v1/funding/deposits']!.get!),
+      detail: summarize(spec.paths[detailPath]!.get!),
+      list: summarize(spec.paths['/v1/funding/transfers']!.get!),
+      providers: summarize(spec.paths['/v1/funding/providers']!.get!),
+      quotes: summarize(spec.paths['/v1/funding/quotes']!.get!),
+      vault: summarize(spec.paths['/v1/funding/transfers/vault']!.post!),
+      zone: summarize(spec.paths['/v1/funding/transfers/zone']!.post!),
+    }
+    const category = spec['x-tagGroups'].find((group) => group.name === 'Funding & Bridge API')
+    const categoryTags = new Set(category?.tags)
+    const sidebar = Object.values(spec.paths).flatMap((path) =>
+      [path.get, path.post].flatMap((operation) =>
+        operation?.tags.some((tag) => categoryTags.has(tag)) ? [operation.summary] : [],
+      ),
+    )
+
+    for (const operation of Object.values(operations))
+      expect(operation.description.split(/\s+/).length).toBeLessThan(15)
+
+    expect({
+      category: category?.name,
+      operations,
+      sidebar,
+    }).toMatchInlineSnapshot(`
+      {
+        "category": "Funding & Bridge API",
+        "operations": {
+          "account": {
+            "description": "Creates a transfer to a Tempo account.",
+            "summary": "Create transfer",
+          },
+          "chains": {
+            "description": "Lists supported source chains and tokens.",
+            "summary": "Get chains",
+          },
+          "deposit": {
+            "description": "Returns one detected deposit and its delivery status.",
+            "summary": "Get deposit",
+          },
+          "depositAddress": {
+            "description": "Returns one reusable funding deposit address.",
+            "summary": "Get deposit address",
+          },
+          "depositAddressCreate": {
+            "description": "Creates or returns a reusable deposit address for funding a Tempo account.",
+            "summary": "Create deposit address",
+          },
+          "depositAddressReconcile": {
+            "description": "Queues an immediate provider reconciliation for one reusable funding deposit address.",
+            "summary": "Reconcile deposit address",
+          },
+          "deposits": {
+            "description": "Lists deposits by deposit address or Tempo recipient, newest first.",
+            "summary": "List deposits",
+          },
+          "detail": {
+            "description": "Returns a transfer by ID.",
+            "summary": "Get transfer",
+          },
+          "list": {
+            "description": "Lists transfers from newest to oldest.",
+            "summary": "List transfers",
+          },
+          "providers": {
+            "description": "Lists available transfer providers.",
+            "summary": "Get providers",
+          },
+          "quotes": {
+            "description": "Returns live quotes for transferring stablecoins to Tempo.",
+            "summary": "Get quotes",
+          },
+          "vault": {
+            "description": "Creates a transfer into a Tempo Earn vault.",
+            "summary": "Create transfer into vault",
+          },
+          "zone": {
+            "description": "Creates a transfer into a Tempo Zone.",
+            "summary": "Create transfer into zone",
+          },
+        },
+        "sidebar": [
+          "Get quotes",
+          "Get chains",
+          "Get providers",
+          "Create deposit address",
+          "List transfers",
+          "Create transfer",
+          "Create transfer into vault",
+          "Create transfer into zone",
+          "Reconcile deposit address",
+          "Get deposit address",
+          "Get transfer",
+          "Get deposit",
+          "List deposits",
+        ],
+      }
+    `)
+  })
+
+  test('publishes concrete creation schemas', async () => {
+    const app = create({ auth: false })
+    const spec = (await (await app.request('/openapi.json')).json()) as {
+      paths: Record<
+        string,
+        {
+          post?: {
+            requestBody: {
+              content: Record<
+                string,
+                {
+                  schema: {
+                    additionalProperties?: boolean
+                    properties: object
+                    required?: readonly string[] | undefined
+                  }
+                }
+              >
+            }
+            responses: Record<string, unknown>
+          }
+        }
+      >
+    }
+    const creationSchema = (path: string) =>
+      spec.paths[path]!.post!.requestBody.content['application/json']!.schema
+    expect(
+      creationSchema('/v1/funding/deposit-addresses').required?.includes('subsidize') ?? false,
+    ).toMatchInlineSnapshot(`false`)
+    const summarize = (path: string) => {
+      const schema = creationSchema(path)
+      return {
+        additionalProperties: schema.additionalProperties,
+        properties: Object.keys(schema.properties),
+      }
+    }
+
+    expect({
+      account: summarize('/v1/funding/transfers'),
+      depositAddress: summarize('/v1/funding/deposit-addresses'),
+      depositAddressResponses: Object.keys(
+        spec.paths['/v1/funding/deposit-addresses']!.post!.responses,
+      ),
+      vault: summarize('/v1/funding/transfers/vault'),
+      vaultResponses: Object.keys(spec.paths['/v1/funding/transfers/vault']!.post!.responses),
+      zone: summarize('/v1/funding/transfers/zone'),
+      zoneResponses: Object.keys(spec.paths['/v1/funding/transfers/zone']!.post!.responses),
+    }).toMatchInlineSnapshot(`
+      {
+        "account": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "destinationToken",
+            "mode",
+            "recipient",
+            "sender",
+            "slippageBps",
+            "sourceChain",
+            "sourceToken",
+          ],
+        },
+        "depositAddress": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "destinationToken",
+            "recipient",
+            "refundAddress",
+            "sourceChain",
+            "sourceToken",
+            "subsidize",
+          ],
+        },
+        "depositAddressResponses": [
+          "200",
+          "400",
+          "401",
+          "404",
+          "409",
+          "429",
+          "500",
+          "502",
+        ],
+        "vault": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "mode",
+            "recipient",
+            "sender",
+            "slippageBps",
+            "sourceChain",
+            "sourceToken",
+            "vaultAddress",
+          ],
+        },
+        "vaultResponses": [
+          "400",
+          "401",
+          "429",
+          "500",
+          "501",
+        ],
+        "zone": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "destinationChain",
+            "destinationToken",
+            "mode",
+            "recipient",
+            "recipientFallback",
+            "sender",
+            "slippageBps",
+            "sourceChain",
+            "sourceToken",
+          ],
+        },
+        "zoneResponses": [
+          "400",
+          "401",
+          "429",
+          "500",
+          "501",
+        ],
+      }
+    `)
+  })
+
+  test('publishes alphabetically ordered example fields and parameter examples', async () => {
+    const app = create({ auth: false })
+    const spec = (await (await app.request('/openapi.json')).json()) as {
+      paths: Record<
+        string,
+        {
+          get: {
+            parameters?: { example?: unknown; name: string; schema?: { examples?: unknown } }[]
+            responses: Record<string, { content: Record<string, { example: { data: {}[] } }> }>
+          }
+        }
+      >
+    }
+    const operation = spec.paths['/v1/funding/transfers']!.get
+    const fields = Object.keys(operation.responses['200']!.content['application/json']!.example.data[0]!) // prettier-ignore
+    expect(fields).toEqual([...fields].sort())
+    for (const route of [operation, spec.paths['/v1/funding/deposits']!.get])
+      for (const parameter of route.parameters ?? [])
+        expect(parameter.example ?? parameter.schema?.examples, parameter.name).toBeDefined()
+  })
+
+  test('publishes operation ids and required scopes', async () => {
+    const app = create({ auth: false })
+    const spec = (await (await app.request('/openapi.json')).json()) as {
+      paths: Record<
+        string,
+        {
+          get: { operationId: string; 'x-required-scopes': string[] }
+          post?: {
+            operationId: string
+            parameters: { in: string; name: string; required: boolean }[]
+            'x-required-scopes': string[]
+          }
+        }
+      >
+    }
+    const detailPath = Object.keys(spec.paths).find((path) =>
+      path.includes('/v1/funding/transfers/{'),
+    )
+    const depositAddressPath = Object.keys(spec.paths).find(
+      (path) =>
+        path.includes('/v1/funding/deposit-addresses/{') &&
+        !path.endsWith('/deposits') &&
+        !path.endsWith('/reconcile'),
+    )
+    const depositPath = Object.keys(spec.paths).find((path) =>
+      path.includes('/v1/funding/deposits/{'),
+    )
+    const reconcilePath = Object.keys(spec.paths).find((path) => path.endsWith('/reconcile'))
+    expect({
+      deposit: depositPath && spec.paths[depositPath]?.get.operationId,
+      depositAddress: depositAddressPath && spec.paths[depositAddressPath]?.get.operationId,
+      depositAddressCreate: spec.paths['/v1/funding/deposit-addresses']?.post?.operationId,
+      depositAddressCreateScopes:
+        spec.paths['/v1/funding/deposit-addresses']?.post?.['x-required-scopes'],
+      depositAddressReconcile: reconcilePath && spec.paths[reconcilePath]?.post?.operationId,
+      depositAddressReconcileScopes:
+        reconcilePath && spec.paths[reconcilePath]?.post?.['x-required-scopes'],
+      depositAddressScopes:
+        depositAddressPath && spec.paths[depositAddressPath]?.get['x-required-scopes'],
+      depositScopes: depositPath && spec.paths[depositPath]?.get['x-required-scopes'],
+      deposits: spec.paths['/v1/funding/deposits']?.get.operationId,
+      depositsScopes: spec.paths['/v1/funding/deposits']?.get['x-required-scopes'],
+      detail: detailPath && spec.paths[detailPath]?.get.operationId,
+      detailScopes: detailPath && spec.paths[detailPath]?.get['x-required-scopes'],
+      list: spec.paths['/v1/funding/transfers']?.get.operationId,
+      listScopes: spec.paths['/v1/funding/transfers']?.get['x-required-scopes'],
+      requiredCreateHeader: spec.paths['/v1/funding/transfers']?.post?.parameters.find(
+        (parameter) => parameter.name === 'idempotency-key',
+      ),
+      vault: spec.paths['/v1/funding/transfers/vault']?.post?.operationId,
+      vaultScopes: spec.paths['/v1/funding/transfers/vault']?.post?.['x-required-scopes'],
+      zone: spec.paths['/v1/funding/transfers/zone']?.post?.operationId,
+      zoneScopes: spec.paths['/v1/funding/transfers/zone']?.post?.['x-required-scopes'],
+    }).toEqual({
+      deposit: 'getFundingDeposit',
+      depositAddress: 'getFundingDepositAddress',
+      depositAddressCreate: 'createFundingDepositAddress',
+      depositAddressCreateScopes: ['funding:write'],
+      depositAddressReconcile: 'reconcileFundingDepositAddress',
+      depositAddressReconcileScopes: ['funding:write'],
+      depositAddressScopes: ['funding:read'],
+      depositScopes: ['funding:read'],
+      deposits: 'listFundingDeposits',
+      depositsScopes: ['funding:read'],
+      detail: 'getFundingTransfer',
+      detailScopes: ['funding:read'],
+      list: 'listFundingTransfers',
+      listScopes: ['funding:read'],
+      requiredCreateHeader: expect.objectContaining({
+        description: expect.stringContaining('24 hours'),
+        in: 'header',
+        name: 'idempotency-key',
+        required: true,
+        schema: expect.any(Object),
+      }),
+      vault: 'createFundingTransferVault',
+      vaultScopes: ['funding:write'],
+      zone: 'createFundingTransferZone',
+      zoneScopes: ['funding:write'],
+    })
+  })
+})
+
+const fundingReader = {
+  id: 'key_funding',
+  orgId: 'org_funding',
+  scopes: ['funding:read'],
+  token: 'secret_funding_reader',
+} satisfies TestApp.kvStore.Key
+
+const fundingProjectReader = {
+  id: 'key_funding_project',
+  orgId: 'org_funding',
+  projectId: 'prj_funding',
+  scopes: ['funding:read'],
+  token: 'secret_funding_project',
+} satisfies TestApp.kvStore.Key
+
+const fundingForeign = {
+  id: 'key_funding_other',
+  orgId: 'org_funding_other',
+  scopes: ['funding:read'],
+  token: 'secret_funding_other',
+} satisfies TestApp.kvStore.Key
+
+const fundingWriter = {
+  id: 'key_funding_writer',
+  orgId: 'org_funding',
+  scopes: ['funding:read', 'funding:write'],
+  token: 'secret_funding_writer',
+} satisfies TestApp.kvStore.Key
+
+function transfersApp(options: TestApp.create.Options = {}) {
+  return create({
+    ...options,
+    auth: {
+      keys: [TestApp.key, fundingReader, fundingProjectReader, fundingForeign, fundingWriter],
+    },
+    defaultChainId: options.defaultChainId ?? tempoMainnet.id,
+  })
+}
+
+function as(key: { token: string }) {
+  return { headers: { authorization: `Bearer ${key.token}` } } as const
+}
+
+let seedSecond = 0
+
+function seedTransfer(input: Partial<FundingTransfer.create.Input> = {}) {
+  // Distinct create times keep ids strictly ordered for paging assertions.
+  return FundingTransfer.create(db, {
+    apiKeyId: fundingReader.id,
+    environment: 'production',
+    id: FundingTransfer.generateId(new Date(Date.UTC(2026, 0, 2, 0, 0, seedSecond++))),
+    orgId: fundingReader.orgId,
+    snapshot: TestFunding.transferSnapshot(),
+    ...input,
+  })
+}