tapimo 0.7.2 → 0.8.0

package/src/internal/Cache.test.ts

@@ -52,7 +52,7 @@ describe('response', () => {
       expect(etag(first)).toMatchInlineSnapshot(`"<etag>"`)
       expect(first.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"9"`)
       expect(first.headers.get('vary')).toMatchInlineSnapshot(
-        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+        `"Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key"`,
       )
 
       expect(await second.json()).toMatchInlineSnapshot(`
@@ -66,7 +66,7 @@ describe('response', () => {
       expect(second.headers.get('etag') === first.headers.get('etag')).toMatchInlineSnapshot(`true`)
       expect(second.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"8"`)
       expect(second.headers.get('vary')).toMatchInlineSnapshot(
-        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+        `"Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key"`,
       )
 
       expect(third.status).toMatchInlineSnapshot(`304`)
@@ -77,11 +77,45 @@ describe('response', () => {
       expect(third.headers.get('etag') === first.headers.get('etag')).toMatchInlineSnapshot(`true`)
       expect(third.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"8"`)
       expect(third.headers.get('vary')).toMatchInlineSnapshot(
-        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+        `"Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key"`,
       )
     })
   })
 
+  test('varies cached responses by the legacy API-key header', async () => {
+    await withCaches(async () => {
+      let calls = 0
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) =>
+        c.json({ calls: ++calls, token: c.req.header('x-api-key') }),
+      )
+
+      const first = await app.request('/', { headers: { 'x-api-key': 'one' } })
+      const second = await app.request('/', { headers: { 'x-api-key': 'two' } })
+      const hit = await app.request('/', { headers: { 'x-api-key': 'one' } })
+
+      expect(calls).toMatchInlineSnapshot(`2`)
+      expect(await first.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 1,
+          "token": "one",
+        }
+      `)
+      expect(await second.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 2,
+          "token": "two",
+        }
+      `)
+      expect(await hit.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 1,
+          "token": "one",
+        }
+      `)
+    })
+  })
+
   test('stores entries with the shared policy form, not the client form', async () => {
     await withCaches(async (stores) => {
       const app = new Hono()

package/src/internal/Cache.ts

@@ -57,7 +57,7 @@ export function response<environment extends Env>(
   options: response.Options<environment>,
 ): MiddlewareHandler<environment> {
   const defaultCacheControl = options.cacheControl ?? policies.default
-  const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key']
+  const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key', 'X-API-Key']
   // hono/cache suffixes its key with `::<directive>=<value>` for every
   // configured vary directive (trimmed, lowercased, deduped). Mirror that
   // normalization so the `no-cache` purge below deletes exactly the entry the

package/src/internal/EdgeCache.test.ts

@@ -37,18 +37,18 @@ describe('middleware', () => {
     expect(second.headers.get('vary')).toMatchInlineSnapshot(`"Accept-Encoding"`)
   })
 
-  test('serves authenticated requests from the same shared cache entry', async () => {
+  test('bypasses the cache for credential headers', async () => {
     const { app, store, downstreamCalls } = createApp()
 
-    // An authenticated request warms the cache; subsequent requests — whether
-    // authenticated (with any key) or anonymous — are all served from the one
-    // shared entry without re-running downstream auth/rate-limiting.
     await app.request('/cached', { headers: { authorization: 'Bearer one' } })
+    await app.request('/cached', { headers: { authorization: 'Basic malformed' } })
+    await app.request('/cached', { headers: { authorization: 'Payment paid' } })
     await app.request('/cached', { headers: { 'tempo-api-key': 'two' } })
-    await app.request('/cached')
+    await app.request('/cached', { headers: { 'x-api-key': 'three' } })
 
-    expect(downstreamCalls()).toMatchInlineSnapshot(`1`)
-    expect(store.size).toMatchInlineSnapshot(`1`)
+    expect(downstreamCalls()).toMatchInlineSnapshot(`5`)
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
   })
 
   test('bypasses the cache for query API key credentials', async () => {

package/src/internal/EdgeCache.ts

@@ -48,8 +48,8 @@ const volatileHeaders = [
 /**
  * Serves GET responses from the edge cache store BEFORE auth and rate-limiting
  * run, so cache hits skip the per-request store round-trips that dominate
- * latency — for every caller, authenticated or not. Place this ahead of the
- * auth middleware.
+ * latency. Credential-bearing requests bypass this layer so per-key policy
+ * enforcement always runs. Place this ahead of the auth middleware.
  *
  * Only 2xx responses from routes that opted into caching (via `Cache.response`,
  * which publishes the `edgeCache` policy) are stored, and the policy is only
@@ -84,8 +84,8 @@ export function middleware<environment extends Env>(
       store !== undefined &&
       c.req.method === 'GET' &&
       !c.req.raw.headers.has('range') &&
-      // Query credentials must reach auth and never enter cache keys.
-      !new URL(c.req.url).searchParams.has('key') &&
+      // Credential-bearing requests must reach auth for per-key policy enforcement.
+      !hasCredential(c.req.raw) &&
       isCacheableRoute(c)
     const key = eligible
       ? await routeCacheKey(c).catch(() => {
@@ -144,6 +144,15 @@ export function middleware<environment extends Env>(
   }
 }
 
+function hasCredential(request: Request): boolean {
+  return (
+    request.headers.has('tempo-api-key') ||
+    request.headers.has('x-api-key') ||
+    request.headers.has('authorization') ||
+    new URL(request.url).searchParams.has('key')
+  )
+}
+
 // Marks handlers whose route publishes an edge-cache policy; the middleware
 // pays the store lookup only when a matched handler carries it.
 const cacheableSymbol = Symbol('tempoApi.edgeCacheable')

package/src/internal/IpAllowlist.test.ts

@@ -0,0 +1,52 @@
+import { Hono } from 'hono'
+
+import * as IpAllowlist from './IpAllowlist.js'
+
+describe('isRule', () => {
+  test.each([
+    ['203.0.113.7', true],
+    ['0.0.0.0/0', true],
+    ['203.0.113.0/24', true],
+    ['203.0.113.7/32', true],
+    ['2001:db8::7', true],
+    ['::/0', true],
+    ['2001:db8::/32', true],
+    ['2001:db8::7/128', true],
+    ['::ffff:192.0.2.1', true],
+    ['203.0.113.0/33', false],
+    ['2001:db8::/129', false],
+    ['203.0.113.0/-1', false],
+    ['203.0.113.999', false],
+    ['2001:db8::1%eth0', false],
+    ['203.0.113.0/24/1', false],
+    [' 203.0.113.7', false],
+    ['203.0.113.7 ', false],
+    ['*', false],
+    ['', false],
+  ])('%s -> %s', (rule, expected) => {
+    expect(IpAllowlist.isRule(rule)).toBe(expected)
+  })
+})
+
+describe('allows', () => {
+  test.each([
+    ['203.0.113.7', ['203.0.113.7'], true],
+    ['203.0.113.7', ['0.0.0.0/0'], true],
+    ['203.0.113.7', ['203.0.113.0/24'], true],
+    ['203.0.113.0', ['203.0.113.0/24'], true],
+    ['203.0.113.255', ['203.0.113.0/24'], true],
+    ['203.0.114.7', ['203.0.113.0/24'], false],
+    ['2001:db8:1::7', ['2001:db8::/32'], true],
+    ['2001:db8::7', ['2001:db8::7/128'], true],
+    ['2001:db8::8', ['2001:db8::7/128'], false],
+    ['2001:db9::7', ['2001:db8::/32'], false],
+    ['203.0.113.7', ['2001:db8::/32'], false],
+    ['::ffff:192.0.2.1', ['::ffff:192.0.2.1'], true],
+    ['not-an-ip', ['203.0.113.0/24'], false],
+  ])('%s in %j -> %s', async (address, rules, expected) => {
+    const app = new Hono().get('/', async (c) =>
+      c.json({ allowed: await IpAllowlist.allows(c, { address, rules }) }),
+    )
+    expect(await (await app.request('/')).json()).toEqual({ allowed: expected })
+  })
+})

package/src/internal/IpAllowlist.ts

@@ -0,0 +1,39 @@
+import type { Context } from 'hono'
+import { ipRestriction } from 'hono/ip-restriction'
+
+/** Returns whether a value is an IPv4/IPv6 address or CIDR range. */
+export function isRule(value: string): boolean {
+  if (value === '*' || value.trim() !== value || value.split('/').length > 2) return false
+  try {
+    ipRestriction(() => '', { allowList: [value] })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Returns whether the client address matches at least one allowlist rule. */
+export async function allows(c: Context, options: allows.Options): Promise<boolean> {
+  const { address, rules } = options
+  if (!address) return false
+  try {
+    const denied = await ipRestriction(
+      () => address,
+      { allowList: [...rules] },
+      () => new Response(null, { status: 403 }),
+    )(c, async () => {})
+    return denied === undefined
+  } catch {
+    return false
+  }
+}
+
+export declare namespace allows {
+  /** Inputs used to check a client address. */
+  type Options = {
+    /** Trusted client IP address. */
+    address?: string | undefined
+    /** Exact IP and CIDR rules to match. */
+    rules: readonly string[]
+  }
+}

package/src/internal/Log.test.ts

@@ -102,7 +102,13 @@ describe('middleware', () => {
     const api = app({ emit: (entry) => void entries.push(entry) })
     api.use('*', async (c, next) => {
       c.set('principal', {
-        apiKey: { environment: 'production', id: 'key_1', orgId: 'org_1', scopes: ['data:read'] },
+        apiKey: {
+          allowedIps: [],
+          environment: 'production',
+          id: 'key_1',
+          orgId: 'org_1',
+          scopes: ['data:read'],
+        },
         environment: 'production',
         id: 'key_1',
         orgId: 'org_1',

package/src/internal/OpenApi.ts

@@ -80,7 +80,7 @@ export const errorCodes = {
     'api_key_malformed',
   ],
   401: ['api_key_missing', 'api_key_invalid', 'unauthorized'],
-  403: ['api_key_forbidden', 'limit_exceeded'],
+  403: ['api_key_forbidden', 'api_key_ip_forbidden', 'limit_exceeded'],
   404: [
     'not_found',
     'token_not_found',

package/src/internal/Tidx.test.ts

@@ -460,6 +460,34 @@ describe('getClient', () => {
       fetch.mockRestore()
     }
   })
+
+  test('sends Zone headers', async () => {
+    const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(JSON.stringify({ columns: [], ok: true, row_count: 0, rows: [] }), {
+        headers: { 'content-type': 'application/json' },
+      }),
+    )
+    try {
+      const client = Tidx.getClient({
+        chainId: Zones.zoneE.id,
+        tidx: {
+          baseUrl: 'https://internal.indexer',
+          zoneHeaders: {
+            'CF-Access-Client-Id': 'client-id',
+            'CF-Access-Client-Secret': 'client-secret',
+          },
+        },
+        zone: Zones.zoneE,
+      })
+      await client.fetch({ query: 'select 1' })
+
+      const upstream = fetch.mock.calls[0]![0] as Request
+      expect(upstream.headers.get('CF-Access-Client-Id')).toBe('client-id')
+      expect(upstream.headers.get('CF-Access-Client-Secret')).toBe('client-secret')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
 })
 
 describe('createGetClient', () => {

package/src/internal/Tidx.ts

@@ -41,6 +41,7 @@ export function resolve(
   const config = typeof tidx === 'function' ? tidx(context) : tidx
   return {
     ...Auth.resolveCredential({ chainId: context.chainId, value: config?.auth }),
+    ...(context.zone && config?.zoneHeaders ? { zoneHeaders: config.zoneHeaders } : {}),
     baseUrl:
       Viem.resolveUrl(config?.baseUrl, context.chainId) ??
       context.zone?.rpcUrls['tidx']?.http[0] ??
@@ -61,18 +62,25 @@ export declare namespace resolve {
     basicAuth?: string | undefined
     /** Bearer auth credential, or undefined to send no Bearer auth. */
     bearerAuth?: string | undefined
+    /** Headers sent to Zone indexer upstreams. */
+    zoneHeaders?: Viem.ZoneHeaders | undefined
   }
 }
 
 export function getClient(options: getClient.Options): Client {
   const { chainId = Viem.defaultChainId, principal = null, tidx, zone } = options
-  const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal, zone })
+  const { baseUrl, basicAuth, bearerAuth, zoneHeaders } = resolve(tidx, {
+    chainId,
+    principal,
+    zone,
+  })
   return withTransientRetry(
     Tidx.create({
       baseUrl,
       basicAuth,
       bearerAuth,
       chainId,
+      headers: zoneHeaders,
     }),
   )
 }
@@ -96,8 +104,12 @@ export function createGetClient(options: createGetClient.Options = {}): GetClien
     const { principal = null, zone } = options
     // Resolve to derive the cache key; `getClient` re-resolves to build the
     // client on a miss. `resolve` is pure and cheap, so the extra call is free.
-    const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal, zone })
-    const cacheKey = `${baseUrl}|${basicAuth ?? ''}|${bearerAuth ?? ''}|${chainId}`
+    const { baseUrl, basicAuth, bearerAuth, zoneHeaders } = resolve(tidx, {
+      chainId,
+      principal,
+      zone,
+    })
+    const cacheKey = `${baseUrl}|${basicAuth ?? ''}|${bearerAuth ?? ''}|${JSON.stringify(zoneHeaders)}|${chainId}`
     const existing = clients.get(cacheKey)
     if (existing) return existing
 
@@ -312,12 +324,16 @@ export declare namespace getClient {
         auth?: Auth.ChainCredential | undefined
         /** Resolves the TIDX base URL for a Tempo chain id, or a static base URL. */
         baseUrl?: UrlResolver | undefined
+        /** Headers sent to Zone indexer upstreams. */
+        zoneHeaders?: Viem.ZoneHeaders | undefined
       }
     | ((context: Viem.resolveRpc.Context) => {
         /** Shared or per-chain TIDX credentials, or undefined for none. */
         auth?: Auth.ChainCredential | undefined
         /** TIDX base URL to use; falls back to the built-in public host when omitted. */
         baseUrl?: string | undefined
+        /** Headers sent to Zone indexer upstreams. */
+        zoneHeaders?: Viem.ZoneHeaders | undefined
       })
 }
 

package/src/internal/Viem.test.ts

@@ -265,6 +265,34 @@ describe('getClient', () => {
       fetch.mockRestore()
     }
   })
+
+  test('sends Zone headers to both internal and public Zone URLs', async () => {
+    const fetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ id: 1, jsonrpc: '2.0', result: '0x1079' }))
+    try {
+      const client = Viem.getClient({
+        chainId: zone.id,
+        rpc: {
+          publicZoneUrl: 'https://public.zone.rpc.test',
+          zoneHeaders: {
+            'CF-Access-Client-Id': 'client-id',
+            'CF-Access-Client-Secret': 'client-secret',
+          },
+        },
+        zone,
+        zoneToken: 'zone-token',
+      })
+      await client.getChainId()
+
+      const [input, init] = fetch.mock.calls[0]!
+      const upstream = new Request(input, init)
+      expect(upstream.headers.get('CF-Access-Client-Id')).toBe('client-id')
+      expect(upstream.headers.get('CF-Access-Client-Secret')).toBe('client-secret')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
 })
 
 describe('createGetClient', () => {

package/src/internal/Viem.ts

@@ -47,6 +47,9 @@ export type UrlResolver =
   | Record<number, string>
   | ((chainId: ChainId) => string | undefined)
 
+/** Headers required when connecting to a Zone upstream. */
+export type ZoneHeaders = Record<string, string>
+
 /** Returns chain ids declared by a static chain-id-to-URL map. */
 export function configuredChainIds(value: UrlResolver | undefined): number[] {
   const urls = parseUrls(value)
@@ -83,6 +86,7 @@ export function resolveRpc(
   return {
     ...auth,
     ...(publicZoneUrl ? { publicZoneUrl } : {}),
+    ...(context.zone && config?.zoneHeaders ? { zoneHeaders: config.zoneHeaders } : {}),
     url:
       resolveUrl(config?.url, context.chainId) ??
       context.zone?.rpcUrls['internal']?.http[0] ??
@@ -114,6 +118,8 @@ export declare namespace resolveRpc {
     bearerAuth?: string | undefined
     /** Public Zone RPC URL that accepts a caller-provided authorization token. */
     publicZoneUrl?: string | undefined
+    /** Headers sent to Zone RPC upstreams. */
+    zoneHeaders?: ZoneHeaders | undefined
     /**
      * Resolved RPC URL, or `undefined` when neither a configured `rpc` nor the
      * built-in {@link url} map covers the chain (e.g. an unconfigured localnet).
@@ -125,7 +131,7 @@ export declare namespace resolveRpc {
 
 export function getClient(options: getClient.Options): getClient.ReturnType {
   const { chainId = defaultChainId, principal = null, rpc, zone, zoneToken } = options
-  const { basicAuth, bearerAuth, publicZoneUrl, url } = resolveRpc(rpc, {
+  const { basicAuth, bearerAuth, publicZoneUrl, url, zoneHeaders } = resolveRpc(rpc, {
     chainId,
     principal,
     zone,
@@ -141,9 +147,10 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
         ? `Bearer ${bearerAuth}`
         : undefined
   const fetchOptions =
-    authorization || zoneToken
+    authorization || zoneToken || zoneHeaders
       ? {
           headers: {
+            ...(zoneHeaders ? Object.fromEntries(new Headers(zoneHeaders)) : {}),
             ...(authorization ? { Authorization: authorization } : {}),
             ...(zoneToken ? { [ZoneRpcAuthentication.headerName]: zoneToken } : {}),
           },
@@ -171,18 +178,23 @@ export function createGetClient(options: createGetClient.Options = {}): createGe
   const zones = new Map((options.zones ?? []).map((zone) => [zone.id, zone]))
 
   return (chainId = defaultChainId_option, principal = null) => {
-    const { basicAuth, bearerAuth, url } = resolveRpc(rpc, {
+    const { basicAuth, bearerAuth, url, zoneHeaders } = resolveRpc(rpc, {
       chainId,
       principal,
       zone: zones.get(chainId),
     })
-    const cacheKey = JSON.stringify([url, basicAuth, bearerAuth, chainId])
+    const cacheKey = JSON.stringify([url, basicAuth, bearerAuth, zoneHeaders, chainId])
     const existing = clients.get(cacheKey)
     if (existing) return existing
 
     const client = getClient({
       chainId,
-      rpc: { auth: basicAuth ?? bearerAuth, url: () => url },
+      rpc: {
+        auth: basicAuth ?? bearerAuth,
+        url: () => url,
+        ...(zoneHeaders ? { zoneHeaders } : {}),
+      },
+      zone: zones.get(chainId),
     })
     clients.set(cacheKey, client)
     return client
@@ -240,6 +252,8 @@ export declare namespace getClient {
         auth?: Auth.ChainCredential | undefined
         /** Resolves the public Zone RPC URL used with caller-provided authorization. */
         publicZoneUrl?: UrlResolver | undefined
+        /** Headers sent to Zone RPC upstreams. */
+        zoneHeaders?: ZoneHeaders | undefined
         /** Resolves the RPC URL for a Tempo chain id. */
         url?: UrlResolver | undefined
       }
@@ -248,6 +262,8 @@ export declare namespace getClient {
         auth?: Auth.ChainCredential | undefined
         /** Public Zone RPC URL used with caller-provided authorization. */
         publicZoneUrl?: string | undefined
+        /** Headers sent to Zone RPC upstreams. */
+        zoneHeaders?: ZoneHeaders | undefined
         /** RPC URL to use; falls back to the built-in public host when omitted. */
         url?: string | undefined
       })

package/src/internal/funding/Deposit.ts

@@ -7,6 +7,12 @@ import * as Id from '../Id.js'
 import * as Schema from '../Schema.js'
 import * as Provider from './Provider.js'
 
+/** Mechanisms that can first detect a funding deposit. */
+export const detectionTriggers = ['chain', 'manual', 'poll', 'webhook'] as const
+
+/** Mechanism that first detected a funding deposit. */
+export type DetectionTrigger = (typeof detectionTriggers)[number]
+
 /**
  * Public funding deposit statuses:
  *
@@ -95,6 +101,11 @@ export namespace schema {
       .readonly(z.array(z.string()))
       .check(z.describe(description), z.meta({ examples: [[`0x${'aa'.repeat(32)}`]] }))
 
+  /** Mechanism that first detected a funding deposit. */
+  export const DetectionTrigger = z
+    .enum(detectionTriggers)
+    .check(z.describe('How the deposit was first detected.'), z.meta({ examples: ['webhook'] }))
+
   /** Funding deposit lifecycle status. */
   export const Status = z
     .enum(statuses)
@@ -187,6 +198,7 @@ export namespace schema {
           z.meta({ examples: ['2026-08-04T00:01:00.000Z'] }),
         ),
       depositAddressId: Snapshot.shape.depositAddressId,
+      detectionTrigger: z.optional(DetectionTrigger),
       destinationAmount: Snapshot.shape.destinationAmount,
       destinationAmountRequired: Snapshot.shape.destinationAmountRequired,
       destinationChain: Snapshot.shape.destinationChain,
@@ -238,6 +250,46 @@ export type Public = z.output<typeof schema.FundingDeposit>
 
 /** Creates a durable record for one provider-observed source transaction. */
 export async function create(db: Db.Db, input: create.Input): Promise<FundingDeposits.Record> {
+  return FundingDeposits.insert(db, await record(db, input))
+}
+
+/** Creates or returns the deposit for one verified chain transfer. */
+export async function createFromSource(
+  db: Db.Db,
+  input: createFromSource.Input,
+): Promise<FundingDeposits.insertOrGetSource.Result> {
+  const stored = await record(db, {
+    detectionTrigger: 'chain',
+    now: input.now,
+    providerRequestId: null,
+    snapshot: input.snapshot,
+    sourceTransactionHash: input.sourceTransactionHash,
+    sourceTransferIndex: input.sourceTransferIndex,
+  })
+  return FundingDeposits.insertOrGetSource(db, {
+    ...stored,
+    sourceTransferIndex: input.sourceTransferIndex,
+  })
+}
+
+export declare namespace createFromSource {
+  /** Verified source transfer used to create a chain-detected deposit. */
+  type Input = {
+    /** Detection time override for deterministic tests. */
+    now?: Date | undefined
+    /** Public route and verified source amount. */
+    snapshot: Snapshot
+    /** Source transaction containing the deposited transfer. */
+    sourceTransactionHash: string
+    /** Verified transfer position within the source transaction. */
+    sourceTransferIndex: number
+  }
+}
+
+async function record(
+  db: Db.Db,
+  input: Omit<create.Input, 'providerRequestId'> & { providerRequestId: string | null },
+): Promise<FundingDeposits.Record> {
   const now = input.now ?? new Date()
   const depositAddressId = schema.Snapshot.shape.depositAddressId.parse(
     input.snapshot.depositAddressId,
@@ -256,18 +308,23 @@ export async function create(db: Db.Db, input: create.Input): Promise<FundingDep
     sourceToken: address.snapshot.sourceToken,
     sourceTransactionHashes: [input.sourceTransactionHash],
   })
-  return FundingDeposits.insert(db, {
+  return {
     createdAt: now.toISOString(),
     depositAddressId: snapshot.depositAddressId,
+    detectionTrigger: input.detectionTrigger ?? null,
     environment: address.environment,
     id: input.id ?? generateId(now),
     orgId: address.orgId,
+    pollObservedAt: input.pollObservedAt ?? null,
     projectId: address.projectId,
     providerOutputAmount: input.providerOutputAmount ?? null,
     providerOutputToken: address.providerOutputToken,
     providerRequestId: input.providerRequestId,
     providerRequestIds: [
-      ...new Set([input.providerRequestId, ...(input.providerRequestIds ?? [])]),
+      ...new Set([
+        ...(input.providerRequestId === null ? [] : [input.providerRequestId]),
+        ...(input.providerRequestIds ?? []),
+      ]),
     ],
     providerState: input.providerState ?? null,
     providerTransactionHashes: input.providerTransactionHashes ?? [],
@@ -285,16 +342,21 @@ export async function create(db: Db.Db, input: create.Input): Promise<FundingDep
     tempoGasPaid: input.tempoGasPaid ?? null,
     updatedAt: now.toISOString(),
     version: 1,
-  })
+    webhookReceivedAt: input.webhookReceivedAt ?? null,
+  }
 }
 
 export declare namespace create {
   /** Fields required to persist a provider-observed deposit. */
   type Input = {
+    /** Mechanism that first detected the deposit. */
+    detectionTrigger?: DetectionTrigger | undefined
     /** Deposit id override for deterministic tests. */
     id?: string | undefined
     /** Detection time override for deterministic tests. */
     now?: Date | undefined
+    /** When polling first observed the provider request. */
+    pollObservedAt?: string | undefined
     /** Provider output amount confirmed on Tempo. */
     providerOutputAmount?: z.output<typeof Schema.TokenAmount> | undefined
     /** Provider request that reported the source transaction. */
@@ -323,6 +385,8 @@ export declare namespace create {
     subsidyAmount?: z.output<typeof Schema.TokenAmount> | undefined
     /** Tempo gas paid for settlement, in base units. */
     tempoGasPaid?: string | undefined
+    /** When Tempo first received an authenticated provider webhook. */
+    webhookReceivedAt?: string | undefined
   }
 }
 
@@ -362,12 +426,12 @@ export async function transition(
     expectedVersion: options.expectedVersion,
     id: options.id,
     providerOutputAmount: options.providerOutputAmount ?? current.providerOutputAmount,
-    providerRequestId: current.providerRequestId,
+    providerRequestId: current.providerRequestId ?? options.providerRequestId ?? null,
     providerRequestIds: options.providerRequestIds ?? current.providerRequestIds,
     providerState: options.providerState ?? current.providerState,
     providerTransactionHashes:
       options.providerTransactionHashes ?? current.providerTransactionHashes,
-    providerTransferIndex: current.providerTransferIndex,
+    providerTransferIndex: options.providerTransferIndex ?? current.providerTransferIndex,
     retryState: options.retryState ?? current.retryState,
     settlementTransaction: options.settlementTransaction ?? current.settlementTransaction,
     settlementTransactionHash:
@@ -395,12 +459,16 @@ export declare namespace transition {
     id: string
     /** Provider output amount confirmed on Tempo. */
     providerOutputAmount?: z.output<typeof Schema.TokenAmount> | undefined
+    /** Provider request attached after chain-first detection. */
+    providerRequestId?: string | undefined
     /** Private provider request identifiers. */
     providerRequestIds?: readonly string[] | undefined
     /** Bounded private provider state. */
     providerState?: PrivateState | undefined
     /** Provider-leg transaction references. */
     providerTransactionHashes?: readonly string[] | undefined
+    /** Deposit position within the attached provider request. */
+    providerTransferIndex?: number | undefined
     /** Bounded private retry state. */
     retryState?: PrivateState | undefined
     /** Persisted settlement transaction bytes for exactly-once rebroadcast. */
@@ -434,6 +502,7 @@ export function toPublic(record: FundingDeposits.Record): Public {
   return schema.FundingDeposit.parse({
     ...record.snapshot,
     createdAt: record.createdAt,
+    ...(record.detectionTrigger === null ? {} : { detectionTrigger: record.detectionTrigger }),
     id: record.id,
     ...(record.sourceTransferIndex === null
       ? {}