@riocrypto/common-server 1.0.2889 → 1.0.2892

package/build/helpers/get-processor.d.ts

@@ -1,12 +1,17 @@
-import { Country, Fiat, Processor, ProcessorRoutingConfig, Side } from "@riocrypto/common";
-export declare const getProcessor: ({ country, fiat, side, isBinanceRFQ, routingConfig, disabledProcessors, customRioBankAccount, }: {
+import { Country, Fiat, Processor, ProcessorEnablementState, ProcessorRoutingConfig, ProcessorRoutingPurpose, RoutingDecision, Side } from "@riocrypto/common";
+export declare const getEnvironmentExcludedProcessors: (purpose: ProcessorRoutingPurpose) => Processor[];
+export type ProcessorSelection = RoutingDecision & {
+    processor: Processor;
+};
+export declare const getProcessor: ({ country, fiat, side, isBinanceRFQ, routingConfig, enablement, requireExplicitPayinEnablement, customRioBankAccount, }: {
     country: Country;
     fiat: Fiat;
     side: Side;
     isBinanceRFQ: boolean;
     routingConfig?: ProcessorRoutingConfig | undefined;
-    disabledProcessors?: Processor[] | undefined;
+    enablement?: ProcessorEnablementState | undefined;
+    requireExplicitPayinEnablement?: boolean | undefined;
     customRioBankAccount?: {
         processor?: Processor | undefined;
     } | undefined;
-}) => Processor;
+}) => ProcessorSelection;

package/build/helpers/get-processor.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getProcessor = void 0;
+exports.getProcessor = exports.getEnvironmentExcludedProcessors = void 0;
 const common_1 = require("@riocrypto/common");
 const resolve_processor_1 = require("./resolve-processor");
 // Alfin takes effect only in Production (Alfin prod). In every other
@@ -18,22 +18,33 @@ const isAlfinEnabled = () => [common_1.RioEnv.Production].includes(process.env.R
 const isSTPAvailable = (purpose) => (purpose === common_1.ProcessorRoutingPurpose.Buy
     ? [common_1.RioEnv.Production]
     : [common_1.RioEnv.Production, common_1.RioEnv.Development]).includes(process.env.RIO_ENV);
-const getProcessor = ({ country, fiat, side, isBinanceRFQ, routingConfig, disabledProcessors, customRioBankAccount, }) => {
+// Rails this deployment cannot reach for a purpose, whatever the settings say.
+// Exported because seeding a customer's first payin account has to make the same
+// call: handing someone an account that only exists in production would look like
+// opt-in having locked them out.
+const getEnvironmentExcludedProcessors = (purpose) => [
+    ...(isAlfinEnabled() ? [] : [common_1.Processor.Alfin]),
+    ...(isSTPAvailable(purpose) ? [] : [common_1.Processor.SPEI_STP]),
+];
+exports.getEnvironmentExcludedProcessors = getEnvironmentExcludedProcessors;
+const getProcessor = ({ country, fiat, side, isBinanceRFQ, routingConfig, enablement, requireExplicitPayinEnablement, customRioBankAccount, }) => {
     if (isBinanceRFQ === true) {
-        return common_1.Processor.BinanceRFQ;
+        return {
+            processor: common_1.Processor.BinanceRFQ,
+            reason: common_1.RoutingDecisionReason.Structural,
+            corridor: [common_1.Processor.BinanceRFQ],
+            decidedAt: new Date(),
+        };
     }
     const purpose = side === common_1.Side.Buy
         ? common_1.ProcessorRoutingPurpose.Buy
         : common_1.ProcessorRoutingPurpose.Sell;
-    const excludedProcessors = [
-        ...(isAlfinEnabled() ? [] : [common_1.Processor.Alfin]),
-        ...(isSTPAvailable(purpose) ? [] : [common_1.Processor.SPEI_STP]),
-    ];
+    const excludedProcessors = (0, exports.getEnvironmentExcludedProcessors)(purpose);
     // Applied only inside the branches that genuinely have more than one rail, so
     // a stray rule cannot hijack structural routing (COP, USD in the US or Mexico)
     // or bypass the country checks below. Answers even when no rule is configured,
     // because the corridor default is only safe to use once the rails the customer
-    // has switched off are out of the running. Undefined is left for the one case
+    // will not accept are out of the running. Undefined is left for the one case
     // that genuinely belongs to structural routing: a custom Rio bank account whose
     // rail we do not know.
     const trySplit = () => {
@@ -43,24 +54,30 @@ const getProcessor = ({ country, fiat, side, isBinanceRFQ, routingConfig, disabl
             purpose,
             routingConfig,
             excludedProcessors,
-            disabledProcessors,
+            enablement,
+            requireExplicitEnablement: requireExplicitPayinEnablement,
             customRioBankAccount,
         });
         if (routed.processor) {
-            return routed.processor;
+            return Object.assign(Object.assign({}, routed), { processor: routed.processor });
+        }
+        // The customer has never told us which of these accounts their bank will let
+        // them pay, so there is nothing to route to. Says so in their terms, since
+        // the fix is theirs to make rather than something support has to escalate.
+        if (routed.reason === common_1.RoutingDecisionReason.NoAcceptedCandidate) {
+            throw new common_1.GenericInputError("You need to turn on a payment account for this currency before you can buy. You can do that from the payment accounts page, once your bank allows transfers to it.");
         }
         // Every rail in this corridor is switched off for this direction, so there is
         // nowhere to send them - a rail at zero percent would still have taken the
-        // order. Says so specifically, and names where to fix it, since the fix is
-        // theirs to make rather than something support has to escalate.
-        if (routed.reason === "noEnabledCandidate") {
+        // order. Says so specifically, and names where to fix it.
+        if (routed.reason === common_1.RoutingDecisionReason.NoEnabledCandidate) {
             throw new common_1.GenericInputError(side === common_1.Side.Buy
                 ? "You need to enable a payment account for this currency before you can buy. You can turn one back on from the payment accounts page."
                 : "You need to enable a payout account for this currency before you can sell. You can turn one back on from the payout accounts page.");
         }
         // No rail in the corridor can be reached in this environment at all, which is
         // a deployment fact rather than anything the customer can act on.
-        if (routed.reason === "noEligibleCandidate") {
+        if (routed.reason === common_1.RoutingDecisionReason.NoEligibleCandidate) {
             throw new common_1.GenericInputError("No payment processor is currently available for this order");
         }
         return undefined;
@@ -75,7 +92,13 @@ const getProcessor = ({ country, fiat, side, isBinanceRFQ, routingConfig, disabl
         if (!fallback) {
             throw new common_1.GenericInputError("No payment processor is configured for this currency");
         }
-        return fallback;
+        return {
+            processor: fallback,
+            reason: common_1.RoutingDecisionReason.Structural,
+            corridor: (0, common_1.getProcessorsForCorridor)(country, fiat, purpose),
+            excluded: excludedProcessors,
+            decidedAt: new Date(),
+        };
     };
     if (fiat === common_1.Fiat.COP) {
         if (country === common_1.Country.Colombia) {

package/build/helpers/payin-destinations.d.ts

@@ -50,11 +50,12 @@ export interface PayinDestination {
     isEnabled: boolean;
     readinessStatus?: ProcessorReadinessStatus;
 }
-export declare const getPayinDestinations: ({ mongoose, user, country, fiat, processors, provision, }: {
+export declare const getPayinDestinations: ({ mongoose, user, country, fiat, processors, provision, requireExplicitEnablement, }: {
     mongoose: Mongoose;
     user: User;
     country: Country;
     fiat: Fiat;
     processors: Processor[];
     provision?: boolean | undefined;
+    requireExplicitEnablement?: boolean | undefined;
 }) => Promise<PayinDestination[]>;

package/build/helpers/payin-destinations.js

@@ -17,6 +17,7 @@ const fintoc_deposit_CLABE_1 = require("../models/fintoc-deposit-CLABE");
 const alfin_virtual_cci_1 = require("../models/alfin-virtual-cci");
 const processor_readiness_1 = require("../models/processor-readiness");
 const cluster_client_1 = require("../clients/cluster-client");
+const processor_enablement_1 = require("./processor-enablement");
 // Rails that give each user their own destination, which therefore has to exist
 // before we can tell a customer where to pay. Every other rail is a shared house
 // account that is always available.
@@ -288,7 +289,7 @@ exports.getPayinBankDetails = getPayinBankDetails;
 // that tells them what to whitelist at their bank. Read-only by default so that
 // viewing the list never allocates anything at a provider; pass `provision` to
 // create the destinations that do not exist yet.
-const getPayinDestinations = ({ mongoose, user, country, fiat, processors, provision = false, }) => __awaiter(void 0, void 0, void 0, function* () {
+const getPayinDestinations = ({ mongoose, user, country, fiat, processors, provision = false, requireExplicitEnablement, }) => __awaiter(void 0, void 0, void 0, function* () {
     var _d, _e;
     const ProcessorReadiness = (0, processor_readiness_1.buildProcessorReadiness)(mongoose);
     const readiness = yield ProcessorReadiness.find({
@@ -300,9 +301,12 @@ const getPayinDestinations = ({ mongoose, user, country, fiat, processors, provi
         .lean();
     const readinessByProcessor = new Map(readiness.map((record) => [record.processor, record]));
     const isEnabled = (processor) => {
-        var _a, _b, _c;
-        return ((_c = (_b = (_a = readinessByProcessor.get(processor)) === null || _a === void 0 ? void 0 : _a.enablement) === null || _b === void 0 ? void 0 : _b[common_1.Side.Buy]) === null || _c === void 0 ? void 0 : _c.isEnabled) !==
-            false;
+        var _a;
+        return (0, processor_enablement_1.isProcessorEnabled)({
+            enablement: (_a = readinessByProcessor.get(processor)) === null || _a === void 0 ? void 0 : _a.enablement,
+            side: common_1.Side.Buy,
+            requireExplicitEnablement,
+        });
     };
     const destinations = [];
     for (const processor of processors) {

package/build/helpers/payin-verification.js

@@ -53,10 +53,11 @@ exports.extractTestReference = extractTestReference;
 // arrives. Deliberately does not touch an already-verified record - there is
 // nothing left to prove.
 //
-// Proving a rail works does not switch it on, and never switching it on does not
-// stop it being used: enablement is the customer's own decision and lives on the
-// same record under enablement. A test is how they find out a rail works before an
-// order depends on it, not how they get access to it.
+// Passing the test does switch the rail on for buys, when the customer has not
+// already said either way. Sending us the deposit is their bank demonstrating the
+// transfer is allowed, which is the same thing the toggle asserts, so asking for
+// both would be asking them to confirm what we just watched happen. It never
+// overrides a rail they have deliberately switched off.
 //
 // The token does not expire. Whitelisting an account at a bank can take days of
 // back and forth at the customer's end, and expiring the token in the middle of
@@ -144,6 +145,20 @@ const matchPendingPayinVerification = ({ mongoose, reference, amount, fiat, proc
         if (!matched) {
             return undefined;
         }
+        // Left out of the transition above so that a failure here cannot cost us the
+        // verification itself, which is the part that must not be repeated. A rail
+        // switched off keeps its answer, and one already on is not restamped.
+        yield ProcessorReadiness.updateOne({
+            _id: matched._id,
+            [`enablement.${common_1.Side.Buy}`]: { $exists: false },
+        }, {
+            $set: {
+                [`enablement.${common_1.Side.Buy}`]: {
+                    isEnabled: true,
+                    updatedAt: new Date(),
+                },
+            },
+        });
         return {
             userId: matched.userId,
             country: matched.country,

package/build/helpers/processor-enablement.d.ts

@@ -1,13 +1,25 @@
-import { Country, Fiat, Processor, Side } from "@riocrypto/common";
+import { Country, Fiat, Processor, ProcessorEnablementState, Side } from "@riocrypto/common";
 import { Mongoose } from "mongoose";
-export declare const getDisabledProcessors: ({ mongoose, userId, country, fiat, side, }: {
+export declare const isProcessorEnabled: ({ enablement, side, requireExplicitEnablement, }: {
+    enablement?: {
+        buy?: {
+            isEnabled: boolean;
+        } | undefined;
+        sell?: {
+            isEnabled: boolean;
+        } | undefined;
+    } | undefined;
+    side: Side;
+    requireExplicitEnablement?: boolean | undefined;
+}) => boolean;
+export declare const getProcessorEnablementState: ({ mongoose, userId, country, fiat, side, }: {
     mongoose: Mongoose;
     userId: string;
     country: Country;
     fiat: Fiat;
     side: Side;
-}) => Promise<Processor[]>;
-export declare const setProcessorEnablement: ({ mongoose, userId, country, fiat, side, processor, isEnabled, adminId, }: {
+}) => Promise<ProcessorEnablementState>;
+export declare const setProcessorEnablement: ({ mongoose, userId, country, fiat, side, processor, isEnabled, adminId, requireExplicitEnablement, }: {
     mongoose: Mongoose;
     userId: string;
     country: Country;
@@ -16,4 +28,11 @@ export declare const setProcessorEnablement: ({ mongoose, userId, country, fiat,
     processor: Processor;
     isEnabled: boolean;
     adminId?: string | undefined;
+    requireExplicitEnablement?: boolean | undefined;
 }) => Promise<void>;
+export declare const ensureDefaultPayinEnablement: ({ mongoose, userId, country, fiat, }: {
+    mongoose: Mongoose;
+    userId: string;
+    country: Country;
+    fiat: Fiat;
+}) => Promise<Processor | undefined>;

package/build/helpers/processor-enablement.js

@@ -9,34 +9,69 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setProcessorEnablement = exports.getDisabledProcessors = void 0;
+exports.ensureDefaultPayinEnablement = exports.setProcessorEnablement = exports.getProcessorEnablementState = exports.isProcessorEnabled = void 0;
 const common_1 = require("@riocrypto/common");
 const processor_readiness_1 = require("../models/processor-readiness");
+const get_processor_1 = require("./get-processor");
 // Enablement is asked per side, so the purpose is fixed by the direction rather
 // than chosen by the caller: verifications are ours to place and are never gated.
 const getPurpose = (side) => side === common_1.Side.Buy
     ? common_1.ProcessorRoutingPurpose.Buy
     : common_1.ProcessorRoutingPurpose.Sell;
-// Rails the user has switched off for one corridor and one direction, which order
-// routing skips. On a buy that means a rail their bank will not let them send
-// money to; on a sell, one it will not accept credits from.
+// Whether one rail may carry one customer's orders in one direction.
 //
-// Only explicit refusals count. A rail with no record is enabled, which is what
-// keeps a customer who has never opened their account settings trading exactly as
-// they did before.
-const getDisabledProcessors = ({ mongoose, userId, country, fiat, side, }) => __awaiter(void 0, void 0, void 0, function* () {
+// The two directions disagree about silence, which is the whole point. A payout
+// needs nothing arranged at the customer's bank, so a rail nobody has spoken
+// about can pay them. A payin asks them to send money to an account their bank
+// has to allow first, so silence means no while payin accounts are opt-in.
+const isProcessorEnabled = ({ enablement, side, requireExplicitEnablement, }) => {
+    var _a, _b;
+    return (_b = (_a = enablement === null || enablement === void 0 ? void 0 : enablement[side]) === null || _a === void 0 ? void 0 : _a.isEnabled) !== null && _b !== void 0 ? _b : (side === common_1.Side.Sell || !requireExplicitEnablement);
+};
+exports.isProcessorEnabled = isProcessorEnabled;
+// What a customer has said about each rail in one corridor and one direction.
+//
+// Reports the three sets rather than a verdict so that the policy lives in one
+// place, in routing, instead of being decided here and again wherever a page
+// needs to show the same thing. Only rails the corridor currently serves are
+// reported, so a record left behind by a rail we no longer route to is ignored
+// rather than resurrected.
+const getProcessorEnablementState = ({ mongoose, userId, country, fiat, side, }) => __awaiter(void 0, void 0, void 0, function* () {
     const ProcessorReadiness = (0, processor_readiness_1.buildProcessorReadiness)(mongoose);
-    const readiness = yield ProcessorReadiness.find({
+    const records = yield ProcessorReadiness.find({
         userId,
         country,
         fiat,
-        [`enablement.${side}.isEnabled`]: false,
     })
-        .select({ processor: 1 })
+        .select({ processor: 1, enablement: 1 })
         .lean();
-    return readiness.map((record) => record.processor);
+    const stated = new Map(records.map((record) => {
+        var _a, _b;
+        return [
+            record.processor,
+            (_b = (_a = record.enablement) === null || _a === void 0 ? void 0 : _a[side]) === null || _b === void 0 ? void 0 : _b.isEnabled,
+        ];
+    }));
+    const state = {
+        enabled: [],
+        disabled: [],
+        unset: [],
+    };
+    for (const processor of (0, common_1.getProcessorsForCorridor)(country, fiat, getPurpose(side))) {
+        const isEnabled = stated.get(processor);
+        if (isEnabled === true) {
+            state.enabled.push(processor);
+        }
+        else if (isEnabled === false) {
+            state.disabled.push(processor);
+        }
+        else {
+            state.unset.push(processor);
+        }
+    }
+    return state;
 });
-exports.getDisabledProcessors = getDisabledProcessors;
+exports.getProcessorEnablementState = getProcessorEnablementState;
 // Turns a rail on or off for one user in one direction, which is what order
 // routing gates on. Deliberately says nothing about verification: a customer can
 // enable a rail they have never tested, and switching one off leaves its test
@@ -44,8 +79,9 @@ exports.getDisabledProcessors = getDisabledProcessors;
 //
 // Refuses to switch off the last rail standing. Enabling nothing means we have
 // nowhere to send their money, and finding that out when they try to place an
-// order is worse than being told here.
-const setProcessorEnablement = ({ mongoose, userId, country, fiat, side, processor, isEnabled, adminId, }) => __awaiter(void 0, void 0, void 0, function* () {
+// order is worse than being told here. Turning another on first is always open to
+// them, so nobody is stuck with a rail they cannot use.
+const setProcessorEnablement = ({ mongoose, userId, country, fiat, side, processor, isEnabled, adminId, requireExplicitEnablement, }) => __awaiter(void 0, void 0, void 0, function* () {
     const corridorProcessors = (0, common_1.getProcessorsForCorridor)(country, fiat, getPurpose(side));
     if (!corridorProcessors.includes(processor)) {
         throw new common_1.GenericInputError(side === common_1.Side.Buy
@@ -53,15 +89,18 @@ const setProcessorEnablement = ({ mongoose, userId, country, fiat, side, process
             : "This payout rail is not available for this country and currency");
     }
     if (!isEnabled) {
-        const disabled = yield (0, exports.getDisabledProcessors)({
+        const state = yield (0, exports.getProcessorEnablementState)({
             mongoose,
             userId,
             country,
             fiat,
             side,
         });
-        const stillEnabled = corridorProcessors.filter((candidate) => candidate !== processor && !disabled.includes(candidate));
-        if (!stillEnabled.length) {
+        const stillUsable = [
+            ...state.enabled,
+            ...(side === common_1.Side.Sell || !requireExplicitEnablement ? state.unset : []),
+        ].filter((candidate) => candidate !== processor);
+        if (!stillUsable.length) {
             throw new common_1.GenericInputError(side === common_1.Side.Buy
                 ? "At least one payment account has to stay enabled for this currency, otherwise there is nowhere to send your orders"
                 : "At least one payout account has to stay enabled for this currency, otherwise there is nowhere to pay your orders from");
@@ -85,3 +124,49 @@ const setProcessorEnablement = ({ mongoose, userId, country, fiat, side, process
     }, { upsert: true });
 });
 exports.setProcessorEnablement = setProcessorEnablement;
+// Gives a customer with no payin account turned on the one their corridor would
+// have routed them to anyway, so opt-in never leaves somebody unable to be
+// quoted. Called when an onboarding is approved, and by the backfill for accounts
+// that predate all of this.
+//
+// Skips anyone who has already turned a rail on, because their answer is better
+// than our guess and adding to it would put their money somewhere they have not
+// agreed to. Where the default rail is one they have switched off, it falls to
+// the corridor's own order, which is the rail routing would have picked for them
+// before opt-in existed. Returns the rail it turned on, or nothing if it left
+// them alone.
+const ensureDefaultPayinEnablement = ({ mongoose, userId, country, fiat, }) => __awaiter(void 0, void 0, void 0, function* () {
+    const state = yield (0, exports.getProcessorEnablementState)({
+        mongoose,
+        userId,
+        country,
+        fiat,
+        side: common_1.Side.Buy,
+    });
+    if (state.enabled.length) {
+        return undefined;
+    }
+    // Environment exclusions are honoured here rather than left to routing, since
+    // seeding a rail this deployment cannot reach would hand the customer an
+    // account nothing can route to and read as opt-in having blocked them.
+    const unreachable = [
+        ...(0, get_processor_1.getEnvironmentExcludedProcessors)(common_1.ProcessorRoutingPurpose.Buy),
+        ...state.disabled,
+    ];
+    const seed = (0, common_1.getDefaultProcessor)(country, fiat, common_1.ProcessorRoutingPurpose.Buy, unreachable) ||
+        state.unset.find((candidate) => !unreachable.includes(candidate));
+    if (!seed || !state.unset.includes(seed)) {
+        return undefined;
+    }
+    yield (0, exports.setProcessorEnablement)({
+        mongoose,
+        userId,
+        country,
+        fiat,
+        side: common_1.Side.Buy,
+        processor: seed,
+        isEnabled: true,
+    });
+    return seed;
+});
+exports.ensureDefaultPayinEnablement = ensureDefaultPayinEnablement;

package/build/helpers/record-observed-processor-readiness.js

@@ -22,16 +22,38 @@ const DUPLICATE_KEY_ERROR_CODE = 11000;
 // penny test, because it is a real payment at real size. Called from the payment
 // matching paths so the record stays current without anyone maintaining it.
 //
-// Only touches verification. A rail the customer has switched off stays off even
-// if a payment turns up on it, because the account they cannot send to next month
-// is not made usable by one that arrived this month.
+// Also turns the rail on for buys when the customer has never said either way,
+// which is what keeps opt-in from needing a second migration. A payin arriving is
+// their bank demonstrating the transfer is allowed, so asking them to also flip a
+// switch would be asking them to confirm something we just watched happen.
 //
-// Never downgrades an existing verified record: an admin override stays
-// attributed to the admin who granted it.
+// Never overrides an explicit answer in either direction. A rail the customer
+// switched off stays off even if a payment turns up on it, because the account
+// they cannot send to next month is not made usable by one that arrived this
+// month, and a verified record keeps the admin attribution it was granted with.
 const recordObservedProcessorReadiness = ({ mongoose, userId, country, fiat, processor, CLABE, }) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const ProcessorReadiness = (0, processor_readiness_1.buildProcessorReadiness)(mongoose);
     try {
+        const enablement = {
+            isEnabled: true,
+            updatedAt: new Date(),
+        };
+        // Separate from the write below because the two have different conditions.
+        // Verification is skipped once verified, while enablement is skipped once the
+        // customer has answered, and folding them together would let one already
+        // satisfied condition suppress the other.
+        yield ProcessorReadiness.updateOne({
+            userId,
+            country,
+            fiat,
+            processor,
+            [`enablement.${common_1.Side.Buy}`]: { $exists: false },
+        }, {
+            $set: {
+                [`enablement.${common_1.Side.Buy}`]: enablement,
+            },
+        });
         yield ProcessorReadiness.updateOne({
             userId,
             country,
@@ -46,6 +68,9 @@ const recordObservedProcessorReadiness = ({ mongoose, userId, country, fiat, pro
                 country,
                 fiat,
                 processor,
+                // The write above cannot reach a record that does not exist yet, and
+                // this one creates it.
+                [`enablement.${common_1.Side.Buy}`]: enablement,
             },
         }, { upsert: true });
     }

package/build/helpers/resolve-processor.d.ts

@@ -1,18 +1,16 @@
-import { Country, Fiat, Processor, ProcessorRoutingConfig, ProcessorRoutingPurpose } from "@riocrypto/common";
+import { Country, Fiat, Processor, ProcessorEnablementState, ProcessorRoutingConfig, ProcessorRoutingPurpose, RoutingDecision } from "@riocrypto/common";
 export interface ResolveProcessorParams {
     country: Country;
     fiat: Fiat;
     purpose: ProcessorRoutingPurpose;
     routingConfig?: ProcessorRoutingConfig;
     excludedProcessors?: Processor[];
-    disabledProcessors?: Processor[];
+    enablement?: ProcessorEnablementState;
+    requireExplicitEnablement?: boolean;
     customRioBankAccount?: {
         processor?: Processor;
     };
     randomSeed?: number;
 }
-export interface ResolveProcessorResult {
-    processor?: Processor;
-    reason: "customRioBankAccount" | "customRioBankAccountWithoutRail" | "split" | "onlyCandidate" | "enabledRailWithoutShare" | "noEligibleCandidate" | "noEnabledCandidate";
-}
-export declare const resolveProcessor: ({ country, fiat, purpose, routingConfig, excludedProcessors, disabledProcessors, customRioBankAccount, randomSeed, }: ResolveProcessorParams) => ResolveProcessorResult;
+export type ResolveProcessorResult = RoutingDecision;
+export declare const resolveProcessor: ({ country, fiat, purpose, routingConfig, excludedProcessors, enablement, requireExplicitEnablement, customRioBankAccount, randomSeed, }: ResolveProcessorParams) => ResolveProcessorResult;

package/build/helpers/resolve-processor.js

@@ -25,30 +25,28 @@ const pickByShare = (candidates, position) => {
 // A percentage divides volume between the rails that are actually available to
 // the customer; it is not a switch. A rail left at zero, left out of the rule, or
 // belonging to a corridor with no rule at all still takes their orders when it is
-// the only one they have left enabled, which is why the candidate set comes from
-// the corridor rather than from the rule. Switching a rail off is the only way to
-// keep an order away from it.
+// the only one available to them, which is why the candidate set comes from the
+// corridor rather than from the rule. What keeps an order away from a rail is the
+// customer, by switching it off or, on buys, by never turning it on.
 //
-// Does no IO of its own - the routing config and the user's readiness are passed
+// Does no IO of its own - the routing config and the user's enablement are passed
 // in - and the only nondeterminism is the per-order roll, which a caller can
 // pin down by supplying randomSeed. Because the roll happens once, the answer
 // belongs to the record that stores it: anything that needs to know which rail
 // an existing order uses reads it off the order rather than calling again.
 //
+// Returns the sets it filtered as well as the rail, because they are gone by the
+// time anyone asks why. Settings move, a customer turns a rail off, an
+// environment changes, and the question "why did this order go there" is then
+// unanswerable from the order alone.
+//
 // Only handles rails that participate in a split. Structural routing that is not
 // a commercial choice - Binance RFQ, COP, USD in the US or Mexico - stays in
 // getProcessor and never reaches here.
-const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProcessors, disabledProcessors, customRioBankAccount, randomSeed, }) => {
+const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProcessors, enablement, requireExplicitEnablement, customRioBankAccount, randomSeed, }) => {
+    const corridor = (0, common_1.getProcessorsForCorridor)(country, fiat, purpose);
+    const decidedAt = new Date();
     const isEligible = (processor) => !(excludedProcessors === null || excludedProcessors === void 0 ? void 0 : excludedProcessors.includes(processor));
-    // A rail the customer has switched off for this direction is worthless whatever
-    // share it carries: on a buy they cannot send money to it, on a sell their bank
-    // will not accept the credit. Applies to every rail, verifiable or not - a bank
-    // can refuse a wire from Bancrea as easily as a SPEI transfer from Fintoc.
-    //
-    // Verifications are exempt because they are ours to place against an account the
-    // customer gave us, not a rail they have to accept.
-    const isUsable = (processor) => purpose === common_1.ProcessorRoutingPurpose.BankAccountVerification ||
-        !(disabledProcessors === null || disabledProcessors === void 0 ? void 0 : disabledProcessors.includes(processor));
     // A custom Rio bank account outranks everything on buys, because it is where
     // the money physically goes: `getBankDetails` returns it in place of the
     // rail's own destination. Routing the order to a different processor would
@@ -62,16 +60,30 @@ const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProce
         // to the structural path and leave these users exactly as they were until an
         // admin records which rail the account belongs to.
         if (!processor) {
-            return { reason: "customRioBankAccountWithoutRail" };
+            return {
+                reason: common_1.RoutingDecisionReason.CustomRioBankAccountWithoutRail,
+                corridor,
+                decidedAt,
+            };
         }
         // Deliberately fail closed rather than fall through to the split. The payin
         // destination is fixed, so if that rail cannot be used here the only honest
         // options are to refuse the order or to keep sending payins to a provider we
         // have stopped watching.
         if (!isEligible(processor)) {
-            return { reason: "noEligibleCandidate" };
+            return {
+                reason: common_1.RoutingDecisionReason.NoEligibleCandidate,
+                corridor,
+                excluded: excludedProcessors,
+                decidedAt,
+            };
         }
-        return { processor, reason: "customRioBankAccount" };
+        return {
+            processor,
+            reason: common_1.RoutingDecisionReason.CustomRioBankAccount,
+            corridor,
+            decidedAt,
+        };
     }
     // An absent rule is read as every rail at zero rather than as a reason to stop.
     // Bailing out here would hand the decision to the structural default, which
@@ -83,14 +95,43 @@ const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProce
     // because a percentage decides how volume is divided between the rails a
     // customer can use - it is not what makes a rail usable. Also drops any share
     // stored against a rail this purpose does not serve, which nothing dispatches.
-    const corridorProcessors = (0, common_1.getProcessorsForCorridor)(country, fiat, purpose);
-    const eligible = corridorProcessors.filter(isEligible);
+    const eligible = corridor.filter(isEligible);
     if (!eligible.length) {
-        return { reason: "noEligibleCandidate" };
+        return {
+            reason: common_1.RoutingDecisionReason.NoEligibleCandidate,
+            corridor,
+            excluded: excludedProcessors,
+            decidedAt,
+        };
     }
-    const candidates = eligible.filter(isUsable);
+    // A rail the customer has switched off for this direction is worthless whatever
+    // share it carries: on a buy they cannot send money to it, on a sell their bank
+    // will not accept the credit. Applies to every rail, verifiable or not - a bank
+    // can refuse a wire from Bancrea as easily as a SPEI transfer from Fintoc.
+    //
+    // Verifications are exempt because they are ours to place against an account the
+    // customer gave us, not a rail they have to accept.
+    const isGated = purpose !== common_1.ProcessorRoutingPurpose.BankAccountVerification;
+    const disabled = isGated ? (enablement === null || enablement === void 0 ? void 0 : enablement.disabled) || [] : [];
+    const unset = isGated && requireExplicitEnablement && purpose === common_1.ProcessorRoutingPurpose.Buy
+        ? (enablement === null || enablement === void 0 ? void 0 : enablement.unset) || []
+        : [];
+    const candidates = eligible.filter((processor) => !disabled.includes(processor) && !unset.includes(processor));
     if (!candidates.length) {
-        return { reason: "noEnabledCandidate" };
+        return {
+            // Told apart because they are different conversations. One customer turned
+            // their rails off and can turn one back on; the other has never told us
+            // which account their bank will let them pay, and needs to whitelist one
+            // before anything can be routed.
+            reason: unset.length
+                ? common_1.RoutingDecisionReason.NoAcceptedCandidate
+                : common_1.RoutingDecisionReason.NoEnabledCandidate,
+            corridor,
+            excluded: excludedProcessors,
+            disabled,
+            unset,
+            decidedAt,
+        };
     }
     const shares = candidates
         .map((processor) => {
@@ -101,6 +142,7 @@ const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProce
         });
     })
         .filter((candidate) => candidate.percentage > 0);
+    const percentages = Object.fromEntries(shares.map((share) => [share.processor, share.percentage]));
     // None of the rails this customer can use carries a share - or no rule is
     // configured at all - so there is no split to draw from. Refusing the order
     // would read a zero as "never use this rail", when all it says is where volume
@@ -111,18 +153,40 @@ const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProce
         const fallback = (0, common_1.getDefaultProcessor)(country, fiat, purpose, excludedProcessors);
         return {
             processor: fallback && candidates.includes(fallback) ? fallback : candidates[0],
-            reason: "enabledRailWithoutShare",
+            reason: common_1.RoutingDecisionReason.EnabledRailWithoutShare,
+            corridor,
+            excluded: excludedProcessors,
+            disabled,
+            unset,
+            decidedAt,
         };
     }
     if (shares.length === 1) {
-        return { processor: shares[0].processor, reason: "onlyCandidate" };
+        return {
+            processor: shares[0].processor,
+            reason: common_1.RoutingDecisionReason.OnlyCandidate,
+            corridor,
+            excluded: excludedProcessors,
+            disabled,
+            unset,
+            percentages,
+            decidedAt,
+        };
     }
     // Rolled per order, so the realized share converges on the configured
     // percentages by order count. Nothing is persisted here: a caller that needs
     // the same answer twice passes back the seed it used.
+    const seed = randomSeed !== null && randomSeed !== void 0 ? randomSeed : Math.random();
     return {
-        processor: pickByShare(shares, randomSeed !== null && randomSeed !== void 0 ? randomSeed : Math.random()),
-        reason: "split",
+        processor: pickByShare(shares, seed),
+        reason: common_1.RoutingDecisionReason.Split,
+        corridor,
+        excluded: excludedProcessors,
+        disabled,
+        unset,
+        percentages,
+        seed,
+        decidedAt,
     };
 };
 exports.resolveProcessor = resolveProcessor;

package/build/models/order.d.ts

@@ -1,4 +1,4 @@
-import { Country, Fees, Fiat, LiquidityProvider, OrderStatus, PaymentMethod, PayoutMethod, Processor, Side, Crypto, OrderAttribute, DeferredPaymentType, TwoWaySettlementType, OrderType } from "@riocrypto/common";
+import { Country, Fees, Fiat, LiquidityProvider, OrderStatus, PaymentMethod, PayoutMethod, Processor, RoutingDecision, Side, Crypto, OrderAttribute, DeferredPaymentType, TwoWaySettlementType, OrderType } from "@riocrypto/common";
 import { Mongoose, Model, Document, HydratedDocument } from "mongoose";
 interface OrderAttrs {
     quoteId: string;
@@ -21,6 +21,7 @@ interface OrderAttrs {
     amountCryptoReceived?: number;
     liquidityProvider: LiquidityProvider;
     processor: Processor;
+    routingDecision?: RoutingDecision;
     fees: Fees;
     actualFees?: Fees;
     wireMessage?: string;
@@ -172,6 +173,7 @@ interface OrderDoc extends Document {
     amountCryptoReceived?: number;
     liquidityProvider: LiquidityProvider;
     processor: Processor;
+    routingDecision?: RoutingDecision;
     fees: Fees;
     actualFees?: Fees;
     marketPrice: number;

package/build/models/order.js

@@ -110,6 +110,9 @@ const buildOrder = (mongoose) => {
             type: String,
             required: true,
         },
+        routingDecision: {
+            type: Object,
+        },
         liquidityProvider: {
             type: String,
             required: true,

package/build/models/quote.d.ts

@@ -1,4 +1,4 @@
-import { Country, Fees, Fiat, LiquidityProvider, PaymentMethod, PayoutMethod, Processor, Side, Crypto, DeferredPaymentType, TwoWaySettlementType, OrderType } from "@riocrypto/common";
+import { Country, Fees, Fiat, LiquidityProvider, PaymentMethod, PayoutMethod, Processor, RoutingDecision, Side, Crypto, DeferredPaymentType, TwoWaySettlementType, OrderType } from "@riocrypto/common";
 import { Mongoose, Model, Document, HydratedDocument } from "mongoose";
 interface QuoteAttrs {
     userId: string;
@@ -15,6 +15,7 @@ interface QuoteAttrs {
     amountCrypto: number;
     liquidityProvider: LiquidityProvider;
     processor: Processor;
+    routingDecision?: RoutingDecision;
     fees: Fees;
     assetPriceInUSD: number;
     actualAssetPriceInUSD?: number;
@@ -61,6 +62,7 @@ interface QuoteDoc extends Document {
     amountCrypto: number;
     liquidityProvider: LiquidityProvider;
     processor: Processor;
+    routingDecision?: RoutingDecision;
     createdAt: Date;
     timeInForceStartsAt?: Date;
     timeInForceEndsAt?: Date;

package/build/models/quote.js

@@ -55,6 +55,9 @@ const buildQuote = (mongoose) => {
             type: String,
             required: true,
         },
+        routingDecision: {
+            type: Object,
+        },
         liquidityProvider: {
             type: String,
             required: true,

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

@@ -55,6 +55,7 @@ interface RioSettingsAttrs {
     };
     fxTradingPolicies?: FXTradingPolicies;
     processorRouting?: ProcessorRoutingConfig;
+    requireExplicitPayinEnablement?: boolean;
     TVFXDataProvider: {
         [key in Fiat]: TVFXDataProvider;
     };
@@ -149,6 +150,7 @@ interface RioSettingsDoc extends mongoose.Document {
     };
     fxTradingPolicies?: FXTradingPolicies;
     processorRouting?: ProcessorRoutingConfig;
+    requireExplicitPayinEnablement?: boolean;
     TVFXDataProvider: {
         [key in Fiat]: TVFXDataProvider;
     };

package/build/models/rio-settings.js

@@ -59,6 +59,9 @@ const buildRioSettings = (mongoose) => {
         processorRouting: {
             type: Object,
         },
+        requireExplicitPayinEnablement: {
+            type: Boolean,
+        },
         TVFXDataProvider: {
             type: Object,
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riocrypto/common-server",
-  "version": "1.0.2889",
+  "version": "1.0.2892",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -28,7 +28,7 @@
     "@google-cloud/secret-manager": "^5.6.0",
     "@google-cloud/storage": "^7.19.0",
     "@hyperdx/node-opentelemetry": "^0.10.3",
-    "@riocrypto/common": "1.0.2702",
+    "@riocrypto/common": "1.0.2706",
     "@slack/web-api": "^7.15.0",
     "@types/express": "^4.17.25",
     "axios": "1.18.1",