tapimo 0.7.0 → 0.7.2

package/src/db/Schema.ts

@@ -1,5 +1,12 @@
 import * as z from 'zod/mini'
-
+import type { Address } from 'viem'
+
+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'
+import type * as funding_Provider from '../internal/funding/Provider.js'
+import type * as funding_Transfer from '../internal/funding/Transfer.js'
+import type * as internal_Schema from '../internal/Schema.js'
 import type * as Webhooks from '../internal/Webhooks.js'
 
 /** One authenticated administrator access to a protected admin API route. */
@@ -81,6 +88,30 @@ export const EnabledBillingSource = z.object({
 /** Columns of the `enabled_billing_sources` table. */
 export type EnabledBillingSource = z.output<typeof EnabledBillingSource>
 
+/** One curated Earn vault. */
+export const EarnVault = z
+  .object({
+    chainId: z.number().check(z.int(), z.describe('Chain the deployment belongs to.')),
+    createdAt: z.string().check(z.describe('When the vault was registered (ISO 8601).')),
+    description: z
+      .nullable(z.string())
+      .check(z.describe('Curated vault description, or null when absent.')),
+    label: z.string().check(z.describe('Curated vault label.')),
+    privateInputTokens: z
+      .custom<readonly Address[]>()
+      .check(z.describe('Tokens accepted for private deposits (`jsonb`).')),
+    privateOutputTokens: z
+      .custom<readonly Address[]>()
+      .check(z.describe('Tokens supported for private redemptions (`jsonb`).')),
+    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).')),
+  })
+  .check(z.describe('One curated Earn vault row.'))
+
+/** Columns of the `earn_vaults` table. */
+export type EarnVault = z.output<typeof EarnVault>
+
 /** A pending, expiring offer of organization membership. */
 export const Invitation = z.object({
   acceptedAt: z
@@ -250,7 +281,9 @@ export const SponsoredTransaction = z.object({
     .nullable(z.string())
     .check(z.describe('When the row was reported to the billing meter (ISO 8601), or null; exactly-once marker.')), // prettier-ignore
   orgId: z.string().check(z.describe('Organization id (`org_…`) the spend attributes to.')),
-  projectId: z.string().check(z.describe('Project id (`prj_…`) the spend attributes to.')),
+  projectId: z
+    .nullable(z.string())
+    .check(z.describe('Project id (`prj_…`) the spend attributes to, or null for organization-level spend.')), // prettier-ignore
   signPayload: z
     .string()
     .check(z.describe('Fee-payer sign payload — a stable identity for the sponsored envelope.')),
@@ -361,6 +394,296 @@ export const User = z.object({
 /** Columns of the `users` table. */
 export type User = z.output<typeof User>
 
+/** Metadata for the current funding catalog snapshot. */
+export const FundingCatalog = z.object({
+  id: z.string().check(z.describe('Singleton funding catalog id.')),
+  updatedAt: z.string().check(z.describe('When the funding catalog was last published.')),
+  version: z.string().check(z.describe('Opaque funding catalog version.')),
+})
+
+/** Columns of the `funding_catalogs` table. */
+export type FundingCatalog = z.output<typeof FundingCatalog>
+
+/** One chain available to the funding catalog. */
+export const FundingChain = z.object({
+  aliases: z
+    .readonly(z.array(z.string()))
+    .check(z.describe('Caller-facing aliases accepted for the funding chain.')),
+  id: z.string().check(z.describe('CAIP-2 funding chain identifier.')),
+  name: z.string().check(z.describe('Human-readable funding chain name.')),
+  parentChainId: z
+    .nullable(z.string())
+    .check(z.describe('Parent funding chain identifier for a Zone, or null.')),
+  rpcUrls: z
+    ._default(z.readonly(z.array(z.url())), [])
+    .check(z.describe('Public RPC endpoints used for funding-chain evidence.')),
+  slug: z.string().check(z.describe('Stable funding chain slug.')),
+})
+
+/** Columns of the `funding_chains` table. */
+export type FundingChain = z.output<typeof FundingChain>
+
+/** One token available to the funding catalog. */
+export const FundingToken = z.object({
+  currency: z.string().check(z.describe('Monetary denomination represented by the token.')),
+  id: z.string().check(z.describe('Stable funding token identifier.')),
+  name: z.string().check(z.describe('Human-readable funding token name.')),
+  symbol: z.string().check(z.describe('Funding token ticker symbol.')),
+})
+
+/** Columns of the `funding_tokens` table. */
+export type FundingToken = z.output<typeof FundingToken>
+
+/** Chain-specific metadata for one funding token. */
+export const FundingChainToken = z.object({
+  address: z.string().check(z.describe('Token address on the funding chain.')),
+  chainId: z.string().check(z.describe('CAIP-2 identifier of the funding chain.')),
+  decimals: z.number().check(z.int(), z.nonnegative(), z.describe('Token decimal precision.')),
+  name: z.nullable(z.string()).check(z.describe('Chain-specific token name override, or null.')),
+  standard: z.string().check(z.describe('Token standard on the funding chain.')),
+  tokenId: z.string().check(z.describe('Stable funding token identifier.')),
+})
+
+/** Columns of the `funding_chain_tokens` table. */
+export type FundingChainToken = z.output<typeof FundingChainToken>
+
+/** One source-to-destination route supported by a funding provider. */
+export const FundingRoute = z.object({
+  destinationChainId: z.string().check(z.describe('Destination funding chain identifier.')),
+  destinationTokenId: z.string().check(z.describe('Destination funding token identifier.')),
+  capabilities: z
+    .nullable(z.custom<funding_Catalog.Capabilities>())
+    .check(z.describe('Executable capability (`jsonb`), or null for indicative-only routes.')),
+  providerId: z.string().check(z.describe('Funding provider identifier.')),
+  sourceChainId: z.string().check(z.describe('Source funding chain identifier.')),
+  sourceTokenId: z.string().check(z.describe('Source funding token identifier.')),
+})
+
+/** Columns of the `funding_routes` table. */
+export type FundingRoute = z.output<typeof FundingRoute>
+
+/**
+ * A reusable funding deposit address. Public route fields live in `snapshot`;
+ * provider routing and correlation remain private.
+ */
+export const FundingDepositAddress = z.object({
+  address: z.string().check(z.describe('Reusable source-chain deposit address.')),
+  apiKeyId: z.string().check(z.describe('API key id (`key_…`) that provisioned the address.')),
+  createdAt: z.string().check(z.describe('When the address was created (ISO 8601).')),
+  deliveryStrategy: z
+    .custom<funding_DepositAddress.DeliveryStrategy>()
+    .check(z.describe('Whether the provider or Tempo delivers the requested destination token.')),
+  destinationTokenKey: z.string().check(z.describe('Customer destination token key.')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Key environment the address belongs to.')),
+  id: z.string().check(z.describe('Funding deposit address id (`fda_…`).')),
+  lastPolledAt: z
+    .nullable(z.string())
+    .check(z.describe('When provider reconciliation last completed successfully, or null.')),
+  nextPollAt: z.string().check(z.describe('When provider reconciliation is next due.')),
+  orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  pollFailureCount: z.number().check(z.int(), z.describe('Consecutive reconciliation failures.')),
+  pollLeaseUntil: z
+    .nullable(z.string())
+    .check(z.describe('When the current reconciliation lease expires, or null.')),
+  pollLeaseVersion: z
+    .number()
+    .check(z.int(), z.describe('Fencing token for reconciliation leases.')),
+  projectId: z.nullable(z.string()).check(z.describe('Attributed project id (`prj_…`), or null.')),
+  providerOutputToken: z
+    .custom<funding_Provider.TokenRef>()
+    .check(z.describe('Token that the provider outputs on Tempo (`jsonb`).')),
+  providerId: z.string().check(z.describe('Selected funding provider id.')),
+  providerRequestIds: z
+    .readonly(z.array(z.string()))
+    .check(z.describe('Private provider request identifiers (`jsonb`).')),
+  providerState: z
+    .nullable(z.custom<funding_DepositAddress.ProviderState>())
+    .check(z.describe('Bounded private provider state (`jsonb`), or null.')),
+  recipient: z.string().check(z.describe('Tempo account that receives completed deposits.')),
+  refundAddress: z.string().check(z.describe('Source-chain refund address.')),
+  snapshot: z
+    .custom<funding_DepositAddress.Snapshot>()
+    .check(z.describe('Public address fields (`jsonb`).')),
+  sourceChainId: z.string().check(z.describe('Source chain CAIP-2 id.')),
+  sourceTokenKey: z.string().check(z.describe('Source token key.')),
+  status: z.custom<funding_DepositAddress.Status>().check(z.describe('Lifecycle status.')),
+  subsidize: z.boolean().check(z.describe('Whether Tempo guarantees normalized 1:1 delivery.')),
+  updatedAt: z.string().check(z.describe('When the address last materially changed (ISO 8601).')),
+  version: z.number().check(z.int(), z.describe('Material version used to guard updates.')),
+})
+
+/** Columns of the `funding_deposit_addresses` table. */
+export type FundingDepositAddress = z.output<typeof FundingDepositAddress>
+
+/**
+ * One provider-observed deposit. Public route and evidence live in `snapshot`;
+ * reconciliation and settlement state is private.
+ */
+export const FundingDeposit = z.object({
+  createdAt: z.string().check(z.describe('When the deposit was detected (ISO 8601).')),
+  depositAddressId: z.string().check(z.describe('Funding deposit address id (`fda_…`).')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Key environment inherited from the deposit address.')),
+  id: z.string().check(z.describe('Funding deposit id (`fdp_…`).')),
+  orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  projectId: z.nullable(z.string()).check(z.describe('Attributed project id (`prj_…`), or null.')),
+  providerOutputAmount: z
+    .nullable(z.custom<z.output<typeof internal_Schema.TokenAmount>>())
+    .check(z.describe('Provider output amount verified on Tempo (`jsonb`), or null.')),
+  providerOutputToken: z
+    .custom<funding_Provider.TokenRef>()
+    .check(z.describe('Token output by the provider on Tempo (`jsonb`).')),
+  providerRequestId: z
+    .nullable(z.string())
+    .check(z.describe('Provider request that first reported the deposit, or null if unavailable.')),
+  providerRequestIds: z
+    .readonly(z.array(z.string()))
+    .check(z.describe('Private provider request identifiers (`jsonb`).')),
+  providerState: z
+    .nullable(z.custom<funding_Deposit.PrivateState>())
+    .check(z.describe('Bounded private provider state (`jsonb`), or null.')),
+  providerTransactionHashes: z
+    .readonly(z.array(z.string()))
+    .check(z.describe('Private provider-leg transaction references (`jsonb`).')),
+  providerTransferIndex: z
+    .number()
+    .check(z.int(), z.nonnegative(), z.describe('Deposit position within the provider request.')),
+  retryState: z
+    .nullable(z.custom<funding_Deposit.PrivateState>())
+    .check(z.describe('Bounded private retry state (`jsonb`), or null.')),
+  settlementTransaction: z
+    .nullable(z.string())
+    .check(z.describe('Persisted settlement transaction bytes, or null.')),
+  settlementTransactionHash: z
+    .nullable(z.string())
+    .check(z.describe('Persisted settlement transaction hash, or null.')),
+  snapshot: z
+    .custom<funding_Deposit.Snapshot>()
+    .check(z.describe('Public deposit fields (`jsonb`).')),
+  sourceChainId: z.string().check(z.describe('Source chain CAIP-2 id.')),
+  sourceTransactionHash: z
+    .string()
+    .check(z.describe('Provider-observed source transaction reference.')),
+  sourceTransferIndex: z
+    .nullable(z.number().check(z.int()))
+    .check(z.describe('Verified transfer position in the source transaction, or null.')),
+  status: z.custom<funding_Deposit.Status>().check(z.describe('Lifecycle status.')),
+  statusReason: z
+    .nullable(z.custom<funding_Deposit.StatusReason>())
+    .check(z.describe('Customer-safe status reason (`jsonb`), or null.')),
+  subsidyAmount: z
+    .nullable(z.custom<z.output<typeof internal_Schema.TokenAmount>>())
+    .check(z.describe('Destination token amount supplied by Tempo (`jsonb`), or null.')),
+  tempoGasPaid: z.nullable(z.string()).check(z.describe('Tempo gas paid for settlement, or null.')),
+  updatedAt: z.string().check(z.describe('When the deposit last materially changed (ISO 8601).')),
+  version: z.number().check(z.int(), z.describe('Material version used to guard updates.')),
+})
+
+/** Columns of the `funding_deposits` table. */
+export type FundingDeposit = z.output<typeof FundingDeposit>
+
+/**
+ * A durable funding transfer. Lifecycle state lives in typed columns; the
+ * public quote terms and reconciled fields live in the `snapshot` jsonb and
+ * merge in at serialization (`Transfer.toPublic`).
+ */
+export const FundingTransfer = z.object({
+  apiKeyId: z.string().check(z.describe('API key id (`key_…`) that created the transfer.')),
+  createdAt: z.string().check(z.describe('When the transfer was created (ISO 8601).')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Key environment the transfer belongs to.')),
+  id: z.string().check(z.describe('Transfer id (`ftr_…`, lexically time-ordered).')),
+  method: z
+    .custom<funding_Transfer.Snapshot['method']>()
+    .check(z.describe('Funding method selected at creation.')),
+  mode: z
+    .custom<funding_Transfer.Snapshot['mode']>()
+    .check(z.describe('Amount mode selected at creation.')),
+  orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  projectId: z
+    .nullable(z.string())
+    .check(z.describe('Attributed project id (`prj_…`), or null for organization-attributed keys.')), // prettier-ignore
+  providerId: z.string().check(z.describe('Selected funding provider id.')),
+  providerState: z
+    .nullable(z.custom<funding_Provider.prepareTransfer.Correlation>())
+    .check(z.describe('Private provider correlation (`jsonb`), or null. Never serialized publicly.')), // prettier-ignore
+  quoteExpiresAt: z
+    .string()
+    .check(z.describe('When the quoted terms stop being executable (ISO 8601).')),
+  snapshot: z
+    .custom<funding_Transfer.Snapshot>()
+    .check(z.describe('Public quote terms and reconciled fields (`jsonb`).')),
+  status: z.custom<funding_Transfer.Status>().check(z.describe('Lifecycle status.')),
+  statusReason: z
+    .nullable(z.custom<funding_Transfer.StatusReason>())
+    .check(z.describe('Customer-safe status reason (`jsonb`), or null.')),
+  updatedAt: z.string().check(z.describe('When the transfer last materially changed (ISO 8601).')),
+  version: z
+    .number()
+    .check(z.int(), z.describe('Increments on every material change; guards transitions.')),
+})
+
+/** Columns of the `funding_transfers` table. */
+export type FundingTransfer = z.output<typeof FundingTransfer>
+
+/** One immutable public snapshot of a funding transfer at a material version. */
+export const FundingTransferEvent = z.object({
+  createdAt: z.string().check(z.describe('When the version was committed (ISO 8601).')),
+  snapshot: z
+    .custom<funding_Transfer.Public>()
+    .check(z.describe('The complete public transfer at this version (`jsonb`).')),
+  status: z.custom<funding_Transfer.Status>().check(z.describe('Status at this version.')),
+  transferId: z.string().check(z.describe('Transfer id (`ftr_…`) the event belongs to.')),
+  version: z.number().check(z.int(), z.describe('Material version the event records.')),
+})
+
+/** Columns of the `funding_transfer_events` table. */
+export type FundingTransferEvent = z.output<typeof FundingTransferEvent>
+
+/** One verified transaction reference associated with a funding transfer. */
+export const FundingTransferTransaction = z.object({
+  chainId: z.string().check(z.describe('CAIP-2 chain the transaction executed on.')),
+  createdAt: z.string().check(z.describe('When the reference was accepted (ISO 8601).')),
+  role: z
+    .custom<funding_Transfer.TransactionRole>()
+    .check(z.describe('What the transaction evidences: `source`, `destination`, or `refund`.')),
+  transactionRef: z
+    .string()
+    .check(z.describe('EVM transaction hash or case-sensitive Solana signature.')),
+  transferId: z.string().check(z.describe('Transfer id (`ftr_…`) the reference belongs to.')),
+})
+
+/** Columns of the `funding_transfer_transactions` table. */
+export type FundingTransferTransaction = z.output<typeof FundingTransferTransaction>
+
+/**
+ * An API-key-scoped idempotency claim for funding resource creation. The row
+ * retains recovery checkpoints and completed responses until `expiresAt`.
+ */
+export const FundingIdempotencyRequest = z.object({
+  apiKeyId: z.string().check(z.describe('API key id (`key_…`) the claim is scoped to.')),
+  createdAt: z.string().check(z.describe('When the claim was taken (ISO 8601).')),
+  expiresAt: z.string().check(z.describe('When the claim stops replaying (ISO 8601).')),
+  keyHash: z.string().check(z.describe('SHA-256 of the caller Idempotency-Key.')),
+  requestHash: z.string().check(z.describe('SHA-256 fingerprint of the canonical request.')),
+  response: z
+    .nullable(z.string())
+    .check(z.describe('Serialized checkpoint or success response, or null while pending.')),
+  status: z
+    .enum(['completed', 'pending', 'provisioned'])
+    .check(z.describe('Claim state for execution, recovery, or replay.')),
+  transferId: z
+    .nullable(z.string())
+    .check(z.describe('Transfer id (`ftr_…`) the completed claim created, or null.')),
+})
+
+/** Columns of the `funding_idempotency_requests` table. */
+export type FundingIdempotencyRequest = z.output<typeof FundingIdempotencyRequest>
+
 /**
  * A verified token: one row per curated token, ordered by `position` (list
  * order is canonical and surfaced to clients). Addresses are stored lowercase;

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

@@ -0,0 +1,185 @@
+import * as TestApp from '../../../test/App.js'
+import * as EarnVaults from './earnVaults.js'
+
+const input = {
+  chainId: 42_431,
+  description: 'Bridge test PATHUSD deposited into Tempo Earn.',
+  label: 'btPATHUSD Earn',
+  privateInputTokens: [
+    '0x20c00000000000000000000057F242B21a53ae4D',
+    '0x20c0000000000000000000005B77A125d795262A',
+  ],
+  privateOutputTokens: ['0x20c00000000000000000000057F242B21a53ae4D'],
+  vaultAddress: '0x2f05f4d3625B2eFFb383eFbEDAFd2D8F04371636',
+} as const satisfies EarnVaults.upsert.Options
+
+describe('upsert', () => {
+  test('inserts flattened curated fields and generates a stable slug', async () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime('2026-01-01T00:00:00.000Z')
+      const record = await EarnVaults.upsert(TestApp.database(), input)
+      const { slug, ...stored } = record
+      expect(slug).toMatch(/^btpathusd-earn-[0-9a-z]{8}$/)
+      expect(stored).toMatchInlineSnapshot(`
+        {
+          "chainId": 42431,
+          "createdAt": "2026-01-01T00:00:00.000Z",
+          "description": "Bridge test PATHUSD deposited into Tempo Earn.",
+          "label": "btPATHUSD Earn",
+          "privateInputTokens": [
+            "0x20c00000000000000000000057F242B21a53ae4D",
+            "0x20c0000000000000000000005B77A125d795262A",
+          ],
+          "privateOutputTokens": [
+            "0x20c00000000000000000000057F242B21a53ae4D",
+          ],
+          "updatedAt": "2026-01-01T00:00:00.000Z",
+          "vaultAddress": "0x2f05f4d3625b2effb383efbedafd2d8f04371636",
+        }
+      `)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('updates mutable fields while preserving createdAt', async () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime('2026-01-01T00:00:00.000Z')
+      const db = TestApp.database()
+      const created = await EarnVaults.upsert(db, input)
+      vi.setSystemTime('2026-01-02T00:00:00.000Z')
+      const updated = await EarnVaults.upsert(db, {
+        ...input,
+        description: null,
+        label: 'Renamed Vault',
+        privateInputTokens: [],
+        privateOutputTokens: [],
+        slug: 'replacement-slug',
+      })
+      const { slug, ...stored } = updated
+      expect(slug).toBe('replacement-slug')
+      expect(stored.createdAt).toBe(created.createdAt)
+      expect({
+        createdAt: stored.createdAt,
+        description: stored.description,
+        label: stored.label,
+        privateInputTokens: stored.privateInputTokens,
+        privateOutputTokens: stored.privateOutputTokens,
+        updatedAt: stored.updatedAt,
+      }).toMatchInlineSnapshot(`
+        {
+          "createdAt": "2026-01-01T00:00:00.000Z",
+          "description": null,
+          "label": "Renamed Vault",
+          "privateInputTokens": [],
+          "privateOutputTokens": [],
+          "updatedAt": "2026-01-02T00:00:00.000Z",
+        }
+      `)
+
+      expect(updated.slug).toBe('replacement-slug')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('supports chain ids above the Postgres integer range', async () => {
+    const chainId = 4_217_000_001
+    const db = TestApp.database()
+    const record = await EarnVaults.upsert(db, { ...input, chainId })
+    expect(record.chainId).toBe(chainId)
+    expect(
+      await EarnVaults.get(db, {
+        chainId,
+        vaultAddress: input.vaultAddress,
+      }),
+    ).toStrictEqual(record)
+  })
+})
+
+describe('get', () => {
+  test('reads case-insensitively and returns undefined when absent', async () => {
+    const db = TestApp.database()
+    const record = await EarnVaults.upsert(db, input)
+    expect(
+      await EarnVaults.get(db, {
+        chainId: input.chainId,
+        vaultAddress: input.vaultAddress.toUpperCase(),
+      }),
+    ).toStrictEqual(record)
+    expect(
+      await EarnVaults.get(db, {
+        chainId: 1,
+        vaultAddress: input.vaultAddress,
+      }),
+    ).toBeUndefined()
+  })
+})
+
+describe('list', () => {
+  test('filters by chain and returns stable order', async () => {
+    const db = TestApp.database()
+    const second = {
+      ...input,
+      vaultAddress: '0xaa0000000000000000000000000000000000000e',
+    } as const satisfies EarnVaults.upsert.Options
+    const third = {
+      ...input,
+      chainId: 4217,
+      vaultAddress: '0xaa0000000000000000000000000000000000000f',
+    } as const satisfies EarnVaults.upsert.Options
+    await EarnVaults.upsert(db, second)
+    await EarnVaults.upsert(db, input)
+    await EarnVaults.upsert(db, third)
+
+    expect(
+      (await EarnVaults.list(db)).map(({ chainId, vaultAddress }) => ({
+        chainId,
+        vaultAddress,
+      })),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "chainId": 4217,
+          "vaultAddress": "0xaa0000000000000000000000000000000000000f",
+        },
+        {
+          "chainId": 42431,
+          "vaultAddress": "0x2f05f4d3625b2effb383efbedafd2d8f04371636",
+        },
+        {
+          "chainId": 42431,
+          "vaultAddress": "0xaa0000000000000000000000000000000000000e",
+        },
+      ]
+    `)
+    expect(await EarnVaults.list(db, { chainId: third.chainId })).toHaveLength(1)
+  })
+})
+
+describe('remove', () => {
+  test('physically deletes one curated vault', async () => {
+    const db = TestApp.database()
+    const created = await EarnVaults.upsert(db, input)
+    expect(
+      await EarnVaults.remove(db, {
+        chainId: input.chainId,
+        vaultAddress: input.vaultAddress.toUpperCase(),
+      }),
+    ).toStrictEqual(created)
+    expect(
+      await EarnVaults.get(db, {
+        chainId: input.chainId,
+        vaultAddress: input.vaultAddress,
+      }),
+    ).toBeUndefined()
+    expect(
+      await EarnVaults.remove(db, {
+        chainId: input.chainId,
+        vaultAddress: input.vaultAddress,
+      }),
+    ).toBeUndefined()
+  })
+})

package/src/db/tables/earnVaults.ts

@@ -0,0 +1,151 @@
+import type { ColumnType, JSONColumnType, Selectable } from 'kysely'
+import { customAlphabet } from 'nanoid'
+import type { Address } from 'viem'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+const slugSuffix = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 8)
+
+/** Columns of the `earn_vaults` table. */
+export type Table = Omit<
+  db_Schema.EarnVault,
+  'chainId' | 'privateInputTokens' | 'privateOutputTokens'
+> & {
+  /** Bigint chain id, read as a string from pg and written as a number. */
+  chainId: ColumnType<string, number, number>
+  /** Tokens accepted for private deposits. */
+  privateInputTokens: JSONColumnType<db_Schema.EarnVault['privateInputTokens'], string, string>
+  /** Tokens supported for private redemptions. */
+  privateOutputTokens: JSONColumnType<db_Schema.EarnVault['privateOutputTokens'], string, string>
+}
+
+/** A stored curated Earn vault. */
+export type Record = db_Schema.EarnVault
+
+/** Reads one curated vault by chain and vault address. */
+export async function get(db: Db.Db, options: get.Options): Promise<Record | undefined> {
+  const row = await db.kysely
+    .selectFrom('earn_vaults')
+    .selectAll()
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace get {
+  /** Identity of one curated vault. */
+  type Options = {
+    /** Chain the vault belongs to. */
+    chainId: number
+    /** Earn vault address. */
+    vaultAddress: string
+  }
+}
+
+/** Lists curated vaults in stable chain and address order. */
+export async function list(db: Db.Db, options: list.Options = {}): Promise<Record[]> {
+  let query = db.kysely.selectFrom('earn_vaults').selectAll()
+  if (options.chainId !== undefined) query = query.where('chainId', '=', String(options.chainId))
+  const rows = await query.orderBy('chainId', 'asc').orderBy('vaultAddress', 'asc').execute()
+  return rows.map(toRecord)
+}
+
+export declare namespace list {
+  /** Optional curated-vault filters. */
+  type Options = {
+    /** Restrict results to one chain. */
+    chainId?: number | undefined
+  }
+}
+
+/** Inserts or updates a curated vault while preserving its stable identity fields. */
+export async function upsert(db: Db.Db, options: upsert.Options): Promise<Record> {
+  const now = new Date().toISOString()
+  const slug = options.slug ?? `${kebab(options.label)}-${slugSuffix()}`
+  const row = await db.kysely
+    .insertInto('earn_vaults')
+    .values({
+      chainId: options.chainId,
+      createdAt: now,
+      description: options.description,
+      label: options.label,
+      privateInputTokens: JSON.stringify(options.privateInputTokens),
+      privateOutputTokens: JSON.stringify(options.privateOutputTokens),
+      slug,
+      updatedAt: now,
+      vaultAddress: normalize(options.vaultAddress),
+    })
+    .onConflict((oc) =>
+      oc.columns(['chainId', 'vaultAddress']).doUpdateSet({
+        description: options.description,
+        label: options.label,
+        privateInputTokens: JSON.stringify(options.privateInputTokens),
+        privateOutputTokens: JSON.stringify(options.privateOutputTokens),
+        ...(options.slug !== undefined ? { slug } : {}),
+        updatedAt: now,
+      }),
+    )
+    .returningAll()
+    .executeTakeFirstOrThrow()
+  return toRecord(row)
+}
+
+export declare namespace upsert {
+  /** Curated fields stored for one verified vault. */
+  type Options = {
+    /** Chain the vault belongs to. */
+    chainId: number
+    /** Curated vault description. */
+    description: string | null
+    /** Curated vault label. */
+    label: string
+    /** Tokens accepted for private deposits. */
+    privateInputTokens: readonly Address[]
+    /** Tokens supported for private redemptions. */
+    privateOutputTokens: readonly Address[]
+    /** Stable slug, generated from the label when omitted. */
+    slug?: string | undefined
+    /** Earn vault address. */
+    vaultAddress: Address
+  }
+}
+
+/** Removes one curated vault. */
+export async function remove(db: Db.Db, options: remove.Options): Promise<Record | undefined> {
+  const row = await db.kysely
+    .deleteFrom('earn_vaults')
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace remove {
+  /** Identity of one curated vault. */
+  type Options = {
+    /** Chain the vault belongs to. */
+    chainId: number
+    /** Earn vault address. */
+    vaultAddress: string
+  }
+}
+
+function kebab(label: string): string {
+  return (
+    label
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || 'vault'
+  )
+}
+
+function toRecord(row: Selectable<Table>): Record {
+  return { ...row, chainId: Number(row.chainId) }
+}
+
+function normalize(address: string): Address {
+  return address.toLowerCase() as Address
+}