tapimo 0.15.1 → 0.18.0

package/src/internal/routes/Policy.ts

@@ -0,0 +1,399 @@
+import type * as Catalog from './Catalog.js'
+import * as z from 'zod/mini'
+
+export type Payer = 'tempo' | 'enterprise'
+export type Scope = {
+  orgId: string
+  environment: 'production' | 'sandbox'
+  projectId?: string | undefined
+  apiKeyId?: string | undefined
+}
+export type Rule = {
+  sourceChainId: string
+  sourceTokenId: string
+  destinationChainId: string
+  destinationTokenId: string
+  providerId?: string | undefined
+}
+export type Overrides = {
+  access?: Rule[] | null
+  subsidyRoutes?: Rule[] | null
+  subsidyEnabled?: boolean
+  subsidyPayer?: Payer
+  maxAmount?: string
+  terms?: Array<
+    Rule & {
+      subsidyEligible?: boolean
+      subsidyEnabled?: boolean
+      subsidyPayer?: Payer
+      maxAmount?: string
+    }
+  >
+  suspended?: boolean
+}
+export type Legacy = { subsidyEnabled: boolean; maxAmount: string; subsidyPayer: 'enterprise' }
+export type Effective = {
+  access: Rule[] | null
+  subsidyEligible: boolean
+  subsidyRoutes: Rule[] | null
+  subsidyEnabled: boolean
+  subsidyPayer: Payer
+  maxAmount: string
+  suspended: boolean
+}
+
+/** Immutable financial terms retained independently of mutable grants. */
+export type Commitment = {
+  maxAmount: string
+  scope: Scope
+  subsidyPayer: Payer
+  versions: number[]
+}
+
+const amount = z
+  .string()
+  .check(
+    z.regex(/^(?:0|[1-9]\d{0,11})(?:\.\d{1,6})?$/),
+    z.describe('Nonnegative USD decimal with at most 12 integer and 6 fractional digits.'),
+    z.meta({ examples: ['0.05'] }),
+  )
+
+/** Public route-policy input schemas. */
+export namespace schema {
+  /** Scope of an independently versioned route policy. */
+  export const Scope = z
+    .strictObject({
+      apiKeyId: z.optional(
+        z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('API key attribution.'),
+            z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      ),
+      environment: z
+        .enum(['production', 'sandbox'])
+        .check(z.describe('Deployment environment.'), z.meta({ examples: ['production'] })),
+      orgId: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe('Owning organization identifier.'),
+          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      projectId: z.optional(
+        z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Project attribution.'),
+            z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      ),
+    })
+    .check(
+      z.describe('Organization, optional project, and optional API key policy scope.'),
+      z.meta({ examples: [{ environment: 'production', orgId: 'org_1a2b3c4d5e6f7g8h9j0k1m2n' }] }),
+    )
+
+  /** Stable identifiers selecting one route, optionally for one provider. */
+  export const Rule = z
+    .strictObject({
+      destinationChainId: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe('Destination CAIP-2 chain identifier.'),
+          z.meta({ examples: ['eip155:4217'] }),
+        ),
+      destinationTokenId: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe('Destination token identifier.'),
+          z.meta({ examples: ['usdce'] }),
+        ),
+      providerId: z.optional(
+        z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Optional provider identifier.'),
+            z.meta({ examples: ['stargate'] }),
+          ),
+      ),
+      sourceChainId: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe('Source CAIP-2 chain identifier.'),
+          z.meta({ examples: ['eip155:8453'] }),
+        ),
+      sourceTokenId: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe('Source token identifier.'),
+          z.meta({ examples: ['usdc'] }),
+        ),
+    })
+    .check(z.describe('Route selector.'))
+
+  const Term = z.extend(Rule, {
+    maxAmount: z.optional(amount),
+    subsidyEligible: z
+      .optional(z.boolean())
+      .check(
+        z.describe('Whether this route is eligible for subsidies.'),
+        z.meta({ examples: [true] }),
+      ),
+    subsidyEnabled: z
+      .optional(z.boolean())
+      .check(
+        z.describe('Whether subsidies are enabled for this route.'),
+        z.meta({ examples: [true] }),
+      ),
+    subsidyPayer: z
+      .optional(z.enum(['tempo', 'enterprise']))
+      .check(z.describe('Party paying this route subsidy.'), z.meta({ examples: ['tempo'] })),
+  })
+  const unique = <T extends Rule>(values: readonly T[]) =>
+    new Set(values.map(specificityKey)).size === values.length
+
+  /** Independently inherited route-policy overrides. */
+  export const Overrides = z
+    .strictObject({
+      access: z
+        .optional(z.nullable(z.array(Rule).check(z.refine(unique))))
+        .check(
+          z.describe('Allowed routes; null allows all and an empty list denies all.'),
+          z.meta({ examples: [null, []] }),
+        ),
+      maxAmount: z.optional(amount),
+      subsidyEnabled: z
+        .optional(z.boolean())
+        .check(
+          z.describe('Whether subsidies are enabled for this scope.'),
+          z.meta({ examples: [true] }),
+        ),
+      subsidyPayer: z
+        .optional(z.enum(['tempo', 'enterprise']))
+        .check(
+          z.describe('Default party paying route subsidies.'),
+          z.meta({ examples: ['enterprise'] }),
+        ),
+      subsidyRoutes: z
+        .optional(z.nullable(z.array(Rule).check(z.refine(unique))))
+        .check(
+          z.describe('Subsidy-eligible routes; null allows all.'),
+          z.meta({ examples: [null, []] }),
+        ),
+      suspended: z
+        .optional(z.boolean())
+        .check(
+          z.describe('Whether new instructions are suspended in this environment.'),
+          z.meta({ examples: [false] }),
+        ),
+      terms: z.optional(z.array(Term).check(z.refine(unique))).check(
+        z.describe('Route-specific subsidy overrides.'),
+        z.meta({
+          examples: [
+            [
+              {
+                destinationChainId: 'eip155:4217',
+                destinationTokenId: 'usdce',
+                providerId: 'stargate',
+                sourceChainId: 'eip155:8453',
+                sourceTokenId: 'usdc',
+                maxAmount: '0.05',
+                subsidyEnabled: true,
+                subsidyPayer: 'tempo',
+              },
+            ],
+          ],
+        }),
+      ),
+    })
+    .check(
+      z.describe('Explicit policy values inherited by more specific scopes.'),
+      z.meta({
+        examples: [
+          { access: null, maxAmount: '0.05', subsidyEnabled: true, subsidyPayer: 'tempo' },
+        ],
+      }),
+    )
+
+  /** Financial commitment captured before a new resource is accepted. */
+  export const Commitment = z.object({
+    maxAmount: amount,
+    scope: Scope,
+    subsidyPayer: z.enum(['tempo', 'enterprise']),
+    versions: z.array(z.number().check(z.int(), z.nonnegative())),
+  })
+}
+
+/** Reads private, immutable route terms; malformed stored terms fail closed. */
+export function commitment(
+  state: Record<string, unknown> | null | undefined,
+): Commitment | undefined {
+  return state?.['routePolicy'] === undefined
+    ? undefined
+    : schema.Commitment.parse(state['routePolicy'])
+}
+
+/** Stable reuse identity excludes the authoring key and policy revision. */
+export function commitmentKey(value: Commitment | undefined): string {
+  if (!value) return ''
+  const [whole, fraction = ''] = value.maxAmount.split('.')
+  const amount = `${BigInt(whole!)}.${fraction.padEnd(6, '0')}`
+  return JSON.stringify([value.subsidyPayer, amount])
+}
+
+/** Keeps fixed-rate addresses separate from addresses that require local subsidy settlement. */
+export function depositKey(state: Record<string, unknown> | null | undefined): string {
+  const key = commitmentKey(commitment(state))
+  return state?.['fixedRate'] === '1:1' ? JSON.stringify([key, '1:1']) : key
+}
+
+/** Resolves independently inherited policy fields. Layers are org, project, then key. */
+export function resolve(input: {
+  layers: readonly Overrides[]
+  legacy: Legacy
+  /** Legacy access remains unrestricted until the organization saves its first policy. */
+  defaultAccess?: null
+  route?: Rule
+}): Effective {
+  const { layers, legacy, route } = input
+  const inherited = <K extends keyof Overrides>(key: K) => {
+    for (let index = layers.length - 1; index >= 0; index--) {
+      const value = layers[index]?.[key]
+      if (value !== undefined) return value
+    }
+    return undefined
+  }
+  const term = <K extends 'subsidyPayer' | 'maxAmount'>(key: K) => {
+    if (!route) return undefined
+    for (let index = layers.length - 1; index >= 0; index--) {
+      const terms = layers[index]?.terms
+      const exact = terms?.find(
+        (candidate) => candidate.providerId !== undefined && matches(candidate, route),
+      )
+      const any = terms?.find(
+        (candidate) => candidate.providerId === undefined && matches(candidate, route),
+      )
+      const value = exact?.[key] ?? any?.[key]
+      if (value !== undefined) return value
+      const fallback = layers[index]?.[key]
+      if (fallback !== undefined) return fallback
+    }
+    return undefined
+  }
+  const subsidyEligible = () => {
+    if (!route) return true
+    for (let index = layers.length - 1; index >= 0; index--) {
+      const terms = layers[index]?.terms
+      const exact = terms?.find(
+        (candidate) => candidate.providerId !== undefined && matches(candidate, route),
+      )
+      if (exact?.subsidyEnabled !== undefined) return exact.subsidyEnabled
+      if (exact?.subsidyEligible !== undefined) return exact.subsidyEligible
+      const any = terms?.find(
+        (candidate) => candidate.providerId === undefined && matches(candidate, route),
+      )
+      if (any?.subsidyEnabled !== undefined) return any.subsidyEnabled
+      if (any?.subsidyEligible !== undefined) return any.subsidyEligible
+      const routes = layers[index]?.subsidyRoutes
+      if (routes !== undefined) return allows(routes, route)
+    }
+    return true
+  }
+  const routeSubsidyEnabled = () => {
+    if (!route) return inherited('subsidyEnabled') ?? legacy.subsidyEnabled
+    for (let index = layers.length - 1; index >= 0; index--) {
+      const terms = layers[index]?.terms
+      const exact = terms?.find(
+        (candidate) => candidate.providerId !== undefined && matches(candidate, route),
+      )
+      if (exact?.subsidyEnabled !== undefined) return exact.subsidyEnabled
+      const any = terms?.find(
+        (candidate) => candidate.providerId === undefined && matches(candidate, route),
+      )
+      if (any?.subsidyEnabled !== undefined) return any.subsidyEnabled
+      const fallback = layers[index]?.subsidyEnabled
+      if (fallback !== undefined) return fallback
+    }
+    return legacy.subsidyEnabled
+  }
+  const access = inherited('access')
+  return {
+    access: access === undefined ? (input.defaultAccess === null ? null : []) : access,
+    subsidyEligible: subsidyEligible(),
+    subsidyRoutes: inherited('subsidyRoutes') ?? null,
+    subsidyEnabled: routeSubsidyEnabled(),
+    subsidyPayer: term('subsidyPayer') ?? inherited('subsidyPayer') ?? legacy.subsidyPayer,
+    maxAmount: term('maxAmount') ?? inherited('maxAmount') ?? legacy.maxAmount,
+    suspended: layers[0]?.suspended === true,
+  }
+}
+
+/** Whether a replace-list permits a catalog route; null permits every route. */
+export function allows(rules: readonly Rule[] | null, route: Rule): boolean {
+  return rules === null || rules.some((rule) => matches(rule, route))
+}
+
+/** Converts a hydrated catalog route to stable policy identifiers. */
+export function fromRoute(value: Catalog.ProviderRoute): Rule {
+  return {
+    sourceChainId: value.route.source.chain.id,
+    sourceTokenId: value.route.source.slug,
+    destinationChainId: value.route.destination.chain.id,
+    destinationTokenId: value.route.destination.slug,
+    providerId: value.providerId,
+  }
+}
+
+/** Filters catalog routes and rebuilds its provider index. */
+export function filter(
+  catalog: Catalog.Snapshot,
+  input: {
+    layers: readonly Overrides[]
+    legacy: Legacy
+    defaultAccess?: null
+    subsidize?: boolean
+  },
+) {
+  const routes = catalog.routes.filter((route) => {
+    const rule = fromRoute(route)
+    const effective = resolve({ ...input, route: rule })
+    if (effective.suspended || !allows(effective.access, rule)) return false
+    return !input.subsidize || (effective.subsidyEnabled && effective.subsidyEligible)
+  })
+  const routesByProvider = new Map<string, Catalog.ProviderRoute[]>()
+  for (const route of routes) {
+    const entries = routesByProvider.get(route.providerId) ?? []
+    entries.push(route)
+    routesByProvider.set(route.providerId, entries)
+  }
+  return { ...catalog, routes, routesByProvider }
+}
+
+function specificityKey(rule: Rule): string {
+  return [
+    rule.sourceChainId,
+    rule.sourceTokenId,
+    rule.destinationChainId,
+    rule.destinationTokenId,
+    rule.providerId ?? '*',
+  ].join('\0')
+}
+
+function matches(rule: Rule, route: Rule): boolean {
+  return (
+    rule.sourceChainId === route.sourceChainId &&
+    rule.sourceTokenId === route.sourceTokenId &&
+    rule.destinationChainId === route.destinationChainId &&
+    rule.destinationTokenId === route.destinationTokenId &&
+    (rule.providerId === undefined || rule.providerId === route.providerId)
+  )
+}

package/src/internal/routes/Provider.test.ts

@@ -1,7 +1,10 @@
+import * as z from 'zod/mini'
+
 import * as TestRoutes from '../../../test/Routes.js'
 import * as RoutesCatalog from './Catalog.js'
 import * as RoutesProvider from './Provider.js'
 import * as Across from './providers/across.js'
+import * as PropAmm from './providers/propAmm.js'
 import * as Relay from './providers/relay.js'
 import * as Rhino from './providers/rhino.js'
 import * as Squid from './providers/squid.js'
@@ -207,9 +210,81 @@ describe('formatAttempt', () => {
       ]
     `)
   })
+
+  test('classifies upstream HTTP 429 responses as rate-limit failures', () => {
+    expect(
+      RoutesProvider.formatAttempt({
+        cause: new RoutesProvider.ProviderResponseError(429, null, 1_000),
+        durationMs: 10,
+        operation: 'getQuote',
+        outcome: 'failed',
+        provider: { id: 'squid' },
+      }),
+    ).toEqual({
+      durationMs: 10,
+      failure: 'rate_limit',
+      id: 'squid',
+      operation: 'getQuote',
+      outcome: 'failed',
+      rateLimitSource: 'upstream',
+    })
+  })
 })
 
 describe('getQuotes', () => {
+  test('isolates unavailable observers and still reports the quote outcome', async () => {
+    const results: RoutesProvider.QuoteRequestResult[] = []
+    let calls = 0
+    const quotes = await RoutesProvider.getQuotes({
+      catalog: TestRoutes.snapshot,
+      destinationToken: 'usdy',
+      onResult: (result) => results.push(result),
+      onUnavailable: () => {
+        calls++
+        throw new Error('observer failed')
+      },
+      providers: [PropAmm.propAmm()],
+      sourceAmount: '1000000',
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: 'tempo',
+      sourceToken: 'usdce',
+    })
+    expect(quotes).toEqual([])
+    expect(calls).toBe(1)
+    expect(results).toMatchInlineSnapshot(`
+      [
+        {
+          "candidateCount": 1,
+          "outcome": "unavailable",
+          "quotes": [],
+        },
+      ]
+    `)
+  })
+
+  test.each([
+    { identity: {}, reason: 'identity_required' },
+    {
+      identity: { recipient: `0x${'11'.repeat(20)}`, sender: 'invalid' },
+      reason: 'invalid_identity',
+    },
+  ])('reports the real PropAMM rejection: $reason', async ({ identity, reason }) => {
+    const unavailable: z.output<typeof RoutesProvider.schema.UnavailableReason>[] = []
+    const quotes = await RoutesProvider.getQuotes({
+      ...identity,
+      catalog: TestRoutes.snapshot,
+      destinationToken: 'usdy',
+      onUnavailable: (result) => unavailable.push(result),
+      providers: [PropAmm.propAmm()],
+      sourceAmount: '1000000',
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: 'tempo',
+      sourceToken: 'usdce',
+    })
+    expect(quotes).toEqual([])
+    expect(unavailable).toEqual([reason])
+  })
+
   test('reports bounded request outcomes and quote ages', async () => {
     const results: RoutesProvider.QuoteRequestResult[] = []
     const onResult = (result: RoutesProvider.QuoteRequestResult) => results.push(result)
@@ -708,7 +783,7 @@ describe('createDepositAddress', () => {
     ])
   })
 
-  test('returns no selection when the provider reports no route', async () => {
+  test('preserves current quote unavailability', async () => {
     const attempts: RoutesProvider.ProviderAttempt[] = []
     await expect(
       RoutesProvider.createDepositAddress({
@@ -720,7 +795,7 @@ describe('createDepositAddress', () => {
           }),
         ],
       }),
-    ).resolves.toBeUndefined()
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.ProviderUnavailableError]`)
     expect(attempts.map(stableAttempt)).toEqual([
       { operation: 'createDepositAddress', outcome: 'unavailable', provider: 'relay' },
     ])
@@ -1725,6 +1800,32 @@ describe('getQuoteCandidates', () => {
   })
 })
 
+describe('unavailableResult', () => {
+  test.each(['sender_not_allowed', 'recipient_not_allowed'] as const)(
+    'preserves the public %s reason',
+    (reason) => {
+      const result = RoutesProvider.unavailableResult({
+        detail: 'propamm',
+        message: 'Private provider reason',
+        now: new Date('2026-01-01T00:00:00Z'),
+        reason,
+        source: 'onchain',
+      })
+      expect(result.reason).toBe(reason)
+    },
+  )
+
+  test('does not publish arbitrary upstream messages', () => {
+    const result = RoutesProvider.unavailableResult({
+      detail: 'provider',
+      message: 'Request failed at https://private.example/?key=secret',
+      now: new Date('2026-01-01T00:00:00Z'),
+      source: 'api',
+    })
+    expect(result.reason).toBeUndefined()
+  })
+})
+
 describe('getProviders', () => {
   test('lists supplied providers', () => {
     expect(RoutesProvider.getProviders({ catalog: TestRoutes.snapshot, providers }))