tapimo 0.13.0 → 0.15.0

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

@@ -17,7 +17,8 @@ import type * as Viem from '../../../internal/Viem.js'
 import * as WebhookDestination from '../../../internal/WebhookDestination.js'
 import * as WebhookTransfer from '../../../internal/WebhookTransfer.js'
 import * as Webhooks from '../../../internal/Webhooks.js'
-import * as FundingDeposit from '../../../internal/funding/Deposit.js'
+import * as RoutesDeposit from '../../../internal/routes/Deposit.js'
+import * as RoutesTransfer from '../../../internal/routes/Transfer.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
 
@@ -41,7 +42,8 @@ const redactedSlackUrl = 'https://hooks.slack.com/…'
  */
 export const eventTypes = [
   'block:created',
-  'funding:deposit.updated',
+  'routes:deposit.updated',
+  'routes:transfer.updated',
   'log:emitted',
   'token:transfer',
   'transaction:included',
@@ -50,6 +52,20 @@ export const eventTypes = [
 /** Event types a subscription can listen to. Derived from {@link eventTypes}. */
 export type EventType = (typeof eventTypes)[number]
 
+/** Route resource events produced by the API instead of chain scans. */
+export const routesEventTypes = [
+  'routes:deposit.updated',
+  'routes:transfer.updated',
+] as const satisfies readonly EventType[]
+
+/** Event type carrying an owner-scoped route resource. */
+export type RoutesEventType = (typeof routesEventTypes)[number]
+
+/** Returns whether an event type carries an owner-scoped route resource. */
+export function isRoutesEventType(eventType: EventType): eventType is RoutesEventType {
+  return (routesEventTypes as readonly EventType[]).includes(eventType)
+}
+
 /** Subscribable event types surfaced by `GET /webhooks/event-types`. */
 const eventTypeDescriptions = [
   {
@@ -59,8 +75,13 @@ const eventTypeDescriptions = [
   },
   {
     description:
-      'A funding deposit materially changed after verified reconciliation, filterable by deposit address, recipient, or status.',
-    type: 'funding:deposit.updated',
+      'A route deposit materially changed after verified reconciliation, filterable by deposit address, recipient, or status.',
+    type: 'routes:deposit.updated',
+  },
+  {
+    description:
+      'A route transfer materially changed, filterable by transfer ID or lifecycle status.',
+    type: 'routes:transfer.updated',
   },
   {
     description:
@@ -81,7 +102,10 @@ const eventTypeDescriptions = [
 /** Zod schemas owned by the webhooks resource. */
 export namespace schema {
   /** Subscribable event type. */
-  export const EventType = z.enum(eventTypes).check(z.describe('Event type you can subscribe to.'))
+  export const EventType = OpenApi.component(
+    z.enum(eventTypes).check(z.describe('Event type you can subscribe to.')),
+    'WebhookSubscriptionEventType',
+  )
 
   /** Subscription lifecycle status. */
   export const Status = z
@@ -137,19 +161,19 @@ export namespace schema {
    * 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
+  const DestinationSchema = z
     .discriminatedUnion('type', [
       z.object({
-        type: z.literal('url'),
+        type: z.literal('url').check(z.meta({ examples: ['url'] })),
         url: Url,
       }),
       z.object({
-        type: z.literal('slack'),
+        type: z.literal('slack').check(z.meta({ examples: ['slack'] })),
         url: SlackUrl,
       }),
       z.object({
         token: BetterstackToken,
-        type: z.literal('betterstack'),
+        type: z.literal('betterstack').check(z.meta({ examples: ['betterstack'] })),
         url: BetterstackUrl,
       }),
     ])
@@ -157,27 +181,41 @@ export namespace schema {
       z.describe(
         'Delivery destination: an HTTPS URL, a Slack incoming-webhook URL, or a Better Stack source.',
       ),
+      z.meta({ examples: [{ type: 'url', url: 'https://example.com/webhooks' }] }),
     )
+  const Destination = OpenApi.component(DestinationSchema, 'WebhookDestination')
 
-  const PublicDestination = z
+  const PublicDestinationSchema = z
     .discriminatedUnion('type', [
       z.object({
-        type: z.literal('url'),
+        type: z.literal('url').check(z.meta({ examples: ['url'] })),
         url: Url,
       }),
       z.object({
-        type: z.literal('slack'),
-        url: z.literal(redactedSlackUrl).check(z.describe('Redacted Slack webhook URL.')),
+        type: z.literal('slack').check(z.meta({ examples: ['slack'] })),
+        url: z
+          .literal(redactedSlackUrl)
+          .check(
+            z.describe('Redacted Slack webhook URL.'),
+            z.meta({ examples: [redactedSlackUrl] }),
+          ),
       }),
       z.object({
         token: z
           .literal(redactedBetterstackToken)
-          .check(z.describe('Redacted Better Stack source token.')),
-        type: z.literal('betterstack'),
+          .check(
+            z.describe('Redacted Better Stack source token.'),
+            z.meta({ examples: [redactedBetterstackToken] }),
+          ),
+        type: z.literal('betterstack').check(z.meta({ examples: ['betterstack'] })),
         url: BetterstackUrl,
       }),
     ])
-    .check(z.describe('Delivery destination with bearer credentials redacted.'))
+    .check(
+      z.describe('Delivery destination with bearer credentials redacted.'),
+      z.meta({ examples: [{ type: 'url', url: 'https://example.com/webhooks' }] }),
+    )
+  const PublicDestination = OpenApi.component(PublicDestinationSchema, 'WebhookPublicDestination')
 
   /**
    * Equality / membership operator for a filterable field. A consumer can pass a
@@ -212,7 +250,10 @@ export namespace schema {
         lt: z.optional(Schema.Quantity),
         lte: z.optional(Schema.Quantity),
       })
-      .check(z.refine((c) => Object.keys(c).length > 0, { error: 'Comparison cannot be empty.' })),
+      .check(
+        z.refine((c) => Object.keys(c).length > 0, { error: 'Comparison cannot be empty.' }),
+        z.meta({ examples: [{ gte: '0x1' }] }),
+      ),
   ])
 
   /**
@@ -232,9 +273,11 @@ export namespace schema {
    * drift. All are optional and AND-combined; omit every field to subscribe to
    * the full stream.
    */
-  export const TransferFilters = Transfers.schema.Predicates.check(
-    z.describe('Filters that narrow which TIP-20 transfer events trigger this webhook.'),
-    z.meta({ title: 'Transfer filters' }),
+  export const TransferFilters = OpenApi.component(
+    Transfers.schema.Predicates.check(
+      z.describe('Filters that narrow which TIP-20 transfer events trigger this webhook.'),
+    ),
+    'WebhookTransferFilters',
   )
 
   /**
@@ -246,80 +289,88 @@ export namespace schema {
    * `address` matches either side (`from` OR `to`); when `includeCalls` is set
    * (default), `to`/`address` also match an inner call target (`calls[].to`).
    */
-  export const TxFilters = z
-    .strictObject({
-      hash: z.optional(
-        eq(Schema.Hash).check(z.describe('Match this exact transaction hash (or any of several).')),
-      ),
-      address: z.optional(
-        eq(Schema.Address).check(
-          z.describe('Match transactions where this address is the sender or recipient.'),
+  export const TxFilters = OpenApi.component(
+    z
+      .strictObject({
+        hash: z.optional(
+          eq(Schema.Hash).check(
+            z.describe('Match this exact transaction hash (or any of several).'),
+          ),
         ),
-      ),
-      from: z.optional(
-        eq(Schema.Address).check(z.describe('Match transactions whose sender (`from`) is this.')),
-      ),
-      to: z.optional(
-        eq(Schema.Address).check(
-          z.describe('Match transactions sent to this address (root `to`; see `includeCalls`).'),
+        address: z.optional(
+          eq(Schema.Address).check(
+            z.describe('Match transactions where this address is the sender or recipient.'),
+          ),
         ),
-      ),
-      includeCalls: z.optional(
-        z
-          .boolean()
-          .check(
+        from: z.optional(
+          eq(Schema.Address).check(z.describe('Match transactions whose sender (`from`) is this.')),
+        ),
+        to: z.optional(
+          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] }),
+            ),
+        ),
+        value: z.optional(compare.check(z.describe('Match the transaction value (wei) bounds.'))),
+        input: z.optional(
+          bytes.check(
             z.describe(
-              'When true (default), `to`/`address` also match an inner account-abstraction call target (`calls[].to`).',
+              'Match top-level calldata by 4-byte `selector`, hex `startsWith`, or exact.',
             ),
-            z.meta({ examples: [true] }),
           ),
-      ),
-      value: z.optional(compare.check(z.describe('Match the transaction value (wei) bounds.'))),
-      input: z.optional(
-        bytes.check(
-          z.describe('Match top-level calldata by 4-byte `selector`, hex `startsWith`, or exact.'),
         ),
-      ),
-      calls: z.optional(
-        z
-          .strictObject({
-            to: eq(Schema.Address),
-          })
-          .check(
-            z.describe(
-              'Match if ANY inner account-abstraction call targets this address (`calls[].to`).',
+        calls: z.optional(
+          z
+            .strictObject({
+              to: eq(Schema.Address),
+            })
+            .check(
+              z.describe(
+                'Match if ANY inner account-abstraction call targets this address (`calls[].to`).',
+              ),
             ),
+        ),
+        callCount: z.optional(
+          compare.check(z.describe('Match the number of inner calls (`call_count`).')),
+        ),
+        txType: z.optional(
+          eq(Schema.Hex).check(
+            z.describe('Match the transaction type (e.g. `0x76` for Tempo AA).'),
           ),
-      ),
-      callCount: z.optional(
-        compare.check(z.describe('Match the number of inner calls (`call_count`).')),
-      ),
-      txType: z.optional(
-        eq(Schema.Hex).check(z.describe('Match the transaction type (e.g. `0x76` for Tempo AA).')),
-      ),
-      feeToken: z.optional(
-        eq(Schema.TokenAddress).check(z.describe('Match the fee token address.')),
-      ),
-      gasLimit: z.optional(compare.check(z.describe('Match the gas limit bounds.'))),
-      maxFeePerGas: z.optional(compare.check(z.describe('Match the max fee per gas bounds.'))),
-      maxPriorityFeePerGas: z.optional(
-        compare.check(z.describe('Match the max priority fee per gas bounds.')),
-      ),
-      nonce: z.optional(compare.check(z.describe('Match the nonce bounds.'))),
-      nonceKey: z.optional(eq(Schema.Hex).check(z.describe('Match the nonce key (Tempo AA).'))),
-      validBefore: z.optional(
-        compare.check(z.describe('Match the `validBefore` bounds (unix s).')),
-      ),
-      validAfter: z.optional(compare.check(z.describe('Match the `validAfter` bounds (unix s).'))),
-      blockNumber: z.optional(compare.check(z.describe('Match the block-number bounds.'))),
-      timestamp: z.optional(
-        compare.check(z.describe('Match the block timestamp bounds (unix s).')),
-      ),
-    })
-    .check(
-      z.describe('Filters that narrow which included transactions trigger this webhook.'),
-      z.meta({ title: 'Included-transaction filters' }),
-    )
+        ),
+        feeToken: z.optional(
+          eq(Schema.TokenAddress).check(z.describe('Match the fee token address.')),
+        ),
+        gasLimit: z.optional(compare.check(z.describe('Match the gas limit bounds.'))),
+        maxFeePerGas: z.optional(compare.check(z.describe('Match the max fee per gas bounds.'))),
+        maxPriorityFeePerGas: z.optional(
+          compare.check(z.describe('Match the max priority fee per gas bounds.')),
+        ),
+        nonce: z.optional(compare.check(z.describe('Match the nonce bounds.'))),
+        nonceKey: z.optional(eq(Schema.Hex).check(z.describe('Match the nonce key (Tempo AA).'))),
+        validBefore: z.optional(
+          compare.check(z.describe('Match the `validBefore` bounds (unix s).')),
+        ),
+        validAfter: z.optional(
+          compare.check(z.describe('Match the `validAfter` bounds (unix s).')),
+        ),
+        blockNumber: z.optional(compare.check(z.describe('Match the block-number bounds.'))),
+        timestamp: z.optional(
+          compare.check(z.describe('Match the block timestamp bounds (unix s).')),
+        ),
+      })
+      .check(z.describe('Filters that narrow which included transactions trigger this webhook.')),
+    'WebhookTransactionFilters',
+  )
 
   /** A 32-byte log topic (lowercased hex). */
   const topic = Schema.Hash
@@ -332,87 +383,92 @@ export namespace schema {
    * firehose), and an addressless filter must still be selective — an event
    * anchor (`signature`/`topic0`) plus at least one indexed topic or argument.
    */
-  export const LogFilters = z
-    .strictObject({
-      address: z.optional(
-        eq(Schema.Address).check(
-          z.describe('Only match logs emitted by this contract address (or any of several).'),
-          z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
+  export const LogFilters = OpenApi.component(
+    z
+      .strictObject({
+        address: z.optional(
+          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)`.',
+        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)'],
+            }),
           ),
-          z.meta({
-            examples: ['event Transfer(address indexed from, address indexed to, uint256 value)'],
-          }),
         ),
-      ),
-      topic0: z.optional(
-        eq(topic).check(
-          z.describe('Event signature hash (topic 0). Mutually exclusive with `signature`.'),
-          z.meta({
-            examples: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
-          }),
+        topic0: z.optional(
+          eq(topic).check(
+            z.describe('Event signature hash (topic 0). Mutually exclusive with `signature`.'),
+            z.meta({
+              examples: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
+            }),
+          ),
         ),
-      ),
-      topic1: z.optional(
-        eq(topic).check(
-          z.describe('Raw indexed argument 1 (topic 1).'),
-          z.meta({
-            examples: ['0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38'],
-          }),
+        topic1: z.optional(
+          eq(topic).check(
+            z.describe('Raw indexed argument 1 (topic 1).'),
+            z.meta({
+              examples: ['0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38'],
+            }),
+          ),
         ),
-      ),
-      topic2: z.optional(
-        eq(topic).check(
-          z.describe('Raw indexed argument 2 (topic 2).'),
-          z.meta({
-            examples: ['0x0000000000000000000000009e39034aae71fb89f66061a2602eb6efec271754'],
-          }),
+        topic2: z.optional(
+          eq(topic).check(
+            z.describe('Raw indexed argument 2 (topic 2).'),
+            z.meta({
+              examples: ['0x0000000000000000000000009e39034aae71fb89f66061a2602eb6efec271754'],
+            }),
+          ),
         ),
-      ),
-      topic3: z.optional(
-        eq(topic).check(
-          z.describe('Raw indexed argument 3 (topic 3).'),
-          z.meta({
-            examples: ['0x0000000000000000000000000000000000000000000000000000000000000000'],
-          }),
+        topic3: z.optional(
+          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 a super admin object.',
+        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 a super admin object.',
+              ),
+              z.meta({ examples: [{ to: '0x9e39034aae71fb89f66061a2602eb6efec271754' }] }),
             ),
-            z.meta({ examples: [{ to: '0x9e39034aae71fb89f66061a2602eb6efec271754' }] }),
-          ),
-      ),
-      blockNumber: z.optional(
-        compare.check(z.describe('Only match logs within these block-number bounds.')),
+        ),
+        blockNumber: z.optional(
+          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({
+          examples: [{ address: '0x20c0000000000000000000008f5425160ebe5525' }],
+        }),
+        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) => hasLogPushdown(f), {
+          error:
+            'Log filters must include a pushdown-capable address or an event/topic0 anchor plus an indexed topic or argument.',
+        }),
       ),
-    })
-    .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) => hasLogPushdown(f), {
-        error:
-          'Log filters must include a pushdown-capable address or an event/topic0 anchor plus an indexed topic or argument.',
-      }),
-    )
+    'WebhookLogFilters',
+  )
 
   /**
    * `block:created` subscription filters. All optional and AND-combined; unlike
@@ -420,166 +476,187 @@ export namespace schema {
    * non-abusive heartbeat feed. Block-level metadata only (no transaction
    * predicates; use `transaction:included` for those).
    */
-  export const BlockFilters = z
-    .strictObject({
-      number: z.optional(
-        compare.check(z.describe('Only match blocks within these block-number bounds.')),
-      ),
-      miner: z.optional(
-        eq(Schema.Address).check(
-          z.describe('Only match blocks produced by this address (the miner/producer).'),
-          z.meta({ examples: ['0x0000000000000000000000000000000000000000'] }),
+  export const BlockFilters = OpenApi.component(
+    z
+      .strictObject({
+        number: z.optional(
+          compare.check(z.describe('Only match blocks within these block-number bounds.')),
         ),
-      ),
-      proposer: z.optional(
-        eq(Schema.Address).check(
-          z.describe('Only match blocks proposed by this consensus proposer (when available).'),
+        miner: z.optional(
+          eq(Schema.Address).check(
+            z.describe('Only match blocks produced by this address (the miner/producer).'),
+            z.meta({ examples: ['0x0000000000000000000000000000000000000000'] }),
+          ),
         ),
-      ),
-      gasUsed: z.optional(
-        compare.check(z.describe('Only match blocks whose total gas used is within these bounds.')),
-      ),
-      gasLimit: z.optional(
-        compare.check(z.describe('Only match blocks whose gas limit is within these bounds.')),
-      ),
-      timestamp: z.optional(
-        compare.check(
-          z.describe('Only match blocks whose unix timestamp (seconds) is within these bounds.'),
+        proposer: z.optional(
+          eq(Schema.Address).check(
+            z.describe('Only match blocks proposed by this consensus proposer (when available).'),
+          ),
         ),
-      ),
-    })
-    .check(
-      z.describe('Filters that narrow which new blocks trigger this webhook.'),
-      z.meta({ title: 'Block filters' }),
-    )
+        gasUsed: z.optional(
+          compare.check(
+            z.describe('Only match blocks whose total gas used is within these bounds.'),
+          ),
+        ),
+        gasLimit: z.optional(
+          compare.check(z.describe('Only match blocks whose gas limit is within these bounds.')),
+        ),
+        timestamp: z.optional(
+          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.')),
+    'WebhookBlockFilters',
+  )
 
-  /** `funding:deposit.updated` subscription filters. All are optional and AND-combined. */
-  export const FundingDepositFilters = z
-    .strictObject({
-      depositAddressId: z.optional(FundingDeposit.schema.Snapshot.shape.depositAddressId),
-      recipient: z.optional(Schema.Address),
-      status: z.optional(FundingDeposit.schema.Status),
-    })
-    .check(
-      z.describe('Filters that narrow which funding deposit changes trigger this webhook.'),
-      z.meta({ title: 'Funding deposit filters' }),
-    )
+  /** `routes:deposit.updated` subscription filters. All are optional and AND-combined. */
+  export const RoutesDepositFilters = OpenApi.component(
+    z
+      .strictObject({
+        depositAddressId: z.optional(RoutesDeposit.schema.Snapshot.shape.depositAddressId),
+        recipient: z.optional(Schema.Address),
+        status: z.optional(RoutesDeposit.schema.Status),
+      })
+      .check(z.describe('Filters that narrow which route deposit changes trigger this webhook.')),
+    'WebhookRoutesDepositFilters',
+  )
+
+  /** `routes:transfer.updated` subscription filters. All are optional and AND-combined. */
+  export const RoutesTransferFilters = OpenApi.component(
+    z
+      .strictObject({
+        id: z.optional(RoutesTransfer.schema.RoutesTransfer.shape.id),
+        status: z.optional(RoutesTransfer.schema.Status),
+      })
+      .check(z.describe('Filters that narrow which route transfer changes trigger this webhook.')),
+    'WebhookRoutesTransferFilters',
+  )
 
   /**
    * 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.
    */
-  export const Context = z
-    .object({
-      description: z.optional(
-        z
-          .string()
+  export const Context = OpenApi.component(
+    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.')),
+    'WebhookContext',
+  )
+
+  /**
+   * Public subscription representation. Never includes the signing `secret`
+   * (returned once by `POST /webhooks`) or the internal owner.
+   */
+  export const Subscription = OpenApi.component(
+    z
+      .object({
+        chainId: chainIdResponse,
+        context: z
+          .optional(Context)
+          .check(z.meta({ examples: [{ title: 'Prod USDC large transfers' }] })),
+        createdAt: z.iso
+          .datetime()
           .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.'] }),
+            z.describe('When the subscription was created, as an ISO 8601 timestamp.'),
+            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
           ),
-      ),
-      metadata: z.optional(
-        z
-          .record(
-            z.string().check(z.minLength(1), z.maxLength(64)),
-            z.string().check(z.maxLength(500)),
-          )
+        destination: PublicDestination,
+        environment: z
+          .optional(z.enum(['production', 'sandbox']))
+          .check(
+            z.describe('API-key environment for private resource events, when applicable.'),
+            z.meta({ examples: ['production'] }),
+          ),
+        eventType: EventType.check(z.meta({ examples: ['token:transfer'] })),
+        expiresAt: z
+          .optional(z.iso.datetime())
           .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.',
+              'When the subscription expires, as an ISO 8601 timestamp. Only MPP-paid subscriptions expire.',
             ),
-            z.meta({ examples: [{ env: 'prod', team: 'payments' }] }),
+            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
           ),
-      ),
-      title: z.optional(
-        z
-          .string()
+        failureCount: z
+          .number()
           .check(
-            z.maxLength(120),
-            z.describe('Short label for this subscription.'),
-            z.meta({ examples: ['Prod USDC large transfers'] }),
+            z.int(),
+            z.nonnegative(),
+            z.describe(
+              'Number of delivery failures in a row for this subscription, capped at the auto-disable threshold.',
+            ),
+            z.meta({ examples: [0] }),
           ),
-      ),
-    })
-    .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.
-   */
-  export const Subscription = z
-    .object({
-      chainId: chainIdResponse,
-      context: z.optional(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: PublicDestination,
-      environment: z
-        .optional(z.enum(['production', 'sandbox']))
-        .check(
-          z.describe('API-key environment for private resource events, when applicable.'),
-          z.meta({ examples: ['production'] }),
+        filters: Filters.check(
+          z.describe('Filters applied to this event type.'),
+          z.meta({ examples: [{ address: '0x20c0000000000000000000008f5425160ebe5525' }] }),
         ),
-      eventType: 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.',
+        id: z
+          .string()
+          .check(
+            z.describe('Webhook subscription ID (`wh_…`).'),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
-          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, capped at the auto-disable threshold.',
+        lastDeliveryAt: z
+          .optional(z.iso.datetime())
+          .check(
+            z.describe(
+              'When Tempo last delivered an event successfully, as an ISO 8601 timestamp. Refreshed at most once per minute during sustained delivery.',
+            ),
+            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
           ),
-          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_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-      lastDeliveryAt: z
-        .optional(z.iso.datetime())
-        .check(
-          z.describe(
-            'When Tempo last delivered an event successfully, as an ISO 8601 timestamp. Refreshed at most once per minute during sustained delivery.',
+        status: 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'] }),
           ),
-          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-        ),
-      status: 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 its destination.',
         ),
-    })
-    .check(
-      z.describe(
-        'A webhook subscription that tells Tempo which onchain events to send to your destination.',
       ),
-    )
+    'Webhook',
+  )
 
   /** Outcome of a single delivery attempt. */
   export const DeliveryStatus = z
@@ -590,69 +667,72 @@ export namespace schema {
     )
 
   /** A logged delivery attempt for a subscription. */
-  export const 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_001718668800000_C1yJkk7CuML98HFthEDk9PsY'] }),
-        ),
-      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.',
+  export const Delivery = OpenApi.component(
+    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] }),
           ),
-          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: DeliveryStatus.check(z.meta({ examples: ['succeeded'] })),
-      subscriptionId: z
-        .string()
-        .check(
-          z.describe('Subscription ID (`wh_…`) this delivery belongs to.'),
-          z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-    })
-    .check(z.describe('One attempt by Tempo to deliver an event to your webhook URL.'))
+        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_001718668800000_C1yJkk7CuML98HFthEDk9PsY'] }),
+          ),
+        requestUrl: z
+          .url()
+          .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: DeliveryStatus.check(z.meta({ examples: ['succeeded'] })),
+        subscriptionId: z
+          .string()
+          .check(
+            z.describe('Subscription ID (`wh_…`) this delivery belongs to.'),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('One attempt by Tempo to deliver an event to a webhook destination.')),
+    'WebhookDelivery',
+  )
 
   /**
    * A `transfer` event payload: the decoded TIP-20 `Transfer` row. Mirrors a
@@ -660,88 +740,94 @@ export namespace schema {
    * read endpoint adds (webhook delivery does not perform per-event token
    * lookups).
    */
-  export const 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'] }),
+  export const TransferEvent = OpenApi.component(
+    z
+      .object({
+        address: Schema.TokenAddress.check(
+          z.describe('TIP-20 token contract address.'),
+          z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
         ),
-      blockNumber: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Block number where this transfer was included.'),
-          z.meta({ examples: [1000002] }),
+        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'] }),
         ),
-      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.685Z'] }),
+        sender: Schema.Address.check(
+          z.describe('Address that sent the transfer.'),
+          z.meta({ examples: ['0xe7687128b0a808c2831ff94d4f7b2fb35c65af38'] }),
         ),
-      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'] })),
-          })
+        timestamp: z.iso
+          .datetime()
           .check(
-            z.describe(
-              'Best-effort token metadata (symbol/decimals) resolved before delivery so `amount` can render as a human amount. Omitted when the lookup is unavailable.',
-            ),
+            z.describe('Block timestamp as an ISO 8601 string.'),
+            z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
           ),
+        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 before delivery 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.'),
       ),
-      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.'),
-    )
+    'WebhookTransferEvent',
+  )
 
   /**
    * A `transaction` event payload using the humanized transaction shape without
    * opt-in read resources such as receipts.
    */
-  export const TransactionEvent = z
-    .object({
-      ...Transactions.schema.Transaction.shape,
-      meta: z
-        .object({
-          rpc: Transactions.schema.Rpc.Transaction.check(
-            z.describe('The original JSON-RPC transaction payload.'),
-          ),
-        })
-        .check(z.describe('Metadata for this transaction webhook event.')),
-    })
-    .check(z.describe('A transaction included in a block.'))
+  export const TransactionEvent = OpenApi.component(
+    z
+      .object({
+        ...Transactions.schema.Transaction.shape,
+        meta: z
+          .object({
+            rpc: Transactions.schema.Rpc.Transaction.check(
+              z.describe('The original JSON-RPC transaction payload.'),
+            ),
+          })
+          .check(z.describe('Metadata for this transaction webhook event.')),
+      })
+      .check(z.describe('A transaction included in a block.')),
+    'WebhookTransactionEvent',
+  )
 
   /**
    * A `log:emitted` event payload: the raw contract event log. When a
@@ -749,185 +835,204 @@ export namespace schema {
    * `event`/`args` fields carry the decoded event name and arguments (large
    * integers as decimal strings).
    */
-  export const 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] }),
+  export const LogEvent = OpenApi.component(
+    z
+      .object({
+        address: Schema.Address.check(
+          z.describe('Contract that emitted the log.'),
+          z.meta({ examples: ['0x20c00000000000000000000071de0cd31ab0d105'] }),
         ),
-      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'],
-              }),
+        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.describe(
-              'Decoded event identity, present only when a `signature` filter was supplied.',
-            ),
+            z.int(),
+            z.nonnegative(),
+            z.describe('Block number the log was included in.'),
+            z.meta({ examples: [1000002] }),
           ),
-      ),
-      logIndex: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Index of the log within its block.'),
-          z.meta({ examples: [0] }),
+        data: Schema.Hex.check(
+          z.describe('Unindexed log data (ABI-encoded).'),
+          z.meta({
+            examples: ['0x0000000000000000000000000000000000000000000000000000000000002710'],
+          }),
         ),
-      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.685Z'] }),
+        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.',
+              ),
+            ),
         ),
-      topics: z.array(Schema.Hash).check(
-        z.describe('Log topics, starting with the event signature hash (topic 0).'),
-        z.meta({
-          examples: [
-            [
-              '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
-              '0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38',
+        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.685Z'] }),
+          ),
+        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 (an RPC-derived block header). */
-  export const 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'] }),
+        transactionHash: Schema.Hash.check(
+          z.describe('Hash of the transaction that emitted the log.'),
+          z.meta({
+            examples: ['0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3'],
+          }),
         ),
-      ),
-      gasUsed: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Total gas used by every transaction in this block.'),
-          z.meta({ examples: [4340281] }),
+        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).')),
+    'WebhookLogEvent',
+  )
+
+  /** Payload for a `block:created` event (an RPC-derived block header). */
+  export const BlockEvent = OpenApi.component(
+    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'],
+          }),
         ),
-      gasLimit: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Maximum gas available for all transactions in this block.'),
-          z.meta({ examples: [500000000] }),
+        parentHash: Schema.Hash.check(
+          z.describe('Hash of the previous block in the chain.'),
+          z.meta({
+            examples: ['0xa406dff9c51cc2abbef3a811f0499e99a568bf781019f129ab45dca1df0e43e5'],
+          }),
         ),
-      transactionCount: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Number of transactions included in this block.'),
-          z.meta({ examples: [3] }),
+        miner: Schema.Address.check(
+          z.describe('Address of the block producer (miner/proposer).'),
+          z.meta({ examples: ['0x0000000000000000000000000000000000000000'] }),
         ),
-      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.685Z'] }),
+        proposer: z.optional(
+          Schema.Address.check(
+            z.describe('Consensus proposer of the block, when the chain records one.'),
+            z.meta({ examples: ['0x0000000000000000000000000000000000000000'] }),
+          ),
         ),
-    })
-    .check(z.describe('Payload for a `block:created` event (a new block header).'))
+        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.685Z'] }),
+          ),
+      })
+      .check(z.describe('Payload for a `block:created` event (a new block header).')),
+    'WebhookBlockEvent',
+  )
 
-  /** Public funding deposit after a committed material change. */
-  export const FundingDepositEvent = FundingDeposit.schema.FundingDeposit
+  /** Public route deposit after a committed material change. */
+  export const RoutesDepositEvent = RoutesDeposit.schema.RoutesDeposit
+
+  /** Public route transfer after a committed material change. */
+  export const RoutesTransferEvent = RoutesTransfer.schema.RoutesTransfer
 
   /** A `ping` (synthetic test-delivery) payload, sent by `POST /webhooks/:id/ping`. */
-  export const 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.'))
+  export const PingEvent = OpenApi.component(
+    z
+      .object({
+        ping: z
+          .literal(true)
+          .check(
+            z.describe('Marks this payload as a synthetic ping test.'),
+            z.meta({ examples: [true] }),
+          ),
+      })
+      .check(z.describe('Payload for a webhook ping test delivery.')),
+    'WebhookPingEvent',
+  )
 
   /** Fields common to every delivery envelope. */
   const envelopeBase = {
     chainId: Schema.ChainId,
-    context: z.optional(Context),
+    context: z
+      .optional(Context)
+      .check(z.meta({ examples: [{ title: 'Prod USDC large transfers' }] })),
     createdAt: z.iso
       .datetime()
       .check(
@@ -957,155 +1062,254 @@ export namespace schema {
    * variant selector — without per-variant titles, inline `oneOf` members render
    * as a single (first) collapsed schema.
    */
-  export const Envelope = z
-    .discriminatedUnion('type', [
-      z
-        .object({ ...envelopeBase, data: TransferEvent, type: z.literal('token:transfer') })
-        .check(z.meta({ title: 'Transfer event' })),
-      z
-        .object({
-          ...envelopeBase,
-          data: TransactionEvent,
-          type: z.literal('transaction:included'),
-        })
-        .check(z.meta({ title: 'Included transaction event' })),
-      z
-        .object({ ...envelopeBase, data: LogEvent, type: z.literal('log:emitted') })
-        .check(z.meta({ title: 'Log event' })),
-      z
-        .object({ ...envelopeBase, data: BlockEvent, type: z.literal('block:created') })
-        .check(z.meta({ title: 'Block event' })),
-      z
-        .object({
-          ...envelopeBase,
-          data: FundingDepositEvent,
-          type: z.literal('funding:deposit.updated'),
-        })
-        .check(z.meta({ title: 'Funding deposit updated event' })),
-      z
-        .object({ ...envelopeBase, data: PingEvent, type: z.literal('ping') })
-        .check(z.meta({ title: 'Ping (test delivery)' })),
-    ])
-    .check(z.describe('The signed JSON payload Tempo POSTs to your webhook URL.'))
-
-  /** Schemas for the getWebhookEventTypes operation. */
-  export namespace getWebhookEventTypes {
-    export const 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: 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.'))
-  }
-
-  /** Schemas for the createWebhook operation. */
-  export namespace 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}).
-     */
-    export const Body = z
-      .discriminatedUnion('eventType', [
+  export const Envelope = OpenApi.component(
+    z
+      .discriminatedUnion('type', [
         z
           .object({
-            chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
-            context: z.optional(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(TransferFilters),
+            ...envelopeBase,
+            data: TransferEvent,
+            type: z.literal('token:transfer').check(z.meta({ examples: ['token:transfer'] })),
           })
-          .check(z.meta({ title: 'Transfer subscription' })),
+          .check(z.meta({ title: 'Transfer event' })),
         z
           .object({
-            chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
-            context: z.optional(Context),
-            destination: Destination,
-            eventType: z
+            ...envelopeBase,
+            data: TransactionEvent,
+            type: 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(TxFilters),
+              .check(z.meta({ examples: ['transaction:included'] })),
           })
-          .check(z.meta({ title: 'Included-transaction subscription' })),
+          .check(z.meta({ title: 'Included transaction event' })),
         z
           .object({
-            chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
-            context: z.optional(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: LogFilters,
+            ...envelopeBase,
+            data: LogEvent,
+            type: z.literal('log:emitted').check(z.meta({ examples: ['log:emitted'] })),
           })
-          .check(z.meta({ title: 'Log subscription' })),
+          .check(z.meta({ title: 'Log event' })),
         z
           .object({
-            chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
-            context: z.optional(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(BlockFilters),
+            ...envelopeBase,
+            data: BlockEvent,
+            type: z.literal('block:created').check(z.meta({ examples: ['block:created'] })),
           })
-          .check(z.meta({ title: 'Block subscription' })),
+          .check(z.meta({ title: 'Block event' })),
         z
           .object({
-            chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
-            context: z.optional(Context),
-            destination: Destination,
-            eventType: z
-              .literal('funding:deposit.updated')
-              .check(
-                z.describe('Event type for committed funding deposit changes.'),
-                z.meta({ examples: ['funding:deposit.updated'] }),
-              ),
-            filters: z.optional(FundingDepositFilters),
+            ...envelopeBase,
+            data: RoutesDepositEvent,
+            type: z
+              .literal('routes:deposit.updated')
+              .check(z.meta({ examples: ['routes:deposit.updated'] })),
+          })
+          .check(z.meta({ title: 'Route deposit updated event' })),
+        z
+          .object({
+            ...envelopeBase,
+            data: RoutesTransferEvent,
+            type: z
+              .literal('routes:transfer.updated')
+              .check(z.meta({ examples: ['routes:transfer.updated'] })),
+          })
+          .check(z.meta({ title: 'Route transfer updated event' })),
+        z
+          .object({
+            ...envelopeBase,
+            data: PingEvent,
+            type: z.literal('ping').check(z.meta({ examples: ['ping'] })),
           })
-          .check(z.meta({ title: 'Funding deposit subscription' })),
+          .check(z.meta({ title: 'Ping (test delivery)' })),
       ])
-      .check(z.describe('Details for creating a webhook subscription.'))
+      .check(z.describe('The signed JSON payload Tempo POSTs to a webhook destination.')),
+    'WebhookEventEnvelope',
+  )
 
-    export const Response = z
-      .object({
-        ...Subscription.shape,
-        destination: Destination,
-        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.',
+  /** Schemas for the getWebhookEventTypes operation. */
+  export namespace getWebhookEventTypes {
+    const EventTypeEntry = OpenApi.component(
+      z
+        .object({
+          description: z
+            .string()
+            .check(
+              z.describe('Plain-English description of the event type.'),
+              z.meta({ examples: ['TIP-20 token transfer event.'] }),
             ),
-            z.meta({ examples: ['whsec_abc123'] }),
+          type: EventType.check(z.meta({ examples: ['token:transfer'] })),
+        })
+        .check(z.describe('One webhook event type available for subscription.')),
+      'WebhookEventType',
+    )
+
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(EventTypeEntry).check(
+            z.describe('Webhook event types available for subscription.'),
+            z.meta({
+              examples: [[{ description: 'TIP-20 token transfer event.', type: 'token:transfer' }]],
+            }),
           ),
-      })
-      .check(z.describe('The new webhook subscription, including the one-time signing secret.'))
+        })
+        .check(z.describe('List of webhook event types Tempo can send.')),
+      'WebhookEventTypeList',
+    )
+  }
+
+  /** Schemas for the createWebhook operation. */
+  export namespace createWebhook {
+    /** Request variant for TIP-20 transfer subscriptions. */
+    export const TransferBody = OpenApi.component(
+      z
+        .object({
+          chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+          context: z.optional(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(TransferFilters),
+        })
+        .check(z.meta({ title: 'Transfer subscription' })),
+      'CreateWebhookTransferRequest',
+    )
+
+    /** Request variant for included transaction subscriptions. */
+    export const TransactionBody = OpenApi.component(
+      z
+        .object({
+          chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+          context: z.optional(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(TxFilters),
+        })
+        .check(z.meta({ title: 'Included-transaction subscription' })),
+      'CreateWebhookTransactionRequest',
+    )
+
+    /** Request variant for emitted log subscriptions. */
+    export const LogBody = OpenApi.component(
+      z
+        .object({
+          chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+          context: z.optional(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: LogFilters,
+        })
+        .check(z.meta({ title: 'Log subscription' })),
+      'CreateWebhookLogRequest',
+    )
+
+    /** Request variant for created block subscriptions. */
+    export const BlockBody = OpenApi.component(
+      z
+        .object({
+          chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+          context: z.optional(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(BlockFilters),
+        })
+        .check(z.meta({ title: 'Block subscription' })),
+      'CreateWebhookBlockRequest',
+    )
+
+    /** Request variant for route deposit subscriptions. */
+    export const RoutesDepositBody = OpenApi.component(
+      z
+        .object({
+          chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+          context: z.optional(Context),
+          destination: Destination,
+          eventType: z
+            .literal('routes:deposit.updated')
+            .check(
+              z.describe('Event type for committed route deposit changes.'),
+              z.meta({ examples: ['routes:deposit.updated'] }),
+            ),
+          filters: z.optional(RoutesDepositFilters),
+        })
+        .check(z.meta({ title: 'Route deposit subscription' })),
+      'CreateWebhookRoutesDepositRequest',
+    )
+
+    /** Request variant for route transfer subscriptions. */
+    export const RoutesTransferBody = OpenApi.component(
+      z
+        .object({
+          chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+          context: z.optional(Context),
+          destination: Destination,
+          eventType: z
+            .literal('routes:transfer.updated')
+            .check(
+              z.describe('Event type for committed route transfer changes.'),
+              z.meta({ examples: ['routes:transfer.updated'] }),
+            ),
+          filters: z.optional(RoutesTransferFilters),
+        })
+        .check(z.meta({ title: 'Route transfer subscription' })),
+      'CreateWebhookRoutesTransferRequest',
+    )
+
+    /**
+     * 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}).
+     */
+    export const Body = OpenApi.component(
+      z
+        .discriminatedUnion('eventType', [
+          TransferBody,
+          TransactionBody,
+          LogBody,
+          BlockBody,
+          RoutesDepositBody,
+          RoutesTransferBody,
+        ])
+        .check(z.describe('Details for creating a webhook subscription.')),
+      'CreateWebhookRequest',
+    )
+
+    export const Response = OpenApi.component(
+      z
+        .object({
+          ...Subscription.shape,
+          destination: Destination,
+          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.')),
+      'CreateWebhookResponse',
+    )
   }
 
   /** Schemas for the listWebhooks operation. */
@@ -1122,15 +1326,23 @@ export namespace schema {
         z.describe('Query parameters for listing your webhook subscriptions.'),
       )
 
-    export const Response = z
-      .object({
-        data: z.array(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.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Subscription)
+            .check(z.describe('Webhook subscriptions on this page.'), z.meta({ examples: [[]] })),
+          meta: z
+            .optional(Schema.CountMeta)
+            .check(
+              z.describe('Extra response metadata requested with `include`.'),
+              z.meta({ examples: [{ totalCount: 1, totalCountCapped: false }] }),
+            ),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of webhook subscriptions.')),
+      'WebhookList',
+    )
   }
 
   /** Schemas for the getWebhook operation. */
@@ -1165,55 +1377,69 @@ export namespace schema {
         z.describe('Query parameters for listing webhook delivery attempts.'),
       )
 
-    export const Response = z
-      .object({
-        data: z.array(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.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Delivery)
+            .check(
+              z.describe('Webhook delivery attempts on this page.'),
+              z.meta({ examples: [[]] }),
+            ),
+          meta: z
+            .optional(Schema.CountMeta)
+            .check(
+              z.describe('Extra response metadata requested with `include`.'),
+              z.meta({ examples: [{ totalCount: 1, totalCountCapped: false }] }),
+            ),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of webhook delivery attempts.')),
+      'WebhookDeliveryList',
+    )
   }
 
   /** Schemas for the pingWebhook operation. */
   export namespace pingWebhook {
     export const Params = getWebhook.Params
 
-    export const 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.'))
+    export const Response = OpenApi.component(
+      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 a webhook destination.')),
+      'PingWebhookResponse',
+    )
   }
 
   /** Schemas for the retryWebhookDelivery operation. */
@@ -1235,32 +1461,37 @@ export namespace schema {
       })
       .check(z.describe('Path parameters for retrying a webhook delivery.'))
 
-    export const Response = pingWebhook.Response
+    export const Response = OpenApi.component(pingWebhook.Response, 'RetryWebhookDeliveryResponse')
   }
 
   /** Schemas for the updateWebhook operation. */
   export namespace updateWebhook {
     export const Params = getWebhook.Params
 
-    export const Body = z
-      .object({
-        context: z
-          .optional(z.nullable(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(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.'))
+    export const Body = OpenApi.component(
+      z
+        .object({
+          context: z
+            .optional(z.nullable(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(Status)
+            .check(z.describe('New lifecycle status, such as pausing or resuming delivery.')),
+        })
+        .check(z.describe('Fields to update on the webhook subscription.')),
+      'UpdateWebhookRequest',
+    )
 
     export const Response = Subscription
   }
@@ -1269,16 +1500,19 @@ export namespace schema {
   export namespace deleteWebhook {
     export const Params = getWebhook.Params
 
-    export const Response = z
-      .object({
-        id: z
-          .string()
-          .check(
-            z.describe('ID of the webhook subscription that was deleted.'),
-            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-          ),
-      })
-      .check(z.describe('Confirmation that the webhook subscription was deleted.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          id: z
+            .string()
+            .check(
+              z.describe('ID of the webhook subscription that was deleted.'),
+              z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+            ),
+        })
+        .check(z.describe('Confirmation that the webhook subscription was deleted.')),
+      'DeleteWebhookResponse',
+    )
   }
 }
 
@@ -1293,8 +1527,7 @@ export function webhooks(options: webhooks.Options = {}) {
   const hidden = !options.enabled
   const availableEventTypes = eventTypeDescriptions.filter(
     (eventType) =>
-      eventType.type !== 'funding:deposit.updated' ||
-      options.applicationEventTypes?.includes(eventType.type),
+      !isRoutesEventType(eventType.type) || options.applicationEventTypes?.includes(eventType.type),
   )
   const availableEventTypeSet = new Set(availableEventTypes.map((eventType) => eventType.type))
   // Gate the whole resource on a configured state store. Without it the
@@ -1322,6 +1555,16 @@ export function webhooks(options: webhooks.Options = {}) {
           hide: hidden,
           operationId: 'getWebhookEventTypes',
           responses: OpenApi.responses({
+            errors: {
+              400: {
+                codes: [],
+                description: 'The API key credential is malformed.',
+              },
+              404: {
+                codes: ['webhooks_not_enabled'],
+                description: 'Webhooks are not enabled for this API deployment.',
+              },
+            },
             success: {
               description: 'Webhook event types available for subscription.',
               schema: schema.getWebhookEventTypes.Response,
@@ -1376,7 +1619,12 @@ export function webhooks(options: webhooks.Options = {}) {
               },
               403: {
                 codes: ['api_key_forbidden', 'limit_exceeded'],
-                description: 'The API key lacks access or the subscription limit was reached.',
+                description:
+                  'The API key lacks access or its creator-shared subscription limit was reached.',
+              },
+              404: {
+                codes: ['webhooks_not_enabled'],
+                description: 'Webhooks are not enabled for this API deployment.',
               },
             },
             success: {
@@ -1410,11 +1658,11 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Webhook event type is not available in this deployment',
               status: 400,
             })
-          if (body.eventType === 'funding:deposit.updated') {
+          if (isRoutesEventType(body.eventType)) {
             if (principal?.type !== 'api_key') return unauthorized(c)
             if (
               !principal.apiKey.scopes.some(
-                (scope) => scope === Scope.wildcard || scope === 'funding:read',
+                (scope) => scope === Scope.wildcard || scope === 'routes:read',
               )
             )
               return Response.error(c, {
@@ -1432,12 +1680,11 @@ export function webhooks(options: webhooks.Options = {}) {
             // Preserve destination errors before the creation-time RPC dependency.
             WebhookDestination.assertDestination(body.destination)
             const maxPerOwner = webhook.maxPerOwner ?? defaultMaxPerOwner
-            if ((await Webhooks.countSubscriptions(db, owner)) >= maxPerOwner)
+            if ((await Webhooks.countSubscriptionsForLimit(db, { owner })) >= maxPerOwner)
               throw new Webhooks.LimitExceededError(maxPerOwner)
-            const startBlockNumber =
-              body.eventType === 'funding:deposit.updated'
-                ? undefined
-                : await getRpcHead(c.get('getClient')(chainId))
+            const startBlockNumber = isRoutesEventType(body.eventType)
+              ? undefined
+              : await getRpcHead(c.get('getClient')(chainId))
             const subscription = await Webhooks.createSubscription(
               db,
               {
@@ -1483,6 +1730,16 @@ export function webhooks(options: webhooks.Options = {}) {
           hide: hidden,
           operationId: 'listWebhooks',
           responses: OpenApi.responses({
+            errors: {
+              400: {
+                codes: ['query_invalid'],
+                description: 'The query parameters are invalid.',
+              },
+              404: {
+                codes: ['webhooks_not_enabled'],
+                description: 'Webhooks are not enabled for this API deployment.',
+              },
+            },
             success: {
               description: 'A page of webhook subscriptions.',
               schema: schema.listWebhooks.Response,
@@ -1560,9 +1817,13 @@ export function webhooks(options: webhooks.Options = {}) {
           operationId: 'getWebhook',
           responses: OpenApi.responses({
             errors: {
+              400: {
+                codes: ['param_invalid'],
+                description: 'The webhook ID is invalid.',
+              },
               404: {
                 description: 'No webhook subscription was found for that ID.',
-                codes: ['webhook_not_found'],
+                codes: ['webhook_not_found', 'webhooks_not_enabled'],
               },
             },
             success: {
@@ -1617,9 +1878,13 @@ export function webhooks(options: webhooks.Options = {}) {
           operationId: 'listWebhookDeliveries',
           responses: OpenApi.responses({
             errors: {
+              400: {
+                codes: ['param_invalid', 'query_invalid'],
+                description: 'The webhook ID or query parameters are invalid.',
+              },
               404: {
                 description: 'No webhook subscription was found for that ID.',
-                codes: ['webhook_not_found'],
+                codes: ['webhook_not_found', 'webhooks_not_enabled'],
               },
             },
             success: {
@@ -1706,9 +1971,13 @@ export function webhooks(options: webhooks.Options = {}) {
           operationId: 'pingWebhook',
           responses: OpenApi.responses({
             errors: {
+              400: {
+                codes: ['param_invalid'],
+                description: 'The webhook ID is invalid.',
+              },
               404: {
                 description: 'No webhook subscription was found for that ID.',
-                codes: ['webhook_not_found'],
+                codes: ['webhook_not_found', 'webhooks_not_enabled'],
               },
             },
             success: {
@@ -1771,9 +2040,13 @@ export function webhooks(options: webhooks.Options = {}) {
           operationId: 'retryWebhookDelivery',
           responses: OpenApi.responses({
             errors: {
+              400: {
+                codes: ['param_invalid'],
+                description: 'The webhook or delivery ID is invalid.',
+              },
               404: {
                 description: 'No webhook subscription or delivery was found for those IDs.',
-                codes: ['webhook_not_found', 'delivery_not_found'],
+                codes: ['webhook_not_found', 'delivery_not_found', 'webhooks_not_enabled'],
               },
             },
             success: {
@@ -1859,7 +2132,7 @@ export function webhooks(options: webhooks.Options = {}) {
               },
               404: {
                 description: 'No webhook subscription was found for that ID.',
-                codes: ['webhook_not_found'],
+                codes: ['webhook_not_found', 'webhooks_not_enabled'],
               },
             },
             success: {
@@ -1926,9 +2199,13 @@ export function webhooks(options: webhooks.Options = {}) {
           operationId: 'deleteWebhook',
           responses: OpenApi.responses({
             errors: {
+              400: {
+                codes: ['param_invalid'],
+                description: 'The webhook ID is invalid.',
+              },
               404: {
                 description: 'No webhook subscription was found for that ID.',
-                codes: ['webhook_not_found'],
+                codes: ['webhook_not_found', 'webhooks_not_enabled'],
               },
             },
             success: {
@@ -2088,7 +2365,8 @@ export async function getRpcHead(client: Viem.getClient.ReturnType): Promise<num
 
 const filterSchemas = {
   'block:created': schema.BlockFilters,
-  'funding:deposit.updated': schema.FundingDepositFilters,
+  'routes:deposit.updated': schema.RoutesDepositFilters,
+  'routes:transfer.updated': schema.RoutesTransferFilters,
   'log:emitted': schema.LogFilters,
   'token:transfer': schema.TransferFilters,
   'transaction:included': schema.TxFilters,
@@ -2340,8 +2618,18 @@ function pushEventArgs(args: Record<string, unknown> | undefined, event: AbiEven
   return pushed
 }
 
+type LogPushdownFilters = {
+  address?: unknown
+  args?: Record<string, unknown> | undefined
+  signature?: string | undefined
+  topic0?: unknown
+  topic1?: unknown
+  topic2?: unknown
+  topic3?: unknown
+}
+
 /** Checks that the accepted filter carries a selective anchor rather than matching every log. */
-function hasLogPushdown(f: z.output<typeof schema.LogFilters>): boolean {
+function hasLogPushdown(f: LogPushdownFilters): boolean {
   if (pushAddress(f.address) !== undefined) return true
 
   const secondaryTopic = [f.topic1, f.topic2, f.topic3].some(
@@ -2611,8 +2899,7 @@ function toPublic(subscription: Webhooks.Subscription) {
     ...(subscription.context === undefined ? {} : { context: subscription.context }),
     createdAt: subscription.createdAt,
     destination: redactDestination(subscription.destination),
-    ...(subscription.eventType === 'funding:deposit.updated' &&
-    subscription.environment !== undefined
+    ...(isRoutesEventType(subscription.eventType) && subscription.environment !== undefined
       ? { environment: subscription.environment }
       : {}),
     eventType: subscription.eventType,