tapimo 0.0.0 → 0.0.2

package/dist/apps/webhooks.js

@@ -0,0 +1,2112 @@
+import { Hono } from 'hono';
+import { parseAbiItem } from 'viem';
+import * as z from 'zod/mini';
+import * as Auth from '../internal/Auth.js';
+import * as Cache from '../internal/Cache.js';
+import * as Cursor from '../internal/Cursor.js';
+import * as OpenApi from '../internal/OpenApi.js';
+import * as Response from '../internal/Response.js';
+import * as Schema from '../internal/Schema.js';
+import * as Store from '../internal/Store.js';
+import * as Ttl from '../internal/Ttl.js';
+import * as Value from '../internal/Value.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 active subscriptions per owner, overridable via `webhook.maxPerOwner`. */
+const defaultMaxPerOwner = 100;
+/**
+ * Lifetime of an MPP-payer-owned subscription. A payer pays once, so the
+ * subscription is TTL-bounded (renewable by another paid create) to bound the
+ * paid-once / deliver-forever mismatch. API-key-owned subscriptions have no TTL.
+ */
+const mppTtlMs = 30 * 24 * 60 * 60 * 1_000;
+/**
+ * The subscribable webhook event types, in alphabetical order. The source of
+ * truth for the event-type *set*: the {@link EventType} union and the route zod
+ * enum ({@link schema.EventType}) both derive from this.
+ */
+export const eventTypes = [
+    'block:created',
+    'log:emitted',
+    'token:transfer',
+    'transaction:included',
+];
+/** Subscribable event types surfaced by `GET /webhooks/event-types`. */
+const eventTypeDescriptions = [
+    {
+        description: '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: 'Any contract event log, filtered by emitting address, event signature/topics, or decoded arguments.',
+        type: 'log:emitted',
+    },
+    {
+        description: 'TIP-20 token transfer event, such as a stablecoin payment sent or received.',
+        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.',
+        type: 'transaction:included',
+    },
+];
+/** Zod schemas owned by the webhooks resource. */
+export var schema;
+(function (schema) {
+    /** Subscribable event type. */
+    schema.EventType = z.enum(eventTypes).check(z.describe('Event type you can subscribe to.'));
+    /** Subscription lifecycle status. */
+    schema.Status = z
+        .enum(['active', 'disabled', 'paused'])
+        .check(z.describe('Current state of the webhook subscription.'), z.meta({ examples: ['active'] }));
+    const Filters = z.record(z.string(), z.unknown());
+    const chainIdResponse = z
+        .number()
+        .check(z.int(), z.positive(), z.describe('Tempo chain ID for this subscription.'), z.meta({ examples: [4217] }));
+    const Url = z
+        .url()
+        .check(z.describe('Your HTTPS endpoint where Tempo sends signed event POSTs.'), z.meta({ examples: ['https://example.com/webhooks'] }));
+    const SlackUrl = z
+        .url()
+        .check(z.describe('Your Slack incoming-webhook URL (`https://hooks.slack.com/services/…`).'), z.meta({ examples: ['https://hooks.slack.com/services/T000/B000/XXXXXXXX'] }));
+    const BetterstackUrl = z
+        .url()
+        .check(z.describe('Your Better Stack source ingest host URL (`https://<host>.betterstackdata.com`).'), z.meta({ examples: ['https://s1234567.eu-nbg-2.betterstackdata.com'] }));
+    const BetterstackToken = z
+        .string()
+        .check(z.minLength(1), z.describe('Your Better Stack source token (sent as `Authorization: Bearer …`).'), z.meta({ examples: ['FczKcxEhjEDE58dBX7XaeX1q'] }));
+    /**
+     * Where matched events are delivered: a `url` destination (a signed event POST
+     * to your HTTPS endpoint), a `slack` destination (a formatted message posted to
+     * your Slack incoming-webhook URL), or a `betterstack` destination (a structured
+     * log event POSTed to a Better Stack source with a bearer source token).
+     */
+    const Destination = z
+        .discriminatedUnion('type', [
+        z.object({
+            type: z.literal('url'),
+            url: Url,
+        }),
+        z.object({
+            type: z.literal('slack'),
+            url: SlackUrl,
+        }),
+        z.object({
+            token: BetterstackToken,
+            type: z.literal('betterstack'),
+            url: BetterstackUrl,
+        }),
+    ])
+        .check(z.describe('Delivery destination: an HTTPS URL, a Slack incoming-webhook URL, or a Better Stack source.'));
+    /**
+     * Equality / membership operator for a filterable field. A consumer can pass a
+     * bare value (shorthand for exact equality, the common case) or an operator
+     * object: `{ eq }` exact, `{ in: [...] }` OR-list, `{ not }` negation. Used for
+     * addresses, hashes, byte strings, enums, and raw topics. `in` lists are capped
+     * at 64 members so a single filter can't fan out into an unbounded SQL `IN`.
+     *
+     * @see {@link matchesOperator} for how it is evaluated.
+     */
+    schema.eq = (item) => z.union([
+        item,
+        z.strictObject({ eq: item }),
+        z.strictObject({ in: z.array(item).check(z.minLength(1), z.maxLength(64)) }),
+        z.strictObject({ not: item }),
+    ]);
+    /**
+     * Ordered-comparison operator for a numeric field (`value`, gas/fee fields,
+     * `nonce`, `blockNumber`, timestamps). A bare value is exact equality; the
+     * object form AND-combines any of `eq`/`gt`/`gte`/`lt`/`lte` to express ranges.
+     * Values are `0x`-hex quantities (the wire format), compiled to decimal in SQL.
+     */
+    schema.compare = z.union([
+        Schema.Quantity,
+        z
+            .strictObject({
+            eq: z.optional(Schema.Quantity),
+            gt: z.optional(Schema.Quantity),
+            gte: z.optional(Schema.Quantity),
+            lt: z.optional(Schema.Quantity),
+            lte: z.optional(Schema.Quantity),
+        })
+            .check(z.refine((c) => Object.keys(c).length > 0, { error: 'Comparison cannot be empty.' })),
+    ]);
+    /**
+     * Byte/calldata-matching operator for hex fields (tx `input`, `calls[].input`).
+     * `{ selector }` matches the first 4 bytes (the function selector, the cheap
+     * common case), `{ startsWith }` a hex prefix, `{ eq }` exact calldata.
+     */
+    schema.bytes = z.union([
+        z.strictObject({ selector: Schema.Hex }),
+        z.strictObject({ startsWith: Schema.Hex }),
+        z.strictObject({ eq: Schema.Hex }),
+    ]);
+    /**
+     * `transfer` subscription filters. The predicate fields are shared verbatim
+     * with `GET /transfers` via `Transfers.schema.Predicates`, so the two can't
+     * drift. All are optional and AND-combined; omit every field to subscribe to
+     * the full stream.
+     */
+    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.
+     *
+     * `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({
+        hash: z.optional(schema.eq(Schema.Hash).check(z.describe('Match this exact transaction hash (or any of several).'))),
+        address: z.optional(schema.eq(Schema.Address).check(z.describe('Match transactions where this address is the sender or recipient.'))),
+        from: z.optional(schema.eq(Schema.Address).check(z.describe('Match transactions whose sender (`from`) is this.'))),
+        to: z.optional(schema.eq(Schema.Address).check(z.describe('Match transactions sent to this address (root `to`; see `includeCalls`).'))),
+        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
+            .strictObject({
+            to: schema.eq(Schema.Address),
+        })
+            .check(z.describe('Match if ANY inner account-abstraction call targets this address (`calls[].to`).'))),
+        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.'))),
+        nonceKey: z.optional(schema.eq(Schema.Hex).check(z.describe('Match the nonce key (Tempo AA).'))),
+        validBefore: z.optional(schema.compare.check(z.describe('Match the `validBefore` bounds (unix s).'))),
+        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). */
+    const topic = Schema.Hash;
+    /**
+     * `log:emitted` subscription filters. Raw `topic0..3` map straight to the
+     * `logs` table; an optional human-readable ABI event `signature` is sugar that
+     * pins `topic0` and lets `args` match decoded (indexed **or** non-indexed)
+     * parameters by name. At least one predicate is required (no chain-wide
+     * firehose), and an addressless filter must still be selective — an event
+     * anchor (`signature`/`topic0`) plus at least one indexed topic or argument.
+     */
+    schema.LogFilters = z
+        .strictObject({
+        address: z.optional(schema.eq(Schema.Address).check(z.describe('Only match logs emitted by this contract address (or any of several).'), z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }))),
+        signature: z.optional(z.string().check(z.describe('Human-readable ABI event signature used to derive `topic0` and decode `args`, e.g. `event Transfer(address indexed from, address indexed to, uint256 value)`.'), z.meta({
+            examples: ['event Transfer(address indexed from, address indexed to, uint256 value)'],
+        }))),
+        topic0: z.optional(schema.eq(topic).check(z.describe('Event signature hash (topic 0). Mutually exclusive with `signature`.'), z.meta({
+            examples: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
+        }))),
+        topic1: z.optional(schema.eq(topic).check(z.describe('Raw indexed argument 1 (topic 1).'), z.meta({
+            examples: ['0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38'],
+        }))),
+        topic2: z.optional(schema.eq(topic).check(z.describe('Raw indexed argument 2 (topic 2).'), z.meta({
+            examples: ['0x0000000000000000000000009e39034aae71fb89f66061a2602eb6efec271754'],
+        }))),
+        topic3: z.optional(schema.eq(topic).check(z.describe('Raw indexed argument 3 (topic 3).'), z.meta({
+            examples: ['0x0000000000000000000000000000000000000000000000000000000000000000'],
+        }))),
+        args: z.optional(z
+            .record(z.string(), z.unknown())
+            .check(z.describe('Match decoded event arguments by name (indexed or non-indexed). Requires `signature`. Each value is an exact value or an operator object.'), z.meta({ examples: [{ to: '0x9e39034aae71fb89f66061a2602eb6efec271754' }] }))),
+        blockNumber: z.optional(schema.compare.check(z.describe('Only match logs within these block-number bounds.'))),
+    })
+        .check(z.describe('Filters that narrow which contract event logs trigger this webhook.'), z.meta({ title: 'Log filters' }), z.refine((f) => Object.keys(f).length > 0, {
+        error: 'At least one log filter is required.',
+    }), z.refine((f) => !(f.signature && f.topic0), {
+        error: 'Pass `signature` or `topic0`, not both.',
+    }), z.refine((f) => !f.args || f.signature, {
+        error: '`args` requires `signature` to decode the event.',
+    }), z.refine((f) => Boolean(f.address) ||
+        (Boolean(f.signature || f.topic0) && Boolean(f.topic1 || f.topic2 || f.topic3 || f.args)), {
+        error: 'Addressless log filters must include an event signature or topic0 plus at least one indexed topic or argument.',
+    }));
+    /**
+     * `block:created` subscription filters. All optional and AND-combined; unlike
+     * `log:emitted`, an empty filter is allowed — one row per block is a bounded,
+     * non-abusive heartbeat feed. Block-level metadata only (no transaction
+     * predicates; use `transaction:included` for those).
+     */
+    schema.BlockFilters = z
+        .strictObject({
+        number: z.optional(schema.compare.check(z.describe('Only match blocks within these block-number bounds.'))),
+        miner: z.optional(schema.eq(Schema.Address).check(z.describe('Only match blocks produced by this address (the miner/producer).'), z.meta({ examples: ['0x0000000000000000000000000000000000000000'] }))),
+        proposer: z.optional(schema.eq(Schema.Address).check(z.describe('Only match blocks proposed by this consensus proposer (when available).'))),
+        gasUsed: z.optional(schema.compare.check(z.describe('Only match blocks whose total gas used is within these bounds.'))),
+        gasLimit: z.optional(schema.compare.check(z.describe('Only match blocks whose gas limit is within these bounds.'))),
+        timestamp: z.optional(schema.compare.check(z.describe('Only match blocks whose unix timestamp (seconds) is within these bounds.'))),
+    })
+        .check(z.describe('Filters that narrow which new blocks trigger this webhook.'), z.meta({ title: 'Block filters' }));
+    /**
+     * Optional human context describing what a subscription is for. Surfaced by
+     * destinations (Slack header + description, Better Stack log fields) and echoed
+     * on every delivered event envelope.
+     */
+    schema.Context = z
+        .object({
+        description: z.optional(z
+            .string()
+            .check(z.maxLength(500), z.describe('Longer description of what this subscription is for.'), z.meta({ examples: ['Notify #ops when a large USDC transfer settles on mainnet.'] }))),
+        metadata: z.optional(z
+            .record(z.string().check(z.minLength(1), z.maxLength(64)), z.string().check(z.maxLength(500)))
+            .check(z.refine((m) => Object.keys(m).length <= 20, {
+            error: 'At most 20 metadata entries are allowed.',
+        }), z.describe('Arbitrary key/value labels echoed on every delivered event and rendered by destinations (Slack fields, Better Stack log fields). Keys are 1–64 chars, values ≤500 chars, ≤20 entries.'), z.meta({ examples: [{ env: 'prod', team: 'payments' }] }))),
+        title: z.optional(z
+            .string()
+            .check(z.maxLength(120), z.describe('Short label for this subscription.'), z.meta({ examples: ['Prod USDC large transfers'] }))),
+    })
+        .check(z.describe('Human context describing what this webhook subscription is for.'));
+    /**
+     * Public subscription representation. Never includes the signing `secret`
+     * (returned once by `POST /webhooks`) or the internal owner.
+     */
+    schema.Subscription = z
+        .object({
+        chainId: chainIdResponse,
+        context: z.optional(schema.Context),
+        createdAt: z.iso
+            .datetime()
+            .check(z.describe('When the subscription was created, as an ISO 8601 timestamp.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+        destination: Destination,
+        eventType: schema.EventType.check(z.meta({ examples: ['token:transfer'] })),
+        expiresAt: z
+            .optional(z.iso.datetime())
+            .check(z.describe('When the subscription expires, as an ISO 8601 timestamp. Only MPP-paid subscriptions expire.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+        failureCount: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Number of delivery failures in a row for this subscription.'), z.meta({ examples: [0] })),
+        filters: Filters.check(z.describe('Filters applied to this event type.'), z.meta({ examples: [{ address: '0x20c0000000000000000000008f5425160ebe5525' }] })),
+        id: z
+            .string()
+            .check(z.describe('Webhook subscription ID (`wh_…`).'), z.meta({ examples: ['wh_abc123'] })),
+        lastDeliveryAt: z
+            .optional(z.iso.datetime())
+            .check(z.describe('When Tempo last delivered an event successfully, as an ISO 8601 timestamp.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+        status: schema.Status.check(z.meta({ examples: ['active'] })),
+        updatedAt: z.iso
+            .datetime()
+            .check(z.describe('When the subscription was last changed, as an ISO 8601 timestamp.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+    })
+        .check(z.describe('A webhook subscription that tells Tempo which onchain events to send to your destination.'));
+    /** Outcome of a single delivery attempt. */
+    schema.DeliveryStatus = z
+        .enum(['failed', 'pending', 'succeeded'])
+        .check(z.describe('Outcome of a webhook delivery attempt.'), z.meta({ examples: ['succeeded'] }));
+    /** A logged delivery attempt for a subscription. */
+    schema.Delivery = z
+        .object({
+        attempt: z
+            .number()
+            .check(z.int(), z.positive(), z.describe('Retry attempt number for this delivery, starting at 1.'), z.meta({ examples: [1] })),
+        createdAt: z.iso
+            .datetime()
+            .check(z.describe('When this delivery attempt was created, as an ISO 8601 timestamp.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+        error: z
+            .optional(z.string())
+            .check(z.describe('Why delivery failed, present when `status` is `failed`.'), z.meta({ examples: ['Connection timed out'] })),
+        eventId: z
+            .string()
+            .check(z.describe('Stable event ID (`evt_…`) you can use to dedupe webhook deliveries.'), z.meta({ examples: ['evt_abc123'] })),
+        id: z
+            .string()
+            .check(z.describe('Webhook delivery ID (`whd_…`).'), z.meta({ examples: ['whd_abc123'] })),
+        requestUrl: z
+            .string()
+            .check(z.describe('Your callback URL that Tempo attempted to deliver to.'), z.meta({ examples: ['https://example.com/webhooks'] })),
+        responseMs: z
+            .optional(z.number().check(z.int(), z.nonnegative()))
+            .check(z.describe('How long the delivery attempt took in milliseconds, when Tempo made a request.'), z.meta({ examples: [12] })),
+        responseStatus: z
+            .optional(z.number().check(z.int()))
+            .check(z.describe('HTTP status your endpoint returned, when Tempo received a response.'), z.meta({ examples: [200] })),
+        status: schema.DeliveryStatus.check(z.meta({ examples: ['succeeded'] })),
+        subscriptionId: z
+            .string()
+            .check(z.describe('Subscription ID (`wh_…`) this delivery belongs to.'), z.meta({ examples: ['wh_abc123'] })),
+    })
+        .check(z.describe('One attempt by Tempo to deliver an event to your webhook URL.'));
+    /**
+     * A `transfer` event payload: the decoded TIP-20 `Transfer` row. Mirrors a
+     * `GET /transfers` row but without the `sourceToken` metadata enrichment the
+     * read endpoint adds (webhook delivery does not perform per-event token
+     * lookups).
+     */
+    schema.TransferEvent = z
+        .object({
+        address: Schema.TokenAddress.check(z.describe('TIP-20 token contract address.'), z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] })),
+        amount: z
+            .string()
+            .check(z.describe('Amount transferred, as a decimal integer string in the token base unit.'), z.meta({ examples: ['10000'] })),
+        blockNumber: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Block number where this transfer was included.'), z.meta({ examples: [1000002] })),
+        recipient: Schema.Address.check(z.describe('Address that received the transfer.'), z.meta({ examples: ['0x9e39034aae71fb89f66061a2602eb6efec271754'] })),
+        sender: Schema.Address.check(z.describe('Address that sent the transfer.'), z.meta({ examples: ['0xe7687128b0a808c2831ff94d4f7b2fb35c65af38'] })),
+        timestamp: z.iso
+            .datetime()
+            .check(z.describe('Block timestamp as an ISO 8601 string.'), z.meta({ examples: ['2026-01-14T18:38:03.000Z'] })),
+        token: z.optional(z
+            .object({
+            decimals: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Number of decimals the token uses.'), z.meta({ examples: [6] })),
+            symbol: z
+                .string()
+                .check(z.describe('Token symbol (e.g. `USDC`).'), z.meta({ examples: ['USDC'] })),
+        })
+            .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.'))),
+        transactionHash: Schema.Hash.check(z.describe('Transaction hash that contains this transfer.'), z.meta({
+            examples: ['0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3'],
+        })),
+    })
+        .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).
+     */
+    schema.TransactionEvent = Transactions.schema.getTransaction.Response;
+    /**
+     * A `log:emitted` event payload: the raw contract event log. When a
+     * `signature` filter was supplied and decoding succeeds, the best-effort
+     * `event`/`args` fields carry the decoded event name and arguments (large
+     * integers as decimal strings).
+     */
+    schema.LogEvent = z
+        .object({
+        address: Schema.Address.check(z.describe('Contract that emitted the log.'), z.meta({ examples: ['0x20c00000000000000000000071de0cd31ab0d105'] })),
+        args: z.optional(z
+            .record(z.string(), z.unknown())
+            .check(z.describe('Decoded event arguments, present only when a `signature` filter was supplied and decoding succeeded.'), z.meta({ examples: [{ from: '0xe768…', to: '0x9e39…', value: '10000' }] }))),
+        blockNumber: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Block number the log was included in.'), z.meta({ examples: [1000002] })),
+        data: Schema.Hex.check(z.describe('Unindexed log data (ABI-encoded).'), z.meta({
+            examples: ['0x0000000000000000000000000000000000000000000000000000000000002710'],
+        })),
+        event: z.optional(z
+            .object({
+            name: z
+                .string()
+                .check(z.describe('Decoded event name.'), z.meta({ examples: ['Transfer'] })),
+            signature: z.string().check(z.describe('Human-readable event signature used to decode the log.'), z.meta({
+                examples: [
+                    'event Transfer(address indexed from, address indexed to, uint256 value)',
+                ],
+            })),
+            topic0: Schema.Hash.check(z.describe('Event signature hash (topic 0).'), z.meta({
+                examples: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
+            })),
+        })
+            .check(z.describe('Decoded event identity, present only when a `signature` filter was supplied.'))),
+        logIndex: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Index of the log within its block.'), z.meta({ examples: [0] })),
+        timestamp: z.iso
+            .datetime()
+            .check(z.describe('When the block was produced, as an ISO 8601 timestamp.'), z.meta({ examples: ['2026-01-14T18:38:03.000Z'] })),
+        topics: z.array(Schema.Hash).check(z.describe('Log topics, starting with the event signature hash (topic 0).'), z.meta({
+            examples: [
+                [
+                    '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
+                    '0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38',
+                ],
+            ],
+        })),
+        transactionHash: Schema.Hash.check(z.describe('Hash of the transaction that emitted the log.'), z.meta({
+            examples: ['0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3'],
+        })),
+        transactionIndex: z
+            .number()
+            .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). */
+    schema.BlockEvent = z
+        .object({
+        number: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Block height, starting from genesis block 0.'), z.meta({ examples: [1000002] })),
+        hash: Schema.Hash.check(z.describe('Hash that identifies this block.'), z.meta({
+            examples: ['0x3fe7d9e595f3d8215ec840c6ef55ac0bead58933e96fc2ead0f2aaf79715f45d'],
+        })),
+        parentHash: Schema.Hash.check(z.describe('Hash of the previous block in the chain.'), z.meta({
+            examples: ['0xa406dff9c51cc2abbef3a811f0499e99a568bf781019f129ab45dca1df0e43e5'],
+        })),
+        miner: Schema.Address.check(z.describe('Address of the block producer (miner/proposer).'), z.meta({ examples: ['0x0000000000000000000000000000000000000000'] })),
+        proposer: z.optional(Schema.Address.check(z.describe('Consensus proposer of the block, when the chain records one.'), z.meta({ examples: ['0x0000000000000000000000000000000000000000'] }))),
+        gasUsed: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Total gas used by every transaction in this block.'), z.meta({ examples: [4340281] })),
+        gasLimit: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Maximum gas available for all transactions in this block.'), z.meta({ examples: [500000000] })),
+        transactionCount: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Number of transactions included in this block.'), z.meta({ examples: [3] })),
+        timestamp: z.iso
+            .datetime()
+            .check(z.describe('When the block was produced, as an ISO 8601 timestamp.'), z.meta({ examples: ['2026-01-14T18:38:03.000Z'] })),
+    })
+        .check(z.describe('Payload for a `block:created` event (a new block header).'));
+    /** A `ping` (synthetic test-delivery) payload, sent by `POST /webhooks/:id/ping`. */
+    schema.PingEvent = z
+        .object({
+        ping: z.literal(true).check(z.describe('Marks this payload as a synthetic ping test.')),
+    })
+        .check(z.describe('Payload for a webhook ping test delivery.'));
+    /** Fields common to every delivery envelope. */
+    const envelopeBase = {
+        chainId: Schema.ChainId,
+        context: z.optional(schema.Context),
+        createdAt: z.iso
+            .datetime()
+            .check(z.describe('When Tempo built this delivery envelope, as an ISO 8601 timestamp.'), z.meta({ examples: ['2026-01-14T18:38:03.000Z'] })),
+        id: z
+            .string()
+            .check(z.describe('Stable event ID (`evt_…`) for this delivery. Store it and ignore duplicates.'), z.meta({ examples: ['evt_abc123'] })),
+        subscriptionId: z
+            .string()
+            .check(z.describe('Subscription ID (`wh_…`) that produced this delivery.'), z.meta({ examples: ['wh_abc123'] })),
+    };
+    /**
+     * The signed JSON body POSTed to subscriber URLs, discriminated by `type`. The
+     * `tempo-event-type` header mirrors `type`. Event variants carry the matched
+     * event row; `ping` is a synthetic test delivery.
+     *
+     * Each variant carries a `title` so doc renderers (Scalar) show a labelled
+     * variant selector — without per-variant titles, inline `oneOf` members render
+     * as a single (first) collapsed schema.
+     */
+    schema.Envelope = z
+        .discriminatedUnion('type', [
+        z
+            .object({ ...envelopeBase, data: schema.TransferEvent, type: z.literal('token:transfer') })
+            .check(z.meta({ title: 'Transfer event' })),
+        z
+            .object({
+            ...envelopeBase,
+            data: schema.TransactionEvent,
+            type: z.literal('transaction:included'),
+        })
+            .check(z.meta({ title: 'Included transaction event' })),
+        z
+            .object({ ...envelopeBase, data: schema.LogEvent, type: z.literal('log:emitted') })
+            .check(z.meta({ title: 'Log event' })),
+        z
+            .object({ ...envelopeBase, data: schema.BlockEvent, type: z.literal('block:created') })
+            .check(z.meta({ title: 'Block event' })),
+        z
+            .object({ ...envelopeBase, data: schema.PingEvent, type: z.literal('ping') })
+            .check(z.meta({ title: 'Ping (test delivery)' })),
+    ])
+        .check(z.describe('The signed JSON payload Tempo POSTs to your webhook URL.'));
+    /** Schemas for the getWebhookEventTypes operation. */
+    let getWebhookEventTypes;
+    (function (getWebhookEventTypes) {
+        getWebhookEventTypes.Response = z
+            .object({
+            data: z
+                .array(z.object({
+                description: z
+                    .string()
+                    .check(z.describe('Plain-English description of the event type.'), z.meta({ examples: ['TIP-20 token transfer event.'] })),
+                type: schema.EventType.check(z.meta({ examples: ['token:transfer'] })),
+            }))
+                .check(z.describe('Webhook event types available for subscription.')),
+        })
+            .check(z.describe('List of webhook event types Tempo can send.'));
+    })(getWebhookEventTypes = schema.getWebhookEventTypes || (schema.getWebhookEventTypes = {}));
+    /** Schemas for the createWebhook operation. */
+    let createWebhook;
+    (function (createWebhook) {
+        /**
+         * Discriminated on `eventType` so each variant carries its own typed
+         * `filters` object — this is what lets the docs render the valid filter
+         * fields per event type instead of an opaque map. Variant `title`s drive the
+         * doc renderer's selector (see {@link schema.Envelope}).
+         */
+        createWebhook.Body = z
+            .discriminatedUnion('eventType', [
+            z
+                .object({
+                chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+                context: z.optional(schema.Context),
+                destination: Destination,
+                eventType: z
+                    .literal('token:transfer')
+                    .check(z.describe('Event type you want Tempo to send to your webhook URL.'), z.meta({ examples: ['token:transfer'] })),
+                filters: z.optional(schema.TransferFilters),
+            })
+                .check(z.meta({ title: 'Transfer subscription' })),
+            z
+                .object({
+                chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+                context: z.optional(schema.Context),
+                destination: Destination,
+                eventType: z
+                    .literal('transaction:included')
+                    .check(z.describe('Event type you want Tempo to send to your webhook URL.'), z.meta({ examples: ['transaction:included'] })),
+                filters: z.optional(schema.TxFilters),
+            })
+                .check(z.meta({ title: 'Included-transaction subscription' })),
+            z
+                .object({
+                chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+                context: z.optional(schema.Context),
+                destination: Destination,
+                eventType: z
+                    .literal('log:emitted')
+                    .check(z.describe('Event type you want Tempo to send to your webhook URL.'), z.meta({ examples: ['log:emitted'] })),
+                filters: schema.LogFilters,
+            })
+                .check(z.meta({ title: 'Log subscription' })),
+            z
+                .object({
+                chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+                context: z.optional(schema.Context),
+                destination: Destination,
+                eventType: z
+                    .literal('block:created')
+                    .check(z.describe('Event type you want Tempo to send to your webhook URL.'), z.meta({ examples: ['block:created'] })),
+                filters: z.optional(schema.BlockFilters),
+            })
+                .check(z.meta({ title: 'Block subscription' })),
+        ])
+            .check(z.describe('Details for creating a webhook subscription.'));
+        createWebhook.Response = z
+            .extend(schema.Subscription, {
+            secret: z
+                .string()
+                .check(z.describe('HMAC signing secret (`whsec_…`) used to verify Tempo webhook signatures. It is shown once when you create the webhook, so store it now.'), z.meta({ examples: ['whsec_abc123'] })),
+        })
+            .check(z.describe('The new webhook subscription, including the one-time signing secret.'));
+    })(createWebhook = schema.createWebhook || (schema.createWebhook = {}));
+    /** Schemas for the listWebhooks operation. */
+    let listWebhooks;
+    (function (listWebhooks) {
+        listWebhooks.Query = z
+            .object({
+            cursor: Schema.Cursor,
+            include: Schema.totalCountInclude,
+            limit: Schema.Limit,
+            page: Schema.Page,
+        })
+            .check(...Schema.pageChecks(), z.describe('Query parameters for listing your webhook subscriptions.'));
+        listWebhooks.Response = z
+            .object({
+            data: z.array(schema.Subscription).check(z.describe('Webhook subscriptions on this page.')),
+            meta: z
+                .optional(Schema.CountMeta)
+                .check(z.describe('Extra response metadata requested with `include`.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A page of your webhook subscriptions.'));
+    })(listWebhooks = schema.listWebhooks || (schema.listWebhooks = {}));
+    /** Schemas for the getWebhook operation. */
+    let getWebhook;
+    (function (getWebhook) {
+        getWebhook.Params = z
+            .object({
+            id: z
+                .string()
+                .check(z.describe('Webhook subscription ID (`wh_…`).'), z.meta({ examples: ['wh_001718668800000_V1StGXR8Z5jdHi6B2myTq'] })),
+        })
+            .check(z.describe('Path parameters for a webhook subscription request.'));
+        getWebhook.Response = schema.Subscription;
+    })(getWebhook = schema.getWebhook || (schema.getWebhook = {}));
+    /** Schemas for the listWebhookDeliveries operation. */
+    let listWebhookDeliveries;
+    (function (listWebhookDeliveries) {
+        listWebhookDeliveries.Params = getWebhook.Params;
+        listWebhookDeliveries.Query = z
+            .object({
+            cursor: Schema.Cursor,
+            include: Schema.totalCountInclude,
+            limit: Schema.Limit,
+            page: Schema.Page,
+        })
+            .check(...Schema.pageChecks(), z.describe('Query parameters for listing webhook delivery attempts.'));
+        listWebhookDeliveries.Response = z
+            .object({
+            data: z.array(schema.Delivery).check(z.describe('Webhook delivery attempts on this page.')),
+            meta: z
+                .optional(Schema.CountMeta)
+                .check(z.describe('Extra response metadata requested with `include`.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A page of webhook delivery attempts.'));
+    })(listWebhookDeliveries = schema.listWebhookDeliveries || (schema.listWebhookDeliveries = {}));
+    /** Schemas for the pingWebhook operation. */
+    let pingWebhook;
+    (function (pingWebhook) {
+        pingWebhook.Params = getWebhook.Params;
+        pingWebhook.Response = z
+            .object({
+            delivered: z
+                .boolean()
+                .check(z.describe('Whether your endpoint returned a 2xx response.'), z.meta({ examples: [true] })),
+            error: z
+                .optional(z.string())
+                .check(z.describe('Why the delivery failed, present when `delivered` is `false`.'), z.meta({ examples: ['Connection timed out'] })),
+            eventId: z
+                .string()
+                .check(z.describe('Synthetic event ID (`evt_…`) Tempo sent for this ping.'), z.meta({ examples: ['evt_abc123'] })),
+            responseMs: z
+                .optional(z.number().check(z.int(), z.nonnegative()))
+                .check(z.describe('Round-trip delivery time in milliseconds, when the request completed.'), z.meta({ examples: [12] })),
+            responseStatus: z
+                .optional(z.number().check(z.int()))
+                .check(z.describe('HTTP status your endpoint returned, when Tempo received a response.'), z.meta({ examples: [200] })),
+        })
+            .check(z.describe('Result of sending a synthetic ping event to your webhook URL.'));
+    })(pingWebhook = schema.pingWebhook || (schema.pingWebhook = {}));
+    /** Schemas for the retryWebhookDelivery operation. */
+    let retryWebhookDelivery;
+    (function (retryWebhookDelivery) {
+        retryWebhookDelivery.Params = z
+            .object({
+            deliveryId: z
+                .string()
+                .check(z.describe('Delivery ID (`whd_…`) you want Tempo to replay.'), z.meta({ examples: ['whd_001718668800000_8oQ2pVmZ4kKxWnLcRfTbN'] })),
+            id: z
+                .string()
+                .check(z.describe('Webhook subscription ID (`wh_…`).'), z.meta({ examples: ['wh_001718668800000_V1StGXR8Z5jdHi6B2myTq'] })),
+        })
+            .check(z.describe('Path parameters for retrying a webhook delivery.'));
+        retryWebhookDelivery.Response = pingWebhook.Response;
+    })(retryWebhookDelivery = schema.retryWebhookDelivery || (schema.retryWebhookDelivery = {}));
+    /** Schemas for the updateWebhook operation. */
+    let updateWebhook;
+    (function (updateWebhook) {
+        updateWebhook.Params = getWebhook.Params;
+        updateWebhook.Body = z
+            .object({
+            context: z
+                .optional(z.nullable(schema.Context))
+                .check(z.describe('New human context, or `null` to clear it.')),
+            destination: z
+                .optional(Destination)
+                .check(z.describe('New delivery destination for future events (URL or Slack channel).')),
+            filters: z
+                .optional(Filters)
+                .check(z.describe('New filters to apply to future webhook events.'), z.meta({ examples: [{ address: '0x20c0000000000000000000008f5425160ebe5525' }] })),
+            status: z
+                .optional(schema.Status)
+                .check(z.describe('New lifecycle status, such as pausing or resuming delivery.')),
+        })
+            .check(z.describe('Fields you want to update on the webhook subscription.'));
+        updateWebhook.Response = schema.Subscription;
+    })(updateWebhook = schema.updateWebhook || (schema.updateWebhook = {}));
+    /** Schemas for the deleteWebhook operation. */
+    let deleteWebhook;
+    (function (deleteWebhook) {
+        deleteWebhook.Params = getWebhook.Params;
+        deleteWebhook.Response = z
+            .object({
+            id: z
+                .string()
+                .check(z.describe('ID of the webhook subscription that was deleted.'), z.meta({ examples: ['wh_abc123'] })),
+        })
+            .check(z.describe('Confirmation that the webhook subscription was deleted.'));
+    })(deleteWebhook = schema.deleteWebhook || (schema.deleteWebhook = {}));
+})(schema || (schema = {}));
+/**
+ * Creates the webhooks resource. The subscription surface is non-public and
+ * API-key-only for now (MPP paid access is disabled) and never edge-cached; only
+ * `GET /webhooks/event-types` is public catalog data. Routes are always mounted
+ * but return `404` when no state `webhook.store` is configured, and are hidden
+ * from the OpenAPI document in that case.
+ */
+export function webhooks(options = {}) {
+    const hidden = !options.enabled;
+    return (new Hono()
+        .use('*', async (c, next) => {
+        // Gate the whole resource on a configured state store. Without it the
+        // outbound-HTTP surface is disabled (read-only deployment).
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        await next();
+        // Subscriptions are principal-scoped, mutating, and stateful: never cache.
+        if (!c.res.headers.has('Cache-Control'))
+            c.res.headers.set('Cache-Control', 'no-store');
+        return;
+    })
+        .get('/event-types', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.describeRoute({
+        description: 'See which onchain event types Tempo can POST to your webhook URL.',
+        hide: hidden,
+        operationId: 'getWebhookEventTypes',
+        responses: OpenApi.responses({
+            success: {
+                description: 'Webhook event types available for subscription.',
+                schema: schema.getWebhookEventTypes.Response,
+            },
+        }),
+        summary: 'List webhook event types',
+        tags: ['Webhooks'],
+    }), Cache.response({
+        cacheControl: Cache.policies.stable,
+        name: 'tempo-api:webhooks:v1',
+        key: (c) => {
+            const url = new URL(c.req.url);
+            url.search = '';
+            return url.toString();
+        },
+    }), (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        return c.json(Response.validated(schema.getWebhookEventTypes.Response, {
+            data: eventTypeDescriptions.map((eventType) => ({ ...eventType })),
+        }), 200);
+    })
+        .post('/', Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }), OpenApi.validate('json', schema.createWebhook.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Create a webhook subscription so Tempo can POST signed onchain events to your URL. The signing secret is shown only once, and each call creates a separate subscription.',
+        hide: hidden,
+        operationId: 'createWebhook',
+        responses: OpenApi.responses({
+            errors: { 403: 'You have reached the webhook subscription limit.' },
+            success: {
+                description: 'The created webhook subscription, including the one-time signing secret.',
+                schema: schema.createWebhook.Response,
+            },
+        }),
+        summary: 'Create webhook',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'body_invalid',
+                message: 'Check the request body and try again.',
+            });
+        const webhook = c.get('webhook');
+        const store = webhook.store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(c);
+        const body = c.req.valid('json');
+        const chainId = body.chainId ?? c.get('chainId');
+        try {
+            const subscription = await Webhooks.createSubscription(store, {
+                chainId,
+                ...(body.context === undefined ? {} : { context: body.context }),
+                destination: body.destination,
+                eventType: body.eventType,
+                filters: body.filters,
+                owner,
+                ...(owner.type === 'mpp' ? { ttl: mppTtlMs } : {}),
+            }, { maxPerOwner: webhook.maxPerOwner ?? defaultMaxPerOwner });
+            return c.json(Response.validated(schema.createWebhook.Response, toCreated(subscription)), 200);
+        }
+        catch (cause) {
+            return mutationError(c, cause);
+        }
+    })
+        .get('/', Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }), OpenApi.validate('query', schema.listWebhooks.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'List your webhook subscriptions.',
+        hide: hidden,
+        operationId: 'listWebhooks',
+        responses: OpenApi.responses({
+            success: {
+                description: 'A page of webhook subscriptions.',
+                schema: schema.listWebhooks.Response,
+            },
+        }),
+        summary: 'List webhooks',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Check the query parameters and try again.',
+            });
+        const store = c.get('webhook').store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(c);
+        const { cursor, include, limit, page } = c.req.valid('query');
+        try {
+            // `totalCount` is opt-in and exact (the per-owner set is bounded);
+            // 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(store, owner).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(store, owner, {
+                cursor,
+                limit: limit + 1,
+                offset: page !== undefined && page > 1 ? (page - 1) * limit : undefined,
+            });
+            const hasMore = rows.length > limit;
+            const data = (hasMore ? rows.slice(0, limit) : rows).map(toPublic);
+            const nextCursor = hasMore ? (data[data.length - 1]?.id ?? null) : null;
+            const totalCount = countPromise ? await countPromise : undefined;
+            return c.json(Response.validated(schema.listWebhooks.Response, {
+                data,
+                ...(totalCount !== undefined
+                    ? { meta: { totalCountCapped: false, totalCount } }
+                    : {}),
+                nextCursor,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        // The `:id` param is constrained to the `wh_…` id shape so it can't also
+        // match the sibling static route `GET /webhooks/event-types`. Without the
+        // constraint, this API-key-only route's policy would be collected for the
+        // event-types request and override its (intentionally public) access.
+        .get('/:id{wh_[A-Za-z0-9_-]+}', Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }), OpenApi.validate('param', schema.getWebhook.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Get one webhook subscription by its ID.',
+        hide: hidden,
+        operationId: 'getWebhook',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No webhook subscription was found for that ID.',
+                    codes: ['webhook_not_found'],
+                },
+            },
+            success: {
+                description: 'The requested webhook subscription.',
+                schema: schema.getWebhook.Response,
+            },
+        }),
+        summary: 'Get webhook',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'param_invalid',
+                message: 'Check the path parameters and try again.',
+            });
+        const store = c.get('webhook').store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(c);
+        const { id } = c.req.valid('param');
+        try {
+            const subscription = await Webhooks.getSubscription(store, owner, id);
+            if (!subscription)
+                return notFound(c);
+            return c.json(Response.validated(schema.getWebhook.Response, toPublic(subscription)), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/:id{wh_[A-Za-z0-9_-]+}/deliveries', Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }), OpenApi.validate('param', schema.listWebhookDeliveries.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+    }), OpenApi.validate('query', schema.listWebhookDeliveries.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'List delivery attempts for a webhook subscription.',
+        hide: hidden,
+        operationId: 'listWebhookDeliveries',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No webhook subscription was found for that ID.',
+                    codes: ['webhook_not_found'],
+                },
+            },
+            success: {
+                description: 'A newest-first page of webhook delivery attempts.',
+                schema: schema.listWebhookDeliveries.Response,
+            },
+        }),
+        summary: 'List webhook deliveries',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'param_invalid',
+                message: 'Check the path parameters and try again.',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Check the query parameters and try again.',
+            });
+        const store = c.get('webhook').store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(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(store, owner, id);
+            if (!subscription)
+                return notFound(c);
+            // `totalCount` is opt-in and exact (the delivery log is TTL-bounded);
+            // run it concurrently with the page list. Best-effort: a failure
+            // omits `meta` rather than failing the page.
+            const countPromise = include.includes('totalCount')
+                ? Webhooks.countDeliveries(store, id).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.listDeliveries(store, id, {
+                cursor,
+                limit: limit + 1,
+                offset: page !== undefined && page > 1 ? (page - 1) * limit : undefined,
+            });
+            const hasMore = rows.length > limit;
+            const data = hasMore ? rows.slice(0, limit) : rows;
+            const nextCursor = hasMore ? (data[data.length - 1]?.id ?? null) : null;
+            const totalCount = countPromise ? await countPromise : undefined;
+            return c.json(Response.validated(schema.listWebhookDeliveries.Response, {
+                data,
+                ...(totalCount !== undefined
+                    ? { meta: { totalCountCapped: false, totalCount } }
+                    : {}),
+                nextCursor,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .post('/:id{wh_[A-Za-z0-9_-]+}/ping', Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }), OpenApi.validate('param', schema.pingWebhook.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Send a signed `ping` event to your webhook URL to test delivery and signature verification.',
+        hide: hidden,
+        operationId: 'pingWebhook',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No webhook subscription was found for that ID.',
+                    codes: ['webhook_not_found'],
+                },
+            },
+            success: {
+                description: 'Result of the synthetic ping delivery.',
+                schema: schema.pingWebhook.Response,
+            },
+        }),
+        summary: 'Ping webhook',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'param_invalid',
+                message: 'Check the path parameters and try again.',
+            });
+        const store = c.get('webhook').store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(c);
+        const { id } = c.req.valid('param');
+        try {
+            // Owner-scope first so unowned/unknown ids are indistinguishable (404).
+            const subscription = await Webhooks.getSubscription(store, owner, id);
+            if (!subscription)
+                return notFound(c);
+            // Inline delivery (not the queue) so the caller gets an immediate
+            // result. `ping` never mutates the subscription's failure/lifecycle
+            // state — a test must not disable a healthy endpoint.
+            const { envelope, result } = await Webhooks.ping(store, subscription);
+            return c.json(Response.validated(schema.pingWebhook.Response, {
+                delivered: result.ok,
+                eventId: envelope.id,
+                ...(result.error === undefined ? {} : { error: result.error }),
+                ...(result.durationMs === undefined ? {} : { responseMs: result.durationMs }),
+                ...(result.status === undefined ? {} : { responseStatus: result.status }),
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .post('/:id{wh_[A-Za-z0-9_-]+}/deliveries/:deliveryId/retry', Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }), OpenApi.validate('param', schema.retryWebhookDelivery.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Replay a previous webhook delivery and update the delivery result.',
+        hide: hidden,
+        operationId: 'retryWebhookDelivery',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No webhook subscription or delivery was found for those IDs.',
+                    codes: ['webhook_not_found', 'delivery_not_found'],
+                },
+            },
+            success: {
+                description: 'Result of replaying the webhook delivery.',
+                schema: schema.retryWebhookDelivery.Response,
+            },
+        }),
+        summary: 'Retry webhook delivery',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'param_invalid',
+                message: 'Check the path parameters and try again.',
+            });
+        const store = c.get('webhook').store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(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(store, owner, id);
+            if (!subscription)
+                return notFound(c);
+            const delivery = await Webhooks.getDelivery(store, id, deliveryId);
+            if (!delivery)
+                return Response.error(c, {
+                    code: 'delivery_not_found',
+                    message: 'Delivery not found',
+                    status: 404,
+                });
+            // Replay the exact persisted envelope inline. Unlike `ping`, this is a
+            // real event, so the outcome updates the subscription's failure state.
+            const result = await Webhooks.deliverAndRecord(store, subscription, delivery.envelope);
+            return c.json(Response.validated(schema.retryWebhookDelivery.Response, {
+                delivered: result.ok,
+                eventId: delivery.envelope.id,
+                ...(result.error === undefined ? {} : { error: result.error }),
+                ...(result.durationMs === undefined ? {} : { responseMs: result.durationMs }),
+                ...(result.status === undefined ? {} : { responseStatus: result.status }),
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .patch('/:id{wh_[A-Za-z0-9_-]+}', Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }), OpenApi.validate('param', schema.updateWebhook.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+    }), OpenApi.validate('json', schema.updateWebhook.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Update a webhook subscription URL, filters, or delivery status.',
+        hide: hidden,
+        operationId: 'updateWebhook',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No webhook subscription was found for that ID.',
+                    codes: ['webhook_not_found'],
+                },
+            },
+            success: {
+                description: 'The updated webhook subscription.',
+                schema: schema.updateWebhook.Response,
+            },
+        }),
+        summary: 'Update webhook',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'param_invalid',
+                message: 'Check the path parameters and try again.',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'body_invalid',
+                message: 'Check the request body and try again.',
+            });
+        const store = c.get('webhook').store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(c);
+        const { id } = c.req.valid('param');
+        const patch = c.req.valid('json');
+        try {
+            // The PATCH body accepts an opaque `filters` map (it can't know the
+            // subscription's event type up front), so revalidate the incoming
+            // filters against the stored `eventType` and fail closed before
+            // persisting — otherwise a bad filter would silently widen the match
+            // set at scan time.
+            if (patch.filters !== undefined) {
+                const existing = await Webhooks.getSubscription(store, owner, id);
+                if (!existing)
+                    return notFound(c);
+                parseFilters(existing.eventType, patch.filters);
+            }
+            const subscription = await Webhooks.updateSubscription(store, owner, id, patch);
+            if (!subscription)
+                return notFound(c);
+            return c.json(Response.validated(schema.updateWebhook.Response, toPublic(subscription)), 200);
+        }
+        catch (cause) {
+            return mutationError(c, cause);
+        }
+    })
+        .delete('/:id{wh_[A-Za-z0-9_-]+}', Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }), OpenApi.validate('param', schema.deleteWebhook.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Delete a webhook subscription and stop future deliveries immediately.',
+        hide: hidden,
+        operationId: 'deleteWebhook',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No webhook subscription was found for that ID.',
+                    codes: ['webhook_not_found'],
+                },
+            },
+            success: {
+                description: 'Confirmation that the webhook subscription was deleted.',
+                schema: schema.deleteWebhook.Response,
+            },
+        }),
+        summary: 'Delete webhook',
+        tags: ['Webhooks'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (!c.get('webhook'))
+            return notEnabled(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'param_invalid',
+                message: 'Check the path parameters and try again.',
+            });
+        const store = c.get('webhook').store;
+        const owner = ownerFor(c);
+        if (!owner)
+            return unauthorized(c);
+        const { id } = c.req.valid('param');
+        try {
+            const deleted = await Webhooks.deleteSubscription(store, owner, id);
+            if (!deleted)
+                return notFound(c);
+            return c.json(Response.validated(schema.deleteWebhook.Response, { id }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    }));
+}
+/**
+ * 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;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export async function poll(options) {
+    const { batchSize = 100, chainId, client, confirmations = 2, eventTypes = ['token:transfer', 'transaction:included', 'log:emitted', 'block:created'], maxBlocks = 1_000, store, tidx, } = options;
+    const now = options.now ?? (() => new Date());
+    // 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(store, 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 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);
+    // 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 result = {
+        chainId,
+        dispatched: 0,
+        failed: 0,
+        safeBlock: rpcSafeBlock,
+        scanned: 0,
+        subscriptions: 0,
+    };
+    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(store, chainId, eventType);
+        for (const subscription of subscriptions) {
+            result.subscriptions++;
+            const cursor = await Webhooks.getCursor(store, subscription.id);
+            if (cursor === null) {
+                // First time we've seen this subscription: anchor it at the head of the
+                // confirmed window so we never backfill from genesis. Events start
+                // flowing from the next tick onward.
+                await Webhooks.setCursor(store, subscription.id, Cursor.encode([safeBlock, endOfBlockIndex]));
+                continue;
+            }
+            const page = await scanSubscription({
+                batchSize,
+                cache,
+                client,
+                cursor,
+                maxBlocks,
+                safeBlock,
+                subscription,
+                tidx,
+            });
+            result.scanned += page.items.length;
+            let accepted;
+            let failed = false;
+            for (const item of page.items) {
+                // Enrich `token:transfer` rows with best-effort token metadata so
+                // downstream destinations (Slack human amounts, richer `url`/`betterstack`
+                // payloads) can render `amount` in token units. Non-fatal on failure.
+                const data = eventType === 'token:transfer'
+                    ? await withTokenMetadata(item.data, { chainId, client, store })
+                    : 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;
+                }
+                accepted = item.cursor;
+                result.dispatched++;
+            }
+            // Advance the high-water mark. On a dispatch failure, stop at the last
+            // accepted row so the failed one retries next tick. Otherwise: window
+            // scanners jump to the end of the fully-scanned range (even with zero
+            // matches); keyset scanners advance past the last dispatched row, or — on
+            // a complete empty page — to the end of the confirmed window.
+            if (failed) {
+                if (accepted)
+                    await Webhooks.setCursor(store, subscription.id, Cursor.encode([...accepted]));
+            }
+            else if (page.scannedThrough !== undefined)
+                await Webhooks.setCursor(store, subscription.id, Cursor.encode([page.scannedThrough, endOfBlockIndex]));
+            else if (accepted)
+                await Webhooks.setCursor(store, subscription.id, Cursor.encode([...accepted]));
+            else if (!page.hasMore)
+                await Webhooks.setCursor(store, subscription.id, Cursor.encode([safeBlock, endOfBlockIndex]));
+        }
+    }
+    return result;
+}
+/**
+ * Attaches best-effort `{ symbol, decimals }` token metadata to a
+ * `token:transfer` row so destinations can render human amounts. Reads the row's
+ * `address` (the TIP-20 contract), resolves metadata via a memoized RPC lookup,
+ * and returns the row unchanged when the address is missing or the lookup fails.
+ */
+async function withTokenMetadata(data, deps) {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    const address = data['address'];
+    if (typeof address !== 'string')
+        return data;
+    const token = await resolveTokenMetadata(address, deps);
+    return token ? { ...data, token } : data;
+}
+/**
+ * Resolves a token's `{ symbol, decimals }` via `token.getMetadata`, memoized per
+ * `(chainId, address)` with a short TTL so a busy transfer stream shares one RPC
+ * lookup per token. Returns `undefined` on any failure — metadata is a rendering
+ * nicety, never a delivery blocker.
+ */
+async function resolveTokenMetadata(address, deps) {
+    try {
+        return await Store.memoize(async () => {
+            const meta = await deps.client.token.getMetadata({ token: address });
+            return { decimals: meta.decimals, symbol: meta.symbol };
+        }, {
+            key: `webhook:token-meta:v1:${deps.chainId}:${address}`,
+            store: deps.store,
+            ttl: Ttl.minutes(5),
+        });
+    }
+    catch {
+        // Metadata is best-effort; fall back to base-unit rendering.
+        return undefined;
+    }
+}
+/** 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',
+    });
+    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({
+            cache,
+            client,
+            cursor,
+            filters: parseFilters('log:emitted', subscription.filters),
+            maxBlocks,
+            safeBlock,
+        });
+    if (subscription.eventType === 'block:created')
+        return scanBlocks({
+            cache,
+            cursor,
+            filters: parseFilters('block:created', subscription.filters),
+            maxBlocks,
+            safeBlock,
+        });
+    if (subscription.eventType === 'transaction:included')
+        return scanTxs({
+            cache,
+            cursor,
+            filters: parseFilters('transaction:included', subscription.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 });
+    return { hasMore: page.hasMore, items: page.items };
+}
+const filterSchemas = {
+    'block:created': schema.BlockFilters,
+    'log:emitted': schema.LogFilters,
+    'token:transfer': schema.TransferFilters,
+    'transaction:included': schema.TxFilters,
+};
+/**
+ * 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
+ * bad filter can never silently widen the match set.
+ */
+export function parseFilters(eventType, filters) {
+    const result = filterSchemas[eventType].safeParse(filters ?? {});
+    if (!result.success)
+        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')
+        return op.toLowerCase();
+    if (Array.isArray(op))
+        return op.map(lowercaseLeaves);
+    if (op && typeof op === 'object') {
+        const out = {};
+        for (const [key, value] of Object.entries(op))
+            out[key] = lowercaseLeaves(value);
+        return out;
+    }
+    return op;
+}
+/** Recursively renders decoded event args JSON-safe (bigint → decimal string). */
+function serializeArgs(value) {
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (Array.isArray(value))
+        return value.map(serializeArgs);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, inner] of Object.entries(value))
+            out[key] = serializeArgs(inner);
+        return out;
+    }
+    return value;
+}
+// Shared filter matching (JS predicates over RPC objects).
+/** Parses a `0x`-hex (or decimal) quantity into a bigint for numeric comparison. */
+const toBig = (value) => BigInt(String(value));
+/** Case-insensitive equality for string fields; bigint equality for numeric. */
+function operandEquals(value, target, kind) {
+    return kind === 'number'
+        ? toBig(value) === toBig(target)
+        : value.toLowerCase() === String(target).toLowerCase();
+}
+/**
+ * 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
+ * missing field so an absent value never matches (fail-closed).
+ *
+ * - bare value / `{ eq }` → equality
+ * - `{ in: [...] }` → membership
+ * - `{ not }` → inequality
+ * - `{ gt|gte|lt|lte }` → numeric range (AND-combined)
+ * - `{ selector }` → first 4 bytes (10 hex chars) equal
+ * - `{ startsWith }` → hex prefix
+ */
+export function matchesOperator(value, op, kind = 'string') {
+    if (value === undefined)
+        return false;
+    if (typeof op !== 'object' || op === null)
+        return operandEquals(value, op, kind);
+    const o = op;
+    if ('selector' in o)
+        return value.slice(0, 10).toLowerCase() === String(o['selector']).toLowerCase();
+    if ('startsWith' in o)
+        return value.toLowerCase().startsWith(String(o['startsWith']).toLowerCase());
+    if ('in' in o)
+        return o['in'].some((v) => operandEquals(value, v, kind));
+    if ('not' in o)
+        return !operandEquals(value, o['not'], kind);
+    // Comparison object: AND-combine whichever of eq/gt/gte/lt/lte are present.
+    const n = toBig(value);
+    let ok = true;
+    if ('eq' in o)
+        ok = ok && n === toBig(o['eq']);
+    if ('gt' in o)
+        ok = ok && n > toBig(o['gt']);
+    if ('gte' in o)
+        ok = ok && n >= toBig(o['gte']);
+    if ('lt' in o)
+        ok = ok && n < toBig(o['lt']);
+    if ('lte' in o)
+        ok = ok && n <= toBig(o['lte']);
+    return ok;
+}
+/** Matches an `eq`-operator against any inner account-abstraction call target. */
+function matchesCalls(calls, op) {
+    const targets = (Array.isArray(calls) ? calls : [])
+        .map((c) => (c && typeof c === 'object' ? c['to'] : undefined))
+        .filter((to) => typeof to === 'string')
+        .map((to) => to.toLowerCase());
+    const has = (addr) => targets.includes(String(addr).toLowerCase());
+    if (typeof op === 'object' && op !== null) {
+        const o = op;
+        if ('in' in o)
+            return o['in'].some(has);
+        if ('not' in o)
+            return !has(o['not']);
+        if ('eq' in o)
+            return has(o['eq']);
+    }
+    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) => `0x${n.toString(16)}`;
+/** Issues a JSON-RPC request through the viem client for a method viem can't type. */
+function rpc(client, method, params) {
+    return client.request({
+        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, safeBlock, maxBlocks) {
+    const decoded = cursor ? Cursor.decode(cursor, ['int', 'int']) : undefined;
+    const cb = decoded ? decoded[0] : 0;
+    const ci = decoded ? decoded[1] : 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, index, skip) {
+    return block < skip[0] || (block === skip[0] && index <= skip[1]);
+}
+/** Builds a per-tick {@link ChainCache} bound to a viem client. */
+function createChainCache(client) {
+    const headers = new Map();
+    const blocks = new Map();
+    const receipts = new Map();
+    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((b) => b ?? undefined);
+                blocks.set(n, p);
+            }
+            return p;
+        },
+        header(n) {
+            let p = headers.get(n);
+            if (!p) {
+                p = client
+                    .getBlock({ blockNumber: BigInt(n), includeTransactions: false })
+                    .catch(() => undefined);
+                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;
+        },
+    };
+}
+/**
+ * Builds the delivered `log:emitted` payload from a viem-formatted 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.
+ */
+function toLogEvent(log, timestamp, signature, event) {
+    const address = Schema.Address.safeParse(log.address);
+    const transactionHash = Schema.Hash.safeParse(log.transactionHash);
+    const blockNumber = log.blockNumber === null ? undefined : Number(log.blockNumber);
+    const logIndex = log.logIndex ?? undefined;
+    const transactionIndex = log.transactionIndex ?? undefined;
+    const topics = log.topics.filter((t) => typeof t === 'string');
+    const topic0 = Schema.Hash.safeParse(topics[0]);
+    const data = typeof log.data === 'string' ? log.data : '0x';
+    if (!address.success ||
+        !transactionHash.success ||
+        !topic0.success ||
+        blockNumber === undefined ||
+        logIndex === undefined ||
+        transactionIndex === undefined ||
+        timestamp === undefined)
+        return undefined;
+    const base = {
+        address: address.data,
+        blockNumber,
+        data,
+        logIndex,
+        timestamp,
+        topics,
+        transactionHash: transactionHash.data,
+        transactionIndex,
+    };
+    if (!signature || !event || log.args === undefined)
+        return base;
+    return {
+        ...base,
+        args: serializeArgs(log.args),
+        event: { name: event.name, signature, topic0: topic0.data },
+    };
+}
+/** Narrows an `eq`/`in` address operator into the `getLogs` address pushdown. */
+function pushAddress(op) {
+    if (op === undefined)
+        return undefined;
+    if (typeof op === 'string')
+        return op;
+    if (typeof op === 'object' && op !== null) {
+        const o = op;
+        if (typeof o['eq'] === 'string')
+            return o['eq'];
+        if (Array.isArray(o['in']))
+            return o['in'].filter((v) => typeof v === 'string');
+    }
+    // `not`/range forms can't be pushed; widen here, re-check in JS.
+    return undefined;
+}
+/**
+ * Scans contract event logs over the confirmed window via viem's `getLogs`,
+ * then re-checks **every** filter in JS (so operators the RPC can't express —
+ * `not`, ranges, decoded `args` — still apply). Two modes:
+ * - **raw** (no `signature`): `topic0..3` are matched directly.
+ * - **decoded** (`signature` present): `getLogs` is given the `event`, so it
+ *   pushes the event selector down, filters to matching logs, and best-effort
+ *   decodes `args` — which the JS pass then matches by name.
+ *
+ * `address` (`eq`/`in`) is pushed down to the node; all other operators are
+ * re-checked in JS over the narrow window.
+ */
+async function scanLogs(options) {
+    const { cache, client, cursor, filters, maxBlocks, safeBlock } = options;
+    const f = filters;
+    const window = scanWindow(cursor, safeBlock, maxBlocks);
+    if (!window)
+        return { items: [], scannedThrough: undefined };
+    const event = f.signature ? parseAbiItem(f.signature) : undefined;
+    if (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 fromBlock = BigInt(window.from);
+    const toBlock = BigInt(window.to);
+    const logs = (event
+        ? await client.getLogs({
+            ...(address ? { address } : {}),
+            event,
+            fromBlock,
+            strict: false,
+            toBlock,
+        })
+        : await client.getLogs({
+            ...(address ? { address } : {}),
+            fromBlock,
+            toBlock,
+        }));
+    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 items = [];
+    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 header = await cache.header(blockNumber);
+        const timestamp = blockIso(header);
+        const data = toLogEvent(log, timestamp, f.signature, event);
+        if (data)
+            items.push({ cursor: [data.blockNumber, data.logIndex], data });
+    }
+    return { items, scannedThrough: window.to };
+}
+/** Re-checks all log filters (including non-pushable operators) in JS. */
+function matchesLog(log, f, event) {
+    const topics = log.topics;
+    if (f.address !== undefined && !matchesOperator(log.address, f.address))
+        return false;
+    if (f.blockNumber !== undefined &&
+        !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.
+    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`.
+        if (log.args === undefined || Array.isArray(log.args))
+            return false;
+        const args = log.args;
+        for (const [name, op] of Object.entries(f.args)) {
+            const input = event.inputs.find((i) => i.name === name);
+            if (!input)
+                throw new Webhooks.InvalidFilterError('log:emitted', [
+                    { message: `Unknown event argument: ${name}.`, path: ['args', name] },
+                ]);
+            const numeric = /^u?int/.test(input.type);
+            const value = args[name];
+            const normalized = input.type === 'address' ? lowercaseLeaves(op) : op;
+            if (!matchesOperator(asString(value), normalized, numeric ? 'number' : 'string'))
+                return false;
+        }
+    }
+    return true;
+}
+// block:created (getBlock)
+/** Converts a viem block's `timestamp` (seconds) to an ISO 8601 string. */
+function blockIso(block) {
+    if (!block || typeof block.timestamp !== 'bigint')
+        return undefined;
+    return new Date(Number(block.timestamp) * 1000).toISOString();
+}
+/** Builds the delivered `block:created` payload from a viem block header. */
+function toBlockEvent(block) {
+    const number = block.number === null ? undefined : Number(block.number);
+    const hash = Schema.Hash.safeParse(block.hash);
+    const parentHash = Schema.Hash.safeParse(block.parentHash);
+    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 transactionCount = Array.isArray(block.transactions) ? block.transactions.length : 0;
+    if (number === undefined ||
+        !hash.success ||
+        !parentHash.success ||
+        !miner.success ||
+        gasUsed === undefined ||
+        gasLimit === undefined ||
+        timestamp === undefined)
+        return undefined;
+    return {
+        gasLimit,
+        gasUsed,
+        hash: hash.data,
+        miner: miner.data,
+        number,
+        parentHash: parentHash.data,
+        timestamp,
+        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.
+ */
+async function scanBlocks(options) {
+    const { cache, cursor, filters, maxBlocks, safeBlock } = options;
+    const f = filters;
+    const window = scanWindow(cursor, safeBlock, maxBlocks);
+    if (!window)
+        return { items: [], scannedThrough: undefined };
+    const items = [];
+    for (let n = window.from; n <= window.to; n++) {
+        if (atOrBefore(n, 0, window.skip))
+            continue;
+        const block = await cache.header(n);
+        if (!block)
+            continue;
+        if (!matchesBlock(block, f))
+            continue;
+        const data = toBlockEvent(block);
+        if (data)
+            items.push({ cursor: [data.number, 0], data });
+    }
+    return { items, scannedThrough: window.to };
+}
+/** Re-checks all block filters in JS. The RPC has no consensus `proposer`. */
+function matchesBlock(block, f) {
+    if (f.number !== undefined && !matchesOperator(block.number?.toString(), f.number, 'number'))
+        return false;
+    if (f.miner !== undefined && !matchesOperator(block.miner, f.miner))
+        return false;
+    if (f.gasUsed !== undefined && !matchesOperator(block.gasUsed?.toString(), f.gasUsed, 'number'))
+        return false;
+    if (f.gasLimit !== undefined &&
+        !matchesOperator(block.gasLimit?.toString(), f.gasLimit, 'number'))
+        return false;
+    if (f.timestamp !== undefined &&
+        !matchesOperator(block.timestamp?.toString(), f.timestamp, 'number'))
+        return false;
+    // `proposer` is not exposed over standard RPC, so it can never match.
+    if (f.proposer !== undefined)
+        return false;
+    return true;
+}
+// transaction:included (eth_getBlockByNumber + eth_getBlockReceipts)
+/** Maps a `transaction:included` scalar filter field to its raw-tx field + kind. */
+const txFields = {
+    blockNumber: { field: 'blockNumber', kind: 'number' },
+    feeToken: { field: 'feeToken', kind: 'string' },
+    gasLimit: { field: 'gas', kind: 'number' },
+    hash: { field: 'hash', kind: 'string' },
+    maxFeePerGas: { field: 'maxFeePerGas', kind: 'number' },
+    maxPriorityFeePerGas: { field: 'maxPriorityFeePerGas', kind: 'number' },
+    nonce: { field: 'nonce', kind: 'number' },
+    nonceKey: { field: 'nonceKey', kind: 'string' },
+    txType: { field: 'type', kind: 'string' },
+    validAfter: { field: 'validAfter', kind: 'number' },
+    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 reuses `Transactions.humanizeTransaction`, so it is
+ * byte-identical to the read endpoint.
+ */
+async function scanTxs(options) {
+    const { cache, cursor, filters, maxBlocks, safeBlock } = options;
+    const f = filters;
+    const window = scanWindow(cursor, safeBlock, maxBlocks);
+    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;
+        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)
+                continue;
+            if (!matchesTx(tx, f, includeCalls, receipt, timestamp, n))
+                continue;
+            const parsed = Transactions.schema.Rpc.Transaction.safeParse(tx);
+            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 });
+        }
+    }
+    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) {
+    const from = tx['from'];
+    const to = tx['to'];
+    const calls = tx['calls'];
+    if (f.from !== undefined && !matchesOperator(asString(from), f.from))
+        return false;
+    if (f.to !== undefined) {
+        const direct = matchesOperator(asString(to), f.to);
+        if (!direct && !(includeCalls && matchesCalls(calls, f.to)))
+            return false;
+    }
+    if (f.address !== undefined) {
+        const direct = matchesOperator(asString(from), f.address) || matchesOperator(asString(to), f.address);
+        if (!direct && !(includeCalls && matchesCalls(calls, f.address)))
+            return false;
+    }
+    if (f.calls?.to !== undefined && !matchesCalls(calls, f.calls.to))
+        return false;
+    if (f.input !== undefined && !matchesOperator(asString(tx['input']), f.input))
+        return false;
+    if (f.callCount !== undefined) {
+        const count = Array.isArray(calls) ? calls.length : 0;
+        if (!matchesOperator(String(count), f.callCount, 'number'))
+            return false;
+    }
+    for (const [name, spec] of Object.entries(txFields)) {
+        const op = f[name];
+        if (op === undefined)
+            continue;
+        const value = name === 'blockNumber'
+            ? (asString(tx['blockNumber']) ?? blockNumber.toString())
+            : asString(tx[spec.field]);
+        if (!matchesOperator(value, op, spec.kind))
+            return false;
+    }
+    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. */
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function ownerFor(c) {
+    const principal = Auth.getPrincipal(c);
+    if (!principal)
+        return null;
+    if (principal.type === 'api_key')
+        return { orgId: principal.orgId, type: 'api_key' };
+    const payer = principal.payment?.payer;
+    return payer ? { payer, type: 'mpp' } : null;
+}
+/** Strips internal fields (`owner`, `secret`) from a subscription for reads. */
+function toPublic(subscription) {
+    return {
+        chainId: subscription.chainId,
+        ...(subscription.context === undefined ? {} : { context: subscription.context }),
+        createdAt: subscription.createdAt,
+        destination: subscription.destination,
+        eventType: subscription.eventType,
+        ...(subscription.expiresAt === undefined ? {} : { expiresAt: subscription.expiresAt }),
+        failureCount: subscription.failureCount,
+        filters: subscription.filters,
+        id: subscription.id,
+        ...(subscription.lastDeliveryAt === undefined
+            ? {}
+            : { lastDeliveryAt: subscription.lastDeliveryAt }),
+        status: subscription.status,
+        updatedAt: subscription.updatedAt,
+    };
+}
+/** Public read shape plus the one-time signing secret (creation only). */
+function toCreated(subscription) {
+    return { ...toPublic(subscription), secret: subscription.secret };
+}
+function mutationError(c, cause) {
+    if (cause instanceof Webhooks.InvalidUrlError)
+        return Response.error(c, { code: 'url_invalid', message: cause.message, status: 400 });
+    if (cause instanceof Webhooks.InvalidFilterError)
+        return Response.error(c, {
+            code: 'filters_invalid',
+            details: cause.details,
+            message: cause.message,
+            status: 400,
+        });
+    if (cause instanceof Webhooks.LimitExceededError)
+        return Response.error(c, { code: 'limit_exceeded', message: cause.message, status: 403 });
+    return Response.upstream(c, cause);
+}
+function notFound(c) {
+    return Response.error(c, {
+        code: 'webhook_not_found',
+        message: 'Webhook not found',
+        status: 404,
+    });
+}
+function notEnabled(c) {
+    return Response.error(c, {
+        code: 'webhooks_not_enabled',
+        message: 'Webhooks are not enabled for this Tempo API deployment.',
+        status: 404,
+    });
+}
+function unauthorized(c) {
+    return Response.error(c, {
+        code: 'unauthorized',
+        message: 'Tempo could not determine which authenticated account owns this webhook.',
+        status: 401,
+    });
+}
+//# sourceMappingURL=webhooks.js.map