tapimo 0.13.0 → 0.14.0

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

@@ -4,27 +4,24 @@ 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 Stargate from '../../../internal/funding/providers/stargate.js'
-
-import * as TestApp from '../../../../test/App.js'
-
-import * as TestFunding from '../../../../test/Funding.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 = [
@@ -40,6 +37,9 @@ const executableProviders = [
     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))
 
@@ -224,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',
@@ -390,6 +438,40 @@ 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, {
@@ -728,7 +810,7 @@ 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')
+        if (executable.id === 'stargate') {
           expect(transfer.fees).toMatchObject([
             {
               amount: { baseUnits: BigInt(transfer.action.calls.at(-1)!.value).toString() },
@@ -736,6 +818,16 @@ describe.skipIf(!Anvil.available)('POST /funding/transfers (forked localnet)', (
               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) {
@@ -754,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)
@@ -781,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' },
@@ -847,8 +1278,11 @@ 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/{'),
+    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,
@@ -856,6 +1290,7 @@ describe('funding transfers OpenAPI', () => {
       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(
@@ -885,6 +1320,7 @@ describe('funding transfers OpenAPI', () => {
         'FundingTransferList',
         'FundingTransferQuote',
         'FundingTransferStatusReason',
+        'RegisterFundingTransferSourceTransactionRequest',
       ].filter((name) => spec.components.schemas[name]),
       formats: {
         createdAt: spec.components.schemas.FundingTransfer.properties.createdAt.format,
@@ -907,6 +1343,7 @@ describe('funding transfers OpenAPI', () => {
         createZone: summarize(operations.createZone),
         get: summarize(operations.get),
         list: summarize(operations.list),
+        registerSourceTransaction: summarize(operations.registerSourceTransaction),
       },
       operationErrorCodes: {
         createInvalid:
@@ -944,6 +1381,7 @@ describe('funding transfers OpenAPI', () => {
           "FundingTransferList",
           "FundingTransferQuote",
           "FundingTransferStatusReason",
+          "RegisterFundingTransferSourceTransactionRequest",
         ],
         "formats": {
           "createdAt": "date-time",
@@ -1136,6 +1574,41 @@ describe('funding transfers OpenAPI', () => {
               "$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",
+            },
+          },
         },
       }
     `)
@@ -1209,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) =>
@@ -1239,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!),
     }
@@ -1309,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",
@@ -1324,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",
@@ -1507,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) =>
@@ -1544,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,
@@ -1572,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',
@@ -1598,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