tapimo 0.7.2 → 0.8.0

package/src/cloudflare.ts

@@ -4,6 +4,9 @@
 // @ts-ignore
 import { DurableObject as CloudflareDurableObject } from 'cloudflare:workers'
 
+import * as Db from './db/Db.js'
+import * as Funding from './internal/funding/index.js'
+import * as Metrics from './Metrics.js'
 import * as Store from './internal/Store.js'
 
 type State = ConstructorParameters<typeof CloudflareDurableObject>[0]
@@ -68,3 +71,279 @@ export class DurableObject extends CloudflareDurableObject {
     return this.#store.swap!(key, expected, next, options)
   }
 }
+
+const fundingSourceAlarmIntervalMs = 500
+const fundingSourceRetryIntervalMs = 2_000
+
+type FundingSourceConfiguration = {
+  chainId: string
+  rpcUrls: readonly string[]
+  tokenAddress: string
+}
+
+type FundingSourceRoute = Funding.SourceObservation.Route
+
+type FundingSourceRegisterOptions = FundingSourceConfiguration & {
+  route: FundingSourceRoute
+}
+
+type FundingSourceSyncOptions = FundingSourceConfiguration & {
+  routes: readonly FundingSourceRoute[]
+}
+
+type FundingSourceConfigurationRow = {
+  value: string
+}
+
+type FundingSourceRouteRow = {
+  address: string
+  id: string
+}
+
+type FundingSourceStateRow = {
+  value: string
+}
+
+/** Cloudflare Durable Object that detects EVM funding deposits before provider indexing. */
+export class FundingSourceObserver<
+  environment extends FundingSourceObserver.Environment = FundingSourceObserver.Environment,
+> extends CloudflareDurableObject {
+  /** Durable Object storage and alarm context. */
+  protected context: State
+  /** Cloudflare bindings used by the observer. */
+  protected environment: environment
+
+  constructor(ctx: State, env: environment) {
+    super(ctx, env as never)
+    this.context = ctx
+    this.environment = env
+    void ctx.blockConcurrencyWhile(async () => {
+      ctx.storage.sql.exec(
+        'CREATE TABLE IF NOT EXISTS configuration (id INTEGER PRIMARY KEY CHECK (id = 1), value TEXT NOT NULL)',
+      )
+      ctx.storage.sql.exec('CREATE TABLE IF NOT EXISTS backfills (id TEXT PRIMARY KEY)')
+      ctx.storage.sql.exec(
+        'CREATE TABLE IF NOT EXISTS routes (id TEXT PRIMARY KEY, address TEXT NOT NULL UNIQUE)',
+      )
+      ctx.storage.sql.exec(
+        'CREATE TABLE IF NOT EXISTS state (key TEXT PRIMARY KEY, value TEXT NOT NULL)',
+      )
+    })
+  }
+
+  /** Registers one newly created deposit address and starts source observation. */
+  async register(options: FundingSourceRegisterOptions): Promise<void> {
+    const configuration = serializeFundingSourceConfiguration(options)
+    const route = this.context.storage.sql
+      .exec<FundingSourceRouteRow>('SELECT id, address FROM routes WHERE id = ?', options.route.id)
+      .toArray()[0]
+    this.context.storage.transactionSync(() => {
+      this.context.storage.sql.exec(
+        'INSERT OR REPLACE INTO configuration (id, value) VALUES (1, ?)',
+        configuration,
+      )
+      this.context.storage.sql.exec(
+        'INSERT OR REPLACE INTO routes (id, address) VALUES (?, ?)',
+        options.route.id,
+        options.route.address.toLowerCase(),
+      )
+      if (!route || route.address.toLowerCase() !== options.route.address.toLowerCase())
+        this.context.storage.sql.exec(
+          'INSERT OR IGNORE INTO backfills (id) VALUES (?)',
+          options.route.id,
+        )
+    })
+    await this.#ensureAlarm()
+  }
+
+  /** Replaces the active routes from the database and repairs alarm scheduling. */
+  async sync(options: FundingSourceSyncOptions): Promise<void> {
+    const configuration = serializeFundingSourceConfiguration(options)
+    const existing = new Map(
+      this.context.storage.sql
+        .exec<FundingSourceRouteRow>('SELECT id, address FROM routes ORDER BY id')
+        .toArray()
+        .map((route: FundingSourceRouteRow) => [route.id, route.address.toLowerCase()] as const),
+    )
+    const changed = options.routes.filter(
+      (route) => existing.get(route.id) !== route.address.toLowerCase(),
+    )
+    this.context.storage.transactionSync(() => {
+      this.context.storage.sql.exec(
+        'INSERT OR REPLACE INTO configuration (id, value) VALUES (1, ?)',
+        configuration,
+      )
+      this.context.storage.sql.exec('DELETE FROM routes')
+      for (const route of options.routes)
+        this.context.storage.sql.exec(
+          'INSERT INTO routes (id, address) VALUES (?, ?)',
+          route.id,
+          route.address.toLowerCase(),
+        )
+      this.context.storage.sql.exec('DELETE FROM backfills WHERE id NOT IN (SELECT id FROM routes)')
+      for (const route of changed)
+        this.context.storage.sql.exec('INSERT OR IGNORE INTO backfills (id) VALUES (?)', route.id)
+    })
+    if (options.routes.length === 0) {
+      await this.context.storage.deleteAlarm()
+      return
+    }
+    await this.#ensureAlarm()
+  }
+
+  /** Scans confirmed source blocks and persists newly observed deposits. */
+  async alarm(): Promise<void> {
+    const metrics = this.createMetrics()
+    const configuration = this.#readConfiguration()
+    const routes: FundingSourceRouteRow[] = this.context.storage.sql
+      .exec<FundingSourceRouteRow>('SELECT id, address FROM routes ORDER BY id')
+      .toArray()
+    if (!configuration || routes.length === 0) return
+
+    try {
+      const cursor = this.context.storage.sql
+        .exec<FundingSourceStateRow>("SELECT value FROM state WHERE key = 'cursor'")
+        .toArray()[0]
+      const result = await Funding.SourceObservation.scan({
+        chainId: configuration.chainId,
+        ...(cursor ? { cursor: BigInt(cursor.value) } : {}),
+        routes,
+        rpcUrls: configuration.rpcUrls,
+        tokenAddress: configuration.tokenAddress,
+      })
+      const backfills = this.context.storage.sql
+        .exec<FundingSourceRouteRow>(
+          'SELECT routes.id, routes.address FROM routes INNER JOIN backfills ON backfills.id = routes.id ORDER BY routes.id',
+        )
+        .toArray()
+      // Backfill new routes independently so the main cursor retains any older shard backlog.
+      const backfill = await (async () => {
+        if (!cursor || backfills.length === 0) return undefined
+        return Funding.SourceObservation.scan({
+          chainId: configuration.chainId,
+          routes: backfills,
+          rpcUrls: configuration.rpcUrls,
+          tokenAddress: configuration.tokenAddress,
+        })
+      })()
+      const database = Db.get(() =>
+        Db.postgres({ connectionString: this.environment.HYPERDRIVE.connectionString }),
+      )
+      const routesById = new Map(routes.map((route) => [route.id, route] as const))
+      const observations = new Map(
+        [...result.observations, ...(backfill?.observations ?? [])].map((observation) => [
+          `${observation.addressId}:${observation.transactionHash.toLowerCase()}:${observation.transferIndex}`,
+          observation,
+        ]),
+      ).values()
+      for (const observation of observations) {
+        const route = routesById.get(observation.addressId)
+        if (!route) continue
+        const persisted = await Funding.SourceObservation.observe(database, {
+          ...observation,
+          recipient: route.address,
+        })
+        if (
+          persisted.type === 'ignored' ||
+          persisted.record.providerRequestId !== null ||
+          Funding.Deposit.isTerminal(persisted.record.status)
+        )
+          continue
+        await this.environment.FUNDING_RECONCILIATION_QUEUE.send({
+          addressId: observation.addressId,
+          trigger: 'chain',
+          type: 'funding:deposit-address:reconcile',
+        })
+        metrics.count('funding_source_observer_deposit_count', 1, {
+          chain: configuration.chainId,
+          outcome: persisted.type,
+        })
+      }
+      this.context.storage.transactionSync(() => {
+        this.context.storage.sql.exec(
+          "INSERT OR REPLACE INTO state (key, value) VALUES ('cursor', ?)",
+          result.cursor.toString(),
+        )
+        for (const route of backfills)
+          this.context.storage.sql.exec('DELETE FROM backfills WHERE id = ?', route.id)
+      })
+      metrics.count('funding_source_observer_scan_count', 1, {
+        chain: configuration.chainId,
+        outcome: 'completed',
+      })
+      metrics.gauge(
+        'funding_source_observer_block_lag',
+        Math.max(0, Number(result.head - result.cursor)),
+        { chain: configuration.chainId },
+      )
+      await this.context.storage.setAlarm(
+        result.cursor < result.head ? Date.now() : Date.now() + fundingSourceAlarmIntervalMs,
+      )
+    } catch (cause) {
+      metrics.count('funding_source_observer_scan_count', 1, {
+        chain: configuration.chainId,
+        outcome: 'failed',
+      })
+      this.capture(cause)
+      await this.context.storage.setAlarm(Date.now() + fundingSourceRetryIntervalMs)
+    } finally {
+      metrics.flush()
+    }
+  }
+
+  /** Reports one source-observer failure. */
+  protected capture(cause: unknown): void {
+    console.error(cause)
+  }
+
+  /** Creates the operational metric sink used by one alarm invocation. */
+  protected createMetrics(): Metrics.Metrics {
+    return Metrics.cloudflare({
+      enabled: Boolean(this.environment.ENVIRONMENT),
+      environment: this.environment.ENVIRONMENT ?? 'development',
+      service: 'tapimo',
+    })
+  }
+
+  #configuration(): string | undefined {
+    return this.context.storage.sql
+      .exec<FundingSourceConfigurationRow>('SELECT value FROM configuration WHERE id = 1')
+      .toArray()[0]?.value
+  }
+
+  async #ensureAlarm(): Promise<void> {
+    if ((await this.context.storage.getAlarm()) === null)
+      await this.context.storage.setAlarm(Date.now())
+  }
+
+  #readConfiguration(): FundingSourceConfiguration | undefined {
+    const value = this.#configuration()
+    return value ? (JSON.parse(value) as FundingSourceConfiguration) : undefined
+  }
+}
+
+export declare namespace FundingSourceObserver {
+  /** Cloudflare bindings and deployment metadata used by the observer. */
+  type Environment = {
+    /** Deployment environment included in operational metrics. */
+    ENVIRONMENT?: string | undefined
+    /** Queue that receives deposit-address reconciliation work. */
+    FUNDING_RECONCILIATION_QUEUE: {
+      /** Enqueues one chain-detected address for reconciliation. */
+      send(message: Funding.Provider.Webhook.receive.Dispatchable): Promise<unknown>
+    }
+    /** Authoritative Postgres connection exposed through Hyperdrive. */
+    HYPERDRIVE: {
+      /** PostgreSQL connection string supplied by the Hyperdrive binding. */
+      connectionString: string
+    }
+  }
+}
+
+function serializeFundingSourceConfiguration(options: FundingSourceConfiguration): string {
+  return JSON.stringify({
+    chainId: options.chainId,
+    rpcUrls: options.rpcUrls,
+    tokenAddress: options.tokenAddress.toLowerCase(),
+  } satisfies FundingSourceConfiguration)
+}

package/src/db/Db.ts

@@ -17,6 +17,7 @@ import type * as EarnVaults from './tables/earnVaults.js'
 import type * as EnabledBillingSources from './tables/enabledBillingSources.js'
 import type * as FundingCatalog from './tables/fundingCatalog.js'
 import type * as FundingDepositAddresses from './tables/fundingDepositAddresses.js'
+import type * as FundingDepositRequestObservations from './tables/fundingDepositRequestObservations.js'
 import type * as FundingDeposits from './tables/fundingDeposits.js'
 import type * as FundingIdempotency from './tables/fundingIdempotency.js'
 import type * as FundingTransferEvents from './tables/fundingTransferEvents.js'
@@ -50,6 +51,7 @@ export type Database = {
   funding_chain_tokens: FundingCatalog.ChainTokenTable
   funding_chains: FundingCatalog.ChainTable
   funding_deposit_addresses: FundingDepositAddresses.Table
+  funding_deposit_request_observations: FundingDepositRequestObservations.Table
   funding_deposits: FundingDeposits.Table
   funding_idempotency_requests: FundingIdempotency.Table
   funding_routes: FundingCatalog.RouteTable
@@ -1209,6 +1211,66 @@ export const migrations: readonly Migration[] = [
         $$`,
       ),
   },
+  {
+    name: '0108_funding_deposits_recipient_index',
+    // The expression indexes existing snapshots without a deployment-order-sensitive column backfill.
+    up: (db) =>
+      raw(
+        db,
+        sql`CREATE INDEX IF NOT EXISTS funding_deposits_recipient_idx ON funding_deposits (org_id, environment, lower(snapshot->>'recipient'), created_at, id)`,
+      ),
+  },
+  {
+    name: '0109_funding_deposits_detection_trigger',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE funding_deposits ADD COLUMN IF NOT EXISTS detection_trigger text CHECK (detection_trigger IN ('manual', 'poll', 'webhook'))`,
+      ),
+  },
+  {
+    name: '0110_funding_deposit_request_observations',
+    up: (db) =>
+      db.schema
+        .createTable('fundingDepositRequestObservations')
+        .ifNotExists()
+        .addColumn('depositAddressId', 'text', (c) =>
+          c.notNull().references('fundingDepositAddresses.id').onDelete('cascade'),
+        )
+        .addColumn('pollObservedAt', 'text')
+        .addColumn('providerRequestId', 'text', (c) => c.notNull())
+        .addColumn('webhookReceivedAt', 'text')
+        .addPrimaryKeyConstraint('funding_deposit_request_observations_pkey', [
+          'depositAddressId',
+          'providerRequestId',
+        ]),
+  },
+  {
+    name: '0111_funding_deposit_observation_timestamps',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE funding_deposits
+          ADD COLUMN IF NOT EXISTS poll_observed_at text,
+          ADD COLUMN IF NOT EXISTS webhook_received_at text`,
+      ),
+  },
+  {
+    name: '0112_funding_deposits_source_observation_index',
+    up: (db) =>
+      raw(
+        db,
+        sql`CREATE UNIQUE INDEX IF NOT EXISTS funding_deposits_source_observation_idx ON funding_deposits (deposit_address_id, source_transaction_hash, source_transfer_index)`,
+      ),
+  },
+  {
+    name: '0113_funding_deposits_chain_detection_trigger',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE funding_deposits DROP CONSTRAINT IF EXISTS funding_deposits_detection_trigger_check, ADD CONSTRAINT funding_deposits_detection_trigger_check CHECK (detection_trigger IN ('chain', 'manual', 'poll', 'webhook'))`,
+      ),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -517,6 +517,21 @@ export const FundingDepositAddress = z.object({
 /** Columns of the `funding_deposit_addresses` table. */
 export type FundingDepositAddress = z.output<typeof FundingDepositAddress>
 
+/** First Tempo observations of one provider request through polling and webhooks. */
+export const FundingDepositRequestObservation = z.object({
+  depositAddressId: z.string().check(z.describe('Funding deposit address id (`fda_…`).')),
+  pollObservedAt: z
+    .nullable(z.string())
+    .check(z.describe('When polling first observed the provider request, or null.')),
+  providerRequestId: z.string().check(z.describe('Provider request identifier.')),
+  webhookReceivedAt: z
+    .nullable(z.string())
+    .check(z.describe('When Tempo first received an authenticated webhook, or null.')),
+})
+
+/** Columns of the `funding_deposit_request_observations` table. */
+export type FundingDepositRequestObservation = z.output<typeof FundingDepositRequestObservation>
+
 /**
  * One provider-observed deposit. Public route and evidence live in `snapshot`;
  * reconciliation and settlement state is private.
@@ -524,11 +539,17 @@ export type FundingDepositAddress = z.output<typeof FundingDepositAddress>
 export const FundingDeposit = z.object({
   createdAt: z.string().check(z.describe('When the deposit was detected (ISO 8601).')),
   depositAddressId: z.string().check(z.describe('Funding deposit address id (`fda_…`).')),
+  detectionTrigger: z
+    .nullable(z.custom<funding_Deposit.DetectionTrigger>())
+    .check(z.describe('Mechanism that first detected the deposit, or null for legacy rows.')),
   environment: z
     .enum(['production', 'sandbox'])
     .check(z.describe('Key environment inherited from the deposit address.')),
   id: z.string().check(z.describe('Funding deposit id (`fdp_…`).')),
   orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  pollObservedAt: z
+    .nullable(z.string())
+    .check(z.describe('When polling first observed the provider request, or null.')),
   projectId: z.nullable(z.string()).check(z.describe('Attributed project id (`prj_…`), or null.')),
   providerOutputAmount: z
     .nullable(z.custom<z.output<typeof internal_Schema.TokenAmount>>())
@@ -580,6 +601,9 @@ export const FundingDeposit = z.object({
   tempoGasPaid: z.nullable(z.string()).check(z.describe('Tempo gas paid for settlement, or null.')),
   updatedAt: z.string().check(z.describe('When the deposit last materially changed (ISO 8601).')),
   version: z.number().check(z.int(), z.describe('Material version used to guard updates.')),
+  webhookReceivedAt: z
+    .nullable(z.string())
+    .check(z.describe('When Tempo first received an authenticated provider webhook, or null.')),
 })
 
 /** Columns of the `funding_deposits` table. */

package/src/db/tables/fundingDepositAddresses.ts

@@ -168,6 +168,34 @@ export function getMatching(db: Db.Db, match: Match): Promise<Record | undefined
   return query.executeTakeFirst()
 }
 
+/** Lists active provider addresses for one source-chain token. */
+export function listActiveSources(
+  db: Db.Db,
+  options: listActiveSources.Options,
+): Promise<readonly Record[]> {
+  return db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('providerId', '=', options.providerId)
+    .where('sourceChainId', '=', options.sourceChainId)
+    .where('sourceTokenKey', '=', options.sourceTokenKey)
+    .where('status', '=', 'active')
+    .orderBy('id', 'asc')
+    .execute()
+}
+
+export declare namespace listActiveSources {
+  /** Provider and source asset identifying one observer shard. */
+  type Options = {
+    /** Funding provider that owns the deposit addresses. */
+    providerId: string
+    /** Source chain CAIP-2 id. */
+    sourceChainId: string
+    /** Source token key. */
+    sourceTokenKey: string
+  }
+}
+
 /** Claims a bounded batch of active addresses due for provider reconciliation. */
 export function claimDue(db: Db.Db, options: claimDue.Options): Promise<readonly Record[]> {
   return db.transaction(async (tx) => {

package/src/db/tables/fundingDepositRequestObservations.test.ts

@@ -0,0 +1,106 @@
+import * as DepositAddress from '../../internal/funding/DepositAddress.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as FundingDepositRequestObservations from './fundingDepositRequestObservations.js'
+
+const db = TestApp.database()
+
+let addressCounter = 0
+function seedAddress() {
+  const index = addressCounter++
+  return DepositAddress.create(db, {
+    apiKeyId: 'key_request_observations',
+    deliveryStrategy: 'provider',
+    environment: 'production',
+    now: new Date(Date.UTC(2026, 0, 1, 0, 0, index)),
+    orgId: 'org_request_observations',
+    providerOutputToken: TestFunding.providerOutputToken(),
+    snapshot: TestFunding.depositAddressSnapshot({
+      provider: { id: `relay_observation_${index}`, name: 'Relay' },
+      recipient: `0x${index.toString(16).padStart(40, '0')}`,
+    }),
+  })
+}
+
+describe('get', () => {
+  test('returns no observation before a request is seen', async () => {
+    const address = await seedAddress()
+    expect(
+      await FundingDepositRequestObservations.get(db, {
+        depositAddressId: address.id,
+        providerRequestId: 'relay_unseen',
+      }),
+    ).toMatchInlineSnapshot(`undefined`)
+  })
+})
+
+describe('observePoll', () => {
+  test('retains the first poll timestamp for each request', async () => {
+    const address = await seedAddress()
+    await FundingDepositRequestObservations.observePoll(db, {
+      depositAddressId: address.id,
+      observedAt: '2026-01-01T00:00:10.000Z',
+      providerRequestIds: ['relay_poll', 'relay_poll'],
+    })
+    await FundingDepositRequestObservations.observePoll(db, {
+      depositAddressId: address.id,
+      observedAt: '2026-01-01T00:00:09.000Z',
+      providerRequestIds: ['relay_poll'],
+    })
+
+    expect(
+      await FundingDepositRequestObservations.get(db, {
+        depositAddressId: address.id,
+        providerRequestId: 'relay_poll',
+      }),
+    ).toMatchInlineSnapshot(
+      { depositAddressId: expect.any(String) },
+      `
+      {
+        "depositAddressId": Any<String>,
+        "pollObservedAt": "2026-01-01T00:00:09.000Z",
+        "providerRequestId": "relay_poll",
+        "webhookReceivedAt": null,
+      }
+    `,
+    )
+  })
+})
+
+describe('observeWebhook', () => {
+  test('retains both first-observation timestamps regardless of arrival order', async () => {
+    const address = await seedAddress()
+    await FundingDepositRequestObservations.observeWebhook(db, {
+      depositAddressId: address.id,
+      providerRequestId: 'relay_webhook',
+      receivedAt: '2026-01-01T00:00:08.000Z',
+    })
+    await FundingDepositRequestObservations.observePoll(db, {
+      depositAddressId: address.id,
+      observedAt: '2026-01-01T00:00:07.000Z',
+      providerRequestIds: ['relay_webhook'],
+    })
+    await FundingDepositRequestObservations.observeWebhook(db, {
+      depositAddressId: address.id,
+      providerRequestId: 'relay_webhook',
+      receivedAt: '2026-01-01T00:00:06.000Z',
+    })
+
+    expect(
+      await FundingDepositRequestObservations.get(db, {
+        depositAddressId: address.id,
+        providerRequestId: 'relay_webhook',
+      }),
+    ).toMatchInlineSnapshot(
+      { depositAddressId: expect.any(String) },
+      `
+      {
+        "depositAddressId": Any<String>,
+        "pollObservedAt": "2026-01-01T00:00:07.000Z",
+        "providerRequestId": "relay_webhook",
+        "webhookReceivedAt": "2026-01-01T00:00:06.000Z",
+      }
+    `,
+    )
+  })
+})

package/src/db/tables/fundingDepositRequestObservations.ts

@@ -0,0 +1,99 @@
+import { sql, type Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_deposit_request_observations` table. */
+export type Table = db_Schema.FundingDepositRequestObservation
+
+/** First Tempo observations of one provider request. */
+export type Record = Selectable<Table>
+
+/** Gets observation timestamps for one provider request. */
+export function get(db: Db.Db, options: get.Options): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_deposit_request_observations')
+    .selectAll()
+    .where('depositAddressId', '=', options.depositAddressId)
+    .where('providerRequestId', '=', options.providerRequestId)
+    .executeTakeFirst()
+}
+
+export declare namespace get {
+  /** Provider request identity scoped to one reusable address. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** Provider request identifier. */
+    providerRequestId: string
+  }
+}
+
+/** Records when polling first observed each provider request. */
+export async function observePoll(db: Db.Db, options: observePoll.Options): Promise<Record[]> {
+  const providerRequestIds = [...new Set(options.providerRequestIds)]
+  if (providerRequestIds.length === 0) return []
+  return db.kysely
+    .insertInto('funding_deposit_request_observations')
+    .values(
+      providerRequestIds.map((providerRequestId) => ({
+        depositAddressId: options.depositAddressId,
+        pollObservedAt: options.observedAt,
+        providerRequestId,
+        webhookReceivedAt: null,
+      })),
+    )
+    .onConflict((oc) =>
+      oc.columns(['depositAddressId', 'providerRequestId']).doUpdateSet({
+        pollObservedAt: sql<string>`LEAST(COALESCE(funding_deposit_request_observations.poll_observed_at, excluded.poll_observed_at), excluded.poll_observed_at)`,
+      }),
+    )
+    .returningAll()
+    .execute()
+}
+
+export declare namespace observePoll {
+  /** Provider requests observed in one successful poll response. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** When Tempo observed the provider requests. */
+    observedAt: string
+    /** Provider request identifiers returned by the poll. */
+    providerRequestIds: readonly string[]
+  }
+}
+
+/** Records when Tempo first received an authenticated webhook for a provider request. */
+export function observeWebhook(
+  db: Db.Db,
+  options: observeWebhook.Options,
+): Promise<Record | undefined> {
+  return db.kysely
+    .insertInto('funding_deposit_request_observations')
+    .values({
+      depositAddressId: options.depositAddressId,
+      pollObservedAt: null,
+      providerRequestId: options.providerRequestId,
+      webhookReceivedAt: options.receivedAt,
+    })
+    .onConflict((oc) =>
+      oc.columns(['depositAddressId', 'providerRequestId']).doUpdateSet({
+        webhookReceivedAt: sql<string>`LEAST(COALESCE(funding_deposit_request_observations.webhook_received_at, excluded.webhook_received_at), excluded.webhook_received_at)`,
+      }),
+    )
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace observeWebhook {
+  /** Authenticated webhook observation for one provider request. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** Provider request identifier. */
+    providerRequestId: string
+    /** When Tempo received the webhook. */
+    receivedAt: string
+  }
+}