tapimo 0.13.0 → 0.15.0

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

@@ -0,0 +1,169 @@
+import { privateKeyToAccount } from 'viem/accounts'
+
+import * as Organizations from '../../db/tables/organizations.js'
+import * as RoutesSubsidies from '../../db/tables/routesSubsidies.js'
+import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as Viem from '../Viem.js'
+import * as Subsidy from './Subsidy.js'
+
+const privateKey = `0x${'11'.repeat(32)}` as const
+
+describe('check', () => {
+  test('resolves the effective policy and production billing state', async () => {
+    const db = TestApp.database()
+    try {
+      await Organizations.create(db, { id: 'org_subsidy_check', name: 'Subsidy check' })
+      const options = {
+        environment: 'production',
+        orgId: 'org_subsidy_check',
+      } as const
+      const missing = await Subsidy.check(db, options)
+      await RoutesSubsidies.upsertOrganization(db, {
+        frequency: 'tx',
+        maxAmount: '2.5',
+        orgId: options.orgId,
+      })
+      const productionWithoutBilling = await Subsidy.check(db, options)
+      const sandbox = await Subsidy.check(db, { ...options, environment: 'sandbox' })
+      await StripeCustomers.create(db, {
+        orgId: options.orgId,
+        stripeCustomerId: 'cus_subsidy_check',
+      })
+      await StripeCustomers.setStatus(db, options.orgId, 'past_due')
+      const pastDue = await Subsidy.check(db, options)
+      await StripeCustomers.setStatus(db, options.orgId, 'active')
+      const active = await Subsidy.check(db, options)
+
+      expect({ active, missing, pastDue, productionWithoutBilling, sandbox })
+        .toMatchInlineSnapshot(`
+        {
+          "active": {
+            "frequency": "tx",
+            "maxAmount": "2.5",
+            "type": "allowed",
+          },
+          "missing": {
+            "reason": "routes_subsidy_not_enabled",
+            "type": "denied",
+          },
+          "pastDue": {
+            "reason": "billing_past_due",
+            "type": "denied",
+          },
+          "productionWithoutBilling": {
+            "reason": "billing_required",
+            "type": "denied",
+          },
+          "sandbox": {
+            "frequency": "tx",
+            "maxAmount": "2.5",
+            "type": "allowed",
+          },
+        }
+      `)
+    } finally {
+      await db.close()
+    }
+  })
+})
+
+describe('supports', () => {
+  test('accepts only corresponding USD routes within the deposit limit', () => {
+    const route = TestRoutes.transferSnapshot()
+    expect({
+      aboveLimit: Subsidy.supports(
+        { maxAmount: '1' },
+        {
+          amount: '1000001',
+          destinationToken: route.destinationToken,
+          sourceToken: route.sourceToken,
+        },
+      ),
+      invalidLimit: Subsidy.supports(
+        { maxAmount: 'invalid' },
+        {
+          amount: '1000000',
+          destinationToken: route.destinationToken,
+          sourceToken: route.sourceToken,
+        },
+      ),
+      withinLimit: Subsidy.supports(
+        { maxAmount: '1' },
+        {
+          amount: '1000000',
+          destinationToken: route.destinationToken,
+          sourceToken: route.sourceToken,
+        },
+      ),
+      wrongCurrency: Subsidy.supports(
+        { maxAmount: '1' },
+        {
+          amount: '1000000',
+          destinationToken: { ...route.destinationToken, currency: 'EUR' },
+          sourceToken: route.sourceToken,
+        },
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "aboveLimit": false,
+        "invalidLimit": false,
+        "withinLimit": true,
+        "wrongCurrency": false,
+      }
+    `)
+  })
+})
+
+describe('supportsGap', () => {
+  test('compares the destination-token deficit with the decimal USD limit', () => {
+    const route = TestRoutes.transferSnapshot()
+    expect({
+      aboveLimit: Subsidy.supportsGap(
+        { maxAmount: '0.05' },
+        { amount: 50_001n, destinationToken: route.destinationToken },
+      ),
+      atLimit: Subsidy.supportsGap(
+        { maxAmount: '0.05' },
+        { amount: 50_000n, destinationToken: route.destinationToken },
+      ),
+      invalidLimit: Subsidy.supportsGap(
+        { maxAmount: 'invalid' },
+        { amount: 1n, destinationToken: route.destinationToken },
+      ),
+      wrongCurrency: Subsidy.supportsGap(
+        { maxAmount: '0.05' },
+        { amount: 50_000n, destinationToken: { ...route.destinationToken, currency: 'EUR' } },
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "aboveLimit": false,
+        "atLimit": true,
+        "invalidLimit": false,
+        "wrongCurrency": false,
+      }
+    `)
+  })
+})
+
+describe('create', () => {
+  test('exposes the dedicated account and policy without network access', () => {
+    const account = privateKeyToAccount(privateKey)
+    const policy = { maxAmount: '10' }
+    const settler = Subsidy.create({
+      account,
+      getClient: Viem.createGetClient(),
+      policy,
+    })
+
+    expect({ account: settler.account, policy: settler.policy }).toMatchInlineSnapshot(`
+      {
+        "account": "0x19E7E376E7C213B7E7e7e46cc70A5dD086DAff2A",
+        "policy": {
+          "maxAmount": "10",
+        },
+      }
+    `)
+  })
+})

package/src/internal/{funding → routes}/Subsidy.ts

@@ -14,6 +14,9 @@ import {
 } from 'viem/actions'
 import { Actions, Addresses } from 'viem/tempo'
 
+import type * as Db from '../../db/Db.js'
+import * as RoutesSubsidies from '../../db/tables/routesSubsidies.js'
+import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
 import * as Fees from '../Fees.js'
 import type * as Viem from '../Viem.js'
 import type * as Provider from './Provider.js'
@@ -21,12 +24,66 @@ import type * as Provider from './Provider.js'
 const slippageBps = 100n
 const slippageDenominator = 10_000n
 
-/** Maximum subsidized deposit value expressed as a decimal USD amount. */
+/** Decimal USD limit used by a Routes subsidy check. */
 export type Policy = {
-  /** Maximum source deposit value that Tempo will subsidize. */
+  /** Maximum amount that Tempo will subsidize. */
   maxAmount: string
 }
 
+/** Public messages for Routes subsidy policy denials. */
+export const denialMessages = {
+  billing_past_due: 'Billing past due.',
+  billing_required: 'Billing required.',
+  routes_subsidy_not_enabled: 'Routes subsidies are not enabled for this organization.',
+} as const
+
+/** Reason that a Routes subsidy policy denied a request or settlement. */
+export type DenialReason = keyof typeof denialMessages
+
+/** Resolves the organization policy and required production billing state. */
+export async function check(db: Db.Db, options: check.Options): Promise<check.Result> {
+  const policy = await RoutesSubsidies.getOrganization(db, options.orgId)
+  if (!policy?.enabled || policy.maxAmount === null)
+    return { reason: 'routes_subsidy_not_enabled', type: 'denied' }
+  if (options.environment === 'production') {
+    const billing = await StripeCustomers.get(db, options.orgId)
+    if (billing?.status === 'past_due') return { reason: 'billing_past_due', type: 'denied' }
+    if (billing?.status !== 'active') return { reason: 'billing_required', type: 'denied' }
+  }
+  return {
+    frequency: policy.frequency,
+    maxAmount: policy.maxAmount,
+    type: 'allowed',
+  }
+}
+
+export declare namespace check {
+  /** Organization and environment used to check one subsidy policy. */
+  type Options = {
+    /** API-key environment attributed to the subsidy. */
+    environment: 'production' | 'sandbox'
+    /** Organization id (`org_…`) attributed to the subsidy. */
+    orgId: string
+  }
+
+  /** Effective policy or the reason that the subsidy is denied. */
+  type Result =
+    | {
+        /** Interval over which the subsidy limit applies. */
+        frequency: 'tx'
+        /** Maximum subsidy gap in decimal USD. */
+        maxAmount: string
+        /** The effective policy allows the subsidy. */
+        type: 'allowed'
+      }
+    | {
+        /** Policy or billing reason that denied the subsidy. */
+        reason: DenialReason
+        /** The effective policy denies the subsidy. */
+        type: 'denied'
+      }
+}
+
 /** Returns whether one USD stablecoin deposit is within the subsidy policy. */
 export function supports(policy: Policy, options: supports.Options): boolean {
   if (
@@ -56,13 +113,36 @@ export declare namespace supports {
   }
 }
 
+/** Returns whether one destination-token deficit is within the scoped subsidy limit. */
+export function supportsGap(policy: Policy, options: supportsGap.Options): boolean {
+  if (options.destinationToken.currency !== 'USD') return false
+  const maximum = (() => {
+    try {
+      return Value.from(policy.maxAmount, options.destinationToken.decimals)
+    } catch {
+      return 0n
+    }
+  })()
+  return maximum > 0n && options.amount <= maximum
+}
+
+export declare namespace supportsGap {
+  /** Destination-token deficit evaluated against a scoped subsidy policy. */
+  type Options = {
+    /** Destination-token deficit in base units. */
+    amount: bigint
+    /** Token that Tempo supplies to cover the deficit. */
+    destinationToken: Provider.TokenRef
+  }
+}
+
 /** Prepares and submits durable pathUSD-funded subsidy transactions. */
 export type Settler = {
   /** Tempo account that supplies pathUSD. */
   account: Address
   /** Broadcasts one previously persisted signed transaction. */
   broadcast(parameters: Settler.broadcast.Parameters): Promise<void>
-  /** Maximum subsidized deposit policy enforced at creation and settlement. */
+  /** Maximum source deposit value that Tempo will subsidize. */
   policy: Policy
   /** Prepares one signed transaction without broadcasting it. */
   prepare(parameters: Settler.prepare.Parameters): Promise<Settler.prepare.ReturnType>
@@ -246,15 +326,15 @@ function hasRevert(cause: unknown, names: readonly string[]): boolean {
 
 /** The subsidy account lacks enough pathUSD. */
 export class BalanceUnavailableError extends Error {
-  override name = 'Funding.Subsidy.BalanceUnavailableError'
+  override name = 'Routes.Subsidy.BalanceUnavailableError'
 }
 
 /** The Tempo DEX cannot quote the required destination amount. */
 export class LiquidityUnavailableError extends Error {
-  override name = 'Funding.Subsidy.LiquidityUnavailableError'
+  override name = 'Routes.Subsidy.LiquidityUnavailableError'
 }
 
 /** The RPC returned a hash that differs from the persisted transaction. */
 export class TransactionHashMismatchError extends Error {
-  override name = 'Funding.Subsidy.TransactionHashMismatchError'
+  override name = 'Routes.Subsidy.TransactionHashMismatchError'
 }

package/src/internal/{funding → routes}/Token.test.ts

@@ -41,7 +41,7 @@ describe('resolve', () => {
     })
 
     expect(() => base({ tokens: [token] })).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Token.MissingChainError]`,
+      `[Routes.Token.MissingChainError]`,
     )
   })
 })

package/src/internal/{funding → routes}/Token.ts

@@ -1,6 +1,6 @@
 import type * as Chain from './Chain.js'
 
-/** A token accepted or returned by a funding provider. */
+/** A token accepted or returned by a route provider. */
 export type Token = {
   /** Chain-specific token metadata keyed by CAIP-2 chain id. */
   chains: Partial<Record<Chain.Id, ChainConfig>>
@@ -26,7 +26,7 @@ export type ChainConfig = {
   standard: string
 }
 
-/** A token resolved to one funding chain. */
+/** A token resolved to one route chain. */
 export type Resolved = Omit<Token, 'chains'> &
   Omit<ChainConfig, 'name'> & {
     /** Chain where the token exists. */
@@ -35,12 +35,12 @@ export type Resolved = Omit<Token, 'chains'> &
     name: string
   }
 
-/** Creates a canonical funding token. */
+/** Creates a canonical route token. */
 export function from<const token extends Token>(options: token): token {
   return options
 }
 
-/** Resolves a funding token to its metadata on one chain. */
+/** Resolves a route token to its metadata on one chain. */
 export function resolve(token: Token, chain: Chain.Chain): Resolved {
   const config = token.chains[chain.id]
   if (!config) throw new MissingChainError()
@@ -55,5 +55,5 @@ export function resolve(token: Token, chain: Chain.Chain): Resolved {
 
 /** Error thrown when a token is not configured for a selected chain. */
 export class MissingChainError extends Error {
-  override name = 'Funding.Token.MissingChainError'
+  override name = 'Routes.Token.MissingChainError'
 }