tapimo 0.9.0 → 0.10.0

package/dist/apps/data/routes/webhooks.js

@@ -12,8 +12,8 @@ import * as Store from '../../../internal/Store.js';
 import * as Ttl from '../../../internal/Ttl.js';
 import * as Value from '../../../internal/Value.js';
 import * as WebhookDestination from '../../../internal/WebhookDestination.js';
+import * as WebhookTransfer from '../../../internal/WebhookTransfer.js';
 import * as Webhooks from '../../../internal/Webhooks.js';
-import * as Receipts from './receipts.js';
 import * as Transactions from './transactions.js';
 import * as Transfers from './transfers.js';
 /** Default cap on live subscriptions per owner, overridable via `webhook.maxPerOwner`. */
@@ -52,7 +52,7 @@ const eventTypeDescriptions = [
         type: 'token:transfer',
     },
     {
-        description: 'A transaction included in a block, filterable on every transaction field (sender, recipient, value, calldata, inner account-abstraction calls, fees, nonce) and its execution status.',
+        description: 'A transaction included in a block, filterable on transaction fields such as sender, recipient, value, calldata, inner account-abstraction calls, fees, and nonce.',
         type: 'transaction:included',
     },
 ];
@@ -173,13 +173,12 @@ export var schema;
     schema.TransferFilters = Transfers.schema.Predicates.check(z.describe('Filters that narrow which TIP-20 transfer events trigger this webhook.'), z.meta({ title: 'Transfer filters' }));
     /**
      * `transaction:included` subscription filters: operators over every column the
-     * `txs` envelope exposes, plus inner account-abstraction `calls`, the
-     * top-level `input` calldata, and the receipt-sourced execution `status`. All
-     * optional and AND-combined; omit every field for the full stream.
+     * `txs` envelope exposes, plus inner account-abstraction `calls` and the
+     * top-level `input` calldata. All optional and AND-combined; omit every field
+     * for the full stream.
      *
      * `address` matches either side (`from` OR `to`); when `includeCalls` is set
      * (default), `to`/`address` also match an inner call target (`calls[].to`).
-     * Set `includeReceipt` to embed the receipt in the delivered payload.
      */
     schema.TxFilters = z
         .strictObject({
@@ -190,9 +189,6 @@ export var schema;
         includeCalls: z.optional(z
             .boolean()
             .check(z.describe('When true (default), `to`/`address` also match an inner account-abstraction call target (`calls[].to`).'), z.meta({ examples: [true] }))),
-        includeReceipt: z.optional(z
-            .boolean()
-            .check(z.describe('When true, embed the transaction receipt (execution `status`, `gasUsed`, `logs`, …) in the delivered payload under `meta.receipt`. Default false (the receipt is an extra fetch). Mirrors the read endpoint\u2019s `include=receipt`.'), z.meta({ examples: [true] }))),
         value: z.optional(schema.compare.check(z.describe('Match the transaction value (wei) bounds.'))),
         input: z.optional(schema.bytes.check(z.describe('Match top-level calldata by 4-byte `selector`, hex `startsWith`, or exact.'))),
         calls: z.optional(z
@@ -203,9 +199,7 @@ export var schema;
         callCount: z.optional(schema.compare.check(z.describe('Match the number of inner calls (`call_count`).'))),
         txType: z.optional(schema.eq(Schema.Hex).check(z.describe('Match the transaction type (e.g. `0x76` for Tempo AA).'))),
         feeToken: z.optional(schema.eq(Schema.TokenAddress).check(z.describe('Match the fee token address.'))),
-        feePayer: z.optional(schema.eq(Schema.Address).check(z.describe('Match the fee payer address.'))),
         gasLimit: z.optional(schema.compare.check(z.describe('Match the gas limit bounds.'))),
-        gasUsed: z.optional(schema.compare.check(z.describe('Match the gas used bounds.'))),
         maxFeePerGas: z.optional(schema.compare.check(z.describe('Match the max fee per gas bounds.'))),
         maxPriorityFeePerGas: z.optional(schema.compare.check(z.describe('Match the max priority fee per gas bounds.'))),
         nonce: z.optional(schema.compare.check(z.describe('Match the nonce bounds.'))),
@@ -214,9 +208,6 @@ export var schema;
         validAfter: z.optional(schema.compare.check(z.describe('Match the `validAfter` bounds (unix s).'))),
         blockNumber: z.optional(schema.compare.check(z.describe('Match the block-number bounds.'))),
         timestamp: z.optional(schema.compare.check(z.describe('Match the block timestamp bounds (unix s).'))),
-        status: z.optional(z
-            .enum(['success', 'reverted'])
-            .check(z.describe('Match the receipt execution status (routes through `receipts`).'), z.meta({ examples: ['success'] }))),
     })
         .check(z.describe('Filters that narrow which included transactions trigger this webhook.'), z.meta({ title: 'Included-transaction filters' }));
     /** A 32-byte log topic (lowercased hex). */
@@ -402,10 +393,19 @@ export var schema;
     })
         .check(z.describe('Payload for a `token:transfer` event, decoded from a TIP-20 `Transfer` log.'));
     /**
-     * A `transaction` event payload: identical to the `GET /transactions/:hash`
-     * response (the poller reuses the same humanized shape).
+     * A `transaction` event payload using the humanized transaction shape without
+     * opt-in read resources such as receipts.
      */
-    schema.TransactionEvent = Transactions.schema.getTransaction.Response;
+    schema.TransactionEvent = z
+        .object({
+        ...Transactions.schema.Transaction.shape,
+        meta: z
+            .object({
+            rpc: Transactions.schema.Rpc.Transaction.check(z.describe('The original JSON-RPC transaction payload.')),
+        })
+            .check(z.describe('Metadata for this transaction webhook event.')),
+    })
+        .check(z.describe('A transaction included in a block.'));
     /**
      * A `log:emitted` event payload: the raw contract event log. When a
      * `signature` filter was supplied and decoding succeeds, the best-effort
@@ -461,7 +461,7 @@ export var schema;
             .check(z.int(), z.nonnegative(), z.describe('Index of the transaction within its block.'), z.meta({ examples: [0] })),
     })
         .check(z.describe('Payload for a `log:emitted` event (a raw contract event log).'));
-    /** Payload for a `block:created` event (a TIDX-derived block header). */
+    /** Payload for a `block:created` event (an RPC-derived block header). */
     schema.BlockEvent = z
         .object({
         number: z
@@ -1317,6 +1317,50 @@ export function webhooks(options = {}) {
  */
 const endOfBlockIndex = 2_147_483_647;
 const scanPageSize = 100;
+/** 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;
+/** Schedules asynchronous work through one shared concurrency bound. */
+function createLimiter(limit) {
+    let active = 0;
+    const waiting = [];
+    return async (fn) => {
+        if (active >= limit)
+            await new Promise((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(items, limit, fn) {
+    const results = [];
+    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, candidate) {
     const before = Cursor.decode(current, ['int', 'int']);
@@ -1336,13 +1380,9 @@ function laterCursor(current, candidate) {
  * matching row, advancing each active subscription's `(block, index)` keyset
  * cursor.
  *
- * The new monitoring event types (`log:emitted`, `block:created`,
- * `transaction:included`) scan a **narrow confirmed window** `[cursor, head -
- * confirmations]` directly over JSON-RPC (`eth_getLogs`, `eth_getBlockByNumber`,
- * `eth_getBlockReceipts`) — the same data sources the indexer itself consumes —
- * so they need no indexer and stay fresh. The pre-existing `token:transfer`
- * type continues to read its humanized shape from TIDX, clamped to the indexed
- * head so it never runs ahead of the indexer.
+ * 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,
@@ -1355,28 +1395,45 @@ function laterCursor(current, candidate) {
  * after the remaining subscriptions run.
  */
 export async function poll(options) {
-    const { batchSize = 200, cache: cache_metadata = Store.memory(), chainId, client, confirmations = 2, db, eventTypes = ['token:transfer', 'transaction:included', 'log:emitted', 'block:created'], maxBlocks = 1_000, tidx, } = options;
+    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));
-    // Head resolution is lazy and per-source. RPC types work back from the live
-    // RPC head; the legacy TIDX types from the indexed head (never ahead of the
-    // indexer). A pinned `headBlockNumber` (tests) overrides both.
+    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 = override === undefined ? undefined : Number(override);
     const resolveRpcHead = async () => (rpcHead ??= await getRpcHead(client));
-    let tidxHead = override === undefined ? undefined : Number(override);
-    const resolveTidxHead = async () => (tidxHead ??= tidx ? await getIndexedHead(tidx, chainId) : await resolveRpcHead());
-    const rpcSafeBlock = Math.max(0, (await resolveRpcHead()) - confirmations);
-    // Reclaim expired rows (MPP-owned subscriptions, aged delivery logs) once
-    // per tick; reads filter expiry at query time, so this is hygiene only.
-    await Webhooks.pruneExpired(db, { now }).catch(() => { });
-    // Per-tick lazy cache so multiple subscriptions of the same/related types
-    // share fetched blocks and receipts instead of refetching the same window.
-    const cache = createChainCache(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 = {
         chainId,
         dispatched: 0,
@@ -1385,19 +1442,76 @@ export async function poll(options) {
         scanned: 0,
         subscriptions: 0,
     };
-    const scanErrors = [];
-    for (const eventType of eventTypes) {
-        const legacy = eventType === 'token:transfer';
-        const safeBlock = legacy ? Math.max(0, (await resolveTidxHead()) - confirmations) : rpcSafeBlock;
-        const subscriptions = await Webhooks.listActive(db, chainId, eventType);
+    let cursorLagBlocks = 0;
+    const pollErrors = [];
+    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,
+        };
+        const observed = new Set();
+        let cursorWriteOutcome = 'ok';
+        let scanOutcome = 'ok';
+        const writeCursor = async (parameters) => {
+            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 = [];
-        for (const subscription of subscriptions) {
+        for (const pair of pairs) {
+            const { subscription } = pair;
             result.subscriptions++;
-            let cursor = await Webhooks.getCursor(db, subscription.id);
+            let filters;
+            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 Webhooks.compareAndSetCursor(db, {
+                await writeCursor({
                     cursor: Cursor.encode([safeBlock, endOfBlockIndex]),
                     expectedCursor: null,
                     subscriptionId: subscription.id,
@@ -1412,7 +1526,7 @@ export async function poll(options) {
                     Math.max(0, checkpoint[0] - confirmations),
                     endOfBlockIndex,
                 ]);
-                const committed = await Webhooks.compareAndSetCursor(db, {
+                const committed = await writeCursor({
                     cursor: confirmedCursor,
                     expectedCursor: cursor,
                     subscriptionId: subscription.id,
@@ -1421,9 +1535,15 @@ export async function poll(options) {
                     continue;
                 cursor = confirmedCursor;
             }
-            const window = legacy ? undefined : scanWindow(cursor, safeBlock, maxBlocks);
+            const position = Cursor.decode(cursor, ['int', 'int']);
+            if (position)
+                cursorLagBlocks = Math.max(cursorLagBlocks, safeBlock - position[0]);
+            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,
@@ -1432,87 +1552,219 @@ export async function poll(options) {
         // 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 = [];
-            for (const state of states) {
-                const { subscription } = state;
-                let page;
-                try {
-                    page = await scanSubscription({
-                        batchSize: Math.min(scanPageSize, state.remaining),
-                        cache,
-                        client,
-                        cursor: state.cursor,
-                        maxBlocks,
-                        safeBlock: state.safeBlock,
-                        subscription,
-                        tidx,
-                    });
+            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';
+                const busy = [];
+                const idle = [];
+                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 });
                 }
-                catch (error) {
-                    scanErrors.push(error);
-                    continue;
+                // 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();
+                        }
+                    })();
+                    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');
                 }
-                result.scanned += page.items.length;
-                state.remaining -= page.items.length;
-                let accepted;
-                let failed = false;
-                for (const item of page.items) {
-                    // Token metadata is best-effort for webhooks: transfers use it for display,
-                    // while transactions expose fee-token references without blocking delivery.
-                    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 envelope = Webhooks.buildEnvelope({
-                        blockNumber: item.cursor[0],
-                        createdAt: now(),
-                        data,
-                        logIndex: item.cursor[1],
-                        subscription,
-                    });
-                    const delivered = await dispatch({ envelope, subscription });
-                    if (!delivered.ok) {
-                        result.failed++;
-                        failed = true;
-                        break;
+                for (const { page, state } of busy) {
+                    options.signal?.throwIfAborted();
+                    const { subscription } = state;
+                    let accepted;
+                    let failed = false;
+                    const buildDispatchable = async (item) => {
+                        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 = [];
+                        for (const item of page.items)
+                            dispatchables.push(await buildDispatchable(item));
+                        options.signal?.throwIfAborted();
+                        const delivered = await dispatchBatch(dispatchables);
+                        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;
                     }
-                    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 Webhooks.compareAndSetCursor(db, {
-                        cursor,
-                        expectedCursor: state.cursor,
-                        subscriptionId: subscription.id,
-                    });
-                    if (committed)
-                        state.cursor = cursor;
                 }
-                if (!failed && page.hasMore === true && committed && state.remaining > 0)
-                    continuations.push(state);
             }
             states = continuations;
         }
-    }
-    if (scanErrors.length > 0)
-        throw scanErrors[0];
+        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;
 }
 /**
@@ -1583,103 +1835,77 @@ function withResolvedFeeToken(data, metadata) {
         result['feeToken'] = { address, ...token };
     return result;
 }
-/** Adds best-effort fee-token references to a transaction and its embedded receipt. */
+/** Adds a best-effort fee-token reference to a transaction. */
 async function withFeeTokenMetadata(data, deps) {
     if (typeof data !== 'object' || data === null)
         return data;
     const transaction = data;
-    const meta = transaction['meta'];
-    const receipt = typeof meta === 'object' && meta !== null
-        ? meta['receipt']
-        : undefined;
-    const addresses = new Set();
-    const transactionAddress = feeTokenAddress(transaction['feeToken']);
-    if (transactionAddress)
-        addresses.add(transactionAddress.toLowerCase());
-    if (typeof receipt === 'object' && receipt !== null) {
-        const receiptAddress = feeTokenAddress(receipt['feeToken']);
-        if (receiptAddress)
-            addresses.add(receiptAddress.toLowerCase());
-    }
-    if (addresses.size === 0)
+    const address = feeTokenAddress(transaction['feeToken']);
+    if (!address)
         return data;
-    const resolved = await Promise.all([...addresses].map(async (address) => [address, await resolveTokenMetadata(address, deps)]));
-    const metadata = new Map(resolved.filter((entry) => entry[1] !== undefined));
-    const result = withResolvedFeeToken(transaction, metadata);
-    if (typeof receipt !== 'object' || receipt === null)
-        return result;
-    return {
-        ...result,
-        meta: {
-            ...meta,
-            receipt: withResolvedFeeToken(receipt, metadata),
-        },
-    };
+    const token = await resolveTokenMetadata(address, deps);
+    const metadata = new Map();
+    if (token)
+        metadata.set(address.toLowerCase(), token);
+    return withResolvedFeeToken(transaction, metadata);
 }
 /** Returns the live RPC head block number for the chain. */
 export async function getRpcHead(client) {
     return Number(await client.getBlockNumber());
 }
-/**
- * Returns the highest block number TIDX has indexed for a chain (0 when none).
- * The legacy `token:transfer` type works back from this so it never scans past
- * the indexer.
- */
-export async function getIndexedHead(tidx, chainId) {
-    const result = await tidx.fetch({
-        chainId,
-        query: 'SELECT num FROM blocks ORDER BY num DESC LIMIT 1',
+/** Groups aligned cursors only when their bounded upstream scans are equivalent. */
+async function scanSubscriptions(options) {
+    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),
+        })),
     });
-    return Value.toNumber(result.rows[0]?.['num']) ?? 0;
 }
-/**
- * Scans new events for one subscription. The RPC monitoring types
- * (`log:emitted` / `block:created` / `transaction:included`) read a confirmed
- * window directly over JSON-RPC; the legacy `token:transfer` type dispatches to
- * its TIDX read core (`Transfers.scan`).
- */
-async function scanSubscription(options) {
-    const { batchSize, cache, client, cursor, maxBlocks, safeBlock, subscription, tidx } = options;
-    // Stored `chainId` was validated against `Schema.ChainId` at create time.
-    const chainId = subscription.chainId;
-    if (subscription.eventType === 'log:emitted')
-        return scanLogs({
-            batchSize,
-            cache,
-            client,
-            cursor,
-            filters: parseFilters('log:emitted', subscription.filters),
-            maxBlocks,
-            safeBlock,
-        });
-    if (subscription.eventType === 'block:created')
-        return scanBlocks({
-            batchSize,
-            cache,
-            cursor,
-            filters: parseFilters('block:created', subscription.filters),
-            maxBlocks,
-            safeBlock,
-        });
-    if (subscription.eventType === 'transaction:included')
-        return scanTxs({
-            batchSize,
+/** Returns the bounded JSON-RPC method used by an event scanner. */
+function scanRpcMethod(eventType) {
+    return eventType === 'block:created' || eventType === 'transaction:included'
+        ? 'eth_getBlockByNumber'
+        : 'eth_getLogs';
+}
+/** Classifies a completed batch without exposing an unbounded upstream error. */
+function scanResultOutcome(pages) {
+    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) {
+    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,
-            filters: parseFilters('transaction:included', subscription.filters),
+            cursor: state.cursor,
+            filters: state.filters,
             maxBlocks,
-            safeBlock,
-        });
-    // Legacy TIDX-backed type.
-    if (!tidx)
-        return { hasMore: false, items: [] };
-    const filters = transferFilters(subscription.filters);
-    const page = await Transfers.scan({ tidx }, { chainId, cursor, limit: batchSize, order: 'asc', toBlock: safeBlock, ...filters });
-    // A cap-truncated fallback sample is an arbitrary subset: dispatching it
-    // would advance the cursor past unseen matches. Hold position and retry.
-    if (page.capped)
-        return { hasMore: true, items: [] };
-    return { hasMore: page.hasMore, items: page.items };
+            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,
@@ -1699,17 +1925,6 @@ export function parseFilters(eventType, filters) {
         throw new Webhooks.InvalidFilterError(eventType, Response.validationDetails(result.error.issues));
     return result.data;
 }
-/** Narrows stored `transfer` filters into validated `Transfers.scan` predicates. */
-function transferFilters(filters) {
-    const parsed = schema.TransferFilters.safeParse(filters);
-    const { address, recipient, sender, token } = parsed.success ? parsed.data : {};
-    return {
-        ...(address === undefined ? {} : { eitherSide: address }),
-        ...(recipient === undefined ? {} : { recipient }),
-        ...(sender === undefined ? {} : { sender }),
-        ...(token === undefined ? {} : { token }),
-    };
-}
 /** Recursively lowercases string leaves of a filter operator (for address args). */
 function lowercaseLeaves(op) {
     if (typeof op === 'string')
@@ -1842,52 +2057,34 @@ function scanWindow(cursor, safeBlock, maxBlocks) {
 function atOrBefore(block, index, skip) {
     return block < skip[0] || (block === skip[0] && index <= skip[1]);
 }
-/** Builds a per-tick {@link ChainCache} bound to a viem client. */
+/** Builds a per-batch {@link ChainCache} bound to a viem client. */
 function createChainCache(client) {
     const headers = new Map();
     const blocks = new Map();
-    const receipts = new Map();
+    const singleFlight = (pending, key, load) => {
+        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) {
-            let p = blocks.get(n);
-            if (!p) {
-                // The transaction payload reuses `humanizeTransaction`, which consumes
-                // the raw RPC tx shape, so the full block stays on the untyped path.
-                p = rpc(client, 'eth_getBlockByNumber', [
-                    blockTag(n),
-                    true,
-                ]).then((block) => {
-                    if (!block)
-                        throw new BlockUnavailableError(n);
-                    return block;
-                });
-                blocks.set(n, p);
-            }
-            return p;
+            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(client, 'eth_getBlockByNumber', [
+                blockTag(n),
+                true,
+            ]).then((block) => {
+                if (!block)
+                    throw new BlockUnavailableError(n);
+                return block;
+            }));
         },
         header(n) {
-            let p = headers.get(n);
-            if (!p) {
-                p = client.getBlock({ blockNumber: BigInt(n), includeTransactions: false });
-                headers.set(n, p);
-            }
-            return p;
-        },
-        receipts(n) {
-            let p = receipts.get(n);
-            if (!p) {
-                p = rpc(client, 'eth_getBlockReceipts', [blockTag(n)]).then((list) => {
-                    const map = new Map();
-                    for (const receipt of list ?? []) {
-                        const hash = receipt['transactionHash'];
-                        if (typeof hash === 'string')
-                            map.set(hash.toLowerCase(), receipt);
-                    }
-                    return map;
-                });
-                receipts.set(n, p);
-            }
-            return p;
+            return singleFlight(headers, n, () => client.getBlock({ blockNumber: BigInt(n), includeTransactions: false }));
         },
     };
 }
@@ -2005,7 +2202,7 @@ function pushTopics(f, event) {
         pushHex(f.topic2),
         pushHex(f.topic3),
     ];
-    while (topics.at(-1) === undefined)
+    while (topics.length > 0 && topics.at(-1) === undefined)
         topics.pop();
     return topics.map((topic) => topic ?? null);
 }
@@ -2040,17 +2237,7 @@ function decodeScanLog(log, event) {
         return log;
     }
 }
-/**
- * Scans contract event logs over the confirmed window via `eth_getLogs`,
- * then re-checks **every** filter in JS. Operators the RPC cannot express
- * (`not`, ranges, non-indexed `args`) still apply. Two modes:
- * - **raw** (no `signature`): `topic0..3` are matched directly.
- * - **decoded** (`signature` present): the selector, raw topics, and supported
- *   indexed `args` are pushed down before the JS pass matches decoded values.
- *
- * Exact and membership address/topic operators are pushed down to the node;
- * all operators are re-checked in JS over the narrow window.
- */
+/** Scans contract logs for one subscription, then re-checks every filter in memory. */
 async function scanLogs(options) {
     const { batchSize, cache, client, cursor, filters, maxBlocks, safeBlock } = options;
     const f = filters;
@@ -2063,8 +2250,6 @@ async function scanLogs(options) {
             { message: 'Unsupported event signature.', path: ['signature'] },
         ]);
     const address = pushAddress(f.address);
-    const fromBlock = BigInt(window.from);
-    const toBlock = BigInt(window.to);
     const topics = pushTopics(f, event);
     const hasRawTopics = topics.slice(1).some((topic) => topic !== null);
     const args = event ? pushEventArgs(f.args, event) : {};
@@ -2083,16 +2268,13 @@ async function scanLogs(options) {
             ...(address ? { address } : {}),
             ...(Object.keys(args).length > 0 ? { args: args } : {}),
             event,
-            fromBlock,
+            fromBlock: BigInt(window.from),
             strict: false,
-            toBlock,
+            toBlock: BigInt(window.to),
         }));
     logs.sort((a, b) => {
-        const ab = Number(a.blockNumber ?? 0n);
-        const bb = Number(b.blockNumber ?? 0n);
-        if (ab !== bb)
-            return ab - bb;
-        return (a.logIndex ?? 0) - (b.logIndex ?? 0);
+        const block = Number(a.blockNumber ?? 0n) - Number(b.blockNumber ?? 0n);
+        return block || (a.logIndex ?? 0) - (b.logIndex ?? 0);
     });
     const items = [];
     for (const log of logs) {
@@ -2104,9 +2286,7 @@ async function scanLogs(options) {
             continue;
         if (!matchesLog(log, f, event))
             continue;
-        const header = await cache.header(blockNumber);
-        const timestamp = blockIso(header);
-        const data = toLogEvent(log, timestamp, f.signature, event);
+        const data = toLogEvent(log, blockIso(await cache.header(blockNumber)), f.signature, event);
         if (data) {
             items.push({ cursor: [data.blockNumber, data.logIndex], data });
             if (items.length >= batchSize)
@@ -2118,6 +2298,11 @@ async function scanLogs(options) {
 /** Re-checks all log filters (including non-pushable operators) in JS. */
 function matchesLog(log, f, event) {
     const topics = log.topics;
+    if (event) {
+        const selector = encodeEventTopics({ abi: [event] })[0];
+        if (topics[0]?.toLowerCase() !== selector.toLowerCase())
+            return false;
+    }
     if (f.address !== undefined && !matchesOperator(log.address, f.address))
         return false;
     if (f.blockNumber !== undefined &&
@@ -2189,11 +2374,7 @@ function toBlockEvent(block) {
         transactionCount,
     };
 }
-/**
- * Scans new blocks over the confirmed window via viem's `getBlock`. One row per
- * block (the keyset index is always 0); filters match block-level metadata. An
- * empty filter is a per-block heartbeat.
- */
+/** Scans new blocks over one subscription's confirmed window. */
 async function scanBlocks(options) {
     const { batchSize, cache, cursor, filters, maxBlocks, safeBlock } = options;
     const f = filters;
@@ -2201,10 +2382,10 @@ async function scanBlocks(options) {
     if (!window)
         return { items: [], scannedThrough: undefined };
     const items = [];
-    for (let n = window.from; n <= window.to; n++) {
-        if (atOrBefore(n, 0, window.skip))
+    for (let blockNumber = window.from; blockNumber <= window.to; blockNumber++) {
+        if (atOrBefore(blockNumber, 0, window.skip))
             continue;
-        const block = await cache.header(n);
+        const block = await cache.header(blockNumber);
         if (!block)
             continue;
         if (!matchesBlock(block, f))
@@ -2237,7 +2418,7 @@ function matchesBlock(block, f) {
         return false;
     return true;
 }
-// transaction:included (eth_getBlockByNumber + eth_getBlockReceipts)
+// transaction:included (eth_getBlockByNumber)
 /** Maps a `transaction:included` scalar filter field to its raw-tx field + kind. */
 const txFields = {
     blockNumber: { field: 'blockNumber', kind: 'number' },
@@ -2253,13 +2434,7 @@ const txFields = {
     validBefore: { field: 'validBefore', kind: 'number' },
     value: { field: 'value', kind: 'number' },
 };
-/**
- * Scans included transactions over the confirmed window. Each block is fetched
- * with full transactions via `eth_getBlockByNumber(n, true)`; receipts are
- * fetched lazily (only when a `status`/`gasUsed`/`feePayer` filter needs them).
- * The delivered payload starts from `Transactions.humanizeTransaction`; the
- * poller then resolves its fee-token references.
- */
+/** Scans included transactions over one subscription's confirmed window. */
 async function scanTxs(options) {
     const { batchSize, cache, cursor, filters, maxBlocks, safeBlock } = options;
     const f = filters;
@@ -2267,54 +2442,33 @@ async function scanTxs(options) {
     if (!window)
         return { items: [], scannedThrough: undefined };
     const includeCalls = f.includeCalls ?? true;
-    const includeReceipt = f.includeReceipt ?? false;
-    // Filter-driven receipt need gates matching; `includeReceipt` only enriches the
-    // payload, so it never drops a row when the receipt is missing.
-    const needsReceipt = f.status !== undefined || f.gasUsed !== undefined || f.feePayer !== undefined;
     const items = [];
-    for (let n = window.from; n <= window.to; n++) {
-        const block = await cache.block(n);
-        const txs = Array.isArray(block['transactions']) ? block['transactions'] : [];
-        if (txs.length === 0)
-            continue;
-        const receipts = needsReceipt || includeReceipt ? await cache.receipts(n) : undefined;
+    for (let blockNumber = window.from; blockNumber <= window.to; blockNumber++) {
+        const block = await cache.block(blockNumber);
+        const transactions = Array.isArray(block['transactions'])
+            ? block['transactions']
+            : [];
         const timestamp = asString(block['timestamp']);
-        for (let i = 0; i < txs.length; i++) {
-            const tx = txs[i];
-            const index = Value.hexToNumber(tx['transactionIndex']) ?? i;
-            if (atOrBefore(n, index, window.skip))
-                continue;
-            const receipt = receipts?.get(String(tx['hash']).toLowerCase());
-            if (needsReceipt && !receipt)
+        for (let offset = 0; offset < transactions.length; offset++) {
+            const transaction = transactions[offset];
+            const transactionIndex = Value.hexToNumber(transaction['transactionIndex']) ?? offset;
+            if (atOrBefore(blockNumber, transactionIndex, window.skip))
                 continue;
-            if (!matchesTx(tx, f, includeCalls, receipt, timestamp, n))
+            if (!matchesTx(transaction, f, includeCalls, timestamp, blockNumber))
                 continue;
-            const parsed = Transactions.schema.Rpc.Transaction.safeParse(tx);
+            const parsed = Transactions.schema.Rpc.Transaction.safeParse(transaction);
             if (!parsed.success)
                 continue;
-            let data = Transactions.humanizeTransaction(parsed.data);
-            // Embed the humanized receipt under `meta.receipt`, matching the read
-            // endpoint's `include=receipt` shape so `data` stays a valid envelope.
-            if (includeReceipt && receipt) {
-                const r = Receipts.schema.Rpc.Receipt.safeParse(receipt);
-                if (r.success)
-                    data = {
-                        ...data,
-                        meta: {
-                            ...data['meta'],
-                            receipt: Receipts.humanizeReceipt(r.data),
-                        },
-                    };
-            }
-            items.push({ cursor: [n, index], data });
+            const data = Transactions.humanizeTransaction(parsed.data);
+            items.push({ cursor: [blockNumber, transactionIndex], data });
             if (items.length >= batchSize)
                 return { hasMore: true, items };
         }
     }
     return { items, scannedThrough: window.to };
 }
-/** Re-checks all transaction filters in JS against the raw RPC tx (+ receipt). */
-function matchesTx(tx, f, includeCalls, receipt, timestamp, blockNumber) {
+/** Re-checks transaction filters against the raw RPC transaction. */
+function matchesTx(tx, f, includeCalls, timestamp, blockNumber) {
     const from = tx['from'];
     const to = tx['to'];
     const calls = tx['calls'];
@@ -2351,18 +2505,6 @@ function matchesTx(tx, f, includeCalls, receipt, timestamp, blockNumber) {
     }
     if (f.timestamp !== undefined && !matchesOperator(timestamp, f.timestamp, 'number'))
         return false;
-    if (receipt) {
-        if (f.feePayer !== undefined && !matchesOperator(asString(receipt['feePayer']), f.feePayer))
-            return false;
-        if (f.gasUsed !== undefined &&
-            !matchesOperator(asString(receipt['gasUsed']), f.gasUsed, 'number'))
-            return false;
-        if (f.status !== undefined) {
-            const ok = Value.hexToNumber(receipt['status']) === 1;
-            if ((f.status === 'success') !== ok)
-                return false;
-        }
-    }
     return true;
 }
 /** Coerces an RPC field to a string for matching, or `undefined` when absent. */