@metamask/ramps-controller 26.3.0 → 27.0.0

package/dist/RampsController.js

@@ -1,7 +1,7 @@
 import { BaseController } from '@metamask/base-controller';
-import { BrokenCircuitError } from '@metamask/controller-utils';
+import { BrokenCircuitError, HttpError } from '@metamask/controller-utils';
 import { BigNumber } from 'bignumber.js';
-import { applyAutorampRemoteStatus, AutorampStatus, buildBrazilMusdAutorampRequest, createAutorampAccount, markAutorampNotified, } from './autorampAccount.js';
+import { applyAutorampRemoteStatus, AutorampStatus, createAutorampAccount, markAutorampNotified, } from './autorampAccount.js';
 import { getHeadlessProviderAllowlist, isHeadlessAllProvidersEnabled, normalizeHeadlessProviderId, } from './featureFlags.js';
 import { areOrdersEqual, deleteOrderInUserStorage, syncOrdersWithUserStorage as syncOrdersWithUserStorageInternal, updateOrderInUserStorage, } from './order-syncing/index.js';
 import { PENDING_ORDER_STATUSES, TERMINAL_ORDER_STATUSES, } from './orderStatus.js';
@@ -81,9 +81,9 @@ export const RAMPS_CONTROLLER_REQUIRED_CONTROLLER_ACTIONS = [
     'AuthenticationController:getSessionProfile',
     'AuthenticationController:isSignedIn',
     'KeyringController:signPersonalMessage',
-    'KycController:getSessionStatusForVendor',
     'KycController:getProviderFlowStatus',
-    'KycController:refreshSessionStatus',
+    'KycController:readSessionStatus',
+    'KycController:fetchSessionStatusOnce',
     'KycController:hasCompletedVendorDisclaimers',
     'KycController:hasCompletedSessionDisclaimers',
     'KycController:clearState',
@@ -92,6 +92,15 @@ export const RAMPS_CONTROLLER_REQUIRED_CONTROLLER_ACTIONS = [
     'UserStorageController:performGetStorageAllFeatureEntries',
     'UserStorageController:performBatchSetStorage',
 ];
+/**
+ * `finalStatus` values that end a KYC session. Mirrors
+ * `TERMINAL_SESSION_STATUSES` in `@metamask/kyc-controller`.
+ */
+const TERMINAL_VBA_KYC_FINAL_STATUSES = new Set([
+    'approved',
+    'rejected',
+    'retry',
+]);
 /**
  * KYC vocabulary used on the VBA onboarding snapshot. `'none'` means no
  * session exists yet (or the vendor returned an unrecognized status).
@@ -112,13 +121,21 @@ export const VBA_PROVIDER_FLOW_STATUSES = [
 ];
 /**
  * Autoramp setup progress after KYC has been approved.
- * `'in_progress'` is reserved for hosts that observe an in-flight hydrate;
- * {@link RampsController.hydrateVbaOnboarding} itself returns `'ready'` or
- * `'retryable_failure'` once the coalesced run settles.
+ *
+ * `'needs_wallet_registration'` means KYC is approved, this wallet has no
+ * persisted registration row, and there is no usable autoramp.
+ * `'needs_source_currency'` means KYC is approved, the registration row is
+ * `active` or `disabled`, and there is no usable autoramp.
+ * `'in_progress'` is reserved for hosts that observe an in-flight hydrate.
+ * {@link RampsController.hydrateVbaOnboarding} returns `'ready'`,
+ * `'needs_wallet_registration'`, `'needs_source_currency'`, or
+ * `'retryable_failure'` once an approved read settles.
  */
 export const VBA_AUTORAMP_STATUSES = [
     'not_ready',
     'in_progress',
+    'needs_wallet_registration',
+    'needs_source_currency',
     'ready',
     'retryable_failure',
 ];
@@ -144,24 +161,97 @@ function toVbaKycStatus(value) {
     return 'none';
 }
 /**
- * Idempotency key for the standing BRL to mUSD autoramp.
+ * Maps a KYC session onto the snapshot vocabulary.
+ *
+ * Relay approval (`kycStatus: 'approved'`) counts even when `finalStatus` is
+ * still `pending`. A non-approved session whose provider flow was submitted,
+ * or whose status is pending, is `pending`.
+ *
+ * @param session - Persisted or freshly fetched KYC session.
+ * @param providerFlowStatus - Durable provider-flow outcome.
+ * @returns The snapshot KYC status.
+ */
+function resolveVbaKycStatus(session, providerFlowStatus) {
+    if (session.finalStatus === 'approved' || session.kycStatus === 'approved') {
+        return 'approved';
+    }
+    const mapped = toVbaKycStatus(session.finalStatus);
+    if (mapped === 'rejected' || mapped === 'retry') {
+        return mapped;
+    }
+    if (session.finalStatus === 'pending' ||
+        session.kycStatus === 'pending' ||
+        providerFlowStatus === 'submitted') {
+        return 'pending';
+    }
+    return mapped;
+}
+/**
+ * Idempotency key for a standing fiat to mUSD autoramp on Monad.
  *
- * The customer and wallet keep retries of one create on the same key. Rejected
- * or cancelled route ids are appended, sorted, so a replacement create is a
- * new key and MoonPay does not replay the terminal route.
+ * The source fiat, customer, and wallet keep retries of one create on the
+ * same key (`brl-musd-monad` versus `usd-musd-monad`). Rejected or cancelled
+ * route ids are appended, sorted, so a replacement create is a new key and
+ * MoonPay does not replay the terminal route.
  *
+ * @param sourceCurrencyCode - Fiat code from the create body. Trimmed and lowercased here.
  * @param customerId - MoonPay customer id.
  * @param walletAddress - Money Account address that receives mUSD.
  * @param terminalAutorampIds - Ids of rejected or cancelled routes for this wallet.
  * @returns Idempotency-Key value.
  */
-function buildBrazilMusdAutorampIdempotencyKey(customerId, walletAddress, terminalAutorampIds) {
-    const base = `brl-musd-monad:${customerId}:${walletAddress.trim().toLowerCase()}`;
+function buildMusdAutorampIdempotencyKey(sourceCurrencyCode, customerId, walletAddress, terminalAutorampIds) {
+    const fiatPrefix = sourceCurrencyCode.trim().toLowerCase();
+    const base = `${fiatPrefix}-musd-monad:${customerId}:${walletAddress.trim().toLowerCase()}`;
     if (terminalAutorampIds.length === 0) {
         return base;
     }
     return `${base}:${[...terminalAutorampIds].sort().join(':')}`;
 }
+/**
+ * Reads the first fiat `source_currencies` code from an autoramp create body.
+ *
+ * @param request - Caller-supplied create payload.
+ * @returns Lowercased fiat code, or `null` when the body has none.
+ */
+function readCreateAutorampFiatCode(request) {
+    const sourceCurrencies = request.source_currencies;
+    if (!Array.isArray(sourceCurrencies)) {
+        return null;
+    }
+    for (const currency of sourceCurrencies) {
+        if (!currency || typeof currency !== 'object') {
+            continue;
+        }
+        const record = currency;
+        if (record.type !== 'Fiat' || typeof record.code !== 'string') {
+            continue;
+        }
+        const code = record.code.trim().toLowerCase();
+        if (code.length > 0) {
+            return code;
+        }
+    }
+    return null;
+}
+/**
+ * Reads the destination wallet from an autoramp create body.
+ *
+ * @param request - Caller-supplied create payload.
+ * @returns Trimmed recipient address, or `null` when it is missing.
+ */
+function readCreateAutorampWalletAddress(request) {
+    const recipient = request.recipient_account;
+    if (!recipient || typeof recipient !== 'object') {
+        return null;
+    }
+    const { address } = recipient;
+    if (typeof address !== 'string') {
+        return null;
+    }
+    const trimmed = address.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 /**
  * Distinguishes an already-materialized {@link AutorampAccount} from the
  * create-fields shape accepted by {@link RampsController.addAutoramp}.
@@ -290,6 +380,18 @@ const rampsControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
+    moneyAccountWalletRegistrations: {
+        persist: true,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    vbaAutorampListFetchedAt: {
+        persist: true,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: false,
+        usedInUi: true,
+    },
     providerAutoSelected: {
         persist: true,
         includeInDebugSnapshot: true,
@@ -340,6 +442,8 @@ export function getDefaultRampsControllerState() {
         },
         orders: [],
         autoramps: [],
+        moneyAccountWalletRegistrations: [],
+        vbaAutorampListFetchedAt: null,
         providerAutoSelected: false,
     };
 }
@@ -2390,17 +2494,31 @@ export class RampsController extends BaseController {
      *
      * The vendor `customer_id` is resolved via
      * {@link RampsController.resolveAutorampCustomerId} and injected into the
-     * request (any caller-supplied `customer_id` is overwritten).
-     *
-     * @param request - CreateAutoramp payload.
-     * @param options - Optional idempotency key forwarded to the proxy.
+     * request (any caller-supplied `customer_id` is overwritten). The caller
+     * supplies the fiat body. When that body names a source fiat and a
+     * recipient wallet, the idempotency key is derived from that fiat
+     * (`brl-musd-monad` or `usd-musd-monad`), the customer, the wallet, and
+     * rejected or cancelled autoramp ids. A caller-supplied key is used only
+     * when the body has no source fiat or recipient address.
+     *
+     * @param request - CreateAutoramp payload, including the source fiat.
+     * @param options - Optional idempotency key forwarded when the body does
+     * not identify a fiat route.
      * @param options.idempotencyKey - Value sent as `Idempotency-Key`.
      * @returns The created/updated local {@link AutorampAccount}.
      */
     async createAutoramp(request, options = {}) {
         const customerId = await this.resolveAutorampCustomerId();
+        const fiatCode = readCreateAutorampFiatCode(request);
+        const walletAddress = readCreateAutorampWalletAddress(request);
+        const requestOptions = fiatCode && walletAddress
+            ? {
+                ...options,
+                idempotencyKey: buildMusdAutorampIdempotencyKey(fiatCode, customerId, walletAddress, this.#terminalAutorampIdsForWallet(walletAddress)),
+            }
+            : options;
         const body = { ...request, customer_id: customerId };
-        const remote = await this.messenger.call('NeoBankService:createAutoramp', body, options);
+        const remote = await this.messenger.call('NeoBankService:createAutoramp', body, requestOptions);
         return this.#applyAutorampRemoteSnapshot(remote);
     }
     /**
@@ -2498,7 +2616,7 @@ export class RampsController extends BaseController {
         };
         const existingResult = await resolveLookup();
         if (existingResult) {
-            return existingResult;
+            return this.#finishMoneyAccountWalletRegistration(address, existingResult);
         }
         let idempotencyKey = createIdempotencyKey();
         let lastMessage;
@@ -2533,7 +2651,7 @@ export class RampsController extends BaseController {
                     idempotencyKey,
                 });
                 machine = transitionWalletRegistration(machine, { type: 'SUBMIT_OK' });
-                return result;
+                return this.#finishMoneyAccountWalletRegistration(address, result);
             }
             catch (error) {
                 if (!(error instanceof WalletRegistrationError)) {
@@ -2576,7 +2694,7 @@ export class RampsController extends BaseController {
                     machine.status === 'checkThenRetry') {
                     const reconciledResult = await resolveLookup();
                     if (reconciledResult) {
-                        return reconciledResult;
+                        return this.#finishMoneyAccountWalletRegistration(address, reconciledResult);
                     }
                 }
                 if (machine.status !== 'signing') {
@@ -2586,23 +2704,37 @@ export class RampsController extends BaseController {
         }
     }
     /**
-     * Refreshes KYC session facts and, when Iron has approved KYC, activates the
-     * Money Account (wallet registration + autoramp). Hosts map the returned
+     * Reads VBA onboarding facts. Hosts map the returned
      * {@link VbaOnboardingSnapshot} onto their own funnel; this method does not
      * name screens.
      *
-     * Overlapping calls share one run so polling cannot trigger duplicate wallet
-     * signatures or autoramp creation.
+     * The read uses the persisted KYC session. `refreshKyc` performs one
+     * session-status GET when a session id is already stored and `finalStatus`
+     * is not terminal. `refreshAutoramps` lists autoramps when KYC is approved,
+     * unless this wallet already has a usable route. It does not sign, post a
+     * self-hosted address, create an autoramp, or start KYC polling.
+     *
+     * Overlapping calls share one run.
      *
      * @param params - VBA onboarding parameters.
      * @param params.walletAddress - Monad Money Account wallet address.
+     * @param params.refreshKyc - When true, fetch session status once for a
+     * non-terminal persisted session. A failed GET keeps that session. Defaults
+     * to false.
+     * @param params.refreshAutoramps - When true, replace the autoramp cursor
+     * from `GET /neobank/autoramps` unless a usable route is already stored.
+     * Defaults to false.
      * @returns Independent KYC and autoramp facts for the current customer.
      */
-    async hydrateVbaOnboarding({ walletAddress, }) {
+    async hydrateVbaOnboarding({ walletAddress, refreshKyc = false, refreshAutoramps = false, }) {
         if (this.#vbaOnboardingHydrationPromise) {
             return await this.#vbaOnboardingHydrationPromise;
         }
-        const hydrationPromise = this.#hydrateVbaOnboarding(walletAddress);
+        const hydrationPromise = this.#hydrateVbaOnboarding({
+            walletAddress,
+            refreshKyc,
+            refreshAutoramps,
+        });
         this.#vbaOnboardingHydrationPromise = hydrationPromise;
         try {
             return await hydrationPromise;
@@ -2613,46 +2745,39 @@ export class RampsController extends BaseController {
             }
         }
     }
-    async #hydrateVbaOnboarding(walletAddress) {
-        // Prefer the in-memory/persisted session status over the backend
-        // latest-status endpoint: after SumSub the backend endpoint can lag, while
-        // the controller state reflects the journey/SDK outcome. Fall back to a
-        // backend fetch only when the controller has no session in state (e.g. a
-        // reinstall/cleared state resuming an existing customer, or a brand-new user
-        // with no session at all).
-        let session = null;
-        // Whether `session` came from persisted controller state (as opposed to a
-        // fresh backend fetch, which is always scoped to the current user). Only a
-        // persisted session can belong to a previous identity, so only that path
-        // needs the ownership check below.
-        let sessionFromCache = false;
-        try {
-            session = this.messenger.call('KycController:refreshSessionStatus');
-            sessionFromCache = true;
+    async #hydrateVbaOnboarding({ walletAddress, refreshKyc, refreshAutoramps, }) {
+        let session = this.messenger.call('KycController:readSessionStatus');
+        // A persisted session can outlive the identity that created it. Reusing it
+        // makes session-scoped calls fail closed. Discard it before any fetch, with
+        // the registration rows and autoramp cursor it left behind, since neither
+        // is keyed by profile.
+        if (session && !(await this.#isVbaSessionOwnedByCurrentProfile(session))) {
+            this.messenger.call('KycController:clearState');
+            this.update((state) => {
+                state.moneyAccountWalletRegistrations = [];
+                state.autoramps = [];
+                state.vbaAutorampListFetchedAt = null;
+            });
+            return { ...EMPTY_VBA_ONBOARDING_SNAPSHOT };
         }
-        catch {
+        if (refreshKyc &&
+            session?.id &&
+            !TERMINAL_VBA_KYC_FINAL_STATUSES.has(session.finalStatus)) {
             try {
-                session = await this.messenger.call('KycController:getSessionStatusForVendor', 'iron');
+                session = await this.messenger.call('KycController:fetchSessionStatusOnce', session.id);
             }
-            catch {
-                // No session exists for this customer yet: the backend returns 404
-                // ("KYC session not found"), which surfaces as a rejection here.
-                session = null;
+            catch (error) {
+                if (error instanceof HttpError && error.httpStatus === 404) {
+                    this.messenger.call('KycController:clearState');
+                    return { ...EMPTY_VBA_ONBOARDING_SNAPSHOT };
+                }
+                // The persisted session is already in hand. A transient status GET
+                // must not reject the read.
             }
         }
         if (!session) {
             return { ...EMPTY_VBA_ONBOARDING_SNAPSHOT };
         }
-        // A persisted session can outlive the identity that created it — e.g. a new
-        // wallet created over an install that still holds a previous customer's
-        // session. Reusing it makes the backend reject every session-scoped call
-        // (owner mismatch), dead-ending the user. Verify ownership up front against
-        // the signed-in profile and, on a mismatch, discard the stale session.
-        if (sessionFromCache &&
-            !(await this.#isVbaSessionOwnedByCurrentProfile(session))) {
-            this.messenger.call('KycController:clearState');
-            return { ...EMPTY_VBA_ONBOARDING_SNAPSHOT };
-        }
         const vendorDisclaimersComplete = await this.messenger.call('KycController:hasCompletedVendorDisclaimers');
         const sessionDisclaimersComplete = await this.messenger.call('KycController:hasCompletedSessionDisclaimers');
         const providerFlowStatus = this.messenger.call('KycController:getProviderFlowStatus');
@@ -2661,15 +2786,7 @@ export class RampsController extends BaseController {
             vendorDisclaimersComplete,
             sessionDisclaimersComplete,
             providerFlowStatus,
-            // The relay approves (`kycStatus: 'approved'`) as soon as the KYC decision
-            // is made, while the vendor-side `finalStatus` can lag at `'pending'` until
-            // the vendor record is finalized (and in sandbox may never advance). Treat
-            // either signal as approval so a relay-approved user is not stranded on the
-            // pending screen. This mirrors the UKYC backend, whose own "already
-            // approved" check is `finalStatus === 'approved' || kycStatus === 'approved'`.
-            kycStatus: session.finalStatus === 'approved' || session.kycStatus === 'approved'
-                ? 'approved'
-                : toVbaKycStatus(session.finalStatus),
+            kycStatus: resolveVbaKycStatus(session, providerFlowStatus),
             autorampStatus: 'not_ready',
         };
         if (snapshot.kycStatus !== 'approved') {
@@ -2678,46 +2795,98 @@ export class RampsController extends BaseController {
         if (!walletAddress.trim()) {
             throw new Error('walletAddress is required after KYC acceptance.');
         }
-        // KYC is approved; the remaining work activates the Money account (register
-        // the wallet + ensure an autoramp). Those calls hit the neobank backend and
-        // can fail transiently (e.g. an address-list lookup timeout). Surface
-        // `retryable_failure` so the host can keep the user on a pending screen
-        // rather than a fatal error — the KYC decision itself already succeeded.
-        try {
-            const registration = await this.registerMoneyAccountWallet({
-                address: walletAddress,
-            });
-            if (registration.type === 'lookupUnavailable') {
-                throw registration.error;
+        if (this.#hasUsableAutorampForWallet(walletAddress)) {
+            return { ...snapshot, autorampStatus: 'ready' };
+        }
+        if (refreshAutoramps) {
+            try {
+                await this.#replaceAutorampCursorFromList();
             }
-            const customerId = await this.resolveAutorampCustomerId();
-            const remoteAutoramps = await this.messenger.call('NeoBankService:getAutoramps', { customerId });
-            const remoteAutorampIds = new Set(remoteAutoramps.map((autoramp) => autoramp.id));
-            for (const autoramp of remoteAutoramps) {
-                this.#applyAutorampRemoteSnapshot(autoramp);
+            catch {
+                return { ...snapshot, autorampStatus: 'retryable_failure' };
             }
-            this.update((state) => {
-                state.autoramps = state.autoramps.filter((autoramp) => remoteAutorampIds.has(autoramp.id));
-            });
-            const trimmedWalletAddress = walletAddress.trim();
-            const normalizedWalletAddress = trimmedWalletAddress.toLowerCase();
-            const autorampsForWallet = this.state.autoramps.filter((autoramp) => autoramp.walletAddress.toLowerCase() === normalizedWalletAddress);
-            const hasUsableAutoramp = autorampsForWallet.some((autoramp) => autoramp.status !== AutorampStatus.Rejected &&
-                autoramp.status !== AutorampStatus.Cancelled);
-            if (!hasUsableAutoramp) {
-                const terminalAutorampIds = autorampsForWallet
-                    .filter((autoramp) => autoramp.status === AutorampStatus.Rejected ||
-                    autoramp.status === AutorampStatus.Cancelled)
-                    .map((autoramp) => autoramp.id);
-                await this.createAutoramp(buildBrazilMusdAutorampRequest(trimmedWalletAddress), {
-                    idempotencyKey: buildBrazilMusdAutorampIdempotencyKey(customerId, trimmedWalletAddress, terminalAutorampIds),
-                });
+            if (this.#hasUsableAutorampForWallet(walletAddress)) {
+                return { ...snapshot, autorampStatus: 'ready' };
             }
         }
-        catch {
-            return { ...snapshot, autorampStatus: 'retryable_failure' };
+        const registration = this.state.moneyAccountWalletRegistrations.find((row) => row.walletAddress.trim().toLowerCase() ===
+            walletAddress.trim().toLowerCase());
+        if (!registration) {
+            return { ...snapshot, autorampStatus: 'needs_wallet_registration' };
         }
-        return { ...snapshot, autorampStatus: 'ready' };
+        return { ...snapshot, autorampStatus: 'needs_source_currency' };
+    }
+    /**
+     * Writes the registration row after a successful register outcome.
+     * `lookupUnavailable` writes nothing.
+     *
+     * @param address - Money Account wallet address.
+     * @param result - Registration outcome.
+     * @returns The same outcome.
+     */
+    #finishMoneyAccountWalletRegistration(address, result) {
+        if (result.type === 'lookupUnavailable') {
+            return result;
+        }
+        const normalized = address.trim().toLowerCase();
+        const status = result.type === 'registeredDisabled' ? 'disabled' : 'active';
+        const row = {
+            walletAddress: normalized,
+            status,
+            updatedAt: Date.now(),
+        };
+        this.update((state) => {
+            const index = state.moneyAccountWalletRegistrations.findIndex((existing) => existing.walletAddress.trim().toLowerCase() === normalized);
+            if (index === -1) {
+                state.moneyAccountWalletRegistrations.push(row);
+            }
+            else {
+                state.moneyAccountWalletRegistrations[index] = row;
+            }
+        });
+        return result;
+    }
+    /**
+     * Ids of rejected or cancelled autoramps for a wallet, used in create keys.
+     *
+     * @param walletAddress - Destination wallet address.
+     * @returns Terminal autoramp ids for that wallet.
+     */
+    #terminalAutorampIdsForWallet(walletAddress) {
+        const normalized = walletAddress.trim().toLowerCase();
+        return this.state.autoramps
+            .filter((autoramp) => autoramp.walletAddress.toLowerCase() === normalized &&
+            (autoramp.status === AutorampStatus.Rejected ||
+                autoramp.status === AutorampStatus.Cancelled))
+            .map((autoramp) => autoramp.id);
+    }
+    /**
+     * Whether this wallet has an autoramp that is not Rejected or Cancelled.
+     *
+     * @param walletAddress - Destination wallet address.
+     * @returns Whether a usable route is already on the cursor.
+     */
+    #hasUsableAutorampForWallet(walletAddress) {
+        const normalized = walletAddress.trim().toLowerCase();
+        return this.state.autoramps.some((autoramp) => autoramp.walletAddress.toLowerCase() === normalized &&
+            autoramp.status !== AutorampStatus.Rejected &&
+            autoramp.status !== AutorampStatus.Cancelled);
+    }
+    /**
+     * Replaces the autoramp cursor from `GET /neobank/autoramps` and records
+     * `vbaAutorampListFetchedAt` only after that GET succeeds.
+     */
+    async #replaceAutorampCursorFromList() {
+        const customerId = await this.resolveAutorampCustomerId();
+        const remoteAutoramps = await this.messenger.call('NeoBankService:getAutoramps', { customerId });
+        const remoteAutorampIds = new Set(remoteAutoramps.map((autoramp) => autoramp.id));
+        for (const autoramp of remoteAutoramps) {
+            this.#applyAutorampRemoteSnapshot(autoramp);
+        }
+        this.update((state) => {
+            state.autoramps = state.autoramps.filter((autoramp) => remoteAutorampIds.has(autoramp.id));
+            state.vbaAutorampListFetchedAt = Date.now();
+        });
     }
     /**
      * Whether a persisted KYC session belongs to the currently signed-in profile.