Populate chain plugin id, token id, and EVM chain id for nexchange txs

Fetch the n.exchange currency catalog and map each order's deposit and
payout assets to Edge's chain plugin id, token id, and EVM chain id so
reported transactions comply with the asset-identification requirements.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: paullinator

src/partners/nexchange.ts

@@ -3,6 +3,7 @@ import {
   asBoolean,
   asEither,
   asNull,
+  asNumber,
   asObject,
   asOptional,
   asString,
@@ -19,6 +20,8 @@ import {
   Status
 } from '../types'
 import { datelog, retryFetch, safeParseFloat, snooze } from '../util'
+import { createTokenId, tokenTypes } from '../util/asEdgeTokenId'
+import { EVM_CHAIN_IDS } from '../util/chainIds'
 
 const asNexchangePluginParams = asObject({
   settings: asObject({
@@ -27,6 +30,10 @@ const asNexchangePluginParams = asObject({
   apiKeys: asObject({
     apiKey: asOptional(asString),
     baseUrl: asOptional(asString, 'https://api.n.exchange/en/api/v1'),
+    currencyUrl: asOptional(
+      asString,
+      'https://api.n.exchange/en/api/v2/currency/'
+    ),
     authMode: asOptional(asValue('x-api-key', 'authorization', 'both'), 'both')
   })
 })
@@ -53,6 +60,22 @@ const asNexchangeOrdersResponse = asObject({
   hasMore: asBoolean
 })
 
+// Each entry from /api/v2/currency/.  Many secondary fields exist but only the
+// ones below are needed to derive Edge chain plugin / token ids.
+const asNexchangeCurrencyMeta = asObject({
+  code: asString,
+  is_fiat: asOptional(asBoolean, false),
+  network: asOptional(asEither(asString, asNull), null),
+  contract_address: asOptional(asEither(asString, asNull), null),
+  common_symbol: asOptional(asEither(asString, asNull), null),
+  decimals: asOptional(asNumber, 8)
+})
+
+const asNexchangeCurrencyList = asArray(asNexchangeCurrencyMeta)
+
+export type NexchangeCurrencyMeta = ReturnType<typeof asNexchangeCurrencyMeta>
+export type NexchangeCurrencyInfoMap = Record<string, NexchangeCurrencyMeta>
+
 type NexchangeAuthMode = 'x-api-key' | 'authorization' | 'both'
 
 const QUERY_LOOKBACK = 1000 * 60 * 60 * 24 * 5 // 5 days
@@ -80,13 +103,58 @@ const statusMap: { [key: string]: Status } = {
   failed: 'other'
 }
 
+// Map of n.exchange network identifier -> Edge chain plugin id.
+// Networks that have no Edge equivalent are intentionally omitted; those
+// transactions will be reported without chain/token id enrichment.
+export const NEXCHANGE_NETWORK_TO_PLUGIN_ID: Record<string, string> = {
+  ADA: 'cardano',
+  ALGO: 'algorand',
+  ARB: 'arbitrum',
+  ATOM: 'cosmoshub',
+  AVAXC: 'avalanche',
+  BASE: 'base',
+  BCH: 'bitcoincash',
+  BSC: 'binancesmartchain',
+  BTC: 'bitcoin',
+  DASH: 'dash',
+  DOGE: 'dogecoin',
+  DOT: 'polkadot',
+  EOS: 'eos',
+  ETC: 'ethereumclassic',
+  ETH: 'ethereum',
+  FIL: 'filecoin',
+  FILEVM: 'filecoinfevm',
+  FTM: 'fantom',
+  HBAR: 'hedera',
+  HyperEvm: 'hyperevm',
+  LTC: 'litecoin',
+  // n.exchange exposes both MATIC and POL networks; both reference the same
+  // Polygon chain (chain id 137).
+  MATIC: 'polygon',
+  OP: 'optimism',
+  POL: 'polygon',
+  SOL: 'solana',
+  SONIC: 'sonic',
+  SUI: 'sui',
+  TON: 'ton',
+  TRON: 'tron',
+  TRX: 'tron',
+  XLM: 'stellar',
+  XMR: 'monero',
+  XRP: 'ripple',
+  XTZ: 'tezos',
+  ZEC: 'zcash'
+}
+
 function toQueryIsoDate(latestIsoDate: string): string {
   let previousTimestamp = new Date(latestIsoDate).getTime() - QUERY_LOOKBACK
   if (previousTimestamp < 0) previousTimestamp = 0
   return new Date(previousTimestamp).toISOString()
 }
 
-function parseApiDate(dateString: string): { isoDate: string; timestamp: number } {
+function parseApiDate(
+  dateString: string
+): { isoDate: string; timestamp: number } {
   const hasTimezone = /(Z|[+-]\d{2}:\d{2})$/.test(dateString)
   const normalized = hasTimezone ? dateString : `${dateString}Z`
   const date = new Date(normalized)
@@ -113,11 +181,137 @@ export function makeNexchangeHeaders(
   return headers
 }
 
+/**
+ * Fetches the n.exchange currency catalog and returns a lookup keyed by the
+ * uppercased currency code.  The catalog supplies the network and contract
+ * address fields that the audit-orders endpoint omits, which Edge needs to
+ * populate chain plugin id and token id.
+ */
+export async function fetchNexchangeCurrencyMap(
+  currencyUrl: string
+): Promise<NexchangeCurrencyInfoMap> {
+  const response = await retryFetch(currencyUrl, { method: 'GET' })
+  if (!response.ok) {
+    const text = await response.text()
+    throw new Error(`HTTP ${response.status.toString()}: ${text}`)
+  }
+  const json = await response.json()
+  const currencies = asNexchangeCurrencyList(json)
+  const map: NexchangeCurrencyInfoMap = {}
+  for (const currency of currencies) {
+    map[currency.code.toUpperCase()] = currency
+  }
+  return map
+}
+
+/**
+ * Resolves an n.exchange currency code into Edge chain plugin and token
+ * identifiers.  Returns `undefined` fields when the network is unknown to
+ * Edge, when no metadata is available, or when the currency is a fiat.  The
+ * caller is expected to leave the corresponding StandardTx fields undefined
+ * in that case so downstream rates lookup can fall back to currency-code
+ * mappings.
+ */
+export function resolveNexchangeAsset(
+  currencyCode: string,
+  currencyMap: NexchangeCurrencyInfoMap
+): {
+  currencyCode: string
+  chainPluginId?: string
+  tokenId?: string | null
+  evmChainId?: number
+} {
+  const upper = currencyCode.toUpperCase()
+  const meta = currencyMap[upper]
+
+  // Default to the raw nexchange code; downstream `standardizeNames` handles
+  // some of the composite codes (e.g. USDCSOL -> USDC).
+  let normalizedCode = upper
+
+  if (meta == null) {
+    return { currencyCode: normalizedCode }
+  }
+
+  // Prefer the canonical symbol when n.exchange supplies one.
+  if (
+    meta.common_symbol != null &&
+    meta.common_symbol !== '' &&
+    // Some entries embed suffixes like "USDT-old"; only use the symbol when
+    // it looks like a clean ticker.
+    /^[A-Za-z0-9]+$/.test(meta.common_symbol)
+  ) {
+    normalizedCode = meta.common_symbol.toUpperCase()
+  }
+
+  if (meta.is_fiat) {
+    return { currencyCode: normalizedCode }
+  }
+
+  const network = meta.network
+  if (network == null || network === '') {
+    return { currencyCode: normalizedCode }
+  }
+
+  const chainPluginId = NEXCHANGE_NETWORK_TO_PLUGIN_ID[network]
+  if (chainPluginId == null) {
+    return { currencyCode: normalizedCode }
+  }
+
+  const tokenType = tokenTypes[chainPluginId]
+  const evmChainId = EVM_CHAIN_IDS[chainPluginId]
+
+  // No contract_address means a native chain asset.
+  const contractAddress = meta.contract_address
+  if (contractAddress == null || contractAddress === '') {
+    return {
+      currencyCode: normalizedCode,
+      chainPluginId,
+      tokenId: null,
+      evmChainId
+    }
+  }
+
+  // The contract address is present but the chain does not support tokens in
+  // Edge's model.  Fall back to a chain-only mapping so we at least populate
+  // the chain plugin id for rates lookup.
+  if (tokenType == null) {
+    return {
+      currencyCode: normalizedCode,
+      chainPluginId,
+      tokenId: null,
+      evmChainId
+    }
+  }
+
+  let tokenId: string | null
+  try {
+    tokenId = createTokenId(tokenType, normalizedCode, contractAddress)
+  } catch (e) {
+    datelog(
+      `nexchange: unable to derive tokenId for ${upper} (${chainPluginId}): ${String(
+        e
+      )}`
+    )
+    return {
+      currencyCode: normalizedCode,
+      chainPluginId,
+      evmChainId
+    }
+  }
+
+  return {
+    currencyCode: normalizedCode,
+    chainPluginId,
+    tokenId,
+    evmChainId
+  }
+}
+
 export async function queryNexchange(
   pluginParams: PluginParams
 ): Promise<PluginResult> {
   const { settings, apiKeys } = asNexchangePluginParams(pluginParams)
-  const { apiKey, baseUrl, authMode } = apiKeys
+  const { apiKey, baseUrl, currencyUrl, authMode } = apiKeys
   let { latestIsoDate } = settings
 
   if (apiKey == null || apiKey === '') {
@@ -130,6 +324,15 @@ export async function queryNexchange(
   let offset = 0
   let retry = 0
 
+  // Fetch the currency catalog once per query.  An empty map degrades the
+  // plugin to legacy behaviour (no chain/token enrichment) instead of failing.
+  let currencyMap: NexchangeCurrencyInfoMap = {}
+  try {
+    currencyMap = await fetchNexchangeCurrencyMap(currencyUrl)
+  } catch (e) {
+    datelog(`nexchange: failed to fetch currency catalog: ${String(e)}`)
+  }
+
   const txByOrderId: Map<string, StandardTx> = new Map()
 
   while (true) {
@@ -156,7 +359,7 @@ export async function queryNexchange(
       const { orders, nextCursor, hasMore } = asNexchangeOrdersResponse(json)
 
       for (const rawOrder of orders) {
-        const standardTx = processNexchangeTx(rawOrder)
+        const standardTx = processNexchangeTx(rawOrder, currencyMap)
         txByOrderId.set(standardTx.orderId, standardTx)
         if (standardTx.isoDate > latestIsoDate) {
           latestIsoDate = standardTx.isoDate
@@ -197,26 +400,38 @@ export const nexchange: PartnerPlugin = {
   pluginId: 'nexchange'
 }
 
-export function processNexchangeTx(rawTx: unknown): StandardTx {
+export function processNexchangeTx(
+  rawTx: unknown,
+  currencyMap: NexchangeCurrencyInfoMap = {}
+): StandardTx {
   const tx = asNexchangeOrder(rawTx)
   const lowerStatus = tx.status.toLowerCase()
   const status = statusMap[lowerStatus] ?? 'other'
   const { isoDate, timestamp } = parseApiDate(tx.createdAt)
 
+  const deposit = resolveNexchangeAsset(tx.deposit.currency, currencyMap)
+  const payout = resolveNexchangeAsset(tx.payout.currency, currencyMap)
+
   return {
     status,
     orderId: tx.orderId,
     countryCode: tx.countryCode,
     depositTxid: tx.deposit.txid ?? undefined,
     depositAddress: tx.deposit.address ?? undefined,
-    depositCurrency: tx.deposit.currency.toUpperCase(),
+    depositCurrency: deposit.currencyCode,
+    depositChainPluginId: deposit.chainPluginId,
+    depositTokenId: deposit.tokenId,
+    depositEvmChainId: deposit.evmChainId,
     depositAmount: safeParseFloat(tx.deposit.amount),
     direction: null,
     exchangeType: 'swap',
     paymentType: null,
     payoutTxid: tx.payout.txid ?? undefined,
     payoutAddress: tx.payout.address ?? undefined,
-    payoutCurrency: tx.payout.currency.toUpperCase(),
+    payoutCurrency: payout.currencyCode,
+    payoutChainPluginId: payout.chainPluginId,
+    payoutTokenId: payout.tokenId,
+    payoutEvmChainId: payout.evmChainId,
     payoutAmount: safeParseFloat(tx.payout.amount),
     timestamp,
     isoDate,