Add NYM Swap (nymswap) reporting plugin

Query NYM's partner reporting API for completed swap orders and map them
into StandardTx, modeled on the clean shape of swapuz. Register nymswap in
queryEngine and the demo partners config. Add a transform unit test.

The reporting endpoint, auth scheme, and order field names are the
documented assumption to confirm with NYM; credentials are human/ops set.

Author: j0ntz

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- added: Add NYM Swap (nymswap) reporting
 - changed: Update sideshift plugin with new optional API fields
 - changed: Add signature header support to Exolix
 - changed: Add index for orderId

src/demo/partners.ts

@@ -97,6 +97,10 @@ export default {
     type: 'fiat',
     color: '#7214F5'
   },
+  nymswap: {
+    type: 'swap',
+    color: '#FB6E4E'
+  },
   paybis: {
     type: 'fiat',
     color: '#FFB400'

src/partners/nym.ts

@@ -0,0 +1,351 @@
+import {
+  asArray,
+  asMaybe,
+  asNumber,
+  asObject,
+  asOptional,
+  asString,
+  asUnknown,
+  asValue
+} from 'cleaners'
+
+import {
+  PartnerPlugin,
+  PluginParams,
+  PluginResult,
+  StandardTx,
+  Status
+} from '../types'
+import {
+  retryFetch,
+  safeParseFloat,
+  smartIsoDateFromTimestamp,
+  snooze
+} from '../util'
+
+// NYM ("nymswap") reporting plugin.
+//
+// Confirmed against NYM's live "Edge Partner" API (OpenAPI at
+// https://nym-swap-api.nymtech.cc/api/docs/) and a live query under the GUI's
+// swap key. The reporting endpoint is
+//   GET /api/partner/v1/reports/transactions
+// authenticated with the same `x-api-key` header the swap plugin uses
+// (edge-exchange-plugins src/swap/central/nym.ts). Query params are `startDate`
+// /`endDate` (ISO date-time), `limit` (<= 500), and an opaque `cursor`; the
+// response is
+//   { transactions: EdgeTransactionRecord[], nextCursor: string | null }
+// paged by following `nextCursor` until it is null.
+//
+// Amounts arrive as native-unit strings (e.g. ETH in wei). StandardTx wants
+// major units, so each is divided by 10^decimals using NYM's own
+// GET /api/partner/v1/currencies list, keyed by currency code + tokenId.
+//
+// The report timestamp is keyed off `createdDate`: NYM leaves `completedDate`
+// null on most completed orders (observed 7 of 8 in the live sample), so it is
+// not a reliable time source.
+const NYM_API_BASE = 'https://nym-swap-api.nymtech.cc'
+const REPORTS_PATH = '/api/partner/v1/reports/transactions'
+const CURRENCIES_PATH = '/api/partner/v1/currencies'
+
+// Re-query a 5-day window behind the saved progress so in-flight orders that
+// settle after the previous run are re-seen (mirrors sibling swap partners).
+const QUERY_LOOKBACK = 1000 * 60 * 60 * 24 * 5 // 5 days
+const PAGE_LIMIT = 500 // API max
+const MAX_RETRIES = 5
+
+// Fallback native-unit decimals for NYM's current asset set, used only when the
+// live /currencies fetch fails. The live list overlays this at runtime, so a
+// newly listed asset is picked up automatically. Key: `CODE|tokenIdLower`.
+const DEFAULT_DECIMALS: { [key: string]: number } = {
+  'BTC|': 8,
+  'ETH|': 18,
+  'NYM|': 6,
+  'USDT|0xdac17f958d2ee523a2206206994597c13d831ec7': 6,
+  'USDC|0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48': 6,
+  'NYM|0x525a8f6f3ba4752868cde25164382bfbae3990e1': 6
+}
+
+interface DecimalsMap {
+  [key: string]: number
+}
+
+const decimalsKey = (
+  currencyCode: string,
+  tokenId: string | undefined
+): string => `${currencyCode.toUpperCase()}|${(tokenId ?? '').toLowerCase()}`
+
+export const asNymPluginParams = asObject({
+  settings: asObject({
+    latestIsoDate: asOptional(asString, '1970-01-01T00:00:00.000Z')
+  }),
+  apiKeys: asObject({
+    // Partner-issued reporting key, human/ops-set in production CouchDB
+    // (reports_apps partnerIds.nymswap.apiKeys). Never fetched or set by code.
+    apiKey: asString
+  })
+})
+
+// NYM's EdgeStatus enum. Unknown values degrade to 'other' instead of throwing.
+const asNymStatus = asMaybe(
+  asValue(
+    'pending',
+    'processing',
+    'infoNeeded',
+    'expired',
+    'refunded',
+    'completed'
+  ),
+  'other'
+)
+type NymStatus = ReturnType<typeof asNymStatus>
+
+const statusMap: { [key in NymStatus]: Status } = {
+  pending: 'pending',
+  processing: 'processing',
+  infoNeeded: 'blocked',
+  expired: 'expired',
+  refunded: 'refunded',
+  completed: 'complete',
+  other: 'other'
+}
+
+// A supported-asset entry from GET /api/partner/v1/currencies. Only the fields
+// used to convert native amounts to major units are consumed.
+const asNymCurrency = asObject({
+  currencyCode: asString,
+  tokenId: asMaybe(asString),
+  decimals: asNumber
+})
+const asNymCurrencies = asArray(asNymCurrency)
+
+// One EdgeTransactionRecord. `orderId`/`status`/`createdDate`, the currency
+// codes, and the native-unit amounts are always present; the nullable/optional
+// fields use asMaybe so a partial or differently-typed record degrades to
+// undefined instead of throwing and aborting the whole query block.
+const asNymTransaction = asObject({
+  orderId: asString,
+  status: asNymStatus,
+  createdDate: asString,
+  completedDate: asMaybe(asString),
+
+  // Source (deposit) side.
+  sourceCurrencyCode: asString,
+  sourceTokenId: asMaybe(asString),
+  sourceAmount: asString,
+  payinAddress: asMaybe(asString),
+  payinTxid: asMaybe(asString),
+
+  // Destination (payout) side.
+  destinationCurrencyCode: asString,
+  destinationTokenId: asMaybe(asString),
+  destinationAmount: asString,
+  payoutAddress: asMaybe(asString),
+  payoutTxid: asMaybe(asString)
+})
+
+// Reporting page envelope: `{ transactions, nextCursor }`.
+const asNymResult = asObject({
+  transactions: asArray(asUnknown),
+  nextCursor: asMaybe(asString)
+})
+
+// Converts a native-unit amount string to a major-unit number using the asset's
+// decimals (live /currencies, then DEFAULT_DECIMALS). Throws for an unknown
+// asset so the caller skips the record rather than reporting a mis-scaled
+// amount that would corrupt the downstream USD valuation.
+const toMajorAmount = (
+  nativeAmount: string,
+  currencyCode: string,
+  tokenId: string | undefined,
+  decimals: DecimalsMap
+): number => {
+  const key = decimalsKey(currencyCode, tokenId)
+  const dec = decimals[key] ?? DEFAULT_DECIMALS[key]
+  if (dec == null) {
+    throw new Error(`Unknown decimals for ${key}`)
+  }
+  const native = safeParseFloat(nativeAmount)
+  if (!Number.isFinite(native)) return 0
+  return native / 10 ** dec
+}
+
+// Fetches NYM's supported-asset list into a decimals lookup. Non-fatal: on any
+// error, processNymTx falls back to DEFAULT_DECIMALS for the known asset set.
+const fetchDecimals = async (
+  headers: { [key: string]: string },
+  log: PluginParams['log']
+): Promise<DecimalsMap> => {
+  const decimals: DecimalsMap = {}
+  try {
+    const response = await retryFetch(`${NYM_API_BASE}${CURRENCIES_PATH}`, {
+      method: 'GET',
+      headers
+    })
+    if (!response.ok) throw new Error(await response.text())
+    const currencies = asNymCurrencies(await response.json())
+    for (const c of currencies) {
+      decimals[decimalsKey(c.currencyCode, c.tokenId)] = c.decimals
+    }
+  } catch (e) {
+    log.warn(
+      `Could not fetch NYM currencies, using fallback decimals: ${String(e)}`
+    )
+  }
+  return decimals
+}
+
+export async function queryNym(
+  pluginParams: PluginParams
+): Promise<PluginResult> {
+  const { log } = pluginParams
+  const { settings, apiKeys } = asNymPluginParams(pluginParams)
+  const { apiKey } = apiKeys
+  let { latestIsoDate } = settings
+
+  // Progress persisted before this run. Only advanced past when the full cursor
+  // walk COMPLETES (nextCursor null); on an error-driven early exit we keep this
+  // value so a partial fetch never skips orders we did not page through. This
+  // does not depend on the API's page ordering.
+  const savedIsoDate = latestIsoDate
+
+  const standardTxs: StandardTx[] = []
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    'x-api-key': apiKey
+  }
+
+  const decimals = await fetchDecimals(headers, log)
+
+  let lookbackTimestamp = new Date(latestIsoDate).getTime() - QUERY_LOOKBACK
+  if (lookbackTimestamp < 0) lookbackTimestamp = 0
+  const startDate = new Date(lookbackTimestamp).toISOString()
+
+  let cursor: string | undefined
+  let retry = 0
+  let completed = false
+
+  while (true) {
+    let url = `${NYM_API_BASE}${REPORTS_PATH}?startDate=${encodeURIComponent(
+      startDate
+    )}&limit=${PAGE_LIMIT}`
+    if (cursor != null) url += `&cursor=${encodeURIComponent(cursor)}`
+    try {
+      const response = await retryFetch(url, { method: 'GET', headers })
+      if (!response.ok) {
+        const text = await response.text()
+        throw new Error(text)
+      }
+      const { transactions, nextCursor } = asNymResult(await response.json())
+      for (const rawTx of transactions) {
+        // Skip a single unparseable/unpriceable record rather than throwing out
+        // to the page retry below, which would re-append this page's already
+        // -pushed records and produce duplicate orderIds.
+        let standardTx: StandardTx
+        try {
+          standardTx = processNymTx(rawTx, decimals)
+        } catch (e) {
+          log.error(`Skipping unparseable transaction: ${String(e)}`)
+          continue
+        }
+        standardTxs.push(standardTx)
+        if (standardTx.isoDate > latestIsoDate) {
+          latestIsoDate = standardTx.isoDate
+        }
+      }
+      log(
+        `cursor=${cursor ?? 'start'} count=${
+          transactions.length
+        } latestIsoDate ${latestIsoDate}`
+      )
+      retry = 0
+      // A null nextCursor marks the last page: the walk is complete.
+      if (nextCursor == null) {
+        completed = true
+        break
+      }
+      cursor = nextCursor
+    } catch (e) {
+      log.error(String(e))
+      // Retry the SAME cursor a few times to ride out throttling.
+      retry++
+      if (retry <= MAX_RETRIES) {
+        log.warn(`Snoozing ${5 * retry}s`)
+        await snooze(5000 * retry)
+      } else {
+        // Give up this run WITHOUT advancing progress (completed stays false),
+        // so the unfetched remainder is re-queried next run. Already-fetched
+        // records are still returned; the cache engine dedupes them by orderId.
+        break
+      }
+    }
+  }
+
+  const out: PluginResult = {
+    settings: { latestIsoDate: completed ? latestIsoDate : savedIsoDate },
+    transactions: standardTxs
+  }
+  return out
+}
+
+export const nymswap: PartnerPlugin = {
+  // queryFunc takes PluginParams and returns a PluginResult
+  queryFunc: queryNym,
+  pluginName: 'NYM',
+  pluginId: 'nymswap'
+}
+
+export function processNymTx(
+  rawTx: unknown,
+  decimals: DecimalsMap = {}
+): StandardTx {
+  const tx = asNymTransaction(rawTx)
+
+  // completedDate is frequently null even on completed orders, so key the report
+  // timestamp off createdDate (always present).
+  const { isoDate, timestamp } = smartIsoDateFromTimestamp(tx.createdDate)
+
+  const depositAmount = toMajorAmount(
+    tx.sourceAmount,
+    tx.sourceCurrencyCode,
+    tx.sourceTokenId,
+    decimals
+  )
+  const payoutAmount = toMajorAmount(
+    tx.destinationAmount,
+    tx.destinationCurrencyCode,
+    tx.destinationTokenId,
+    decimals
+  )
+
+  // Clean shape (mirrors swapuz): carry currency codes + major-unit amounts and
+  // leave the chain/evm/token plugin fields undefined (NYM's `sourceNetwork`
+  // naming does not map 1:1 to Edge plugin ids).
+  const standardTx: StandardTx = {
+    status: statusMap[tx.status],
+    orderId: tx.orderId,
+    countryCode: null,
+    depositTxid: tx.payinTxid,
+    depositAddress: tx.payinAddress,
+    depositCurrency: tx.sourceCurrencyCode.toUpperCase(),
+    depositChainPluginId: undefined,
+    depositEvmChainId: undefined,
+    depositTokenId: undefined,
+    depositAmount,
+    direction: null,
+    exchangeType: 'swap',
+    paymentType: null,
+    payoutTxid: tx.payoutTxid,
+    payoutAddress: tx.payoutAddress,
+    payoutCurrency: tx.destinationCurrencyCode.toUpperCase(),
+    payoutChainPluginId: undefined,
+    payoutEvmChainId: undefined,
+    payoutTokenId: undefined,
+    payoutAmount,
+    timestamp,
+    isoDate,
+    usdValue: -1,
+    rawTx
+  }
+  return standardTx
+}

src/queryEngine.ts

@@ -22,6 +22,7 @@ import { letsexchange } from './partners/letsexchange'
 import { libertyx } from './partners/libertyx'
 import { lifi } from './partners/lifi'
 import { moonpay } from './partners/moonpay'
+import { nymswap } from './partners/nym'
 import { paybis } from './partners/paybis'
 import { paytrie } from './partners/paytrie'
 import { rango } from './partners/rango'
@@ -74,6 +75,7 @@ const plugins = [
   lifi,
   maya,
   moonpay,
+  nymswap,
   paybis,
   paytrie,
   rango,