tapimo 0.10.0 → 0.10.2

package/src/apps/funding/routes/transfers.test.ts

@@ -27,11 +27,8 @@ const db = TestApp.database()
 /** Providers exercised against executable calls on a forked source chain. */
 const executableProviders = [
   {
-    create: (sender: string) =>
-      Relay.relay({
-        ...(process.env.RELAY_API_KEY ? { apiKey: process.env.RELAY_API_KEY } : {}),
-        userAddress: sender,
-      }),
+    create: (_sender: string) =>
+      Relay.relay(process.env.RELAY_API_KEY ? { apiKey: process.env.RELAY_API_KEY } : {}),
     id: 'relay',
   },
 ] as const
@@ -282,7 +279,7 @@ describe('POST /funding/transfers', () => {
       providerResponse(),
   ) {
     return FundingProvider.from({
-      ...Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+      ...Relay.relay(),
       prepareTransfer,
     })
   }
@@ -844,6 +841,7 @@ describe('funding transfers OpenAPI', () => {
       deposit: summarize(spec.paths[depositPath]!.get!),
       depositAddress: summarize(spec.paths[depositAddressPath]!.get!),
       depositAddressCreate: summarize(spec.paths['/v1/funding/deposit-addresses']!.post!),
+      depositAddressList: summarize(spec.paths['/v1/funding/deposit-addresses']!.get!),
       depositAddressReconcile: summarize(spec.paths[reconcilePath]!.post!),
       deposits: summarize(spec.paths['/v1/funding/deposits']!.get!),
       detail: summarize(spec.paths[detailPath]!.get!),
@@ -892,12 +890,16 @@ describe('funding transfers OpenAPI', () => {
             "description": "Creates or returns a reusable deposit address for funding a Tempo account.",
             "summary": "Create deposit address",
           },
+          "depositAddressList": {
+            "description": "Lists reusable funding deposit addresses, newest first.",
+            "summary": "List deposit addresses",
+          },
           "depositAddressReconcile": {
             "description": "Queues an immediate provider reconciliation for one reusable funding deposit address.",
             "summary": "Reconcile deposit address",
           },
           "deposits": {
-            "description": "Lists deposits by deposit address or Tempo recipient, newest first.",
+            "description": "Lists visible deposits, optionally filtered, newest first.",
             "summary": "List deposits",
           },
           "detail": {
@@ -929,6 +931,7 @@ describe('funding transfers OpenAPI', () => {
           "Get quotes",
           "Get chains",
           "Get providers",
+          "List deposit addresses",
           "Create deposit address",
           "List transfers",
           "Create transfer",
@@ -1090,7 +1093,11 @@ describe('funding transfers OpenAPI', () => {
     const operation = spec.paths['/v1/funding/transfers']!.get
     const fields = Object.keys(operation.responses['200']!.content['application/json']!.example.data[0]!) // prettier-ignore
     expect(fields).toEqual([...fields].sort())
-    for (const route of [operation, spec.paths['/v1/funding/deposits']!.get])
+    for (const route of [
+      operation,
+      spec.paths['/v1/funding/deposit-addresses']!.get,
+      spec.paths['/v1/funding/deposits']!.get,
+    ])
       for (const parameter of route.parameters ?? [])
         expect(parameter.example ?? parameter.schema?.examples, parameter.name).toBeDefined()
   })
@@ -1129,6 +1136,9 @@ describe('funding transfers OpenAPI', () => {
       depositAddressCreate: spec.paths['/v1/funding/deposit-addresses']?.post?.operationId,
       depositAddressCreateScopes:
         spec.paths['/v1/funding/deposit-addresses']?.post?.['x-required-scopes'],
+      depositAddressList: spec.paths['/v1/funding/deposit-addresses']?.get.operationId,
+      depositAddressListScopes:
+        spec.paths['/v1/funding/deposit-addresses']?.get['x-required-scopes'],
       depositAddressReconcile: reconcilePath && spec.paths[reconcilePath]?.post?.operationId,
       depositAddressReconcileScopes:
         reconcilePath && spec.paths[reconcilePath]?.post?.['x-required-scopes'],
@@ -1153,6 +1163,8 @@ describe('funding transfers OpenAPI', () => {
       depositAddress: 'getFundingDepositAddress',
       depositAddressCreate: 'createFundingDepositAddress',
       depositAddressCreateScopes: ['funding:write'],
+      depositAddressList: 'listFundingDepositAddresses',
+      depositAddressListScopes: ['funding:read'],
       depositAddressReconcile: 'reconcileFundingDepositAddress',
       depositAddressReconcileScopes: ['funding:write'],
       depositAddressScopes: ['funding:read'],

package/src/apps/funding/routes/transfers.ts

@@ -110,7 +110,7 @@ export namespace schema {
           .check(
             z.regex(/^eip155:\d+$/),
             z.describe('Configured Zone CAIP-2 id.'),
-            z.meta({ examples: ['eip155:421700001'] }),
+            z.meta({ examples: ['eip155:1424310001'] }),
           ),
         destinationToken: FundingTransfer.schema.CreateRequest.shape.destinationToken,
         mode: destinationCreateFields.mode,

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

@@ -699,7 +699,7 @@ export function billing() {
       Auth.policy({
         apiKey: false,
         mpp: false,
-        public: { rateLimit: { perMinute: 600 } },
+        public: { rateLimit: { limit: 600, period: 'minute' } },
         session: false,
       }),
       OpenApi.describeRoute({ hide: true, summary: 'Stripe webhook' }),

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

@@ -10,8 +10,8 @@ import * as Value from '../../../internal/Value.js'
 import * as Viem from '../../../internal/Viem.js'
 import type { Environment } from '../App.js'
 
-const addressRateLimit = { perMinute: 1 } satisfies RateLimit.Limit
-const userRateLimit = { perMinute: 3 } satisfies RateLimit.Limit
+const addressRateLimit = { limit: 1, period: 'minute' } satisfies RateLimit.Limit
+const userRateLimit = { limit: 3, period: 'minute' } satisfies RateLimit.Limit
 
 /** OpenAPI schemas owned by the sandbox faucet. */
 export namespace schema {

package/src/apps/management/routes/me.test.ts

@@ -1,7 +1,10 @@
 import { serve } from '@hono/node-server'
 import * as Accounts from 'accounts/server'
 import { exportJWK, generateKeyPair } from 'jose'
+import { P256 } from 'ox'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { Account } from 'viem/tempo'
+import { tempoTestnet } from 'viem/tempo/chains'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Me from './me.js'
@@ -18,6 +21,34 @@ function createApp() {
   })
 }
 
+describe('SIWE verification', () => {
+  test('surfaces configured RPC failures as dependency errors', async () => {
+    const account = Account.fromHeadlessWebAuthn(P256.randomPrivateKey(), {
+      origin,
+      rpId: 'localhost',
+    })
+    let chainId_seen: number | undefined
+    const app = TestApp.create({
+      rpc: ({ chainId }) => {
+        chainId_seen = chainId
+        return { url: 'http://127.0.0.1:1' }
+      },
+    })
+
+    const { verifyResponse } = await TestApp.signIn(app, account, {
+      chainId: tempoTestnet.id,
+    })
+
+    expect(verifyResponse.status).toBe(502)
+    expect(chainId_seen).toMatchInlineSnapshot(`42431`)
+    expect(await verifyResponse.json()).toMatchInlineSnapshot(`
+      {
+        "error": "signature verification unavailable",
+      }
+    `)
+  })
+})
+
 describe('GET /me', () => {
   test('returns the signed-in user', async () => {
     const app = createApp()

package/src/apps/mcp.ts

@@ -138,7 +138,10 @@ export function mcp(options: mcp.Options) {
   const app = new Hono<App.Environment>()
     .post(
       '/mcp',
-      Auth.policy({ apiKey: { scopes: [] }, public: { rateLimit: { perMinute: 100 } } }),
+      Auth.policy({
+        apiKey: { scopes: [] },
+        public: { rateLimit: { limit: 100, period: 'minute' } },
+      }),
       OpenApi.describeRoute({
         description:
           "A stateless streamable-HTTP MCP server: send JSON-RPC 2.0 messages as `POST` with `Accept: application/json, text/event-stream`. Tools mirror the API's data domain, plus `docs_*` documentation search. Anonymous requests allow 100 requests per minute; send `Authorization: Bearer <api key>` for protected tools.",

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 WebhookQueueEvents from './tables/webhookQueueEvents.js'
 import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
 
 /**
@@ -82,6 +83,7 @@ export type Database = {
   verified_token_requests: VerifiedTokenRequests.Table
   verified_tokens: VerifiedTokens.Table
   webhook_deliveries: WebhookDeliveries.Table
+  webhook_queue_events: WebhookQueueEvents.Table
   webhook_subscriptions: WebhookSubscriptions.Table
 }
 
@@ -1281,6 +1283,121 @@ export const migrations: readonly Migration[] = [
         .on('fundingDepositAddresses')
         .columns(['orgId', 'environment', 'address', 'projectId']),
   },
+  {
+    name: '0115_webhook_queue_events',
+    up: (db) =>
+      db.schema
+        .createTable('webhookQueueEvents')
+        .ifNotExists()
+        .addColumn('subscriptionId', 'text', (c) =>
+          c.notNull().references('webhookSubscriptions.id').onDelete('cascade'),
+        )
+        .addColumn('eventId', 'text', (c) => c.notNull())
+        .addColumn('envelope', 'jsonb', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('expiresAt', 'text', (c) => c.notNull())
+        .addPrimaryKeyConstraint('webhook_queue_events_pkey', ['subscriptionId', 'eventId']),
+  },
+  {
+    name: '0116_webhook_queue_events_expires_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_queue_events_expires_idx')
+        .ifNotExists()
+        .on('webhookQueueEvents')
+        .column('expiresAt'),
+  },
+  {
+    name: '0117_webhook_queue_events_ledger_columns',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE webhook_queue_events
+          ADD COLUMN IF NOT EXISTS status text NOT NULL DEFAULT 'pending',
+          ADD COLUMN IF NOT EXISTS attempt_count integer NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS attempting_at text,
+          ADD COLUMN IF NOT EXISTS next_attempt_at text`,
+      ),
+  },
+  {
+    name: '0118_webhook_queue_events_status_check',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE webhook_queue_events DROP CONSTRAINT IF EXISTS webhook_queue_events_status_check, ADD CONSTRAINT webhook_queue_events_status_check CHECK (status IN ('failed', 'pending', 'skipped', 'succeeded'))`,
+      ),
+  },
+  {
+    name: '0119_webhook_queue_events_pending_index',
+    up: (db) =>
+      // NULLS FIRST matches the due-sweep order (null = due immediately);
+      // INCLUDE lets the pending gauge take min(created_at) index-only.
+      raw(
+        db,
+        sql`CREATE INDEX IF NOT EXISTS webhook_queue_events_pending_idx ON webhook_queue_events (next_attempt_at NULLS FIRST) INCLUDE (created_at) WHERE status = 'pending'`,
+      ),
+  },
+  {
+    name: '0120_webhook_queue_events_pending_index_drop',
+    up: (db) => raw(db, sql`DROP INDEX IF EXISTS webhook_queue_events_pending_idx`),
+  },
+  {
+    name: '0121_webhook_queue_events_pending_index_expiry',
+    up: (db) =>
+      // Recreated with expires_at so claimable and gauge queries, which all
+      // filter expiry at query time, stay index-only.
+      raw(
+        db,
+        sql`CREATE INDEX IF NOT EXISTS webhook_queue_events_pending_idx ON webhook_queue_events (next_attempt_at NULLS FIRST) INCLUDE (created_at, expires_at) WHERE status = 'pending'`,
+      ),
+  },
+  {
+    name: '0122_webhook_queue_events_expired_pending_cleanup',
+    up: (db) =>
+      // Pre-ledger rows already past their staging TTL were dead under the
+      // old read path; pending rows no longer expire, so drop them once
+      // instead of resurrecting them as eternal obligations.
+      raw(
+        db,
+        sql`DELETE FROM webhook_queue_events WHERE status = 'pending' AND attempting_at IS NULL AND expires_at <= to_char(now() AT TIME ZONE 'utc', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`,
+      ),
+  },
+  {
+    name: '0123_funding_deposit_addresses_owner_list_index',
+    up: (db) =>
+      db.schema
+        .createIndex('funding_deposit_addresses_owner_list_idx')
+        .ifNotExists()
+        .on('fundingDepositAddresses')
+        .columns(['orgId', 'environment', 'createdAt', 'id']),
+  },
+  {
+    name: '0124_funding_deposit_addresses_project_list_index',
+    up: (db) =>
+      db.schema
+        .createIndex('funding_deposit_addresses_project_list_idx')
+        .ifNotExists()
+        .on('fundingDepositAddresses')
+        .columns(['orgId', 'environment', 'projectId', 'createdAt', 'id']),
+  },
+  {
+    name: '0125_funding_deposits_owner_list_index',
+    up: (db) =>
+      db.schema
+        .createIndex('funding_deposits_owner_list_idx')
+        .ifNotExists()
+        .on('fundingDeposits')
+        .columns(['orgId', 'environment', 'createdAt', 'id']),
+  },
+  {
+    name: '0126_funding_deposits_project_list_index',
+    up: (db) =>
+      db.schema
+        .createIndex('funding_deposits_project_list_idx')
+        .ifNotExists()
+        .on('fundingDeposits')
+        .columns(['orgId', 'environment', 'projectId', 'createdAt', 'id']),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -874,3 +874,35 @@ export const WebhookDelivery = z.object({
 
 /** Columns of the `webhook_deliveries` table. */
 export type WebhookDelivery = z.output<typeof WebhookDelivery>
+
+/** 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.')),
+  attemptingAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO timestamp of the current claim, or null when unclaimed.')),
+  createdAt: z.string().check(z.describe('ISO timestamp when the envelope was staged.')),
+  envelope: z
+    .custom<Webhooks.Envelope>()
+    .check(z.describe('The full webhook envelope retained outside Cloudflare Queues.')),
+  eventId: z.string().check(z.describe('Idempotent event id (`evt_...`).')),
+  expiresAt: z
+    .string()
+    .check(
+      z.describe(
+        'ISO dedupe retention deadline, restarted at terminal transitions; inert while pending.',
+      ),
+    ),
+  nextAttemptAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO retry due time, or null when due immediately.')),
+  status: z
+    .enum(['failed', 'pending', 'skipped', 'succeeded'])
+    .check(z.describe('Delivery-obligation lifecycle status.')),
+  subscriptionId: z
+    .string()
+    .check(z.describe('Owning subscription id (`wh_...`); FK with `ON DELETE CASCADE`.')),
+})
+
+/** Columns of the `webhook_queue_events` table. */
+export type WebhookQueueEvent = z.output<typeof WebhookQueueEvent>

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

@@ -578,3 +578,31 @@ describe('renewPoll', () => {
     `)
   })
 })
+
+describe('list', () => {
+  test('pages organization addresses and narrows project-attributed owners', async () => {
+    const listOwner = { environment: owner.environment, orgId: 'org_address_list' } as const
+    const first = await seed({ orgId: listOwner.orgId })
+    const project = await seed({ orgId: listOwner.orgId, projectId: 'prj_address_list' })
+    const sibling = await seed({ orgId: listOwner.orgId, projectId: 'prj_address_sibling' })
+    await seed({ orgId: 'org_address_list_foreign' })
+    await seed({ environment: 'sandbox', orgId: listOwner.orgId })
+
+    const page = await FundingDepositAddresses.list(db, { limit: 2, owner: listOwner })
+    expect(page.map((record) => record.id)).toEqual([sibling.id, project.id])
+    const rest = await FundingDepositAddresses.list(db, {
+      cursor: { createdAt: project.createdAt, id: project.id },
+      limit: 2,
+      owner: listOwner,
+    })
+    expect(rest.map((record) => record.id)).toEqual([first.id])
+    expect(
+      (
+        await FundingDepositAddresses.list(db, {
+          limit: 10,
+          owner: { ...listOwner, projectId: 'prj_address_list' },
+        })
+      ).map((record) => record.id),
+    ).toEqual([project.id])
+  })
+})

package/src/db/tables/fundingDepositAddresses.ts

@@ -148,6 +148,45 @@ export function getOwned(db: Db.Db, owner: Owner, id: string): Promise<Record |
   return query.executeTakeFirst()
 }
 
+/** Lists owner-visible funding deposit addresses newest-first. */
+export function list(db: Db.Db, options: list.Options): Promise<Record[]> {
+  const { cursor, limit, owner } = options
+  let query = db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('environment', '=', owner.environment)
+    .where('orgId', '=', owner.orgId)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  if (cursor)
+    query = query.where((eb) =>
+      eb.or([
+        eb('createdAt', '<', cursor.createdAt),
+        eb.and([eb('createdAt', '=', cursor.createdAt), eb('id', '<', cursor.id)]),
+      ]),
+    )
+  return query.orderBy('createdAt', 'desc').orderBy('id', 'desc').limit(limit).execute()
+}
+
+export declare namespace list {
+  /** Ownership and paging options for funding deposit addresses. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: Cursor | undefined
+    /** Maximum rows to return. */
+    limit: number
+    /** Ownership filter derived from the authenticated API key. */
+    owner: Owner
+  }
+
+  /** Cursor fields for the last address returned by the previous page. */
+  type Cursor = {
+    /** Deposit address creation time. */
+    createdAt: string
+    /** Deposit address id, used as a deterministic tie-breaker. */
+    id: string
+  }
+}
+
 /** Gets the reusable address that matches one owner and route identity. */
 export function getMatching(db: Db.Db, match: Match): Promise<Record | undefined> {
   let query = db.kysely

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

@@ -498,3 +498,85 @@ describe('toPublic', () => {
     })
   })
 })
+
+describe('list', () => {
+  test('pages organization deposits and narrows project-attributed owners', async () => {
+    const listOwner = { environment: owner.environment, orgId: 'org_deposit_list' } as const
+    const firstAddress = await seedAddress({ orgId: listOwner.orgId })
+    const projectAddress = await seedAddress({
+      orgId: listOwner.orgId,
+      projectId: 'prj_deposit_list',
+    })
+    const siblingAddress = await seedAddress({
+      orgId: listOwner.orgId,
+      projectId: 'prj_deposit_sibling',
+    })
+    const first = await seedDeposit(firstAddress)
+    const project = await seedDeposit(projectAddress)
+    const sibling = await seedDeposit(siblingAddress)
+    const foreignAddress = await seedAddress({ orgId: 'org_deposit_list_foreign' })
+    await seedDeposit(foreignAddress)
+    const sandboxAddress = await seedAddress({
+      environment: 'sandbox',
+      orgId: listOwner.orgId,
+    })
+    await seedDeposit(sandboxAddress)
+
+    const page = await FundingDeposits.list(db, { limit: 2, owner: listOwner })
+    expect(page.map((record) => record.id)).toEqual([sibling.id, project.id])
+    const rest = await FundingDeposits.list(db, {
+      cursor: { createdAt: project.createdAt, id: project.id },
+      limit: 2,
+      owner: listOwner,
+    })
+    expect(rest.map((record) => record.id)).toEqual([first.id])
+    expect(
+      (
+        await FundingDeposits.list(db, {
+          limit: 10,
+          owner: { ...listOwner, projectId: 'prj_deposit_list' },
+        })
+      ).map((record) => record.id),
+    ).toEqual([project.id])
+  })
+
+  test('AND-combines filters and counts through the same ownership scope', async () => {
+    const listOwner = { environment: owner.environment, orgId: 'org_deposit_filters' } as const
+    const recipient = `0x${'ab'.repeat(20)}`
+    const address = await seedAddress({
+      orgId: listOwner.orgId,
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_filters', name: 'Relay' },
+        recipient,
+      }),
+    })
+    const match = await seedDeposit(address)
+    const unrelatedAddress = await seedAddress({ orgId: listOwner.orgId })
+    await seedDeposit(unrelatedAddress)
+    const filters = {
+      depositAddress: address.address,
+      destinationTokenKeys: [address.destinationTokenKey],
+      providerId: address.providerId,
+      recipient: recipient.toLowerCase(),
+      sourceChainIds: [address.sourceChainId],
+      sourceTokenKeys: [address.sourceTokenKey],
+      status: 'detected',
+    } as const
+
+    expect(
+      (await FundingDeposits.list(db, { ...filters, limit: 10, owner: listOwner })).map(
+        (record) => record.id,
+      ),
+    ).toEqual([match.id])
+    expect(await FundingDeposits.count(db, { ...filters, cap: 10, owner: listOwner })).toBe(1)
+    expect(await FundingDeposits.count(db, { ...filters, cap: 0, owner: listOwner })).toBe(1)
+    expect(
+      await FundingDeposits.count(db, {
+        ...filters,
+        destinationTokenKeys: [],
+        cap: 10,
+        owner: listOwner,
+      }),
+    ).toBe(0)
+  })
+})

package/src/db/tables/fundingDeposits.ts

@@ -27,6 +27,24 @@ export type Owner = {
   projectId?: string | undefined
 }
 
+/** Optional filters shared by funding deposit list and count queries. */
+export type Filters = {
+  /** Reusable source-chain address that received the funds. */
+  depositAddress?: string | undefined
+  /** Canonical destination token keys accepted by the filter. */
+  destinationTokenKeys?: readonly string[] | undefined
+  /** Funding provider id. */
+  providerId?: string | undefined
+  /** Tempo account that receives completed deposits. */
+  recipient?: string | undefined
+  /** Canonical source chain ids accepted by the filter. */
+  sourceChainIds?: readonly string[] | undefined
+  /** Canonical source token keys accepted by the filter. */
+  sourceTokenKeys?: readonly string[] | undefined
+  /** Deposit lifecycle status. */
+  status?: Record['status'] | undefined
+}
+
 /** Inserts one provider-observed source transfer as a funding deposit. */
 export function insert(db: Db.Db, record: Record): Promise<Record> {
   return db.kysely
@@ -234,6 +252,118 @@ export function getOwned(db: Db.Db, owner: Owner, id: string): Promise<Record |
   return query.executeTakeFirst()
 }
 
+/** Lists owner-visible funding deposits newest-first. */
+export function list(db: Db.Db, options: list.Options): Promise<Record[]> {
+  const { cursor, limit } = options
+  let builder = query(db, options).selectAll('funding_deposits')
+  if (cursor)
+    builder = builder.where((eb) =>
+      eb.or([
+        eb('funding_deposits.createdAt', '<', cursor.createdAt),
+        eb.and([
+          eb('funding_deposits.createdAt', '=', cursor.createdAt),
+          eb('funding_deposits.id', '<', cursor.id),
+        ]),
+      ]),
+    )
+  return builder
+    .orderBy('funding_deposits.createdAt', 'desc')
+    .orderBy('funding_deposits.id', 'desc')
+    .limit(limit)
+    .execute()
+}
+
+export declare namespace list {
+  /** Ownership and paging options for funding deposits. */
+  type Options = Filters & {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: listByAddress.Cursor | undefined
+    /** Maximum rows to return. */
+    limit: number
+    /** Ownership filter derived from the authenticated API key. */
+    owner: Owner
+  }
+}
+
+/** Counts owner-visible funding deposits through the list's shared filters. */
+export async function count(db: Db.Db, options: count.Options): Promise<number> {
+  const rows = query(db, options)
+    .select('funding_deposits.id')
+    .limit(options.cap + 1)
+    .as('rows')
+  const result = await db.kysely
+    .selectFrom(rows)
+    .select(sql<number>`count(*)::int`.as('count'))
+    .executeTakeFirstOrThrow()
+  return result.count
+}
+
+export declare namespace count {
+  /** Ownership, filter, and cap options for counting funding deposits. */
+  type Options = Filters & {
+    /** Maximum exact count before returning the cap plus one. */
+    cap: number
+    /** Ownership filter derived from the authenticated API key. */
+    owner: Owner
+  }
+}
+
+function query(db: Db.Db, options: query.Options) {
+  const owner = options.owner
+  let builder = db.kysely
+    .selectFrom('funding_deposits')
+    .innerJoin(
+      'funding_deposit_addresses',
+      'funding_deposit_addresses.id',
+      'funding_deposits.depositAddressId',
+    )
+    .where('funding_deposit_addresses.environment', '=', owner.environment)
+    .where('funding_deposit_addresses.orgId', '=', owner.orgId)
+    .where('funding_deposits.environment', '=', owner.environment)
+    .where('funding_deposits.orgId', '=', owner.orgId)
+  if (owner.projectId !== undefined)
+    builder = builder
+      .where('funding_deposit_addresses.projectId', '=', owner.projectId)
+      .where('funding_deposits.projectId', '=', owner.projectId)
+  if (options.depositAddress !== undefined) {
+    const address = /^0x[0-9a-fA-F]{40}$/.test(options.depositAddress)
+      ? options.depositAddress.toLowerCase()
+      : options.depositAddress
+    builder = builder.where('funding_deposit_addresses.address', '=', address)
+  }
+  if (options.destinationTokenKeys !== undefined)
+    builder = options.destinationTokenKeys.length
+      ? builder.where(
+          'funding_deposit_addresses.destinationTokenKey',
+          'in',
+          options.destinationTokenKeys,
+        )
+      : builder.where(sql<boolean>`false`)
+  if (options.providerId !== undefined)
+    builder = builder.where('funding_deposit_addresses.providerId', '=', options.providerId)
+  if (options.recipient !== undefined)
+    builder = builder.where(
+      sql<boolean>`lower(funding_deposit_addresses.recipient) = ${options.recipient.toLowerCase()}`,
+    )
+  if (options.sourceChainIds !== undefined)
+    builder = options.sourceChainIds.length
+      ? builder.where('funding_deposit_addresses.sourceChainId', 'in', options.sourceChainIds)
+      : builder.where(sql<boolean>`false`)
+  if (options.sourceTokenKeys !== undefined)
+    builder = options.sourceTokenKeys.length
+      ? builder.where('funding_deposit_addresses.sourceTokenKey', 'in', options.sourceTokenKeys)
+      : builder.where(sql<boolean>`false`)
+  if (options.status !== undefined)
+    builder = builder.where('funding_deposits.status', '=', options.status)
+  return builder
+}
+
+declare namespace query {
+  type Options = Filters & {
+    owner: Owner
+  }
+}
+
 /** Lists one owner-visible address's deposits newest-first. */
 export function listByAddress(
   db: Db.Db,