Skip to content

feat(transaction-pay-controller): send client header on Relay API requests - #11282

Merged
jpuri merged 4 commits into
mainfrom
feat/conf-2191-relay-client-header
Nov 4, 2026
Merged

jpuri merged 4 commits into
mainfrom
feat/conf-2191-relay-client-header

Conversation

@jpuri

@jpuri jpuri commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

#11259 added the X-Client-Id header so the Intents API could distinguish Mobile from Extension traffic. It wired the header into serverFetch, which covers the server strategy's three endpoints — but the relay strategy has its own fetch helper (relayFetch in strategy/relay/relay-api.ts) that was left untouched, so Relay requests still arrive unlabelled.

This gap is not theoretical. There are exactly three fetch() call sites in this package:

Module Endpoint Header before this PR
strategy/server/server-api.ts intents.api.cx.metamask.io Yes (#11259)
strategy/relay/relay-api.ts api.relay.link No
strategy/relay/hyperliquid-activation.ts Hyperliquid info API No (third-party, out of scope)

MetaMask Extension hardcodes getStrategy to TransactionPayStrategy.Relay (transaction-pay-controller-init.ts), so all of its MM Pay traffic goes through Relay. The Extension's companion PR passes clientId correctly, yet no header appeared on the wire — because the only path it exercises was the uncovered one. This was confirmed by inspecting live traffic from a money-account deposit.

Changes

  • Thread the messenger through relayFetch, so the header is injected at the single chokepoint shared by all three Relay endpoints (/quote, /execute, /status) rather than at each call site.
  • Reuse the exact getClientId helper shape from server-api.ts, including the try/catch so a missing messenger handler degrades to an unlabelled request instead of breaking payments.
  • Omit the header entirely when no clientId is configured, so existing consumers are unaffected.

Notes for reviewers

getRelayStatus signature change. It gains a leading messenger parameter. It is not exported from src/index.ts and has a single in-repo caller (relay-submit.ts, where messenger was already in scope), so this is internal-only and I have not marked it BREAKING. Flagging it explicitly in case you read the package boundary differently.

Relay is a third-party API. Unlike the Intents API, api.relay.link is not MetaMask-operated, so this sends a client identifier to an external service. No new information is disclosed beyond the existing extension/mobile distinction, and it is consistent with how X-Client-Id is already used elsewhere, but it is a deliberate decision rather than a mechanical omission fix — worth a conscious ack rather than a rubber stamp.

hyperliquid-activation.ts is intentionally untouched for the same third-party reason, and because it is an activation probe rather than a pay request.

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

Low Risk
Small, centralized HTTP header change with graceful fallback when clientId is missing; no payment logic or auth changes, though Relay (third-party) receives extension/mobile labels when configured.

Overview
Extends the optional clientId / X-Client-Id behavior from the intents API to Relay traffic on /quote, /execute, and /status, so Extension vs Mobile can be labeled on the path Extension actually uses for MM Pay.

relayFetch now takes the controller messenger, resolves the client id via TransactionPayController:getClientId, and merges X-Client-Id into request headers when configured. If no id is set or the messenger lookup throws, requests proceed without the header so payments are not blocked.

getRelayStatus gains a leading messenger argument (caller updated in relay-submit.ts); it remains internal to the package. Tests cover header present/absent and failed client-id lookup; the changelog documents the behavior.

Reviewed by Cursor Bugbot for commit 8b3a8cb. Bugbot is set up for automated code reviews on this repo. Configure here.

jpuri added a commit that referenced this pull request Nov 4, 2026
The changelog check requires Unreleased entries to link to the PR that
introduces them. The entry referenced #11259, the original client-header
PR this one follows up on, rather than #11282.
jpuri added 3 commits November 4, 2026 15:00
…uests

Core #11259 added the `X-Client-Id` header so the Intents API could tell
Mobile from Extension traffic, but only wired it into the `server`
strategy. The `relay` strategy has its own fetch helper and was left
unlabelled, so Relay requests still arrive anonymous.

This matters in practice because clients do not necessarily route
through `server`: MetaMask Extension hardcodes `TransactionPayStrategy
.Relay`, so none of its MM Pay traffic was carrying the header despite
the client passing `clientId`.

Thread the messenger through `relayFetch` so all three Relay endpoints
(`/quote`, `/execute`, `/status`) pick up the header from the single
chokepoint, mirroring `serverFetch`. The messenger lookup is wrapped in
try/catch so a missing handler degrades to an unlabelled request rather
than breaking payments, and the header is omitted entirely when no
`clientId` is configured.

`getRelayStatus` gains a leading `messenger` parameter. It is internal
and not exported from the package, so consumers are unaffected.
`yarn lint:tsc:check` failed because `EXECUTE_REQUEST_MOCK` was an
untyped object literal missing the required `metamask` property. The
repo tracks unsuppressed type errors by count, and the three tests added
in this branch took TS2741 from 2 suppressed occurrences to 5.

Rather than raise the suppression count, annotate the mock as
`RelayExecuteRequest` and supply `metamask`, which removes all five
occurrences and lets the two pre-existing TS2741 suppressions be pruned.

Also replace the `tradeType: 'EXPECTED_OUTPUT'` string literal with
`TradeType.ExactOutput`. `EXPECTED_OUTPUT` is not a member of the
`TradeType` enum, so it was silently wrong as well as untyped.
The changelog check requires Unreleased entries to link to the PR that
introduces them. The entry referenced #11259, the original client-header
PR this one follows up on, rather than #11282.
@jpuri
jpuri force-pushed the feat/conf-2191-relay-client-header branch from 8d83480 to 80b5fb3 Compare November 4, 2026 09:32
@jpuri
jpuri marked this pull request as ready for review November 4, 2026 09:32
@jpuri
jpuri requested review from a team as code owners November 4, 2026 09:32
@jpuri
jpuri enabled auto-merge November 4, 2026 09:32
@jpuri
jpuri temporarily deployed to default-branch November 4, 2026 09:32 — with GitHub Actions Inactive
@jpuri
jpuri added this pull request to the merge queue Nov 4, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 4, 2026
@jpuri
jpuri enabled auto-merge November 4, 2026 14:38
@jpuri
jpuri added this pull request to the merge queue Nov 4, 2026
Merged via the queue into main with commit b01ce30 Nov 4, 2026
153 of 154 checks passed
@jpuri
jpuri deleted the feat/conf-2191-relay-client-header branch November 4, 2026 14:48
weitingsun pushed a commit to Poovarasan-Sandhanam/metamask-mobile that referenced this pull request Nov 6, 2026
## **Description**

MM Pay requests did not identify which client they came from, so the
server could not tell Mobile traffic apart from Extension traffic.

[MetaMask/core#11259](MetaMask/core#11259) added
an optional `clientId` option to `TransactionPayController`, forwarded
as the `X-Client-Id` header on Intents API requests. That option is
deliberately optional, so it ships as a **no-op until each client opts
in**. This PR is the Mobile side of that opt-in, mirroring the Extension
PR
([MetaMask/metamask-extension#47607](MetaMask/metamask-extension#47607)).

Changes:

- Bump `@metamask/transaction-pay-controller` from `^30.3.1` to
`^30.4.2`.
- Pass `clientId: TransactionPayClientId.Mobile` when constructing
`TransactionPayController`, so requests send `X-Client-Id: mobile`.

That is the whole diff — two lines of source plus the lockfile.

### Header coverage: both `server` and Relay strategies

The original opt-in
([core#11259](MetaMask/core#11259), released in
`30.4.0`) only covered the `server` strategy (`POST /quote`, `POST
/submit`, `GET /status`). A follow-up
([core#11282](MetaMask/core#11282), released in
`30.4.1`) extended the same header to the Relay API (`/quote`,
`/execute`, `/status`).

Taking `30.4.2` rather than `30.4.0` means this single opt-in now
attributes **both** pay strategies, instead of leaving Relay traffic
unattributed and needing a second follow-up PR. No extra code is
required on the Mobile side — the same `clientId` option feeds both
paths.

`30.4.2` additionally treats an unreadable live payment-token balance as
unknown rather than insufficient, so a failing RPC no longer blocks a
transaction that is actually funded. Quote simulation and on-chain
execution still reject genuinely underfunded transactions. The
now-deprecated `balance-unavailable` `QuoteErrorReason` is not
referenced anywhere in this repo, so there is nothing to migrate.

### Previously in this PR, now handled by `main`

Earlier revisions of this branch also carried a root
`@metamask/core-backend` bump, a default `/v2/assets` E2E mock, and type
workarounds for duplicate `core-backend` copies. **All of that is gone**
— `main` landed the same changes in
[MetaMask#38819](MetaMask#38819)
(`assets-controller` `^20.2.2`, `assets-controllers` `^113.1.1`,
`core-backend` `^14.0.0`) plus its own `/v2/assets` mock, so merging
`main` made them redundant.

For context on why they were needed: `assets-controller` `20.2.1` added
a launchpad exemption to the unlock spam cleanup which calls
`TokenApiClient.fetchV2Assets`, a method that first ships in
`core-backend` `14.0.0`. Mobile injects its own client built from the
**root** `core-backend`, so while that root stayed on `^13.0.0` the call
threw, the cleanup failed closed and no spam tokens were removed. It
surfaced as five Appium Android smoke shards failing on a single
unmocked `/v2/assets` request. With `main` now on `core-backend`
`^14.0.0` and shipping the mock, the path works and this branch needs no
part of it.

The duplicate-`core-backend` type workarounds in
`assets-controller-init.ts`, `defi-positions-controller-v2-init.ts` and
`assets-controller-price.test.ts` were also dropped — `yarn lint:tsc` is
clean without them now that the root resolves `core-backend` 14.

## **Changelog**

CHANGELOG entry: null

<!--
Not end-user-facing: adds a request header used for server-side traffic
attribution. No UI or user-visible behaviour changes.
-->

## **Related issues**

Fixes:
[CONF-2191](https://consensyssoftware.atlassian.net/browse/CONF-2191)

Refs:
[MetaMask/core#11259](MetaMask/core#11259),
[MetaMask/core#11282](MetaMask/core#11282)
(extends the header to the Relay API, released in `30.4.1`),
[MetaMask/metamask-extension#47607](MetaMask/metamask-extension#47607)

## **Manual testing steps**

The change is only observable in outbound network traffic — there is no
UI surface. Verify with a proxy (Charles/Proxyman) or Flipper network
inspection.

```gherkin
Feature: MM Pay requests identify the client

  Scenario: user completes an MM Pay flow
    Given the app is built from this branch
    And a network proxy is attached to the device
    And the user has a funded wallet

    When user starts an MM Pay flow that requires a quote
    Then the outbound pay API request carries the header "X-Client-Id: mobile"

    When user submits the transaction
    Then the submit and status requests also carry "X-Client-Id: mobile"
    And the pay flow completes exactly as before

  Scenario: the Relay strategy is also attributed
    Given the app is built from this branch
    And a network proxy is attached to the device

    When user completes an MM Pay flow that routes through the Relay API
    Then the quote, execute and status requests carry "X-Client-Id: mobile"
```

Regression check: MM Pay quoting, submission and status polling should
be unchanged apart from the added header.

Regression check for the `30.4.2` balance change: with a funded wallet,
confirm a pay transaction still succeeds when the payment-token balance
RPC is slow or failing (the flow should proceed to quote simulation
rather than failing early), and that a genuinely underfunded transaction
is still rejected.

## **Screenshots/Recordings**

N/A — no UI changes. The only observable difference is an HTTP request
header.

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

#### Performance checks (if applicable)

- [x] I've tested on Android
- N/A — no runtime behaviour change; the diff adds one constructor
option and type-level casts.
- [x] I've tested with a power user scenario
  - N/A — change is independent of account/token volume.
- [x] I've instrumented key operations with Sentry traces for production
performance metrics
  - N/A — no new operations introduced.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.


[CONF-2191]:
https://consensyssoftware.atlassian.net/browse/CONF-2191?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches MM Pay outbound API configuration and assets/token cleanup
paths via core-backend and controller init; runtime impact is mostly a
new header plus keeping spam cleanup working on the bumped
assets-controller.
> 
> **Overview**
> Mobile opts into **MM Pay client attribution** by passing `clientId:
TransactionPayClientId.Mobile` when constructing
`TransactionPayController` (via `@metamask/transaction-pay-controller`
**^30.4.2**), so Intents and Relay requests include **`X-Client-Id:
mobile`**. Init tests assert `clientId` is `'mobile'`.
> 
> The dependency bump also pulls newer **assets-controller** behaviour
that needs **`@metamask/core-backend` ^14.0.0** on the app’s injected
API client (`fetchV2Assets` for launchpad-aware spam cleanup). Without
that bump, unlock spam cleanup would fail when the new exemption runs.
> 
> **Type-only wiring** for duplicate `core-backend` copies:
`assets-controller-init`, `defi-positions-controller-v2-init`, and the
price unit test derive client types from each
controller/`PriceDataSource` and cast `createApiPlatformClient` results
instead of importing `ApiPlatformClient` from the root package.
> 
> E2E API mocks add a **v2 `/assets`** stub (empty list) so launchpad
lookups don’t break tests after the assets-controller update.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
0a94d21. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
LabinatorSolutions pushed a commit to LabinatorSolutions/metamask-extension that referenced this pull request Nov 6, 2026
## **Description**

MM Pay requests to the Intents API did not identify which client they
came from, so the server could not tell Extension traffic apart from
Mobile traffic.

[MetaMask/core#11259](MetaMask/core#11259) added
an optional `clientId` option to `TransactionPayController`, which is
forwarded as the `X-Client-Id` header on Intents API requests. That
option is deliberately optional, so it ships as a **no-op until each
client opts in**. This PR is the Extension side of that opt-in.

`main` already resolves `@metamask/transaction-pay-controller` at
`^31.0.0` (which includes the `clientId` option and header coverage for
both the `server` and Relay strategies). This PR does **not** bump the
dependency.

**Change:** pass `clientId: TransactionPayClientId.Extension` when
constructing `TransactionPayController`, so Intents / Relay API requests
send `X-Client-Id: extension`. Unit test updated to assert the new
constructor argument.

Diff is two files only:
- `app/scripts/messenger-client-init/transaction-pay-controller-init.ts`
-
`app/scripts/messenger-client-init/transaction-pay-controller-init.test.ts`

## **Changelog**

CHANGELOG entry: null

<!--
Not end-user-facing: adds a request header used for server-side traffic
attribution. No UI or user-visible behaviour changes.
-->

## **Related issues**

Fixes:
[CONF-2191](https://consensyssoftware.atlassian.net/browse/CONF-2191)

Depends on:
[MetaMask/core#11259](MetaMask/core#11259)
(merged; `clientId` option) and
[MetaMask/core#11282](MetaMask/core#11282)
(merged; extends the header to the Relay API). Both are already in the
`^31.0.0` line that `main` resolves.

## **Manual testing steps**

The client ID change is only observable in outbound network requests —
there is no UI surface.

1. Build and run the extension with a wallet that has a funded balance.
2. Open the background service worker DevTools (`chrome://extensions` →
MetaMask → "service worker") and select the **Network** tab.
3. Start an MM Pay flow that routes through the Intents API
(`https://intents.api.cx.metamask.io`) — e.g. a deposit where the
payment token differs from the token required by the transaction, so a
cross-token quote is needed.
4. Find the request to `intents.api.cx.metamask.io/quote` and inspect
its **Request Headers**.
5. Verify `X-Client-Id: extension` is present.
6. Continue through to submitting the transaction and verify the same
header is present on `/submit` and on the `/status` polling requests.
7. Repeat with a flow that uses the **Relay** strategy and verify the
same header is present on its `/quote`, `/execute` and `/status`
requests.
8. Verify the pay flow itself still completes normally — quoting,
submission and status polling should be unchanged aside from the added
header.

<!--
## **Screenshots/Recordings**

### **Before**

### **After**
-->

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask
Extension Coding
Standards](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I’ve included tests if applicable
- [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I’ve applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.


[CONF-2191]:
https://consensyssoftware.atlassian.net/browse/CONF-2191?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Single constructor option for request-header attribution; pay flow
behavior on the extension side is unchanged aside from inherited
controller-package fixes from the dependency bump described in the PR.
> 
> **Overview**
> Extension MM Pay now **opts in** to client attribution by passing
**`clientId: TransactionPayClientId.Extension`** when wiring up
`TransactionPayController` in `transaction-pay-controller-init.ts`. That
value is forwarded by the controller as the **`X-Client-Id: extension`**
header on Intents (and Relay) API traffic so the backend can distinguish
Extension from Mobile.
> 
> The init unit test was updated to assert the new constructor argument
alongside the existing callbacks.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
71feea7. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants