tapimo 0.14.0 → 0.15.0

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

@@ -0,0 +1,1332 @@
+import { type Context, Hono } from 'hono'
+import { etag } from 'hono/etag'
+import { AbiFunction, Hex } from 'ox'
+import { getAddress } from 'viem'
+import * as z from 'zod/mini'
+
+import type * as App from '../../../App.js'
+import * as Db from '../../../db/Db.js'
+import * as RoutesIdempotency from '../../../db/tables/routesIdempotency.js'
+import * as RoutesTransfers from '../../../db/tables/routesTransfers.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as RoutesCatalog from '../../../internal/routes/Catalog.js'
+import * as RoutesObservability from '../../../internal/routes/Observability.js'
+import * as RoutesProvider from '../../../internal/routes/Provider.js'
+import * as RoutesSubsidy from '../../../internal/routes/Subsidy.js'
+import * as RoutesTransfer from '../../../internal/routes/Transfer.js'
+import * as RoutesTransferSubsidy from '../../../internal/routes/TransferSubsidy.js'
+import * as RoutesTransferReconciliation from '../../../internal/routes/TransferReconciliation.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 type * as Webhooks from '../../../internal/Webhooks.js'
+import * as Access from '../Access.js'
+
+const maximumSourceTransactionHashes = 10
+const recipientExample = getAddress(`0x${'11'.repeat(20)}`)
+const senderExample = getAddress(`0x${'22'.repeat(20)}`)
+const stargatePoolExample = '0x8c76e2f6c5ceda9aa7772e7eff30280226c44392'
+const stargateApproveExample = AbiFunction.from('function approve(address spender, uint256 amount)')
+const stargateFeeTokenExample = '0x0cEb237E109eE22374a567c6b09F373C73FA4cBb'
+const stargateSendExample = AbiFunction.from(
+  'function send((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, (uint256 nativeFee, uint256 lzTokenFee) fee, address refundAddress)',
+)
+const stargateWrapExample = AbiFunction.from(
+  'function wrap(address token, address to, uint256 amount)',
+)
+
+/** Zod schemas owned by route transfer resources. */
+export namespace schema {
+  /** A durable route transfer. Reads never include the executable `action`. */
+  export const Transfer = RoutesTransfer.schema.RoutesTransfer
+  /** Schemas for the listRoutesTransfers operation. */
+  export namespace listRoutesTransfers {
+    /** Query parameters for listing route transfers. */
+    export const Query = z
+      .object({
+        cursor: Schema.Cursor,
+        include: Schema.totalCountInclude,
+        limit: Schema.Limit,
+        status: z.optional(RoutesTransfer.schema.Status),
+      })
+      .check(z.describe('Query parameters for listing route transfers.'))
+
+    /** Paginated route transfer list. */
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(Transfer).check(z.describe('Route 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 route transfers.')),
+      'RoutesTransferList',
+    )
+  }
+
+  /** Schemas for the createRoutesTransfer operation. */
+  export namespace createRoutesTransfer {
+    /** Route transfer creation request body. */
+    export const Body = RoutesTransfer.schema.CreateRequest
+
+    /** Required headers for route 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: ['routes_01k1c5j8q8p0be6j5v9m6d1e4r'] }),
+        ),
+    })
+
+    /** The created transfer with its one-time executable action. */
+    export const Response = RoutesTransfer.schema.CreatedRoutesTransfer
+  }
+
+  const destinationCreateFields = {
+    amount: RoutesTransfer.schema.CreateRequest.shape.amount,
+    mode: RoutesTransfer.schema.CreateRequest.shape.mode,
+    recipient: RoutesTransfer.schema.CreateRequest.shape.recipient,
+    sender: RoutesTransfer.schema.CreateRequest.shape.sender,
+    slippageBps: RoutesTransfer.schema.CreateRequest.shape.slippageBps,
+    sourceChain: RoutesTransfer.schema.CreateRequest.shape.sourceChain,
+    sourceToken: RoutesTransfer.schema.CreateRequest.shape.sourceToken,
+  }
+
+  /** Schemas for the createRoutesTransferVault operation. */
+  export namespace createRoutesTransferVault {
+    /** Route transfer creation request for an Earn vault destination. */
+    export const Body = OpenApi.component(
+      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 route transfer creation request.')),
+      'CreateRoutesTransferVaultRequest',
+    )
+
+    /** Required headers for vault route transfer creation. */
+    export const Headers = createRoutesTransfer.Headers
+  }
+
+  /** Schemas for the createRoutesTransferZone operation. */
+  export namespace createRoutesTransferZone {
+    /** Route transfer creation request for a Zone destination. */
+    export const Body = OpenApi.component(
+      z
+        .strictObject({
+          amount: destinationCreateFields.amount,
+          destinationChain: z
+            .string()
+            .check(
+              z.regex(/^eip155:\d+$/),
+              z.describe('Configured Zone CAIP-2 id.'),
+              z.meta({ examples: ['eip155:1424310003'] }),
+            ),
+          destinationToken: RoutesTransfer.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 route transfer creation request.')),
+      'CreateRoutesTransferZoneRequest',
+    )
+
+    /** Required headers for Zone route transfer creation. */
+    export const Headers = createRoutesTransfer.Headers
+  }
+
+  /** Schemas for the getRoutesTransfer operation. */
+  export namespace getRoutesTransfer {
+    /** Path parameters for a route transfer read. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.describe('Route transfer ID (`rtr_…`).'),
+            z.meta({ examples: ['rtr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for a route transfer request.'))
+
+    /** The route transfer resource, returned directly. */
+    export const Response = Transfer
+  }
+
+  /** Schemas for the registerRoutesTransferSourceTransaction operation. */
+  export namespace registerRoutesTransferSourceTransaction {
+    /** Source transaction registration request body. */
+    export const Body = OpenApi.component(
+      z
+        .union([
+          z.strictObject({
+            transactionHash: Schema.hash(`0x${'51'.repeat(32)}`),
+          }),
+          z.strictObject({
+            transactionHashes: z
+              .array(Schema.hash(`0x${'52'.repeat(32)}`))
+              .check(
+                z.minLength(1),
+                z.maxLength(maximumSourceTransactionHashes),
+                z.describe('Source transactions produced by the prepared calls.'),
+              ),
+          }),
+        ])
+        .check(z.describe('Source transactions to verify and register for the transfer.')),
+      'RegisterRoutesTransferSourceTransactionRequest',
+    )
+
+    /** Path parameters for source transaction registration. */
+    export const Params = getRoutesTransfer.Params
+
+    /** The transfer after source transaction registration. */
+    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 tempoChainExample = {
+  addressFormat: 'hex',
+  id: 'eip155:4217',
+  kind: 'evm',
+  name: 'Tempo',
+} as const
+
+const tempoUsdcExample = {
+  address: '0x20c000000000000000000000b9537d11c60e8b50',
+  currency: 'USD',
+  decimals: 6,
+  name: 'Bridged USDC (Stargate)',
+  standard: 'TIP-20',
+  symbol: 'USDC.e',
+  tokenKey: 'eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50',
+  verified: true,
+} as const
+
+const tempoFeeExample = {
+  address: '0x20c0000000000000000000000000000000000000',
+  currency: 'USD',
+  decimals: 6,
+  name: 'pathUSD',
+  standard: 'TIP-20',
+  symbol: 'pathUSD',
+  tokenKey: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
+  verified: true,
+} as const
+
+const routesTransferExample = {
+  createdAt: '2026-01-01T00:00:00.000Z',
+  destinationAmount: Value.tokenAmount({ baseUnits: '979295', currency: 'USD', decimals: 6 }),
+  destinationAmountMin: Value.tokenAmount({ baseUnits: '974398', currency: 'USD', decimals: 6 }),
+  destinationAmountRequired: Value.tokenAmount({
+    baseUnits: '1000000',
+    currency: 'USD',
+    decimals: 6,
+  }),
+  destinationChain: baseChainExample,
+  destinationToken: baseUsdcExample,
+  fees: [
+    {
+      amount: Value.tokenAmount({ baseUnits: '10000', currency: 'USD', decimals: 6 }),
+      side: 'source',
+      token: tempoFeeExample,
+      type: 'provider',
+    },
+  ],
+  id: 'rtr_001767225600000_2ZPE2gvateYEQ0dQslgvkhjx',
+  method: 'transaction',
+  mode: 'exactSource',
+  provider: { id: 'stargate', name: 'Stargate' },
+  quote: {
+    expiresAt: '2026-01-01T00:01:00.000Z',
+    sampledAt: '2026-01-01T00:00:00.000Z',
+  },
+  recipient: recipientExample,
+  sender: senderExample,
+  sourceAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+  sourceChain: tempoChainExample,
+  sourceToken: tempoUsdcExample,
+  status: 'awaiting-source',
+  subsidize: true,
+  updatedAt: '2026-01-01T00:00:00.000Z',
+  version: 1,
+} satisfies z.output<typeof schema.Transfer>
+
+const registeredRoutesTransferExample = {
+  ...routesTransferExample,
+  sourceTransactionHashes: [`0x${'51'.repeat(32)}`],
+  status: 'processing',
+  updatedAt: '2026-01-01T00:00:20.000Z',
+  version: 2,
+} satisfies z.output<typeof schema.registerRoutesTransferSourceTransaction.Response>
+
+const listRoutesTransfersResponseExample = {
+  data: [routesTransferExample],
+  nextCursor: null,
+} satisfies z.output<typeof schema.listRoutesTransfers.Response>
+
+const createdRoutesTransferExample = {
+  action: {
+    calls: [
+      {
+        data: AbiFunction.encodeData(stargateApproveExample, [stargatePoolExample, 1_000_000n]),
+        to: tempoUsdcExample.address,
+        value: '0x0',
+      },
+      {
+        data: AbiFunction.encodeData(stargateApproveExample, [stargateFeeTokenExample, 10_000n]),
+        to: tempoFeeExample.address,
+        value: '0x0',
+      },
+      {
+        data: AbiFunction.encodeData(stargateWrapExample, [
+          tempoFeeExample.address,
+          senderExample,
+          10_000n,
+        ]),
+        to: stargateFeeTokenExample,
+        value: '0x0',
+      },
+      {
+        data: AbiFunction.encodeData(stargateApproveExample, [stargatePoolExample, 10_000n]),
+        to: stargateFeeTokenExample,
+        value: '0x0',
+      },
+      {
+        data: AbiFunction.encodeData(stargateSendExample, [
+          {
+            amountLD: 1_000_000n,
+            composeMsg: '0x',
+            dstEid: 30_184,
+            extraOptions: '0x',
+            minAmountLD: 974_398n,
+            oftCmd: '0x',
+            to: Hex.padLeft(recipientExample, 32),
+          },
+          { lzTokenFee: 0n, nativeFee: 10_000n },
+          senderExample,
+        ]),
+        to: stargatePoolExample,
+        value: '0x0',
+      },
+    ],
+    type: 'evm:calls',
+  },
+  ...routesTransferExample,
+} satisfies z.output<typeof schema.createRoutesTransfer.Response>
+
+const unimplementedRoutesTransferResponses = (() => {
+  const responses = OpenApi.responses({
+    errors: {
+      400: { codes: ['body_invalid', 'idempotency_key_required'] },
+      501: {
+        codes: ['not_implemented'],
+        description: 'This route 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 routesEtag = etag()
+const bodyValidation = {
+  code: 'body_invalid',
+  message: 'Check the request body and try again.',
+} as const
+const paramValidation = {
+  code: 'param_invalid',
+  message: 'Check the path parameters and try again.',
+} as const
+
+/** Mounts durable route transfer routes. */
+export function transfers(options: transfers.Options = {}) {
+  return new Hono<App.Environment>()
+    .get(
+      '/v1/routes/transfers',
+      Auth.policy({ apiKey: { scopes: ['routes:read'] } }),
+      OpenApi.validate('query', schema.listRoutesTransfers.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Lists transfers from newest to oldest.',
+        operationId: 'listRoutesTransfers',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['query_invalid'] },
+          },
+          success: {
+            description: 'A page of route transfers.',
+            example: listRoutesTransfersResponseExample,
+            schema: schema.listRoutesTransfers.Response,
+          },
+        }),
+        summary: 'List transfers',
+        tags: ['Route Transfers'],
+      }),
+      routesEtag,
+      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')
+            ? RoutesTransfers.count(db, owner, { cap: Schema.countCap, status }).catch(() => {
+                c.set('routesTransferCountFailed', true)
+                return undefined
+              })
+            : undefined
+
+          // Fetch one extra to detect a further page without a second round-trip.
+          const rows = await RoutesTransfers.listByOwner(db, owner, {
+            cursor,
+            limit: limit + 1,
+            status,
+          })
+          const hasMore = rows.length > limit
+          const data = (hasMore ? rows.slice(0, limit) : rows).map(RoutesTransfer.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.listRoutesTransfers.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/routes/transfers/:id{rtr_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['routes:read'] } }),
+      OpenApi.validate('param', schema.getRoutesTransfer.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Returns a transfer by ID.',
+        operationId: 'getRoutesTransfer',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'] },
+            404: {
+              codes: ['routes_transfer_not_found'],
+              description: 'No visible route transfer exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'The requested route transfer.',
+            example: routesTransferExample,
+            schema: schema.getRoutesTransfer.Response,
+          },
+        }),
+        summary: 'Get transfer',
+        tags: ['Route 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 RoutesTransfers.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'routes_transfer_not_found',
+              message: 'Route 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.getRoutesTransfer.Response, RoutesTransfer.toPublic(record)),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/routes/transfers/:id{rtr_[A-Za-z0-9_-]+}/source-transactions',
+      Auth.policy({ apiKey: { scopes: ['routes:write'] } }),
+      OpenApi.validate(
+        'param',
+        schema.registerRoutesTransferSourceTransaction.Params,
+        paramValidation,
+      ),
+      OpenApi.validate('json', schema.registerRoutesTransferSourceTransaction.Body, bodyValidation),
+      OpenApi.describeRoute({
+        description:
+          'Registers verified source transactions once per organization, environment, and project.',
+        operationId: 'registerRoutesTransferSourceTransaction',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: ['body_invalid', 'param_invalid', 'source_transaction_invalid'],
+              description: 'The path, body, or submitted source transaction is invalid.',
+            },
+            404: {
+              codes: ['routes_transfer_not_found'],
+              description: 'No visible route transfer exists for the identifier.',
+            },
+            409: {
+              codes: [
+                'routes_transfer_not_awaiting_source',
+                'source_transaction_conflict',
+                'source_transaction_pending',
+              ],
+              description: 'The transfer or source transaction cannot be registered yet.',
+            },
+            501: {
+              codes: ['not_implemented'],
+              description: 'Source transaction reconciliation is not configured.',
+            },
+            502: {
+              codes: ['upstream_error'],
+              description: 'Source verification or reconciliation dispatch failed.',
+            },
+          },
+          success: {
+            description: 'The transfer with its verified source transactions.',
+            example: registeredRoutesTransferExample,
+            schema: schema.registerRoutesTransferSourceTransaction.Response,
+          },
+        }),
+        summary: 'Register source transaction',
+        tags: ['Route Transfers'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
+
+        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, X-API-Key')
+
+        const dispatch = options.dispatchTransferReconciliation
+        if (!dispatch)
+          return Response.error(c, {
+            code: 'not_implemented',
+            message: 'Source transaction reconciliation is not configured',
+            status: 501,
+          })
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        const body = c.req.valid('json')
+        const transactionHashes = [
+          ...new Set('transactionHash' in body ? [body.transactionHash] : body.transactionHashes),
+        ]
+        try {
+          const record = await RoutesTransfers.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'routes_transfer_not_found',
+              message: 'Route transfer not found',
+              status: 404,
+            })
+          if (
+            transactionHashes.every((transactionHash) =>
+              record.snapshot.sourceTransactionHashes?.some(
+                (candidate) => candidate.toLowerCase() === transactionHash,
+              ),
+            )
+          ) {
+            return c.json(
+              Response.validated(
+                schema.registerRoutesTransferSourceTransaction.Response,
+                RoutesTransfer.toPublic(record),
+              ),
+              200,
+            )
+          }
+          const provider = c
+            .get('providers')
+            .filter(RoutesProvider.is)
+            .find((candidate) => candidate.id === record.providerId)
+          if (!provider || !RoutesProvider.canVerifySourceTransaction(provider))
+            return Response.error(c, {
+              code: 'routes_transfer_not_awaiting_source',
+              message: 'Route transfer does not accept source transactions',
+              status: 409,
+            })
+          if (record.status !== 'awaiting-source')
+            return Response.error(c, {
+              code: 'routes_transfer_not_awaiting_source',
+              message: 'Route transfer is not awaiting a source transaction',
+              status: 409,
+            })
+
+          const catalog = await RoutesCatalog.snapshot(c)
+          const destinationChain = catalog.chainsByKey.get(record.snapshot.destinationChain.id)
+          const sourceChain = catalog.chainsByKey.get(record.snapshot.sourceChain.id)
+          const routeConfiguration = catalog.routesByProvider
+            .get(record.providerId)
+            ?.find(
+              (candidate) =>
+                candidate.route.source.chain.id === record.snapshot.sourceChain.id &&
+                candidate.route.source.address.toLowerCase() ===
+                  record.snapshot.sourceToken.address.toLowerCase() &&
+                candidate.route.destination.chain.id === record.snapshot.destinationChain.id &&
+                candidate.route.destination.address.toLowerCase() ===
+                  record.snapshot.destinationToken.address.toLowerCase(),
+            )?.configuration
+          if (!destinationChain || !sourceChain)
+            return Response.error(c, {
+              code: 'routes_transfer_not_awaiting_source',
+              message: 'Route transfer route chains are no longer configured',
+              status: 409,
+            })
+
+          const attempts: RoutesProvider.ProviderAttemptResult[] = []
+          const verifications = transactionHashes.map(async (transactionHash) => ({
+            ...(await RoutesProvider.observe(
+              provider,
+              () =>
+                provider.verifySourceTransaction(
+                  {
+                    destinationChain,
+                    providerState: record.providerState ?? undefined,
+                    routeConfiguration,
+                    sourceChain,
+                    transactionHash,
+                    transfer: record.snapshot,
+                  },
+                  c.req.raw.signal,
+                ),
+              {
+                onAttempt: (attempt) => attempts.push(attempt),
+                operation: 'verifySourceTransaction',
+              },
+            )),
+            transactionHash,
+          }))
+          const candidates = await Promise.all(verifications)
+            .catch(async (cause) => {
+              await Promise.allSettled(verifications)
+              throw cause
+            })
+            .finally(() => {
+              if (attempts.length > 0) c.set('routesProviderAttempts', attempts)
+            })
+          const verified = candidates.filter((candidate) => candidate.type === 'verified')
+          if (candidates.some((candidate) => candidate.type === 'invalid'))
+            return Response.error(c, {
+              code: 'source_transaction_invalid',
+              message: 'Source transactions do not match the route transfer',
+              status: 400,
+            })
+          if (candidates.some((candidate) => candidate.type === 'pending'))
+            return Response.error(c, {
+              code: 'source_transaction_pending',
+              message: 'A source transaction is not confirmed yet',
+              status: 409,
+            })
+          const evidence = verified[0]
+          if (!evidence || verified.length !== 1)
+            return Response.error(c, {
+              code: 'source_transaction_invalid',
+              message: 'Source transactions do not match the route transfer',
+              status: 400,
+            })
+
+          const registered = await RoutesTransfer.registerSourceTransactions(db, {
+            chainId: record.snapshot.sourceChain.id,
+            ...(evidence.destinationAmount
+              ? {
+                  destinationAmount: Value.tokenAmount({
+                    baseUnits: evidence.destinationAmount,
+                    currency: record.snapshot.destinationToken.currency,
+                    decimals: record.snapshot.destinationToken.decimals,
+                  }),
+                }
+              : {}),
+            id: record.id,
+            providerState: evidence.providerState ?? {},
+            transactionHashes: [
+              evidence.transactionHash,
+              ...candidates
+                .filter((candidate) => candidate.type === 'related')
+                .map((candidate) => candidate.transactionHash),
+            ],
+          })
+          if (registered.type === 'not_found')
+            return Response.error(c, {
+              code: 'routes_transfer_not_found',
+              message: 'Route transfer not found',
+              status: 404,
+            })
+          if (registered.type === 'conflict')
+            return Response.error(c, {
+              code: 'source_transaction_conflict',
+              message: 'Source transaction is already assigned to another route transfer',
+              status: 409,
+            })
+          if (registered.type === 'invalid')
+            return Response.error(c, {
+              code: 'routes_transfer_not_awaiting_source',
+              message: 'Route transfer is not awaiting a source transaction',
+              status: 409,
+            })
+
+          const sourceRoutes = (() => {
+            if (registered.type !== 'registered') return undefined
+            RoutesObservability.recordTransfer(c.get('metrics'), {
+              previous: record,
+              record: registered.record,
+            })
+            return RoutesObservability.transferSourceRoutesInterval({
+              record: registered.record,
+            })
+          })()
+
+          await Promise.all([
+            registered.type === 'registered'
+              ? dispatch({ transferId: record.id, type: 'routes:transfer:reconcile' })
+              : undefined,
+            sourceRoutes && options.recordLifecycleInterval
+              ? options.recordLifecycleInterval(sourceRoutes)
+              : undefined,
+            registered.type === 'registered' &&
+            options.dispatchTransferUpdates &&
+            registered.references.length > 0
+              ? options.dispatchTransferUpdates(registered.references)
+              : undefined,
+          ])
+          return c.json(
+            Response.validated(
+              schema.registerRoutesTransferSourceTransaction.Response,
+              RoutesTransfer.toPublic(registered.record),
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/routes/transfers',
+      Auth.policy({ apiKey: { scopes: ['routes:write'] } }),
+      OpenApi.validate('header', schema.createRoutesTransfer.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Route transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createRoutesTransfer.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Creates a durable transfer between supported chains, including optional normalized destination subsidies.',
+        operationId: 'createRoutesTransfer',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid', 'idempotency_key_required'] },
+            403: {
+              codes: [
+                'billing_past_due',
+                'billing_required',
+                'routes_subsidy_limit_exceeded',
+                'routes_subsidy_not_enabled',
+              ],
+              description: 'The requested normalized delivery subsidy is unavailable.',
+            },
+            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.',
+            },
+            501: {
+              codes: ['not_implemented'],
+              description: 'Destination subsidy settlement is not configured.',
+            },
+            502: {
+              codes: ['upstream_error'],
+              description: 'No provider succeeded and at least one failed unexpectedly.',
+            },
+            503: {
+              codes: ['subsidy_inventory_unavailable', 'subsidy_signer_unavailable'],
+              description: 'Destination subsidy capacity is temporarily unavailable.',
+            },
+          },
+          success: {
+            description: 'The created route transfer with its one-time executable action.',
+            example: createdRoutesTransferExample,
+            schema: schema.createRoutesTransfer.Response,
+          },
+        }),
+        summary: 'Create transfer',
+        tags: ['Route 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 subsidize = body.subsidize ?? false
+        if (subsidize && body.mode !== 'exactSource')
+          return Response.error(c, {
+            code: 'body_invalid',
+            message: 'Normalized delivery subsidies require `exactSource` mode.',
+            status: 400,
+          })
+        const db = Db.get(c.get('db'))
+        const identity = {
+          apiKeyId: principal.id,
+          keyHash: Idempotency.inputHash(idempotencyKey),
+          requestHash: Idempotency.inputHash(body),
+        }
+        const claimed = await (async () => {
+          try {
+            return {
+              claim: await RoutesIdempotency.claim(db, {
+                ...identity,
+                irrevocable: false,
+                operation: RoutesIdempotency.operations.transfer,
+                orgId: owner.orgId,
+                ttlMs: idempotencyPendingTtlMs,
+              }),
+              type: 'success',
+            } as const
+          } catch (cause) {
+            if (RoutesIdempotency.isOwnerFenceError(cause))
+              return { type: 'ownerNotFound' } as const
+            throw cause
+          }
+        })()
+        if (claimed.type === 'ownerNotFound') return ownerNotFound(c)
+        const claim = claimed.claim
+        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 route transfer creation is still running.',
+            status: 409,
+          })
+        if (claim.type === 'replay')
+          return c.json(
+            Response.validated(
+              schema.createRoutesTransfer.Response,
+              JSON.parse(claim.response) as Record<string, unknown>,
+            ),
+            200,
+          )
+
+        const release = async () => {
+          try {
+            await RoutesIdempotency.release(db, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+            })
+          } catch {
+            // The pending claim expires on its own; the response stays authoritative.
+          }
+        }
+        try {
+          if (subsidize && !options.transferSubsidy) {
+            await release()
+            return Response.error(c, {
+              code: 'not_implemented',
+              message: 'Destination subsidy settlement is not configured.',
+              status: 501,
+            })
+          }
+          const subsidyPolicy = subsidize
+            ? await RoutesSubsidy.check(db, {
+                environment: owner.environment,
+                orgId: owner.orgId,
+              })
+            : undefined
+          if (subsidyPolicy?.type === 'denied') {
+            RoutesObservability.recordSubsidyRejection(c.get('metrics'), {
+              reason: subsidyPolicy.reason,
+              routesEnvironment: owner.environment,
+            })
+            await release()
+            return Response.error(c, {
+              code: subsidyPolicy.reason,
+              message: RoutesSubsidy.denialMessages[subsidyPolicy.reason],
+              status: 403,
+            })
+          }
+          const attempts: RoutesProvider.ProviderAttempt[] = []
+          const catalog = await RoutesCatalog.snapshot(c)
+          const providers = c.get('providers').filter(RoutesProvider.is)
+          const selected = await RoutesProvider.prepareTransfer({
+            catalog,
+            destinationChain: body.destinationChain ?? `eip155:${c.get('chainId')}`,
+            destinationToken: body.destinationToken,
+            method: 'transaction',
+            mode: body.mode,
+            onAttempt: (attempt) => attempts.push(attempt),
+            provider: body.provider,
+            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('routesProviderAttempts', attempts.map(RoutesProvider.formatAttempt))
+          if (!selected) {
+            await release()
+            return quoteNotAvailable(c)
+          }
+
+          const { candidate, result } = selected
+          const subsidyDestinationChain = subsidize
+            ? catalog.chainsByKey.get(candidate.destinationChain.id)
+            : undefined
+          if (subsidize && !subsidyDestinationChain) {
+            await release()
+            return quoteNotAvailable(c)
+          }
+          if (
+            subsidize &&
+            (candidate.sourceChain.id !== `eip155:${c.get('chainId')}` ||
+              !['eip155:1', 'eip155:8453'].includes(candidate.destinationChain.id))
+          ) {
+            await release()
+            return Response.error(c, {
+              code: 'body_invalid',
+              message: 'Destination subsidies support Tempo transfers to Base or Ethereum.',
+              status: 400,
+            })
+          }
+          const destinationAmountRequired = subsidize
+            ? RoutesTransferSubsidy.requiredAmount({
+                destinationToken: candidate.destinationToken,
+                sourceAmount: candidate.sourceAmount.amount,
+                sourceToken: candidate.sourceToken,
+              })
+            : undefined
+          const subsidyAmount =
+            destinationAmountRequired !== undefined &&
+            destinationAmountRequired > BigInt(result.destinationAmountMin)
+              ? destinationAmountRequired - BigInt(result.destinationAmountMin)
+              : 0n
+          if (
+            destinationAmountRequired !== undefined &&
+            subsidyPolicy?.type === 'allowed' &&
+            (!RoutesSubsidy.supportsGap(subsidyPolicy, {
+              amount: subsidyAmount,
+              destinationToken: candidate.destinationToken,
+            }) ||
+              (options.transferSubsidy !== undefined &&
+                !RoutesSubsidy.supportsGap(options.transferSubsidy.policy, {
+                  amount: subsidyAmount,
+                  destinationToken: candidate.destinationToken,
+                })))
+          ) {
+            await release()
+            return Response.error(c, {
+              code: 'routes_subsidy_limit_exceeded',
+              message: 'The required destination subsidy exceeds the configured limit.',
+              status: 403,
+            })
+          }
+          const snapshot: RoutesTransfer.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,
+            }),
+            ...(destinationAmountRequired === undefined
+              ? {}
+              : {
+                  destinationAmountRequired: Value.tokenAmount({
+                    baseUnits: destinationAmountRequired,
+                    currency: candidate.destinationToken.currency,
+                    decimals: candidate.destinationToken.decimals,
+                  }),
+                }),
+            destinationChain: candidate.destinationChain,
+            destinationToken: candidate.destinationToken,
+            fees: result.fees.map((fee) => {
+              const token =
+                fee.token ??
+                (fee.side === 'source' ? candidate.sourceToken : candidate.destinationToken)
+              return {
+                amount: Value.tokenAmount({
+                  baseUnits: fee.amount,
+                  currency: token.currency,
+                  decimals: token.decimals,
+                }),
+                side: fee.side,
+                token,
+                type: 'provider',
+              }
+            }),
+            method: 'transaction',
+            mode: body.mode,
+            provider: candidate.provider,
+            quote: { expiresAt: result.expiresAt, sampledAt: result.sampledAt },
+            recipient: selected.recipient,
+            sender: selected.sender,
+            sourceAmount: Value.tokenAmount({
+              baseUnits: candidate.sourceAmount.amount,
+              currency: candidate.sourceToken.currency,
+              decimals: candidate.sourceToken.decimals,
+            }),
+            sourceChain: candidate.sourceChain,
+            sourceToken: candidate.sourceToken,
+            subsidize,
+          }
+
+          // 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 input: RoutesTransfer.create.Input = {
+              apiKeyId: principal.id,
+              environment: owner.environment,
+              orgId: owner.orgId,
+              projectId: owner.projectId,
+              providerState:
+                result.correlation || result.providerState
+                  ? {
+                      ...result.correlation,
+                      ...result.providerState,
+                    }
+                  : undefined,
+              snapshot,
+            }
+            const { record, references } =
+              subsidize && subsidyAmount > 0n && options.transferSubsidy
+                ? await RoutesTransfer.reserveSubsidyCommitmentIn(tx, input, {
+                    account: options.transferSubsidy.account,
+                    chainId: candidate.destinationChain.id,
+                    check: ({ reservations }) =>
+                      options.transferSubsidy!.check({
+                        amount: subsidyAmount,
+                        chain: subsidyDestinationChain!,
+                        recipient: getAddress(selected.recipient),
+                        reservations,
+                        token: getAddress(candidate.destinationToken.address),
+                      }),
+                    subsidyCommitmentAmount: Value.tokenAmount({
+                      baseUnits: subsidyAmount,
+                      currency: candidate.destinationToken.currency,
+                      decimals: candidate.destinationToken.decimals,
+                    }),
+                    tokenAddress: candidate.destinationToken.address,
+                  })
+                : await RoutesTransfer.createIn(tx, input)
+            const validated = Response.validated(
+              schema.createRoutesTransfer.Response,
+              RoutesTransfer.toCreated(record, result.action),
+            )
+            const completion = await RoutesIdempotency.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('Route transfer creation lease was lost.')
+            return { record, references, response: validated }
+          })
+          RoutesObservability.recordTransfer(c.get('metrics'), {
+            record: created.record,
+            ...(body.provider === undefined && selected.preparedCount > 1
+              ? { selection: { bestDestinationAmount: selected.bestDestinationAmount } }
+              : {}),
+          })
+          if (options.dispatchTransferUpdates && created.references.length > 0)
+            try {
+              await options.dispatchTransferUpdates(created.references)
+            } catch (cause) {
+              return Response.upstream(c, cause)
+            }
+          return c.json(created.response, 200)
+        } catch (cause) {
+          await release()
+          if (cause instanceof RoutesProvider.InvalidAmountError)
+            return Response.error(c, { code: 'body_invalid', message: 'Invalid `amount`.', status: 400 }) // prettier-ignore
+          if (cause instanceof RoutesProvider.InvalidRecipientAddressError)
+            return Response.error(c, { code: 'body_invalid', message: 'Invalid `recipient`.', status: 400 }) // prettier-ignore
+          if (cause instanceof RoutesProvider.InvalidSenderAddressError)
+            return Response.error(c, { code: 'body_invalid', message: 'Invalid `sender`.', status: 400 }) // prettier-ignore
+          if (cause instanceof RoutesProvider.UnsupportedProviderError)
+            return Response.error(c, { code: 'body_invalid', message: 'Unsupported `provider`.', status: 400 }) // prettier-ignore
+          if (
+            cause instanceof RoutesTransferSubsidy.UnsupportedAmountError ||
+            cause instanceof RoutesTransferSubsidy.UnsupportedTokenError
+          )
+            return Response.error(c, {
+              code: 'body_invalid',
+              message: 'Normalized delivery requires compatible USD token amounts.',
+              status: 400,
+            })
+          if (
+            cause instanceof RoutesProvider.UnsupportedDestinationChainError ||
+            cause instanceof RoutesProvider.UnsupportedSourceChainError
+          )
+            return quoteNotAvailable(c)
+          if (cause instanceof RoutesTransfer.QuoteExpiredError) return quoteNotAvailable(c)
+          if (cause instanceof RoutesProvider.ProviderQuoteError) {
+            if (cause.routesProviderAttempts.length > 0)
+              c.set('routesProviderAttempts', cause.routesProviderAttempts)
+            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 route provider could prepare the transfer.',
+              status: 502,
+            })
+          }
+          if (cause instanceof RoutesTransferSubsidy.BalanceUnavailableError)
+            return Response.error(c, {
+              code: 'subsidy_inventory_unavailable',
+              message: 'Tempo lacks enough destination token inventory or native gas.',
+              status: 503,
+            })
+          if (cause instanceof RoutesTransferSubsidy.InventoryUpstreamError)
+            return Response.upstream(c, cause)
+          if (
+            cause instanceof RoutesTransfer.OrganizationNotFoundError ||
+            RoutesIdempotency.isOwnerFenceError(cause)
+          )
+            return ownerNotFound(c)
+          if (cause instanceof RoutesTransfer.SubsidySignerBlockedError)
+            return Response.error(c, {
+              code: 'subsidy_signer_unavailable',
+              message: 'Destination subsidy settlement is temporarily unavailable.',
+              status: 503,
+            })
+          throw cause
+        }
+      },
+    )
+    .post(
+      '/v1/routes/transfers/vault',
+      Auth.policy({ apiKey: { scopes: ['routes:write'] } }),
+      OpenApi.validate('header', schema.createRoutesTransferVault.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Route transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createRoutesTransferVault.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Earn vault.',
+        operationId: 'createRoutesTransferVault',
+        responses: unimplementedRoutesTransferResponses,
+        summary: 'Create transfer into vault',
+        tags: ['Route 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 route transfers are not implemented.',
+          status: 501,
+        })
+      },
+    )
+    .post(
+      '/v1/routes/transfers/zone',
+      Auth.policy({ apiKey: { scopes: ['routes:write'] } }),
+      OpenApi.validate('header', schema.createRoutesTransferZone.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Route transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createRoutesTransferZone.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Zone.',
+        operationId: 'createRoutesTransferZone',
+        responses: unimplementedRoutesTransferResponses,
+        summary: 'Create transfer into zone',
+        tags: ['Route 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 route transfers are not implemented.',
+          status: 501,
+        })
+      },
+    )
+}
+
+export declare namespace transfers {
+  /** Route transfer route dependencies. */
+  type Options = {
+    /** Enqueues one registered transfer for destination reconciliation. */
+    dispatchTransferReconciliation?:
+      | ((message: RoutesTransferReconciliation.Message) => Promise<void>)
+      | undefined
+    /** Enqueues webhook updates staged with transfer mutations. */
+    dispatchTransferUpdates?:
+      | ((references: readonly Webhooks.QueueReference[]) => Promise<number>)
+      | undefined
+    /** Records completed route lifecycle intervals. */
+    recordLifecycleInterval?:
+      | ((interval: RoutesObservability.LifecycleInterval) => Promise<void>)
+      | undefined
+    /** Read-only destination subsidy inventory, when settlement is configured. */
+    transferSubsidy?: RoutesTransferSubsidy.Inventory | undefined
+  }
+}
+
+function quoteNotAvailable(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'quote_not_available',
+    message: 'No provider can prepare the requested provider route.',
+    status: 404,
+  })
+}
+
+function ownerNotFound(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'api_key_forbidden',
+    message: 'API key organization no longer exists.',
+    status: 403,
+  })
+}
+
+class IdempotencyLeaseLostError extends Error {
+  override name = 'Routes.IdempotencyLeaseLostError'
+}