tapimo 0.7.2 → 0.9.0

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
       ? {}

package/src/internal/funding/Evidence.test.ts

@@ -83,7 +83,7 @@ describe('resolveRpcUrls', () => {
 })
 
 describe('createVerifier', () => {
-  test('verifies finalized Solana and Tron token transfers', async () => {
+  test('verifies finalized Solana and one-confirmation Tron token transfers', async () => {
     const tron = TestFunding.depositAddressSnapshot()
     const solana = TestFunding.transferSnapshot({
       sourceChain: {
@@ -118,7 +118,7 @@ describe('createVerifier', () => {
         return
       }
       const result = request.url?.includes('getnowblock')
-        ? { block_header: { raw_data: { number: 200 } } }
+        ? { block_header: { raw_data: { number: 150 } } }
         : request.url?.includes('gettransactioninfobyid')
           ? {
               blockNumber: 150,

package/src/internal/funding/Evidence.ts

@@ -14,6 +14,7 @@ const transferEvent = AbiEvent.from(
 )
 const transferTopic = AbiEvent.getSelector(transferEvent).slice(2)
 const catalogCacheTtlMs = 60_000
+const defaultConfirmations = 1
 
 type SolanaRpcSchema = RpcSchema.From<{
   Request: {
@@ -117,7 +118,7 @@ export declare namespace resolveRpcUrls {
   }
 }
 
-/** Creates a finalized token-transfer verifier for EVM, Solana, and Tron chains. */
+/** Creates a token-transfer verifier for EVM, Solana, and Tron chains. */
 export function createVerifier(options: createVerifier.Options): Reconciliation.VerifyTransfers {
   const fetch = options.fetch ?? globalThis.fetch
   // Delay this shared read until reconciliation releases its claim transaction.
@@ -156,15 +157,13 @@ export function createVerifier(options: createVerifier.Options): Reconciliation.
     if (!urls || urls.length === 0) throw new ChainConfigurationError(parameters.chain.id)
     if (parameters.chain.kind === 'evm')
       return verifyEvm(parameters, {
-        confirmations:
-          options.confirmations?.[parameters.chain.id] ?? options.defaultEvmConfirmations ?? 12,
+        confirmations: options.confirmations?.[parameters.chain.id] ?? defaultConfirmations,
         fetch,
         urls,
       })
     if (parameters.chain.kind === 'solana') return verifySolana(parameters, { fetch, urls })
     return verifyTron(parameters, {
-      confirmations:
-        options.confirmations?.[parameters.chain.id] ?? options.defaultTronConfirmations ?? 20,
+      confirmations: options.confirmations?.[parameters.chain.id] ?? defaultConfirmations,
       fetch,
       urls,
     })
@@ -180,10 +179,6 @@ export declare namespace createVerifier {
     db: Db.Source
     /** Tempo chain that receives a shared RPC URL override. */
     defaultChainId?: Viem.ChainId | undefined
-    /** Default confirmation requirement for EVM chains. */
-    defaultEvmConfirmations?: number | undefined
-    /** Default confirmation requirement for Tron. */
-    defaultTronConfirmations?: number | undefined
     /** Fetch implementation override for tests. */
     fetch?: typeof globalThis.fetch | undefined
     /** Shared or per-EVM-chain RPC URL environment value. */

package/src/internal/funding/Provider.ts

@@ -249,6 +249,7 @@ export namespace schema {
     createdAt: z.iso.datetime(),
     destinationTransactionHashes: z.array(z.string()),
     id: z.string().check(z.minLength(1)),
+    providerState: z.optional(z.record(z.string(), z.unknown())),
     sourceTransactionHashes: z.array(z.string()),
     status: z.string().check(z.minLength(1)),
     updatedAt: z.iso.datetime(),
@@ -478,6 +479,68 @@ export declare namespace listDepositAddressRequests {
   type ReturnType = z.output<typeof schema.DepositAddressRequestsResult>
 }
 
+/** Contract of the provider `observeDepositAddressRequest` method. */
+export declare namespace observeDepositAddressRequest {
+  /** Verified source transfer used to correlate provider delivery. */
+  type Source = {
+    /** Token quantity in base units. */
+    amount: string
+    /** Verified source transaction reference. */
+    transactionHash: string
+  }
+
+  /** Input passed to a provider observing one pending reusable-address request. */
+  type Parameters = {
+    /** Provider-owned reusable deposit address. */
+    address: string
+    /** Chain that receives provider delivery. */
+    destinationChain: ChainRef
+    /** Token delivered by the provider. */
+    destinationToken: TokenRef
+    /** Bounded private provider correlation from an earlier observation. */
+    providerState?: Record<string, unknown> | undefined
+    /** Final beneficiary on the destination chain. */
+    recipient: string
+    /** Source-chain account credited by the provider deposit. */
+    refundAddress: string
+    /** Provider request, when the provider has indexed the source transfer. */
+    request?: listDepositAddressRequests.ReturnType['requests'][number] | undefined
+    /** One verified source transfer received by the deposit address. */
+    source: Source
+    /** Chain containing the source transfer. */
+    sourceChain: ChainRef
+    /** Token received by the reusable address. */
+    sourceToken: TokenRef
+  }
+
+  /** Private provider evidence shared by pending and verified observations. */
+  type Evidence = {
+    /** Bounded private provider correlation retained for reconciliation. */
+    providerState?: Record<string, unknown> | undefined
+    /** Verified provider-leg transaction references. */
+    providerTransactionHashes?: readonly string[] | undefined
+  }
+
+  /** Bounded provider delivery observation. */
+  type ReturnType = Evidence &
+    (
+      | {
+          /** No matching provider delivery has reached the destination yet. */
+          type: 'pending'
+        }
+      | {
+          /** This provider or route cannot produce authenticated delivery observations. */
+          type: 'unsupported'
+        }
+      | {
+          /** Verified destination transaction references. */
+          destinationTransactionHashes: readonly string[]
+          /** Authenticated provider delivery was observed onchain. */
+          type: 'verified'
+        }
+    )
+}
+
 /** Optional webhook capability implemented by a complete funding integration. */
 export type Webhook = {
   /** Authenticates, resolves, and enqueues one provider status event. */
@@ -502,12 +565,46 @@ export declare namespace Webhook {
     type Dispatchable = {
       /** Stored funding deposit address id. */
       addressId: string
+      /** Bounded follow-up state for work awaiting provider or settlement confirmation. */
+      followUp?: FollowUp | undefined
       /** Reconciliation lease fencing token, when a scheduled poll already claimed the address. */
       pollLeaseVersion?: number | undefined
       /** Optional provider request id that triggered reconciliation. */
       requestId?: string | undefined
+      /** Mechanism that requested reconciliation. */
+      trigger: 'chain' | 'manual' | 'poll' | 'webhook'
       /** Reconciliation queue message discriminator. */
       type: 'funding:deposit-address:reconcile'
+      /** Authenticated provider webhook timing carried into reconciliation. */
+      webhookTiming?: WebhookTiming | undefined
+    }
+
+    /** Bounded follow-up state carried between delayed reconciliation messages. */
+    type FollowUp = {
+      /** Zero-based attempt in the current follow-up schedule. */
+      attempt: number
+      /** Work that still awaits confirmation. */
+      kind: 'delivery' | 'provider' | 'settlement'
+    }
+
+    /** Authenticated provider webhook timing used for latency measurement. */
+    type WebhookTiming = {
+      /** When Tempo sent the reconciliation message to its queue. */
+      enqueuedAt: string
+      /** Bounded provider status carried by the webhook. */
+      providerStatus: string
+      /** When the provider last changed the request status. */
+      providerUpdatedAt: string
+      /** When Tempo started processing the webhook request. */
+      receivedAt: string
+      /** When the provider sent the signed webhook. */
+      sentAt: string
+    }
+
+    /** Durable reconciliation message, including messages queued before trigger attribution. */
+    type Queued = Omit<Dispatchable, 'trigger'> & {
+      /** Mechanism that requested reconciliation, when written by a trigger-aware producer. */
+      trigger?: Dispatchable['trigger'] | undefined
     }
 
     /** Safe disposition of one authenticated funding provider webhook. */
@@ -526,8 +623,14 @@ export declare namespace Webhook {
     type ReturnType = {
       /** Reusable provider address, when the provider attributed one. */
       address?: string | undefined
+      /** Bounded provider status carried by the webhook. */
+      providerStatus?: string | undefined
+      /** When the provider last changed the request status. */
+      providerUpdatedAt?: string | undefined
       /** Provider request id, when included in the event. */
       requestId?: string | undefined
+      /** When the provider sent the signed webhook. */
+      sentAt?: string | undefined
     }
   }
 }
@@ -546,6 +649,11 @@ export type Provider<id extends string = string> = core_Provider.Provider<id, 'f
     input: listDepositAddressRequests.Parameters,
     signal: AbortSignal,
   ): Promise<listDepositAddressRequests.ReturnType>
+  /** Observes authenticated delivery for a verified reusable-address transfer, when supported. */
+  observeDepositAddressRequest?(
+    input: observeDepositAddressRequest.Parameters,
+    signal: AbortSignal,
+  ): Promise<observeDepositAddressRequest.ReturnType>
   /** Prepares an executable funding transfer, when the provider supports it. */
   prepareTransfer?(
     input: prepareTransfer.Parameters,
@@ -595,6 +703,13 @@ export function canListDepositAddressRequests(provider: Provider): provider is P
   return typeof provider.listDepositAddressRequests === 'function'
 }
 
+/** Narrows a funding provider to one that observes reusable-address delivery onchain. */
+export function canObserveDepositAddressRequest(provider: Provider): provider is Provider & {
+  observeDepositAddressRequest: NonNullable<Provider['observeDepositAddressRequest']>
+} {
+  return typeof provider.observeDepositAddressRequest === 'function'
+}
+
 /** Narrows a funding provider to one with authenticated webhook receipt. */
 export function canReceiveWebhook(provider: Provider): provider is Provider & {
   webhook: Webhook