tapimo 0.13.0 → 0.14.0

package/src/internal/funding/Transfer.ts

@@ -2,12 +2,15 @@ import * as z from 'zod/mini'
 
 import type * as Db from '../../db/Db.js'
 import * as FundingTransferEvents from '../../db/tables/fundingTransferEvents.js'
+import * as FundingTransferTransactions from '../../db/tables/fundingTransferTransactions.js'
 import * as FundingTransfers from '../../db/tables/fundingTransfers.js'
 import * as Id from '../Id.js'
 import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
+import type * as Webhooks from '../Webhooks.js'
 import * as Action from './Action.js'
 import * as Provider from './Provider.js'
+import * as TransferWebhook from './TransferWebhook.js'
 
 /** Public funding transfer statuses, in the order documented by the API. */
 export const statuses = [
@@ -61,7 +64,7 @@ const transitions: Record<Status, readonly Status[]> = {
   'awaiting-source': ['action-required', 'expired', 'processing'],
   completed: [],
   expired: [],
-  processing: ['action-required', 'completed', 'refunding'],
+  processing: ['action-required', 'awaiting-source', 'completed', 'refunding'],
   refunded: [],
   refunding: ['action-required', 'refunded'],
 }
@@ -383,12 +386,22 @@ export const transactionRoles = ['destination', 'refund', 'source'] as const
 /** Role of a verified transaction reference on a transfer. */
 export type TransactionRole = (typeof transactionRoles)[number]
 
+/** Bounded private provider state retained for transfer reconciliation. */
+export type ProviderState = Record<string, unknown>
+
+type Staged = {
+  /** Funding transfer record committed with the webhook obligations. */
+  record: FundingTransfers.Record
+  /** Webhook queue references committed with the transfer. */
+  references: Webhooks.QueueReference[]
+}
+
 /**
  * Creates a durable funding transfer: the row plus its version-1 event commit
  * in one transaction, so every stored version has an immutable public record.
  */
 export async function create(db: Db.Db, input: create.Input): Promise<FundingTransfers.Record> {
-  return db.transaction((tx) => createIn(tx, input))
+  return db.transaction(async (tx) => (await createIn(tx, input)).record)
 }
 
 /**
@@ -396,7 +409,7 @@ export async function create(db: Db.Db, input: create.Input): Promise<FundingTra
  * transaction, for writes that must commit atomically with sibling state
  * (idempotency completion).
  */
-export async function createIn(tx: Db.Db, input: create.Input): Promise<FundingTransfers.Record> {
+export async function createIn(tx: Db.Db, input: create.Input): Promise<createIn.Result> {
   const now = new Date()
   const snapshot = parseSnapshot(input.snapshot)
   const record: FundingTransfers.Record = {
@@ -418,14 +431,22 @@ export async function createIn(tx: Db.Db, input: create.Input): Promise<FundingT
     version: 1,
   }
   const created = await FundingTransfers.insert(tx, record)
-  await FundingTransferEvents.insert(tx, {
+  const event = await FundingTransferEvents.insert(tx, {
     createdAt: record.createdAt,
     snapshot: toPublic(created),
     status: created.status,
     transferId: created.id,
     version: created.version,
   })
-  return created
+  const { references } = await TransferWebhook.stage(tx, {
+    changes: [{ event, record: created }],
+  })
+  return { record: created, references }
+}
+
+export declare namespace createIn {
+  /** Created transfer and webhook queue references committed with it. */
+  type Result = Staged
 }
 
 export declare namespace create {
@@ -442,12 +463,193 @@ export declare namespace create {
     /** Attributed project id, when the creating key is project-attributed. */
     projectId?: string | undefined
     /** Private provider correlation retained for reconciliation. */
-    providerState?: Provider.prepareTransfer.Correlation | undefined
+    providerState?: ProviderState | undefined
     /** The public snapshot captured from the selected quote. */
     snapshot: Snapshot
   }
 }
 
+/** Atomically assigns one verified source transaction and starts reconciliation. */
+export async function registerSourceTransaction(
+  db: Db.Db,
+  options: registerSourceTransaction.Options,
+): Promise<registerSourceTransaction.Result> {
+  return db.transaction(async (tx) => {
+    const current = await FundingTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+
+    const existing = await FundingTransferTransactions.getSource(tx, {
+      chainId: options.chainId,
+      transactionRef: options.transactionHash,
+    })
+    if (existing) {
+      if (existing.transferId !== current.id) return { current, type: 'conflict' }
+      if (current.status !== 'processing' && current.status !== 'completed')
+        return { current, type: 'invalid' }
+      return { record: current, type: 'replayed' }
+    }
+    if (current.status !== 'awaiting-source') return { current, type: 'invalid' }
+
+    const claimed = await FundingTransferTransactions.claimSource(tx, {
+      chainId: options.chainId,
+      createdAt: new Date().toISOString(),
+      role: 'source',
+      transactionRef: options.transactionHash,
+      transferId: options.id,
+    })
+    if (claimed.type === 'conflict') return { current, type: 'conflict' }
+    if (claimed.type === 'replayed') return { record: current, type: 'replayed' }
+
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: { ...current.providerState, ...options.providerState },
+      snapshot: {
+        ...current.snapshot,
+        sourceTransactionHashes: [claimed.record.transactionRef],
+      },
+      status: 'processing',
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { record: result.record, references: result.references, type: 'registered' }
+  })
+}
+
+export declare namespace registerSourceTransaction {
+  /** Verified source evidence and private provider correlation. */
+  type Options = {
+    /** Source chain CAIP-2 id. */
+    chainId: string
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Private state added for destination reconciliation. */
+    providerState: ProviderState
+    /** Verified source transaction hash. */
+    transactionHash: string
+  }
+
+  /** Source transaction registration outcome. */
+  type Result =
+    | { current: FundingTransfers.Record; type: 'conflict' }
+    | { current: FundingTransfers.Record; type: 'invalid' }
+    | (Staged & { type: 'registered' })
+    | { record: FundingTransfers.Record; type: 'replayed' }
+    | { type: 'not_found' }
+}
+
+/** Atomically removes invalidated source evidence and accepts a replacement. */
+export async function reopenSourceTransaction(
+  db: Db.Db,
+  options: reopenSourceTransaction.Options,
+): Promise<reopenSourceTransaction.Result> {
+  return db.transaction(async (tx) => {
+    const current = await FundingTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.status !== 'processing') return { current, type: 'invalid' }
+
+    const removed = await FundingTransferTransactions.removeSource(tx, {
+      chainId: options.chainId,
+      transactionHash: options.transactionHash,
+      transferId: current.id,
+    })
+    if (!removed) return { current, type: 'invalid' }
+    const { sourceTransactionHashes: _sourceTransactionHashes, ...snapshot } = current.snapshot
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: options.providerState,
+      snapshot,
+      status: 'awaiting-source',
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { record: result.record, references: result.references, type: 'reopened' }
+  })
+}
+
+export declare namespace reopenSourceTransaction {
+  /** Source evidence to remove after it disappears from the canonical chain. */
+  type Options = {
+    /** Source chain CAIP-2 id. */
+    chainId: string
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Private provider state retained while awaiting replacement evidence. */
+    providerState: ProviderState
+    /** Invalidated source transaction hash. */
+    transactionHash: string
+  }
+
+  /** Source transaction reopening outcome. */
+  type Result =
+    | { current: FundingTransfers.Record; type: 'invalid' }
+    | (Staged & { type: 'reopened' })
+    | { type: 'not_found' }
+}
+
+/** Atomically records a verified destination transaction and completes a transfer. */
+export async function complete(db: Db.Db, options: complete.Options): Promise<complete.Result> {
+  return db.transaction(async (tx) => {
+    const current = await FundingTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.status === 'completed') {
+      const transactions = await FundingTransferTransactions.listByTransfer(tx, current.id)
+      const existing = transactions.some(
+        (transaction) =>
+          transaction.chainId === options.chainId &&
+          transaction.role === 'destination' &&
+          transaction.transactionRef === options.transactionHash.toLowerCase(),
+      )
+      return existing ? { record: current, type: 'replayed' } : { current, type: 'invalid' }
+    }
+    if (current.status !== 'processing') return { current, type: 'invalid' }
+
+    const transaction = await FundingTransferTransactions.insert(tx, {
+      chainId: options.chainId,
+      createdAt: new Date().toISOString(),
+      role: 'destination',
+      transactionRef: options.transactionHash,
+      transferId: options.id,
+    })
+    if (!transaction) throw new AtomicTransitionError()
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      snapshot: {
+        ...current.snapshot,
+        destinationAmount: options.destinationAmount,
+        destinationTransactionHashes: [transaction.transactionRef],
+      },
+      status: 'completed',
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { record: result.record, references: result.references, type: 'completed' }
+  })
+}
+
+export declare namespace complete {
+  /** Verified destination evidence for one processing transfer. */
+  type Options = {
+    /** Destination chain CAIP-2 id. */
+    chainId: string
+    /** Exact verified destination amount. */
+    destinationAmount: NonNullable<Snapshot['destinationAmount']>
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Verified destination transaction hash. */
+    transactionHash: string
+  }
+
+  /** Transfer completion outcome. */
+  type Result =
+    | { current: FundingTransfers.Record; type: 'invalid' }
+    | (Staged & { type: 'completed' })
+    | { record: FundingTransfers.Record; type: 'replayed' }
+    | { type: 'not_found' }
+}
+
 /**
  * Applies a version-guarded material change: a status transition, a snapshot
  * update, or both. The row update and its immutable event commit in one
@@ -457,39 +659,48 @@ export declare namespace create {
 export async function transition(
   db: Db.Db,
   options: transition.Options,
+): Promise<transition.Result> {
+  return db.transaction((tx) => transitionIn(tx, options))
+}
+
+async function transitionIn(
+  tx: Db.Db,
+  options: transition.Options & { current?: FundingTransfers.Record | undefined },
 ): Promise<transition.Result> {
   const now = new Date()
-  return db.transaction(async (tx) => {
-    const current = await FundingTransfers.get(tx, options.id)
-    if (!current) return { type: 'not_found' }
-    if (current.version !== options.expectedVersion) return { current, type: 'stale' }
-    const status = options.status ?? current.status
-    if (status !== current.status && !canTransition(current.status, status))
-      return { current, type: 'invalid' }
-
-    const updated = await FundingTransfers.update(tx, {
-      expectedVersion: options.expectedVersion,
-      id: options.id,
-      snapshot: options.snapshot === undefined ? current.snapshot : parseSnapshot(options.snapshot),
-      status,
-      statusReason:
-        options.statusReason ?? (status === current.status ? current.statusReason : null),
-      updatedAt: now.toISOString(),
-      version: current.version + 1,
-    })
-    if (!updated) {
-      const latest = await FundingTransfers.get(tx, options.id)
-      return latest ? { current: latest, type: 'stale' } : { type: 'not_found' }
-    }
-    await FundingTransferEvents.insert(tx, {
-      createdAt: updated.updatedAt,
-      snapshot: toPublic(updated),
-      status: updated.status,
-      transferId: updated.id,
-      version: updated.version,
-    })
-    return { record: updated, type: 'applied' }
+  const current = options.current ?? (await FundingTransfers.get(tx, options.id))
+  if (!current) return { type: 'not_found' }
+  if (current.version !== options.expectedVersion) return { current, type: 'stale' }
+  const status = options.status ?? current.status
+  if (status !== current.status && !canTransition(current.status, status))
+    return { current, type: 'invalid' }
+
+  const updated = await FundingTransfers.update(tx, {
+    expectedVersion: options.expectedVersion,
+    id: options.id,
+    providerState:
+      options.providerState === undefined ? current.providerState : options.providerState,
+    snapshot: options.snapshot === undefined ? current.snapshot : parseSnapshot(options.snapshot),
+    status,
+    statusReason: options.statusReason ?? (status === current.status ? current.statusReason : null),
+    updatedAt: now.toISOString(),
+    version: current.version + 1,
   })
+  if (!updated) {
+    const latest = await FundingTransfers.get(tx, options.id)
+    return latest ? { current: latest, type: 'stale' } : { type: 'not_found' }
+  }
+  const event = await FundingTransferEvents.insert(tx, {
+    createdAt: updated.updatedAt,
+    snapshot: toPublic(updated),
+    status: updated.status,
+    transferId: updated.id,
+    version: updated.version,
+  })
+  const { references } = await TransferWebhook.stage(tx, {
+    changes: [{ event, record: updated }],
+  })
+  return { record: updated, references, type: 'applied' }
 }
 
 export declare namespace transition {
@@ -499,6 +710,8 @@ export declare namespace transition {
     expectedVersion: number
     /** Transfer id (`ftr_…`). */
     id: string
+    /** Replacement private provider state; omitted keeps the stored value. */
+    providerState?: ProviderState | null | undefined
     /** Replacement public snapshot; omitted keeps the stored snapshot. */
     snapshot?: Snapshot | undefined
     /** New status; omitted keeps the current status (snapshot-only change). */
@@ -509,7 +722,7 @@ export declare namespace transition {
 
   /** Outcome of a guarded transition. */
   type Result =
-    | { record: FundingTransfers.Record; type: 'applied' }
+    | (Staged & { type: 'applied' })
     | { current: FundingTransfers.Record; type: 'invalid' }
     | { current: FundingTransfers.Record; type: 'stale' }
     | { type: 'not_found' }
@@ -543,3 +756,7 @@ function parseSnapshot(snapshot: Snapshot): Snapshot {
     },
   }
 }
+
+class AtomicTransitionError extends Error {
+  override name = 'Funding.Transfer.AtomicTransitionError'
+}

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

@@ -0,0 +1,147 @@
+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 Catalog from './Catalog.js'
+import * as Transfer from './Transfer.js'
+import * as TransferReconciliation from './TransferReconciliation.js'
+
+const db = TestApp.database()
+const destinationTransactionHash =
+  '0x3dfaba0a78b8f4bc09e55e05211c8120729e7b6879efe32613883befbca666da'
+const guid = '0x5549d117c8b23f0ecdf05c2604ed989cf0034f378707bd81319e93834f2f85f2'
+const recipient = '0x7212623e4cff9ad010d28aa065fad2bf58578783'
+const sender = '0x52b650a62e384f68880d0a1dc2b84dfed47d5660'
+const sourceTransactionHash = '0xfd71359adf5095f2ab512a19e0a2df6c8cc0db14ac8a52286d61287daabdccd4'
+const routeConfiguration = TestFunding.snapshot.routesByProvider
+  .get('stargate')!
+  .find((candidate) => candidate.route.source.chain.id === 'eip155:8453')!.configuration!
+
+describe.skipIf(!Anvil.available)('createTracker', () => {
+  let destination: Anvil.start.ReturnType
+
+  beforeAll(async () => {
+    destination = await Anvil.start({
+      chain: tempoMainnet,
+      forkUrl: tempoMainnet.rpcUrls.default.http[0]!,
+    })
+    await Catalog.publish(db, {
+      ...TestFunding.data,
+      chains: TestFunding.data.chains.map((chain) =>
+        chain.id === 'eip155:4217' ? { ...chain, rpcUrls: [destination.rpcUrl] } : chain,
+      ),
+    })
+  })
+
+  afterAll(async () => {
+    await destination?.stop()
+  })
+
+  test('completes a registered transfer from Tempo evidence', async () => {
+    const amount = {
+      baseUnits: '200000',
+      currency: 'USD',
+      decimals: 6,
+      formatted: '0.2',
+    } as const
+    const transfer = await Transfer.create(db, {
+      apiKeyId: 'key_test',
+      environment: 'production',
+      orgId: 'org_test',
+      providerState: {
+        destinationBlockNumber: (
+          await destination.client.getTransactionReceipt({ hash: destinationTransactionHash })
+        ).blockNumber.toString(),
+        routeConfiguration,
+      },
+      snapshot: TestFunding.transferSnapshot({
+        destinationAmount: amount,
+        destinationAmountMin: amount,
+        provider: { id: 'stargate', name: 'Stargate' },
+        recipient,
+        sender,
+        sourceAmount: amount,
+      }),
+    })
+    await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: transfer.id,
+      providerState: { stargate: { guid, sourceEid: 30_184 } },
+      transactionHash: sourceTransactionHash,
+    })
+    await Catalog.publish(db, {
+      ...TestFunding.data,
+      chains: TestFunding.data.chains.map((chain) =>
+        chain.id === 'eip155:4217' ? { ...chain, rpcUrls: [destination.rpcUrl] } : chain,
+      ),
+      routes: TestFunding.data.routes.filter((route) => route.providerId !== 'stargate'),
+    })
+
+    const tracker = TransferReconciliation.createTracker({ db })
+    await expect(
+      tracker.reconcile({ transferId: transfer.id, type: 'funding:transfer:reconcile' }),
+    ).resolves.toEqual({ type: 'completed' })
+
+    const completed = await Transfer.transition(db, {
+      expectedVersion: 2,
+      id: transfer.id,
+      status: 'completed',
+    })
+    expect(completed.type).toBe('stale')
+    if (completed.type !== 'stale') return
+    expect({
+      destinationTransactionHashes: completed.current.snapshot.destinationTransactionHashes,
+      status: completed.current.status,
+      version: completed.current.version,
+    }).toEqual({
+      destinationTransactionHashes: [destinationTransactionHash],
+      status: 'completed',
+      version: 3,
+    })
+  })
+})
+
+describe('tick', () => {
+  test('advances through bounded recovery pages', async () => {
+    const database = TestApp.database()
+    await TestFunding.publish(database)
+    for (let index = 0; index < 26; index++) {
+      const transfer = await Transfer.create(database, {
+        apiKeyId: 'key_test',
+        environment: 'production',
+        id: Transfer.generateId(new Date(Date.UTC(2026, 0, 1, 0, 0, index))),
+        orgId: 'org_test',
+        providerState: {},
+        snapshot: TestFunding.transferSnapshot({
+          provider: { id: 'stargate', name: 'Stargate' },
+        }),
+      })
+      await Transfer.transition(database, {
+        expectedVersion: 1,
+        id: transfer.id,
+        status: 'processing',
+      })
+    }
+
+    type Dispatch = { delaySeconds: number; message: TransferReconciliation.Message }
+    const dispatches: Dispatch[] = []
+    let available = false
+    const tracker = TransferReconciliation.createTracker({
+      db: database,
+      dispatch: async (message, options) => {
+        dispatches.push({ delaySeconds: options.delaySeconds, message })
+        if (!available) throw new Error('queue unavailable')
+      },
+    })
+    await expect(tracker.tick()).rejects.toThrow('queue unavailable')
+    available = true
+    await expect(tracker.tick()).resolves.toEqual({ checked: 25 })
+    await expect(tracker.tick()).resolves.toEqual({ checked: 1 })
+
+    expect(dispatches).toHaveLength(27)
+    expect(dispatches[0]).toEqual(dispatches[1])
+    expect(new Set(dispatches.map(({ delaySeconds }) => delaySeconds))).toEqual(new Set([0]))
+    expect(new Set(dispatches.map(({ message }) => message.transferId)).size).toBe(26)
+  })
+})