tapimo 0.12.0 → 0.14.0

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)
+  })
+})

package/src/internal/funding/TransferReconciliation.ts

@@ -0,0 +1,264 @@
+import { Hash } from 'ox'
+import * as z from 'zod/mini'
+
+import * as Db from '../../db/Db.js'
+import * as FundingTransferTransactions from '../../db/tables/fundingTransferTransactions.js'
+import * as FundingTransfers from '../../db/tables/fundingTransfers.js'
+import type * as Metrics from '../../Metrics.js'
+import * as Schema from '../Schema.js'
+import type * as Webhooks from '../Webhooks.js'
+import * as Catalog from './Catalog.js'
+import type * as Provider from './Provider.js'
+import * as Stargate from './providers/stargate.js'
+import * as Transfer from './Transfer.js'
+
+const followUpDelaySeconds = 15
+const maximumFollowUpAttempts = 120
+const sweepLimit = 25
+
+const providerState = z.object({
+  destinationBlockNumber: z.string().check(z.regex(/^\d+$/)),
+  routeConfiguration: Stargate.schema.Configuration,
+  stargate: z.object({
+    guid: Schema.Hash,
+    sourceBlock: z.optional(
+      z.object({
+        hash: Schema.Hash,
+        number: z.string().check(z.regex(/^\d+$/)),
+      }),
+    ),
+    sourceEid: z.number().check(z.int(), z.positive()),
+  }),
+})
+
+/** Queue message that advances one registered funding transfer. */
+export type Message = {
+  /** Zero-based destination reconciliation attempt. */
+  attempt?: number | undefined
+  /** Funding transfer id (`ftr_…`). */
+  transferId: string
+  /** Funding transfer reconciliation discriminator. */
+  type: 'funding:transfer:reconcile'
+}
+
+/** Creates a tracker that verifies and completes registered funding transfers. */
+export function createTracker(options: createTracker.Options): createTracker.Tracker {
+  const fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init))
+  let sweepCursor: string | undefined
+  const record = (outcome: string, count = 1) => {
+    options.metrics?.count('funding_transfer_reconciliation_count', count, {
+      outcome,
+      provider: 'stargate',
+    })
+  }
+
+  return {
+    async reconcile(message) {
+      const db = Db.get(options.db)
+      const transfer = await FundingTransfers.get(db, message.transferId)
+      if (!transfer || transfer.status === 'completed') {
+        record(transfer ? 'already_completed' : 'not_found')
+        return { type: 'ignored' }
+      }
+      if (transfer.status !== 'processing' || transfer.providerId !== 'stargate') {
+        record('invalid_state')
+        return { type: 'ignored' }
+      }
+
+      const state = providerState.safeParse(transfer.providerState)
+      const transactions = await FundingTransferTransactions.listByTransfer(db, transfer.id)
+      const source = transactions.find((transaction) => transaction.role === 'source')
+      const catalog = await Catalog.read(db)
+      const destinationChain = catalog.chainsByKey.get(transfer.snapshot.destinationChain.id)
+      const sourceChain = catalog.chainsByKey.get(transfer.snapshot.sourceChain.id)
+      const destinationAmount = transfer.snapshot.destinationAmount
+      if (
+        !state.success ||
+        !source ||
+        !Hash.validate(source.transactionRef) ||
+        !destinationChain ||
+        !destinationAmount ||
+        !sourceChain ||
+        !transfer.snapshot.sender
+      )
+        throw new EvidenceError('Registered Stargate transfer evidence is incomplete.')
+
+      const delivery = await Stargate.verifyDestinationDelivery({
+        configuration: state.data.routeConfiguration,
+        destinationAmount: destinationAmount.baseUnits,
+        destinationBlockNumber: state.data.destinationBlockNumber,
+        destinationChain,
+        destinationTokenAddress: transfer.snapshot.destinationToken.address,
+        fetch,
+        guid: state.data.stargate.guid,
+        recipient: transfer.snapshot.recipient,
+        sourceChainId: transfer.snapshot.sourceChain.id,
+        sourceTokenAddress: transfer.snapshot.sourceToken.address,
+      })
+      if (delivery.type === 'invalid')
+        throw new EvidenceError('Tempo delivery conflicts with registered transfer terms.')
+      if (delivery.type === 'pending') {
+        const verified = await Stargate.verifySourceTransaction({
+          configuration: state.data.routeConfiguration,
+          destinationTokenAddress: transfer.snapshot.destinationToken.address,
+          fetch,
+          recipient: transfer.snapshot.recipient,
+          sender: transfer.snapshot.sender,
+          sourceAmount: transfer.snapshot.sourceAmount.baseUnits,
+          sourceBlock: state.data.stargate.sourceBlock
+            ? {
+                hash: state.data.stargate.sourceBlock.hash,
+                number: BigInt(state.data.stargate.sourceBlock.number),
+              }
+            : undefined,
+          sourceChain,
+          sourceTokenAddress: transfer.snapshot.sourceToken.address,
+          transactionHash: source.transactionRef,
+          validAfter: transfer.snapshot.quote.sampledAt,
+        })
+        if (verified.type === 'reorged') {
+          const reopened = await Transfer.reopenSourceTransaction(db, {
+            chainId: transfer.snapshot.sourceChain.id,
+            id: transfer.id,
+            providerState: {
+              destinationBlockNumber: state.data.destinationBlockNumber,
+              routeConfiguration: state.data.routeConfiguration,
+            },
+            transactionHash: source.transactionRef,
+          })
+          if (reopened.type !== 'reopened') {
+            record('invalid_state')
+            return { type: 'ignored' }
+          }
+          if (options.dispatchTransferUpdates && reopened.references.length > 0)
+            await options.dispatchTransferUpdates(reopened.references)
+          record('reopened')
+          return { type: 'reopened' }
+        }
+        if (verified.type === 'pending') return followUp(message, options, record)
+        if (
+          verified.type === 'invalid' ||
+          verified.guid.toLowerCase() !== state.data.stargate.guid.toLowerCase() ||
+          verified.sourceEid !== state.data.stargate.sourceEid
+        )
+          throw new EvidenceError('Source transaction conflicts with registered Stargate evidence.')
+        return followUp(message, options, record)
+      }
+
+      const completed = await Transfer.complete(db, {
+        chainId: transfer.snapshot.destinationChain.id,
+        destinationAmount,
+        id: transfer.id,
+        transactionHash: delivery.transactionHash,
+      })
+      if (completed.type === 'invalid')
+        throw new EvidenceError('Funding transfer cannot accept destination evidence.')
+      if (completed.type === 'not_found') {
+        record('not_found')
+        return { type: 'ignored' }
+      }
+      if (
+        completed.type === 'completed' &&
+        options.dispatchTransferUpdates &&
+        completed.references.length > 0
+      )
+        await options.dispatchTransferUpdates(completed.references)
+      record(completed.type)
+      return { type: 'completed' }
+    },
+    async tick() {
+      if (!options.dispatch) throw new DispatchError()
+      const db = Db.get(options.db)
+      let records = await FundingTransfers.listProcessing(db, {
+        cursor: sweepCursor,
+        limit: sweepLimit,
+        providerId: 'stargate',
+      })
+      if (records.length === 0 && sweepCursor !== undefined) {
+        sweepCursor = undefined
+        records = await FundingTransfers.listProcessing(db, {
+          limit: sweepLimit,
+          providerId: 'stargate',
+        })
+      }
+      let checked = 0
+      for (const transfer of records) {
+        await options.dispatch(
+          {
+            transferId: transfer.id,
+            type: 'funding:transfer:reconcile',
+          },
+          { delaySeconds: 0 },
+        )
+        sweepCursor = transfer.id
+        checked++
+      }
+      record('swept', checked)
+      return { checked }
+    },
+  }
+}
+
+export declare namespace createTracker {
+  /** Tracker dependencies and queue dispatch. */
+  type Options = {
+    /** Authoritative database or per-invocation database factory. */
+    db: Db.Source
+    /** Enqueues one delayed reconciliation follow-up. */
+    dispatch?: ((message: Message, options: { delaySeconds: number }) => Promise<void>) | undefined
+    /** Enqueues webhook updates staged with transfer mutations. */
+    dispatchTransferUpdates?:
+      | ((references: readonly Webhooks.QueueReference[]) => Promise<number>)
+      | undefined
+    /** Fetch implementation override for chain RPC requests. */
+    fetch?: Provider.Fetch | undefined
+    /** Optional bounded operational metrics. */
+    metrics?: Metrics.Metrics | undefined
+  }
+
+  /** Reconciles one registered funding transfer. */
+  type Tracker = {
+    /** Verifies or defers one destination delivery. */
+    reconcile(message: Message): Promise<Result>
+    /** Enqueues processing transfers whose initial dispatch may have failed. */
+    tick(): Promise<{ checked: number }>
+  }
+
+  /** One reconciliation disposition. */
+  type Result =
+    | { type: 'completed' }
+    | { type: 'ignored' }
+    | { type: 'pending' }
+    | { type: 'reopened' }
+}
+
+async function followUp(
+  message: Message,
+  options: createTracker.Options,
+  record: (outcome: string) => void,
+): Promise<createTracker.Result> {
+  const attempt = (message.attempt ?? 0) + 1
+  if (attempt > maximumFollowUpAttempts) {
+    record('exhausted')
+    throw new ExhaustedError()
+  }
+  if (!options.dispatch) throw new DispatchError()
+  await options.dispatch(
+    { attempt, transferId: message.transferId, type: 'funding:transfer:reconcile' },
+    { delaySeconds: followUpDelaySeconds },
+  )
+  record('pending')
+  return { type: 'pending' }
+}
+
+class DispatchError extends Error {
+  override name = 'Funding.TransferReconciliation.DispatchError'
+}
+
+class EvidenceError extends Error {
+  override name = 'Funding.TransferReconciliation.EvidenceError'
+}
+
+class ExhaustedError extends Error {
+  override name = 'Funding.TransferReconciliation.ExhaustedError'
+}

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

@@ -0,0 +1,128 @@
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as FundingTransferEvents from '../../db/tables/fundingTransferEvents.js'
+import * as Webhooks from '../Webhooks.js'
+import * as Transfer from './Transfer.js'
+import * as TransferWebhook from './TransferWebhook.js'
+
+const db = TestApp.database()
+
+describe('stage', () => {
+  test('stages owner-scoped public versions with stable event ids', async () => {
+    const id = Transfer.generateId()
+    const orgId = 'org_funding_transfer_webhook'
+    const projectId = 'prj_funding_transfer_webhook'
+    const org = await subscription({ filters: { id }, orgId })
+    const project = await subscription({ filters: { id, status: 'completed' }, orgId, projectId })
+    await subscription({ filters: { id }, orgId, projectId: 'prj_funding_transfer_sibling' })
+    await subscription({ environment: 'sandbox', filters: { id }, orgId })
+    await subscription({ filters: { id: Transfer.generateId() }, orgId })
+    await subscription({ filters: { id }, now: new Date('2099-01-01T00:00:00.000Z'), orgId })
+
+    const created = await db.transaction((tx) =>
+      Transfer.createIn(tx, {
+        apiKeyId: 'key_funding_transfer_webhook',
+        environment: 'production',
+        id,
+        orgId,
+        projectId,
+        providerState: { privateRequestId: 'provider-private' },
+        snapshot: TestFunding.transferSnapshot(),
+      }),
+    )
+    const processing = await Transfer.transition(db, {
+      expectedVersion: created.record.version,
+      id,
+      status: 'processing',
+    })
+    if (processing.type !== 'applied') throw new Error('Expected processing transition.')
+    const completed = await Transfer.transition(db, {
+      expectedVersion: processing.record.version,
+      id,
+      status: 'completed',
+    })
+    if (completed.type !== 'applied') throw new Error('Expected completion transition.')
+
+    expect({
+      completed: completed.references.length,
+      created: created.references.length,
+      processing: processing.references.length,
+    }).toEqual({ completed: 2, created: 1, processing: 1 })
+
+    const rows = await db.kysely
+      .selectFrom('webhook_queue_events')
+      .select(['envelope', 'subscriptionId'])
+      .where('subscriptionId', 'in', [org.id, project.id])
+      .orderBy('subscriptionId')
+      .execute()
+    expect(
+      rows.map(({ envelope, subscriptionId }) => ({
+        data: envelope.data,
+        eventId: envelope.id,
+        subscriptionId,
+        type: envelope.type,
+      })),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          data: expect.objectContaining({ id, status: 'awaiting-source', version: 1 }),
+          subscriptionId: org.id,
+          type: 'funding:transfer.updated',
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({ id, status: 'processing', version: 2 }),
+          subscriptionId: org.id,
+          type: 'funding:transfer.updated',
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({ id, status: 'completed', version: 3 }),
+          subscriptionId: org.id,
+          type: 'funding:transfer.updated',
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({ id, status: 'completed', version: 3 }),
+          subscriptionId: project.id,
+          type: 'funding:transfer.updated',
+        }),
+      ]),
+    )
+    expect(rows).toHaveLength(4)
+    expect(rows[0]?.envelope.data).not.toHaveProperty('action')
+    expect(rows[0]?.envelope.data).not.toHaveProperty('providerState')
+
+    const events = await FundingTransferEvents.listByTransfer(db, id)
+    const repeated = await TransferWebhook.stage(db, {
+      changes: [{ event: events.at(-1)!, record: completed.record }],
+    })
+    expect(repeated.created).toBe(0)
+    expect(new Set(repeated.references.map((reference) => reference.eventId))).toEqual(
+      new Set([rows.find(({ subscriptionId }) => subscriptionId === project.id)?.envelope.id]),
+    )
+  })
+})
+
+function subscription(options: subscription.Options) {
+  return Webhooks.createSubscription(
+    db,
+    {
+      chainId: 4217,
+      destination: { type: 'url', url: 'https://example.com/webhooks/tempo' },
+      environment: options.environment ?? 'production',
+      eventType: 'funding:transfer.updated',
+      filters: options.filters,
+      owner: { orgId: options.orgId, type: 'api_key' },
+      ...(options.projectId === undefined ? {} : { projectId: options.projectId }),
+    },
+    options.now === undefined ? {} : { now: () => options.now! },
+  )
+}
+
+declare namespace subscription {
+  type Options = {
+    environment?: 'production' | 'sandbox' | undefined
+    filters: Record<string, unknown>
+    now?: Date | undefined
+    orgId: string
+    projectId?: string | undefined
+  }
+}

package/src/internal/funding/TransferWebhook.ts

@@ -0,0 +1,67 @@
+import type * as Db from '../../db/Db.js'
+import type * as FundingTransferEvents from '../../db/tables/fundingTransferEvents.js'
+import type * as FundingTransfers from '../../db/tables/fundingTransfers.js'
+import * as WebhookSubscriptions from '../../db/tables/webhookSubscriptions.js'
+import * as Webhooks from '../Webhooks.js'
+
+/** Stages durable webhook obligations for committed funding transfer versions. */
+export async function stage(
+  db: Db.Db,
+  options: stage.Options,
+): Promise<Webhooks.ensureQueueEvents.Result> {
+  const dispatchables: Webhooks.ensureQueueEvents.Dispatchable[] = []
+  const now = new Date().toISOString()
+  for (const { event, record } of options.changes) {
+    const match = /^eip155:(\d+)$/.exec(event.snapshot.destinationChain.id)
+    if (!match?.[1]) continue
+    const chainId = Number(match[1])
+    if (!Number.isSafeInteger(chainId) || chainId <= 0) continue
+    const subscriptions = await WebhookSubscriptions.listActiveForFundingEvent(db, {
+      chainId,
+      environment: record.environment,
+      eventCreatedAt: event.createdAt,
+      eventType: 'funding:transfer.updated',
+      now,
+      orgId: record.orgId,
+      ...(record.projectId === null ? {} : { projectId: record.projectId }),
+    })
+    for (const subscription of subscriptions) {
+      if (
+        typeof subscription.filters['id'] === 'string' &&
+        subscription.filters['id'] !== event.transferId
+      )
+        continue
+      if (
+        typeof subscription.filters['status'] === 'string' &&
+        subscription.filters['status'] !== event.status
+      )
+        continue
+      dispatchables.push({
+        envelope: Webhooks.buildKeyedEnvelope({
+          createdAt: new Date(event.createdAt),
+          data: event.snapshot,
+          key: `${event.transferId}:${event.version}`,
+          subscription,
+        }),
+        subscription,
+      })
+    }
+  }
+  return Webhooks.ensureQueueEvents(db, dispatchables)
+}
+
+export declare namespace stage {
+  /** One committed transfer record and its immutable public event. */
+  type Change = {
+    /** Immutable public transfer version. */
+    event: FundingTransferEvents.Record
+    /** Transfer ownership and environment record. */
+    record: FundingTransfers.Record
+  }
+
+  /** Committed transfer changes eligible for customer webhook delivery. */
+  type Options = {
+    /** Transfer changes committed with their delivery obligations. */
+    changes: readonly Change[]
+  }
+}

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

@@ -17,6 +17,7 @@ test('exports funding modules', () => {
       "Subsidy",
       "Token",
       "Transfer",
+      "TransferReconciliation",
     ]
   `)
 })

package/src/internal/funding/index.ts

@@ -12,3 +12,4 @@ export * as SourceObservation from './SourceObservation.js'
 export * as Subsidy from './Subsidy.js'
 export * as Token from './Token.js'
 export * as Transfer from './Transfer.js'
+export * as TransferReconciliation from './TransferReconciliation.js'