tapimo 0.10.2 → 0.11.0

package/src/internal/funding/DepositWebhook.ts

@@ -0,0 +1,101 @@
+import type * as Db from '../../db/Db.js'
+import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as WebhookSubscriptions from '../../db/tables/webhookSubscriptions.js'
+import * as Webhooks from '../Webhooks.js'
+import * as Deposit from './Deposit.js'
+
+/** Applies a deposit transition and stages every matching webhook obligation atomically. */
+export async function transition(
+  db: Db.Db,
+  options: Deposit.transition.Options,
+): Promise<transition.Result> {
+  return db.transaction(async (tx) => {
+    const result = await Deposit.transition(tx, options)
+    if (result.type !== 'applied') return { references: [], result }
+    const staged = await stage(tx, { records: [result.record] })
+    return { references: staged.references, result }
+  })
+}
+
+export declare namespace transition {
+  /** Transition result plus compact references for atomically staged obligations. */
+  type Result = {
+    /** Queue references staged with the applied transition. */
+    references: Webhooks.QueueReference[]
+    /** Version-guarded deposit transition outcome. */
+    result: Deposit.transition.Result
+  }
+}
+
+/** Stages durable webhook obligations for committed funding deposit 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 record of unique(options.records)) {
+    const chainId = destinationChainId(record)
+    if (chainId === undefined) continue
+    const subscriptions = await WebhookSubscriptions.listActiveForFundingDeposit(db, {
+      chainId,
+      environment: record.environment,
+      now,
+      orgId: record.orgId,
+      ...(record.projectId === null ? {} : { projectId: record.projectId }),
+    })
+    const data = Deposit.toPublic(record)
+    for (const subscription of subscriptions) {
+      if (!matches(subscription.filters, data)) continue
+      dispatchables.push({
+        envelope: Webhooks.buildKeyedEnvelope({
+          createdAt: new Date(record.updatedAt),
+          data,
+          key: `${record.id}:${record.version}`,
+          subscription,
+        }),
+        subscription,
+      })
+    }
+  }
+  return Webhooks.ensureQueueEvents(db, dispatchables)
+}
+
+export declare namespace stage {
+  /** Committed deposit changes eligible for customer webhook delivery. */
+  type Options = {
+    /** Latest committed funding deposit records. */
+    records: readonly FundingDeposits.Record[]
+  }
+}
+
+function destinationChainId(record: FundingDeposits.Record): number | undefined {
+  const match = /^eip155:(\d+)$/.exec(record.snapshot.destinationChain.id)
+  if (!match) return undefined
+  const chainId = Number(match[1])
+  return Number.isSafeInteger(chainId) && chainId > 0 ? chainId : undefined
+}
+
+function matches(filters: Record<string, unknown>, deposit: Deposit.Public): boolean {
+  if (
+    typeof filters['depositAddressId'] === 'string' &&
+    filters['depositAddressId'] !== deposit.depositAddressId
+  )
+    return false
+  if (
+    typeof filters['recipient'] === 'string' &&
+    filters['recipient'].toLowerCase() !== deposit.recipient.toLowerCase()
+  )
+    return false
+  if (typeof filters['status'] === 'string' && filters['status'] !== deposit.status) return false
+  return true
+}
+
+function unique(records: readonly FundingDeposits.Record[]): FundingDeposits.Record[] {
+  const byId = new Map<string, FundingDeposits.Record>()
+  for (const record of records) {
+    const current = byId.get(record.id)
+    if (!current || current.version < record.version) byId.set(record.id, record)
+  }
+  return [...byId.values()]
+}

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

@@ -770,9 +770,11 @@ describe('createTracker', () => {
       ).requests[0]
       if (!request) throw new Error('Expected a Relay refund request.')
       const verifyTransfers = Evidence.createVerifier({ db })
+      const depositUpdateVersions: number[] = []
       const first = await Reconciliation.reconcileRequest(db, {
         address,
         metrics,
+        onDeposit: (deposit) => depositUpdateVersions.push(deposit.version),
         request,
         verifyTransfers,
       })
@@ -784,12 +786,14 @@ describe('createTracker', () => {
       const second = await Reconciliation.reconcileRequest(db, {
         address,
         metrics,
+        onDeposit: (deposit) => depositUpdateVersions.push(deposit.version),
         request,
         verifyTransfers,
       })
       const duplicate = await Reconciliation.reconcileRequest(db, {
         address,
         metrics,
+        onDeposit: (deposit) => depositUpdateVersions.push(deposit.version),
         request,
         verifyTransfers,
       })
@@ -797,6 +801,9 @@ describe('createTracker', () => {
         depositAddressId: address.id,
         sourceTransactionHash,
       })
+      if (!firstRecord || !record) throw new Error('Expected reconciled funding deposits.')
+
+      expect(depositUpdateVersions).toEqual([2, firstRecord.version, 4, record.version])
 
       expect({
         counts,
@@ -1944,9 +1951,14 @@ describe('createTracker', () => {
         routes: [],
         tokens: [],
       })
+      const dispatchedEventIds: string[][] = []
       const tracker = Reconciliation.createTracker({
         db,
         dispatch: async () => undefined,
+        dispatchDepositUpdates: async (references) => {
+          dispatchedEventIds.push(references.map((reference) => reference.eventId))
+          return references.length
+        },
         providers: [Relay.relay({ apiKey: 'relay-api-key', baseUrl: server.url })],
         verifyTransfers: Evidence.createVerifier({ db }),
       })
@@ -1970,6 +1982,8 @@ describe('createTracker', () => {
         { limit: 10 },
       )
 
+      expect(dispatchedEventIds).toEqual([])
+
       expect({ failures, records: records.map(Deposit.toPublic) }).toMatchInlineSnapshot(
         {
           records: [

package/src/internal/funding/Reconciliation.ts

@@ -6,7 +6,9 @@ import * as FundingDepositRequestObservations from '../../db/tables/fundingDepos
 import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
 import type * as Metrics from '../../Metrics.js'
 import * as Value from '../Value.js'
+import type * as Webhooks from '../Webhooks.js'
 import * as Deposit from './Deposit.js'
+import * as DepositWebhook from './DepositWebhook.js'
 import * as Provider from './Provider.js'
 import * as Subsidy from './Subsidy.js'
 
@@ -119,6 +121,17 @@ export function createTracker(options: createTracker.Options): createTracker.Tra
         })()
         heartbeat.assert()
         let created = 0
+        const depositWebhookReferences = new Map<string, Webhooks.QueueReference>()
+        const onDeposit: NonNullable<reconcileRequest.Options['onDeposit']> = (
+          _deposit,
+          references,
+        ) => {
+          for (const reference of references)
+            depositWebhookReferences.set(
+              `${reference.subscriptionId}:${reference.eventId}`,
+              reference,
+            )
+        }
         let updated = 0
         const pendingRequestIds = new Set([
           ...requests.pendingRequestIds,
@@ -129,6 +142,7 @@ export function createTracker(options: createTracker.Options): createTracker.Tra
           const result = await reconcileRequest(database, {
             address: claimed,
             metrics: options.metrics,
+            onDeposit,
             provider,
             request,
             signal: options.signal,
@@ -148,6 +162,7 @@ export function createTracker(options: createTracker.Options): createTracker.Tra
         const unattributed = await reconcileUnattributed(database, {
           address: claimed,
           metrics: options.metrics,
+          onDeposit,
           provider,
           signal: options.signal,
           subsidies: options.subsidies,
@@ -166,6 +181,24 @@ export function createTracker(options: createTracker.Options): createTracker.Tra
             trigger,
           })
 
+        if (options.dispatchDepositUpdates && depositWebhookReferences.size > 0) {
+          const references = [...depositWebhookReferences.values()]
+          await options.dispatchDepositUpdates(references).then(
+            (count) =>
+              options.metrics?.count('funding_deposit_webhook_enqueue_count', count, {
+                outcome: 'succeeded',
+                provider: claimed.providerId,
+              }),
+            (cause) => {
+              options.metrics?.count('funding_deposit_webhook_enqueue_count', references.length, {
+                outcome: 'failed',
+                provider: claimed.providerId,
+              })
+              throw cause
+            },
+          )
+        }
+
         const leaseFailure = await heartbeat.stop()
         if (leaseFailure !== undefined) throw leaseFailure
         const completedAt = now()
@@ -295,6 +328,10 @@ export declare namespace createTracker {
       message: Provider.Webhook.receive.Dispatchable,
       options?: createTracker.DispatchOptions,
     ) => Promise<void>
+    /** Stages and dispatches committed funding deposit webhook updates. */
+    dispatchDepositUpdates?:
+      | ((references: readonly Webhooks.QueueReference[]) => Promise<number>)
+      | undefined
     /** Duration of one reconciliation lease. */
     leaseMs?: number | undefined
     /** Optional bounded operational metrics sink. */
@@ -589,6 +626,7 @@ type VerifiedDeposit = {
 type ReconcileDeliveryOptions = {
   address: FundingDepositAddresses.Record
   metrics?: Metrics.Metrics | undefined
+  onDeposit?: reconcileRequest.Options['onDeposit'] | undefined
   provider?: Provider.Provider | undefined
   request?: Provider.listDepositAddressRequests.ReturnType['requests'][number] | undefined
   signal?: AbortSignal | undefined
@@ -690,7 +728,11 @@ async function reconcileUnattributed(db: Db.Db, options: reconcileUnattributed.O
     if (!delivery.terminal) terminal = false
     for (const id of delivery.updatedIds) updatedIds.add(id)
   }
-  return { ...(followUp ? { followUp } : {}), terminal, updatedIds }
+  return {
+    ...(followUp ? { followUp } : {}),
+    terminal,
+    updatedIds,
+  }
 }
 
 declare namespace reconcileUnattributed {
@@ -843,21 +885,25 @@ export async function reconcileRequest(
         deposit.providerRequestId === null ||
         !deposit.providerRequestIds.includes(options.request.id)
       ) {
-        const result = await Deposit.transition(db, {
-          expectedVersion: deposit.version,
-          id: deposit.id,
-          providerRequestId: options.request.id,
-          providerRequestIds: unique([...deposit.providerRequestIds, options.request.id]),
-          providerTransferIndex,
-          snapshot: {
-            ...deposit.snapshot,
-            ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
-            ...(transfer.sender ? { sender: transfer.sender } : {}),
-            sourceAmount,
+        const result = await transitionDeposit(
+          db,
+          {
+            expectedVersion: deposit.version,
+            id: deposit.id,
+            providerRequestId: options.request.id,
+            providerRequestIds: unique([...deposit.providerRequestIds, options.request.id]),
+            providerTransferIndex,
+            snapshot: {
+              ...deposit.snapshot,
+              ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
+              ...(transfer.sender ? { sender: transfer.sender } : {}),
+              sourceAmount,
+            },
+            sourceTransferIndex: transfer.transferIndex,
+            status: deposit.status === 'detected' ? 'bridging' : deposit.status,
           },
-          sourceTransferIndex: transfer.transferIndex,
-          status: deposit.status === 'detected' ? 'bridging' : deposit.status,
-        })
+          options.onDeposit,
+        )
         if (result.type === 'applied') {
           deposit = result.record
           updatedIds.add(deposit.id)
@@ -867,7 +913,9 @@ export async function reconcileRequest(
     }
   }
   if (verified.length === 0) return { created, terminal: false, updated: updatedIds.size }
-  if (!sourceEvidenceComplete) return { created, terminal: false, updated: updatedIds.size }
+  if (!sourceEvidenceComplete) {
+    return { created, terminal: false, updated: updatedIds.size }
+  }
   const recovery = await reconcileProviderRecovery(db, { ...options, verified })
   if (recovery) {
     for (const id of recovery.updatedIds) updatedIds.add(id)
@@ -895,6 +943,10 @@ export declare namespace reconcileRequest {
     address: FundingDepositAddresses.Record
     /** Optional bounded operational metrics sink. */
     metrics?: Metrics.Metrics | undefined
+    /** Observes the latest committed form of each verified deposit. */
+    onDeposit?:
+      | ((deposit: FundingDeposits.Record, references: readonly Webhooks.QueueReference[]) => void)
+      | undefined
     /** Provider integration that discovered the request. */
     provider?: Provider.Provider | undefined
     /** Provider request containing discovered chain transactions. */
@@ -922,6 +974,17 @@ export declare namespace reconcileRequest {
   }
 }
 
+async function transitionDeposit(
+  db: Db.Db,
+  options: Deposit.transition.Options,
+  onDeposit: reconcileRequest.Options['onDeposit'],
+): Promise<Deposit.transition.Result> {
+  const committed = await DepositWebhook.transition(db, options)
+  if (committed.result.type === 'applied')
+    onDeposit?.(committed.result.record, committed.references)
+  return committed.result
+}
+
 async function reconcileProviderRecovery(db: Db.Db, options: ReconcileDeliveryOptions) {
   const failed = (providerFailureStatuses as readonly string[]).includes(
     options.request?.status ?? '',
@@ -991,15 +1054,19 @@ async function reconcileProviderRecovery(db: Db.Db, options: ReconcileDeliveryOp
     if (Deposit.isTerminal(entry.deposit.status)) continue
     let deposit = entry.deposit
     if (deposit.status !== 'refunding') {
-      const result = await Deposit.transition(db, {
-        expectedVersion: deposit.version,
-        id: deposit.id,
-        providerTransactionHashes: unique([
-          ...deposit.providerTransactionHashes,
-          ...providerRefundTransactionHashes,
-        ]),
-        status: 'refunding',
-      })
+      const result = await transitionDeposit(
+        db,
+        {
+          expectedVersion: deposit.version,
+          id: deposit.id,
+          providerTransactionHashes: unique([
+            ...deposit.providerTransactionHashes,
+            ...providerRefundTransactionHashes,
+          ]),
+          status: 'refunding',
+        },
+        options.onDeposit,
+      )
       if (result.type === 'applied') {
         deposit = result.record
         updatedIds.add(deposit.id)
@@ -1011,20 +1078,24 @@ async function reconcileProviderRecovery(db: Db.Db, options: ReconcileDeliveryOp
       terminal = false
       continue
     }
-    const result = await Deposit.transition(db, {
-      expectedVersion: deposit.version,
-      id: deposit.id,
-      snapshot: {
-        ...deposit.snapshot,
-        refundAmount: Value.tokenAmount({
-          baseUnits: amount,
-          currency: options.address.snapshot.sourceToken.currency,
-          decimals: options.address.snapshot.sourceToken.decimals,
-        }),
-        refundTransactionHashes,
+    const result = await transitionDeposit(
+      db,
+      {
+        expectedVersion: deposit.version,
+        id: deposit.id,
+        snapshot: {
+          ...deposit.snapshot,
+          refundAmount: Value.tokenAmount({
+            baseUnits: amount,
+            currency: options.address.snapshot.sourceToken.currency,
+            decimals: options.address.snapshot.sourceToken.decimals,
+          }),
+          refundTransactionHashes,
+        },
+        status: 'refunded',
       },
-      status: 'refunded',
-    })
+      options.onDeposit,
+    )
     if (result.type === 'applied') updatedIds.add(deposit.id)
     else if (result.type !== 'stale' || !Deposit.isTerminal(result.current.status)) terminal = false
   }
@@ -1116,57 +1187,61 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
       currency: options.address.snapshot.destinationToken.currency,
       decimals: options.address.snapshot.destinationToken.decimals,
     })
-    const result = await Deposit.transition(db, {
-      expectedVersion: deposit.version,
-      id: deposit.id,
-      ...(delivered > 0n
-        ? {
-            providerOutputAmount: Value.tokenAmount({
-              baseUnits: delivered,
-              currency: options.address.providerOutputToken.currency,
-              decimals: options.address.providerOutputToken.decimals,
-            }),
-          }
-        : {}),
-      providerRequestIds: options.request
-        ? unique([...deposit.providerRequestIds, options.request.id])
-        : deposit.providerRequestIds,
-      ...(deliveryObservation?.providerState
-        ? {
-            providerState: {
-              ...deposit.providerState,
-              ...deliveryObservation.providerState,
-            },
-          }
-        : {}),
-      providerTransactionHashes: unique([
-        ...deposit.providerTransactionHashes,
-        ...providerTransactionHashes,
-        ...(deliveryObservation?.providerTransactionHashes ?? []),
-      ]),
-      ...(settlement.settlementTransaction
-        ? { settlementTransaction: settlement.settlementTransaction }
-        : {}),
-      ...(settlement.settlementTransactionHash
-        ? { settlementTransactionHash: settlement.settlementTransactionHash }
-        : {}),
-      snapshot: {
-        ...deposit.snapshot,
-        ...(delivered + settlement.delivered > 0n ? { destinationAmount } : {}),
-        ...(settlement.status === 'completed' && !options.address.snapshot.subsidize
-          ? { destinationAmountRequired: destinationAmount }
+    const result = await transitionDeposit(
+      db,
+      {
+        expectedVersion: deposit.version,
+        id: deposit.id,
+        ...(delivered > 0n
+          ? {
+              providerOutputAmount: Value.tokenAmount({
+                baseUnits: delivered,
+                currency: options.address.providerOutputToken.currency,
+                decimals: options.address.providerOutputToken.decimals,
+              }),
+            }
+          : {}),
+        providerRequestIds: options.request
+          ? unique([...deposit.providerRequestIds, options.request.id])
+          : deposit.providerRequestIds,
+        ...(deliveryObservation?.providerState
+          ? {
+              providerState: {
+                ...deposit.providerState,
+                ...deliveryObservation.providerState,
+              },
+            }
           : {}),
-        destinationTransactionHashes: unique([
-          ...(deposit.snapshot.destinationTransactionHashes ?? []),
-          ...destinationTransfers.map((evidence) => evidence.transactionHash),
-          ...settlement.destinationTransactionHashes,
+        providerTransactionHashes: unique([
+          ...deposit.providerTransactionHashes,
+          ...providerTransactionHashes,
+          ...(deliveryObservation?.providerTransactionHashes ?? []),
         ]),
+        ...(settlement.settlementTransaction
+          ? { settlementTransaction: settlement.settlementTransaction }
+          : {}),
+        ...(settlement.settlementTransactionHash
+          ? { settlementTransactionHash: settlement.settlementTransactionHash }
+          : {}),
+        snapshot: {
+          ...deposit.snapshot,
+          ...(delivered + settlement.delivered > 0n ? { destinationAmount } : {}),
+          ...(settlement.status === 'completed' && !options.address.snapshot.subsidize
+            ? { destinationAmountRequired: destinationAmount }
+            : {}),
+          destinationTransactionHashes: unique([
+            ...(deposit.snapshot.destinationTransactionHashes ?? []),
+            ...destinationTransfers.map((evidence) => evidence.transactionHash),
+            ...settlement.destinationTransactionHashes,
+          ]),
+        },
+        status: settlement.status,
+        ...(settlement.statusReason ? { statusReason: settlement.statusReason } : {}),
+        ...(settlement.subsidyAmount ? { subsidyAmount: settlement.subsidyAmount } : {}),
+        ...(settlement.tempoGasPaid ? { tempoGasPaid: settlement.tempoGasPaid } : {}),
       },
-      status: settlement.status,
-      ...(settlement.statusReason ? { statusReason: settlement.statusReason } : {}),
-      ...(settlement.subsidyAmount ? { subsidyAmount: settlement.subsidyAmount } : {}),
-      ...(settlement.tempoGasPaid ? { tempoGasPaid: settlement.tempoGasPaid } : {}),
-    })
+      options.onDeposit,
+    )
     if (result.type === 'applied') {
       updatedIds.add(deposit.id)
       if (settlement.broadcast && options.subsidies) {

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

@@ -8,6 +8,7 @@ test('exports funding modules', () => {
       "Catalog",
       "Deposit",
       "DepositAddress",
+      "DepositWebhook",
       "Evidence",
       "Provider",
       "Reconciliation",

package/src/internal/funding/index.ts

@@ -3,6 +3,7 @@ export * as Chain from './Chain.js'
 export * as Catalog from './Catalog.js'
 export * as Deposit from './Deposit.js'
 export * as DepositAddress from './DepositAddress.js'
+export * as DepositWebhook from './DepositWebhook.js'
 export * as Evidence from './Evidence.js'
 export * as Provider from './Provider.js'
 export * as Reconciliation from './Reconciliation.js'

package/src/internal/webhookDestinations/slack.ts

@@ -41,6 +41,7 @@ type Block =
 /** Per-event emoji + friendly header name; also the notification fallback lead. */
 const friendlyName: Record<Webhooks.Envelope['type'], string> = {
   'block:created': ':link: Block created',
+  'funding:deposit.updated': ':inbox_tray: Funding deposit updated',
   'log:emitted': ':label: Log emitted',
   ping: ':bell: Webhook test ping',
   'token:transfer': ':money_with_wings: Token transfer',
@@ -150,9 +151,23 @@ function renderEvent(
   if (type === 'transaction:included') return transactionLayout(data, base)
   if (type === 'log:emitted') return logLayout(data, base)
   if (type === 'block:created') return blockLayout(data, base)
+  if (type === 'funding:deposit.updated') return fundingDepositLayout(data)
   return pingLayout()
 }
 
+function fundingDepositLayout(data: Record<string, unknown>): Layout {
+  const fields: Field[] = []
+  field(fields, 'Deposit', escape(str(data['id']) ?? 'unknown'))
+  field(fields, 'Status', escape(str(data['status']) ?? 'unknown'))
+  const recipient = str(data['recipient'])
+  if (recipient !== undefined) field(fields, 'Recipient', escape(recipient))
+  return {
+    fields,
+    header: friendlyName['funding:deposit.updated'],
+    text: `Funding deposit updated · ${str(data['status']) ?? 'unknown'}`,
+  }
+}
+
 function transferLayout(data: Record<string, unknown>, base: string | undefined): Layout {
   const amount = str(data['amount'])
   const token =