feat: transaction pay controller

.github/CODEOWNERS

@@ -27,6 +27,7 @@
 /packages/name-controller                   @MetaMask/confirmations
 /packages/signature-controller              @MetaMask/confirmations
 /packages/transaction-controller            @MetaMask/confirmations
+/packages/transaction-pay-controller        @MetaMask/confirmations
 /packages/user-operation-controller         @MetaMask/confirmations
 
 ## Delegation Team
@@ -150,6 +151,8 @@
 /packages/signature-controller/CHANGELOG.md       @MetaMask/confirmations @MetaMask/core-platform
 /packages/transaction-controller/package.json     @MetaMask/confirmations @MetaMask/core-platform
 /packages/transaction-controller/CHANGELOG.md     @MetaMask/confirmations @MetaMask/core-platform
+/packages/transaction-pay-controller/package.json @MetaMask/confirmations @MetaMask/core-platform
+/packages/transaction-pay-controller/CHANGELOG.md @MetaMask/confirmations @MetaMask/core-platform
 /packages/user-operation-controller/package.json  @MetaMask/confirmations @MetaMask/core-platform
 /packages/user-operation-controller/CHANGELOG.md  @MetaMask/confirmations @MetaMask/core-platform
 /packages/multichain-transactions-controller/package.json @MetaMask/accounts-engineers @MetaMask/core-platform

README.md

@@ -78,6 +78,7 @@ Each package in this repository has its own README where you can find installati
 - [`@metamask/subscription-controller`](packages/subscription-controller)
 - [`@metamask/token-search-discovery-controller`](packages/token-search-discovery-controller)
 - [`@metamask/transaction-controller`](packages/transaction-controller)
+- [`@metamask/transaction-pay-controller`](packages/transaction-pay-controller)
 - [`@metamask/user-operation-controller`](packages/user-operation-controller)
 
 <!-- end package list -->
@@ -146,6 +147,7 @@ linkStyle default opacity:0.5
   subscription_controller(["@metamask/subscription-controller"]);
   token_search_discovery_controller(["@metamask/token-search-discovery-controller"]);
   transaction_controller(["@metamask/transaction-controller"]);
+  transaction_pay_controller(["@metamask/transaction-pay-controller"]);
   user_operation_controller(["@metamask/user-operation-controller"]);
   account_tree_controller --> base_controller;
   account_tree_controller --> messenger;
@@ -346,6 +348,7 @@ linkStyle default opacity:0.5
   selected_network_controller --> network_controller;
   selected_network_controller --> permission_controller;
   shield_controller --> base_controller;
+  shield_controller --> controller_utils;
   shield_controller --> messenger;
   shield_controller --> signature_controller;
   shield_controller --> transaction_controller;
@@ -362,6 +365,7 @@ linkStyle default opacity:0.5
   subscription_controller --> controller_utils;
   subscription_controller --> messenger;
   subscription_controller --> polling_controller;
+  subscription_controller --> transaction_controller;
   subscription_controller --> profile_sync_controller;
   token_search_discovery_controller --> base_controller;
   token_search_discovery_controller --> messenger;
@@ -375,6 +379,15 @@ linkStyle default opacity:0.5
   transaction_controller --> gas_fee_controller;
   transaction_controller --> network_controller;
   transaction_controller --> remote_feature_flag_controller;
+  transaction_pay_controller --> controller_utils;
+  transaction_pay_controller --> messenger;
+  transaction_pay_controller --> assets_controllers;
+  transaction_pay_controller --> bridge_controller;
+  transaction_pay_controller --> bridge_status_controller;
+  transaction_pay_controller --> gas_fee_controller;
+  transaction_pay_controller --> network_controller;
+  transaction_pay_controller --> transaction_controller;
+  transaction_pay_controller --> remote_feature_flag_controller;
   user_operation_controller --> base_controller;
   user_operation_controller --> controller_utils;
   user_operation_controller --> messenger;

packages/transaction-pay-controller/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture
+
+The ultimate purpose of the `TransactionPayController` is to automatically provide ERC-20 or native tokens on the appropriate chains and accounts, in order to enable and simplify EVM transactions.
+
+This functionality is referred to as `MetaMask Pay` in the MetaMask clients.
+
+## Required Tokens
+
+The tokens required by a transaction are automatically identified from various sources, this includes:
+
+- ERC-20 Token Transfers
+  - Identified from the call data using the `0xa9059cbb` four-byte prefix.
+  - Supports EIP-7702 transactions where the token transfer is a nested call.
+- Gas Fees
+  - A required native token is generated from the gas limit and gas fee parameters, including estimates from the `GasFeeController`.
+
+See [required-tokens.ts](/packages/transaction-pay-controller/src/utils/required-tokens.ts).
+
+## Payment Token
+
+The payment token is the source ERC-20 or native token which will provide the funds for the transaction on the target chain.
+
+This can be selected by the user via the transaction confirmation in the client, or automatically selected based on the highest balance and chain.
+
+## Pay Strategies
+
+The mechanism by which the tokens are provided on the target chain is abstracted into a `PayStrategy`.
+
+Each `PayStrategy` dictates how the `quotes` are retrieved, which detail the associated fees and strategy specific data, and how those quotes are actioned or "submitted".
+
+### Bridge
+
+The `BridgeStrategy` bridges tokens from the payment our source token to the target chain.
+
+Quotes are retrieved from the MetaMask Bridge API via the `BridgeController`, then submitted using the `BridgeStatusController`.
+
+The `BridgeStatusController` generates suitable transactions via the `TransactionController` that target the MetaMask Bridge contract which in turn communicates with a specific Bridge provider according to the quote.
+
+### Relay
+
+The `RelayStrategy` also requires a payment or source token.
+
+Quotes are retrieved from the [Relay API](https://docs.relay.link/what-is-relay), then submitted via a transaction directly to the `TransactionController`.
+
+The resulting transaction deposits the necessary funds (on the source network), then a Relayer on the target chain immediately transfers the necessary funds and optionally executes any requested call data.
+
+## Lifecycle
+
+The high level interaction with the `TransactionPayController` is as follows:
+
+1. Client assigns the `TransactionPayPublishHook` as a publish hook in the `TransactionController` during initialisation.
+2. Controller subscribes to `TransactionController` state changes during initialisation.
+3. An unapproved transaction is created in a MetaMask client, either internally or via a dApp.
+4. Controller identifies any required tokens and adds them to its state.
+5. If a client confirmation is using `MetaMask Pay`, the user selects a payment token (or it is done automatically) which invokes the `updatePaymentToken` action.
+   - The below steps are also triggered if the transaction `data` is updated.
+6. Controller selects an appropriate `PayStrategy` using the `getStrategy` action.
+7. Controller requests quotes from the `PayStrategy` and persists them in state, including associated totals.
+8. Resulting fees and totals are presented in the client transaction confirmation.
+9. If approved by the user, the target transaction is signed and published.
+10. The `TransactionPayPublishHook` is invoked and submits the relevant quotes via the same `PayStrategy`.
+11. The hook waits for any transactions and quotes to complete.
+12. Depending on the pay strategy and required tokens, the original target transaction is also published as the required funds are now in place on the user's account on the target chain.
+13. Target transaction is finalized and any related controller state is removed.
+
+## State
+
+State is grouped according to the associated transaction ID in the `transactionData` property.
+
+This transaction specific data includes any required tokens, selected payment token, retrieved quotes, and calculated totals.

packages/transaction-pay-controller/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release ([#6820](https://github.com/MetaMask/core/pull/6820))
+
+[Unreleased]: https://github.com/MetaMask/core/

packages/transaction-pay-controller/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

packages/transaction-pay-controller/README.md

@@ -0,0 +1,19 @@
+# `@metamask/transaction-pay-controller`
+
+Manages alternate payment strategies to provide required funds for transactions in MetaMask.
+
+## Installation
+
+`yarn add @metamask/transaction-pay-controller`
+
+or
+
+`npm install @metamask/transaction-pay-controller`
+
+## Compatibility
+
+This package relies implicitly upon the `EventEmitter` module. This module is available natively in Node.js, but when using this package for the browser, make sure to use a polyfill such as `events`.
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

packages/transaction-pay-controller/jest.config.js

@@ -0,0 +1,26 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+const merge = require('deepmerge');
+const path = require('path');
+
+const baseConfig = require('../../jest.config.packages');
+
+const displayName = path.basename(__dirname);
+
+module.exports = merge(baseConfig, {
+  // The display name when running multiple projects
+  displayName,
+
+  // An object that configures minimum threshold enforcement for coverage results
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+});

packages/transaction-pay-controller/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@metamask/transaction-pay-controller",
+  "version": "0.0.0",
+  "description": "Manages alternate payment strategies to provide required funds for transactions in MetaMask",
+  "keywords": [
+    "MetaMask",
+    "Ethereum"
+  ],
+  "homepage": "https://github.com/MetaMask/core/tree/main/packages/transaction-pay-controller#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/core/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/core.git"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
+    "build:docs": "typedoc",
+    "changelog:update": "../../scripts/update-changelog.sh @metamask/transaction-pay-controller",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/transaction-pay-controller",
+    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
+    "publish:preview": "yarn npm publish --tag preview",
+    "since-latest-release": "../../scripts/since-latest-release.sh",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
+    "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
+    "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
+  },
+  "dependencies": {
+    "@ethersproject/abi": "^5.7.0",
+    "@ethersproject/contracts": "^5.7.0",
+    "@metamask/base-controller": "^9.0.0",
+    "@metamask/controller-utils": "^11.15.0",
+    "@metamask/messenger": "^0.3.0",
+    "@metamask/metamask-eth-abis": "^3.1.1",
+    "@metamask/utils": "^11.8.1",
+    "bignumber.js": "^9.1.2",
+    "bn.js": "^5.2.1",
+    "immer": "^9.0.6",
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "@metamask/assets-controllers": "^85.0.0",
+    "@metamask/auto-changelog": "^3.4.4",
+    "@metamask/bridge-controller": "^57.0.0",
+    "@metamask/bridge-status-controller": "^57.0.0",
+    "@metamask/gas-fee-controller": "^25.0.0",
+    "@metamask/network-controller": "^25.0.0",
+    "@metamask/remote-feature-flag-controller": "^2.0.0",
+    "@metamask/transaction-controller": "^61.0.0",
+    "@ts-bridge/cli": "^0.6.1",
+    "@types/jest": "^27.4.1",
+    "deepmerge": "^4.2.2",
+    "jest": "^27.5.1",
+    "ts-jest": "^27.1.4",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-missing-exports": "^2.0.0",
+    "typescript": "~5.2.2"
+  },
+  "peerDependencies": {
+    "@metamask/assets-controllers": "^85.0.0",
+    "@metamask/bridge-controller": "^57.0.0",
+    "@metamask/bridge-status-controller": "^57.0.0",
+    "@metamask/gas-fee-controller": "^25.0.0",
+    "@metamask/network-controller": "^25.0.0",
+    "@metamask/remote-feature-flag-controller": "^2.0.0",
+    "@metamask/transaction-controller": "^61.0.0"
+  },
+  "engines": {
+    "node": "^18.18 || >=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}