Skip to content

docs(activity-mappers): expand cross-client guidance #187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
n3ps wants to merge 3 commits into
base: main
Choose a base branch
from
+54 −12
Open

docs(activity-mappers): expand cross-client guidance #187

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
81f036c
docs(activity-mappers): expand cross-client guidance
n3ps Sep 30, 2026
167d514
revised
n3ps Oct 7, 2026
75936bd
Merge branch 'main' into n3ps/update-activity-mappers
n3ps Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 54 additions & 12 deletions domains/ui/skills/activity-mappers/skill.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,63 @@ description: >-
or their data mapping.
---

# Activity Mappers
# Activity mapper guide

## When To Use
## When to use

- Changing the Activity List or Activity Item
- Changing the data used to render an Activity List or Activity Item
- Changing the Activity list, row, item, mapper, or a details template.
- Changing the Activity data, source precedence, filtering, or details routing.

## In Scope
## Workflow

- Extension: `ui/pages/activity`, `ui/pages/details`, `shared/lib/activity`
- Mobile: `app/components/views/Activity`, `app/components/views/ActivityDetails`, `app/util/activity-adapters`
1. Compare behavior with other MetaMask or wallet instances. If the issue is only in the local instance, look for any local-only implementation and try to revise/remove them. The preferred data source for EVM transactions is the Account Transactions API
2. Search closed Extension and Mobile issues and pull requests for similar Activity-related PRs.

## Workflow
3. Check whether `@metamask/client-utils` already maps the behavior.

4. For changes related to the Activity list, keep it within the mappers or selectors. For Activity Details, check the corresponding templates.
5. Add or update focused tests in the mapper, row, or details layer that owns the changed behavior.

## Start with the data source

| Source | Shared mapper |
| ---------------------------------- | ----------------------- |
| EVM transaction | `mapApiTransaction` |
| Non-EVM transaction | `mapKeyringTransaction` |
| Ramps order | `mapRampsOrder` |
| Pending and local-only transaction | `mapLocalTransaction` |

## Extension and Mobile reference

| Feature, function, or flow | Mobile | Extension |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Base Activity types and mappers | `@metamask/client-utils` provides `ActivityItem` and core mappers | `@metamask/client-utils` provides `ActivityItem` and core mappersts` |
| API activity mapping | Mobile fetch hooks map API and domain sources into one Activity shape. | `ui/pages/activity/useTransactionsQuery.ts` for lists. `mapApiTransaction` in `ui/pages/details/transaction-details.tsx` for details. |
| Non-EVM mapping | Mobile local adapters produce shared activity items for non-EVM sources. | `mapKeyringTransaction` in `ui/selectors/activity.ts`. |
| Local mapping | `enrich-local-activity.ts` enriches core-mapper output with local facts. | `selectLocalActivityItems` prepares mapper data. `ui/selectors/activity/enrich-local-activity.ts` adds Extension cases. |
| Bridge and swap enrichment | Uses bridge quotes and legacy swap metadata to derive status and token legs. | Bridge history in `ui/selectors/activity.ts`. |
| Source merge and deduplication | `adapters/dedup.ts` and list transformations prevent duplicate local, API, and domain rows. | `ui/pages/activity/helpers.ts` deduplicates, sorts, and groups rows. |
| Ramps mapping | `ramp-order.ts` and `ramps-order.ts` handle two Mobile order sources. | `ui/hooks/ramps/utils/mapRampsOrderSafely.ts` and `ui/selectors/rampsController/index.ts`. |
| Predict activity | `predict-activity.ts` maps prediction, cash-out, and claim entries. | No unified-list mapper or details template. |
| Fiat and token formatting | `fiat.ts` and `token-display.ts` format signed values and token amounts. | `shared/lib/activity/fiat.ts` and `ui/pages/activity/rows/useActivityRowContent.tsx`. |
| List transformations | `activity-list-helpers.ts` handles date grouping, source precedence, and display data. | `ui/pages/activity/helpers.ts` and `ui/pages/activity/query-filters`. |
| Activity list | `ActivityList.tsx` and source hooks unify local, API, Perps, Predict, and Ramps items. | `ui/pages/activity/activity-list.tsx` unifies local, API, non-EVM, and Ramps items. |
| Activity rows | `ActivityListItemRow.tsx`, layout, and icon helpers render rows. | `ui/pages/activity/rows/activity-row.tsx`, `activity-row-layout.tsx`, and `useActivityRowContent.tsx`. |
| Pending rows and actions | Pending row and actions present queued and pending activity. | `pending-activity-row.tsx` and `pending-transaction-actions.tsx`. |
| Details item lookup | `useActivityDetailsItem.ts` resolves cached, API, local, and domain items. | `transaction-details.tsx` resolves Ramps, API or local EVM, non-EVM, then API. |
| Details template dispatch | `TemplateLoader.tsx` dispatches generic and domain-specific templates. | `ui/pages/details/templates/template-loader.tsx`. |
| Details layout, amounts, status, and metadata | Mobile has reusable details frame, metadata, amount, fee, status, pending-banner, and footer components. | `ui/pages/details/components` plus templates. |

## Transaction details ownership

| Transaction details group | Detail files | Domain team to involve |
| ----------------------------------------------- | -------------------------------------------------------- | ----------------------------- |
| Shared mappers and generic Activity componentss | `pages/activity`, `pages/details` | `@MetaMask/core-extension-ux` |
| Swap and Bridge | `pages/details/templates/bridge-details` | `@MetaMask/swaps-engineers` |
| Perps | `pages/details/templates/perps-details.tsx` | `@MetaMask/perps` |
| Money Account and MetaMask Pay | `money-account-details.tsx`, `mm-pay-details-layout.tsx` | `@MetaMask/earn` |
| Ramps orders | `ui/pages/details/templates/ramps` | `@MetaMask/money-movement` |

##

1. Start in [`@metamask/client-utils/mappers`](https://github.com/MetaMask/core/tree/main/packages/client-utils/src/mappers).
2. Prefer data from the API. For non-EVM activity, use the keyring transaction.
3. Avoid massaging local state because it does not exist in other instances.
4. Add or update the unit tests in the mappers package.
##