tapimo 0.7.1 → 0.7.2

package/src/internal/funding/Catalog.ts

@@ -0,0 +1,347 @@
+import type { Context } from 'hono'
+import * as z from 'zod/mini'
+
+import type * as App from '../../App.js'
+import * as Db from '../../db/Db.js'
+import * as db_Schema from '../../db/Schema.js'
+import * as core_Catalog from '../../db/tables/fundingCatalog.js'
+import * as Timing from '../Timing.js'
+import * as Chain from './Chain.js'
+import * as Route from './Route.js'
+import * as Token from './Token.js'
+import * as Transfer from './Transfer.js'
+
+const defaultRefreshMs = 10_000
+const emptyUpdatedAt = '1970-01-01T00:00:00.000Z'
+const emptyVersion = 'empty'
+
+/** Funding catalog schemas. */
+export namespace schema {
+  const ChainId = z
+    .string()
+    .check(
+      z.regex(/^(?:eip155:\d+|solana:[^:]+|tron:[^:]+)$/),
+      z.describe('CAIP-2 funding chain identifier.'),
+    )
+
+  const Chain = z.extend(db_Schema.FundingChain, {
+    id: ChainId,
+    parentChainId: z.nullable(ChainId),
+  })
+
+  const TransferCapability = z
+    .object({
+      modes: z
+        .readonly(z.array(z.enum(Transfer.modes)))
+        .check(z.minLength(1), z.describe('Amount modes enabled for funding transfers.')),
+    })
+    .check(z.describe('Funding transfer capability enabled on one provider route.'))
+
+  /** Funding capabilities enabled on one provider route. */
+  export const Capabilities = z
+    .object({
+      depositAddress: z
+        .optional(z.literal(true))
+        .check(z.describe('Deposit-address funding support enabled on the route.')),
+      transfer: z
+        .optional(TransferCapability)
+        .check(z.describe('Funding transfer support enabled on the route.')),
+    })
+    .check(
+      z.refine(
+        (capabilities) =>
+          capabilities.depositAddress !== undefined || capabilities.transfer !== undefined,
+      ),
+      z.describe('Funding capabilities enabled on one provider route.'),
+    )
+
+  // Absent or null `capabilities` keeps a route quote-only, so transfer and
+  // deposit-address support enable through reviewed seed edits.
+  const Route = z.extend(db_Schema.FundingRoute, {
+    capabilities: z.optional(z.nullable(Capabilities)),
+  })
+
+  /** Complete funding catalog content accepted by the publish boundary. */
+  export const Data = z
+    .object({
+      chainTokens: z
+        .readonly(z.array(db_Schema.FundingChainToken))
+        .check(z.describe('Chain-scoped funding tokens.')),
+      chains: z.readonly(z.array(Chain)).check(z.describe('Funding chains.')),
+      routes: z.readonly(z.array(Route)).check(z.describe('Funding provider routes.')),
+      tokens: z.readonly(z.array(db_Schema.FundingToken)).check(z.describe('Funding tokens.')),
+    })
+    .check(z.describe('Complete funding catalog content.'))
+}
+
+/** Funding capabilities enabled on one provider route. */
+export type Capabilities = z.output<typeof schema.Capabilities>
+
+/** One hydrated provider route in a funding catalog snapshot. */
+export type ProviderRoute = {
+  /** Funding capabilities; absent means the route is quote-only. */
+  capabilities?: Capabilities | undefined
+  /** Funding provider that supports the route. */
+  providerId: string
+  /** Hydrated source-to-destination funding route. */
+  route: Route.Route
+}
+
+/** Compiled and indexed funding catalog. */
+export type Snapshot = {
+  /** Funding chains indexed by CAIP-2 id, slug, and alias. */
+  chainsByKey: ReadonlyMap<string, Chain.Chain>
+  /** Hydrated provider routes in stable catalog order. */
+  routes: readonly ProviderRoute[]
+  /** Hydrated routes grouped by provider id. */
+  routesByProvider: ReadonlyMap<string, readonly Route.Route[]>
+  /** Canonical funding tokens indexed by stable id. */
+  tokensById: ReadonlyMap<string, Token.Token>
+  /** ISO timestamp of the catalog's last publish. */
+  updatedAt: string
+  /** Opaque catalog version. */
+  version: string
+}
+
+/** Compiles stored funding catalog rows into a validated snapshot. */
+export function compile(rows: core_Catalog.Rows): Snapshot {
+  const data = normalize({
+    chainTokens: rows.chainTokens,
+    chains: rows.chains,
+    routes: rows.routes,
+    tokens: rows.tokens,
+  })
+  if (!rows.catalog && hasContent(data))
+    throw new InvalidCatalogError('Catalog content exists without a version head.')
+
+  const chainIds = new Set(data.chains.map((chain) => chain.id))
+  const chainsById = new Map<string, Chain.Chain>()
+  const chainsByKey = new Map<string, Chain.Chain>()
+  for (const row of data.chains) {
+    if (row.parentChainId && !chainIds.has(row.parentChainId))
+      throw new InvalidCatalogError(`Unknown parent chain "${row.parentChainId}".`)
+    const chain = Chain.from({
+      aliases: row.aliases,
+      id: row.id as Chain.Id,
+      name: row.name,
+      ...(row.parentChainId ? { parentChainId: row.parentChainId as Chain.Id } : {}),
+      rpcUrls: row.rpcUrls,
+      slug: row.slug,
+    })
+    if (chainsById.has(chain.id)) throw new InvalidCatalogError(`Duplicate chain "${chain.id}".`)
+    chainsById.set(chain.id, chain)
+    for (const key of [chain.id, chain.slug, ...chain.aliases]) {
+      const normalized = normalizeKey(key)
+      if (chainsByKey.has(normalized))
+        throw new InvalidCatalogError(`Duplicate chain key "${key}".`)
+      chainsByKey.set(normalized, chain)
+    }
+  }
+
+  const configs = new Map<string, Partial<Record<Chain.Id, Token.ChainConfig>>>()
+  const placements = new Set<string>()
+  const tokenIds = new Set(data.tokens.map((token) => token.id))
+  for (const row of data.chainTokens) {
+    const chain = chainsById.get(row.chainId)
+    if (!chain) throw new InvalidCatalogError(`Unknown chain "${row.chainId}" for token placement.`)
+    if (!tokenIds.has(row.tokenId))
+      throw new InvalidCatalogError(`Unknown token "${row.tokenId}" for token placement.`)
+    const placement = placementKey(row.chainId, row.tokenId)
+    if (placements.has(placement))
+      throw new InvalidCatalogError(`Duplicate token placement "${placement}".`)
+    placements.add(placement)
+    const chains = configs.get(row.tokenId) ?? {}
+    chains[chain.id] = {
+      address: row.address,
+      decimals: row.decimals,
+      ...(row.name ? { name: row.name } : {}),
+      standard: row.standard,
+    }
+    configs.set(row.tokenId, chains)
+  }
+
+  const tokensById = new Map<string, Token.Token>()
+  for (const row of data.tokens) {
+    if (tokensById.has(row.id)) throw new InvalidCatalogError(`Duplicate token "${row.id}".`)
+    tokensById.set(
+      row.id,
+      Token.from({
+        chains: configs.get(row.id) ?? {},
+        currency: row.currency,
+        name: row.name,
+        slug: row.id,
+        symbol: row.symbol,
+      }),
+    )
+  }
+
+  const routes: ProviderRoute[] = []
+  const routesByProvider = new Map<string, Route.Route[]>()
+  for (const row of data.routes) {
+    const route = {
+      destination: resolvePlacement(
+        chainsById,
+        tokensById,
+        row.destinationChainId,
+        row.destinationTokenId,
+      ),
+      source: resolvePlacement(chainsById, tokensById, row.sourceChainId, row.sourceTokenId),
+    }
+    routes.push({
+      ...(row.capabilities ? { capabilities: row.capabilities } : {}),
+      providerId: row.providerId,
+      route,
+    })
+    const providerRoutes = routesByProvider.get(row.providerId)
+    if (providerRoutes) providerRoutes.push(route)
+    else routesByProvider.set(row.providerId, [route])
+  }
+
+  return {
+    chainsByKey,
+    routes,
+    routesByProvider,
+    tokensById,
+    updatedAt: rows.catalog?.updatedAt ?? emptyUpdatedAt,
+    version: rows.catalog?.version ?? emptyVersion,
+  }
+}
+
+/** Reads and compiles the current funding catalog from Postgres. */
+export async function read(db: Db.Db): Promise<Snapshot> {
+  return compile(await core_Catalog.read(db))
+}
+
+/** Publishes a complete funding catalog and primes the current isolate. */
+export async function publish(db: Db.Db, input: publish.Input): Promise<Snapshot> {
+  const data = normalize(input)
+  compile({
+    catalog: { id: 'default', updatedAt: emptyUpdatedAt, version: 'validation' },
+    ...data,
+  })
+  // Absent `capabilities` persists as null; both mean indicative-only.
+  await core_Catalog.publish(db, {
+    ...data,
+    routes: data.routes.map((route) => ({ ...route, capabilities: route.capabilities ?? null })),
+  })
+  return prime(db, await read(db))
+}
+
+export declare namespace publish {
+  /** Complete funding catalog content. */
+  type Input = z.input<typeof schema.Data>
+}
+
+/** Replaces the current isolate's compiled catalog snapshot. */
+export function prime(source: Db.Source, snapshot: Snapshot): Snapshot {
+  cells.set(source, { checkedAt: Date.now(), snapshot })
+  return snapshot
+}
+
+/** Returns the current funding catalog snapshot with soft background refresh. */
+export function snapshot(c: Context<App.Environment>): Promise<Snapshot> {
+  return Timing.time(c, 'funding_catalog', async () => {
+    const source = c.get('dbCached')
+    const cell = cells.get(source)
+    if (cell && Date.now() - cell.checkedAt < defaultRefreshMs) return cell.snapshot
+    if (cell) {
+      const pending = refresh(c, source, cell)
+      try {
+        c.executionCtx.waitUntil(pending)
+      } catch {
+        void pending
+      }
+      return cell.snapshot
+    }
+    return refresh(c, source, undefined)
+  })
+}
+
+type Cell = {
+  checkedAt: number
+  snapshot: Snapshot
+}
+
+const cells = new WeakMap<Db.Source, Cell>()
+const refreshing = new WeakMap<Db.Source, Promise<Snapshot>>()
+
+function refresh(c: Context<App.Environment>, source: Db.Source, current: Cell | undefined) {
+  const existing = refreshing.get(source)
+  if (existing) return existing
+  const pending = (async () => {
+    try {
+      const db = Db.get(source)
+      if (current) {
+        const head = await Timing.time(c, 'funding_catalog_head', () => core_Catalog.head(db))
+        if (!head || head.version === current.snapshot.version) {
+          cells.set(source, { checkedAt: Date.now(), snapshot: current.snapshot })
+          return current.snapshot
+        }
+      }
+      const next = await read(db)
+      cells.set(source, { checkedAt: Date.now(), snapshot: next })
+      return next
+    } catch (error) {
+      if (!current) throw error
+      console.error('[funding-catalog] refresh failed; serving last good snapshot', error)
+      cells.set(source, { checkedAt: Date.now(), snapshot: current.snapshot })
+      return current.snapshot
+    } finally {
+      refreshing.delete(source)
+    }
+  })()
+  refreshing.set(source, pending)
+  return pending
+}
+
+function hasContent(data: z.output<typeof schema.Data>) {
+  return (
+    data.chains.length > 0 ||
+    data.tokens.length > 0 ||
+    data.chainTokens.length > 0 ||
+    data.routes.length > 0
+  )
+}
+
+function normalize(input: z.input<typeof schema.Data>): z.output<typeof schema.Data> {
+  const data = schema.Data.parse(input)
+  return {
+    ...data,
+    chainTokens: data.chainTokens.map((token) => ({
+      ...token,
+      address: token.chainId.startsWith('eip155:') ? token.address.toLowerCase() : token.address,
+    })),
+  }
+}
+
+function normalizeKey(key: string) {
+  return key.trim().toLowerCase()
+}
+
+function placementKey(chainId: string, tokenId: string) {
+  return `${chainId}:${tokenId}`
+}
+
+function resolvePlacement(
+  chains: ReadonlyMap<string, Chain.Chain>,
+  tokens: ReadonlyMap<string, Token.Token>,
+  chainId: string,
+  tokenId: string,
+) {
+  const chain = chains.get(chainId)
+  if (!chain) throw new InvalidCatalogError(`Unknown route chain "${chainId}".`)
+  const token = tokens.get(tokenId)
+  if (!token) throw new InvalidCatalogError(`Unknown route token "${tokenId}".`)
+  try {
+    return Token.resolve(token, chain)
+  } catch {
+    throw new InvalidCatalogError(
+      `Unknown route token placement "${placementKey(chainId, tokenId)}".`,
+    )
+  }
+}
+
+/** Error thrown when funding catalog references cannot be compiled. */
+export class InvalidCatalogError extends Error {
+  override name = 'Funding.Catalog.InvalidCatalogError'
+}

package/src/internal/funding/Chain.test.ts

@@ -0,0 +1,79 @@
+import * as Chain from './Chain.js'
+
+describe('from', () => {
+  test('derives EVM chain metadata from an EIP-155 id', () => {
+    const chain = Chain.from({
+      aliases: ['eth'],
+      id: 'eip155:1',
+      name: 'Ethereum',
+      slug: 'ethereum',
+    })
+    expect(metadata(chain)).toMatchInlineSnapshot(`
+      {
+        "addressFormat": "hex",
+        "aliases": [
+          "eth",
+        ],
+        "id": "eip155:1",
+        "kind": "evm",
+        "name": "Ethereum",
+        "slug": "ethereum",
+      }
+    `)
+  })
+
+  test('derives non-EVM chain metadata from the CAIP-2 namespace', () => {
+    expect(
+      [
+        Chain.from({
+          id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+          name: 'Solana',
+          slug: 'solana',
+        }),
+        Chain.from({
+          id: 'tron:0x2b6653dc',
+          name: 'Tron',
+          slug: 'tron',
+        }),
+      ].map(metadata),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "addressFormat": "base58",
+          "aliases": [],
+          "id": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+          "kind": "solana",
+          "name": "Solana",
+          "slug": "solana",
+        },
+        {
+          "addressFormat": "base58check",
+          "aliases": [],
+          "id": "tron:0x2b6653dc",
+          "kind": "tron",
+          "name": "Tron",
+          "slug": "tron",
+        },
+      ]
+    `)
+  })
+})
+
+describe('eip155Id', () => {
+  test('returns the numeric EIP-155 chain id', () => {
+    const chain = Chain.from({ id: 'eip155:8453', name: 'Base', slug: 'base' })
+    expect(Chain.eip155Id(chain)).toBe('8453')
+  })
+
+  test('rejects non-EIP-155 chains', () => {
+    const chain = Chain.from({ id: 'solana:mainnet', name: 'Solana', slug: 'solana' })
+    expect(() => Chain.eip155Id(chain)).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Chain.InvalidIdError]`,
+    )
+  })
+})
+
+function metadata(chain: Chain.Chain) {
+  const { addressFormat, aliases, id, kind, name, slug } = chain
+  return { addressFormat, aliases, id, kind, name, slug }
+}

package/src/internal/funding/Chain.ts

@@ -0,0 +1,120 @@
+import * as Token from './Token.js'
+
+/** Canonical identifier for a funding chain. */
+export type Id = `eip155:${number}` | `solana:${string}` | `tron:${string}`
+
+/** Chain metadata for a funding token. */
+export type Chain = Callable &
+  (
+    | (Base & {
+        /** Address encoding used by accounts and tokens on the chain. */
+        addressFormat: 'hex'
+        /** Chain execution family. */
+        kind: 'evm'
+      })
+    | (Base & {
+        /** Address encoding used by accounts and tokens on the chain. */
+        addressFormat: 'base58'
+        /** Chain execution family. */
+        kind: 'solana'
+      })
+    | (Base & {
+        /** Address encoding used by accounts and tokens on the chain. */
+        addressFormat: 'base58check'
+        /** Chain execution family. */
+        kind: 'tron'
+      })
+  )
+
+type Callable = (options: Callable.Options) => Selection
+
+declare namespace Callable {
+  /** Tokens selected for a funding route on this chain. */
+  type Options = {
+    /** Token definitions to resolve on the chain. */
+    tokens: readonly Token.Token[]
+  }
+}
+
+/** Tokens resolved for one funding chain. */
+export type Selection = {
+  /** Chain shared by every selected token. */
+  chain: Chain
+  /** Chain-scoped funding tokens. */
+  tokens: readonly Token.Resolved[]
+}
+
+type Base = {
+  /** Caller-facing aliases accepted for this chain. */
+  aliases: readonly string[]
+  /** CAIP-2 chain identifier. */
+  id: Id
+  /** Human-readable chain name. */
+  name: string
+  /** Parent chain identifier when this chain is a Zone. */
+  parentChainId?: Id | undefined
+  /** Public RPC endpoints used for funding-chain evidence. */
+  rpcUrls: readonly string[]
+  /** Stable chain segment used in quote identifiers. */
+  slug: string
+}
+
+/** Creates funding chain metadata from a CAIP-2 identifier. */
+export function from(options: from.Options): Chain {
+  const { aliases = [], id, name, parentChainId, rpcUrls = [], slug } = options
+  const base = { aliases, id, name, ...(parentChainId ? { parentChainId } : {}), rpcUrls, slug }
+  const metadata = (() => {
+    if (id.startsWith('eip155:')) return { ...base, addressFormat: 'hex', kind: 'evm' } as const
+    if (id.startsWith('solana:'))
+      return { ...base, addressFormat: 'base58', kind: 'solana' } as const
+    if (id.startsWith('tron:'))
+      return { ...base, addressFormat: 'base58check', kind: 'tron' } as const
+    throw new InvalidIdError()
+  })()
+  function select(parameters: Callable.Options): Selection {
+    const chain = select as Chain
+    return {
+      chain,
+      tokens: parameters.tokens.map((token) => Token.resolve(token, chain)),
+    }
+  }
+  return Object.defineProperties(
+    select,
+    Object.fromEntries(
+      Object.entries(metadata).map(([key, value]) => [
+        key,
+        { configurable: true, enumerable: true, value },
+      ]),
+    ),
+  ) as Chain
+}
+
+export declare namespace from {
+  /** Funding chain definition. */
+  type Options = {
+    /** Additional caller-facing aliases accepted for this chain. */
+    aliases?: readonly string[] | undefined
+    /** CAIP-2 chain identifier. */
+    id: Id
+    /** Human-readable chain name. */
+    name: string
+    /** Parent chain identifier when this chain is a Zone. */
+    parentChainId?: Id | undefined
+    /** Public RPC endpoints used for funding-chain evidence. */
+    rpcUrls?: readonly string[] | undefined
+    /** Stable chain segment used in quote identifiers. */
+    slug: string
+  }
+}
+
+/** Returns the numeric portion of an EIP-155 CAIP-2 chain identifier. */
+export function eip155Id(chain: Chain): string {
+  const match = /^eip155:(\d+)$/.exec(chain.id)
+  if (!match?.[1]) throw new InvalidIdError()
+  return match[1]
+}
+
+/** Error thrown when a funding chain identifier is invalid for an operation. */
+export class InvalidIdError extends Error {
+  override name = 'Funding.Chain.InvalidIdError'
+}

package/src/internal/funding/Deposit.test.ts

@@ -0,0 +1,26 @@
+import * as Deposit from './Deposit.js'
+
+describe('generateId', () => {
+  test('embeds the timestamp so lexical order is chronological', () => {
+    const earlier = Deposit.generateId(new Date('2026-01-01T00:00:00.000Z'))
+    const later = Deposit.generateId(new Date('2026-01-01T00:00:01.000Z'))
+    expect(earlier).toMatch(/^fdp_\d{15}_[0-9A-Za-z]{24}$/)
+    expect(earlier < later).toBe(true)
+  })
+})
+
+describe('isTerminal', () => {
+  test('recognizes only completed and refunded deposits', () => {
+    expect(Deposit.statuses.filter(Deposit.isTerminal)).toEqual(['completed', 'refunded'])
+  })
+})
+
+describe('canTransition', () => {
+  test('allows evidence-driven progress and prevents terminal exits', () => {
+    expect(Deposit.canTransition('detected', 'bridging')).toBe(true)
+    expect(Deposit.canTransition('bridging', 'settling')).toBe(true)
+    expect(Deposit.canTransition('settling', 'completed')).toBe(true)
+    expect(Deposit.canTransition('completed', 'refunding')).toBe(false)
+    expect(Deposit.canTransition('refunded', 'bridging')).toBe(false)
+  })
+})