tapimo 0.11.0 → 0.12.0

package/src/internal/Webhooks.test.ts

@@ -348,6 +348,41 @@ describe('recordSuccess / recordFailure', () => {
     expect(read?.lastDeliveryAt).toBe('2026-01-01T00:00:00.000Z')
   })
 
+  test('recordSuccess refreshes the stamp at most once per precision window', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(db, createInput())
+    const stamped = await Webhooks.recordSuccess(db, created, { now: fixedNow })
+    expect(stamped.lastDeliveryAt).toBe(fixedNow().toISOString())
+
+    // A success moments later has nothing to move: the counter is already zero
+    // and the stamp is inside its window, so the row is never rewritten.
+    const soon = new Date(fixedNow().getTime() + 1_000)
+    await Webhooks.recordSuccess(db, stamped, { now: () => soon })
+    const unmoved = await Webhooks.getSubscription(db, apiKeyOwner, created.id)
+    expect(unmoved?.lastDeliveryAt, 'the stored stamp must not move').toBe(fixedNow().toISOString())
+
+    // Past any plausible window; the exact bound is internal.
+    const later = new Date(fixedNow().getTime() + 3_600_000)
+    await Webhooks.recordSuccess(db, stamped, { now: () => later })
+    const moved = await Webhooks.getSubscription(db, apiKeyOwner, created.id)
+    expect(moved?.lastDeliveryAt).toBe(later.toISOString())
+  })
+
+  test('recordSuccess always resets a non-zero failure counter', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(db, createInput())
+    // Stamp first, so only the counter is out of date: the reset must not be
+    // suppressed by a fresh stamp.
+    const stamped = await Webhooks.recordSuccess(db, created, { now: fixedNow })
+    const failed = await Webhooks.recordFailure(db, stamped, { now: fixedNow })
+    expect(failed.failureCount).toBe(1)
+
+    await Webhooks.recordSuccess(db, failed, { now: fixedNow })
+
+    const read = await Webhooks.getSubscription(db, apiKeyOwner, created.id)
+    expect(read?.failureCount, 'a pending reset must never be skipped').toBe(0)
+  })
+
   test('recordFailure auto-disables at the threshold and drops from the active index', async () => {
     const db = TestApp.database()
     let subscription = await Webhooks.createSubscription(db, createInput())
@@ -375,6 +410,37 @@ describe('recordSuccess / recordFailure', () => {
       await Webhooks.listActiveForChain(db, { chainId: 4217, eventTypes: ['token:transfer'] }),
     ).toMatchInlineSnapshot(`[]`)
   })
+
+  test('recordFailure leaves an already-disabled subscription alone at the cap', async () => {
+    const db = TestApp.database()
+    let subscription = await Webhooks.createSubscription(db, createInput())
+    subscription = await Webhooks.recordFailure(db, subscription, { maxFailures: 2, now: fixedNow })
+    subscription = await Webhooks.recordFailure(db, subscription, { maxFailures: 2, now: fixedNow })
+    expect(subscription.status).toBe('disabled')
+
+    // A straggler failing after the disable has nothing to move: the row is
+    // never rewritten.
+    const later = new Date(fixedNow().getTime() + 1_000)
+    await Webhooks.recordFailure(db, subscription, { maxFailures: 2, now: () => later })
+
+    const read = await Webhooks.getSubscription(db, apiKeyOwner, subscription.id)
+    expect(read?.failureCount, 'the stored counter must not move').toBe(2)
+    expect(read?.updatedAt, 'the stored stamp must not move').toBe(fixedNow().toISOString())
+  })
+
+  test('recordFailure re-disables a re-enabled subscription still at the cap', async () => {
+    const db = TestApp.database()
+    let subscription = await Webhooks.createSubscription(db, createInput())
+    subscription = await Webhooks.recordFailure(db, subscription, { maxFailures: 1, now: fixedNow })
+    expect(subscription.status).toBe('disabled')
+
+    await Webhooks.updateSubscription(db, apiKeyOwner, subscription.id, { status: 'active' })
+
+    // The counter still sits at the cap, so this failure must write again.
+    await Webhooks.recordFailure(db, subscription, { maxFailures: 1, now: fixedNow })
+    const read = await Webhooks.getSubscription(db, apiKeyOwner, subscription.id)
+    expect(read?.status).toBe('disabled')
+  })
 })
 
 describe('sign / verify', () => {
@@ -1015,7 +1081,7 @@ describe('ensureQueueEvents', () => {
     expect(await Webhooks.getQueueEvent(db, reference)).toBeNull()
   })
 
-  test('replaces an expired terminal row so replays stay deliverable', async () => {
+  test('stages a replay once its completion has expired', async () => {
     vi.useFakeTimers({ toFake: ['Date'] })
     vi.setSystemTime(fixedNow())
     try {
@@ -1031,9 +1097,9 @@ describe('ensureQueueEvents', () => {
         }),
       ).toBe(true)
 
-      // Past the dedupe window an unpruned terminal row must not suppress a
+      // Past the dedupe window an unpruned completion must not suppress a
       // replay.
-      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs + 1_000))
+      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
       const replay = await Webhooks.ensureQueueEvents(db, [{ envelope, subscription }])
       expect(replay.created).toBe(1)
       await expect(Webhooks.claimQueueEvent(db, reference)).resolves.toMatchObject({
@@ -1044,7 +1110,7 @@ describe('ensureQueueEvents', () => {
     }
   })
 
-  test('refreshes the observation stamp when a replay replaces an expired row', async () => {
+  test('stamps a fresh observation on a post-expiry replay', async () => {
     vi.useFakeTimers({ toFake: ['Date'] })
     vi.setSystemTime(fixedNow())
     try {
@@ -1057,7 +1123,7 @@ describe('ensureQueueEvents', () => {
         status: 'succeeded',
       })
 
-      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs + 1_000))
+      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
       const observedAt = Date.now() - 250
       await Webhooks.ensureQueueEvents(db, [{ envelope, subscription }], { observedAt })
 
@@ -1070,6 +1136,38 @@ describe('ensureQueueEvents', () => {
       vi.useRealTimers()
     }
   })
+
+  test('suppresses only the completed obligation when staging a mixed batch', async () => {
+    const db = TestApp.database()
+    const done = await stagedObligation(db, 4)
+    const claim = await Webhooks.claimQueueEvent(db, done.reference)
+    if (claim.type !== 'claimed') throw new Error(`Unexpected claim: ${claim.type}`)
+    await Webhooks.completeQueueEvent(db, done.reference, {
+      claimedAt: claim.record.attemptingAt!,
+      status: 'failed',
+    })
+
+    const fresh = Webhooks.buildEnvelope({
+      blockNumber: 124,
+      createdAt: new Date(),
+      data: { amount: '1' },
+      logIndex: 5,
+      subscription: done.subscription,
+    })
+    const batch = await Webhooks.ensureQueueEvents(db, [
+      { envelope: done.envelope, subscription: done.subscription },
+      { envelope: fresh, subscription: done.subscription },
+    ])
+
+    expect(batch.created).toBe(1)
+    await expect(Webhooks.claimQueueEvent(db, done.reference)).resolves.toEqual({
+      status: 'failed',
+      type: 'terminal',
+    })
+    await expect(Webhooks.claimQueueEvent(db, batch.references[1]!)).resolves.toMatchObject({
+      type: 'claimed',
+    })
+  })
 })
 
 describe('claimQueueEvent', () => {
@@ -1082,6 +1180,22 @@ describe('claimQueueEvent', () => {
     vi.useRealTimers()
   })
 
+  test('reads an expired completion as missing', async () => {
+    const db = TestApp.database()
+    const { reference } = await stagedObligation(db)
+    const claim = await Webhooks.claimQueueEvent(db, reference)
+    if (claim.type !== 'claimed') throw new Error(`Unexpected claim: ${claim.type}`)
+    await Webhooks.completeQueueEvent(db, reference, {
+      claimedAt: claim.record.attemptingAt!,
+      status: 'succeeded',
+    })
+
+    // Matches a pruned terminal row: past the dedupe window the completion is
+    // invisible everywhere, not only to staging.
+    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
+    await expect(Webhooks.claimQueueEvent(db, reference)).resolves.toEqual({ type: 'missing' })
+  })
+
   test('claims a due obligation once and reclaims after staleness', async () => {
     const db = TestApp.database()
     const { reference } = await stagedObligation(db)
@@ -1146,17 +1260,17 @@ describe('claimQueueEvent', () => {
 
     // Pending obligations never expire; only terminal transitions stamp a
     // dedupe deadline.
-    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs * 3))
+    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs * 3))
     await expect(Webhooks.claimQueueEvent(db, reference)).resolves.toMatchObject({
       type: 'claimed',
     })
   })
 
-  test('never prunes pending work', async () => {
+  test('leaves pending obligations claimable across a prune', async () => {
     const db = TestApp.database()
     const { reference } = await stagedObligation(db)
 
-    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs + 1_000))
+    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
     await Webhooks.pruneExpired(db)
     const claim = await Webhooks.claimQueueEvent(db, reference)
     expect(claim.type).toBe('claimed')

package/src/internal/Webhooks.ts

@@ -3,6 +3,7 @@ import { Hash, Hex } from 'ox'
 import type * as app_Webhooks from '../apps/data/routes/webhooks.js'
 import type * as Db from '../db/Db.js'
 import * as WebhookDeliveries from '../db/tables/webhookDeliveries.js'
+import * as WebhookQueueCompletions from '../db/tables/webhookQueueCompletions.js'
 import * as WebhookQueueEvents from '../db/tables/webhookQueueEvents.js'
 import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import type * as Metrics from '../Metrics.js'
@@ -95,7 +96,8 @@ export type Subscription = {
   filters: Record<string, unknown>
   /** Subscription id (`wh_…`). */
   id: string
-  /** ISO timestamp of the last successful delivery, if any. */
+  /** ISO timestamp of the last successful delivery, if any. Display only:
+   * refreshed at most once per precision window. */
   lastDeliveryAt?: string | undefined
   /** Authenticated owner. */
   owner: Owner
@@ -105,7 +107,8 @@ export type Subscription = {
   secret: string
   /** Lifecycle status. */
   status: Status
-  /** ISO timestamp of the last mutation. */
+  /** ISO timestamp of the last mutation. May lag repeat deliveries; see
+   * `lastDeliveryAt`. */
   updatedAt: string
 }
 
@@ -406,11 +409,18 @@ export async function getCursor(db: Db.Db, subscriptionId: string): Promise<stri
  * deliveries past retention. Reads already filter expiry at query time; this
  * is the janitor reclaiming space, run best-effort on a schedule.
  */
-export async function pruneExpired(db: Db.Db, options: pruneExpired.Options = {}): Promise<void> {
+export async function pruneExpired(
+  db: Db.Db,
+  options: pruneExpired.Options = {},
+): Promise<pruneExpired.Result> {
   const iso = (options.now ?? (() => new Date()))().toISOString()
-  await WebhookDeliveries.pruneExpired(db, iso)
-  await WebhookQueueEvents.pruneExpired(db, iso)
-  await WebhookSubscriptions.pruneExpired(db, iso)
+  // Sequential on purpose: the subscription delete cascades into the other
+  // tables, so overlapping it with their prunes risks deadlocks.
+  return {
+    completions: await WebhookQueueCompletions.pruneExpired(db, iso),
+    deliveries: await WebhookDeliveries.pruneExpired(db, iso),
+    subscriptions: await WebhookSubscriptions.pruneExpired(db, iso),
+  }
 }
 
 export declare namespace pruneExpired {
@@ -419,6 +429,16 @@ export declare namespace pruneExpired {
     /** Clock used for expiry evaluation; injectable for tests. */
     now?: (() => Date) | undefined
   }
+
+  /** Rows deleted per table; a count pinned at the batch bound means expiry is outpacing pruning. */
+  type Result = {
+    /** Deleted `webhook_queue_completions` rows. */
+    completions: number
+    /** Deleted `webhook_deliveries` rows. */
+    deliveries: number
+    /** Deleted `webhook_subscriptions` rows. */
+    subscriptions: number
+  }
 }
 
 /**
@@ -427,6 +447,13 @@ export declare namespace pruneExpired {
  */
 export const deliveryRetentionMs = 7 * 24 * 60 * 60 * 1_000
 
+/**
+ * Completions dedupe window: replays of a completed obligation are suppressed
+ * this long. Deliberately its own literal so per-deployment log-retention
+ * tuning cannot move it.
+ */
+export const dedupeRetentionMs = 7 * 24 * 60 * 60 * 1_000
+
 /** A compact Cloudflare Queue message referencing a durable staged envelope. */
 export type QueueReference = {
   /** Idempotent event id of the staged envelope. */
@@ -441,8 +468,6 @@ export type QueueEvent = QueueReference & {
   createdAt: string
   /** Full envelope loaded by the Queue consumer. */
   envelope: Envelope
-  /** ISO timestamp after which an unconsumed envelope may be pruned. */
-  expiresAt: string
 }
 
 /** A claim newer than this counts as an in-flight attempt; above the 10s destination timeout default. */
@@ -467,7 +492,6 @@ export async function ensureQueueEvents(
   options: ensureQueueEvents.Options = {},
 ): Promise<ensureQueueEvents.Result> {
   const now = (options.now ?? (() => new Date()))()
-  const expiresAt = new Date(now.getTime() + (options.ttl ?? deliveryRetentionMs)).toISOString()
   // Carried so the delivery worker can measure observation-to-attempt without
   // re-reading the block; replays have no observation and stay null.
   const observedAt =
@@ -476,9 +500,6 @@ export async function ensureQueueEvents(
     createdAt: now.toISOString(),
     envelope,
     eventId: envelope.id,
-    // Inert while pending; the meaningful dedupe deadline is stamped at
-    // terminal transitions.
-    expiresAt,
     // Due immediately; the value orders the sweep so it is never null here.
     nextAttemptAt: now.toISOString(),
     observedAt,
@@ -499,14 +520,12 @@ export declare namespace ensureQueueEvents {
     subscription: Subscription
   }
 
-  /** Staged-envelope retention options. */
+  /** Staging options. */
   type Options = {
     /** Clock used for staging timestamps. */
     now?: (() => Date) | undefined
     /** Epoch ms the head owing these events was observed; absent on replays. */
     observedAt?: number | undefined
-    /** Staged-envelope TTL in ms; defaults to {@link deliveryRetentionMs}. */
-    ttl?: number | undefined
   }
 
   /** Created-row count plus references for every requested obligation. */
@@ -542,7 +561,7 @@ export function completeQueueEvent(
 ): Promise<boolean> {
   return WebhookQueueEvents.complete(db, reference, {
     ...options,
-    expiresAt: new Date(Date.now() + deliveryRetentionMs).toISOString(),
+    expiresAt: new Date(Date.now() + dedupeRetentionMs).toISOString(),
   })
 }
 
@@ -552,7 +571,7 @@ export declare namespace completeQueueEvent {
     /** Claim marker from the claimed record's `attemptingAt`. */
     claimedAt: string
     /** Terminal obligation outcome. */
-    status: WebhookQueueEvents.TerminalStatus
+    status: WebhookQueueCompletions.TerminalStatus
   }
 }
 
@@ -766,10 +785,17 @@ export async function getDelivery(
  */
 export const maxFailures = 10
 
+/**
+ * How stale `lastDeliveryAt` may get before a success rewrites it. Read only
+ * for display, so exactness is traded for not rewriting the row per delivery.
+ */
+const lastDeliveryPrecisionMs = 60_000
+
 /**
  * Records a successful delivery: resets the consecutive-failure counter and
- * stamps `lastDeliveryAt`. A column-targeted update, so a concurrent patch is
- * never clobbered by the stale copy carried through the delivery queue.
+ * refreshes `lastDeliveryAt` at most once per precision window. Returns the
+ * written row, or the caller's snapshot when the write was skipped or the row
+ * deleted.
  */
 export async function recordSuccess(
   db: Db.Db,
@@ -777,11 +803,13 @@ export async function recordSuccess(
   options: recordSuccess.Options = {},
 ): Promise<Subscription> {
   const now = (options.now ?? (() => new Date()))()
-  const iso = now.toISOString()
-  const next = await WebhookSubscriptions.recordSuccess(db, subscription.id, iso)
-  // A concurrently deleted subscription is not resurrected; return the
-  // optimistic next state so the caller still observes the outcome.
-  return next ?? { ...subscription, failureCount: 0, lastDeliveryAt: iso, updatedAt: iso }
+  const next = await WebhookSubscriptions.recordSuccess(db, subscription.id, {
+    now: now.toISOString(),
+    staleBefore: new Date(now.getTime() - lastDeliveryPrecisionMs).toISOString(),
+  })
+  // No row means the write was skipped or the row was deleted; neither
+  // resurrects, so keep the caller's timestamps.
+  return next ?? { ...subscription, failureCount: 0 }
 }
 
 export declare namespace recordSuccess {
@@ -796,7 +824,9 @@ export declare namespace recordSuccess {
  * Records a failed delivery: atomically increments the consecutive-failure
  * counter and, once it reaches `maxFailures`, sets `status: 'disabled'` so the
  * subscription drops out of the partial active index (surfaced via the API).
- * Returns the updated subscription.
+ * Once disabled at the cap the row is left alone, so an outage's in-flight
+ * failures stop contending on its lock. Returns the written row, or the
+ * caller's snapshot advanced optimistically.
  */
 export async function recordFailure(
   db: Db.Db,
@@ -808,14 +838,14 @@ export async function recordFailure(
   const max = options.maxFailures ?? maxFailures
   const next = await WebhookSubscriptions.recordFailure(db, subscription.id, max, iso)
   if (next) return next
-  // A concurrently deleted subscription is not resurrected; return the
-  // optimistic next state so the caller still observes the outcome.
-  const failureCount = subscription.failureCount + 1
+  // No row means skipped (already disabled at the cap) or deleted; neither
+  // resurrects, so keep the caller's timestamps. Capped so chained skips
+  // cannot grow the counter past what the store would hold.
+  const failureCount = Math.min(subscription.failureCount + 1, max)
   return {
     ...subscription,
     failureCount,
     ...(failureCount >= max ? { status: 'disabled' as const } : {}),
-    updatedAt: iso,
   }
 }
 

package/src/internal/funding/Deposit.ts

@@ -4,6 +4,7 @@ import type * as Db from '../../db/Db.js'
 import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
 import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
 import * as Id from '../Id.js'
+import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
 import * as Provider from './Provider.js'
 
@@ -115,22 +116,25 @@ export namespace schema {
     )
 
   /** Customer-safe explanation of a deposit status. */
-  export const StatusReason = z
-    .object({
-      code: z
-        .enum(statusReasonCodes)
-        .check(
-          z.describe('Stable machine-readable reason code.'),
-          z.meta({ examples: ['delivery_liquidity_unavailable'] }),
-        ),
-      message: z
-        .string()
-        .check(
-          z.describe('Human-readable explanation of the current status.'),
-          z.meta({ examples: ['The required destination amount is not currently available.'] }),
-        ),
-    })
-    .check(z.describe('Why a deposit needs attention or recovery.'))
+  export const StatusReason = OpenApi.component(
+    z
+      .object({
+        code: z
+          .enum(statusReasonCodes)
+          .check(
+            z.describe('Stable machine-readable reason code.'),
+            z.meta({ examples: ['delivery_liquidity_unavailable'] }),
+          ),
+        message: z
+          .string()
+          .check(
+            z.describe('Human-readable explanation of the current status.'),
+            z.meta({ examples: ['The required destination amount is not currently available.'] }),
+          ),
+      })
+      .check(z.describe('Why a deposit needs attention or recovery.')),
+    'FundingDepositStatusReason',
+  )
 
   /** Public fields persisted as the deposit snapshot. */
   export const Snapshot = z
@@ -189,54 +193,57 @@ export namespace schema {
     )
 
   /** One detected funding deposit. */
-  export const FundingDeposit = z
-    .object({
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the deposit was first detected (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:01:00.000Z'] }),
-        ),
-      depositAddressId: Snapshot.shape.depositAddressId,
-      detectionTrigger: z.optional(DetectionTrigger),
-      destinationAmount: Snapshot.shape.destinationAmount,
-      destinationAmountRequired: Snapshot.shape.destinationAmountRequired,
-      destinationChain: Snapshot.shape.destinationChain,
-      destinationToken: Snapshot.shape.destinationToken,
-      destinationTransactionHashes: Snapshot.shape.destinationTransactionHashes,
-      id: z
-        .string()
-        .check(
-          z.regex(/^fdp_[A-Za-z0-9_-]+$/),
-          z.describe('Funding deposit id (`fdp_…`).'),
-          z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-      provider: Snapshot.shape.provider,
-      recipient: Snapshot.shape.recipient,
-      refundAddress: Snapshot.shape.refundAddress,
-      refundAmount: Snapshot.shape.refundAmount,
-      refundTransactionHashes: Snapshot.shape.refundTransactionHashes,
-      sender: Snapshot.shape.sender,
-      sourceAmount: Snapshot.shape.sourceAmount,
-      sourceChain: Snapshot.shape.sourceChain,
-      sourceToken: Snapshot.shape.sourceToken,
-      sourceTransactionHashes: Snapshot.shape.sourceTransactionHashes,
-      sourceTransferIndex: z
-        .optional(z.number().check(z.int(), z.minimum(0)))
-        .check(
-          z.describe('Verified transfer position within the source transaction.'),
-          z.meta({ examples: [0] }),
-        ),
-      status: Status,
-      statusReason: z.optional(StatusReason),
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the deposit last materially changed (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:02:00.000Z'] }),
-        ),
-    })
-    .check(z.describe('One detected deposit and its delivery status.'))
+  export const FundingDeposit = OpenApi.component(
+    z
+      .object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit was first detected (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:01:00.000Z'] }),
+          ),
+        depositAddressId: Snapshot.shape.depositAddressId,
+        detectionTrigger: z.optional(DetectionTrigger),
+        destinationAmount: Snapshot.shape.destinationAmount,
+        destinationAmountRequired: Snapshot.shape.destinationAmountRequired,
+        destinationChain: Snapshot.shape.destinationChain,
+        destinationToken: Snapshot.shape.destinationToken,
+        destinationTransactionHashes: Snapshot.shape.destinationTransactionHashes,
+        id: z
+          .string()
+          .check(
+            z.regex(/^fdp_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit id (`fdp_…`).'),
+            z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+        provider: Snapshot.shape.provider,
+        recipient: Snapshot.shape.recipient,
+        refundAddress: Snapshot.shape.refundAddress,
+        refundAmount: Snapshot.shape.refundAmount,
+        refundTransactionHashes: Snapshot.shape.refundTransactionHashes,
+        sender: Snapshot.shape.sender,
+        sourceAmount: Snapshot.shape.sourceAmount,
+        sourceChain: Snapshot.shape.sourceChain,
+        sourceToken: Snapshot.shape.sourceToken,
+        sourceTransactionHashes: Snapshot.shape.sourceTransactionHashes,
+        sourceTransferIndex: z
+          .optional(z.number().check(z.int(), z.minimum(0)))
+          .check(
+            z.describe('Verified transfer position within the source transaction.'),
+            z.meta({ examples: [0] }),
+          ),
+        status: Status,
+        statusReason: z.optional(StatusReason),
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit last materially changed (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:02:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('One detected deposit and its delivery status.')),
+    'FundingDeposit',
+  )
 }
 
 /** Stored public snapshot of a funding deposit. */