tapimo 0.11.0 → 0.12.0

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

@@ -18,7 +18,26 @@ const redactedSlackUrl = 'https://hooks.slack.com/…'
 /** OpenAPI schemas owned by console webhook management. */
 export namespace schema {
   /** Public webhook subscription representation. */
-  export const Subscription = webhookSchema.Subscription
+  export const Subscription = OpenApi.component(
+    z
+      .object({
+        ...webhookSchema.Subscription.shape,
+        context: webhookSchema.Subscription.shape.context.check(
+          z.meta({ examples: [{ title: 'Production transfers' }] }),
+        ),
+        destination: webhookSchema.Subscription.shape.destination.check(
+          z.meta({ examples: [{ type: 'url', url: 'https://example.com/webhooks' }] }),
+        ),
+      })
+      .check(z.describe('An organization webhook subscription.')),
+    'OrganizationWebhook',
+  )
+
+  /** Webhook delivery data returned in collection rows. */
+  export const Delivery = OpenApi.component(
+    webhookSchema.Delivery,
+    'OrganizationWebhookDeliverySummary',
+  )
 
   /** Schemas for creating an organization webhook. */
   export namespace createWebhook {
@@ -30,61 +49,119 @@ export namespace schema {
       )
 
     /** Organization webhook creation requires an explicit network. */
-    export const Body = z
-      .intersection(
-        webhookSchema.createWebhook.Body,
-        z.object({
-          chainId: webhookSchema.Subscription.shape.chainId,
-          environment: z.optional(Environment),
-        }),
-      )
-      .check(
-        z.refine(
-          (body) => body.eventType !== 'funding:deposit.updated' || body.environment !== undefined,
-          { error: '`environment` is required for funding deposit subscriptions.' },
+    export const Body = OpenApi.component(
+      z
+        .intersection(
+          webhookSchema.createWebhook.Body,
+          z.object({
+            chainId: webhookSchema.Subscription.shape.chainId,
+            environment: z.optional(Environment),
+          }),
+        )
+        .check(
+          z.refine(
+            (body) =>
+              body.eventType !== 'funding:deposit.updated' || body.environment !== undefined,
+            { error: '`environment` is required for funding deposit subscriptions.' },
+          ),
+          z.describe('Details for creating an organization webhook subscription.'),
         ),
-        z.describe('Details for creating an organization webhook subscription.'),
-      )
+      'CreateOrganizationWebhookRequest',
+    )
 
     const secret = webhookSchema.createWebhook.Response.shape.secret
-    const urlDestination = z.object({
-      type: z.literal('url'),
-      url: z
-        .url()
-        .check(
-          z.describe('Your HTTPS endpoint where Tempo sends signed event POSTs.'),
-          z.meta({ examples: ['https://example.com/webhooks'] }),
-        ),
-    })
-    const slackDestination = z.object({
-      type: z.literal('slack'),
-      url: z.literal(redactedSlackUrl).check(z.describe('Redacted Slack webhook URL.')),
-    })
-    const betterstackDestination = z.object({
-      token: z
-        .literal(redactedBetterstackToken)
-        .check(z.describe('Redacted Better Stack source token.')),
-      type: z.literal('betterstack'),
-      url: z
-        .url()
-        .check(
-          z.describe('Your Better Stack source ingest host URL.'),
-          z.meta({ examples: ['https://s1234567.eu-nbg-2.betterstackdata.com'] }),
-        ),
-    })
+    const urlDestination = z
+      .object({
+        type: z
+          .literal('url')
+          .check(z.describe('HTTPS destination.'), z.meta({ examples: ['url'] })),
+        url: z
+          .url()
+          .check(
+            z.describe('Your HTTPS endpoint where Tempo sends signed event POSTs.'),
+            z.meta({ examples: ['https://example.com/webhooks'] }),
+          ),
+      })
+      .check(
+        z.describe('HTTPS webhook destination.'),
+        z.meta({ examples: [{ type: 'url', url: 'https://example.com/webhooks' }] }),
+      )
+    const slackDestination = z
+      .object({
+        type: z
+          .literal('slack')
+          .check(z.describe('Slack destination.'), z.meta({ examples: ['slack'] })),
+        url: z
+          .literal(redactedSlackUrl)
+          .check(
+            z.describe('Redacted Slack webhook URL.'),
+            z.meta({ examples: [redactedSlackUrl] }),
+          ),
+      })
+      .check(
+        z.describe('Slack webhook destination with its URL redacted.'),
+        z.meta({ examples: [{ type: 'slack', url: redactedSlackUrl }] }),
+      )
+    const betterstackDestination = z
+      .object({
+        token: z
+          .literal(redactedBetterstackToken)
+          .check(
+            z.describe('Redacted Better Stack source token.'),
+            z.meta({ examples: [redactedBetterstackToken] }),
+          ),
+        type: z
+          .literal('betterstack')
+          .check(z.describe('Better Stack destination.'), z.meta({ examples: ['betterstack'] })),
+        url: z
+          .url()
+          .check(
+            z.describe('Your Better Stack source ingest host URL.'),
+            z.meta({ examples: ['https://s1234567.eu-nbg-2.betterstackdata.com'] }),
+          ),
+      })
+      .check(
+        z.describe('Better Stack destination with its token redacted.'),
+        z.meta({
+          examples: [
+            {
+              token: redactedBetterstackToken,
+              type: 'betterstack',
+              url: 'https://s1234567.eu-nbg-2.betterstackdata.com',
+            },
+          ],
+        }),
+      )
+    const UrlResponse = OpenApi.component(
+      z
+        .object({ ...Subscription.shape, destination: urlDestination, secret })
+        .check(z.describe('Created HTTPS webhook with its one-time signing secret.')),
+      'CreateOrganizationWebhookUrlResponse',
+    )
+    const SlackResponse = OpenApi.component(
+      z
+        .object({ ...Subscription.shape, destination: slackDestination })
+        .check(z.describe('Created Slack webhook with its destination redacted.')),
+      'CreateOrganizationWebhookSlackResponse',
+    )
+    const BetterstackResponse = OpenApi.component(
+      z
+        .object({ ...Subscription.shape, destination: betterstackDestination })
+        .check(z.describe('Created Better Stack webhook with its credentials redacted.')),
+      'CreateOrganizationWebhookBetterstackResponse',
+    )
 
     /** Created webhook with transport credentials redacted. */
-    export const Response = z
-      .union([
-        z.object({ ...Subscription.shape, destination: urlDestination, secret }),
-        z.object({ ...Subscription.shape, destination: slackDestination }),
-        z.object({ ...Subscription.shape, destination: betterstackDestination }),
-      ])
-      .check(
-        z.describe(
-          'The new webhook subscription. HTTPS endpoints include their one-time signing secret.',
+    export const Response = OpenApi.component(
+      z
+        .union([UrlResponse, SlackResponse, BetterstackResponse])
+        .check(
+          z.describe(
+            'The new webhook subscription. HTTPS endpoints include their one-time signing secret.',
+          ),
         ),
-      )
+      'CreateOrganizationWebhookResponse',
+    )
   }
 
   /** Organization webhook collection parameters. */
@@ -116,7 +193,23 @@ export namespace schema {
   export namespace listWebhookDeliveries {
     export const Params = WebhookParams
     export const Query = webhookSchema.listWebhookDeliveries.Query
-    export const Response = webhookSchema.listWebhookDeliveries.Response
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Delivery)
+            .check(
+              z.describe('Webhook delivery attempts on this page.'),
+              z.meta({ examples: [[]] }),
+            ),
+          meta: webhookSchema.listWebhookDeliveries.Response.shape.meta.check(
+            z.meta({ examples: [{ totalCount: 1, totalCountCapped: false }] }),
+          ),
+          nextCursor: webhookSchema.listWebhookDeliveries.Response.shape.nextCursor,
+        })
+        .check(z.describe("A page of an organization's webhook delivery attempts.")),
+      'OrganizationWebhookDeliveryList',
+    )
   }
 
   const DeliveryParams = z
@@ -130,43 +223,63 @@ export namespace schema {
   /** Schemas for loading one organization webhook delivery. */
   export namespace getWebhookDelivery {
     export const Params = DeliveryParams
-    export const Response = z
-      .object({
-        ...webhookSchema.Delivery.shape,
-        envelope: webhookSchema.Envelope,
-      })
-      .check(z.describe('A webhook delivery attempt with the exact JSON payload Tempo sent.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          ...Delivery.shape,
+          envelope: webhookSchema.Envelope,
+        })
+        .check(z.describe('A webhook delivery attempt with the exact JSON payload Tempo sent.')),
+      'OrganizationWebhookDelivery',
+    )
   }
 
   /** Schemas for replaying one organization webhook delivery. */
   export namespace retryWebhookDelivery {
     export const Params = DeliveryParams
-    export const Response = webhookSchema.retryWebhookDelivery.Response
+    export const Response = OpenApi.component(
+      webhookSchema.retryWebhookDelivery.Response,
+      'RetryOrganizationWebhookDeliveryResponse',
+    )
   }
 
   /** Non-paginated organization webhook list. */
-  export const ListResponse = z
-    .object({
-      data: z.array(Subscription).check(z.describe("The organization's webhooks, newest first.")),
-    })
-    .check(z.describe("An organization's webhook subscriptions."))
+  export const ListResponse = OpenApi.component(
+    z
+      .object({
+        data: z
+          .array(Subscription)
+          .check(
+            z.describe("The organization's webhooks, newest first."),
+            z.meta({ examples: [[]] }),
+          ),
+      })
+      .check(z.describe("An organization's webhook subscriptions.")),
+    'OrganizationWebhookList',
+  )
 
   /** Lifecycle state editable from the console. */
-  export const UpdateBody = z
-    .object({ status: webhookSchema.Status })
-    .check(z.describe('New delivery state for a webhook subscription.'))
+  export const UpdateBody = OpenApi.component(
+    z
+      .object({ status: webhookSchema.Status })
+      .check(z.describe('New delivery state for a webhook subscription.')),
+    'UpdateOrganizationWebhookRequest',
+  )
 
   /** Webhook deletion confirmation. */
-  export const DeleteResponse = z
-    .object({
-      id: z
-        .string()
-        .check(
-          z.describe('Deleted webhook subscription id.'),
-          z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-    })
-    .check(z.describe('Confirmation that a webhook subscription was deleted.'))
+  export const DeleteResponse = OpenApi.component(
+    z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.describe('Deleted webhook subscription id.'),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Confirmation that a webhook subscription was deleted.')),
+    'DeleteOrganizationWebhookResponse',
+  )
 }
 
 const bodyValidation = {
@@ -542,7 +655,7 @@ export function webhooks(options: webhooks.Options = {}) {
           },
           success: {
             description: 'Updated webhook.',
-            schema: webhookSchema.Subscription,
+            schema: schema.Subscription,
           },
         }),
         summary: 'Update webhook',
@@ -564,7 +677,7 @@ export function webhooks(options: webhooks.Options = {}) {
           )
           if (!subscription) return notFound(c)
           return c.json(
-            Response.validated(webhookSchema.Subscription, publicSubscription(subscription)),
+            Response.validated(schema.Subscription, publicSubscription(subscription)),
             200,
           )
         } catch (cause) {

package/src/apps/mpp/internal/Adapter.ts

@@ -1,9 +1,10 @@
 import * as Mppx from 'mppx'
 import { tempo } from 'mppx/server'
+import { maxUint256 } from 'viem'
 import type { LocalAccount } from 'viem/accounts'
 
-import type * as Viem from '../../../internal/Viem.js'
 import * as Store from '../../../internal/Store.js'
+import * as Viem from '../../../internal/Viem.js'
 import * as Mpp from '../Mpp.js'
 import * as MppError from './Error.js'
 import * as Screening from './Screening.js'
@@ -37,9 +38,20 @@ export function create(options: create.Options): Adapter {
     store: screeningStore,
     ttl: screeningTtl,
   })
+  // Moderato fees exceed MPPX defaults; preserve its gas cap and bound each
+  // sponsored transaction to $1.
+  const feePayerPolicy =
+    chainId === Viem.chainId.testnet
+      ? {
+          maxFeePerGas: maxUint256,
+          maxPriorityFeePerGas: maxUint256,
+          maxTotalFee: 1_000_000_000_000_000_000n,
+        }
+      : undefined
   const methods = [
     tempo.charge({
       ...(feePayer ? { feePayer } : {}),
+      ...(feePayerPolicy ? { feePayerPolicy } : {}),
       getClient: ({ chainId: chainId_option }) =>
         getClient(chainId_option as Viem.ChainId | undefined),
       store: Utils.mppxStore(state),

package/src/db/Db.test.ts

@@ -3,6 +3,7 @@ import { nanoid } from 'nanoid'
 
 import * as Runtime from '../../test/runtime.js'
 import * as Db from './Db.js'
+import * as Webhooks from '../internal/Webhooks.js'
 import * as Invitations from './tables/invitations.js'
 import * as Organizations from './tables/organizations.js'
 import * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
@@ -35,6 +36,46 @@ describe('postgres', () => {
     await db.close()
   })
 
+  test('behavior: raw webhook staging respects schema scoping', async () => {
+    // Exercises the one raw statement against a schema-scoped db whose only
+    // qualification is WithSchemaPlugin, matching preview Workers: migrate on
+    // one pool (whose session gains a search_path), then query from a fresh
+    // pool that never ran it.
+    const schema = `t_${nanoid()}`
+    const migrator = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    await migrator.migrate()
+    await migrator.close()
+    const db = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    const subscription = await Webhooks.createSubscription(db, {
+      chainId: 4217,
+      destination: { type: 'url', url: 'https://hooks.example.com/endpoint' },
+      eventType: 'token:transfer',
+      owner: { orgId: 'org_1', type: 'api_key' },
+    })
+    const envelope = Webhooks.buildEnvelope({
+      blockNumber: 123,
+      createdAt: new Date(),
+      data: { amount: '1' },
+      logIndex: 4,
+      subscription,
+    })
+
+    const staged = await Webhooks.ensureQueueEvents(db, [{ envelope, subscription }])
+    expect(staged.created).toBe(1)
+    const claim = await Webhooks.claimQueueEvent(db, staged.references[0]!)
+    if (claim.type !== 'claimed') throw new Error(`Unexpected claim: ${claim.type}`)
+    await Webhooks.completeQueueEvent(db, staged.references[0]!, {
+      claimedAt: claim.record.attemptingAt!,
+      status: 'succeeded',
+    })
+
+    // The completion read inside the same raw statement must also resolve
+    // inside the schema for the replay to be suppressed.
+    const replay = await Webhooks.ensureQueueEvents(db, [{ envelope, subscription }])
+    expect(replay.created).toBe(0)
+    await db.close()
+  })
+
   test('behavior: creates a Postgres db without schema scoping', async () => {
     const db = Db.postgres({ connectionString: Runtime.postgresUrl })
     await db.close()

package/src/db/Db.ts

@@ -36,6 +36,7 @@ import type * as Users from './tables/users.js'
 import type * as VerifiedTokenRequests from './tables/verifiedTokenRequests.js'
 import type * as VerifiedTokens from './tables/verifiedTokens.js'
 import type * as WebhookDeliveries from './tables/webhookDeliveries.js'
+import type * as WebhookQueueCompletions from './tables/webhookQueueCompletions.js'
 import type * as WebhookQueueEvents from './tables/webhookQueueEvents.js'
 import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
 
@@ -83,6 +84,7 @@ export type Database = {
   verified_token_requests: VerifiedTokenRequests.Table
   verified_tokens: VerifiedTokens.Table
   webhook_deliveries: WebhookDeliveries.Table
+  webhook_queue_completions: WebhookQueueCompletions.Table
   webhook_queue_events: WebhookQueueEvents.Table
   webhook_subscriptions: WebhookSubscriptions.Table
 }
@@ -1421,6 +1423,66 @@ export const migrations: readonly Migration[] = [
     up: (db) =>
       raw(db, sql`ALTER TABLE webhook_queue_events ADD COLUMN IF NOT EXISTS observed_at text`),
   },
+  {
+    name: '0131_webhook_queue_completions',
+    up: (db) =>
+      db.schema
+        .createTable('webhookQueueCompletions')
+        .ifNotExists()
+        .addColumn('subscriptionId', 'text', (c) =>
+          c.notNull().references('webhookSubscriptions.id').onDelete('cascade'),
+        )
+        .addColumn('eventId', 'text', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull())
+        .addColumn('expiresAt', 'text', (c) => c.notNull())
+        .addPrimaryKeyConstraint('webhook_queue_completions_pkey', ['subscriptionId', 'eventId'])
+        .addCheckConstraint(
+          'webhook_queue_completions_status_check',
+          sql`status IN ('failed', 'skipped', 'succeeded')`,
+        ),
+  },
+  {
+    name: '0132_webhook_queue_completions_expires_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_queue_completions_expires_idx')
+        .ifNotExists()
+        .on('webhookQueueCompletions')
+        .column('expiresAt'),
+  },
+  {
+    // Stock thresholds let ~2M dead tuples accumulate before vacuuming, then
+    // grind gigabytes at once; frequent small vacuums keep indexes usable.
+    name: '0133_webhook_queue_events_autovacuum',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE webhook_queue_events SET (autovacuum_vacuum_scale_factor = 0.01, autovacuum_vacuum_cost_limit = 2000)`,
+      ),
+  },
+  {
+    // New code stops writing queue-event expiry: completions own the dedupe
+    // window, so the column is nullable and inert.
+    name: '0134_webhook_queue_events_expires_nullable',
+    up: (db) =>
+      raw(db, sql`ALTER TABLE webhook_queue_events ALTER COLUMN expires_at DROP NOT NULL`),
+  },
+  {
+    name: '0135_webhook_queue_completions_autovacuum',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE webhook_queue_completions SET (autovacuum_vacuum_scale_factor = 0.01, autovacuum_vacuum_cost_limit = 2000)`,
+      ),
+  },
+  {
+    name: '0136_earn_vault_zones',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE earn_vaults ADD COLUMN IF NOT EXISTS zones jsonb NOT NULL DEFAULT '[]'::jsonb`,
+      ),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -1,6 +1,7 @@
 import * as z from 'zod/mini'
 import type { Address } from 'viem'
 
+import type * as EarnVaults from '../internal/EarnVaults.js'
 import type * as funding_Catalog from '../internal/funding/Catalog.js'
 import type * as funding_Deposit from '../internal/funding/Deposit.js'
 import type * as funding_DepositAddress from '../internal/funding/DepositAddress.js'
@@ -106,6 +107,9 @@ export const EarnVault = z
     slug: z.string().check(z.describe('Stable URL slug assigned when the vault is registered.')),
     updatedAt: z.string().check(z.describe('When the vault registration last changed (ISO 8601).')),
     vaultAddress: z.custom<Address>().check(z.describe('Earn vault address (lowercase).')),
+    zones: z
+      .custom<readonly EarnVaults.ZoneRoute[]>()
+      .check(z.describe('Curated private Zone routes (`jsonb`).')),
   })
   .check(z.describe('One curated Earn vault row.'))
 
@@ -881,6 +885,23 @@ export const WebhookDelivery = z.object({
 /** Columns of the `webhook_deliveries` table. */
 export type WebhookDelivery = z.output<typeof WebhookDelivery>
 
+/** An insert-only dedupe record marking a delivery obligation terminal. */
+export const WebhookQueueCompletion = z.object({
+  eventId: z.string().check(z.describe('Idempotent event id (`evt_...`).')),
+  expiresAt: z
+    .string()
+    .check(z.describe('ISO dedupe retention deadline; rows past it are invisible and pruned.')),
+  status: z
+    .enum(['failed', 'skipped', 'succeeded'])
+    .check(z.describe('Terminal delivery-obligation outcome.')),
+  subscriptionId: z
+    .string()
+    .check(z.describe('Owning subscription id (`wh_...`); FK with `ON DELETE CASCADE`.')),
+})
+
+/** Columns of the `webhook_queue_completions` table. */
+export type WebhookQueueCompletion = z.output<typeof WebhookQueueCompletion>
+
 /** A durable webhook envelope staged before its compact Queue reference is admitted. */
 export const WebhookQueueEvent = z.object({
   attemptCount: z.number().check(z.describe('Delivery attempts claimed so far.')),
@@ -893,10 +914,10 @@ export const WebhookQueueEvent = z.object({
     .check(z.describe('The full webhook envelope retained outside Cloudflare Queues.')),
   eventId: z.string().check(z.describe('Idempotent event id (`evt_...`).')),
   expiresAt: z
-    .string()
+    .nullable(z.string())
     .check(
       z.describe(
-        'ISO dedupe retention deadline, restarted at terminal transitions; inert while pending.',
+        'Unwritten since completions took over dedupe; non-null only on rows staged before the split.',
       ),
     ),
   nextAttemptAt: z
@@ -911,7 +932,11 @@ export const WebhookQueueEvent = z.object({
     ),
   status: z
     .enum(['failed', 'pending', 'skipped', 'succeeded'])
-    .check(z.describe('Delivery-obligation lifecycle status.')),
+    .check(
+      z.describe(
+        'Always `pending` since completions took over terminal state; other values occur only on rows completed before the split.',
+      ),
+    ),
   subscriptionId: z
     .string()
     .check(z.describe('Owning subscription id (`wh_...`); FK with `ON DELETE CASCADE`.')),

package/src/db/tables/earnVaults.test.ts

@@ -11,6 +11,13 @@ const input = {
   ],
   privateOutputTokens: ['0x20c00000000000000000000057F242B21a53ae4D'],
   vaultAddress: '0x2f05f4d3625B2eFFb383eFbEDAFd2D8F04371636',
+  zones: [
+    {
+      chainId: 1_424_310_001,
+      deploymentBlock: 31_039_238,
+      earnRouter: '0x9144086A79dea966d8bf1B52125eBED8919fC45c',
+    },
+  ],
 } as const satisfies EarnVaults.upsert.Options
 
 describe('upsert', () => {
@@ -36,6 +43,13 @@ describe('upsert', () => {
           ],
           "updatedAt": "2026-01-01T00:00:00.000Z",
           "vaultAddress": "0x2f05f4d3625b2effb383efbedafd2d8f04371636",
+          "zones": [
+            {
+              "chainId": 1424310001,
+              "deploymentBlock": 31039238,
+              "earnRouter": "0x9144086a79dea966d8bf1b52125ebed8919fc45c",
+            },
+          ],
         }
       `)
     } finally {
@@ -68,6 +82,7 @@ describe('upsert', () => {
         privateInputTokens: stored.privateInputTokens,
         privateOutputTokens: stored.privateOutputTokens,
         updatedAt: stored.updatedAt,
+        zones: stored.zones,
       }).toMatchInlineSnapshot(`
         {
           "createdAt": "2026-01-01T00:00:00.000Z",
@@ -76,6 +91,13 @@ describe('upsert', () => {
           "privateInputTokens": [],
           "privateOutputTokens": [],
           "updatedAt": "2026-01-02T00:00:00.000Z",
+          "zones": [
+            {
+              "chainId": 1424310001,
+              "deploymentBlock": 31039238,
+              "earnRouter": "0x9144086a79dea966d8bf1b52125ebed8919fc45c",
+            },
+          ],
         }
       `)
 

package/src/db/tables/earnVaults.ts

@@ -10,7 +10,7 @@ const slugSuffix = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 8)
 /** Columns of the `earn_vaults` table. */
 export type Table = Omit<
   db_Schema.EarnVault,
-  'chainId' | 'privateInputTokens' | 'privateOutputTokens'
+  'chainId' | 'privateInputTokens' | 'privateOutputTokens' | 'zones'
 > & {
   /** Bigint chain id, read as a string from pg and written as a number. */
   chainId: ColumnType<string, number, number>
@@ -18,6 +18,8 @@ export type Table = Omit<
   privateInputTokens: JSONColumnType<db_Schema.EarnVault['privateInputTokens'], string, string>
   /** Tokens supported for private redemptions. */
   privateOutputTokens: JSONColumnType<db_Schema.EarnVault['privateOutputTokens'], string, string>
+  /** Curated private Zone routes. */
+  zones: JSONColumnType<db_Schema.EarnVault['zones'], string, string>
 }
 
 /** A stored curated Earn vault. */
@@ -76,6 +78,7 @@ export async function upsert(db: Db.Db, options: upsert.Options): Promise<Record
       slug,
       updatedAt: now,
       vaultAddress: normalize(options.vaultAddress),
+      zones: JSON.stringify(normalizeZones(options.zones)),
     })
     .onConflict((oc) =>
       oc.columns(['chainId', 'vaultAddress']).doUpdateSet({
@@ -85,6 +88,7 @@ export async function upsert(db: Db.Db, options: upsert.Options): Promise<Record
         privateOutputTokens: JSON.stringify(options.privateOutputTokens),
         ...(options.slug !== undefined ? { slug } : {}),
         updatedAt: now,
+        zones: JSON.stringify(normalizeZones(options.zones)),
       }),
     )
     .returningAll()
@@ -109,6 +113,8 @@ export declare namespace upsert {
     slug?: string | undefined
     /** Earn vault address. */
     vaultAddress: Address
+    /** Curated private Zone routes. */
+    zones: db_Schema.EarnVault['zones']
   }
 }
 
@@ -149,3 +155,7 @@ function toRecord(row: Selectable<Table>): Record {
 function normalize(address: string): Address {
   return address.toLowerCase() as Address
 }
+
+function normalizeZones(zones: db_Schema.EarnVault['zones']): db_Schema.EarnVault['zones'] {
+  return zones.map((zone) => ({ ...zone, earnRouter: normalize(zone.earnRouter) }))
+}