feat(ramps): adds ramps controller with geolocation state

[georgeweiler]

Explanation

This PR introduces a new @metamask/ramps-controller package that will provide functionality for managing cryptocurrency on/off ramps within MetaMask.

What's Included

RampsController

A controller that manages ramps-related state, currently focused on user geolocation:

• Stores the user's country code determined by IP-based geolocation
• Exposes an updateGeolocation() method that fetches and persists the user's geolocation
• State is persisted, included in debug snapshots, state logs, and exposed to the UI

OnRampService

A service class that handles API communication with the OnRamp backend:

• Supports multiple environments: Production, Staging, and Development
• Uses createServicePolicy from @metamask/controller-utils for resilient HTTP requests with:
  • Automatic retries (up to 4 attempts for 5xx errors)
  • Circuit breaker pattern
  • Degradation detection (requests taking >5 seconds)
• Exposes getGeolocation() method via messenger pattern
• Properly validates API responses

API Endpoints

• Production: https://on-ramp.api.cx.metamask.io
• Staging: https://on-ramp.uat-api.cx.metamask.io
• Development: http://localhost:3000

Architecture

The package follows the established controller/service patterns in the monorepo:

• Uses @metamask/base-controller for state management
• Uses @metamask/messenger for inter-controller communication
• The RampsController consumes the OnRampService via messenger actions
• Fully typed with TypeScript including proper action/event type exports

Files Added

File	Purpose
RampsController.ts	Main controller for ramps state management
OnRampService.ts	Service for OnRamp API interactions
OnRampService-method-action-types.ts	Type definitions for messenger actions
index.ts	Package exports
RampsController.test.ts	Controller tests with snapshot testing
OnRampService.test.ts	Service tests including retry/degradation scenarios

References

N/A - New package

Changelog

@metamask/ramps-controller

Added

• Initial release with RampsController for managing on/off ramps state
• OnRampService for interacting with the OnRamp API
• Geolocation detection via IP address lookup

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation for new or updated code as appropriate (N/A - README included)
• I've communicated my changes to consumers by updating changelogs for packages I've changed (N/A - new package)
• I've highlighted breaking changes using the "BREAKING" category above as appropriate (N/A)

References

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

Adds a new @metamask/ramps-controller package with RampsController and OnRampService (geolocation via API) and wires it into the monorepo.

• New package: @metamask/ramps-controller
  • RampsController: Manages ramps state; persists geolocation; exposes updateGeolocation().
  • OnRampService: API client with environments (production/staging/development), resilient policy (retries, circuit breaker, degradation); exposes messenger action OnRampService:getGeolocation.
  • Exports, TypeScript configs, Jest config, README, LICENSE, and CHANGELOG added.
• Monorepo integration
  • Added to README.md (package list and dependency graph), tsconfig*.json references, yarn.lock workspace.
  • Ownership and release mappings: .github/CODEOWNERS, teams.json.

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

[mcmire]

Had some suggestions below. Also, we have a relatively new package called core-backend and I'm curious if this service belongs there now or not.

[mcmire]

@Kriys94 What are your thoughts on this service? Do you think this ought to go in the core-backend package?

[georgeweiler]

Hey @mcmire, thanks for the review. This controller will be used for ramps client state, so I believe it makes sense to keep it here. I can see why core-backend might seem like a good fit though, since the controller currently only contains geolocation state.

Eventually, I'd like to extract the geolocation functionality into core-backend, but for now, I've included it here because it's a simple piece of state that requires an API service. This makes for a good initial boilerplate PR that establishes the pattern before we add the ramps state.

What do you think?