@riocrypto/common 1.0.2584 → 1.0.2587

package/build/events/rio-settings-updated-event.d.ts

@@ -2,6 +2,7 @@ import { Country } from "../types/country";
 import { DeferredPaymentType } from "../types/deferred-payment-type";
 import { Fiat } from "../types/fiat";
 import { FXProvider } from "../types/fx-provider";
+import { FXTradingPolicies } from "../types/fx-trading-policy";
 import { Processor } from "../types/processor";
 import { Side } from "../types/side";
 import { TVFXDataProvider } from "../types/TV-FX-data-provider";
@@ -24,12 +25,6 @@ export interface RioSettingsUpdatedEvent {
                 frozen: boolean;
             };
         };
-        buyOrderAutomaticFXTradeLimit?: {
-            [key: string]: number;
-        };
-        sellOrderAutomaticFXTradeLimit?: {
-            [key: string]: number;
-        };
         buyOrderAfterHoursExchangeRateMarkup?: {
             [key: string]: number;
         };
@@ -54,7 +49,7 @@ export interface RioSettingsUpdatedEvent {
                 };
             };
         };
-        fxExecutionThreshold?: number;
+        fxTradingPolicies?: FXTradingPolicies;
         defaultServiceFee?: {
             [key in Country]?: {
                 [key in Side]?: number;

package/build/helpers/get-country-for-fiat.d.ts

@@ -0,0 +1,11 @@
+import { Country } from "../types/country";
+import { Fiat } from "../types/fiat";
+/**
+ * Returns the primary country whose local timezone "owns" a given
+ * fiat. Used by the FX trading-policy resolver to evaluate time-of-day
+ * windows in the currency's natural local time.
+ *
+ * This is intentionally a 1:1 mapping; there's no concept of a fiat
+ * being shared across multiple jurisdictions in our system today.
+ */
+export declare const getCountryForFiat: (fiat: Fiat) => Country;

package/build/helpers/get-country-for-fiat.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCountryForFiat = void 0;
+const country_1 = require("../types/country");
+const fiat_1 = require("../types/fiat");
+/**
+ * Returns the primary country whose local timezone "owns" a given
+ * fiat. Used by the FX trading-policy resolver to evaluate time-of-day
+ * windows in the currency's natural local time.
+ *
+ * This is intentionally a 1:1 mapping; there's no concept of a fiat
+ * being shared across multiple jurisdictions in our system today.
+ */
+const getCountryForFiat = (fiat) => {
+    switch (fiat) {
+        case fiat_1.Fiat.MXN:
+            return country_1.Country.Mexico;
+        case fiat_1.Fiat.PEN:
+            return country_1.Country.Peru;
+        case fiat_1.Fiat.COP:
+            return country_1.Country.Colombia;
+        case fiat_1.Fiat.USD:
+            return country_1.Country.UnitedStates;
+        default:
+            throw new Error(`Unsupported fiat: ${fiat}`);
+    }
+};
+exports.getCountryForFiat = getCountryForFiat;

package/build/index.d.ts

@@ -387,6 +387,7 @@ export * from "./types/arbitrage-asset";
 export * from "./types/arbitrage-frequency";
 export * from "./types/arbitrage-provider";
 export * from "./types/fx-provider";
+export * from "./types/fx-trading-policy";
 export * from "./types/liquidity-automation-frequency";
 export * from "./types/liquidity-automation";
 export * from "./types/liquidity-automation-type";
@@ -538,6 +539,7 @@ export * from "./helpers/is-overnight-or-weekend-mexico-city";
 export * from "./helpers/get-user-payout-vault-id";
 export * from "./helpers/should-add-one-day-to-settlement-date";
 export * from "./helpers/get-country-timezone";
+export * from "./helpers/get-country-for-fiat";
 export * from "./helpers/get-days-between-agreed-two-way-settlement-date-and-payment-date";
 export * from "./helpers/get-days-until-two-way-settlement-date";
 export * from "./helpers/get-two-way-settlement-date-offset-from-date";

package/build/index.js

@@ -403,6 +403,7 @@ __exportStar(require("./types/arbitrage-asset"), exports);
 __exportStar(require("./types/arbitrage-frequency"), exports);
 __exportStar(require("./types/arbitrage-provider"), exports);
 __exportStar(require("./types/fx-provider"), exports);
+__exportStar(require("./types/fx-trading-policy"), exports);
 __exportStar(require("./types/liquidity-automation-frequency"), exports);
 __exportStar(require("./types/liquidity-automation"), exports);
 __exportStar(require("./types/liquidity-automation-type"), exports);
@@ -554,6 +555,7 @@ __exportStar(require("./helpers/is-overnight-or-weekend-mexico-city"), exports);
 __exportStar(require("./helpers/get-user-payout-vault-id"), exports);
 __exportStar(require("./helpers/should-add-one-day-to-settlement-date"), exports);
 __exportStar(require("./helpers/get-country-timezone"), exports);
+__exportStar(require("./helpers/get-country-for-fiat"), exports);
 __exportStar(require("./helpers/get-days-between-agreed-two-way-settlement-date-and-payment-date"), exports);
 __exportStar(require("./helpers/get-days-until-two-way-settlement-date"), exports);
 __exportStar(require("./helpers/get-two-way-settlement-date-offset-from-date"), exports);

package/build/types/fx-trading-policy.d.ts

@@ -0,0 +1,123 @@
+import { Fiat } from "./fiat";
+import { FXProvider } from "./fx-provider";
+import { Side } from "./side";
+/**
+ * One amount band within a (fiat, settlement offset, side) policy.
+ *
+ * The band is interpreted as `[minAmount, maxAmount)` in the policy's fiat.
+ * Both bounds are required and finite. Operators that want a "catch-all
+ * upper tail" set `maxAmount` to a value larger than any plausible single
+ * trade for that fiat (e.g. 1,000,000,000) rather than leaving it
+ * unbounded - this avoids accidentally routing arbitrary-size trades
+ * through automation just because no upper bound was specified.
+ *
+ * `automatic` is only meaningful for providers that support a cosigner
+ * approval workflow (Emarkets, Transnetwork, StoneX). For Matching / Other
+ * the runtime always treats this band as automatic regardless of the
+ * stored value.
+ */
+export interface FXTradingPolicyAmountRange {
+    minAmount: number;
+    maxAmount: number;
+    provider: FXProvider;
+    automatic: boolean;
+}
+/**
+ * One time-of-day window within a (fiat, settlement offset, side) policy.
+ *
+ * Times are minutes from midnight in the currency's country-local
+ * timezone, interpreted as `[startMinute, endMinute)`. The full set of
+ * windows must be contiguous and cover `[0, 1440)` (midnight to
+ * midnight) so every moment of the day maps to exactly one window. A
+ * window that needs to span midnight (e.g. an "after-hours" 22:00-06:00
+ * gate) is split into two rows with identical inner configuration.
+ *
+ * `executionThresholdMs` is the milliseconds an FX trade can dwell in
+ * PendingExecutionThreshold before checkExecutionThreshold transitions
+ * it for placement. It is per-time-window so operators can specify
+ * a different aggregation behavior during the day vs at night.
+ * Re-evaluated against the current time at every step in the trade's
+ * lifecycle (initial creation, cron sweep). A trade created during a
+ * 30s-aggregation window may sit in PendingExecutionThreshold; when the
+ * window flips to 0ms the next cron tick dispatches the trade.
+ *
+ * `byAmountRange` is the amount-range table that applies while this
+ * time window is active. First range starts at 0, ranges are ordered
+ * and strictly contiguous, and every range (including the last) has an
+ * explicit, finite `maxAmount`. Trades whose amount falls above the
+ * last range's cap fall through to the safe Other/manual fallback.
+ */
+export interface FXTradingPolicyTimeRange {
+    startMinute: number;
+    endMinute: number;
+    executionThresholdMs: number;
+    byAmountRange: FXTradingPolicyAmountRange[];
+}
+/**
+ * Per-(fiat, settlement offset, side) trading rules.
+ *
+ * `byTimeRange` is the ordered list of time windows that govern routing
+ * and aggregation across a 24-hour day in the currency's country-local
+ * timezone. The resolver picks the window containing "now" and then
+ * uses that window's `executionThresholdMs` and `byAmountRange`.
+ */
+export interface FXTradingSidePolicy {
+    byTimeRange: FXTradingPolicyTimeRange[];
+}
+export interface FXTradingPolicyBySide {
+    [Side.Buy]?: FXTradingSidePolicy;
+    [Side.Sell]?: FXTradingSidePolicy;
+}
+/**
+ * `default` applies whenever `byOffset[offset]` is not set for the
+ * requested (fiat, side). `byOffset` keys are stored as strings in Mongo
+ * (object property names) but always represent non-negative integer
+ * `twoWaySettlementDateOffset` values.
+ *
+ * Override semantics are all-or-nothing per side: if `byOffset[3].buy` is
+ * defined it fully replaces `default.buy` for offset 3 buy trades; nothing
+ * is merged field-by-field. Offsets that have no override fall back to
+ * `default` regardless of how distant they are from any configured
+ * override.
+ */
+export interface FXTradingPoliciesForFiat {
+    default: FXTradingPolicyBySide;
+    byOffset?: {
+        [offset: number]: FXTradingPolicyBySide;
+    };
+}
+export type FXTradingPolicies = {
+    [key in Fiat]?: FXTradingPoliciesForFiat;
+};
+/**
+ * Result of resolving a (policy, amount) pair: the provider that should
+ * handle the trade and whether placement is automatic. Callers that need
+ * to know how the trade should be staged (Trading vs PendingApproval vs
+ * Completed) derive that from `{ provider, automatic }`.
+ *
+ * The runtime resolver (`resolveFXProviderForAmount` in common-server)
+ * returns `ResolvedFXPlacement` which adds the time-window-matched
+ * `executionThresholdMs`. Callers that only need to map a placement to
+ * the next FX-trade status (e.g. cosigner-notification, alternative
+ * approval) build a synthetic `ResolvedFXProvider` because the
+ * threshold is irrelevant to that decision.
+ */
+export interface ResolvedFXProvider {
+    provider: FXProvider;
+    automatic: boolean;
+}
+/**
+ * Full output of `resolveFXProviderForAmount`. Adds the time-window's
+ * `executionThresholdMs` so callers (cron sweep, order-created
+ * listener) can decide whether to put the trade in
+ * PendingExecutionThreshold for aggregation or dispatch immediately.
+ *
+ * The threshold reflects the *current* time-of-day window in the
+ * currency's country-local timezone. Callers that retain a trade in
+ * PendingExecutionThreshold across a window boundary must re-resolve
+ * the threshold at sweep time - the rules of the now-active window
+ * apply, not the rules at creation time.
+ */
+export interface ResolvedFXPlacement extends ResolvedFXProvider {
+    executionThresholdMs: number;
+}

package/build/types/fx-trading-policy.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const side_1 = require("./side");

package/build/types/rio-settings-update.d.ts

@@ -1,6 +1,7 @@
 import { Country } from "./country";
 import { Fiat } from "./fiat";
 import { FXProvider } from "./fx-provider";
+import { FXTradingPolicies } from "./fx-trading-policy";
 import { Processor } from "./processor";
 import { Side } from "./side";
 import { TVFXDataProvider } from "./TV-FX-data-provider";
@@ -9,12 +10,6 @@ export interface RioSettingsUpdate {
     afterHoursExchangeRateMarkup?: {
         [key: string]: number;
     };
-    buyOrderAutomaticFXTradeLimit?: {
-        [key: string]: number;
-    };
-    sellOrderAutomaticFXTradeLimit?: {
-        [key: string]: number;
-    };
     buyOrderAfterHoursExchangeRateMarkup?: {
         [key: string]: number;
     };
@@ -41,7 +36,7 @@ export interface RioSettingsUpdate {
             enabled: boolean;
         };
     };
-    fxExecutionThreshold?: number;
+    fxTradingPolicies?: FXTradingPolicies;
     defaultServiceFee?: {
         [key in Country]?: {
             [key in Side]?: number;

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

@@ -3,6 +3,7 @@ import { DeferredPaymentType } from "./deferred-payment-type";
 import { EmarketsSettlementType } from "./emarkets-settlement-type";
 import { Fiat } from "./fiat";
 import { FXProvider } from "./fx-provider";
+import { FXTradingPolicies } from "./fx-trading-policy";
 import { Processor } from "./processor";
 import { TransnetworkSettlementType } from "./transnetwork-settlement-type";
 import { Side } from "./side";
@@ -23,12 +24,6 @@ export interface RioSettings {
             frozen: boolean;
         };
     };
-    buyOrderAutomaticFXTradeLimit: {
-        [key: string]: number;
-    };
-    sellOrderAutomaticFXTradeLimit: {
-        [key: string]: number;
-    };
     buyOrderAfterHoursExchangeRateMarkup: {
         [key: string]: number;
     };
@@ -53,7 +48,14 @@ export interface RioSettings {
             };
         };
     };
-    fxExecutionThreshold: number;
+    /**
+     * Per-(fiat, settlement offset, side) FX trading policies. Each side
+     * policy carries its own executionThresholdMs and an ordered list of
+     * amount ranges that map onto a provider and an automatic-vs-cosigner
+     * flag. Resolution is offset-aware: byOffset wins if set, otherwise
+     * default applies. See FXTradingSidePolicy for override semantics.
+     */
+    fxTradingPolicies?: FXTradingPolicies;
     defaultServiceFee: {
         [key in Country]?: {
             [key in Side]?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riocrypto/common",
-  "version": "1.0.2584",
+  "version": "1.0.2587",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",