tapimo 0.9.0 → 0.10.0

package/src/internal/Webhooks.ts

@@ -326,9 +326,59 @@ export async function listActive(
   chainId: number,
   eventType: EventType,
 ): Promise<Subscription[]> {
+  const pairs = await listActiveWithCursors(db, chainId, eventType)
+  return pairs.map((pair) => pair.subscription)
+}
+
+/**
+ * Lists a stream's live active subscriptions paired with their poller cursors,
+ * from one query. The poller's per-tick lookup.
+ */
+export async function listActiveWithCursors(
+  db: Db.Db,
+  chainId: number,
+  eventType: EventType,
+): Promise<{ cursor: string | null; subscription: Subscription }[]> {
   return WebhookSubscriptions.listActive(db, chainId, eventType, new Date().toISOString())
 }
 
+/** Reads every live active subscription on a chain in one poller query. */
+export async function listActiveForChain(
+  db: Db.Db,
+  options: listActiveForChain.Options,
+): Promise<{ cursor: string | null; subscription: Subscription }[]> {
+  return WebhookSubscriptions.listActiveForChain(db, {
+    chainId: options.chainId,
+    eventTypes: options.eventTypes,
+    now: new Date().toISOString(),
+  })
+}
+
+export declare namespace listActiveForChain {
+  /** Filters for the poller's chain-level subscription read. */
+  type Options = Pick<WebhookSubscriptions.listActiveForChain.Options, 'chainId' | 'eventTypes'>
+}
+
+/**
+ * Reads the freshest cursor block across a chain's active subscriptions, or
+ * null when none carry a cursor. Creation checkpoints count at their recorded
+ * head, so a brand-new subscription reads as fresh.
+ */
+export async function maxCursorBlock(db: Db.Db, chainId: number): Promise<number | null> {
+  const cursors = await WebhookSubscriptions.listActiveCursors(
+    db,
+    chainId,
+    new Date().toISOString(),
+  )
+  let max: number | null = null
+  for (const cursor of cursors) {
+    const decoded = Cursor.decode(cursor, ['int', 'int']) ?? Cursor.decode(cursor, ['int'])
+    const block = decoded?.[0]
+    if (typeof block === 'number' && (max === null || block > max)) max = block
+  }
+  return max
+}
+
 /** Reads a subscription's keyset cursor. Returns null when unset. */
 export async function getCursor(db: Db.Db, subscriptionId: string): Promise<string | null> {
   return WebhookSubscriptions.getCursor(db, subscriptionId)
@@ -347,6 +397,19 @@ export declare namespace compareAndSetCursor {
   type Options = WebhookSubscriptions.compareAndSetCursor.Options
 }
 
+/** Writes cursors whose stored values match their expected cursors. */
+export async function compareAndSetCursors(
+  db: Db.Db,
+  options: compareAndSetCursors.Options,
+): Promise<Set<string>> {
+  return WebhookSubscriptions.compareAndSetCursors(db, options)
+}
+
+export declare namespace compareAndSetCursors {
+  /** Options for {@link compareAndSetCursors}. */
+  type Options = WebhookSubscriptions.compareAndSetCursors.Options
+}
+
 /** Writes a subscription's keyset cursor. */
 export async function setCursor(db: Db.Db, subscriptionId: string, cursor: string): Promise<void> {
   await WebhookSubscriptions.setCursor(db, subscriptionId, cursor)
@@ -522,6 +585,7 @@ export async function deliverAndRecord(
   envelope: Envelope,
   options: deliverAndRecord.Options = {},
 ): Promise<WebhookDestination.Result> {
+  const startedAt = Date.now()
   // Snapshot the attempt before recordSuccess/recordFailure mutate the counter.
   const attempt = subscription.failureCount + 1
   const result = await WebhookDestination.from(subscription.destination).deliver({
@@ -530,27 +594,14 @@ export async function deliverAndRecord(
     ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
     ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
   })
+  const stateWriteStartedAt = Date.now()
   if (result.ok) await recordSuccess(db, subscription, options)
   else await recordFailure(db, subscription, options)
-
-  // Emit a `webhook:delivery` metric. recordSuccess/recordFailure are immutable
-  // (they spread into a new record), so `subscription.failureCount` here is still
-  // the pre-mutation snapshot the sink needs to derive the attempt bucket.
-  // Best-effort, like delivery logging.
-  const metrics = options.metrics ? MetricSink.webhooks(options.metrics) : undefined
-  if (metrics) {
-    metrics.record({
-      envelope,
-      result,
-      subscription,
-      trigger: options.trigger ?? 'queue',
-      type: 'webhook:delivery',
-    })
-    metrics.flush()
-  }
+  const stateWriteMs = Date.now() - stateWriteStartedAt
 
   // Append a delivery-log row. Best-effort: a logging failure must never change
   // the delivery outcome the caller (Queue consumer / inline path) acts on.
+  const deliveryLogStartedAt = Date.now()
   try {
     await recordDelivery(
       db,
@@ -560,15 +611,66 @@ export async function deliverAndRecord(
   } catch {
     // delivery logging is best-effort
   }
+  const completedAt = Date.now()
+
+  // Emit after all delivery work so the timings cover every stage. The
+  // subscription is immutable, preserving the pre-attempt failure count.
+  const metrics = options.metrics ? MetricSink.webhooks(options.metrics) : undefined
+  if (metrics) {
+    const eventAt = eventTimestamp(envelope)
+    const envelopeAt = Date.parse(envelope.createdAt)
+    const dequeuedAt = options.dequeuedAt ?? startedAt
+    metrics.record({
+      envelope,
+      queueAttempt: options.queueAttempt,
+      result,
+      subscription,
+      timings: {
+        deliveryLogMs: completedAt - deliveryLogStartedAt,
+        envelopeToQueueMs:
+          options.queuedAt === undefined || Number.isNaN(envelopeAt)
+            ? undefined
+            : Math.max(0, options.queuedAt - envelopeAt),
+        endToEndMs: eventAt === undefined ? undefined : Math.max(0, completedAt - eventAt),
+        eventToEnvelopeMs:
+          eventAt === undefined || Number.isNaN(envelopeAt)
+            ? undefined
+            : Math.max(0, envelopeAt - eventAt),
+        processingMs: Math.max(0, completedAt - dequeuedAt),
+        queueWaitMs:
+          options.queuedAt === undefined ? undefined : Math.max(0, dequeuedAt - options.queuedAt),
+        stateWriteMs,
+        subscriptionReadMs: options.subscriptionReadMs,
+      },
+      trigger: options.trigger ?? 'queue',
+      type: 'webhook:delivery',
+    })
+    metrics.flush()
+  }
 
   return result
 }
 
+/** Reads an event timestamp from an envelope, falling back to its creation time. */
+function eventTimestamp(envelope: Envelope): number | undefined {
+  const value =
+    typeof envelope.data === 'object' &&
+    envelope.data !== null &&
+    'timestamp' in envelope.data &&
+    typeof envelope.data.timestamp === 'string'
+      ? envelope.data.timestamp
+      : envelope.createdAt
+  const timestamp = Date.parse(value)
+  return Number.isNaN(timestamp) ? undefined : timestamp
+}
+
 export declare namespace deliverAndRecord {
   /** Options for {@link deliverAndRecord}. */
   type Options = {
     /** Delivery-log row TTL in ms; defaults to {@link deliveryRetentionMs}. */
     deliveryRetentionMs?: number | undefined
+    /** Queue dequeue time as epoch milliseconds, captured before subscription lookup. */
+    dequeuedAt?: number | undefined
     /** `fetch` implementation passed through to {@link deliver}. */
     fetch?: typeof globalThis.fetch | undefined
     /** Consecutive failures before auto-disabling (default {@link maxFailures}). */
@@ -577,6 +679,12 @@ export declare namespace deliverAndRecord {
     metrics?: Metrics.Metrics | undefined
     /** Clock used for timestamps; injectable for tests. */
     now?: (() => Date) | undefined
+    /** Cloudflare Queue delivery attempt, starting at one; absent for inline delivery paths. */
+    queueAttempt?: number | undefined
+    /** Queue enqueue time as epoch milliseconds, used to isolate queue wait. */
+    queuedAt?: number | undefined
+    /** Authoritative subscription lookup duration, supplied by the queue path. */
+    subscriptionReadMs?: number | undefined
     /** Delivery timeout in ms passed through to {@link deliver}. */
     timeoutMs?: number | undefined
     /** Where this attempt originated; tags the `webhook:delivery` event (default `queue`). */
@@ -594,10 +702,16 @@ export async function deliverCurrentAndRecord(
   envelope: Envelope,
   options: deliverAndRecord.Options = {},
 ): Promise<deliverCurrentAndRecord.Result> {
+  const dequeuedAt = Date.now()
+  const subscriptionReadStartedAt = dequeuedAt
   const subscription = await getSubscription(db, queued.owner, queued.id)
   if (!subscription || subscription.status !== 'active') return { status: 'skipped' }
   return {
-    result: await deliverAndRecord(db, subscription, envelope, options),
+    result: await deliverAndRecord(db, subscription, envelope, {
+      ...options,
+      dequeuedAt,
+      subscriptionReadMs: Date.now() - subscriptionReadStartedAt,
+    }),
     status: 'delivered',
   }
 }

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

@@ -286,6 +286,38 @@ describe('getQuotes', () => {
     },
   )
 
+  test('allows provider quotes within the default deadline', async () => {
+    vi.useFakeTimers()
+    try {
+      const quotes = FundingProvider.getQuotes({
+        ...baseUsdcRequest,
+        providers: [
+          withGetQuote(
+            'relay',
+            () =>
+              new Promise((resolve) => {
+                setTimeout(
+                  () =>
+                    resolve({
+                      destinationAmount: '990000',
+                      sampledAt: '2026-01-01T00:00:00Z',
+                      status: 'available',
+                    }),
+                  3_000,
+                )
+              }),
+          ),
+        ],
+      })
+
+      await vi.advanceTimersByTimeAsync(3_000)
+
+      await expect(quotes).resolves.toHaveLength(1)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   test('aborts providers that exceed the quote deadline', async () => {
     const attempts: FundingProvider.ProviderAttempt[] = []
     let aborted = false
@@ -730,26 +762,34 @@ describe('prepareTransfer', () => {
     })
   })
 
-  test('rounds the slippage floor upward', async () => {
+  test('enforces provider-style slippage rounding', async () => {
+    const inputs: FundingProvider.prepareTransfer.Parameters[] = []
     const prepare = (destinationAmountMin: string) =>
       FundingProvider.prepareTransfer({
         ...prepareOptions,
         providers: [
-          withPrepareTransfer('relay', async () => ({
-            ...preparedResult(),
-            destinationAmount: '10001',
-            destinationAmountMin,
-          })),
+          withPrepareTransfer('relay', async (input) => {
+            inputs.push(input)
+            return {
+              ...preparedResult(),
+              destinationAmount: '10001',
+              destinationAmountMin,
+            }
+          }),
         ],
         slippageBps: 1,
       })
 
-    await expect(prepare('9999')).rejects.toMatchObject({
+    await expect(prepare('9998')).rejects.toMatchObject({
       providerFailure: { failure: 'payload', id: 'relay', operation: 'prepareTransfer' },
     })
+    await expect(prepare('9999')).resolves.toMatchObject({
+      result: { destinationAmount: '10001', destinationAmountMin: '9999' },
+    })
     await expect(prepare('10000')).resolves.toMatchObject({
       result: { destinationAmount: '10001', destinationAmountMin: '10000' },
     })
+    expect(inputs.map((input) => input.slippageBps)).toEqual([1, 1, 1])
   })
 
   test.each([

package/src/internal/funding/Provider.ts

@@ -250,6 +250,8 @@ export namespace schema {
     destinationTransactionHashes: z.array(z.string()),
     id: z.string().check(z.minLength(1)),
     providerState: z.optional(z.record(z.string(), z.unknown())),
+    refundAmountExpected: z.optional(z.string().check(z.regex(/^\d+$/))),
+    refundTransactionHashes: z.array(z.string()),
     sourceTransactionHashes: z.array(z.string()),
     status: z.string().check(z.minLength(1)),
     updatedAt: z.iso.datetime(),
@@ -773,7 +775,9 @@ export type ProviderFailure = {
   provider: Provider
 }
 
-const defaultTimeoutMs = 2_000
+// Slow provider responses can still contain valid quotes; keep the boundary
+// above observed Relay latency while bounding the total request duration.
+const defaultQuoteTimeoutMs = 5_000
 
 /** Returns normalized chains and source tokens supported by quote providers. */
 export function getChains(options: getChains.Options) {
@@ -847,7 +851,7 @@ export async function getQuotes(options: getQuotes.Options) {
             sourceChain: options.sourceChain,
             sourceToken: options.sourceToken,
           },
-          timeoutMs: options.providerTimeoutMs ?? defaultTimeoutMs,
+          timeoutMs: options.providerTimeoutMs ?? defaultQuoteTimeoutMs,
         })
         attempts.set(index, {
           durationMs: performance.now() - start,
@@ -1123,13 +1127,14 @@ export async function prepareTransfer(
         if (Date.parse(expiresAt) <= Date.now()) throw new ProviderPayloadError()
         if (BigInt(result.destinationAmountMin) > BigInt(result.destinationAmount))
           throw new ProviderPayloadError()
-        // A provider that ignores the caller's slippage bound is unusable for
-        // this request; enforce the bound against the quoted minimum.
+        // Providers may floor slippage-adjusted amounts to whole base units;
+        // reject only minima below that allowed rounding.
         if (options.slippageBps !== undefined) {
           const basisPointScale = 10_000n
-          const numerator = BigInt(result.destinationAmount) * BigInt(10_000 - options.slippageBps)
-          const floor = (numerator + basisPointScale - 1n) / basisPointScale
-          if (BigInt(result.destinationAmountMin) < floor) throw new ProviderPayloadError()
+          const minimumAllowed =
+            (BigInt(result.destinationAmount) * BigInt(10_000 - options.slippageBps)) /
+            basisPointScale
+          if (BigInt(result.destinationAmountMin) < minimumAllowed) throw new ProviderPayloadError()
         }
         if (result.action.type === 'evm:calls')
           try {

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

@@ -17,7 +17,6 @@ import * as Evidence from './Evidence.js'
 import * as Reconciliation from './Reconciliation.js'
 import * as Subsidy from './Subsidy.js'
 
-const db = TestApp.database()
 const runtime = Runtime.get()
 const chain = {
   addressFormat: 'hex',
@@ -28,6 +27,8 @@ const chain = {
 
 describe.skipIf(runtime.mode !== 'localnet')('reconcileRequest', () => {
   test('settles an underfilled deposit through the native DEX', async () => {
+    // Vitest retries reuse module state, so each attempt needs a fresh database.
+    const db = TestApp.database()
     const destinationTokenAddress = runtime.fixtures?.crossTokenTransfer?.destinationToken
     if (!destinationTokenAddress) throw new Error('Expected a seeded local DEX pair.')
     const rpcUrl = runtime.rpcUrl
@@ -120,6 +121,7 @@ describe.skipIf(runtime.mode !== 'localnet')('reconcileRequest', () => {
       createdAt: new Date().toISOString(),
       destinationTransactionHashes: [destinationReceipt.receipt.transactionHash],
       id: 'local-deposit-request',
+      refundTransactionHashes: [],
       sourceTransactionHashes: [sourceReceipt.receipt.transactionHash],
       status: 'success',
       updatedAt: new Date().toISOString(),