tapimo 0.13.0 → 0.14.0

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'

package/src/internal/funding/providers/relay.ts

@@ -1,5 +1,4 @@
-import { AbiEvent, AbiFunction, Address, Base58, Bytes, Hash, Hex, RpcTransport } from 'ox'
-import { createClient, custom, fallback } from 'viem'
+import { AbiEvent, AbiFunction, Address, Base58, Bytes, Hash, Hex } from 'ox'
 import { getBlockNumber, getLogs, getTransaction, getTransactionReceipt } from 'viem/actions'
 import * as z from 'zod/mini'
 
@@ -820,7 +819,7 @@ function createDepositAddressObserver(
     const stored = schema.DeliveryObservation.safeParse(parameters.providerState)
     const sourceObservation = await (async () => {
       if (stored.success) return stored.data.relay
-      const sourceClient = jsonRpcClient({ fetch: options.fetch, urls: sourceUrls })
+      const sourceClient = Viem.createEvmClient({ fetch: options.fetch, urls: sourceUrls })
       const sourceReceipt = await getTransactionReceipt(sourceClient, {
         hash: parameters.source.transactionHash as Hex.Hex,
       })
@@ -868,7 +867,7 @@ function createDepositAddressObserver(
     })()
     if (!sourceObservation) return { type: 'pending' }
 
-    const destinationClient = jsonRpcClient({ fetch: options.fetch, urls: destinationUrls })
+    const destinationClient = Viem.createEvmClient({ fetch: options.fetch, urls: destinationUrls })
     const destinationHead = await getBlockNumber(destinationClient, { cacheTime: 0 })
     const destinationLogs = await getLogs(destinationClient, {
       address: parameters.destinationToken.address as Address.Address,
@@ -1001,17 +1000,6 @@ function decodeEvent<const event extends AbiEvent.AbiEvent>(
   }
 }
 
-function jsonRpcClient(options: { fetch: FundingProvider.Fetch; urls: readonly string[] }) {
-  return createClient({
-    transport: fallback(
-      options.urls.map((url) => {
-        const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch })
-        return custom(transport, { retryCount: 0 })
-      }),
-    ),
-  })
-}
-
 function minimum(left: bigint, right: bigint): bigint {
   return left < right ? left : right
 }