Skip to content

Commit 4d0ac75

Browse files
matthewwalsh0matthewwalsh0
committed
Add transaction pay controller
1 parent cfaf095 commit 4d0ac75

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+8992
-1
lines changed

‎.github/CODEOWNERS‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
/packages/name-controller @MetaMask/confirmations
2828
/packages/signature-controller @MetaMask/confirmations
2929
/packages/transaction-controller @MetaMask/confirmations
30+
/packages/transaction-pay-controller @MetaMask/confirmations
3031
/packages/user-operation-controller @MetaMask/confirmations
3132

3233
## Delegation Team
@@ -150,6 +151,8 @@
150151
/packages/signature-controller/CHANGELOG.md @MetaMask/confirmations @MetaMask/core-platform
151152
/packages/transaction-controller/package.json @MetaMask/confirmations @MetaMask/core-platform
152153
/packages/transaction-controller/CHANGELOG.md @MetaMask/confirmations @MetaMask/core-platform
154+
/packages/transaction-pay-controller/package.json @MetaMask/confirmations @MetaMask/core-platform
155+
/packages/transaction-pay-controller/CHANGELOG.md @MetaMask/confirmations @MetaMask/core-platform
153156
/packages/user-operation-controller/package.json @MetaMask/confirmations @MetaMask/core-platform
154157
/packages/user-operation-controller/CHANGELOG.md @MetaMask/confirmations @MetaMask/core-platform
155158
/packages/multichain-transactions-controller/package.json @MetaMask/accounts-engineers @MetaMask/core-platform

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ Each package in this repository has its own README where you can find installati
7878
- [`@metamask/subscription-controller`](packages/subscription-controller)
7979
- [`@metamask/token-search-discovery-controller`](packages/token-search-discovery-controller)
8080
- [`@metamask/transaction-controller`](packages/transaction-controller)
81+
- [`@metamask/transaction-pay-controller`](packages/transaction-pay-controller)
8182
- [`@metamask/user-operation-controller`](packages/user-operation-controller)
8283

8384
<!-- end package list -->
@@ -146,6 +147,7 @@ linkStyle default opacity:0.5
146147
subscription_controller(["@metamask/subscription-controller"]);
147148
token_search_discovery_controller(["@metamask/token-search-discovery-controller"]);
148149
transaction_controller(["@metamask/transaction-controller"]);
150+
transaction_pay_controller(["@metamask/transaction-pay-controller"]);
149151
user_operation_controller(["@metamask/user-operation-controller"]);
150152
account_tree_controller --> base_controller;
151153
account_tree_controller --> messenger;
@@ -346,6 +348,7 @@ linkStyle default opacity:0.5
346348
selected_network_controller --> network_controller;
347349
selected_network_controller --> permission_controller;
348350
shield_controller --> base_controller;
351+
shield_controller --> controller_utils;
349352
shield_controller --> messenger;
350353
shield_controller --> signature_controller;
351354
shield_controller --> transaction_controller;
@@ -362,6 +365,7 @@ linkStyle default opacity:0.5
362365
subscription_controller --> controller_utils;
363366
subscription_controller --> messenger;
364367
subscription_controller --> polling_controller;
368+
subscription_controller --> transaction_controller;
365369
subscription_controller --> profile_sync_controller;
366370
token_search_discovery_controller --> base_controller;
367371
token_search_discovery_controller --> messenger;
@@ -375,6 +379,15 @@ linkStyle default opacity:0.5
375379
transaction_controller --> gas_fee_controller;
376380
transaction_controller --> network_controller;
377381
transaction_controller --> remote_feature_flag_controller;
382+
transaction_pay_controller --> controller_utils;
383+
transaction_pay_controller --> messenger;
384+
transaction_pay_controller --> assets_controllers;
385+
transaction_pay_controller --> bridge_controller;
386+
transaction_pay_controller --> bridge_status_controller;
387+
transaction_pay_controller --> gas_fee_controller;
388+
transaction_pay_controller --> network_controller;
389+
transaction_pay_controller --> transaction_controller;
390+
transaction_pay_controller --> remote_feature_flag_controller;
378391
user_operation_controller --> base_controller;
379392
user_operation_controller --> controller_utils;
380393
user_operation_controller --> messenger;

‎packages/transaction-pay-controller/ARCHITECTURE.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Architecture
2+
3+
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.
4+
5+
This functionality is referred to as `MetaMask Pay` in the MetaMask clients.
6+
7+
## Required Tokens
8+
9+
The tokens required by a transaction are automatically identified from various sources, this includes:
10+
11+
- ERC-20 Token Transfers
12+
- Identified from the call data using the `0xa9059cbb` four-byte prefix.
13+
- Supports EIP-7702 transactions where the token transfer is a nested call.
14+
- Gas Fees
15+
- A required native token is generated from the gas limit and gas fee parameters, including estimates from the `GasFeeController`.
16+
17+
See [required-tokens.ts](/packages/transaction-pay-controller/src/utils/required-tokens.ts).
18+
19+
## Payment Token
20+
21+
The payment token is the source ERC-20 or native token which will provide the funds for the transaction on the target chain.
22+
23+
This can be selected by the user via the transaction confirmation in the client, or automatically selected based on the highest balance and chain.
24+
25+
## Pay Strategies
26+
27+
The mechanism by which the tokens are provided on the target chain is abstracted into a `PayStrategy`.
28+
29+
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".
30+
31+
### Bridge
32+
33+
The `BridgeStrategy` bridges tokens from the payment our source token to the target chain.
34+
35+
Quotes are retrieved from the MetaMask Bridge API via the `BridgeController`, then submitted using the `BridgeStatusController`.
36+
37+
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.
38+
39+
### Relay
40+
41+
The `RelayStrategy` also requires a payment or source token.
42+
43+
Quotes are retrieved from the [Relay API](https://docs.relay.link/what-is-relay), then submitted via a transaction directly to the `TransactionController`.
44+
45+
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.
46+
47+
## Lifecycle
48+
49+
The high level interaction with the `TransactionPayController` is as follows:
50+
51+
1. Client assigns the `TransactionPayPublishHook` as a publish hook in the `TransactionController` during initialisation.
52+
2. Controller subscribes to `TranasctionController` state changes during initialisation.
53+
3. An unapproved transaction is created in a MetaMask client, either internally or via a dApp.
54+
4. Controller identifies any required tokens and adds them to its state.
55+
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.
56+
- The below steps are also triggered if the transaction `data` is updated.
57+
6. Controller selects an appropriate `PayStrategy` using the `getStrategy` action.
58+
7. Controller requests quotes from the `PayStrategy` and persists them in state, including associated totals.
59+
8. Resulting fees and totals are presented in the client transaction confirmation.
60+
9. If approved by the user, the target transaction is signed and published.
61+
10. The `TransactionPayPublishHook` is invoked and submits the relevant quotes via the same `PayStrategy`.
62+
11. The hook waits for any transactions and quotes to complete.
63+
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.
64+
13. Target transaction is finalized and any related controller state is removed.
65+
66+
## State
67+
68+
State is grouped according to the associated transaction ID in the `transactionData` property.
69+
70+
This transaction specific data includes any required tokens, selected payment token, retrieved quotes, and calculated totals.

‎packages/transaction-pay-controller/CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Initial release ([#6820](https://github.com/MetaMask/core/pull/6820))
13+
14+
[Unreleased]: https://github.com/MetaMask/core/

‎packages/transaction-pay-controller/LICENSE‎

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

‎packages/transaction-pay-controller/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# `@metamask/transaction-pay-controller`
2+
3+
Manages alternate payment strategies to provide required funds for transactions in MetaMask.
4+
5+
## Installation
6+
7+
`yarn add @metamask/transaction-pay-controller`
8+
9+
or
10+
11+
`npm install @metamask/transaction-pay-controller`
12+
13+
## Compatibility
14+
15+
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`.
16+
17+
## Contributing
18+
19+
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‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
/*
2+
* For a detailed explanation regarding each configuration property and type check, visit:
3+
* https://jestjs.io/docs/configuration
4+
*/
5+
6+
const merge = require('deepmerge');
7+
const path = require('path');
8+
9+
const baseConfig = require('../../jest.config.packages');
10+
11+
const displayName = path.basename(__dirname);
12+
13+
module.exports = merge(baseConfig, {
14+
// The display name when running multiple projects
15+
displayName,
16+
17+
// An object that configures minimum threshold enforcement for coverage results
18+
coverageThreshold: {
19+
global: {
20+
branches: 100,
21+
functions: 100,
22+
lines: 100,
23+
statements: 100,
24+
},
25+
},
26+
});

‎packages/transaction-pay-controller/package.json‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
{
2+
"name": "@metamask/transaction-pay-controller",
3+
"version": "0.0.0",
4+
"description": "Manages alternate payment strategies to provide required funds for transactions in MetaMask",
5+
"keywords": [
6+
"MetaMask",
7+
"Ethereum"
8+
],
9+
"homepage": "https://github.com/MetaMask/core/tree/main/packages/transaction-pay-controller#readme",
10+
"bugs": {
11+
"url": "https://github.com/MetaMask/core/issues"
12+
},
13+
"repository": {
14+
"type": "git",
15+
"url": "https://github.com/MetaMask/core.git"
16+
},
17+
"license": "MIT",
18+
"sideEffects": false,
19+
"exports": {
20+
".": {
21+
"import": {
22+
"types": "./dist/index.d.mts",
23+
"default": "./dist/index.mjs"
24+
},
25+
"require": {
26+
"types": "./dist/index.d.cts",
27+
"default": "./dist/index.cjs"
28+
}
29+
},
30+
"./package.json": "./package.json"
31+
},
32+
"main": "./dist/index.cjs",
33+
"types": "./dist/index.d.cts",
34+
"files": [
35+
"dist/"
36+
],
37+
"scripts": {
38+
"build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
39+
"build:docs": "typedoc",
40+
"changelog:update": "../../scripts/update-changelog.sh @metamask/transaction-pay-controller",
41+
"changelog:validate": "../../scripts/validate-changelog.sh @metamask/transaction-pay-controller",
42+
"prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
43+
"publish:preview": "yarn npm publish --tag preview",
44+
"since-latest-release": "../../scripts/since-latest-release.sh",
45+
"test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
46+
"test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
47+
"test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
48+
"test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
49+
},
50+
"dependencies": {
51+
"@ethersproject/abi": "^5.7.0",
52+
"@ethersproject/contracts": "^5.7.0",
53+
"@metamask/base-controller": "^9.0.0",
54+
"@metamask/controller-utils": "^11.14.1",
55+
"@metamask/messenger": "^0.3.0",
56+
"@metamask/metamask-eth-abis": "^3.1.1",
57+
"@metamask/utils": "^11.8.1",
58+
"bignumber.js": "^9.1.2",
59+
"bn.js": "^5.2.1",
60+
"immer": "^9.0.6",
61+
"lodash": "^4.17.21"
62+
},
63+
"devDependencies": {
64+
"@metamask/assets-controllers": "^84.0.0",
65+
"@metamask/auto-changelog": "^3.4.4",
66+
"@metamask/bridge-controller": "^56.0.3",
67+
"@metamask/bridge-status-controller": "^56.0.0",
68+
"@metamask/gas-fee-controller": "^25.0.0",
69+
"@metamask/network-controller": "^25.0.0",
70+
"@metamask/remote-feature-flag-controller": "^2.0.0",
71+
"@metamask/transaction-controller": "^61.0.0",
72+
"@ts-bridge/cli": "^0.6.1",
73+
"@types/jest": "^27.4.1",
74+
"deepmerge": "^4.2.2",
75+
"jest": "^27.5.1",
76+
"ts-jest": "^27.1.4",
77+
"typedoc": "^0.24.8",
78+
"typedoc-plugin-missing-exports": "^2.0.0",
79+
"typescript": "~5.2.2"
80+
},
81+
"peerDependencies": {
82+
"@metamask/assets-controllers": "^84.0.0",
83+
"@metamask/bridge-controller": "^56.0.0",
84+
"@metamask/bridge-status-controller": "^56.0.0",
85+
"@metamask/gas-fee-controller": "^25.0.0",
86+
"@metamask/network-controller": "^25.0.0",
87+
"@metamask/remote-feature-flag-controller": "^2.0.0",
88+
"@metamask/transaction-controller": "^61.0.0"
89+
},
90+
"engines": {
91+
"node": "^18.18 || >=20"
92+
},
93+
"publishConfig": {
94+
"access": "public",
95+
"registry": "https://registry.npmjs.org/"
96+
}
97+
}

0 commit comments

Comments
 (0)