tapimo 0.10.1 → 0.11.0

package/src/apps/data/routes/webhooks.ts

@@ -3,11 +3,10 @@ import { type AbiEvent, decodeEventLog, encodeEventTopics, parseAbiItem, type Rp
 import * as z from 'zod/mini'
 
 import type * as App from '../../../App.js'
+import * as Scope from '../../../Scope.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
-import * as Cursor from '../../../internal/Cursor.js'
 import * as Db from '../../../db/Db.js'
-import type * as MetricSink from '../../../internal/MetricSink.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
@@ -18,6 +17,7 @@ import type * as Viem from '../../../internal/Viem.js'
 import * as WebhookDestination from '../../../internal/WebhookDestination.js'
 import * as WebhookTransfer from '../../../internal/WebhookTransfer.js'
 import * as Webhooks from '../../../internal/Webhooks.js'
+import * as FundingDeposit from '../../../internal/funding/Deposit.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
 
@@ -41,6 +41,7 @@ const redactedSlackUrl = 'https://hooks.slack.com/…'
  */
 export const eventTypes = [
   'block:created',
+  'funding:deposit.updated',
   'log:emitted',
   'token:transfer',
   'transaction:included',
@@ -56,6 +57,11 @@ const eventTypeDescriptions = [
       'A new block was added to the chain. Filter by producer, gas usage, or block number, or omit filters for a per-block heartbeat.',
     type: 'block:created',
   },
+  {
+    description:
+      'A funding deposit materially changed after verified reconciliation, filterable by deposit address, recipient, or status.',
+    type: 'funding:deposit.updated',
+  },
   {
     description:
       'Any contract event log, filtered by emitting address, event signature/topics, or decoded arguments.',
@@ -447,6 +453,18 @@ export namespace schema {
       z.meta({ title: 'Block filters' }),
     )
 
+  /** `funding:deposit.updated` subscription filters. All are optional and AND-combined. */
+  export const FundingDepositFilters = z
+    .strictObject({
+      depositAddressId: z.optional(FundingDeposit.schema.Snapshot.shape.depositAddressId),
+      recipient: z.optional(Schema.Address),
+      status: z.optional(FundingDeposit.schema.Status),
+    })
+    .check(
+      z.describe('Filters that narrow which funding deposit changes trigger this webhook.'),
+      z.meta({ title: 'Funding deposit filters' }),
+    )
+
   /**
    * Optional human context describing what a subscription is for. Surfaced by
    * destinations (Slack header + description, Better Stack log fields) and echoed
@@ -506,6 +524,12 @@ export namespace schema {
           z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
         ),
       destination: PublicDestination,
+      environment: z
+        .optional(z.enum(['production', 'sandbox']))
+        .check(
+          z.describe('API-key environment for private resource events, when applicable.'),
+          z.meta({ examples: ['production'] }),
+        ),
       eventType: EventType.check(z.meta({ examples: ['token:transfer'] })),
       expiresAt: z
         .optional(z.iso.datetime())
@@ -683,7 +707,7 @@ export namespace schema {
           })
           .check(
             z.describe(
-              'Best-effort token metadata (symbol/decimals) resolved by the poller so `amount` can render as a human amount. Omitted when the lookup is unavailable.',
+              'Best-effort token metadata (symbol/decimals) resolved before delivery so `amount` can render as a human amount. Omitted when the lookup is unavailable.',
             ),
           ),
       ),
@@ -886,6 +910,9 @@ export namespace schema {
     })
     .check(z.describe('Payload for a `block:created` event (a new block header).'))
 
+  /** Public funding deposit after a committed material change. */
+  export const FundingDepositEvent = FundingDeposit.schema.FundingDeposit
+
   /** A `ping` (synthetic test-delivery) payload, sent by `POST /webhooks/:id/ping`. */
   export const PingEvent = z
     .object({
@@ -944,6 +971,13 @@ export namespace schema {
       z
         .object({ ...envelopeBase, data: BlockEvent, type: z.literal('block:created') })
         .check(z.meta({ title: 'Block event' })),
+      z
+        .object({
+          ...envelopeBase,
+          data: FundingDepositEvent,
+          type: z.literal('funding:deposit.updated'),
+        })
+        .check(z.meta({ title: 'Funding deposit updated event' })),
       z
         .object({ ...envelopeBase, data: PingEvent, type: z.literal('ping') })
         .check(z.meta({ title: 'Ping (test delivery)' })),
@@ -1037,6 +1071,20 @@ export namespace schema {
             filters: z.optional(BlockFilters),
           })
           .check(z.meta({ title: 'Block subscription' })),
+        z
+          .object({
+            chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+            context: z.optional(Context),
+            destination: Destination,
+            eventType: z
+              .literal('funding:deposit.updated')
+              .check(
+                z.describe('Event type for committed funding deposit changes.'),
+                z.meta({ examples: ['funding:deposit.updated'] }),
+              ),
+            filters: z.optional(FundingDepositFilters),
+          })
+          .check(z.meta({ title: 'Funding deposit subscription' })),
       ])
       .check(z.describe('Details for creating a webhook subscription.'))
 
@@ -1239,6 +1287,12 @@ export namespace schema {
  */
 export function webhooks(options: webhooks.Options = {}) {
   const hidden = !options.enabled
+  const availableEventTypes = eventTypeDescriptions.filter(
+    (eventType) =>
+      eventType.type !== 'funding:deposit.updated' ||
+      options.applicationEventTypes?.includes(eventType.type),
+  )
+  const availableEventTypeSet = new Set(availableEventTypes.map((eventType) => eventType.type))
   // Gate the whole resource on a configured state store. Without it the
   // outbound-HTTP surface is disabled (read-only deployment).
   const gate = async (c: Context<App.Environment>, next: () => Promise<void>) => {
@@ -1286,7 +1340,7 @@ export function webhooks(options: webhooks.Options = {}) {
           if (!c.get('webhook')) return notEnabled(c)
           return c.json(
             Response.validated(schema.getWebhookEventTypes.Response, {
-              data: eventTypeDescriptions.map((eventType) => ({ ...eventType })),
+              data: availableEventTypes.map((eventType) => ({ ...eventType })),
             }),
             200,
           )
@@ -1307,12 +1361,18 @@ export function webhooks(options: webhooks.Options = {}) {
           responses: OpenApi.responses({
             errors: {
               400: {
-                codes: ['body_invalid', 'chain_id_unsupported', 'filters_invalid', 'url_invalid'],
+                codes: [
+                  'body_invalid',
+                  'chain_id_unsupported',
+                  'event_type_unsupported',
+                  'filters_invalid',
+                  'url_invalid',
+                ],
                 description: 'The request, destination, filters, or chain are invalid.',
               },
               403: {
-                codes: ['limit_exceeded'],
-                description: 'You have reached the webhook subscription limit.',
+                codes: ['api_key_forbidden', 'limit_exceeded'],
+                description: 'The API key lacks access or the subscription limit was reached.',
               },
             },
             success: {
@@ -1335,10 +1395,30 @@ export function webhooks(options: webhooks.Options = {}) {
 
           const webhook = c.get('webhook')!
           const db = Db.get(c.get('db'))
+          const principal = Auth.getPrincipal(c)
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const body = c.req.valid('json')
+          if (!availableEventTypeSet.has(body.eventType))
+            return Response.error(c, {
+              code: 'event_type_unsupported',
+              message: 'Webhook event type is not available in this deployment',
+              status: 400,
+            })
+          if (body.eventType === 'funding:deposit.updated') {
+            if (principal?.type !== 'api_key') return unauthorized(c)
+            if (
+              !principal.apiKey.scopes.some(
+                (scope) => scope === Scope.wildcard || scope === 'funding:read',
+              )
+            )
+              return Response.error(c, {
+                code: 'api_key_forbidden',
+                message: 'API key missing required scope',
+                status: 403,
+              })
+          }
           const chainId = body.chainId ?? c.get('chainId')
           const supportedChainIds = new Set(webhook.supportedChainIds)
           if (!supportedChainIds.has(chainId))
@@ -1350,13 +1430,24 @@ export function webhooks(options: webhooks.Options = {}) {
             const maxPerOwner = webhook.maxPerOwner ?? defaultMaxPerOwner
             if ((await Webhooks.countSubscriptions(db, owner)) >= maxPerOwner)
               throw new Webhooks.LimitExceededError(maxPerOwner)
-            const startBlockNumber = await getRpcHead(c.get('getClient')(chainId))
+            const startBlockNumber =
+              body.eventType === 'funding:deposit.updated'
+                ? undefined
+                : await getRpcHead(c.get('getClient')(chainId))
             const subscription = await Webhooks.createSubscription(
               db,
               {
                 chainId,
                 ...(body.context === undefined ? {} : { context: body.context }),
                 destination: body.destination,
+                ...(principal?.type === 'api_key'
+                  ? {
+                      environment: principal.environment,
+                      ...(principal.projectId === undefined
+                        ? {}
+                        : { projectId: principal.projectId }),
+                    }
+                  : {}),
                 eventType: body.eventType,
                 filters: body.filters,
                 owner,
@@ -1364,7 +1455,7 @@ export function webhooks(options: webhooks.Options = {}) {
               },
               {
                 maxPerOwner,
-                startBlockNumber,
+                ...(startBlockNumber === undefined ? {} : { startBlockNumber }),
               },
             )
             return c.json(
@@ -1408,6 +1499,7 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
+          const access = accessFor(c)
 
           const { cursor, include, limit, page } = c.req.valid('query')
           try {
@@ -1415,12 +1507,13 @@ export function webhooks(options: webhooks.Options = {}) {
             // run it concurrently with the page list. Best-effort: a failure
             // omits `meta` rather than failing the page.
             const countPromise = include.includes('totalCount')
-              ? Webhooks.countSubscriptions(db, owner).catch(() => undefined)
+              ? Webhooks.countSubscriptions(db, owner, { access }).catch(() => undefined)
               : undefined
 
             // Fetch one extra to detect a further page without a second round-trip.
             // `page` translates to a positional slice of `(page - 1) * limit` rows.
             const rows = await Webhooks.listSubscriptions(db, owner, {
+              access,
               cursor,
               limit: limit + 1,
               offset: page !== undefined && page > 1 ? (page - 1) * limit : undefined,
@@ -1488,10 +1581,11 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
+          const access = accessFor(c)
 
           const { id } = c.req.valid('param')
           try {
-            const subscription = await Webhooks.getSubscription(db, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id, { access })
             if (!subscription) return notFound(c)
             return c.json(
               Response.validated(schema.getWebhook.Response, toPublic(subscription)),
@@ -1549,13 +1643,14 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
+          const access = accessFor(c)
 
           const { id } = c.req.valid('param')
           const { cursor, include, limit, page } = c.req.valid('query')
           try {
             // Owner-scope first: resolving the subscription under the caller's owner
             // key 404s ids they don't own (indistinguishable from "doesn't exist").
-            const subscription = await Webhooks.getSubscription(db, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id, { access })
             if (!subscription) return notFound(c)
 
             // `totalCount` is opt-in and exact (the delivery log is TTL-bounded);
@@ -1632,11 +1727,12 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
+          const access = accessFor(c)
 
           const { id } = c.req.valid('param')
           try {
             // Owner-scope first so unowned/unknown ids are indistinguishable (404).
-            const subscription = await Webhooks.getSubscription(db, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id, { access })
             if (!subscription) return notFound(c)
 
             // Inline delivery (not the queue) so the caller gets an immediate
@@ -1696,11 +1792,12 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
+          const access = accessFor(c)
 
           const { deliveryId, id } = c.req.valid('param')
           try {
             // Owner-scope the subscription first so unowned ids 404 like elsewhere.
-            const subscription = await Webhooks.getSubscription(db, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id, { access })
             if (!subscription) return notFound(c)
 
             const delivery = await Webhooks.getDelivery(db, id, deliveryId)
@@ -1786,6 +1883,7 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
+          const access = accessFor(c)
 
           const { id } = c.req.valid('param')
           const patch = c.req.valid('json')
@@ -1796,11 +1894,11 @@ export function webhooks(options: webhooks.Options = {}) {
             // persisting — otherwise a bad filter would silently widen the match
             // set at scan time.
             if (patch.filters !== undefined) {
-              const existing = await Webhooks.getSubscription(db, owner, id)
+              const existing = await Webhooks.getSubscription(db, owner, id, { access })
               if (!existing) return notFound(c)
               parseFilters(existing.eventType, patch.filters)
             }
-            const subscription = await Webhooks.updateSubscription(db, owner, id, patch)
+            const subscription = await Webhooks.updateSubscription(db, owner, id, patch, { access })
             if (!subscription) return notFound(c)
             return c.json(
               Response.validated(schema.updateWebhook.Response, toPublic(subscription)),
@@ -1849,10 +1947,11 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
+          const access = accessFor(c)
 
           const { id } = c.req.valid('param')
           try {
-            const deleted = await Webhooks.deleteSubscription(db, owner, id)
+            const deleted = await Webhooks.deleteSubscription(db, owner, id, { access })
             if (!deleted) return notFound(c)
             return c.json(Response.validated(schema.deleteWebhook.Response, { id }), 200)
           } catch (cause) {
@@ -1866,631 +1965,13 @@ export function webhooks(options: webhooks.Options = {}) {
 export declare namespace webhooks {
   /** Options for creating webhook routes. */
   type Options = {
+    /** Application events produced by this deployment outside the per-block chain scan. */
+    applicationEventTypes?: readonly Webhooks.EventType[] | undefined
     /** Whether webhook state is configured and routes should appear in OpenAPI. */
     enabled?: boolean | undefined
   }
 }
 
-/**
- * Largest representable in-block index, used as an end-of-block cursor sentinel
- * so a fully-scanned block advances the cursor strictly past it (no row index
- * can equal it).
- */
-const endOfBlockIndex = 2_147_483_647
-const scanPageSize = 100
-
-/** A scanned row paired with its `(block, index)` keyset position. */
-type ScanItem = { cursor: readonly [number, number]; data: unknown }
-
-/**
- * The result of scanning one subscription page. `scannedThrough` is the
- * highest block fully scanned. A batch-limited page omits it, so the poller
- * resumes after the last dispatched row instead of skipping later matches.
- */
-type ScanPage = {
-  hasMore?: boolean | undefined
-  items: readonly ScanItem[]
-  scannedThrough?: number | undefined
-}
-
-/** Per-subscription state retained between fair scan passes. */
-type PollState = {
-  cursor: string
-  filters: Record<string, unknown>
-  remaining: number
-  safeBlock: number
-  subscription: Webhooks.Subscription
-}
-
-/** Concurrent per-subscription scans and cursor writes per poll round; caps RPC and DB fan-out. */
-const pollConcurrency = 8
-
-/** Event types scanned together when their combined state fits one existing scan round. */
-const pollEventTypeConcurrency = 2
-
-/** Maximum subscription states retained by concurrent event-type scan batches. */
-const pollStateLimit = WebhookTransfer.scanCohortSize * pollConcurrency
-
-type Schedule = <value>(fn: () => Promise<value>) => Promise<value>
-
-/** Schedules asynchronous work through one shared concurrency bound. */
-function createLimiter(limit: number): Schedule {
-  let active = 0
-  const waiting: (() => void)[] = []
-  return async (fn) => {
-    if (active >= limit) await new Promise<void>((resolve) => waiting.push(resolve))
-    else active++
-    try {
-      return await fn()
-    } finally {
-      const next = waiting.shift()
-      if (next) next()
-      else active--
-    }
-  }
-}
-
-/** Runs `fn` over `items` with at most `limit` in flight, preserving order. */
-async function mapWithLimit<item, value>(
-  items: readonly item[],
-  limit: number,
-  fn: (item: item) => Promise<value>,
-): Promise<PromiseSettledResult<value>[]> {
-  const results: PromiseSettledResult<value>[] = []
-  let next = 0
-  await Promise.all(
-    Array.from({ length: Math.min(limit, items.length) }, async () => {
-      while (next < items.length) {
-        const index = next++
-        try {
-          results[index] = { status: 'fulfilled', value: await fn(items[index]!) }
-        } catch (reason) {
-          results[index] = { reason, status: 'rejected' }
-        }
-      }
-    }),
-  )
-  return results
-}
-
-/** Returns `candidate` only when it is lexicographically after `current`. */
-function laterCursor(current: string, candidate: string): string {
-  const before = Cursor.decode(current, ['int', 'int'])
-  const after = Cursor.decode(candidate, ['int', 'int'])
-  if (!after) return current
-  if (!before) return candidate
-  const [beforeBlock, beforeIndex] = before as [number, number]
-  const [afterBlock, afterIndex] = after as [number, number]
-  return afterBlock > beforeBlock || (afterBlock === beforeBlock && afterIndex > beforeIndex)
-    ? candidate
-    : current
-}
-
-/**
- * Polls the chain over RPC for new events and dispatches a signed envelope per
- * matching row, advancing each active subscription's `(block, index)` keyset
- * cursor.
- *
- * Every event type scans a **narrow confirmed window** `[cursor, head -
- * confirmations]` directly over JSON-RPC (`eth_getLogs`,
- * `eth_getBlockByNumber`) so webhook delivery does not wait for an indexer.
- *
- * The chain head is injectable (tests pin a fixed historical window); only
- * blocks at least `confirmations` behind head are emitted, giving at-least-once,
- * finalized-ish semantics (re-delivery overlap is harmless because the receiver
- * dedupes on the stable `event.id`).
- *
- * Cursor advances only past successfully dispatched rows, so a dispatch failure
- * pauses that subscription at the last good position and the next tick resumes.
- * Scan failures leave that subscription unchanged; the first error is rethrown
- * after the remaining subscriptions run.
- */
-export async function poll(options: poll.Options): Promise<poll.Result> {
-  const {
-    batchSize = 200,
-    cache: cache_metadata = Store.memory(),
-    chainId,
-    client,
-    confirmations = 1,
-    db,
-    eventTypes: eventTypes_input = [
-      'token:transfer',
-      'transaction:included',
-      'log:emitted',
-      'block:created',
-    ],
-    maxBlocks = 1_000,
-  } = options
-  const now = options.now ?? (() => new Date())
-  options.signal?.throwIfAborted()
-  // Default (self-host) transport: deliver inline and record the outcome so a
-  // sustained-failure subscription auto-disables. On Cloudflare, callers pass a
-  // Queue producer instead and the consumer runs `deliverAndRecord`.
-  const dispatch =
-    options.dispatch ??
-    (({ envelope, subscription }) => Webhooks.deliverAndRecord(db, subscription, envelope))
-  const dispatchBatch = options.dispatchBatch
-
-  // A pinned `headBlockNumber` lets a head subscription supply the exact live
-  // boundary and keeps historical tests deterministic.
-  const override = options.headBlockNumber
-  let rpcHead: number | undefined = override === undefined ? undefined : Number(override)
-  const resolveRpcHead = async () => (rpcHead ??= await getRpcHead(client))
-
-  const headStartedAt = Date.now()
-  const rpcSafeBlock = await (async () => {
-    try {
-      const safeBlock = Math.max(0, (await resolveRpcHead()) - confirmations)
-      options.onStage?.({
-        durationMs: Date.now() - headStartedAt,
-        outcome: 'ok',
-        stage: 'rpc_head',
-      })
-      return safeBlock
-    } catch (error) {
-      options.onStage?.({
-        durationMs: Date.now() - headStartedAt,
-        outcome: 'error',
-        stage: 'rpc_head',
-      })
-      throw error
-    }
-  })()
-  const result: poll.Result = {
-    chainId,
-    dispatched: 0,
-    failed: 0,
-    safeBlock: rpcSafeBlock,
-    scanned: 0,
-    subscriptions: 0,
-  }
-  let cursorLagBlocks = 0
-  const pollErrors: unknown[] = []
-
-  const eventTypes = [...new Set(eventTypes_input)]
-  const subscriptionsStartedAt = Date.now()
-  const pairs = await Webhooks.listActiveForChain(db, { chainId, eventTypes })
-  options.signal?.throwIfAborted()
-  options.onSubscriptions?.(pairs.length)
-  options.onStage?.({
-    durationMs: Date.now() - subscriptionsStartedAt,
-    outcome: 'ok',
-    stage: 'subscription_read',
-  })
-  const pairsByEventType = Map.groupBy(pairs, (pair) => pair.subscription.eventType)
-  const eventTypes_active = eventTypes.filter(
-    (eventType) => (pairsByEventType.get(eventType)?.length ?? 0) > 0,
-  )
-  const eventTypeConcurrency =
-    pairs.length <= pollStateLimit
-      ? Math.min(pollEventTypeConcurrency, eventTypes_active.length)
-      : Math.min(1, eventTypes_active.length)
-  const scanRoundSize = Math.floor(pollStateLimit / Math.max(1, eventTypeConcurrency))
-  const scheduleScan = createLimiter(pollConcurrency)
-
-  const eventTypeResults = await mapWithLimit(
-    eventTypes_active,
-    eventTypeConcurrency,
-    async (eventType) => {
-      options.signal?.throwIfAborted()
-      const safeBlock = rpcSafeBlock
-      const pairs = pairsByEventType.get(eventType) ?? []
-      const durations = {
-        cursor_write: 0,
-        enrich: 0,
-        scan: 0,
-      } satisfies Record<Exclude<MetricSink.PollStage, 'rpc_head' | 'subscription_read'>, number>
-      const observed = new Set<keyof typeof durations>()
-      let cursorWriteOutcome: 'error' | 'ok' = 'ok'
-      let scanOutcome: 'error' | 'ok' = 'ok'
-      const writeCursor = async (parameters: Webhooks.compareAndSetCursor.Options) => {
-        const startedAt = Date.now()
-        observed.add('cursor_write')
-        try {
-          return await Webhooks.compareAndSetCursor(db, parameters)
-        } catch (error) {
-          cursorWriteOutcome = 'error'
-          pollErrors.push(error)
-          return false
-        } finally {
-          durations.cursor_write += Date.now() - startedAt
-        }
-      }
-      let states: PollState[] = []
-      for (const pair of pairs) {
-        const { subscription } = pair
-        result.subscriptions++
-        let filters: Record<string, unknown>
-        try {
-          filters = parseFilters(subscription.eventType, subscription.filters)
-        } catch (error) {
-          if (!(error instanceof Webhooks.InvalidFilterError)) throw error
-          options.signal?.throwIfAborted()
-          // A breaking filter-schema removal must not poison every chain poll.
-          // Disable the legacy subscription without widening its match set.
-          await Webhooks.updateSubscription(db, subscription.owner, subscription.id, {
-            status: 'disabled',
-          })
-          continue
-        }
-        let cursor = pair.cursor
-        if (cursor === null) {
-          // Legacy subscriptions without a creation checkpoint anchor at the
-          // current confirmed head, avoiding a genesis backfill.
-          await writeCursor({
-            cursor: Cursor.encode([safeBlock, endOfBlockIndex]),
-            expectedCursor: null,
-            subscriptionId: subscription.id,
-          })
-          continue
-        }
-        const checkpoint = Cursor.decode(cursor, ['int'])
-        if (checkpoint) {
-          // Creation checkpoints record the live head without finalizing it. Rebase
-          // to this poller's confirmed boundary so replacement blocks stay eligible.
-          const confirmedCursor = Cursor.encode([
-            Math.max(0, (checkpoint[0] as number) - confirmations),
-            endOfBlockIndex,
-          ])
-          const committed = await writeCursor({
-            cursor: confirmedCursor,
-            expectedCursor: cursor,
-            subscriptionId: subscription.id,
-          })
-          if (!committed) continue
-          cursor = confirmedCursor
-        }
-        const position = Cursor.decode(cursor, ['int', 'int'])
-        if (position)
-          cursorLagBlocks = Math.max(cursorLagBlocks, safeBlock - (position[0] as number))
-        const window = scanWindow(cursor, safeBlock, maxBlocks)
-        if (window && window.to < safeBlock) result.hasMore = true
-        states.push({
-          cursor,
-          filters,
-          remaining: batchSize,
-          safeBlock: window?.to ?? safeBlock,
-          subscription,
-        })
-      }
-
-      // Every subscription gets one bounded page before any subscription gets a
-      // continuation page, preserving fairness while allowing catch-up.
-      while (states.length > 0) {
-        options.signal?.throwIfAborted()
-        const continuations: PollState[] = []
-        const round = states
-        for (let offset = 0; offset < round.length; offset += scanRoundSize) {
-          const batch = round.slice(offset, offset + scanRoundSize)
-          const windows = batch.flatMap((state) => {
-            const window = scanWindow(state.cursor, state.safeBlock, maxBlocks)
-            return window ? [window] : []
-          })
-          const maxWindowBlocks = Math.max(
-            0,
-            ...windows.map((window) => window.to - window.from + 1),
-          )
-          const totalWindowBlocks = windows.reduce(
-            (total, window) => total + window.to - window.from + 1,
-            0,
-          )
-          options.onScanCheckpoint?.({
-            concurrency: pollConcurrency,
-            eventType,
-            maxWindowBlocks,
-            phase: 'start',
-            rpcMethod: scanRpcMethod(eventType),
-            subscriptionLimit: scanRoundSize,
-            subscriptionCount: batch.length,
-            totalWindowBlocks,
-          })
-          const scanStartedAt = Date.now()
-          const pages = await scanSubscriptions({
-            client,
-            eventType,
-            maxBlocks,
-            schedule: scheduleScan,
-            states: batch,
-          })
-          options.onScanCheckpoint?.({
-            concurrency: pollConcurrency,
-            durationMs: Date.now() - scanStartedAt,
-            eventType,
-            failedSubscriptions: pages.filter((page) => page.status === 'rejected').length,
-            matchedItems: pages.reduce(
-              (total, page) => total + (page.status === 'fulfilled' ? page.value.items.length : 0),
-              0,
-            ),
-            maxWindowBlocks,
-            outcome: scanResultOutcome(pages),
-            phase: 'complete',
-            rpcMethod: scanRpcMethod(eventType),
-            subscriptionLimit: scanRoundSize,
-            subscriptionCount: batch.length,
-            totalWindowBlocks,
-          })
-          options.signal?.throwIfAborted()
-          durations.scan += Date.now() - scanStartedAt
-          observed.add('scan')
-          if (pages.some((page) => page.status === 'rejected')) scanOutcome = 'error'
-
-          type Scanned = { page: ScanPage; state: PollState }
-          const busy: Scanned[] = []
-          const idle: Scanned[] = []
-          for (let i = 0; i < batch.length; i++) {
-            const state = batch[i]!
-            const settled = pages[i]!
-            if (settled.status === 'rejected') {
-              pollErrors.push(settled.reason)
-              continue
-            }
-            result.scanned += settled.value.items.length
-            state.remaining -= settled.value.items.length
-            ;(settled.value.items.length > 0 ? busy : idle).push({ page: settled.value, state })
-          }
-
-          // Empty pages only advance their cursor: no dispatch order to preserve,
-          // so one statement commits the cohort while retaining per-row CAS semantics.
-          const cursorWritesStartedAt = Date.now()
-          const candidates = idle.flatMap(({ page, state }) => {
-            options.signal?.throwIfAborted()
-            const candidate =
-              page.scannedThrough !== undefined
-                ? Cursor.encode([page.scannedThrough, endOfBlockIndex])
-                : page.hasMore
-                  ? undefined
-                  : Cursor.encode([state.safeBlock, endOfBlockIndex])
-            const cursor = candidate ? laterCursor(state.cursor, candidate) : state.cursor
-            return cursor === state.cursor ? [] : [{ cursor, state }]
-          })
-          if (candidates.length > 0) {
-            const committed = await (async () => {
-              try {
-                return await Webhooks.compareAndSetCursors(db, {
-                  cursors: candidates.map(({ cursor, state }) => ({
-                    cursor,
-                    expectedCursor: state.cursor,
-                    subscriptionId: state.subscription.id,
-                  })),
-                })
-              } catch (error) {
-                cursorWriteOutcome = 'error'
-                pollErrors.push(error)
-                return new Set<string>()
-              }
-            })()
-            for (const { cursor, state } of candidates)
-              if (committed.has(state.subscription.id)) state.cursor = cursor
-            durations.cursor_write += Date.now() - cursorWritesStartedAt
-            observed.add('cursor_write')
-          }
-
-          for (const { page, state } of busy) {
-            options.signal?.throwIfAborted()
-            const { subscription } = state
-
-            let accepted: readonly [number, number] | undefined
-            let failed = false
-            const buildDispatchable = async (item: ScanItem): Promise<poll.Dispatchable> => {
-              options.signal?.throwIfAborted()
-              // Token metadata is best-effort for webhooks: transfers use it for display,
-              // while transactions expose fee-token references without blocking delivery.
-              const enrichStartedAt = Date.now()
-              const data =
-                eventType === 'token:transfer'
-                  ? await withTokenMetadata(item.data, { cache: cache_metadata, chainId, client })
-                  : eventType === 'transaction:included'
-                    ? await withFeeTokenMetadata(item.data, {
-                        cache: cache_metadata,
-                        chainId,
-                        client,
-                      })
-                    : item.data
-              durations.enrich += Date.now() - enrichStartedAt
-              observed.add('enrich')
-              options.signal?.throwIfAborted()
-              const envelope = Webhooks.buildEnvelope({
-                blockNumber: item.cursor[0],
-                createdAt: now(),
-                data,
-                logIndex: item.cursor[1],
-                subscription,
-              })
-              return { envelope, subscription }
-            }
-
-            if (dispatchBatch) {
-              const dispatchables: poll.Dispatchable[] = []
-              for (const item of page.items) dispatchables.push(await buildDispatchable(item))
-              options.signal?.throwIfAborted()
-              const delivered = await dispatchBatch(dispatchables, { db })
-              if (delivered.ok) {
-                accepted = page.items.at(-1)?.cursor
-                result.dispatched += dispatchables.length
-              } else {
-                result.failed += dispatchables.length
-                failed = true
-              }
-            } else {
-              for (const item of page.items) {
-                const dispatchable = await buildDispatchable(item)
-                const delivered = await dispatch(dispatchable)
-                if (!delivered.ok) {
-                  result.failed++
-                  failed = true
-                  break
-                }
-                accepted = item.cursor
-                result.dispatched++
-              }
-            }
-
-            // Persist every accepted page before another subscription begins its
-            // continuation, so a later scan failure retains completed work.
-            const candidate = (() => {
-              if (failed) return accepted ? Cursor.encode([...accepted]) : undefined
-              if (page.scannedThrough !== undefined)
-                return Cursor.encode([page.scannedThrough, endOfBlockIndex])
-              if (accepted) return Cursor.encode([...accepted])
-              if (!page.hasMore) return Cursor.encode([state.safeBlock, endOfBlockIndex])
-              return undefined
-            })()
-            const cursor = candidate ? laterCursor(state.cursor, candidate) : state.cursor
-            const progressed = cursor !== state.cursor
-            let committed = false
-            if (progressed) {
-              committed = await writeCursor({
-                cursor,
-                expectedCursor: state.cursor,
-                subscriptionId: subscription.id,
-              })
-              if (committed) state.cursor = cursor
-            }
-
-            if (!failed && page.hasMore === true) {
-              if (committed && state.remaining > 0) continuations.push(state)
-              else result.hasMore = true
-            }
-          }
-        }
-        states = continuations
-      }
-      for (const stage of observed) {
-        const outcome = (() => {
-          if (stage === 'cursor_write') return cursorWriteOutcome
-          if (stage === 'scan') return scanOutcome
-          return 'ok'
-        })()
-        options.onStage?.({
-          durationMs: durations[stage],
-          eventType,
-          outcome,
-          stage,
-        })
-      }
-    },
-  )
-  for (const result of eventTypeResults)
-    if (result.status === 'rejected') pollErrors.push(result.reason)
-
-  options.onCursorLag?.(cursorLagBlocks)
-  if (pollErrors.length > 0) throw pollErrors[0]
-  return result
-}
-
-export declare namespace poll {
-  /** A row to dispatch, paired with its owning subscription. */
-  type Dispatchable = {
-    /** The signed-on-dispatch delivery envelope. */
-    envelope: Webhooks.Envelope
-    /** The subscription the event matched. */
-    subscription: Webhooks.Subscription
-  }
-  /** Options for {@link poll}. */
-  type Options = {
-    /** Max matching rows scanned per subscription per tick (default 200). */
-    batchSize?: number | undefined
-    /** Cache store for the token-metadata memoize (defaults to a fresh in-memory store; pass a persistent one to share lookups across ticks). */
-    cache?: Store.Store | undefined
-    /** Chain to poll. Callers loop over chains. */
-    chainId: number
-    /** viem RPC client for the chain. */
-    client: Viem.getClient.ReturnType
-    /** Reorg-safety window: only emit blocks this far behind head (default 1). */
-    confirmations?: number | undefined
-    /** Database holding subscriptions + cursors. */
-    db: Db.Db
-    /**
-     * Delivery transport. Defaults to inline {@link Webhooks.deliverAndRecord} (self-host);
-     * on Cloudflare pass a Queue producer so retry/backoff/DLQ are native.
-     */
-    dispatch?: ((input: Dispatchable) => Promise<Webhooks.Result>) | undefined
-    /** Batch delivery transport. A successful result confirms every row in the input. */
-    dispatchBatch?:
-      | ((input: readonly Dispatchable[], context: DispatchContext) => Promise<Webhooks.Result>)
-      | undefined
-    /** Event types to poll (default all). */
-    eventTypes?: readonly EventType[] | undefined
-    /** Current chain head; the poller emits up to `head - confirmations`. */
-    headBlockNumber?: bigint | number | undefined
-    /** Backfill cap: most blocks an RPC scanner inspects per tick (default 1000). */
-    maxBlocks?: number | undefined
-    /** Records the worst confirmed-head distance without changing the poll result. */
-    onCursorLag?: ((blocks: number) => void) | undefined
-    /** Records bounded scan inputs before allocation and outcomes after completion. */
-    onScanCheckpoint?: ((checkpoint: ScanCheckpoint) => void) | undefined
-    /** Records bounded, per-tick poll-stage timings without subscription identities. */
-    onStage?: ((stage: Stage) => void) | undefined
-    /** Records subscriptions eligible for this poll before any scan runs. */
-    onSubscriptions?: ((count: number) => void) | undefined
-    /** Clock for envelope timestamps; injectable for tests. */
-    now?: (() => Date) | undefined
-    /** Stops scanning and dispatch when the caller loses its execution lease. */
-    signal?: AbortSignal | undefined
-  }
-
-  /** Runtime context shared with a batch delivery transport. */
-  type DispatchContext = {
-    /** Database instance already resolved for this poll. */
-    db: Db.Db
-  }
-  /** Summary counters for one poll tick. */
-  type Result = {
-    /** Chain that was polled. */
-    chainId: number
-    /** Rows successfully dispatched. */
-    dispatched: number
-    /** Rows whose dispatch failed (pausing that subscription). */
-    failed: number
-    /** True when a bounded scan left committed work behind the same head. */
-    hasMore?: boolean | undefined
-    /** Highest confirmed block emitted this tick (`head - confirmations`). */
-    safeBlock: number
-    /** Total rows scanned across all subscriptions. */
-    scanned: number
-    /** Active subscriptions visited. */
-    subscriptions: number
-  }
-  /** One scan boundary used to correlate production memory failures with workload shape. */
-  type ScanCheckpoint = {
-    /** Shared upper bound for concurrent upstream scans across event types. */
-    concurrency: number
-    /** Scan duration, present only after completion. */
-    durationMs?: number | undefined
-    /** Subscription event type scanned by this batch. */
-    eventType: EventType
-    /** Subscriptions whose scan rejected, present only after completion. */
-    failedSubscriptions?: number | undefined
-    /** Matching rows retained by completed pages, present only after completion. */
-    matchedItems?: number | undefined
-    /** Largest block window requested by one subscription. */
-    maxWindowBlocks: number
-    /** Whether the checkpoint precedes allocation or follows scan completion. */
-    phase: 'complete' | 'start'
-    /** Outcome of the completed RPC-backed scan. */
-    outcome?: 'empty' | 'error' | 'missing' | 'ok' | undefined
-    /** JSON-RPC method used by this event type's scanner. */
-    rpcMethod: 'eth_getBlockByNumber' | 'eth_getLogs'
-    /** Subscriptions retained in this scan batch. */
-    subscriptionCount: number
-    /** Maximum subscriptions retained by this event-type batch. */
-    subscriptionLimit: number
-    /** Sum of subscription block windows in this scan batch. */
-    totalWindowBlocks: number
-  }
-  /** One bounded poll-stage timing observation. */
-  type Stage = {
-    /** Stage duration in milliseconds. */
-    durationMs: number
-    /** Event type being processed, omitted for the shared RPC-head stage. */
-    eventType?: EventType | undefined
-    /** Whether the stage completed. */
-    outcome: 'error' | 'ok'
-    /** Bounded stage name. */
-    stage: MetricSink.PollStage
-  }
-}
-
 /**
  * Attaches best-effort `{ symbol, decimals }` token metadata to a
  * `token:transfer` row so destinations can render human amounts. Reads the row's
@@ -2601,78 +2082,9 @@ export async function getRpcHead(client: Viem.getClient.ReturnType): Promise<num
   return Number(await client.getBlockNumber())
 }
 
-/** Groups aligned cursors only when their bounded upstream scans are equivalent. */
-async function scanSubscriptions(options: {
-  client: Viem.getClient.ReturnType
-  eventType: EventType
-  maxBlocks: number
-  schedule: Schedule
-  states: readonly PollState[]
-}): Promise<PromiseSettledResult<ScanPage>[]> {
-  const { client, eventType, maxBlocks, schedule, states } = options
-  if (eventType !== 'token:transfer')
-    return scanIndependent({ client, eventType, maxBlocks, schedule, states })
-  return WebhookTransfer.scan({
-    client,
-    concurrency: pollConcurrency,
-    maxBlocks,
-    schedule,
-    states: states.map((state) => ({
-      filters: state.filters,
-      limit: Math.min(scanPageSize, state.remaining),
-      window: scanWindow(state.cursor, state.safeBlock, maxBlocks),
-    })),
-  })
-}
-
-/** Returns the bounded JSON-RPC method used by an event scanner. */
-function scanRpcMethod(eventType: EventType): poll.ScanCheckpoint['rpcMethod'] {
-  return eventType === 'block:created' || eventType === 'transaction:included'
-    ? 'eth_getBlockByNumber'
-    : 'eth_getLogs'
-}
-
-/** Classifies a completed batch without exposing an unbounded upstream error. */
-function scanResultOutcome(
-  pages: readonly PromiseSettledResult<ScanPage>[],
-): NonNullable<poll.ScanCheckpoint['outcome']> {
-  const rejected = pages.filter((page) => page.status === 'rejected')
-  if (rejected.some((page) => page.reason instanceof BlockUnavailableError)) return 'missing'
-  if (rejected.length > 0) return 'error'
-  return pages.every((page) => page.status === 'fulfilled' && page.value.items.length === 0)
-    ? 'empty'
-    : 'ok'
-}
-
-/** Scans CPU-matched streams per subscription while sharing concurrent block reads. */
-function scanIndependent(options: {
-  client: Viem.getClient.ReturnType
-  eventType: Exclude<EventType, 'token:transfer'>
-  maxBlocks: number
-  schedule: Schedule
-  states: readonly PollState[]
-}): Promise<PromiseSettledResult<ScanPage>[]> {
-  const { client, eventType, maxBlocks, schedule, states } = options
-  const cache = createChainCache(client)
-  return mapWithLimit(states, pollConcurrency, (state) =>
-    schedule(() => {
-      const shared = {
-        batchSize: Math.min(scanPageSize, state.remaining),
-        cache,
-        cursor: state.cursor,
-        filters: state.filters,
-        maxBlocks,
-        safeBlock: state.safeBlock,
-      }
-      if (eventType === 'block:created') return scanBlocks(shared)
-      if (eventType === 'log:emitted') return scanLogs({ ...shared, client })
-      return scanTxs(shared)
-    }),
-  )
-}
-
 const filterSchemas = {
   'block:created': schema.BlockFilters,
+  'funding:deposit.updated': schema.FundingDepositFilters,
   'log:emitted': schema.LogFilters,
   'token:transfer': schema.TransferFilters,
   'transaction:included': schema.TxFilters,
@@ -2681,7 +2093,7 @@ const filterSchemas = {
 /**
  * Validates `filters` against the schema for `eventType`, **failing closed**: an
  * invalid filter throws {@link Webhooks.InvalidFilterError} instead of degrading
- * to `{}` (a firehose). Used at create/patch time and by the scanners so a stored
+ * to `{}` (a firehose). Used at create/patch time and by {@link scanBlock} so a stored
  * bad filter can never silently widen the match set.
  */
 export function parseFilters(
@@ -2737,7 +2149,7 @@ function operandEquals(value: string, target: unknown, kind: 'number' | 'string'
  * The JS counterpart of the old SQL `applyOperator`: evaluates one parsed filter
  * operator (from {@link schema.eq}/{@link schema.compare}/{@link schema.bytes})
  * against a single `0x`-hex field value pulled from an RPC object. The one place
- * operator semantics live, shared by every RPC scanner. Returns `false` for a
+ * operator semantics live, shared by every event matcher. Returns `false` for a
  * missing field so an absent value never matches (fail-closed).
  *
  * - bare value / `{ eq }` → equality
@@ -2789,107 +2201,15 @@ function matchesCalls(calls: unknown, op: unknown): boolean {
   return has(op)
 }
 
-// RPC window helpers + per-tick lazy cache.
-
-/** Renders a block number as a `0x`-hex tag for JSON-RPC params. */
-const blockTag = (n: number) => `0x${n.toString(16)}` as const
-
-/** Issues a JSON-RPC request through the viem client for a method viem can't type. */
-function rpc<result>(
-  client: Viem.getClient.ReturnType,
-  method: string,
-  params: readonly unknown[],
-): Promise<result> {
-  return (client.request as (args: { method: string; params: unknown[] }) => Promise<result>)({
-    method,
-    params: [...params],
-  })
-}
-
-/**
- * The confirmed scan window for a cursor. A cursor `(cb, ci)` means rows through
- * `(cb, ci)` were dispatched: when `ci` is the end-of-block sentinel the whole
- * block `cb` is done and scanning resumes at `cb + 1`; otherwise block `cb` is
- * re-scanned (skipping indices `<= ci`). `to` is capped by both `safeBlock` and
- * the per-tick backfill cap. Returns `undefined` when the subscription is
- * already caught up (nothing to scan, cursor unchanged).
- */
-function scanWindow(
-  cursor: string | undefined,
-  safeBlock: number,
-  maxBlocks: number,
-): { from: number; skip: readonly [number, number]; to: number } | undefined {
-  const decoded = cursor ? Cursor.decode(cursor, ['int', 'int']) : undefined
-  const cb = decoded ? (decoded[0] as number) : 0
-  const ci = decoded ? (decoded[1] as number) : endOfBlockIndex
-  const from = ci >= endOfBlockIndex ? cb + 1 : cb
-  if (from > safeBlock) return undefined
-  const to = Math.min(safeBlock, from + maxBlocks - 1)
-  return { from, skip: [cb, ci], to }
-}
-
-/** True when `(block, index)` is at or before the already-dispatched cursor. */
-function atOrBefore(block: number, index: number, skip: readonly [number, number]): boolean {
-  return block < skip[0] || (block === skip[0] && index <= skip[1])
-}
-
 /** A viem-formatted block header (no transactions), as returned by `getBlock`. */
 type RpcBlock = Awaited<ReturnType<Viem.getClient.ReturnType['getBlock']>>
 
-/** Per-batch single-flight cache for chain RPC reads. */
-type ChainCache = {
-  /** Full raw block (with transactions) via `eth_getBlockByNumber(n, true)`. */
-  block(n: number): Promise<Record<string, unknown>>
-  /** Viem-formatted block header (transaction hashes only) via `getBlock`. */
-  header(n: number): Promise<RpcBlock | undefined>
-}
-
-/** Builds a per-batch {@link ChainCache} bound to a viem client. */
-function createChainCache(client: Viem.getClient.ReturnType): ChainCache {
-  const headers = new Map<number, Promise<RpcBlock | undefined>>()
-  const blocks = new Map<number, Promise<Record<string, unknown>>>()
-
-  const singleFlight = <key, value>(
-    pending: Map<key, Promise<value>>,
-    key: key,
-    load: () => Promise<value>,
-  ) => {
-    const existing = pending.get(key)
-    if (existing) return existing
-    const promise = load().finally(() => pending.delete(key))
-    pending.set(key, promise)
-    return promise
-  }
-
-  return {
-    block(n) {
-      return singleFlight(blocks, n, () =>
-        // The transaction payload reuses `humanizeTransaction`, which consumes
-        // the raw RPC tx shape, so the full block stays on the untyped path.
-        rpc<Record<string, unknown> | null>(client, 'eth_getBlockByNumber', [
-          blockTag(n),
-          true,
-        ]).then((block) => {
-          if (!block) throw new BlockUnavailableError(n)
-          return block
-        }),
-      )
-    },
-    header(n) {
-      return singleFlight(headers, n, () =>
-        client.getBlock({ blockNumber: BigInt(n), includeTransactions: false }),
-      )
-    },
-  }
-}
-
-// log:emitted (eth_getLogs)
+// log:emitted
 
 /**
- * A viem-formatted log, as returned by `getLogs`. When a `signature`/`event` is
- * supplied to `getLogs`, viem additionally best-effort decodes `args`/`eventName`
- * (and filters to logs matching the event selector), so the manual
- * `decodeEventLog`/selector-anchoring the scanner used to do is no longer needed.
+ * A viem-shaped log consumed by the log matchers. `args`/`eventName` are present
+ * once {@link decodeScanLog} best-effort decodes the log against a subscription
+ * event signature.
  */
 type ScanLog = {
   address: string
@@ -2918,10 +2238,9 @@ type LogEventData = {
 }
 
 /**
- * Builds the delivered `log:emitted` payload from a viem-formatted log plus the
+ * Builds the delivered `log:emitted` payload from a viem-shaped log plus the
  * block timestamp. Returns `undefined` when a required field is missing/invalid
- * (the row is skipped). When a `signature`/`event` is supplied, `getLogs` has
- * already decoded `args`/`eventName`, so this just serializes them.
+ * (the row is skipped). Decoded `args`/`eventName` are serialized when present.
  */
 function toLogEvent(
   log: ScanLog,
@@ -2990,7 +2309,7 @@ function pushHex(op: unknown): `0x${string}` | `0x${string}`[] | undefined {
   return undefined
 }
 
-/** Narrows an `eq`/`in` address operator into the `getLogs` address pushdown. */
+/** Narrows an `eq`/`in` address operator into a pushdown-capable address value. */
 function pushAddress(op: unknown) {
   return pushHex(op)
 }
@@ -3006,7 +2325,7 @@ function parseEvent(signature: string | undefined): AbiEvent | undefined {
   }
 }
 
-/** Returns exact indexed arguments that viem can push into `eth_getLogs`. */
+/** Returns exact indexed arguments usable as a selective log anchor. */
 function pushEventArgs(args: Record<string, unknown> | undefined, event: AbiEvent) {
   const pushed: Record<string, unknown> = {}
   for (const [name, op] of Object.entries(args ?? {})) {
@@ -3017,7 +2336,7 @@ function pushEventArgs(args: Record<string, unknown> | undefined, event: AbiEven
   return pushed
 }
 
-/** Checks that the accepted filter has a selective `eth_getLogs` representation. */
+/** Checks that the accepted filter carries a selective anchor rather than matching every log. */
 function hasLogPushdown(f: z.output<typeof schema.LogFilters>): boolean {
   if (pushAddress(f.address) !== undefined) return true
 
@@ -3030,19 +2349,7 @@ function hasLogPushdown(f: z.output<typeof schema.LogFilters>): boolean {
   return pushHex(f.topic0) !== undefined && secondaryTopic
 }
 
-/** Builds raw topic filters, preserving null wildcards between constrained positions. */
-function pushTopics(f: z.output<typeof schema.LogFilters>, event: AbiEvent | undefined) {
-  const topics: (`0x${string}` | `0x${string}`[] | null | undefined)[] = [
-    event ? encodeEventTopics({ abi: [event] })[0] : pushHex(f.topic0),
-    pushHex(f.topic1),
-    pushHex(f.topic2),
-    pushHex(f.topic3),
-  ]
-  while (topics.length > 0 && topics.at(-1) === undefined) topics.pop()
-  return topics.map((topic) => topic ?? null)
-}
-
-/** Converts one raw JSON-RPC log into the viem-shaped scanner input. */
+/** Converts one raw JSON-RPC log into the viem-shaped matcher input. */
 function fromRpcLog(log: RpcLog): ScanLog {
   return {
     address: log.address,
@@ -3074,76 +2381,30 @@ function decodeScanLog(log: ScanLog, event: AbiEvent): ScanLog {
   }
 }
 
-/** Scans contract logs for one subscription, then re-checks every filter in memory. */
-async function scanLogs(options: {
-  batchSize: number
-  cache: ChainCache
-  client: Viem.getClient.ReturnType
-  cursor: string | undefined
-  filters: Record<string, unknown>
-  maxBlocks: number
-  safeBlock: number
-}): Promise<ScanPage> {
-  const { batchSize, cache, client, cursor, filters, maxBlocks, safeBlock } = options
-  const f = filters as z.output<typeof schema.LogFilters>
-  const window = scanWindow(cursor, safeBlock, maxBlocks)
-  if (!window) return { items: [], scannedThrough: undefined }
-
-  const event = parseEvent(f.signature)
-  if (f.signature && (!event || !/^[A-Za-z_]\w*$/.test(event.name)))
-    throw new Webhooks.InvalidFilterError('log:emitted', [
-      { message: 'Unsupported event signature.', path: ['signature'] },
-    ])
-
-  const address = pushAddress(f.address)
-  const topics = pushTopics(f, event)
-  const hasRawTopics = topics.slice(1).some((topic) => topic !== null)
-  const args = event ? pushEventArgs(f.args, event) : {}
-  const logs = (!event || hasRawTopics
-    ? (
-        await rpc<RpcLog[]>(client, 'eth_getLogs', [
-          {
-            ...(address ? { address } : {}),
-            fromBlock: blockTag(window.from),
-            ...(topics.length > 0 ? { topics } : {}),
-            toBlock: blockTag(window.to),
-          },
-        ])
-      )
-        .map(fromRpcLog)
-        .map((log) => (event ? decodeScanLog(log, event) : log))
-    : await client.getLogs({
-        ...(address ? { address } : {}),
-        ...(Object.keys(args).length > 0 ? { args: args as never } : {}),
-        event,
-        fromBlock: BigInt(window.from),
-        strict: false,
-        toBlock: BigInt(window.to),
-      })) as unknown as ScanLog[]
-  logs.sort((a, b) => {
-    const block = Number(a.blockNumber ?? 0n) - Number(b.blockNumber ?? 0n)
-    return block || (a.logIndex ?? 0) - (b.logIndex ?? 0)
-  })
+/**
+ * Attaches best-effort token metadata to one matched row before delivery.
+ * Transfers gain display metadata; transactions resolve their fee token.
+ */
+export async function enrichEventData(
+  eventType: EventType,
+  data: unknown,
+  options: enrichEventData.Options,
+): Promise<unknown> {
+  if (eventType === 'token:transfer') return withTokenMetadata(data, options)
+  if (eventType === 'transaction:included') return withFeeTokenMetadata(data, options)
+  return data
+}
 
-  const items: ScanItem[] = []
-  for (const log of logs) {
-    const blockNumber = log.blockNumber === null ? undefined : Number(log.blockNumber)
-    const logIndex = log.logIndex ?? undefined
-    if (blockNumber === undefined || logIndex === undefined) continue
-    if (atOrBefore(blockNumber, logIndex, window.skip)) continue
-    if (!matchesLog(log, f, event)) continue
-    const data = toLogEvent(
-      log,
-      Value.blockToIso(await cache.header(blockNumber)),
-      f.signature,
-      event,
-    )
-    if (data) {
-      items.push({ cursor: [data.blockNumber, data.logIndex], data })
-      if (items.length >= batchSize) return { hasMore: true, items }
-    }
+export declare namespace enrichEventData {
+  /** Metadata lookup dependencies. */
+  type Options = {
+    /** Memoization store for token metadata (5 minute TTL). */
+    cache: Store.Store
+    /** Chain the row was produced on. */
+    chainId: number
+    /** Client for `token.getMetadata` reads. */
+    client: Viem.getClient.ReturnType
   }
-  return { items, scannedThrough: window.to }
 }
 
 /** Re-checks all log filters (including non-pushable operators) in JS. */
@@ -3163,15 +2424,15 @@ function matchesLog(
     !matchesOperator(log.blockNumber?.toString(), f.blockNumber, 'number')
   )
     return false
-  // `getLogs(event)` already anchors topic0 on the event selector, so the raw
-  // `topic0` operator only applies in raw (no-signature) mode.
+  // With a signature, topic0 is anchored on the event selector above, so the
+  // raw `topic0` operator only applies in raw (no-signature) mode.
   if (!event && f.topic0 !== undefined && !matchesOperator(topics[0], f.topic0)) return false
   if (f.topic1 !== undefined && !matchesOperator(topics[1], f.topic1)) return false
   if (f.topic2 !== undefined && !matchesOperator(topics[2], f.topic2)) return false
   if (f.topic3 !== undefined && !matchesOperator(topics[3], f.topic3)) return false
 
   if (event && f.args && Object.keys(f.args).length > 0) {
-    // `getLogs(event, strict:false)` keeps non-decodable matches with no `args`.
+    // Best-effort decoding leaves a non-decodable log without `args`.
     if (log.args === undefined || Array.isArray(log.args)) return false
     const args = log.args as Record<string, unknown>
     for (const [name, op] of Object.entries(f.args)) {
@@ -3189,7 +2450,7 @@ function matchesLog(
   return true
 }
 
-// block:created (getBlock)
+// block:created
 
 type BlockEventData = {
   number: number
@@ -3234,35 +2495,6 @@ function toBlockEvent(block: RpcBlock): BlockEventData | undefined {
   }
 }
 
-/** Scans new blocks over one subscription's confirmed window. */
-async function scanBlocks(options: {
-  batchSize: number
-  cache: ChainCache
-  cursor: string | undefined
-  filters: Record<string, unknown>
-  maxBlocks: number
-  safeBlock: number
-}): Promise<ScanPage> {
-  const { batchSize, cache, cursor, filters, maxBlocks, safeBlock } = options
-  const f = filters as z.output<typeof schema.BlockFilters>
-  const window = scanWindow(cursor, safeBlock, maxBlocks)
-  if (!window) return { items: [], scannedThrough: undefined }
-
-  const items: ScanItem[] = []
-  for (let blockNumber = window.from; blockNumber <= window.to; blockNumber++) {
-    if (atOrBefore(blockNumber, 0, window.skip)) continue
-    const block = await cache.header(blockNumber)
-    if (!block) continue
-    if (!matchesBlock(block, f)) continue
-    const data = toBlockEvent(block)
-    if (data) {
-      items.push({ cursor: [data.number, 0], data })
-      if (items.length >= batchSize) return { hasMore: true, items }
-    }
-  }
-  return { items, scannedThrough: window.to }
-}
-
 /** Re-checks all block filters in JS. The RPC has no consensus `proposer`. */
 function matchesBlock(block: RpcBlock, f: z.output<typeof schema.BlockFilters>): boolean {
   if (f.number !== undefined && !matchesOperator(block.number?.toString(), f.number, 'number'))
@@ -3285,7 +2517,7 @@ function matchesBlock(block: RpcBlock, f: z.output<typeof schema.BlockFilters>):
   return true
 }
 
-// transaction:included (eth_getBlockByNumber)
+// transaction:included
 
 /** Maps a `transaction:included` scalar filter field to its raw-tx field + kind. */
 const txFields = {
@@ -3303,47 +2535,6 @@ const txFields = {
   value: { field: 'value', kind: 'number' },
 } as const satisfies Record<string, { field: string; kind: 'number' | 'string' }>
 
-/** Scans included transactions over one subscription's confirmed window. */
-async function scanTxs(options: {
-  batchSize: number
-  cache: ChainCache
-  cursor: string | undefined
-  filters: Record<string, unknown>
-  maxBlocks: number
-  safeBlock: number
-}): Promise<ScanPage> {
-  const { batchSize, cache, cursor, filters, maxBlocks, safeBlock } = options
-  const f = filters as z.output<typeof schema.TxFilters>
-  const window = scanWindow(cursor, safeBlock, maxBlocks)
-  if (!window) return { items: [], scannedThrough: undefined }
-
-  const includeCalls = f.includeCalls ?? true
-  const items: ScanItem[] = []
-  for (let blockNumber = window.from; blockNumber <= window.to; blockNumber++) {
-    const block = await cache.block(blockNumber)
-    const transactions = Array.isArray(block['transactions'])
-      ? (block['transactions'] as unknown[])
-      : []
-    const timestamp = asString(block['timestamp'])
-    // A transaction's own `blockTimestamp` is seconds-only, so the delivered
-    // timestamp comes from the enclosing block, which carries milliseconds.
-    const blockTime = Value.blockToIso(block)
-    for (let offset = 0; offset < transactions.length; offset++) {
-      const transaction = transactions[offset] as Record<string, unknown>
-      const transactionIndex = Value.hexToNumber(transaction['transactionIndex']) ?? offset
-      if (atOrBefore(blockNumber, transactionIndex, window.skip)) continue
-      if (!matchesTx(transaction, f, includeCalls, timestamp, blockNumber)) continue
-      const parsed = Transactions.schema.Rpc.Transaction.safeParse(transaction)
-      if (!parsed.success) continue
-      const humanized = Transactions.humanizeTransaction(parsed.data)
-      const data = blockTime === undefined ? humanized : { ...humanized, timestamp: blockTime }
-      items.push({ cursor: [blockNumber, transactionIndex], data })
-      if (items.length >= batchSize) return { hasMore: true, items }
-    }
-  }
-  return { items, scannedThrough: window.to }
-}
-
 /** Re-checks transaction filters against the raw RPC transaction. */
 function matchesTx(
   tx: Record<string, unknown>,
@@ -3399,6 +2590,16 @@ function ownerFor(c: Context<App.Environment>): Webhooks.Owner | null {
   return payer ? { payer, type: 'mpp' } : null
 }
 
+function accessFor(c: Context<App.Environment>): Webhooks.Access {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type !== 'api_key') throw new Error('Webhook routes require an API key.')
+  return {
+    environment: principal.environment,
+    ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
+    scopes: principal.apiKey.scopes,
+  }
+}
+
 /** Strips internal fields (`owner`, `secret`) from a subscription for reads. */
 function toPublic(subscription: Webhooks.Subscription) {
   return {
@@ -3406,6 +2607,10 @@ function toPublic(subscription: Webhooks.Subscription) {
     ...(subscription.context === undefined ? {} : { context: subscription.context }),
     createdAt: subscription.createdAt,
     destination: redactDestination(subscription.destination),
+    ...(subscription.eventType === 'funding:deposit.updated' &&
+    subscription.environment !== undefined
+      ? { environment: subscription.environment }
+      : {}),
     eventType: subscription.eventType,
     ...(subscription.expiresAt === undefined ? {} : { expiresAt: subscription.expiresAt }),
     failureCount: subscription.failureCount,
@@ -3688,11 +2893,3 @@ export declare namespace scanBlock {
     matches: readonly Match<subscription>[]
   }
 }
-
-class BlockUnavailableError extends Error {
-  override name = 'Webhooks.BlockUnavailableError'
-
-  constructor(blockNumber: number) {
-    super(`Block ${blockNumber} is unavailable.`)
-  }
-}