tapimo 0.7.2 → 0.9.0

package/src/apps/funding/routes/deposit-addresses.ts

@@ -0,0 +1,932 @@
+import { type Context, Hono } from 'hono'
+import { etag } from 'hono/etag'
+import * as z from 'zod/mini'
+
+import type * as App from '../../../App.js'
+import * as Db from '../../../db/Db.js'
+import * as FundingDepositAddresses from '../../../db/tables/fundingDepositAddresses.js'
+import * as FundingDeposits from '../../../db/tables/fundingDeposits.js'
+import * as FundingIdempotency from '../../../db/tables/fundingIdempotency.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as FundingCatalog from '../../../internal/funding/Catalog.js'
+import * as FundingDeposit from '../../../internal/funding/Deposit.js'
+import * as FundingDepositAddress from '../../../internal/funding/DepositAddress.js'
+import * as FundingProvider from '../../../internal/funding/Provider.js'
+import * as FundingTransfer from '../../../internal/funding/Transfer.js'
+import * as Idempotency from '../../../internal/Idempotency.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Value from '../../../internal/Value.js'
+import * as Access from '../Access.js'
+import * as ProviderAttempts from '../ProviderAttempts.js'
+
+/** Zod schemas owned by funding deposit-address resources. */
+export namespace schema {
+  /** One reusable funding deposit address. */
+  export const DepositAddress = FundingDepositAddress.schema.FundingDepositAddress
+
+  /** One detected funding deposit. */
+  export const Deposit = FundingDeposit.schema.FundingDeposit
+
+  /** Schemas for the createFundingDepositAddress operation. */
+  export namespace createFundingDepositAddress {
+    /** Funding deposit address creation request body. */
+    export const Body = z
+      .strictObject({
+        amount: FundingTransfer.schema.CreateRequest.shape.amount,
+        destinationToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Tempo destination token symbol, contract address, or token key.'),
+            z.meta({ examples: ['usdt0'] }),
+          ),
+        recipient: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Tempo account that receives completed deposits.'),
+            z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
+          ),
+        refundAddress: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source-chain account that receives refunds.'),
+            z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] }),
+          ),
+        sourceChain: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source chain CAIP-2 id, slug, or alias.'),
+            z.meta({ examples: ['tron', 'tron:0x2b6653dc'] }),
+          ),
+        sourceToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source token symbol, contract address, or token key.'),
+            z.meta({ examples: ['usdt'] }),
+          ),
+        subsidize: z
+          .optional(z.boolean())
+          .check(
+            z.describe('Guarantees normalized 1:1 delivery through a Tempo-funded subsidy.'),
+            z.meta({ examples: [false] }),
+          ),
+      })
+      .check(z.describe('Reusable funding deposit address creation request.'))
+
+    /** Required headers for funding deposit address creation. */
+    export const Headers = z.object({
+      'idempotency-key': z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe(
+            'Opaque retry key scoped to the API key. Matching requests replay successful responses for 24 hours; changed input conflicts, in-flight requests block, and failed attempts release the key.',
+          ),
+          z.meta({ examples: ['funding_01k1c5j8q8p0be6j5v9m6d1e4r'] }),
+        ),
+    })
+
+    /** The reusable address, with quoted terms only when the provider address was newly stored. */
+    export const Response = z
+      .union([
+        FundingDepositAddress.schema.CreatedFundingDepositAddress,
+        FundingDepositAddress.schema.FundingDepositAddress,
+      ])
+      .check(
+        z.describe(
+          'A reusable funding deposit address, including terms sampled for a newly stored provider address.',
+        ),
+      )
+  }
+
+  /** Schemas for the getFundingDepositAddress operation. */
+  export namespace getFundingDepositAddress {
+    /** Path parameters for reading a funding deposit address. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.regex(/^fda_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit address ID (`fda_…`).'),
+            z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for reading a funding deposit address.'))
+
+    /** One reusable funding deposit address. */
+    export const Response = DepositAddress
+  }
+
+  /** Schemas for the reconcileFundingDepositAddress operation. */
+  export namespace reconcileFundingDepositAddress {
+    /** Path parameters for reconciling a funding deposit address. */
+    export const Params = getFundingDepositAddress.Params
+  }
+
+  /** Schemas for the listFundingDeposits operation. */
+  export namespace listFundingDeposits {
+    /** Query parameters for listing funding deposits. */
+    export const Query = z
+      .object({
+        depositAddress: z
+          .optional(z.string().check(z.minLength(1)))
+          .check(
+            z.describe('Reusable source-chain deposit address that received the funds.'),
+            z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] }),
+          ),
+        cursor: Schema.Cursor,
+        limit: Schema.Limit,
+        recipient: z
+          .optional(Schema.Address)
+          .check(
+            z.describe('Tempo account that received the deposits.'),
+            z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
+          ),
+      })
+      .check(
+        z.refine(
+          (query) => (query.depositAddress === undefined) !== (query.recipient === undefined),
+          {
+            error: 'Pass exactly one of `depositAddress` or `recipient`.',
+            path: ['depositAddress'],
+          },
+        ),
+        z.describe('Exactly one deposit filter and optional paging parameters.'),
+      )
+
+    /** One page of detected deposits. */
+    export const Response = z
+      .object({
+        data: z.array(Deposit).check(z.describe('Detected deposits on this page, newest first.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of funding deposits matching the selected filter.'))
+  }
+
+  /** Schemas for the getFundingDeposit operation. */
+  export namespace getFundingDeposit {
+    /** Path parameters for reading a funding deposit. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.regex(/^fdp_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit id (`fdp_…`).'),
+            z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for reading a funding deposit.'))
+
+    /** One detected funding deposit. */
+    export const Response = Deposit
+  }
+}
+
+const tronChainExample = {
+  addressFormat: 'base58check',
+  id: 'tron:0x2b6653dc',
+  kind: 'tron',
+  name: 'Tron',
+} as const
+
+const tronUsdtExample = {
+  address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+  currency: 'USD',
+  decimals: 6,
+  name: 'Tether USD',
+  standard: 'TRC-20',
+  symbol: 'USDT',
+  tokenKey: 'tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+  verified: true,
+} as const
+
+const tempoChainExample = {
+  addressFormat: 'hex',
+  id: 'eip155:4217',
+  kind: 'evm',
+  name: 'Tempo',
+} as const
+
+const tempoUsdt0Example = {
+  address: '0x20c00000000000000000000014f22ca97301eb73',
+  currency: 'USD',
+  decimals: 6,
+  name: 'USDT0',
+  standard: 'TIP-20',
+  symbol: 'USDT0',
+  tokenKey: 'eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73',
+  verified: true,
+} as const
+
+const fundingDepositAddressExample = {
+  address: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8',
+  createdAt: '2026-08-04T00:00:00.000Z',
+  destinationChain: tempoChainExample,
+  destinationToken: tempoUsdt0Example,
+  id: 'fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx',
+  provider: { id: 'relay', name: 'Relay' },
+  recipient: `0x${'11'.repeat(20)}`,
+  refundAddress: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8',
+  sourceChain: tronChainExample,
+  sourceToken: tronUsdtExample,
+  status: 'active',
+  subsidize: false,
+  updatedAt: '2026-08-04T00:00:00.000Z',
+} satisfies z.output<typeof schema.DepositAddress>
+
+const createdFundingDepositAddressExample = {
+  ...fundingDepositAddressExample,
+  destinationAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+  destinationAmountMin: Value.tokenAmount({
+    baseUnits: '1000000',
+    currency: 'USD',
+    decimals: 6,
+  }),
+  fees: [],
+  quote: { sampledAt: '2026-08-04T00:00:00.000Z' },
+  sourceAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+} satisfies z.output<typeof schema.createFundingDepositAddress.Response>
+
+const fundingDepositExample = {
+  createdAt: '2026-08-04T00:01:00.000Z',
+  depositAddressId: fundingDepositAddressExample.id,
+  detectionTrigger: 'webhook',
+  destinationChain: tempoChainExample,
+  destinationToken: tempoUsdt0Example,
+  id: 'fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx',
+  provider: { id: 'relay', name: 'Relay' },
+  recipient: fundingDepositAddressExample.recipient,
+  refundAddress: fundingDepositAddressExample.refundAddress,
+  sourceChain: tronChainExample,
+  sourceToken: tronUsdtExample,
+  sourceTransactionHashes: ['9f2c4c80dbb468878baa8c07ff523e0464bf6437f2a486268508485d83f14d12'],
+  status: 'detected',
+  updatedAt: '2026-08-04T00:01:00.000Z',
+} satisfies z.output<typeof schema.Deposit>
+
+const fundingDepositsExample = {
+  data: [fundingDepositExample],
+  nextCursor: null,
+} satisfies z.output<typeof schema.listFundingDeposits.Response>
+
+const reconcileFundingDepositAddressResponses = (() => {
+  const responses = OpenApi.responses({
+    errors: {
+      400: { codes: ['param_invalid'] },
+      403: {
+        codes: ['api_key_forbidden'],
+        description: 'The API key does not grant funding write access.',
+      },
+      404: {
+        codes: ['funding_deposit_address_not_found'],
+        description: 'No visible funding deposit address exists for the identifier.',
+      },
+      409: {
+        codes: ['funding_deposit_address_not_active'],
+        description: 'The funding deposit address is not active.',
+      },
+      501: {
+        codes: ['not_implemented'],
+        description: 'Manual funding reconciliation is not configured.',
+      },
+      502: {
+        codes: ['upstream_error'],
+        description: 'Reconciliation could not be queued.',
+      },
+    },
+    success: {
+      description: 'Unused because reconciliation returns an empty `202` response.',
+      schema: z.never(),
+    },
+  })
+  const { 200: success, ...errors } = responses
+  void success
+  return {
+    202: {
+      description: 'The funding deposit address was queued for reconciliation.',
+      headers: { ...OpenApi.successHeaders },
+    },
+    ...errors,
+  }
+})()
+
+// Replay the exact successful creation response for 24 hours.
+const idempotencyReplayTtlMs = 86_400_000
+// Pending claims only cover the bounded provider preparation window.
+const idempotencyPendingTtlMs = 60_000
+
+const depositAddressCheckpoint = Schema.describe(
+  z.object({
+    candidate: Schema.describe(
+      z.object({
+        destinationChain: FundingProvider.schema.ChainRef,
+        destinationToken: FundingProvider.schema.TokenRef,
+        sourceChain: FundingProvider.schema.ChainRef,
+        sourceToken: FundingProvider.schema.TokenRef,
+      }),
+      'Normalized route retained after provider provisioning.',
+    ),
+    provider: FundingProvider.schema.ProviderRef,
+    recipient: z.string().check(z.describe('Normalized Tempo recipient.')),
+    refundAddress: z.string().check(z.describe('Normalized source-chain refund account.')),
+    result: FundingProvider.schema.DepositAddressResult,
+  }),
+  'Provider result retained until deposit address creation completes.',
+)
+
+const fundingEtag = etag()
+
+/** Mounts reusable deposit-address and detected-deposit routes. */
+export function depositAddresses(options: depositAddresses.Options = {}) {
+  return new Hono<App.Environment>()
+    .post('/webhooks/funding/:providerId', async (c) => {
+      const provider = c
+        .get('providers')
+        .filter(FundingProvider.is)
+        .find((candidate) => candidate.id === c.req.param('providerId'))
+      if (!provider || !FundingProvider.canReceiveWebhook(provider)) return c.body(null, 404)
+      try {
+        await provider.webhook.receive({
+          body: await c.req.text(),
+          headers: c.req.raw.headers,
+        })
+        return c.body(null, 204)
+      } catch (cause) {
+        if (cause instanceof FundingProvider.WebhookAuthenticationError) return c.body(null, 401)
+        if (cause instanceof FundingProvider.WebhookPayloadError) return c.body(null, 400)
+        throw cause
+      }
+    })
+    .post(
+      '/v1/funding/deposit-addresses',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingDepositAddress.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding deposit address creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingDepositAddress.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates or returns a reusable deposit address for funding a Tempo account.',
+        operationId: 'createFundingDepositAddress',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid', 'idempotency_key_required'] },
+            404: {
+              codes: ['deposit_address_not_available'],
+              description: 'No provider can provision the requested reusable address route.',
+            },
+            409: {
+              codes: ['idempotency_conflict', 'idempotency_in_progress'],
+              description: 'The Idempotency-Key conflicts with an existing or in-flight request.',
+            },
+            502: {
+              codes: ['upstream_error'],
+              description: 'The selected provider could not provision the address.',
+            },
+          },
+          success: {
+            description: 'The created or matching reusable funding deposit address and quote.',
+            example: createdFundingDepositAddressExample,
+            schema: schema.createFundingDepositAddress.Response,
+          },
+        }),
+        summary: 'Create deposit address',
+        tags: ['Deposit Addresses'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        const principal = Auth.getPrincipal(c)
+        const owner = Access.owner(c)
+        if (!owner || principal?.type !== 'api_key') return Access.unauthorized(c)
+        c.header('Cache-Control', 'no-store')
+
+        const body = c.req.valid('json')
+        const subsidize = body.subsidize ?? false
+        const db = Db.get(c.get('db'))
+        const identity = {
+          apiKeyId: principal.id,
+          keyHash: Idempotency.inputHash(c.req.valid('header')['idempotency-key']),
+          requestHash: Idempotency.inputHash({
+            body,
+            endpoint: 'POST /v1/funding/deposit-addresses',
+          }),
+        }
+        const claim = await FundingIdempotency.claim(db, {
+          ...identity,
+          ttlMs: idempotencyPendingTtlMs,
+        })
+        if (claim.type === 'mismatch')
+          return Response.error(c, {
+            code: 'idempotency_conflict',
+            message: 'This Idempotency-Key was already used with different input.',
+            status: 409,
+          })
+        if (claim.type === 'pending')
+          return Response.error(c, {
+            code: 'idempotency_in_progress',
+            message: 'An equivalent funding deposit address creation is still running.',
+            status: 409,
+          })
+        if (claim.type === 'replay') {
+          const response = JSON.parse(claim.response) as Record<string, unknown>
+          return c.json(
+            Response.validated(schema.createFundingDepositAddress.Response, {
+              ...response,
+              subsidize: response['subsidize'] ?? false,
+            }),
+            200,
+          )
+        }
+
+        const release = async () => {
+          try {
+            await FundingIdempotency.release(db, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+            })
+          } catch {
+            // The pending claim expires on its own; the response stays authoritative.
+          }
+        }
+        const complete = async (
+          database: Db.Db,
+          response: z.output<typeof schema.createFundingDepositAddress.Response>,
+        ) => {
+          const validated = Response.validated(
+            schema.createFundingDepositAddress.Response,
+            response,
+          )
+          const completion = await FundingIdempotency.complete(database, {
+            apiKeyId: identity.apiKeyId,
+            createdAt: claim.createdAt,
+            keyHash: identity.keyHash,
+            replayTtlMs: idempotencyReplayTtlMs,
+            response: JSON.stringify(validated),
+          })
+          if (!completion)
+            throw new IdempotencyLeaseLostError('Funding deposit address creation lease was lost.')
+          return validated
+        }
+
+        const attempts: FundingProvider.ProviderAttempt[] = []
+        const provisioning = { succeeded: claim.type === 'resume' }
+        try {
+          const selected = await (async () => {
+            if (claim.type === 'resume')
+              return depositAddressCheckpoint.parse(JSON.parse(claim.response))
+            const catalog = await FundingCatalog.snapshot(c)
+            const providers = c.get('providers').filter(FundingProvider.is)
+            const provisioned = await FundingProvider.createDepositAddress({
+              amount: body.amount,
+              catalog,
+              destinationChainId: c.get('chainId'),
+              destinationToken: body.destinationToken,
+              onAttempt: (attempt) => attempts.push(attempt),
+              providers,
+              recipient: body.recipient,
+              refundAddress: body.refundAddress,
+              sourceChain: body.sourceChain,
+              sourceToken: body.sourceToken,
+              subsidize,
+            })
+            if (!provisioned) return undefined
+            provisioning.succeeded = true
+            const checkpoint = depositAddressCheckpoint.parse({
+              candidate: provisioned.candidate,
+              provider: provisioned.provider,
+              recipient: provisioned.recipient,
+              refundAddress: provisioned.refundAddress,
+              result: provisioned.result,
+            })
+            const stored = await FundingIdempotency.checkpoint(db, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+              replayTtlMs: idempotencyReplayTtlMs,
+              response: JSON.stringify(checkpoint),
+            })
+            if (!stored)
+              throw new IdempotencyLeaseLostError(
+                'Funding deposit address creation lease was lost.',
+              )
+            return checkpoint
+          })()
+          if (attempts.length > 0)
+            c.set('fundingProviderAttempts', attempts.map(ProviderAttempts.format))
+          if (!selected) {
+            await release()
+            return depositAddressNotAvailable(c)
+          }
+
+          const {
+            candidate: selectedCandidate,
+            provider,
+            recipient,
+            refundAddress,
+            result,
+          } = selected
+          const feeToken = (side: 'destination' | 'source') =>
+            side === 'source' ? selectedCandidate.sourceToken : selectedCandidate.destinationToken
+          const created = await db.transaction(async (tx) => {
+            const stored = await FundingDepositAddress.createOrGet(tx, {
+              apiKeyId: principal.id,
+              deliveryStrategy: 'provider',
+              environment: owner.environment,
+              orgId: owner.orgId,
+              ...(owner.projectId === undefined ? {} : { projectId: owner.projectId }),
+              providerOutputToken: selectedCandidate.destinationToken,
+              providerRequestIds: [result.correlation.requestId],
+              providerState:
+                result.correlation.checkEndpoint === undefined
+                  ? undefined
+                  : { checkEndpoint: result.correlation.checkEndpoint },
+              snapshot: {
+                address: result.address,
+                destinationChain: selectedCandidate.destinationChain,
+                destinationToken: selectedCandidate.destinationToken,
+                provider,
+                recipient,
+                refundAddress,
+                sourceChain: selectedCandidate.sourceChain,
+                sourceToken: selectedCandidate.sourceToken,
+                subsidize,
+              },
+            })
+            const record = FundingDepositAddress.toPublic(stored.record)
+            if (stored.type === 'existing') return complete(tx, record)
+            return complete(tx, {
+              ...record,
+              destinationAmount: Value.tokenAmount({
+                baseUnits: result.destinationAmount,
+                currency: selectedCandidate.destinationToken.currency,
+                decimals: selectedCandidate.destinationToken.decimals,
+              }),
+              destinationAmountMin: Value.tokenAmount({
+                baseUnits: result.destinationAmountMin,
+                currency: selectedCandidate.destinationToken.currency,
+                decimals: selectedCandidate.destinationToken.decimals,
+              }),
+              fees: result.fees.map((fee) => ({
+                amount: Value.tokenAmount({
+                  baseUnits: fee.amount,
+                  currency: feeToken(fee.side).currency,
+                  decimals: feeToken(fee.side).decimals,
+                }),
+                side: fee.side,
+                token: feeToken(fee.side),
+                type: 'provider',
+              })),
+              quote: {
+                ...(result.expiresAt === undefined ? {} : { expiresAt: result.expiresAt }),
+                sampledAt: result.sampledAt,
+              },
+              sourceAmount: Value.tokenAmount({
+                baseUnits: body.amount,
+                currency: selectedCandidate.sourceToken.currency,
+                decimals: selectedCandidate.sourceToken.decimals,
+              }),
+            })
+          })
+          if (options.registerDepositAddress)
+            await options.registerDepositAddress(
+              FundingDepositAddress.schema.FundingDepositAddress.parse(created),
+            )
+          return c.json(created, 200)
+        } catch (cause) {
+          if (!provisioning.succeeded) await release()
+          if (cause instanceof FundingProvider.InvalidRefundAddressError)
+            return Response.error(c, {
+              code: 'body_invalid',
+              message: 'Invalid `refundAddress`.',
+              status: 400,
+            })
+          if (cause instanceof FundingProvider.UnsupportedSourceChainError)
+            return depositAddressNotAvailable(c)
+          if (
+            cause instanceof FundingDepositAddress.ConflictError ||
+            cause instanceof FundingProvider.ProviderQuoteError
+          ) {
+            if (cause instanceof FundingDepositAddress.ConflictError)
+              return Response.error(c, {
+                code: 'upstream_error',
+                message: 'The funding provider returned a conflicting deposit address.',
+                status: 502,
+              })
+            if (cause.fundingProviderAttempts.length > 0)
+              c.set('fundingProviderAttempts', cause.fundingProviderAttempts)
+            if (cause.providerFailure) c.set('providerFailure', cause.providerFailure)
+            if (cause.providerFailures) c.set('providerFailures', cause.providerFailures)
+            return Response.error(c, {
+              code: 'upstream_error',
+              message: 'The funding provider could not provision the deposit address.',
+              status: 502,
+            })
+          }
+          throw cause
+        }
+      },
+    )
+    .get(
+      '/v1/funding/deposit-addresses/:id{fda_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('param', schema.getFundingDepositAddress.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Returns one reusable funding deposit address.',
+        operationId: 'getFundingDepositAddress',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'] },
+            404: {
+              codes: ['funding_deposit_address_not_found'],
+              description: 'No visible funding deposit address exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'The requested funding deposit address.',
+            example: fundingDepositAddressExample,
+            schema: schema.getFundingDepositAddress.Response,
+          },
+        }),
+        summary: 'Get deposit address',
+        tags: ['Deposit Addresses'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const owner = Access.owner(c)
+        if (!owner) return Access.unauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        try {
+          const record = await FundingDepositAddresses.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_deposit_address_not_found',
+              message: 'Funding deposit address not found',
+              status: 404,
+            })
+
+          c.header('Cache-Control', Cache.policies.noStore)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key')
+          return c.json(
+            Response.validated(
+              schema.getFundingDepositAddress.Response,
+              FundingDepositAddress.toPublic(record),
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/funding/deposit-addresses/:id{fda_[A-Za-z0-9_-]+}/reconcile',
+      Auth.policy({
+        apiKey: { rateLimit: { perMinute: 10 }, scopes: ['funding:write'] },
+      }),
+      OpenApi.validate('param', schema.reconcileFundingDepositAddress.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Queues an immediate provider reconciliation for one reusable funding deposit address.',
+        operationId: 'reconcileFundingDepositAddress',
+        responses: reconcileFundingDepositAddressResponses,
+        summary: 'Reconcile deposit address',
+        tags: ['Deposit Addresses'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const owner = Access.owner(c)
+        if (!owner) return Access.unauthorized(c)
+
+        c.header('Cache-Control', Cache.policies.noStore)
+        c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key')
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        try {
+          const record = await FundingDepositAddresses.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_deposit_address_not_found',
+              message: 'Funding deposit address not found',
+              status: 404,
+            })
+          if (record.status !== 'active')
+            return Response.error(c, {
+              code: 'funding_deposit_address_not_active',
+              message: 'Funding deposit address is not active',
+              status: 409,
+            })
+          const dispatch = options.dispatchReconciliation
+          if (!dispatch)
+            return Response.error(c, {
+              code: 'not_implemented',
+              message: 'Manual funding reconciliation is not configured',
+              status: 501,
+            })
+
+          await dispatch({
+            addressId: record.id,
+            trigger: 'manual',
+            type: 'funding:deposit-address:reconcile',
+          })
+          return c.body(null, 202)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/funding/deposits',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('query', schema.listFundingDeposits.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Lists deposits by deposit address or Tempo recipient, newest first.',
+        operationId: 'listFundingDeposits',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['query_invalid'] },
+          },
+          success: {
+            description: 'A page of funding deposits matching the selected filter.',
+            example: fundingDepositsExample,
+            schema: schema.listFundingDeposits.Response,
+          },
+        }),
+        summary: 'List deposits',
+        tags: ['Deposit Addresses'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const owner = Access.owner(c)
+        if (!owner) return Access.unauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { cursor, depositAddress, limit, recipient } = c.req.valid('query')
+        const decoded = cursor ? Cursor.decode(cursor, ['timestamp', 'id']) : undefined
+        try {
+          const paging = {
+            ...(decoded
+              ? { cursor: { createdAt: String(decoded[0]), id: String(decoded[1]) } }
+              : {}),
+            limit: limit + 1,
+            owner,
+          }
+          const rows =
+            depositAddress === undefined
+              ? await FundingDeposits.listByRecipient(db, { ...paging, recipient: recipient! })
+              : await FundingDeposits.listByDepositAddress(db, { ...paging, depositAddress })
+          const page = Cursor.paginate({
+            key: (record) => [record.createdAt, record.id],
+            limit,
+            rows,
+          })
+          const data = page.rows.map(FundingDeposit.toPublic)
+
+          c.header('Cache-Control', Cache.policies.noStore)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key')
+          return c.json(
+            Response.validated(schema.listFundingDeposits.Response, {
+              data,
+              nextCursor: page.nextCursor,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/funding/deposits/:id{fdp_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('param', schema.getFundingDeposit.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Returns one detected deposit and its delivery status.',
+        operationId: 'getFundingDeposit',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'] },
+            404: {
+              codes: ['funding_deposit_not_found'],
+              description: 'No visible funding deposit exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'The requested funding deposit.',
+            example: fundingDepositExample,
+            schema: schema.getFundingDeposit.Response,
+          },
+        }),
+        summary: 'Get deposit',
+        tags: ['Deposit Addresses'],
+      }),
+      fundingEtag,
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const owner = Access.owner(c)
+        if (!owner) return Access.unauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        try {
+          const record = await FundingDeposits.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_deposit_not_found',
+              message: 'Funding deposit not found',
+              status: 404,
+            })
+
+          c.header('Cache-Control', Cache.policies.state)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key')
+          return c.json(
+            Response.validated(schema.getFundingDeposit.Response, FundingDeposit.toPublic(record)),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+export declare namespace depositAddresses {
+  /** Deposit-address route dependencies. */
+  type Options = {
+    /** Enqueues one deposit address for asynchronous reconciliation. */
+    dispatchReconciliation?:
+      | ((message: FundingProvider.Webhook.receive.Dispatchable) => Promise<void>)
+      | undefined
+    /** Registers a created address with a source-chain observer. */
+    registerDepositAddress?: ((address: FundingDepositAddress.Public) => Promise<void>) | undefined
+  }
+}
+
+function depositAddressNotAvailable(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'deposit_address_not_available',
+    message: 'No provider can provision the requested reusable deposit address.',
+    status: 404,
+  })
+}
+
+class IdempotencyLeaseLostError extends Error {
+  override name = 'Funding.IdempotencyLeaseLostError'
+}