feat: compliance controller by aganglada · Pull Request #7945 · MetaMask/core

aganglada · 2026-02-16T16:38:50Z

Explanation

This PR adds a new @metamask/compliance-controller package to the monorepo. It provides OFAC compliance checking for wallet addresses by interfacing with the Compliance API (va-mmcx-compliance-api).

The package consists of two main components:

`ComplianceService` (data service)

Handles all HTTP communication with the Compliance API. It wraps three endpoints:

checkWalletCompliance(address) — GET /v1/wallet/:address for single address checks
checkWalletsCompliance(addresses) — POST /v1/wallet/batch for batch address checks
fetchBlockedWallets() — GET /v1/blocked-wallets for the full OFAC blocklist with source metadata

All requests are wrapped with createServicePolicy for automatic retries, circuit breaking, and degraded state detection. Response validation uses @metamask/superstruct schemas.

`ComplianceController` (controller)

Manages compliance state and provides a proactive caching pattern (similar to PhishingController):

On initialize(), it fetches and caches the full blocked wallets list if it is missing or stale (configurable refresh interval, defaults to 1 hour)
isWalletBlocked(address) performs a synchronous lookup against the cached blocklist — no API call needed
On-demand methods (checkWalletCompliance, checkWalletsCompliance) remain available for fresh per-address checks when needed (e.g., before high-value transactions)
clearComplianceState() resets all cached data

Test coverage

54 tests with 100% coverage across statements, branches, functions, and lines
Controller tests follow the withController pattern
Service tests use nock for HTTP stubbing with retry, circuit breaker, and degraded state scenarios

References

Compliance API: va-mmcx-compliance-api (NestJS service providing OFAC SDN list checks)
Follows patterns from PhishingController (proactive blocklist caching), ClaimsController (PascalCase file structure), and SampleGasPricesController/SampleGasPricesService (messenger + service policy patterns)

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Medium Risk
Introduces a new network-facing compliance component that can affect address blocking decisions and relies on external API responses/caching semantics; however it is largely additive and well-tested without changing existing controller behavior.

Overview
Adds a new @metamask/compliance-controller package that supports OFAC compliance checks against the Compliance API, including a ComplianceService (HTTP client with retry/circuit-break/degraded detection and response validation) and a ComplianceController that caches a blocked-wallets list plus per-address check results and exposes messenger actions (init, checkWalletCompliance, checkWalletsCompliance, updateBlockedWallets, clearComplianceState) and selectIsWalletBlocked.

Wires the new package into repo metadata (README package list/dependency graph, CODEOWNERS, teams.json, yarn.lock) and includes full unit test coverage plus standard package scaffolding (tsconfigs, typedoc, changelog, license).

^{Written by Cursor Bugbot for commit e493973. This will update automatically on new commits. Configure here.}

packages/compliance-controller/src/ComplianceController.ts

cryptodev-2s · 2026-02-17T11:48:30Z

@aganglada Could also run yarn update-readme-content to update the root monorepo README.

cursor · 2026-02-17T12:03:58Z

packages/compliance-controller/src/ComplianceController.ts

+    // Fall back to per-address compliance status map
+    const status = this.state.walletComplianceStatusMap[address];
+    return status?.blocked ?? false;
+  }


Case-sensitive address lookup may miss blocked wallets

High Severity

isWalletBlocked uses case-sensitive Array.includes() for the blocklist and case-sensitive object key lookup for the status map. Ethereum addresses are hex and case-insensitive, so a casing mismatch between the blocklist and the queried address (e.g., 0xABC vs 0xabc) would cause a sanctioned wallet to be incorrectly reported as not blocked. The PhishingController in this same monorepo already uses toLowerCase() for address comparisons to avoid this problem.

cryptodev-2s

I took an initial look and left a few suggestions to help reduce the boilerplate.

packages/compliance-controller/src/ComplianceController.ts

packages/compliance-controller/src/ComplianceService.ts

packages/compliance-controller/src/index.ts

cursor · 2026-02-17T12:18:17Z

packages/compliance-controller/src/ComplianceController.ts

+      for (let idx = 0; idx < statuses.length; idx++) {
+        const callerAddress = addresses[idx];
+        draftState.walletComplianceStatusMap[callerAddress] = statuses[idx];
+      }


Batch compliance mapping assumes API preserves input ordering

High Severity

checkWalletsCompliance maps results to state using positional indexing — addresses[idx] is used as the key for statuses[idx]. This assumes the batch API returns results in exactly the same order as the input addresses array. If the API returns results in a different order (or a different count), the wrong blocked status gets persisted against the wrong address. For an OFAC compliance controller, this could mark a sanctioned wallet as safe or a clean wallet as blocked. A safer approach would be to key by statuses[idx].address (which comes from result.address in the API response) rather than by positional index from the caller's input array.

cryptodev-2s · 2026-02-17T14:30:48Z

packages/compliance-controller/src/ComplianceService.test.ts

+import { useFakeTimers } from 'sinon';
+import type { SinonFakeTimers } from 'sinon';


What do you think about using jest timers instead ?

Suggested change

import { useFakeTimers } from 'sinon';

import type { SinonFakeTimers } from 'sinon';

This can be achieved by doing the following

| sinon | Jest | |--------------------------|----------------------------------------------------------------------| | `useFakeTimers()` | `jest.useFakeTimers({ doNotFake: ['nextTick', 'queueMicrotask'] })` | | `clock.restore()` | `jest.useRealTimers()` | | `clock.tick(6000)` | `jest.advanceTimersByTime(6000)` | | `clock.nextAsync()` | `jest.advanceTimersToNextTimerAsync()` |

We recently upgraded Jest and we have access to new fake timer APIs.

For some context here, we recently switched to Jest 29, which means we can take advantage of more fake timer APIs.

mcmire

Hello there! I had some comments relating to aligning with best practices.

mcmire · 2026-02-17T21:32:32Z

packages/compliance-controller/src/ComplianceController.ts

+   *
+   * @returns The blocked wallets information.
+   */
+  async fetchBlockedWallets(): Promise<BlockedWalletsInfo> {


Nit: Perhaps this should be called updateBlockedWallets? Besides fetching it's also updating the state.

mcmire · 2026-02-17T21:44:41Z

packages/compliance-controller/src/ComplianceService.test.ts

+import { useFakeTimers } from 'sinon';
+import type { SinonFakeTimers } from 'sinon';


For some context here, we recently switched to Jest 29, which means we can take advantage of more fake timer APIs.

mcmire · 2026-02-17T23:07:39Z

packages/compliance-controller/src/ComplianceService.ts

+  }: {
+    messenger: ComplianceServiceMessenger;
+    fetch: typeof fetch;
+    complianceApiUrl: string;


Is there a reason why you need this class to take a URL? This allows this class to theoretically represent any endpoint that satisfies the API being called here, however, it means that the clients need to store what that URL is, so that knowledge is not kept here.

If we are using multiple URLs for different environments what are your thoughts on having this class take an environment or env option and then constructing the URL here?

mcmire · 2026-02-17T23:08:26Z

packages/compliance-controller/src/ComplianceController.ts

+   * is missing or stale. Call once after construction to ensure the blocklist
+   * is ready for `isWalletBlocked` lookups.
+   */
+  async initialize(): Promise<void> {


This is not an official standard, however, in other controllers such as AccountTreeController use init rather than initialize for the name of the "post-construction initialization" method. What are your thoughts on renaming this method?

Alternatively, what are your thoughts on isWalletBlocked making an API call the first time it's called?

Agree with init.
Regarding isWalletBlocked making the api call, this will mean the first call with be blocking and we don't want that

mcmire · 2026-02-17T23:10:38Z

packages/compliance-controller/src/ComplianceController.ts

+   * @returns `true` if the wallet is blocked according to cached data,
+   * `false` otherwise.
+   */
+  isWalletBlocked(address: string): boolean {


If you truly don't want to make an API call here, since this method only accesses state, what are your thoughts on extracting this to a selector? See here for documentation on how to do this: https://github.com/MetaMask/core/blob/main/docs/code-guidelines/controller-guidelines.md#expose-derived-state-using-selectors-instead-of-getters (See here for defining selectors with arguments.)

mcmire · 2026-02-17T23:17:08Z

packages/compliance-controller/src/index.ts

+  ComplianceServiceCheckWalletComplianceAction,
+  ComplianceServiceCheckWalletsComplianceAction,
+  ComplianceServiceFetchBlockedWalletsAction,
+  ComplianceServiceMethodActions,


Typically we don't export this type, because we don't need it outside the package. Thoughts on removing?

Suggested change

ComplianceServiceMethodActions,

mcmire · 2026-02-17T23:17:23Z

packages/compliance-controller/src/index.ts

+  ComplianceControllerFetchBlockedWalletsAction,
+  ComplianceControllerInitializeAction,
+  ComplianceControllerIsWalletBlockedAction,
+  ComplianceControllerMethodActions,


Same as above.

Suggested change

ComplianceControllerMethodActions,

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

cursor · 2026-02-18T10:02:03Z

packages/compliance-controller/src/selectors.ts

+      if (blockedWallets?.addresses.includes(address)) {
+        return true;
+      }
+      return statusMap[address]?.blocked ?? false;


Case-sensitive address matching bypasses OFAC compliance check

High Severity

selectIsWalletBlocked uses case-sensitive comparison (addresses.includes(address)) and case-sensitive map key lookup (statusMap[address]). Ethereum addresses are case-insensitive — EIP-55 only adds checksum casing for display. A blocked address stored as 0xABC... won't match a lookup for 0xabc..., allowing a sanctioned wallet to bypass the compliance check. The PhishingController in this same monorepo normalizes addresses with toLowerCase() before comparison for exactly this reason. Both the selector and the state storage in checkWalletCompliance/checkWalletsCompliance need address normalization.

Additional Locations (1)

packages/compliance-controller/src/ComplianceController.ts#L250-L253

aganglada self-assigned this Feb 16, 2026

aganglada force-pushed the feat/compliance-controller branch from abafb3c to eb49115 Compare February 16, 2026 17:33

aganglada marked this pull request as ready for review February 17, 2026 11:42

aganglada requested a review from a team as a code owner February 17, 2026 11:42

cursor bot reviewed Feb 17, 2026

View reviewed changes

packages/compliance-controller/src/ComplianceController.ts Outdated Show resolved Hide resolved

cursor bot reviewed Feb 17, 2026

View reviewed changes

cryptodev-2s requested changes Feb 17, 2026

View reviewed changes

cursor bot reviewed Feb 17, 2026

View reviewed changes

aganglada requested a review from cryptodev-2s February 17, 2026 13:38

cryptodev-2s reviewed Feb 17, 2026

View reviewed changes

mcmire reviewed Feb 17, 2026

View reviewed changes

aganglada added 8 commits February 18, 2026 10:53

feat: compliance controller

4dbfdf5

chore: fix lints

e42dce8

chore: fix lints

f92f43b

chore: changelog

9d9f173

chore: update root monorepo

758150c

chore: review feedback

05bb3b0

chore: fix lint

859349a

chore: feedback

06e890c

aganglada force-pushed the feat/compliance-controller branch from b63359f to 06e890c Compare February 18, 2026 09:54

aganglada requested review from cryptodev-2s and mcmire February 18, 2026 09:55

cursor bot reviewed Feb 18, 2026

View reviewed changes

refactor: service url mapping

e493973

		import { useFakeTimers } from 'sinon';
		import type { SinonFakeTimers } from 'sinon';

Uh oh!

Conversation

aganglada commented Feb 16, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

ComplianceService (data service)

ComplianceController (controller)

Test coverage

References

Checklist

Uh oh!

Uh oh!

cryptodev-2s commented Feb 17, 2026

Uh oh!

cursor bot Feb 17, 2026

Choose a reason for hiding this comment

Case-sensitive address lookup may miss blocked wallets

Uh oh!

cryptodev-2s left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Feb 17, 2026

Choose a reason for hiding this comment

Batch compliance mapping assumes API preserves input ordering

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 18, 2026

Choose a reason for hiding this comment

Case-sensitive address matching bypasses OFAC compliance check

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aganglada commented Feb 16, 2026 •

edited by cursor bot

Loading

`ComplianceService` (data service)

`ComplianceController` (controller)