MetaMask · georgeweiler · Sep 10, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026
@@ -5680,6 +5680,7 @@ describe('AccountTreeController', () => {
           isBackupAndSyncUpdateLoading: false,
           isContactSyncingEnabled: false,
           isContactSyncingInProgress: false,
+          isRampsSyncingEnabled: true,
         },
         [],
       );

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `BACKUPANDSYNC_FEATURES.rampsSyncing` and `UserStorageController.isRampsSyncingEnabled` ([#9474](https://github.com/MetaMask/core/pull/9474))
+  - Defaults to enabled (`true`); hosts can toggle Buy & sell order sync independently of account/contact sync
+
+### Changed
+
+- **BREAKING:** `UserStorageControllerState` now includes `isRampsSyncingEnabled`. Consumers that construct full state objects must include this field. ([#9474](https://github.com/MetaMask/core/pull/9474))
+  - Prefer `isRampsSyncingEnabled ?? true` in selectors so wallets upgraded before this field existed keep ramps syncing on by default
+
 ## [31.0.0]
 
 ### Changed

@@ -604,11 +604,10 @@ describe('UserStorageController', () => {
       const controller = new UserStorageController({
         messenger: messengerMocks.messenger,
         state: {
+          ...defaultState,
           isBackupAndSyncEnabled: false,
-          isBackupAndSyncUpdateLoading: false,
           isAccountSyncingEnabled: false,
           isContactSyncingEnabled: false,
-          isContactSyncingInProgress: false,
         },
       });
 
@@ -629,11 +628,10 @@ describe('UserStorageController', () => {
       const controller = new UserStorageController({
         messenger: messengerMocks.messenger,
         state: {
+          ...defaultState,
           isBackupAndSyncEnabled: false,
-          isBackupAndSyncUpdateLoading: false,
           isAccountSyncingEnabled: false,
           isContactSyncingEnabled: false,
-          isContactSyncingInProgress: false,
         },
       });
 
@@ -663,6 +661,7 @@ describe('UserStorageController', () => {
           isAccountSyncingEnabled: true,
           isContactSyncingEnabled: true,
           isContactSyncingInProgress: false,
+          isRampsSyncingEnabled: true,
         },
       });
 
@@ -674,6 +673,31 @@ describe('UserStorageController', () => {
       expect(controller.state.isAccountSyncingEnabled).toBe(false);
       expect(controller.state.isBackupAndSyncEnabled).toBe(true);
     });
+
+    it('should not disable backup and sync when disabling ramps syncing', async () => {
+      const { messengerMocks } = await arrangeMocks();
+      messengerMocks.mockAuthIsSignedIn.mockReturnValue(false);
+
+      const controller = new UserStorageController({
+        messenger: messengerMocks.messenger,
+        state: {
+          isBackupAndSyncEnabled: true,
+          isBackupAndSyncUpdateLoading: false,
+          isAccountSyncingEnabled: true,
+          isContactSyncingEnabled: true,
+          isContactSyncingInProgress: false,
+          isRampsSyncingEnabled: true,
+        },
+      });
+
+      await controller.setIsBackupAndSyncFeatureEnabled(
+        BACKUPANDSYNC_FEATURES.rampsSyncing,
+        false,
+      );
+
+      expect(controller.state.isRampsSyncingEnabled).toBe(false);
+      expect(controller.state.isBackupAndSyncEnabled).toBe(true);
+    });
   });
 
   describe('error handling edge cases', () => {
@@ -917,6 +941,7 @@ describe('metadata', () => {
         "isAccountSyncingEnabled": true,
         "isBackupAndSyncEnabled": true,
         "isContactSyncingEnabled": true,
+        "isRampsSyncingEnabled": true,
       }
     `);
   });
@@ -937,6 +962,7 @@ describe('metadata', () => {
         "isAccountSyncingEnabled": true,
         "isBackupAndSyncEnabled": true,
         "isContactSyncingEnabled": true,
+        "isRampsSyncingEnabled": true,
       }
     `);
   });
@@ -953,6 +979,7 @@ describe('metadata', () => {
         "isAccountSyncingEnabled": true,
         "isBackupAndSyncEnabled": true,
         "isContactSyncingEnabled": true,
+        "isRampsSyncingEnabled": true,
       }
     `);
   });
@@ -975,6 +1002,7 @@ describe('metadata', () => {
         "isBackupAndSyncUpdateLoading": false,
         "isContactSyncingEnabled": true,
         "isContactSyncingInProgress": false,
+        "isRampsSyncingEnabled": true,
       }
     `);
   });

@@ -74,6 +74,10 @@ export type UserStorageControllerState = {
    * Condition used by UI to determine if contact syncing is in progress.
    */
   isContactSyncingInProgress: boolean;
+  /**
+   * Condition used by UI to determine if ramps order syncing is enabled.
+   */
+  isRampsSyncingEnabled: boolean;
 };
 
 export const defaultState: UserStorageControllerState = {
@@ -82,6 +86,7 @@ export const defaultState: UserStorageControllerState = {
   isAccountSyncingEnabled: true,
   isContactSyncingEnabled: true,
   isContactSyncingInProgress: false,
+  isRampsSyncingEnabled: true,
 };
 
 const metadata: StateMetadata<UserStorageControllerState> = {
@@ -115,6 +120,12 @@ const metadata: StateMetadata<UserStorageControllerState> = {
     includeInDebugSnapshot: false,
     usedInUi: true,
   },
+  isRampsSyncingEnabled: {
+    includeInStateLogs: true,
+    persist: true,
+    includeInDebugSnapshot: true,
+    usedInUi: true,
+  },
 };
 
 type ControllerConfig = {
@@ -640,6 +651,10 @@ export class UserStorageController extends BaseController<
         if (feature === BACKUPANDSYNC_FEATURES.contactSyncing) {
           state.isContactSyncingEnabled = enabled;
         }
+
+        if (feature === BACKUPANDSYNC_FEATURES.rampsSyncing) {
+          state.isRampsSyncingEnabled = enabled;
+        }
       });
     } catch (e) {
       // istanbul ignore next

@@ -2,6 +2,7 @@ export const BACKUPANDSYNC_FEATURES = {
   main: 'main',
   accountSyncing: 'accountSyncing',
   contactSyncing: 'contactSyncing',
+  rampsSyncing: 'rampsSyncing',
 } as const;
 
 /**

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add V2 ramps order syncing with User Storage ([#9474](https://github.com/MetaMask/core/pull/9474))
+  - Synchronize orders across clients for the same SRP using timestamp-based last-write-wins conflict resolution, soft-delete tombstones, and incremental add/update/delete pushes
+  - Feature key: `rampsOrders`; hosts call `RampsController:syncOrdersWithUserStorage` on unlock when Backup & Sync + ramps syncing are enabled
+  - Persist optional `lastUpdatedAt` on local `RampsOrder` entries for LWW (not returned by the V2 API)
+  - Strip `paymentDetails` from remote payloads (PII stays local-only)
+  - Soft deletes use remote tombstones; retention matches contact sync (no remote purge/compaction)
+  - Mid-sync local mutations coalesce into a follow-up full sync pass so uploads are not dropped during `performBatchSetStorage`
+  - Polling via `getOrder` → `addOrder` stamps `lastUpdatedAt` and writes to User Storage only when the syncable payload changed
+  - Normalize ISO and numeric-string `createdAt` values from Portfolio and older clients to epoch milliseconds
+  - Optional `onOrderSyncErroneousSituation` (full sync and incremental push/delete) and `trace` callbacks
+
+### Changed
+
+- **BREAKING:** `RampsControllerMessenger` now requires these actions to be delegated for order syncing ([#9474](https://github.com/MetaMask/core/pull/9474)):
+  - `UserStorageController:getState`
+  - `UserStorageController:performGetStorageAllFeatureEntries`
+  - `UserStorageController:performBatchSetStorage`
+  - `AuthenticationController:isSignedIn`
+
 ## [21.0.0]
 
 ### Changed

@@ -55,7 +55,8 @@
     "@metamask/controller-utils": "^13.0.0",
     "@metamask/messenger": "^3.0.0",
     "@metamask/profile-sync-controller": "^31.0.0",
-    "@metamask/remote-feature-flag-controller": "^7.0.0"
+    "@metamask/remote-feature-flag-controller": "^7.0.0",
+    "fast-deep-equal": "^3.1.3"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.0",

@@ -306,6 +306,8 @@ export type RampsControllerGetQuotesAction = {
  * If an order with the same internal order code already exists, the incoming
  * fields are merged on top of the existing order so that fields not present
  * in the update (e.g. paymentDetails from the Transak API) are preserved.
+ * Unchanged syncable payloads (including unchanged poll results) are ignored
+ * so `lastUpdatedAt` is not bumped and User Storage is not rewritten.
  *
  * @param order - The RampsOrder to add or update.
  */
@@ -324,6 +326,20 @@ export type RampsControllerRemoveOrderAction = {
   handler: RampsController['removeOrder'];
 };
 
+/**
+ * Bidirectionally syncs V2 ramps orders with User Storage.
+ * Hosts should call this on unlock / when ramps syncing is enabled.
+ *
+ * Overlapping calls are coalesced into the in-flight worker. After the worker
+ * settles, this method loops when `#orderSyncQueued` is still set so a
+ * request that arrived between the worker's last loop check and promise
+ * resolution is not dropped.
+ */
+export type RampsControllerSyncOrdersWithUserStorageAction = {
+  type: `RampsController:syncOrdersWithUserStorage`;
+  handler: RampsController['syncOrdersWithUserStorage'];
+};
+
 /**
  * Adds or updates a local autoramp last-seen cursor (e.g. after create).
  *
@@ -832,6 +848,7 @@ export type RampsControllerMethodActions =
   | RampsControllerGetQuotesAction
   | RampsControllerAddOrderAction
   | RampsControllerRemoveOrderAction
+  | RampsControllerSyncOrdersWithUserStorageAction
   | RampsControllerAddAutorampAction
   | RampsControllerCreateAutorampAction
   | RampsControllerRegisterMoneyAccountWalletAction