tapimo 0.15.0 → 0.18.0

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

@@ -1,6 +1,7 @@
 import { type Context, Hono } from 'hono'
 import { bodyLimit } from 'hono/body-limit'
 import { etag } from 'hono/etag'
+import { Value as core_Value } from 'ox'
 import * as z from 'zod/mini'
 
 import type * as App from '../../../App.js'
@@ -15,6 +16,7 @@ import * as RoutesCatalog from '../../../internal/routes/Catalog.js'
 import * as RoutesDeposit from '../../../internal/routes/Deposit.js'
 import * as RoutesDepositAddress from '../../../internal/routes/DepositAddress.js'
 import * as RoutesObservability from '../../../internal/routes/Observability.js'
+import * as RoutesPolicy from '../../../internal/routes/Policy.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'
@@ -498,8 +500,10 @@ const depositAddressCheckpoint = Schema.describe(
       'Normalized route retained after provider provisioning.',
     ),
     provider: RoutesProvider.schema.ProviderRef,
+    policyVersions: z.optional(z.array(z.number().check(z.int(), z.nonnegative()))),
     recipient: z.string().check(z.describe('Normalized Tempo recipient.')),
     refundAddress: z.string().check(z.describe('Normalized source-chain refund account.')),
+    routePolicy: z.optional(RoutesPolicy.schema.Commitment),
     result: RoutesProvider.schema.DepositAddressResult,
   }),
   'Provider result retained until deposit address creation completes.',
@@ -572,25 +576,34 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
         operationId: 'createRoutesDepositAddress',
         responses: OpenApi.responses({
           errors: {
-            400: { codes: ['body_invalid', 'idempotency_key_required'] },
+            400: { codes: ['amount_too_low', 'body_invalid', 'idempotency_key_required'] },
             403: {
               codes: [
                 'billing_past_due',
                 'billing_required',
                 'routes_deposit_address_limit_exceeded',
+                'routes_not_allowed',
+                'routes_subsidy_not_allowed',
                 'routes_subsidy_not_enabled',
+                'routes_suspended',
               ],
               description:
                 'The organization cannot create another address or is not eligible for a Tempo-funded Routes subsidy.',
               name: 'CreateRoutesDepositAddressForbiddenError',
             },
             404: {
-              codes: ['deposit_address_not_available'],
-              description: 'No provider can provision the requested reusable address route.',
+              codes: ['deposit_address_not_available', 'quote_not_available'],
+              description: 'The reusable address route or current quote is unavailable.',
             },
             409: {
-              codes: ['idempotency_conflict', 'idempotency_in_progress'],
-              description: 'The Idempotency-Key conflicts with an existing or in-flight request.',
+              codes: [
+                'idempotency_conflict',
+                'idempotency_in_progress',
+                'route_policy_changed',
+                'route_policy_identity_conflict',
+              ],
+              description:
+                'The request conflicts with an existing address, policy, or in-flight request.',
             },
             502: {
               codes: ['upstream_error'],
@@ -721,28 +734,30 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
         const attempts: RoutesProvider.ProviderAttempt[] = []
         const provisioning = { succeeded: claim.type === 'resume' }
         try {
-          if (claim.type === 'claimed' && subsidize) {
-            const policy = await RoutesSubsidy.check(db, {
-              environment: owner.environment,
-              orgId: owner.orgId,
+          const policyContext = await Access.loadPolicy(c)
+          if (!policyContext) throw new Error('Missing route policy context for API key.')
+          const legacy = Access.isLegacy(policyContext)
+          const policy =
+            legacy && claim.type === 'claimed' && subsidize
+              ? await RoutesSubsidy.check(db, owner)
+              : undefined
+          if (policy?.type === 'denied') {
+            RoutesObservability.recordSubsidyRejection(c.get('metrics'), {
+              reason: policy.reason,
+              routesEnvironment: owner.environment,
+            })
+            await release()
+            return Response.error(c, {
+              code: policy.reason,
+              message: RoutesSubsidy.denialMessages[policy.reason],
+              status: 403,
             })
-            if (policy.type === 'denied') {
-              RoutesObservability.recordSubsidyRejection(c.get('metrics'), {
-                reason: policy.reason,
-                routesEnvironment: owner.environment,
-              })
-              await release()
-              return Response.error(c, {
-                code: policy.reason,
-                message: RoutesSubsidy.denialMessages[policy.reason],
-                status: 403,
-              })
-            }
           }
           const selected = await (async () => {
-            if (claim.type === 'resume')
+            if (claim.type === 'resume') {
+              const checkpoint = depositAddressCheckpoint.parse(JSON.parse(claim.response))
               return {
-                checkpoint: depositAddressCheckpoint.parse(JSON.parse(claim.response)),
+                checkpoint,
                 checkpointFresh: claim.checkpointFresh,
                 ...(claim.recoveredClaim === undefined
                   ? {}
@@ -750,10 +765,17 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
                 quoteMatchesRequest: claim.checkpointFresh,
                 type: 'resume',
               } as const
-            const catalog = await RoutesCatalog.snapshot(c)
-            const providers = c.get('providers').filter(RoutesProvider.is)
-            const selection = RoutesProvider.selectDepositAddress({
-              catalog,
+            }
+            const fullCatalog = await RoutesCatalog.snapshot(c)
+            const catalog = Access.filterCatalog(fullCatalog, policyContext, subsidize)
+            const providers = c
+              .get('providers')
+              .filter(RoutesProvider.is)
+              .filter(
+                (provider) =>
+                  !subsidize || options.depositSubsidyAccount || provider.id === 'relay',
+              )
+            const request = {
               destinationChainId: c.get('chainId'),
               destinationToken: body.destinationToken,
               providers,
@@ -761,12 +783,100 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
               refundAddress: body.refundAddress,
               sourceChain: body.sourceChain,
               sourceToken: body.sourceToken,
+            }
+            const candidates = RoutesProvider.getDepositAddressCandidates({
+              ...request,
+              catalog: fullCatalog,
+            })
+            if (
+              candidates.length > 0 &&
+              !candidates.some(({ candidate }) =>
+                catalog.routes.some((entry) => entry.route === candidate.route),
+              )
+            )
+              throw new Access.PolicyError(
+                subsidize ? 'routes_subsidy_not_allowed' : 'routes_not_allowed',
+              )
+            if (candidates.length === 0) return undefined
+            const commitments = new Map<
+              RoutesProvider.QuoteCandidate['route'],
+              RoutesPolicy.Commitment
+            >()
+            if (subsidize && !legacy) {
+              let denied: Access.PolicyError | undefined
+              for (const { candidate } of RoutesProvider.getDepositAddressCandidates({
+                ...request,
+                catalog,
+              })) {
+                try {
+                  commitments.set(
+                    candidate.route,
+                    await Access.commitment(
+                      db,
+                      policyContext,
+                      RoutesPolicy.fromRoute({
+                        providerId: candidate.provider.id,
+                        route: candidate.route,
+                      }),
+                      options.depositSubsidyMaxAmount ?? '0',
+                    ),
+                  )
+                } catch (cause) {
+                  if (!(cause instanceof Access.PolicyError)) throw cause
+                  denied = cause
+                }
+              }
+              if (commitments.size === 0 && denied) throw denied
+            }
+            const selection = RoutesProvider.selectDepositAddress({
+              ...request,
+              catalog:
+                subsidize && !legacy
+                  ? {
+                      ...catalog,
+                      routes: catalog.routes.filter((entry) => commitments.has(entry.route)),
+                    }
+                  : catalog,
             })
             if (!selection) return undefined
+            const commitment = commitments.get(selection.candidate.route)
+            const subsidyMaxAmount = (() => {
+              if (commitment) return commitment.maxAmount
+              if (policy?.type !== 'allowed') return undefined
+              const maximum = core_Value.from(policy.maxAmount, 6)
+              const platform = core_Value.from(options.depositSubsidyMaxAmount ?? '0', 6)
+              return core_Value.format(maximum < platform ? maximum : platform, 6)
+            })()
+            // Relay pins sponsorship to the address, including addresses created under legacy grants.
+            const routePolicy =
+              commitment ??
+              (selection.candidate.provider.id === 'relay' && subsidyMaxAmount !== undefined
+                ? {
+                    maxAmount: subsidyMaxAmount,
+                    scope: policyContext.scope,
+                    subsidyPayer: 'enterprise' as const,
+                    versions: policyContext.versions,
+                  }
+                : undefined)
             const match = {
               destinationTokenKey: selection.candidate.destinationToken.tokenKey,
               environment: owner.environment,
               orgId: owner.orgId,
+              ...(!legacy || (subsidize && selection.candidate.provider.id === 'relay')
+                ? {
+                    policyKey: RoutesPolicy.depositKey({
+                      ...(subsidize && selection.candidate.provider.id === 'relay'
+                        ? { fixedRate: '1:1' }
+                        : {}),
+                      routePolicy,
+                    }),
+                  }
+                : {}),
+              ...(legacy && !routePolicy
+                ? {}
+                : {
+                    providerId: selection.candidate.provider.id,
+                  }),
               ...(owner.projectId === undefined ? {} : { projectId: owner.projectId }),
               recipient: selection.recipient,
               refundAddress: selection.refundAddress,
@@ -775,6 +885,7 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
               subsidize,
             }
             const capacity = await RoutesDepositAddresses.validateCreationCapacity(db, {
+              checkPolicy: (tx) => Access.assertPolicy(tx, policyContext),
               claim: {
                 apiKeyId: identity.apiKeyId,
                 createdAt: claim.createdAt,
@@ -819,7 +930,10 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
             }
             const provisioned = await RoutesProvider.createDepositAddress({
               amount: body.amount,
-              catalog,
+              catalog: {
+                ...catalog,
+                routes: catalog.routes.filter((entry) => entry.route === selection.candidate.route),
+              },
               destinationChainId: c.get('chainId'),
               destinationToken: body.destinationToken,
               onAttempt: (attempt) => attempts.push(attempt),
@@ -829,6 +943,7 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
               sourceChain: body.sourceChain,
               sourceToken: body.sourceToken,
               subsidize,
+              subsidyMaxAmount,
             })
             if (!provisioned) return undefined
             provisioning.succeeded = true
@@ -836,8 +951,10 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
               amount: body.amount,
               candidate: provisioned.candidate,
               provider: provisioned.provider,
+              ...(legacy ? {} : { policyVersions: policyContext.versions }),
               recipient: provisioned.recipient,
               refundAddress: provisioned.refundAddress,
+              routePolicy,
               result: provisioned.result,
             })
             return {
@@ -871,6 +988,22 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
               destinationTokenKey: selected.checkpoint.candidate.destinationToken.tokenKey,
               environment: owner.environment,
               orgId: owner.orgId,
+              ...(selected.checkpoint.policyVersions === undefined &&
+              selected.checkpoint.result.correlation.fixedRate === undefined &&
+              selected.checkpoint.routePolicy === undefined
+                ? {}
+                : {
+                    policyKey: RoutesPolicy.depositKey({
+                      fixedRate: selected.checkpoint.result.correlation.fixedRate,
+                      routePolicy: selected.checkpoint.routePolicy,
+                    }),
+                  }),
+              ...(selected.checkpoint.routePolicy === undefined &&
+              selected.checkpoint.policyVersions === undefined
+                ? {}
+                : {
+                    providerId: selected.checkpoint.provider.id,
+                  }),
               ...(owner.projectId === undefined ? {} : { projectId: owner.projectId }),
               recipient: selected.checkpoint.recipient,
               refundAddress: selected.checkpoint.refundAddress,
@@ -879,6 +1012,9 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
               subsidize,
             }
             const capacity = await RoutesDepositAddresses.validateCreationCapacity(db, {
+              ...(claim.type === 'resume'
+                ? {}
+                : { checkPolicy: (tx: Db.Db) => Access.assertPolicy(tx, policyContext) }),
               claim: {
                 apiKeyId: identity.apiKeyId,
                 createdAt: claim.createdAt,
@@ -920,6 +1056,15 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
             return c.json(response, 200)
           }
 
+          // A resumed provider checkpoint still needs a settler before creating a subsidized address.
+          if (
+            selected.type === 'resume' &&
+            subsidize &&
+            selected.checkpoint.provider.id !== 'relay' &&
+            !options.depositSubsidyAccount
+          )
+            return depositAddressNotAvailable(c)
+
           if (selected.type === 'provisioned') {
             const stored = await RoutesIdempotency.checkpoint(db, {
               apiKeyId: identity.apiKeyId,
@@ -940,6 +1085,8 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
             result,
           } = selected.checkpoint
           const created = await db.transaction(async (tx) => {
+            // Capacity acceptance serialized the grant before provisioning. Recovery
+            // honors those issued terms even after suspension or policy edits.
             const persist =
               selected.type === 'resume'
                 ? RoutesDepositAddress.recoverOrGet
@@ -952,9 +1099,32 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
               providerOutputToken: selectedCandidate.destinationToken,
               providerRequestIds: [result.correlation.requestId],
               providerState:
-                result.correlation.checkEndpoint === undefined
+                result.correlation.checkEndpoint === undefined &&
+                result.correlation.fixedRate === undefined &&
+                selected.checkpoint.routePolicy === undefined
                   ? undefined
-                  : { checkEndpoint: result.correlation.checkEndpoint },
+                  : {
+                      ...(result.correlation.checkEndpoint === undefined
+                        ? {}
+                        : { checkEndpoint: result.correlation.checkEndpoint }),
+                      ...(result.correlation.fixedRate === undefined
+                        ? {}
+                        : { fixedRate: result.correlation.fixedRate }),
+                      ...(selected.checkpoint.routePolicy === undefined
+                        ? {}
+                        : {
+                            routePolicy: selected.checkpoint.routePolicy,
+                          }),
+                      ...(result.correlation.fixedRate === undefined &&
+                      selected.checkpoint.routePolicy === undefined
+                        ? {}
+                        : {
+                            routePolicyKey: RoutesPolicy.depositKey({
+                              fixedRate: result.correlation.fixedRate,
+                              routePolicy: selected.checkpoint.routePolicy,
+                            }),
+                          }),
+                    },
               snapshot: {
                 address: result.address,
                 destinationChain: selectedCandidate.destinationChain,
@@ -1050,13 +1220,50 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
             )
           return c.json(created.response, 200)
         } catch (cause) {
-          if (!provisioning.succeeded) await release()
+          // A definitive rejection creates no provider liability, even after marking a subsidized attempt.
+          if (cause instanceof RoutesProvider.ProviderUnavailableError)
+            await RoutesIdempotency.release(db, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+            })
+          else if (!provisioning.succeeded) await release()
+          if (cause instanceof RoutesProvider.AmountTooLowError) {
+            c.set('routesProviderAttempts', attempts.map(RoutesProvider.formatAttempt))
+            return Response.error(c, {
+              code: 'amount_too_low',
+              message:
+                'This amount cannot cover the route fees. Increase the amount or enable subsidies if available.',
+              status: 400,
+            })
+          }
+          if (cause instanceof RoutesProvider.ProviderUnavailableError) {
+            c.set('routesProviderAttempts', attempts.map(RoutesProvider.formatAttempt))
+            return Response.error(c, {
+              code: 'quote_not_available',
+              message:
+                'A quote is currently unavailable for this request. Adjust the amount or subsidy settings, or try again later.',
+              status: 404,
+            })
+          }
           if (cause instanceof RoutesProvider.InvalidRefundAddressError)
             return Response.error(c, {
               code: 'body_invalid',
               message: 'Invalid `refundAddress`.',
               status: 400,
             })
+          if (cause instanceof Access.PolicyError) return Access.policyError(c, cause)
+          if (cause instanceof RoutesDepositAddresses.IdentityConflictError) {
+            c.get('metrics')?.count('routes_policy_denial_count', 1, {
+              reason: 'route_policy_identity_conflict',
+            })
+            return Response.error(c, {
+              code: 'route_policy_identity_conflict',
+              message:
+                'An address for this route already exists with different terms or provider. Existing deposits retain their original terms.',
+              status: 409,
+            })
+          }
           if (cause instanceof RoutesProvider.UnsupportedSourceChainError)
             return depositAddressNotAvailable(c)
           if (
@@ -1475,6 +1682,10 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
 export declare namespace depositAddresses {
   /** Deposit-address route dependencies. */
   type Options = {
+    /** Tempo account available to settle locally subsidized deposits. */
+    depositSubsidyAccount?: string | undefined
+    /** Platform ceiling used when pinning a subsidized address commitment. */
+    depositSubsidyMaxAmount?: string | undefined
     /** Enqueues one deposit address for asynchronous reconciliation. */
     dispatchDepositReconciliation?:
       | ((message: RoutesProvider.Webhook.receive.Dispatchable) => Promise<void>)
@@ -1487,7 +1698,7 @@ export declare namespace depositAddresses {
 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.',
+    message: 'A deposit address is unavailable for the requested route.',
     status: 404,
   })
 }