tapimo 0.10.2 → 0.12.0

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/funding/providers/index.test.ts

@@ -4,6 +4,7 @@ import * as Across from './across.js'
 import * as Relay from './relay.js'
 import * as Rhino from './rhino.js'
 import * as Squid from './squid.js'
+import * as Stargate from './stargate.js'
 import * as Symbiosis from './symbiosis.js'
 
 const now = () => new Date('2026-01-01T00:00:00.000Z')
@@ -21,6 +22,10 @@ const providers = [
     integratorId: 'squid-integrator-id',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
+  Stargate.stargate({
+    apiKey: 'layerzero-api-key',
+    userAddress: '0x1111111111111111111111111111111111111111',
+  }),
   Symbiosis.symbiosis({ userAddress: '0x1111111111111111111111111111111111111111' }),
 ] as const
 
@@ -335,6 +340,126 @@ describe('funding providers', () => {
     })
   })
 
+  test('maps the best Stargate quote to an available quote result', async () => {
+    const requests: RecordedRequest[] = []
+    const candidate = quoteCandidate('stargate')
+    const fetch = recordingFetch(requests, async () => jsonResponse(stargateQuotes(candidate)))
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      baseUrl: 'https://layerzero.test/v1/',
+      fetch,
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    const result = await provider.getQuote(getQuoteInput(candidate), new AbortController().signal)
+
+    expect(requests).toHaveLength(1)
+    expect(requests[0]?.url.pathname).toBe('/v1/quotes')
+    expect(new Headers(requests[0]?.init?.headers).get('user-agent')).toBe('tempo-api')
+    expect(new Headers(requests[0]?.init?.headers).get('x-api-key')).toBe('layerzero-api-key')
+    expect(jsonRequestBody(requests[0])).toEqual({
+      amount: '1000000',
+      dstChainKey: 'tempo',
+      dstTokenAddress: candidate.destinationToken.address,
+      dstWalletAddress: '0x1111111111111111111111111111111111111111',
+      options: { amountType: 'EXACT_SRC_AMOUNT' },
+      srcChainKey: 'base',
+      srcTokenAddress: candidate.sourceToken.address,
+      srcWalletAddress: '0x1111111111111111111111111111111111111111',
+    })
+    expect(result).toEqual({
+      expiresAt: '2026-01-01T00:01:00.000Z',
+      destinationAmountMin: '999100',
+      destinationAmount: '999600',
+      quality: {
+        estimatedSeconds: 259,
+        liquiditySource: 'providerQuote',
+        sourceDetail: 'stargate:value-transfer-v1:bus',
+        tier: 'liquid',
+      },
+      sampledAt: '2026-01-01T00:00:00.000Z',
+      status: 'available',
+    })
+  })
+
+  test('skips expired Stargate alternatives', async () => {
+    const candidate = quoteCandidate('stargate')
+    const response = stargateQuotes(candidate)
+    response.quotes[2]!.expiresAt = '2026-01-01T00:00:00.000Z'
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse(response)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    await expect(
+      provider.getQuote(getQuoteInput(candidate), new AbortController().signal),
+    ).resolves.toMatchObject({
+      destinationAmountMin: '999000',
+      destinationAmount: '999500',
+      quality: {
+        sourceDetail: 'stargate:value-transfer-v1:taxi',
+        tier: 'liquid',
+      },
+      status: 'available',
+    })
+  })
+
+  test('exposes Base and Ethereum Stargate quote candidates', () => {
+    expect(
+      ['base', 'ethereum'].map((sourceChain) => quoteCandidate('stargate', { sourceChain }).id),
+    ).toEqual(['base-usdc-tempo-usdce-stargate', 'ethereum-usdc-tempo-usdce-stargate'])
+  })
+
+  test('maps responses without Stargate routes to unavailable quote results', async () => {
+    const candidate = quoteCandidate('stargate')
+    const response = stargateQuotes(candidate)
+    response.quotes = response.quotes.filter((quote) => quote.routeSteps[0]?.type === 'CCTP')
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse(response)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    await expect(
+      provider.getQuote(getQuoteInput(candidate), new AbortController().signal),
+    ).resolves.toMatchObject({
+      quality: {
+        sourceDetail: 'stargate:value-transfer-v1:NO_STARGATE_ROUTE',
+        tier: 'unavailable',
+      },
+      status: 'unavailable',
+    })
+  })
+
+  test('rejects malformed Stargate quotes', async () => {
+    const candidate = quoteCandidate('stargate')
+    const response = stargateQuotes(candidate)
+    response.quotes[2]!.srcAmount = '1'
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse(response)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    await expect(
+      provider.getQuote(getQuoteInput(candidate), new AbortController().signal),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[FundingProvider.ProviderPayloadError]`)
+  })
+
+  test('rejects invalid Stargate configuration', () => {
+    expect(() =>
+      Stargate.stargate({
+        apiKey: '',
+        userAddress: '0x1111111111111111111111111111111111111111',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(`[FundingProvider.ProviderConfigurationError]`)
+  })
+
   test('maps successful Symbiosis quotes to available quote results', async () => {
     const requests: RecordedRequest[] = []
     const candidate = quoteCandidate('symbiosis')
@@ -961,6 +1086,32 @@ describe('funding providers', () => {
     })
   })
 
+  test('returns bounded Stargate failure diagnostics', async () => {
+    const candidate = quoteCandidate('stargate')
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse({ message: 'Unauthorized' }, 401)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+    const cause = await provider
+      .getQuote(getQuoteInput(candidate), new AbortController().signal)
+      .catch((error: unknown) => error)
+
+    expect(
+      FundingProvider.failure({
+        cause,
+        operation: 'getQuote',
+        provider: getProvider('stargate'),
+      }),
+    ).toEqual({
+      failure: 'http',
+      id: 'stargate',
+      operation: 'getQuote',
+      status: 401,
+    })
+  })
+
   test('returns bounded Symbiosis failure diagnostics', () => {
     expect(
       FundingProvider.failure({
@@ -1059,6 +1210,40 @@ function squidQuote(candidate: FundingProvider.getQuote.Parameters['candidate'])
   }
 }
 
+function stargateQuotes(candidate: FundingProvider.getQuote.Parameters['candidate']) {
+  return {
+    error: null,
+    quotes: [
+      {
+        dstAmount: '999900',
+        dstAmountMin: '999800',
+        duration: { estimated: '10000' },
+        id: 'quote-cctp',
+        routeSteps: [{ srcChainKey: 'base', type: 'CCTP' }],
+        srcAmount: candidate.sourceAmount.amount,
+      },
+      {
+        dstAmount: '999500',
+        dstAmountMin: '999000',
+        duration: { estimated: '27600' },
+        expiresAt: '2026-01-01T00:01:00.000Z',
+        id: 'quote-stargate-taxi',
+        routeSteps: [{ srcChainKey: 'base', type: 'STARGATE_V2_TAXI' }],
+        srcAmount: candidate.sourceAmount.amount,
+      },
+      {
+        dstAmount: '999600',
+        dstAmountMin: '999100',
+        duration: { estimated: '258899.99999999997' },
+        expiresAt: '2026-01-01T00:01:00.000Z',
+        id: 'quote-stargate-bus',
+        routeSteps: [{ srcChainKey: 'base', type: 'STARGATE_V2_BUS' }],
+        srcAmount: candidate.sourceAmount.amount,
+      },
+    ],
+  }
+}
+
 function symbiosisQuote(candidate: FundingProvider.getQuote.Parameters['candidate']) {
   const source =
     candidate.sourceChain.kind === 'tron'