feat(client-utils): add activity mappers#9376
Open
n3ps wants to merge 7 commits into
Open
Conversation
n3ps
force-pushed
the
n3ps/client-shared-package
branch
from
5e9d190 to
077b222
Compare
n3ps
force-pushed
the
n3ps/client-shared-mappers
branch
from
7ab180a to
f86edbc
Compare
n3ps
force-pushed
the
n3ps/client-shared-package
branch
2 times, most recently
from
c04ad31 to
97ef77d
Compare
n3ps
force-pushed
the
n3ps/client-shared-mappers
branch
from
f86edbc to
9e724dc
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
n3ps
force-pushed
the
n3ps/client-shared-package
branch
from
9f7963e to
7a35be8
Compare
n3ps
changed the title
@metamask/client-shared@metamask/client-utils
n3ps
force-pushed
the
n3ps/client-shared-mappers
branch
from
9e724dc to
ae0bac9
Compare
n3ps
force-pushed
the
n3ps/client-shared-mappers
branch
from
ae0bac9 to
1a09b92
Compare
n3ps
force-pushed
the
n3ps/client-shared-mappers
branch
from
e4d60a2 to
67c8a92
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 24489af. Configure here.
n3ps
force-pushed
the
n3ps/client-shared-mappers
branch
3 times, most recently
from
1d4aed0 to
f91c847
Compare
Add the transaction activity mappers and shared activity types on top of the `@metamask/client-utils` package scaffold: - `mapApiTransaction` for mapping EVM API transactions to activity items - `mapKeyringTransaction` for mapping keyring transactions to activity items - `mapLocalTransaction` for mapping local transaction groups to activity items - Shared activity types (`ActivityItem`, `ActivityKind`, `Status`, etc.) Also adds the runtime dependencies these mappers require and comprehensive unit tests with fixtures. Co-authored-by: Cursor <cursoragent@cursor.com>
Permit2 `approve(token, spender, amount, expiration)` transactions are classified as `tokenMethodApprove`, but `txParams.to` is the Permit2 contract rather than the approved ERC-20. The mapper previously used `to` as the spending-cap token, so Permit2 approvals showed the wrong `assetId`/symbol. Detect the Permit2 approve selector and decode the approved token from the first calldata argument instead. Co-authored-by: Cursor <cursoragent@cursor.com>
On the buy path, getNftPaymentTransfer treated any outbound native (`normal`) transfer as the NFT payment, so an inbound NFT plus an unrelated native send in the same indexed transaction could be mapped as `nftBuy` instead of `receive`. Only count a sent transfer as payment when it goes to the NFT counterparty (direct sale) or to the contract being called (marketplace/router via `transaction.to`). Co-authored-by: Cursor <cursoragent@cursor.com>
Rather than decoding the approved token from Permit2 calldata, the local mapper now just classifies the activity as an approve and omits the token when `to` is the Permit2 contract. This keeps the local mapper thin — its job is to identify the ActivityKind — and defers accurate token data to the API mapper, which has richer information. Co-authored-by: Cursor <cursoragent@cursor.com>
The default contractInteraction path only attached `token` when `token.amount` was truthy, dropping symbol/direction/assetId when the value transfer had no amount. Attach the token whenever it is defined, since getTokenAmountFromTransfer only returns a token with meaningful metadata. Co-authored-by: Cursor <cursoragent@cursor.com>
The local mapper only needs to classify an incoming NFT with native value
as an nftBuy. Drop the placeholder `token: { direction: 'in' }` (no
symbol/assetId/amount) and let the API mapper provide token and payment
details.
Co-authored-by: Cursor <cursoragent@cursor.com>
mapApiTransaction classified a `wrap` on the WETH deposit selector plus any inbound transfer, without confirming transaction.to is the chain's wrapped-native contract (the local mapper already requires this via swapsWrappedTokensAddresses). Gate the wrap classification on transaction.to matching the chain's wrapped-native address. Co-authored-by: Cursor <cursoragent@cursor.com>
n3ps
force-pushed
the
n3ps/client-shared-mappers
branch
from
f91c847 to
f273ba4
Compare
n3ps
changed the title
@metamask/client-utils
NidhiKJha
approved these changes
Jul 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Explanation
Some client logic is currently duplicated across the MetaMask Extension and Mobile apps, including the activity view mappers and the number and currency formatting utilities.
The initial release of this package will include these shared functions extracted fromthe Activity list and details screens of mobile and extension:
mapApiTransaction- maps EVM transactions from@metamask/core-backendmapKeyringTransaction- maps non-EVM transactions from@metamask/keyring-apimapLocalTransaction- maps pending and local transactions from@metamask/transaction-controllerReferences
@metamask/client-utilspackage scaffold #9375, which added the@metamask/client-utilspackage scaffoldChecklist
Note
Medium Risk
Large new mapping surface drives how users see transaction history (amounts, types, NFT payments); misclassification would be user-visible, though logic is heavily tested and mostly additive in a new package.
Overview
Replaces the
@metamask/client-utilsplaceholder with shared activity mapping for Extension and Mobile: indexed EVM txs (mapApiTransaction), keyring txs (mapKeyringTransaction), and local/pending EVM groups (mapLocalTransaction), all emitting a unifiedActivityItemmodel (ActivityKind,Status, tokens, fees).The mappers encode category-specific behavior (send/receive, swaps, NFT buy/sell/mint, approvals, lending, wrap/unwrap, bridge, perps, mUSD, contract fallbacks) using helpers for CAIP asset ids, value-transfer parsing, fees, and mainnet token metadata. Runtime deps are added on
core-backend,transaction-controller,keyring-api, and related packages; README dependency graph is updated.Coverage is large fixture-driven Jest suites; tests note
mapApiTransactionvsmapLocalTransactioncan disagree on some stakes (e.g. Lido classified aslendingDepositvsdeposit).Reviewed by Cursor Bugbot for commit f273ba4. Bugbot is set up for automated code reviews on this repo. Configure here.