tapimo 0.12.0 → 0.14.0

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

@@ -4,34 +4,42 @@ import { base } from 'viem/chains'
 import { tempoMainnet } from 'viem/tempo/chains'
 
 import * as Anvil from '../../../../test/Anvil.js'
+import * as TestApp from '../../../../test/App.js'
+import * as TestFunding from '../../../../test/Funding.js'
 import * as FundingIdempotencyTable from '../../../db/tables/fundingIdempotency.js'
-
 import * as Cache from '../../../internal/Cache.js'
-
+import * as FundingCatalog from '../../../internal/funding/Catalog.js'
+import * as FundingChain from '../../../internal/funding/Chain.js'
 import * as FundingProvider from '../../../internal/funding/Provider.js'
-
 import * as FundingTransfer from '../../../internal/funding/Transfer.js'
-
+import * as FundingTransferReconciliation from '../../../internal/funding/TransferReconciliation.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 Stargate from '../../../internal/funding/providers/stargate.js'
+import * as Webhooks from '../../../internal/Webhooks.js'
 import * as Funding from './transfers.js'
 
 const db = TestApp.database()
+const destinationTransactionHash =
+  '0x3dfaba0a78b8f4bc09e55e05211c8120729e7b6879efe32613883befbca666da'
 
 /** 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 } : {}),
+    destinationToken: 'pathusd',
     id: 'relay',
   },
+  {
+    create: (_sender: string) => Stargate.stargate(),
+    destinationToken: 'usdce',
+    id: 'stargate',
+  },
 ] as const
+const stargateConfiguration = TestFunding.snapshot.routesByProvider
+  .get('stargate')!
+  .find((candidate) => candidate.route.source.chain.id === 'eip155:8453')!.configuration!
 
 beforeAll(() => TestFunding.publish(db))
 
@@ -39,6 +47,11 @@ function create(options: TestApp.create.Options = {}) {
   return TestApp.create({ ...options, db })
 }
 
+type ContractResponse = {
+  $ref?: string | undefined
+  content?: Record<string, { schema: unknown }> | undefined
+}
+
 type JsonSchema = {
   $ref?: string | undefined
   additionalProperties?: boolean | undefined
@@ -211,6 +224,54 @@ describe('GET /funding/transfers/:id', () => {
   })
 })
 
+describe('POST /funding/transfers/:id/source-transactions', () => {
+  test('requires funding write access and validates the transaction hash', async () => {
+    const app = transfersApp()
+    const transfer = await seedTransfer()
+    const path = `/v1/funding/transfers/${transfer.id}/source-transactions`
+    expect((await app.request(path, { method: 'POST' })).status).toBe(401)
+    expect((await app.request(path, { ...as(fundingReader), method: 'POST' })).status).toBe(403)
+    expect(
+      (
+        await app.request(path, {
+          body: JSON.stringify({ transactionHash: '0xinvalid' }),
+          headers: { ...as(fundingWriter).headers, 'content-type': 'application/json' },
+          method: 'POST',
+        })
+      ).status,
+    ).toBe(400)
+  })
+
+  test('reports when transfer reconciliation is not configured', async () => {
+    const app = transfersApp()
+    const transfer = await seedTransfer()
+    const response = await app.request(`/v1/funding/transfers/${transfer.id}/source-transactions`, {
+      body: JSON.stringify({ transactionHash: `0x${'aa'.repeat(32)}` }),
+      headers: { ...as(fundingWriter).headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+    expect(response.status).toBe(501)
+  })
+
+  test('does not expose a transfer owned by another organization', async () => {
+    const tracker = FundingTransferReconciliation.createTracker({ db })
+    const app = transfersApp({
+      funding: {
+        async dispatchTransferReconciliation(message) {
+          await tracker.reconcile(message)
+        },
+      },
+    })
+    const transfer = await seedTransfer()
+    const response = await app.request(`/v1/funding/transfers/${transfer.id}/source-transactions`, {
+      body: JSON.stringify({ transactionHash: `0x${'aa'.repeat(32)}` }),
+      headers: { ...as(fundingForeign).headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+    expect(response.status).toBe(404)
+  })
+})
+
 const createBody = {
   amount: '1000000',
   destinationToken: '0x20c0000000000000000000000000000000000000',
@@ -377,6 +438,103 @@ describe('POST /funding/transfers', () => {
     expect(row.providerState).toEqual({ requestId: `0x${'ab'.repeat(32)}` })
   })
 
+  test('dispatches staged webhook updates after creation commits', async () => {
+    const subscription = await Webhooks.createSubscription(db, {
+      chainId: tempoMainnet.id,
+      destination: { type: 'url', url: 'https://example.com/webhooks/funding-transfers' },
+      environment: 'production',
+      eventType: 'funding:transfer.updated',
+      filters: { status: 'awaiting-source' },
+      owner: { orgId: fundingWriter.orgId, type: 'api_key' },
+    })
+    const references: Webhooks.QueueReference[] = []
+    const app = transfersApp({
+      funding: {
+        async dispatchTransferUpdates(staged) {
+          const reference = staged[0]!
+          const queued = await db.kysely
+            .selectFrom('webhook_queue_events')
+            .select('eventId')
+            .where('eventId', '=', reference.eventId)
+            .where('subscriptionId', '=', reference.subscriptionId)
+            .executeTakeFirst()
+          expect(queued).toBeDefined()
+          references.push(...staged)
+          return staged.length
+        },
+      },
+      providers: [provider()],
+    })
+
+    const response = await postTransfer(app, { idempotencyKey: nextIdempotencyKey() })
+
+    expect(response.status).toBe(200)
+    expect(references).toEqual([{ eventId: expect.any(String), subscriptionId: subscription.id }])
+  })
+
+  test('creates a transfer with the requested provider', async () => {
+    const app = transfersApp({ providers: [provider()] })
+    const response = await postTransfer(app, {
+      body: { ...createBody, provider: 'relay' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Funding.schema.createFundingTransfer.Response)
+    expect(body.provider.id).toBe('relay')
+  })
+
+  test('rejects an unsupported provider', async () => {
+    const app = transfersApp({ providers: [provider()] })
+    const response = await postTransfer(app, {
+      body: { ...createBody, provider: 'bridge' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+
+    expect(response.status).toBe(400)
+    expect(((await response.json()) as { error: { code: string } }).error.code).toBe('body_invalid')
+  })
+
+  test('preserves a provider-specified native fee token', async () => {
+    const app = transfersApp({
+      providers: [
+        provider(async () => ({
+          ...providerResponse(),
+          fees: [
+            {
+              amount: '1000000000000000',
+              side: 'source',
+              token: {
+                address: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+                currency: 'ETH',
+                decimals: 18,
+                name: 'Ether',
+                standard: 'native',
+                symbol: 'ETH',
+                tokenKey: 'eip155:8453/slip44:60',
+                verified: true,
+              },
+            },
+          ],
+        })),
+      ],
+    })
+    const response = await postTransfer(app, {
+      body: { ...createBody, destinationToken: 'pathusd', sourceToken: 'usdc' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Funding.schema.createFundingTransfer.Response)
+
+    expect(body.fees).toMatchObject([
+      {
+        amount: { baseUnits: '1000000000000000', formatted: '0.001' },
+        side: 'source',
+        token: { standard: 'native', symbol: 'ETH' },
+      },
+    ])
+  })
+
   test('resolves token identifiers through the composed route', async () => {
     const app = transfersApp({ providers: [provider()] })
     const identifiers = [
@@ -608,7 +766,7 @@ describe.skipIf(!Anvil.available)('POST /funding/transfers (forked localnet)', (
         (entry) =>
           entry.route.source.chain.id === `eip155:${base.id}` &&
           entry.route.source.symbol === 'USDC' &&
-          entry.route.destination.slug === 'pathusd',
+          entry.route.destination.slug === executable.destinationToken,
       )!
       const usdc = route.route.source
       const amount = Value.from('10', usdc.decimals)
@@ -627,7 +785,12 @@ describe.skipIf(!Anvil.available)('POST /funding/transfers (forked localnet)', (
       function createTransfer(idempotencyKey: string) {
         const app = transfersApp({ providers: [executable.create(sender.address)] })
         return postTransfer(app, {
-          body: { ...createBody, amount: amount.toString(), sender: sender.address },
+          body: {
+            ...createBody,
+            amount: amount.toString(),
+            destinationToken: executable.destinationToken,
+            sender: sender.address,
+          },
           idempotencyKey,
         })
       }
@@ -647,6 +810,24 @@ describe.skipIf(!Anvil.available)('POST /funding/transfers (forked localnet)', (
         expect(transfer.action.type).toBe('evm:calls')
         if (transfer.action.type !== 'evm:calls') return
         expect(transfer.action.calls.length).toBeGreaterThan(0)
+        if (executable.id === 'stargate') {
+          expect(transfer.fees).toMatchObject([
+            {
+              amount: { baseUnits: BigInt(transfer.action.calls.at(-1)!.value).toString() },
+              side: 'source',
+              token: { standard: 'native', symbol: 'ETH' },
+            },
+          ])
+          const row = await db.kysely
+            .selectFrom('funding_transfers')
+            .select('providerState')
+            .where('id', '=', transfer.id)
+            .executeTakeFirstOrThrow()
+          expect(row.providerState).toEqual({
+            destinationBlockNumber: expect.stringMatching(/^\d+$/),
+            routeConfiguration: stargateConfiguration,
+          })
+        }
 
         const receipts = []
         for (const call of transfer.action.calls) {
@@ -665,8 +846,158 @@ describe.skipIf(!Anvil.available)('POST /funding/transfers (forked localnet)', (
         )
         // The deposit is the last call and must emit; an approval alone proves nothing.
         expect(receipts.at(-1)!.logs.length).toBeGreaterThan(0)
+        if (executable.id === 'stargate') {
+          const receipt = receipts.at(-1)!
+          const finalized = await client.getBlock({ blockTag: 'finalized' })
+          expect(receipt.blockNumber).toBeGreaterThan(finalized.number)
+          await expect(
+            Stargate.verifySourceTransaction({
+              configuration: stargateConfiguration,
+              destinationTokenAddress: transfer.destinationToken.address,
+              recipient: transfer.recipient,
+              sender: sender.address,
+              sourceAmount: transfer.sourceAmount.baseUnits,
+              sourceChain: FundingChain.from({
+                id: 'eip155:8453',
+                name: 'Base',
+                rpcUrls: [anvil.rpcUrl],
+                slug: 'base',
+              }),
+              sourceTokenAddress: transfer.sourceToken.address,
+              transactionHash: receipt.transactionHash,
+              validAfter: transfer.quote.sampledAt,
+            }),
+          ).resolves.toMatchObject({ type: 'verified' })
+        }
       })
 
+      if (executable.id === 'stargate')
+        test('reopens registration when the source transaction is reorged out', async () => {
+          await Anvil.setErc20Balance(anvil.client, {
+            address: sender.address,
+            amount,
+            slot: fiatTokenBalanceSlot,
+            token: usdc.address as `0x${string}`,
+          })
+          const response = await createTransfer(`bridge_reorg_${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
+
+          const checkpoint = await anvil.client.snapshot()
+          // Anvil increments fork timestamps instead of following wall time between tests.
+          const block = await anvil.client.getBlock()
+          const sampledAt = BigInt(Math.floor(Date.parse(transfer.quote.sampledAt) / 1_000))
+          if (block.timestamp < sampledAt)
+            await anvil.client.setNextBlockTimestamp({ timestamp: sampledAt })
+          let reverted = false
+          try {
+            const receipts = []
+            for (const call of transfer.action.calls)
+              receipts.push(
+                await anvil.client.sendTransactionSync({
+                  account: sender,
+                  data: call.data as `0x${string}`,
+                  to: call.to as `0x${string}`,
+                  value: BigInt(call.value),
+                }),
+              )
+            const sourceReceipt = receipts.at(-1)!
+            const transactionHash = sourceReceipt.transactionHash
+            await FundingCatalog.publish(db, {
+              ...TestFunding.data,
+              chains: TestFunding.data.chains.map((chain) =>
+                chain.id === 'eip155:8453' ? { ...chain, rpcUrls: [anvil.rpcUrl] } : chain,
+              ),
+            })
+            const messages: FundingTransferReconciliation.Message[] = []
+            const app = transfersApp({
+              funding: {
+                async dispatchTransferReconciliation(message) {
+                  messages.push(message)
+                },
+              },
+              providers: [Stargate.stargate()],
+            })
+            const registered = await app.request(
+              `/v1/funding/transfers/${transfer.id}/source-transactions`,
+              {
+                body: JSON.stringify({ transactionHash }),
+                headers: { ...as(fundingWriter).headers, 'content-type': 'application/json' },
+                method: 'POST',
+              },
+            )
+            expect(registered.status).toBe(200)
+            expect(messages).toEqual([
+              { transferId: transfer.id, type: 'funding:transfer:reconcile' },
+            ])
+
+            await anvil.client.revert({ id: checkpoint })
+            reverted = true
+            const tracker = FundingTransferReconciliation.createTracker({
+              db,
+              async dispatch(message) {
+                messages.push(message)
+              },
+            })
+            await expect(tracker.reconcile(messages[0]!)).resolves.toEqual({ type: 'pending' })
+            expect(messages[1]).toEqual({
+              attempt: 1,
+              transferId: transfer.id,
+              type: 'funding:transfer:reconcile',
+            })
+
+            const pending = await db.kysely
+              .selectFrom('funding_transfers')
+              .select(['snapshot', 'status', 'version'])
+              .where('id', '=', transfer.id)
+              .executeTakeFirstOrThrow()
+            expect({
+              sourceTransactionHashes: pending.snapshot.sourceTransactionHashes,
+              status: pending.status,
+              version: pending.version,
+            }).toEqual({
+              sourceTransactionHashes: [transactionHash],
+              status: 'processing',
+              version: 2,
+            })
+
+            await anvil.client.mine({ blocks: 128 })
+            const finalized = await anvil.client.getBlock({ blockTag: 'finalized' })
+            expect(finalized.number).toBeGreaterThanOrEqual(sourceReceipt.blockNumber)
+            await expect(tracker.reconcile(messages[1]!)).resolves.toEqual({ type: 'reopened' })
+
+            const record = await db.kysely
+              .selectFrom('funding_transfers')
+              .select(['snapshot', 'status', 'version'])
+              .where('id', '=', transfer.id)
+              .executeTakeFirstOrThrow()
+            expect({
+              sourceTransactionHashes: record.snapshot.sourceTransactionHashes,
+              status: record.status,
+              version: record.version,
+            }).toEqual({
+              sourceTransactionHashes: undefined,
+              status: 'awaiting-source',
+              version: 3,
+            })
+            expect(
+              await db.kysely
+                .selectFrom('funding_transfer_transactions')
+                .selectAll()
+                .where('transferId', '=', transfer.id)
+                .execute(),
+            ).toEqual([])
+          } finally {
+            if (!reverted) await anvil.client.revert({ id: checkpoint })
+            await TestFunding.publish(db)
+          }
+        })
+
       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)
@@ -692,6 +1023,195 @@ describe.skipIf(!Anvil.available)('POST /funding/transfers (forked localnet)', (
   }
 })
 
+describe.skipIf(!Anvil.available)(
+  'POST /funding/transfers/:id/source-transactions (forked localnet)',
+  () => {
+    const trackingDb = TestApp.database()
+    let destination: Anvil.start.ReturnType
+    let source: Anvil.start.ReturnType
+
+    beforeAll(async () => {
+      ;[destination, source] = await Promise.all([
+        Anvil.start({ chain: tempoMainnet, forkUrl: tempoMainnet.rpcUrls.default.http[0]! }),
+        Anvil.start({ chain: base, forkUrl: base.rpcUrls.default.http[0]! }),
+      ])
+      await FundingCatalog.publish(trackingDb, {
+        ...TestFunding.data,
+        chains: TestFunding.data.chains.map((chain) => {
+          if (chain.id === 'eip155:4217') return { ...chain, rpcUrls: [destination.rpcUrl] }
+          if (chain.id === 'eip155:8453') return { ...chain, rpcUrls: [source.rpcUrl] }
+          return chain
+        }),
+      })
+    })
+
+    afterAll(async () => {
+      await Promise.all([destination?.stop(), source?.stop()])
+    })
+
+    test('backfills legacy state and completes from destination evidence', async () => {
+      const destinationReceipt = await destination.client.getTransactionReceipt({
+        hash: destinationTransactionHash,
+      })
+      const sourceTransactionHash =
+        '0xfd71359adf5095f2ab512a19e0a2df6c8cc0db14ac8a52286d61287daabdccd4'
+      const sourceReceipt = await source.client.getTransactionReceipt({
+        hash: sourceTransactionHash,
+      })
+      const sourceBlock = await source.client.getBlock({ blockNumber: sourceReceipt.blockNumber })
+      const sampledAt = new Date(Number(sourceBlock.timestamp - 1n) * 1_000).toISOString()
+      const amount = {
+        baseUnits: '200000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '0.2',
+      } as const
+      const snapshot = {
+        ...TestFunding.transferSnapshot({
+          destinationAmount: amount,
+          destinationAmountMin: amount,
+          provider: { id: 'stargate', name: 'Stargate' },
+          recipient: '0x7212623e4cff9ad010d28aa065fad2bf58578783',
+          sender: '0x52b650a62e384f68880d0a1dc2b84dfed47d5660',
+          sourceAmount: amount,
+        }),
+        quote: {
+          expiresAt: new Date(Date.parse(sampledAt) + 60_000).toISOString(),
+          sampledAt,
+        },
+      }
+      const transfer = await FundingTransfer.create(trackingDb, {
+        apiKeyId: fundingWriter.id,
+        environment: 'production',
+        orgId: fundingWriter.orgId,
+        snapshot,
+      })
+      const tracker = FundingTransferReconciliation.createTracker({ db: trackingDb })
+      const messages: FundingTransferReconciliation.Message[] = []
+      let dispatchEnabled = true
+      const app = TestApp.create({
+        auth: { keys: [fundingWriter] },
+        db: trackingDb,
+        defaultChainId: tempoMainnet.id,
+        funding: {
+          async dispatchTransferReconciliation(message) {
+            if (!dispatchEnabled) throw new Error('reconciliation unavailable')
+            messages.push(message)
+          },
+        },
+        providers: [Stargate.stargate()],
+      })
+      const path = `/v1/funding/transfers/${transfer.id}/source-transactions`
+      const registration = {
+        body: JSON.stringify({
+          transactionHash: sourceTransactionHash,
+        }),
+        headers: { ...as(fundingWriter).headers, 'content-type': 'application/json' },
+        method: 'POST',
+      }
+      const response = await app.request(path, registration)
+      expect(response.status).toBe(200)
+      const registered = await TestApp.json(
+        response,
+        Funding.schema.registerFundingTransferSourceTransaction.Response,
+      )
+      expect({
+        sourceTransactionHashes: registered.sourceTransactionHashes,
+        status: registered.status,
+        version: registered.version,
+      }).toEqual({
+        sourceTransactionHashes: [
+          '0xfd71359adf5095f2ab512a19e0a2df6c8cc0db14ac8a52286d61287daabdccd4',
+        ],
+        status: 'processing',
+        version: 2,
+      })
+      const stored = await trackingDb.kysely
+        .selectFrom('funding_transfers')
+        .select('providerState')
+        .where('id', '=', transfer.id)
+        .executeTakeFirstOrThrow()
+      expect(stored).toEqual({
+        providerState: {
+          destinationBlockNumber: expect.stringMatching(/^\d+$/),
+          routeConfiguration: stargateConfiguration,
+          stargate: {
+            guid: '0x5549d117c8b23f0ecdf05c2604ed989cf0034f378707bd81319e93834f2f85f2',
+            sourceBlock: {
+              hash: sourceReceipt.blockHash,
+              number: sourceReceipt.blockNumber.toString(),
+            },
+            sourceEid: 30_184,
+          },
+        },
+      })
+      const destinationBlockNumber = stored.providerState?.['destinationBlockNumber']
+      if (typeof destinationBlockNumber !== 'string')
+        throw new Error('Expected a backfilled destination block number.')
+      expect(BigInt(destinationBlockNumber)).toBeLessThanOrEqual(destinationReceipt.blockNumber)
+      expect(messages).toEqual([{ transferId: transfer.id, type: 'funding:transfer:reconcile' }])
+      await tracker.reconcile(messages[0]!)
+
+      const completed = await TestApp.json(
+        await app.request(`/v1/funding/transfers/${transfer.id}`, as(fundingWriter)),
+        Funding.schema.getFundingTransfer.Response,
+      )
+      expect({
+        destinationTransactionHashes: completed.destinationTransactionHashes,
+        status: completed.status,
+        version: completed.version,
+      }).toEqual({
+        destinationTransactionHashes: [destinationTransactionHash],
+        status: 'completed',
+        version: 3,
+      })
+
+      dispatchEnabled = false
+      const replayed = await TestApp.json(
+        await app.request(path, registration),
+        Funding.schema.registerFundingTransferSourceTransaction.Response,
+      )
+      expect({ status: replayed.status, version: replayed.version }).toEqual({
+        status: 'completed',
+        version: 3,
+      })
+
+      const other = await FundingTransfer.create(trackingDb, {
+        apiKeyId: fundingWriter.id,
+        environment: 'production',
+        orgId: fundingWriter.orgId,
+        snapshot,
+      })
+      const conflict = await app.request(
+        `/v1/funding/transfers/${other.id}/source-transactions`,
+        registration,
+      )
+      expect(conflict.status).toBe(409)
+      expect(((await conflict.json()) as { error: { code: string } }).error.code).toBe(
+        'source_transaction_conflict',
+      )
+
+      const pending = await FundingTransfer.create(trackingDb, {
+        apiKeyId: fundingWriter.id,
+        environment: 'production',
+        orgId: fundingWriter.orgId,
+        snapshot,
+      })
+      const pendingResponse = await app.request(
+        `/v1/funding/transfers/${pending.id}/source-transactions`,
+        {
+          ...registration,
+          body: JSON.stringify({ transactionHash: `0x${'99'.repeat(32)}` }),
+        },
+      )
+      expect(pendingResponse.status).toBe(409)
+      expect(((await pendingResponse.json()) as { error: { code: string } }).error.code).toBe(
+        'source_transaction_pending',
+      )
+    })
+  },
+)
+
 describe('POST /funding/transfers/{destination}', () => {
   test.each([
     { body: vaultTransferBody, destination: 'vault' },
@@ -756,24 +1276,360 @@ describe('POST /funding/transfers/{destination}', () => {
 })
 
 describe('funding transfers OpenAPI', () => {
+  test('publishes generator-ready transfer contracts', async () => {
+    const spec = await (await create({ auth: false }).request('/openapi.json')).json()
+    const detailPath = Object.keys(spec.paths).find(
+      (path) => path.includes('/v1/funding/transfers/{') && !path.endsWith('/source-transactions'),
+    )!
+    const sourceTransactionPath = Object.keys(spec.paths).find((path) =>
+      path.endsWith('/source-transactions'),
+    )!
+    const operations = {
+      create: spec.paths['/v1/funding/transfers'].post,
+      createVault: spec.paths['/v1/funding/transfers/vault'].post,
+      createZone: spec.paths['/v1/funding/transfers/zone'].post,
+      get: spec.paths[detailPath].get,
+      list: spec.paths['/v1/funding/transfers'].get,
+      registerSourceTransaction: spec.paths[sourceTransactionPath].post,
+    }
+    const summarize = (operation: (typeof operations)[keyof typeof operations]) => ({
+      errors: Object.fromEntries(
+        (Object.entries(operation.responses) as [string, ContractResponse][])
+          .filter(([status]) => Number(status) >= 400)
+          .map(([status, response]) => [
+            status,
+            response.$ref ?? response.content?.['application/json']?.schema,
+          ]),
+      ),
+      operationId: operation.operationId,
+      request: operation.requestBody?.content['application/json'].schema,
+      response: operation.responses[200]?.content?.['application/json']?.schema,
+    })
+
+    expect({
+      components: [
+        'CreateFundingTransferRequest',
+        'CreateFundingTransferVaultRequest',
+        'CreateFundingTransferZoneRequest',
+        'CreatedFundingTransfer',
+        'FundingAction',
+        'FundingActionCall',
+        'FundingEvmCallsAction',
+        'FundingTransfer',
+        'FundingTransferFee',
+        'FundingTransferList',
+        'FundingTransferQuote',
+        'FundingTransferStatusReason',
+        'RegisterFundingTransferSourceTransactionRequest',
+      ].filter((name) => spec.components.schemas[name]),
+      formats: {
+        createdAt: spec.components.schemas.FundingTransfer.properties.createdAt.format,
+        quoteExpiresAt: spec.components.schemas.FundingTransferQuote.properties.expiresAt.format,
+        quoteSampledAt: spec.components.schemas.FundingTransferQuote.properties.sampledAt.format,
+        updatedAt: spec.components.schemas.FundingTransfer.properties.updatedAt.format,
+      },
+      models: {
+        action: spec.components.schemas.FundingAction.oneOf,
+        createdAction: spec.components.schemas.CreatedFundingTransfer.properties.action,
+        evmCall: spec.components.schemas.FundingEvmCallsAction.properties.calls.items,
+        feeToken: spec.components.schemas.FundingTransferFee.properties.token,
+        list: spec.components.schemas.FundingTransferList.properties.data.items,
+        quote: spec.components.schemas.FundingTransfer.properties.quote,
+        statusReason: spec.components.schemas.FundingTransfer.properties.statusReason,
+      },
+      operations: {
+        create: summarize(operations.create),
+        createVault: summarize(operations.createVault),
+        createZone: summarize(operations.createZone),
+        get: summarize(operations.get),
+        list: summarize(operations.list),
+        registerSourceTransaction: summarize(operations.registerSourceTransaction),
+      },
+      operationErrorCodes: {
+        createInvalid:
+          spec.components.schemas.ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError
+            .properties.error.properties.code.enum,
+        idempotencyConflict:
+          spec.components.schemas.IdempotencyConflictOrIdempotencyInProgressError.properties.error
+            .properties.code.enum,
+        notImplemented:
+          spec.components.schemas.NotImplemented501Error.properties.error.properties.code.enum,
+        parametersInvalid:
+          spec.components.schemas.ApiKeyMalformedOrParamInvalidError.properties.error.properties
+            .code.enum,
+        queryInvalid:
+          spec.components.schemas.ApiKeyMalformedOrQueryInvalidError.properties.error.properties
+            .code.enum,
+        quoteNotAvailable:
+          spec.components.schemas.QuoteNotAvailableError.properties.error.properties.code.enum,
+        transferNotFound:
+          spec.components.schemas.FundingTransferNotFoundError.properties.error.properties.code
+            .enum,
+      },
+    }).toMatchInlineSnapshot(`
+      {
+        "components": [
+          "CreateFundingTransferRequest",
+          "CreateFundingTransferVaultRequest",
+          "CreateFundingTransferZoneRequest",
+          "CreatedFundingTransfer",
+          "FundingAction",
+          "FundingActionCall",
+          "FundingEvmCallsAction",
+          "FundingTransfer",
+          "FundingTransferFee",
+          "FundingTransferList",
+          "FundingTransferQuote",
+          "FundingTransferStatusReason",
+          "RegisterFundingTransferSourceTransactionRequest",
+        ],
+        "formats": {
+          "createdAt": "date-time",
+          "quoteExpiresAt": "date-time",
+          "quoteSampledAt": "date-time",
+          "updatedAt": "date-time",
+        },
+        "models": {
+          "action": [
+            {
+              "$ref": "#/components/schemas/FundingEvmCallsAction",
+            },
+          ],
+          "createdAction": {
+            "$ref": "#/components/schemas/FundingAction",
+          },
+          "evmCall": {
+            "$ref": "#/components/schemas/FundingActionCall",
+          },
+          "feeToken": {
+            "$ref": "#/components/schemas/FundingToken",
+          },
+          "list": {
+            "$ref": "#/components/schemas/FundingTransfer",
+          },
+          "quote": {
+            "$ref": "#/components/schemas/FundingTransferQuote",
+          },
+          "statusReason": {
+            "$ref": "#/components/schemas/FundingTransferStatusReason",
+          },
+        },
+        "operationErrorCodes": {
+          "createInvalid": [
+            "api_key_malformed",
+            "body_invalid",
+            "idempotency_key_required",
+          ],
+          "idempotencyConflict": [
+            "idempotency_conflict",
+            "idempotency_in_progress",
+          ],
+          "notImplemented": [
+            "not_implemented",
+          ],
+          "parametersInvalid": [
+            "api_key_malformed",
+            "param_invalid",
+          ],
+          "queryInvalid": [
+            "api_key_malformed",
+            "query_invalid",
+          ],
+          "quoteNotAvailable": [
+            "quote_not_available",
+          ],
+          "transferNotFound": [
+            "funding_transfer_not_found",
+          ],
+        },
+        "operations": {
+          "create": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "404": {
+                "$ref": "#/components/schemas/QuoteNotAvailableError",
+              },
+              "409": {
+                "$ref": "#/components/schemas/IdempotencyConflictOrIdempotencyInProgressError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "createFundingTransfer",
+            "request": {
+              "$ref": "#/components/schemas/CreateFundingTransferRequest",
+            },
+            "response": {
+              "$ref": "#/components/schemas/CreatedFundingTransfer",
+            },
+          },
+          "createVault": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "501": {
+                "$ref": "#/components/schemas/NotImplemented501Error",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "createFundingTransferVault",
+            "request": {
+              "$ref": "#/components/schemas/CreateFundingTransferVaultRequest",
+            },
+            "response": undefined,
+          },
+          "createZone": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "501": {
+                "$ref": "#/components/schemas/NotImplemented501Error",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "createFundingTransferZone",
+            "request": {
+              "$ref": "#/components/schemas/CreateFundingTransferZoneRequest",
+            },
+            "response": undefined,
+          },
+          "get": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "404": {
+                "$ref": "#/components/schemas/FundingTransferNotFoundError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "getFundingTransfer",
+            "request": undefined,
+            "response": {
+              "$ref": "#/components/schemas/FundingTransfer",
+            },
+          },
+          "list": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrQueryInvalidError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "listFundingTransfers",
+            "request": undefined,
+            "response": {
+              "$ref": "#/components/schemas/FundingTransferList",
+            },
+          },
+          "registerSourceTransaction": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidOrSourceTransactionInvalidError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "404": {
+                "$ref": "#/components/schemas/FundingTransferNotFoundError",
+              },
+              "409": {
+                "$ref": "#/components/schemas/FundingTransferNotAwaitingSourceOrSourceTransactionConflictOrSourceTransactionPendingError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "501": {
+                "$ref": "#/components/schemas/NotImplemented501Error",
+              },
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "registerFundingTransferSourceTransaction",
+            "request": {
+              "$ref": "#/components/schemas/RegisterFundingTransferSourceTransactionRequest",
+            },
+            "response": {
+              "$ref": "#/components/schemas/FundingTransfer",
+            },
+          },
+        },
+      }
+    `)
+  })
+
   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 } } }>
+        content: Record<string, { schema: JsonSchema }>
       }
       responses: Record<string, { content: Record<string, { example: TransferExample }> }>
     }
-    type Spec = { paths: Record<string, { post: Operation }> }
+    type Spec = ComponentSpec & { paths: Record<string, { post: Operation }> }
     const spec = (await (await app.request('/openapi.json')).json()) as Spec
     const operation = spec.paths['/v1/funding/transfers']!.post
+    const request = dereference(spec, operation.requestBody.content['application/json']!.schema)
 
     expect({
-      request:
-        operation.requestBody.content['application/json']!.schema.properties.destinationToken
-          .examples,
+      request: request.properties!['destinationToken']!.examples,
       response:
         operation.responses['200']!.content['application/json']!.example.destinationToken.address,
     }).toEqual({
@@ -826,8 +1682,11 @@ describe('funding transfers OpenAPI', () => {
       '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 detailPath = Object.keys(spec.paths).find(
+      (path) => path.includes('/v1/funding/transfers/{') && !path.endsWith('/source-transactions'),
+    )!
+    const sourceTransactionPath = Object.keys(spec.paths).find((path) =>
+      path.endsWith('/source-transactions'),
     )!
     const depositAddressPath = Object.keys(spec.paths).find(
       (path) =>
@@ -856,6 +1715,7 @@ describe('funding transfers OpenAPI', () => {
       list: summarize(spec.paths['/v1/funding/transfers']!.get!),
       providers: summarize(spec.paths['/v1/funding/providers']!.get!),
       quotes: summarize(spec.paths['/v1/funding/quotes']!.get!),
+      sourceTransaction: summarize(spec.paths[sourceTransactionPath]!.post!),
       vault: summarize(spec.paths['/v1/funding/transfers/vault']!.post!),
       zone: summarize(spec.paths['/v1/funding/transfers/zone']!.post!),
     }
@@ -926,6 +1786,10 @@ describe('funding transfers OpenAPI', () => {
             "description": "Returns live quotes for transferring stablecoins to Tempo.",
             "summary": "Get quotes",
           },
+          "sourceTransaction": {
+            "description": "Registers and verifies a funding source transaction.",
+            "summary": "Register source transaction",
+          },
           "vault": {
             "description": "Creates a transfer into a Tempo Earn vault.",
             "summary": "Create transfer into vault",
@@ -941,6 +1805,7 @@ describe('funding transfers OpenAPI', () => {
           "Get providers",
           "List deposit addresses",
           "Create deposit address",
+          "Register source transaction",
           "List transfers",
           "Create transfer",
           "Create transfer into vault",
@@ -1002,6 +1867,7 @@ describe('funding transfers OpenAPI', () => {
             "amount",
             "destinationToken",
             "mode",
+            "provider",
             "recipient",
             "sender",
             "slippageBps",
@@ -1031,6 +1897,7 @@ describe('funding transfers OpenAPI', () => {
           "429",
           "500",
           "502",
+          "504",
         ],
         "vault": {
           "additionalProperties": false,
@@ -1052,6 +1919,7 @@ describe('funding transfers OpenAPI', () => {
           "429",
           "500",
           "501",
+          "504",
         ],
         "zone": {
           "additionalProperties": false,
@@ -1075,6 +1943,7 @@ describe('funding transfers OpenAPI', () => {
           "429",
           "500",
           "501",
+          "504",
         ],
       }
     `)
@@ -1120,8 +1989,11 @@ describe('funding transfers OpenAPI', () => {
         }
       >
     }
-    const detailPath = Object.keys(spec.paths).find((path) =>
-      path.includes('/v1/funding/transfers/{'),
+    const detailPath = Object.keys(spec.paths).find(
+      (path) => path.includes('/v1/funding/transfers/{') && !path.endsWith('/source-transactions'),
+    )
+    const sourceTransactionPath = Object.keys(spec.paths).find((path) =>
+      path.endsWith('/source-transactions'),
     )
     const depositAddressPath = Object.keys(spec.paths).find(
       (path) =>
@@ -1157,6 +2029,10 @@ describe('funding transfers OpenAPI', () => {
       requiredCreateHeader: spec.paths['/v1/funding/transfers']?.post?.parameters.find(
         (parameter) => parameter.name === 'idempotency-key',
       ),
+      sourceTransaction:
+        sourceTransactionPath && spec.paths[sourceTransactionPath]?.post?.operationId,
+      sourceTransactionScopes:
+        sourceTransactionPath && spec.paths[sourceTransactionPath]?.post?.['x-required-scopes'],
       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,
@@ -1185,6 +2061,8 @@ describe('funding transfers OpenAPI', () => {
         required: true,
         schema: expect.any(Object),
       }),
+      sourceTransaction: 'registerFundingTransferSourceTransaction',
+      sourceTransactionScopes: ['funding:write'],
       vault: 'createFundingTransferVault',
       vaultScopes: ['funding:write'],
       zone: 'createFundingTransferZone',
@@ -1211,7 +2089,7 @@ const fundingProjectReader = {
 const fundingForeign = {
   id: 'key_funding_other',
   orgId: 'org_funding_other',
-  scopes: ['funding:read'],
+  scopes: ['funding:read', 'funding:write'],
   token: 'secret_funding_other',
 } satisfies TestApp.kvStore.Key