tapimo 0.10.0 → 0.10.2

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

@@ -1,4 +1,4 @@
-import { type Db, Webhooks as Core } from 'tapimo'
+import { type Db, Store, Webhooks as Core } from 'tapimo'
 import * as z from 'zod/mini'
 
 import * as Cursor from '../../../internal/Cursor.js'
@@ -1522,7 +1522,7 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
         "logIndex": 0,
         "recipient": "0x9e39034aae71fb89f66061a2602eb6efec271754",
         "sender": "0xe7687128b0a808c2831ff94d4f7b2fb35c65af38",
-        "timestamp": "2026-01-14T18:38:03.000Z",
+        "timestamp": "2026-01-14T18:38:03.685Z",
         "token": {
           "decimals": 6,
           "symbol": "QKSUSD",
@@ -1540,6 +1540,52 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     `)
   })
 
+  test('delivers collision-shaped token metadata from a cache hit', async () => {
+    const db = TestApp.database()
+    const subscription = await createTransferSubscription(db)
+    await Core.setCursor(db, subscription.id, windowCursor)
+    const cache = Store.memory()
+    const address = '0x20c00000000000000000000071de0cd31ab0d105'
+    await Store.memoize(
+      async () => ({
+        currency: 'USD',
+        decimals: 6,
+        name: 'Collision token',
+        symbol: '123#__bigint',
+      }),
+      {
+        key: `webhook:token-meta:v2:42431:${address}`,
+        store: cache,
+        ttl: 60_000,
+      },
+    )
+    const bodies: string[] = []
+    const fetch = (async (_input, init) => {
+      bodies.push(typeof init?.body === 'string' ? init.body : '')
+      return new Response(null, { status: 200 })
+    }) satisfies typeof globalThis.fetch
+
+    const result = await Webhooks.poll({
+      cache,
+      chainId: 42431,
+      client,
+      db,
+      dispatch: ({ envelope, subscription }) =>
+        Core.deliverAndRecord(db, subscription, envelope, { fetch }),
+      eventTypes: ['token:transfer'],
+      headBlockNumber: windowHead,
+    })
+
+    const payloads = bodies.map((body) => Webhooks.schema.Envelope.parse(JSON.parse(body)))
+    const delivered = payloads.find(
+      (payload) => payload.type === 'token:transfer' && payload.data.address === address,
+    )
+    expect(result.dispatched).toBe(2)
+    expect(delivered?.type === 'token:transfer' ? delivered.data.token?.symbol : undefined).toBe(
+      '123#__bigint',
+    )
+  })
+
   test('scans event types concurrently without increasing scan bounds', async () => {
     const db = TestApp.database()
     const transfer = await createTransferSubscription(db)
@@ -1605,7 +1651,8 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
       chainId: 42431,
       client,
       db,
-      dispatchBatch: async (dispatchables) => {
+      dispatchBatch: async (dispatchables, context) => {
+        expect(context.db).toBe(db)
         batches.push([...dispatchables])
         return { ok: true }
       },
@@ -2070,7 +2117,7 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
           "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
         },
         "logIndex": 0,
-        "timestamp": "2026-01-14T18:38:03.000Z",
+        "timestamp": "2026-01-14T18:38:03.685Z",
         "topics": [
           "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
           "0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38",
@@ -2113,7 +2160,7 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
         "blockNumber": 1000002,
         "data": "0x0000000000000000000000000000000000000000000000000000000000002710",
         "logIndex": 0,
-        "timestamp": "2026-01-14T18:38:03.000Z",
+        "timestamp": "2026-01-14T18:38:03.685Z",
         "topics": [
           "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
           "0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38",
@@ -2290,7 +2337,7 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
         "miner": "0x0000000000000000000000000000000000000000",
         "number": 1000002,
         "parentHash": "0xa406dff9c51cc2abbef3a811f0499e99a568bf781019f129ab45dca1df0e43e5",
-        "timestamp": "2026-01-14T18:38:03.000Z",
+        "timestamp": "2026-01-14T18:38:03.685Z",
         "transactionCount": 52,
       }
     `)

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

@@ -664,7 +664,7 @@ export namespace schema {
         .datetime()
         .check(
           z.describe('Block timestamp as an ISO 8601 string.'),
-          z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
         ),
       token: z.optional(
         z
@@ -790,7 +790,7 @@ export namespace schema {
         .datetime()
         .check(
           z.describe('When the block was produced, as an ISO 8601 timestamp.'),
-          z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
         ),
       topics: z.array(Schema.Hash).check(
         z.describe('Log topics, starting with the event signature hash (topic 0).'),
@@ -881,7 +881,7 @@ export namespace schema {
         .datetime()
         .check(
           z.describe('When the block was produced, as an ISO 8601 timestamp.'),
-          z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
         ),
     })
     .check(z.describe('Payload for a `block:created` event (a new block header).'))
@@ -2276,16 +2276,11 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
               // 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
+              const data = await enrichEventData(eventType, item.data, {
+                cache: cache_metadata,
+                chainId,
+                client,
+              })
               durations.enrich += Date.now() - enrichStartedAt
               observed.add('enrich')
               options.signal?.throwIfAborted()
@@ -2303,7 +2298,7 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
               const dispatchables: poll.Dispatchable[] = []
               for (const item of page.items) dispatchables.push(await buildDispatchable(item))
               options.signal?.throwIfAborted()
-              const delivered = await dispatchBatch(dispatchables)
+              const delivered = await dispatchBatch(dispatchables, { db })
               if (delivered.ok) {
                 accepted = page.items.at(-1)?.cursor
                 result.dispatched += dispatchables.length
@@ -2406,7 +2401,9 @@ export declare namespace poll {
      */
     dispatch?: ((input: Dispatchable) => Promise<Webhooks.Result>) | undefined
     /** Batch delivery transport. A successful result confirms every row in the input. */
-    dispatchBatch?: ((input: readonly Dispatchable[]) => Promise<Webhooks.Result>) | undefined
+    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`. */
@@ -2426,6 +2423,12 @@ export declare namespace poll {
     /** 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. */
@@ -3066,6 +3069,32 @@ function decodeScanLog(log: ScanLog, event: AbiEvent): ScanLog {
   }
 }
 
+/**
+ * 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
+}
+
+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
+  }
+}
+
 /** Scans contract logs for one subscription, then re-checks every filter in memory. */
 async function scanLogs(options: {
   batchSize: number
@@ -3124,7 +3153,12 @@ async function scanLogs(options: {
     if (blockNumber === undefined || logIndex === undefined) continue
     if (atOrBefore(blockNumber, logIndex, window.skip)) continue
     if (!matchesLog(log, f, event)) continue
-    const data = toLogEvent(log, blockIso(await cache.header(blockNumber)), f.signature, event)
+    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 }
@@ -3178,12 +3212,6 @@ function matchesLog(
 
 // block:created (getBlock)
 
-/** Converts a viem block's `timestamp` (seconds) to an ISO 8601 string. */
-function blockIso(block: RpcBlock | undefined): string | undefined {
-  if (!block || typeof block.timestamp !== 'bigint') return undefined
-  return new Date(Number(block.timestamp) * 1000).toISOString()
-}
-
 type BlockEventData = {
   number: number
   hash: string
@@ -3203,7 +3231,7 @@ function toBlockEvent(block: RpcBlock): BlockEventData | undefined {
   const miner = Schema.Address.safeParse(block.miner)
   const gasUsed = typeof block.gasUsed === 'bigint' ? Number(block.gasUsed) : undefined
   const gasLimit = typeof block.gasLimit === 'bigint' ? Number(block.gasLimit) : undefined
-  const timestamp = blockIso(block)
+  const timestamp = Value.blockToIso(block)
   const transactionCount = Array.isArray(block.transactions) ? block.transactions.length : 0
   if (
     number === undefined ||
@@ -3318,6 +3346,9 @@ async function scanTxs(options: {
       ? (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
@@ -3325,7 +3356,8 @@ async function scanTxs(options: {
       if (!matchesTx(transaction, f, includeCalls, timestamp, blockNumber)) continue
       const parsed = Transactions.schema.Rpc.Transaction.safeParse(transaction)
       if (!parsed.success) continue
-      const data = Transactions.humanizeTransaction(parsed.data)
+      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 }
     }
@@ -3482,6 +3514,202 @@ function unauthorized(c: Context<App.Environment>) {
   })
 }
 
+// Pure per-block scanning (no RPC, no cursors, no pagination).
+
+// Pure over its inputs: the caller fetches the raw block (with transactions)
+// and its logs; enrichment happens downstream. Rows require a parsable block number.
+/**
+ * Matches one fetched block against a subscription set, producing the rows
+ * each event type delivers. Invalid stored filters fail closed into `invalid`.
+ */
+export function scanBlock<const subscription extends scanBlock.Subscription>(
+  options: scanBlock.Options<subscription>,
+): scanBlock.Result<subscription> {
+  const { block, logs, subscriptions } = options
+  const blockNumber = Value.hexToNumber(block['number'])
+  const timestamp = Value.blockToIso(block)
+  const header = toScanHeader(block)
+  const viemLogs = logs.map(fromRpcLog)
+  const matches: scanBlock.Match<subscription>[] = []
+  const invalid: scanBlock.Invalid<subscription>[] = []
+
+  for (const subscription of subscriptions) {
+    const filters = (() => {
+      try {
+        return parseFilters(subscription.eventType, subscription.filters)
+      } catch (error) {
+        invalid.push({ error, subscription })
+        return undefined
+      }
+    })()
+    if (filters === undefined) continue
+    const matched = matches.length
+    const push = (data: unknown, logIndex: number) => {
+      if (blockNumber !== undefined) matches.push({ blockNumber, data, logIndex, subscription })
+    }
+
+    // A throwing matcher invalidates only this subscription, rolling back any
+    // rows it matched before the failure.
+    try {
+      switch (subscription.eventType) {
+        case 'block:created': {
+          const f = filters as z.output<typeof schema.BlockFilters>
+          if (!matchesBlock(header, f)) break
+          const data = toBlockEvent(header)
+          if (data) push(data, 0)
+          break
+        }
+        case 'log:emitted': {
+          const f = filters as z.output<typeof schema.LogFilters>
+          const event = parseEvent(f.signature)
+          if (f.signature && (!event || !/^[A-Za-z_]\w*$/.test(event.name))) {
+            invalid.push({
+              error: new Webhooks.InvalidFilterError('log:emitted', [
+                { message: 'Unsupported event signature.', path: ['signature'] },
+              ]),
+              subscription,
+            })
+            break
+          }
+          // Validate arg names up front so a bad filter fails closed even
+          // when the block has no decodable logs.
+          const unknown =
+            event && f.args
+              ? Object.keys(f.args).find(
+                  (name) => !event.inputs.some((input) => input.name === name),
+                )
+              : undefined
+          if (unknown !== undefined) {
+            invalid.push({
+              error: new Webhooks.InvalidFilterError('log:emitted', [
+                { message: `Unknown event argument: ${unknown}.`, path: ['args', unknown] },
+              ]),
+              subscription,
+            })
+            break
+          }
+          for (const log of viemLogs) {
+            const decoded = event ? decodeScanLog(log, event) : log
+            const logIndex = decoded.logIndex ?? undefined
+            if (logIndex === undefined) continue
+            if (!matchesLog(decoded, f, event)) continue
+            const data = toLogEvent(decoded, timestamp, f.signature, event)
+            if (data) push(data, logIndex)
+          }
+          break
+        }
+        case 'token:transfer': {
+          if (timestamp === undefined) break
+          const f = filters as WebhookTransfer.Filters
+          for (const log of logs) {
+            const data = WebhookTransfer.decode(log, timestamp)
+            if (!data || !WebhookTransfer.matches(data, f)) continue
+            push(data, data.logIndex)
+          }
+          break
+        }
+        case 'transaction:included': {
+          const f = filters as z.output<typeof schema.TxFilters>
+          const includeCalls = f.includeCalls ?? true
+          const transactions = Array.isArray(block['transactions'])
+            ? (block['transactions'] as unknown[])
+            : []
+          const rawTimestamp = asString(block['timestamp'])
+          for (let offset = 0; offset < transactions.length; offset++) {
+            const transaction = transactions[offset]
+            if (!transaction || typeof transaction !== 'object') continue
+            const tx = transaction as Record<string, unknown>
+            const transactionIndex = Value.hexToNumber(tx['transactionIndex']) ?? offset
+            if (!matchesTx(tx, f, includeCalls, rawTimestamp, blockNumber ?? 0)) continue
+            const parsed = Transactions.schema.Rpc.Transaction.safeParse(tx)
+            if (!parsed.success) continue
+            const humanized = Transactions.humanizeTransaction(parsed.data)
+            // A transaction's own timestamp is seconds-only; the enclosing
+            // block carries milliseconds.
+            push(
+              timestamp === undefined ? humanized : { ...humanized, timestamp },
+              transactionIndex,
+            )
+          }
+          break
+        }
+      }
+    } catch (error) {
+      matches.length = matched
+      invalid.push({ error, subscription })
+    }
+  }
+  return { invalid, matches }
+}
+
+/** Normalizes a raw RPC header to the viem-shaped fields the block matchers read. */
+function toScanHeader(block: Record<string, unknown>): RpcBlock {
+  const quantity = (value: unknown) => {
+    try {
+      return typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint'
+        ? BigInt(value)
+        : undefined
+    } catch {
+      return undefined
+    }
+  }
+  return {
+    ...block,
+    gasLimit: quantity(block['gasLimit']),
+    gasUsed: quantity(block['gasUsed']),
+    number: quantity(block['number']),
+    timestamp: quantity(block['timestamp']),
+  } as RpcBlock
+}
+
+export declare namespace scanBlock {
+  /** The subscription fields matching consumes; extra fields flow through. */
+  type Subscription = {
+    /** Event type selecting the matcher and payload shape. */
+    eventType: EventType
+    /** Stored filter predicates, validated fail-closed per event type. */
+    filters: Record<string, unknown>
+  }
+
+  /** One fetched block plus the subscriptions to match it against. */
+  type Options<subscription extends Subscription> = {
+    /** Raw `eth_getBlockByNumber(_, true)` result: header plus raw transactions. */
+    block: Record<string, unknown>
+    /** Raw `eth_getLogs` entries for exactly this block, in log order. */
+    logs: readonly RpcLog[]
+    /** Active subscriptions for the chain; any mix of event types. */
+    subscriptions: readonly subscription[]
+  }
+
+  /** One deliverable row for one subscription. */
+  type Match<subscription extends Subscription> = {
+    /** Block the row was produced from. */
+    blockNumber: number
+    /** Payload the matching read endpoint returns (pre-enrichment). */
+    data: unknown
+    /** Row position within the block (log or transaction index; 0 for blocks). */
+    logIndex: number
+    /** The matched subscription, passed through verbatim. */
+    subscription: subscription
+  }
+
+  /** A subscription whose stored filters failed validation. */
+  type Invalid<subscription extends Subscription> = {
+    /** The validation failure. */
+    error: unknown
+    /** The subscription with invalid filters. */
+    subscription: subscription
+  }
+
+  /** Matches plus fail-closed filter rejections. */
+  type Result<subscription extends Subscription> = {
+    /** Subscriptions skipped because their stored filters failed validation. */
+    invalid: readonly Invalid<subscription>[]
+    /** Deliverable rows in subscription order, block order within each type. */
+    matches: readonly Match<subscription>[]
+  }
+}
+
 class BlockUnavailableError extends Error {
   override name = 'Webhooks.BlockUnavailableError'
 

package/src/apps/data/routes/zones.bench.ts

@@ -0,0 +1,32 @@
+import * as Tidx from '../../../internal/Tidx.js'
+import * as Viem from '../../../internal/Viem.js'
+import * as TestApp from '../../../../test/App.js'
+import * as QueryBench from '../../../../test/QueryBench.js'
+
+const senderTag = `0x${'00'.repeat(32)}`
+const zoneChainIds = {
+  4217: 421_700_002,
+  42431: 424_310_002,
+} as const
+
+QueryBench.bench({
+  chainId: false,
+  name: 'listZoneWithdrawals',
+  path: {
+    4217: `/v1/zones/withdrawals/${senderTag}?chainId=${zoneChainIds[4217]}`,
+    42431: `/v1/zones/withdrawals/${senderTag}?chainId=${zoneChainIds[42431]}`,
+  },
+  zones: ({ chainId }) => {
+    const rpcUrl = Viem.resolveUrl(process.env.RPC_URL, chainId) ?? Viem.url[chainId]
+    const tidxUrl = Viem.resolveUrl(process.env.TIDX_URL, chainId) ?? Tidx.url[chainId]
+    if (!rpcUrl || !tidxUrl) throw new Error(`Missing Zone upstream for chain ${chainId}.`)
+    return [
+      TestApp.zone({
+        chainId: zoneChainIds[chainId],
+        rpcUrl,
+        sourceChainId: chainId,
+        tidxUrl,
+      }),
+    ]
+  },
+})

package/src/apps/data/routes/zones.test.ts

@@ -419,7 +419,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
         },
         {
           "examples": [
-            421700001,
+            1424310001,
           ],
           "name": "chainId",
           "required": true,

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

@@ -43,7 +43,7 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainId.check(
           z.describe('The chain id of the Zone where the withdrawal originated.'),
-          z.meta({ examples: [421_700_001] }),
+          z.meta({ examples: [1_424_310_001] }),
         ),
       })
       .check(z.describe('Query parameters used to select the originating Zone.'))

package/src/apps/funding/routes/chains.test.ts

@@ -22,7 +22,7 @@ const providers = [
     integratorId: '0xdead',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
-  Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+  Relay.relay({ userAddresses: TestFunding.relayQuoteUsers }),
   Rhino.rhino(),
   Squid.squid({
     integratorId: 'squid-integrator-id',