@riocrypto/common-server 1.0.2782 → 1.0.2783

package/build/clients/cluster-client.d.ts

@@ -186,7 +186,7 @@ declare class ClusterClient {
         requestedOriginAmount?: number;
         requestedDestinationAmount?: number;
         limitPrice?: number;
-        twoWaySettlementDateOffset: number;
+        twoWaySettlementDateOffset?: number;
         arbitrageSessionId?: string;
         fxTradeId?: string;
         timeInForce?: "day" | "gtc" | "ioc" | "fok";

package/build/helpers/get-fx-trading-policy.d.ts

@@ -0,0 +1,61 @@
+import { Fiat, FXTradingSidePolicy, RioSettings, ResolvedFXPlacement, Side } from "@riocrypto/common";
+/**
+ * Minimum trade size (in MXN) below which the Transnetwork bot will reject
+ * an order. Kept here because it's a hard operational constraint of the
+ * provider, not a per-policy admin setting.
+ */
+export declare const TRANSNETWORK_MIN_MXN_AMOUNT = 1000000;
+type RioSettingsForPolicy = Pick<RioSettings, "fxTradingPolicies">;
+/**
+ * Resolve the active FX trading side-policy for a given (fiat, side, offset).
+ *
+ * Resolution order:
+ *  1. `fxTradingPolicies[fiat].byOffset[offset][side]` if defined
+ *  2. `fxTradingPolicies[fiat].default[side]` if defined
+ *  3. An empty policy that routes every trade to manual (Other) with no
+ *     execution threshold. This is the safe default when no policy is
+ *     configured for a (fiat, side) - the operator must explicitly opt in
+ *     to any automated path.
+ *
+ * Per-side overrides are all-or-nothing: a configured override fully
+ * replaces the default; no field-level merging happens. Offsets without
+ * an explicit override always fall back to the default for that
+ * (fiat, side), regardless of how distant they are from any configured
+ * override.
+ *
+ * A caller that passes `undefined` (e.g. an order whose request body
+ * omitted twoWaySettlementType, which means "default / spot") is
+ * treated as T+0 so the same byOffset[0] override and provider
+ * eligibility apply as an explicit T+0 trade.
+ */
+export declare const getFXTradingPolicy: (rioSettings: RioSettingsForPolicy, fiat: Fiat, side: Side, twoWaySettlementDateOffset: number | undefined) => FXTradingSidePolicy;
+/**
+ * Resolve the runtime placement for an FX trade given a side-policy and
+ * the trade's amount. Returns `{ provider, automatic, executionThresholdMs }`:
+ *  - First the time range covering "now" in the currency's country-local
+ *    timezone is selected. If no range covers the current minute,
+ *    the trade falls back to manual (Other/automatic, threshold=0).
+ *  - The matched time window's `executionThresholdMs` is always
+ *    surfaced even when the inner amount-range lookup falls through to
+ *    Other - aggregation behavior is a property of the time window, not
+ *    of the band the trade landed in.
+ *  - Within that time range, the first amount range matching the trade
+ *    amount wins.
+ *  - If the matched amount range's provider fails operational eligibility
+ *    (e.g. Transnetwork below its 1M minimum, StoneX at T+0), falls back
+ *    to manual (Other/automatic) while preserving the window's threshold.
+ *  - If no amount range matches, same fallback (preserves threshold).
+ *  - For providers that don't support cosigner approval (Matching, Other)
+ *    the `automatic` flag is forced to true regardless of what is stored
+ *    on the range - the dashboard renders the checkbox forced-on for
+ *    these providers, but defense-in-depth on the runtime is cheap.
+ *
+ * `now` defaults to `new Date()` and is exposed so the cron sweep can
+ * pin a single timestamp across the whole batch.
+ *
+ * `Other` returning `automatic: true` is intentional: there is no
+ * cosigner gate for manual trades, so they immediately settle without
+ * waiting for approval.
+ */
+export declare const resolveFXProviderForAmount: (policy: FXTradingSidePolicy, fiat: Fiat, amountFiat: number, offset: number | undefined, now?: Date) => ResolvedFXPlacement;
+export {};

package/build/helpers/get-fx-trading-policy.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFXProviderForAmount = exports.getFXTradingPolicy = exports.TRANSNETWORK_MIN_MXN_AMOUNT = void 0;
+const common_1 = require("@riocrypto/common");
+/**
+ * Minimum trade size (in MXN) below which the Transnetwork bot will reject
+ * an order. Kept here because it's a hard operational constraint of the
+ * provider, not a per-policy admin setting.
+ */
+exports.TRANSNETWORK_MIN_MXN_AMOUNT = 1000000;
+/**
+ * Settlement-offset constraints baked into provider eligibility. The
+ * Emarkets and Transnetwork bots only quote spot / very-short-dated MXN
+ * (T+0..T+2), and StoneX is RFQ/RFS for forward MXN (T+1+) and refuses
+ * same-day (T+0). Keep these in sync with
+ * `isProviderSelectableForFiatAndOffset` in the dashboard's
+ * fx-trading-policy-card so saved policies match what the runtime will
+ * actually pick.
+ */
+const SHORT_DATED_BOT_MAX_OFFSET = 2;
+const STONEX_MIN_OFFSET = 1;
+/**
+ * Providers that do not support a cosigner approval workflow. For these
+ * providers the `automatic` flag is meaningless and the runtime always
+ * treats the band as automatic, regardless of what is persisted on the
+ * policy. The dashboard mirrors this by rendering the checkbox forced-on
+ * and disabled for these providers.
+ *
+ * StoneX is intentionally NOT in this set: even though placement is RFQ
+ * (not fill-or-kill), internal-fx supports gating a StoneX placement
+ * behind the same cosigner webhook the bots use, so operators can
+ * require approval before an RFQ stream is opened.
+ */
+const NON_COSIGNER_PROVIDERS = new Set([
+    common_1.FXProvider.Matching,
+    common_1.FXProvider.Other,
+]);
+const FALLBACK_RESOLUTION = {
+    provider: common_1.FXProvider.Other,
+    automatic: true,
+    // 0ms threshold = place immediately. The Other path completes
+    // manually with no aggregation; surfacing a longer threshold here
+    // would just pin manual trades in PendingExecutionThreshold for no
+    // reason.
+    executionThresholdMs: 0,
+};
+/**
+ * Defensive shape-check. Legacy persisted policies use a different shape
+ * (`providers[]` / `automaticTradeLimit`, or the pre-per-window-threshold
+ * shape that put `executionThresholdMs` on the side policy) - left in
+ * place by an out-of-date deploy, by an admin who hasn't saved the new
+ * editor yet, or by a typo'd manual DB edit. The resolver MUST NOT
+ * crash on that data; instead it treats those slots as "not configured"
+ * so the safe Other/automatic fallback applies and trades route to
+ * manual until the admin saves the new policy shape.
+ */
+const isWellFormedSidePolicy = (policy) => {
+    if (!policy || typeof policy !== "object")
+        return false;
+    const candidate = policy;
+    return Array.isArray(candidate.byTimeRange);
+};
+/**
+ * Defensive shape-check for a single time range. The resolver tolerates
+ * a malformed entry by skipping it (so a malformed window doesn't take
+ * down the whole side). Note: we do NOT require contiguous coverage at
+ * the resolver layer - the rio-settings save route enforces that. Stale
+ * data with a gap still routes to manual via fallback.
+ *
+ * `executionThresholdMs` may be absent on legacy rows that were saved
+ * before the threshold moved per-window; we treat that as "place
+ * immediately" rather than rejecting the whole window, which matches
+ * the safer default and keeps existing routing rules intact for
+ * operators who haven't re-saved yet.
+ */
+const isWellFormedTimeRange = (range) => {
+    if (!range || typeof range !== "object")
+        return false;
+    const candidate = range;
+    return (typeof candidate.startMinute === "number" &&
+        typeof candidate.endMinute === "number" &&
+        Array.isArray(candidate.byAmountRange));
+};
+const safeExecutionThresholdMs = (range) => {
+    return typeof range.executionThresholdMs === "number" &&
+        Number.isFinite(range.executionThresholdMs) &&
+        range.executionThresholdMs >= 0
+        ? range.executionThresholdMs
+        : 0;
+};
+const pickPolicyBySide = (policyBySide, side) => {
+    if (!policyBySide) {
+        return undefined;
+    }
+    const candidate = policyBySide[side];
+    if (!isWellFormedSidePolicy(candidate)) {
+        return undefined;
+    }
+    return candidate;
+};
+/**
+ * Resolve the active FX trading side-policy for a given (fiat, side, offset).
+ *
+ * Resolution order:
+ *  1. `fxTradingPolicies[fiat].byOffset[offset][side]` if defined
+ *  2. `fxTradingPolicies[fiat].default[side]` if defined
+ *  3. An empty policy that routes every trade to manual (Other) with no
+ *     execution threshold. This is the safe default when no policy is
+ *     configured for a (fiat, side) - the operator must explicitly opt in
+ *     to any automated path.
+ *
+ * Per-side overrides are all-or-nothing: a configured override fully
+ * replaces the default; no field-level merging happens. Offsets without
+ * an explicit override always fall back to the default for that
+ * (fiat, side), regardless of how distant they are from any configured
+ * override.
+ *
+ * A caller that passes `undefined` (e.g. an order whose request body
+ * omitted twoWaySettlementType, which means "default / spot") is
+ * treated as T+0 so the same byOffset[0] override and provider
+ * eligibility apply as an explicit T+0 trade.
+ */
+const getFXTradingPolicy = (rioSettings, fiat, side, twoWaySettlementDateOffset) => {
+    var _a;
+    const effectiveOffset = twoWaySettlementDateOffset !== null && twoWaySettlementDateOffset !== void 0 ? twoWaySettlementDateOffset : 0;
+    const fiatPolicies = (_a = rioSettings.fxTradingPolicies) === null || _a === void 0 ? void 0 : _a[fiat];
+    if (fiatPolicies) {
+        if (fiatPolicies.byOffset) {
+            const offsetPolicy = pickPolicyBySide(fiatPolicies.byOffset[effectiveOffset], side);
+            if (offsetPolicy) {
+                return offsetPolicy;
+            }
+        }
+        const defaultPolicy = pickPolicyBySide(fiatPolicies.default, side);
+        if (defaultPolicy) {
+            return defaultPolicy;
+        }
+    }
+    return { byTimeRange: [] };
+};
+exports.getFXTradingPolicy = getFXTradingPolicy;
+/**
+ * Returns true when the given provider can operationally handle the trade.
+ * These are hard provider-side constraints, not admin-configurable.
+ *
+ * `offset === undefined` is interpreted as T+0 (the system convention:
+ * "no settlement type specified" == "default" == spot), matching
+ * `getFXTradingPolicy`. As a result Emarkets / Transnetwork stay eligible
+ * for undefined-offset callers but StoneX (which refuses T+0) does not.
+ */
+const isProviderEligible = (provider, fiat, amountFiat, offset) => {
+    if (provider === common_1.FXProvider.StoneX ||
+        provider === common_1.FXProvider.Emarkets ||
+        provider === common_1.FXProvider.Transnetwork) {
+        if (fiat !== common_1.Fiat.MXN)
+            return false;
+    }
+    if (provider === common_1.FXProvider.Transnetwork) {
+        if (amountFiat === undefined || amountFiat < exports.TRANSNETWORK_MIN_MXN_AMOUNT) {
+            return false;
+        }
+    }
+    const effectiveOffset = offset !== null && offset !== void 0 ? offset : 0;
+    if ((provider === common_1.FXProvider.Emarkets ||
+        provider === common_1.FXProvider.Transnetwork) &&
+        effectiveOffset > SHORT_DATED_BOT_MAX_OFFSET) {
+        return false;
+    }
+    if (provider === common_1.FXProvider.StoneX && effectiveOffset < STONEX_MIN_OFFSET) {
+        return false;
+    }
+    return true;
+};
+/**
+ * Returns true if `amount` falls inside `[range.minAmount, range.maxAmount)`.
+ * Both bounds are required by the type, but the resolver defensively
+ * treats a missing/non-finite `maxAmount` (legacy data, manual db edit)
+ * as a non-match so the trade falls through to the safe Other/manual
+ * fallback rather than silently inheriting a previous "open-ended"
+ * interpretation.
+ */
+const rangeMatchesAmount = (range, amount) => {
+    const min = Math.max(range.minAmount, 0);
+    if (amount < min)
+        return false;
+    if (typeof range.maxAmount !== "number" || !Number.isFinite(range.maxAmount)) {
+        return false;
+    }
+    return amount < range.maxAmount;
+};
+/**
+ * Returns true if `minuteOfDay` (0..1439, in the time range's reference
+ * timezone) falls inside `[range.startMinute, range.endMinute)`.
+ */
+const rangeMatchesMinute = (range, minuteOfDay) => {
+    if (minuteOfDay < range.startMinute)
+        return false;
+    return minuteOfDay < range.endMinute;
+};
+/**
+ * Returns the current minute-of-day in the given IANA timezone, in the
+ * range [0, 1440). Uses `Intl.DateTimeFormat` so DST transitions are
+ * applied automatically by the platform - no manual offset bookkeeping.
+ *
+ * `now` is injectable for testability and so a single cron tick can
+ * snapshot the time once and reuse it across all FX trades being swept.
+ */
+const getMinuteOfDayInTimezone = (now, timezone) => {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+    }).formatToParts(now);
+    let hour = 0;
+    let minute = 0;
+    for (const part of parts) {
+        if (part.type === "hour")
+            hour = parseInt(part.value, 10);
+        if (part.type === "minute")
+            minute = parseInt(part.value, 10);
+    }
+    // Intl formats midnight as "24" in some locales/Node versions; clamp
+    // defensively so we never return 1440 (which would miss the [0, 1440)
+    // last range and fall through to manual).
+    if (hour === 24)
+        hour = 0;
+    return hour * 60 + minute;
+};
+/**
+ * Resolve the runtime placement for an FX trade given a side-policy and
+ * the trade's amount. Returns `{ provider, automatic, executionThresholdMs }`:
+ *  - First the time range covering "now" in the currency's country-local
+ *    timezone is selected. If no range covers the current minute,
+ *    the trade falls back to manual (Other/automatic, threshold=0).
+ *  - The matched time window's `executionThresholdMs` is always
+ *    surfaced even when the inner amount-range lookup falls through to
+ *    Other - aggregation behavior is a property of the time window, not
+ *    of the band the trade landed in.
+ *  - Within that time range, the first amount range matching the trade
+ *    amount wins.
+ *  - If the matched amount range's provider fails operational eligibility
+ *    (e.g. Transnetwork below its 1M minimum, StoneX at T+0), falls back
+ *    to manual (Other/automatic) while preserving the window's threshold.
+ *  - If no amount range matches, same fallback (preserves threshold).
+ *  - For providers that don't support cosigner approval (Matching, Other)
+ *    the `automatic` flag is forced to true regardless of what is stored
+ *    on the range - the dashboard renders the checkbox forced-on for
+ *    these providers, but defense-in-depth on the runtime is cheap.
+ *
+ * `now` defaults to `new Date()` and is exposed so the cron sweep can
+ * pin a single timestamp across the whole batch.
+ *
+ * `Other` returning `automatic: true` is intentional: there is no
+ * cosigner gate for manual trades, so they immediately settle without
+ * waiting for approval.
+ */
+const resolveFXProviderForAmount = (policy, fiat, amountFiat, offset, now = new Date()) => {
+    const country = (0, common_1.getCountryForFiat)(fiat);
+    const timezone = (0, common_1.getCountryTimezone)(country);
+    const minuteOfDay = getMinuteOfDayInTimezone(now, timezone);
+    const matchedTimeRange = policy.byTimeRange.find((range) => isWellFormedTimeRange(range) && rangeMatchesMinute(range, minuteOfDay));
+    if (!matchedTimeRange) {
+        return FALLBACK_RESOLUTION;
+    }
+    // Threshold for the active time window. Always returned (even when
+    // we fall through to Other below) so callers can decide aggregation
+    // based on the window the trade is currently in, not the window when
+    // it was created.
+    const executionThresholdMs = safeExecutionThresholdMs(matchedTimeRange);
+    const matchedAmountRange = matchedTimeRange.byAmountRange.find((range) => rangeMatchesAmount(range, amountFiat));
+    if (!matchedAmountRange) {
+        return Object.assign(Object.assign({}, FALLBACK_RESOLUTION), { executionThresholdMs });
+    }
+    if (!isProviderEligible(matchedAmountRange.provider, fiat, amountFiat, offset)) {
+        return Object.assign(Object.assign({}, FALLBACK_RESOLUTION), { executionThresholdMs });
+    }
+    const automatic = NON_COSIGNER_PROVIDERS.has(matchedAmountRange.provider)
+        ? true
+        : matchedAmountRange.automatic;
+    return {
+        provider: matchedAmountRange.provider,
+        automatic,
+        executionThresholdMs,
+    };
+};
+exports.resolveFXProviderForAmount = resolveFXProviderForAmount;

package/build/index.d.ts

@@ -171,3 +171,4 @@ export * from "./helpers/interpolate-forward-curve-rate";
 export * from "./helpers/find-user-tier-forward-curve-rate";
 export * from "./helpers/resolve-forward-curve-rate";
 export * from "./helpers/get-resolved-forward-curve-tiers";
+export * from "./helpers/get-fx-trading-policy";

package/build/index.js

@@ -187,3 +187,4 @@ __exportStar(require("./helpers/interpolate-forward-curve-rate"), exports);
 __exportStar(require("./helpers/find-user-tier-forward-curve-rate"), exports);
 __exportStar(require("./helpers/resolve-forward-curve-rate"), exports);
 __exportStar(require("./helpers/get-resolved-forward-curve-tiers"), exports);
+__exportStar(require("./helpers/get-fx-trading-policy"), exports);

package/build/models/rio-settings.d.ts

@@ -1,4 +1,4 @@
-import { Country, DeferredPaymentType, EmarketsSettlementType, Fiat, FXProvider, Processor, Side, TransnetworkSettlementType } from "@riocrypto/common";
+import { Country, DeferredPaymentType, EmarketsSettlementType, Fiat, FXProvider, FXTradingPolicies, Processor, Side, TransnetworkSettlementType } from "@riocrypto/common";
 import { TVFXDataProvider } from "@riocrypto/common";
 import mongoose, { HydratedDocument } from "mongoose";
 interface RioSettingsAttrs {
@@ -28,12 +28,6 @@ interface RioSettingsAttrs {
     sellOrderGeneralExchangeRateMarkup: {
         [key in Fiat]: number;
     };
-    buyOrderAutomaticFXTradeLimit: {
-        [key in Fiat]: number;
-    };
-    sellOrderAutomaticFXTradeLimit: {
-        [key in Fiat]: number;
-    };
     defaultServiceFee: {
         [key in Country]?: {
             [key in Side]?: number;
@@ -51,7 +45,7 @@ interface RioSettingsAttrs {
             };
         };
     };
-    fxExecutionThreshold: number;
+    fxTradingPolicies?: FXTradingPolicies;
     activeFiatPaymentProcessors: {
         [Side.Buy]: Processor[];
         [Side.Sell]: Processor[];
@@ -117,12 +111,6 @@ interface RioSettingsDoc extends mongoose.Document {
     sellOrderAfterHoursExchangeRateMarkup: {
         [key in Fiat]: number;
     };
-    buyOrderAutomaticFXTradeLimit: {
-        [key in Fiat]: number;
-    };
-    sellOrderAutomaticFXTradeLimit: {
-        [key in Fiat]: number;
-    };
     additionalBuyOrderLiquidityUSD?: number;
     additionalSellOrderLiquidityUSD?: number;
     previousDayUSDMXNConversionRate?: number;
@@ -140,7 +128,7 @@ interface RioSettingsDoc extends mongoose.Document {
             };
         };
     };
-    fxExecutionThreshold: number;
+    fxTradingPolicies?: FXTradingPolicies;
     activeFiatPaymentProcessors: {
         [Side.Buy]: Processor[];
         [Side.Sell]: Processor[];

package/build/models/rio-settings.js

@@ -15,12 +15,6 @@ const buildRioSettings = (mongoose) => {
         defaultDeferredPaymentFee: {
             type: Object,
         },
-        buyOrderAutomaticFXTradeLimit: {
-            type: Object,
-        },
-        sellOrderAutomaticFXTradeLimit: {
-            type: Object,
-        },
         isAfterHours: {
             type: Object,
         },
@@ -48,8 +42,8 @@ const buildRioSettings = (mongoose) => {
         fxProviders: {
             type: Object,
         },
-        fxExecutionThreshold: {
-            type: Number,
+        fxTradingPolicies: {
+            type: Object,
         },
         defaultServiceFee: {
             type: Object,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riocrypto/common-server",
-  "version": "1.0.2782",
+  "version": "1.0.2783",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -24,7 +24,7 @@
     "@google-cloud/secret-manager": "^5.6.0",
     "@google-cloud/storage": "^7.19.0",
     "@hyperdx/node-opentelemetry": "^0.10.3",
-    "@riocrypto/common": "1.0.2584",
+    "@riocrypto/common": "1.0.2587",
     "@slack/web-api": "^7.15.0",
     "@types/express": "^4.17.25",
     "axios": "1.13.6",