tapimo 0.7.2 → 0.9.0

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

@@ -0,0 +1,704 @@
+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 FundingIdempotency from '../../../db/tables/fundingIdempotency.js'
+import * as FundingTransfers from '../../../db/tables/fundingTransfers.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as FundingCatalog from '../../../internal/funding/Catalog.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 transfer resources. */
+export namespace schema {
+  /** A durable funding transfer. Reads never include the executable `action`. */
+  export const Transfer = FundingTransfer.schema.FundingTransfer
+  /** Schemas for the listFundingTransfers operation. */
+  export namespace listFundingTransfers {
+    /** Query parameters for listing funding transfers. */
+    export const Query = z
+      .object({
+        cursor: Schema.Cursor,
+        include: Schema.totalCountInclude,
+        limit: Schema.Limit,
+        status: z.optional(FundingTransfer.schema.Status),
+      })
+      .check(z.describe('Query parameters for listing funding transfers.'))
+
+    /** Paginated funding transfer list. */
+    export const Response = z
+      .object({
+        data: z.array(Transfer).check(z.describe('Funding transfers on this page, newest first.')),
+        meta: z
+          .optional(Schema.CountMeta)
+          .check(z.describe('Extra response metadata requested with `include`.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of funding transfers.'))
+  }
+
+  /** Schemas for the createFundingTransfer operation. */
+  export namespace createFundingTransfer {
+    /** Funding transfer creation request body. */
+    export const Body = FundingTransfer.schema.CreateRequest
+
+    /** Required headers for funding transfer 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 created transfer with its one-time executable action. */
+    export const Response = FundingTransfer.schema.CreatedFundingTransfer
+  }
+
+  const destinationCreateFields = {
+    amount: FundingTransfer.schema.CreateRequest.shape.amount,
+    mode: FundingTransfer.schema.CreateRequest.shape.mode,
+    recipient: FundingTransfer.schema.CreateRequest.shape.recipient,
+    sender: FundingTransfer.schema.CreateRequest.shape.sender,
+    slippageBps: FundingTransfer.schema.CreateRequest.shape.slippageBps,
+    sourceChain: FundingTransfer.schema.CreateRequest.shape.sourceChain,
+    sourceToken: FundingTransfer.schema.CreateRequest.shape.sourceToken,
+  }
+
+  /** Schemas for the createFundingTransferVault operation. */
+  export namespace createFundingTransferVault {
+    /** Funding transfer creation request for an Earn vault destination. */
+    export const Body = z
+      .strictObject({
+        ...destinationCreateFields,
+        vaultAddress: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Tempo Earn vault contract address.'),
+            z.meta({ examples: [`0x${'f4'.repeat(20)}`] }),
+          ),
+      })
+      .check(z.describe('Vault funding transfer creation request.'))
+
+    /** Required headers for vault funding transfer creation. */
+    export const Headers = createFundingTransfer.Headers
+  }
+
+  /** Schemas for the createFundingTransferZone operation. */
+  export namespace createFundingTransferZone {
+    /** Funding transfer creation request for a Zone destination. */
+    export const Body = z
+      .strictObject({
+        amount: destinationCreateFields.amount,
+        destinationChain: z
+          .string()
+          .check(
+            z.regex(/^eip155:\d+$/),
+            z.describe('Configured Zone CAIP-2 id.'),
+            z.meta({ examples: ['eip155:421700001'] }),
+          ),
+        destinationToken: FundingTransfer.schema.CreateRequest.shape.destinationToken,
+        mode: destinationCreateFields.mode,
+        recipient: destinationCreateFields.recipient,
+        recipientFallback: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Public Tempo recipient used if the Zone credit cannot complete.'),
+            z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
+          ),
+        sender: destinationCreateFields.sender,
+        slippageBps: destinationCreateFields.slippageBps,
+        sourceChain: destinationCreateFields.sourceChain,
+        sourceToken: destinationCreateFields.sourceToken,
+      })
+      .check(z.describe('Zone funding transfer creation request.'))
+
+    /** Required headers for Zone funding transfer creation. */
+    export const Headers = createFundingTransfer.Headers
+  }
+
+  /** Schemas for the getFundingTransfer operation. */
+  export namespace getFundingTransfer {
+    /** Path parameters for a funding transfer read. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.describe('Funding transfer ID (`ftr_…`).'),
+            z.meta({ examples: ['ftr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for a funding transfer request.'))
+
+    /** The funding transfer resource, returned directly. */
+    export const Response = Transfer
+  }
+}
+
+const baseChainExample = {
+  addressFormat: 'hex',
+  id: 'eip155:8453',
+  kind: 'evm',
+  name: 'Base',
+} as const
+
+const baseUsdcExample = {
+  address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+  currency: 'USD',
+  decimals: 6,
+  name: 'USD Coin',
+  standard: 'ERC-20',
+  symbol: 'USDC',
+  tokenKey: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+  verified: true,
+} as const
+
+const fundingTransferExample = {
+  createdAt: '2026-01-01T00:00:00.000Z',
+  destinationAmount: Value.tokenAmount({ baseUnits: '979295', currency: 'USD', decimals: 6 }),
+  destinationAmountMin: Value.tokenAmount({ baseUnits: '939242', currency: 'USD', decimals: 6 }),
+  destinationChain: {
+    addressFormat: 'hex',
+    id: 'eip155:4217',
+    kind: 'evm',
+    name: 'Tempo',
+  },
+  destinationToken: {
+    address: '0x20c0000000000000000000000000000000000000',
+    currency: 'USD',
+    decimals: 6,
+    name: 'PathUSD',
+    standard: 'TIP-20',
+    symbol: 'pathUSD',
+    tokenKey: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
+    verified: true,
+  },
+  fees: [
+    {
+      amount: Value.tokenAmount({ baseUnits: '20705', currency: 'USD', decimals: 6 }),
+      side: 'source',
+      token: baseUsdcExample,
+      type: 'provider',
+    },
+  ],
+  id: 'ftr_001767225600000_2ZPE2gvateYEQ0dQslgvkhjx',
+  method: 'transaction',
+  mode: 'exactSource',
+  provider: { id: 'relay', name: 'Relay' },
+  quote: {
+    expiresAt: '2026-01-01T00:01:00.000Z',
+    sampledAt: '2026-01-01T00:00:00.000Z',
+  },
+  recipient: `0x${'11'.repeat(20)}`,
+  sender: `0x${'22'.repeat(20)}`,
+  sourceAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+  sourceChain: baseChainExample,
+  sourceToken: baseUsdcExample,
+  status: 'awaiting-source',
+  updatedAt: '2026-01-01T00:00:00.000Z',
+  version: 1,
+} satisfies z.output<typeof schema.Transfer>
+
+const listFundingTransfersResponseExample = {
+  data: [fundingTransferExample],
+  nextCursor: null,
+} satisfies z.output<typeof schema.listFundingTransfers.Response>
+
+const createdFundingTransferExample = {
+  action: {
+    calls: [
+      {
+        data: `0x095ea7b3000000000000000000000000${'44'.repeat(20)}00000000000000000000000000000000000000000000000000000000000f4240`,
+        to: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+        value: '0x0',
+      },
+      {
+        data: '0xe8017952',
+        to: `0x${'44'.repeat(20)}`,
+        value: '0x0',
+      },
+    ],
+    type: 'evm:calls',
+  },
+  ...fundingTransferExample,
+} satisfies z.output<typeof schema.createFundingTransfer.Response>
+
+const unimplementedFundingTransferResponses = (() => {
+  const responses = OpenApi.responses({
+    errors: {
+      400: { codes: ['body_invalid', 'idempotency_key_required'] },
+      501: {
+        codes: ['not_implemented'],
+        description: 'This funding transfer destination is not implemented.',
+      },
+    },
+    success: {
+      description: 'Unused until this destination is implemented.',
+      schema: z.never(),
+    },
+  })
+  const { 200: success, 502: upstream, ...errors } = responses
+  void success
+  void upstream
+  return 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 fundingEtag = etag()
+
+/** Mounts durable funding transfer routes. */
+export function transfers() {
+  return new Hono<App.Environment>()
+    .get(
+      '/v1/funding/transfers',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('query', schema.listFundingTransfers.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Lists transfers from newest to oldest.',
+        operationId: 'listFundingTransfers',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['query_invalid'] },
+          },
+          success: {
+            description: 'A page of funding transfers.',
+            example: listFundingTransfersResponseExample,
+            schema: schema.listFundingTransfers.Response,
+          },
+        }),
+        summary: 'List transfers',
+        tags: ['Funding Transfers'],
+      }),
+      fundingEtag,
+      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, include, limit, status } = c.req.valid('query')
+        try {
+          // `totalCount` is opt-in and capped (a capped subquery shares the
+          // list filter); run it concurrently with the page list. Best-effort:
+          // a failure omits `meta` rather than failing the page.
+          const countPromise = include.includes('totalCount')
+            ? FundingTransfers.count(db, owner, { cap: Schema.countCap, status }).catch(() => {
+                c.set('fundingTransferCountFailed', true)
+                return undefined
+              })
+            : undefined
+
+          // Fetch one extra to detect a further page without a second round-trip.
+          const rows = await FundingTransfers.list(db, owner, { cursor, limit: limit + 1, status })
+          const hasMore = rows.length > limit
+          const data = (hasMore ? rows.slice(0, limit) : rows).map(FundingTransfer.toPublic)
+          const nextCursor = hasMore ? (data[data.length - 1]?.id ?? null) : null
+
+          const count = countPromise ? await countPromise : undefined
+
+          c.header('Cache-Control', Cache.policies.feed)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key')
+
+          return c.json(
+            Response.validated(schema.listFundingTransfers.Response, {
+              data,
+              ...(count !== undefined
+                ? {
+                    meta: {
+                      totalCountCapped: count > Schema.countCap,
+                      totalCount: Math.min(count, Schema.countCap),
+                    },
+                  }
+                : {}),
+              nextCursor,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/funding/transfers/:id{ftr_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('param', schema.getFundingTransfer.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Returns a transfer by ID.',
+        operationId: 'getFundingTransfer',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'] },
+            404: {
+              codes: ['funding_transfer_not_found'],
+              description: 'No visible funding transfer exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'The requested funding transfer.',
+            example: fundingTransferExample,
+            schema: schema.getFundingTransfer.Response,
+          },
+        }),
+        summary: 'Get transfer',
+        tags: ['Funding Transfers'],
+      }),
+      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 {
+          // Ownership filters in SQL, so absent and foreign rows are the same 404.
+          const record = await FundingTransfers.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_transfer_not_found',
+              message: 'Funding transfer 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.getFundingTransfer.Response,
+              FundingTransfer.toPublic(record),
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/funding/transfers',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingTransfer.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingTransfer.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer to a Tempo account.',
+        operationId: 'createFundingTransfer',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid', 'idempotency_key_required'] },
+            404: {
+              codes: ['quote_not_available'],
+              description: 'No provider can prepare the requested 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: 'No provider succeeded and at least one failed unexpectedly.',
+            },
+          },
+          success: {
+            description: 'The created funding transfer with its one-time executable action.',
+            example: createdFundingTransferExample,
+            schema: schema.createFundingTransfer.Response,
+          },
+        }),
+        summary: 'Create transfer',
+        tags: ['Funding Transfers'],
+      }),
+      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 idempotencyKey = c.req.valid('header')['idempotency-key']
+
+        const body = c.req.valid('json')
+        const db = Db.get(c.get('db'))
+        const identity = {
+          apiKeyId: principal.id,
+          keyHash: Idempotency.inputHash(idempotencyKey),
+          requestHash: Idempotency.inputHash(body),
+        }
+        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 transfer creation is still running.',
+            status: 409,
+          })
+        if (claim.type === 'replay')
+          return c.json(
+            JSON.parse(claim.response) as z.output<typeof schema.createFundingTransfer.Response>,
+            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.
+          }
+        }
+        try {
+          const attempts: FundingProvider.ProviderAttempt[] = []
+          const catalog = await FundingCatalog.snapshot(c)
+          const providers = c.get('providers').filter(FundingProvider.is)
+          const selected = await FundingProvider.prepareTransfer({
+            catalog,
+            destinationChainId: c.get('chainId'),
+            destinationToken: body.destinationToken,
+            method: 'transaction',
+            mode: body.mode,
+            onAttempt: (attempt) => attempts.push(attempt),
+            providers,
+            recipient: body.recipient,
+            sender: body.sender,
+            slippageBps: body.slippageBps,
+            sourceAmount: body.amount,
+            sourceChain: body.sourceChain,
+            sourceToken: body.sourceToken,
+          })
+          if (attempts.length > 0)
+            c.set('fundingProviderAttempts', attempts.map(ProviderAttempts.format))
+          if (!selected) {
+            await release()
+            return quoteNotAvailable(c)
+          }
+
+          const { candidate, result } = selected
+          const feeToken = (side: 'destination' | 'source') =>
+            side === 'source' ? candidate.sourceToken : candidate.destinationToken
+          const snapshot: FundingTransfer.Snapshot = {
+            destinationAmount: Value.tokenAmount({
+              baseUnits: result.destinationAmount,
+              currency: candidate.destinationToken.currency,
+              decimals: candidate.destinationToken.decimals,
+            }),
+            destinationAmountMin: Value.tokenAmount({
+              baseUnits: result.destinationAmountMin,
+              currency: candidate.destinationToken.currency,
+              decimals: candidate.destinationToken.decimals,
+            }),
+            destinationChain: candidate.destinationChain,
+            destinationToken: candidate.destinationToken,
+            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',
+            })),
+            method: 'transaction',
+            mode: body.mode,
+            provider: candidate.provider,
+            quote: { expiresAt: result.expiresAt, sampledAt: result.sampledAt },
+            recipient: body.recipient,
+            sender: body.sender,
+            sourceAmount: Value.tokenAmount({
+              baseUnits: candidate.sourceAmount.amount,
+              currency: candidate.sourceToken.currency,
+              decimals: candidate.sourceToken.decimals,
+            }),
+            sourceChain: candidate.sourceChain,
+            sourceToken: candidate.sourceToken,
+          }
+
+          // The transfer row, its version-1 event, and the replay body commit
+          // atomically so a crash cannot leave a claimed key without a replay.
+          const created = await db.transaction(async (tx) => {
+            const record = await FundingTransfer.createIn(tx, {
+              apiKeyId: principal.id,
+              environment: owner.environment,
+              orgId: owner.orgId,
+              projectId: owner.projectId,
+              providerState: result.correlation,
+              snapshot,
+            })
+            const validated = Response.validated(
+              schema.createFundingTransfer.Response,
+              FundingTransfer.toCreated(record, result.action),
+            )
+            const completion = await FundingIdempotency.complete(tx, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+              replayTtlMs: idempotencyReplayTtlMs,
+              response: JSON.stringify(validated),
+              transferId: record.id,
+            })
+            if (!completion)
+              throw new IdempotencyLeaseLostError('Funding transfer creation lease was lost.')
+            return validated
+          })
+          return c.json(created, 200)
+        } catch (cause) {
+          await release()
+          if (cause instanceof FundingProvider.InvalidAmountError)
+            return Response.error(c, { code: 'body_invalid', message: 'Invalid `amount`.', status: 400 }) // prettier-ignore
+          if (cause instanceof FundingProvider.UnsupportedSourceChainError)
+            return quoteNotAvailable(c)
+          if (cause instanceof FundingProvider.ProviderQuoteError) {
+            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: 'No funding provider could prepare the transfer.',
+              status: 502,
+            })
+          }
+          throw cause
+        }
+      },
+    )
+    .post(
+      '/v1/funding/transfers/vault',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingTransferVault.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingTransferVault.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Earn vault.',
+        operationId: 'createFundingTransferVault',
+        responses: unimplementedFundingTransferResponses,
+        summary: 'Create transfer into vault',
+        tags: ['Funding Transfers'],
+      }),
+      (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.',
+          })
+
+        c.header('Cache-Control', 'no-store')
+        return Response.error(c, {
+          code: 'not_implemented',
+          message: 'Vault funding transfers are not implemented.',
+          status: 501,
+        })
+      },
+    )
+    .post(
+      '/v1/funding/transfers/zone',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingTransferZone.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingTransferZone.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Zone.',
+        operationId: 'createFundingTransferZone',
+        responses: unimplementedFundingTransferResponses,
+        summary: 'Create transfer into zone',
+        tags: ['Funding Transfers'],
+      }),
+      (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.',
+          })
+
+        c.header('Cache-Control', 'no-store')
+        return Response.error(c, {
+          code: 'not_implemented',
+          message: 'Zone funding transfers are not implemented.',
+          status: 501,
+        })
+      },
+    )
+}
+
+function quoteNotAvailable(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'quote_not_available',
+    message: 'No provider can prepare the requested funding route.',
+    status: 404,
+  })
+}
+
+class IdempotencyLeaseLostError extends Error {
+  override name = 'Funding.IdempotencyLeaseLostError'
+}