feat(social-controllers): expose perp metadata on Position and Trade types#9094
Merged
Conversation
…ypes Adds optional Hyperliquid/perp fields to the `SocialService` response types and their superstruct validation schemas so consumers (mobile) get typed, validated access to the perp metadata that social-api now returns: - `Trade`: `classification`, `perpPositionType`, `perpLeverage` - `Position`: `perpPositionType`, `perpLeverage`, `positionAmountWithLeverage` All fields are optional and nullable, so spot responses remain backward compatible. Part of the Hyperliquid perps leaderboard/positions work (TSA-629). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
joaosantos15
temporarily deployed
to
default-branch
June 11, 2026 12:35 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
|
@metamaskbot publish-previews |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
5 tasks
zone-live
previously approved these changes
Jun 12, 2026
Bigshmow
previously approved these changes
Jun 15, 2026
…on type positionAmountWithLeverage is the leveraged/notional size as reported by Clicker; it is not necessarily positionAmount x perpLeverage (the ratio varies for positions built across fills at different leverage) and it is notional exposure, not capital at risk (the margin is costBasis). Correct the JSDoc so consumers use the field directly and treat perpLeverage as the authoritative leverage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
joaosantos15
enabled auto-merge
June 16, 2026 09:27
zone-live
approved these changes
Jun 16, 2026
pull Bot
pushed a commit
to Reality2byte/metamask-mobile
that referenced
this pull request
Jun 17, 2026
…28) (MetaMask#31570) ## **Description** Adds Hyperliquid (perps) support to the Social Leaderboard UI — the second step of the perps work, consuming the perp fields now exposed by `@metamask/social-controllers` and the social API. **What changed** - New shared primitives: a `PerpBadges` component (leverage pill + `LONG`/`SHORT` pill) and `utils/perp.ts` helpers (`isPerpPosition`/`isPerpTrade` + long/short direction resolution), so perp classification lives in one place. - `getPositionNetworkBadge` resolves the Hyperliquid network logo (HyperEVM image source) for the token avatar badge, without adding `hyperliquid` to `chainNameToId` (so the spot price/QuickBuy paths still treat it as unsupported). - **Trader profile** position rows show the HL network badge + leverage + long/short for perps; spot rows are unchanged. - **Position detail** header shows the same badges; trade rows read "opened/closed" with leverage + direction for perp fills. - The position detail footer swaps the single **Buy** CTA for **Long/Short** buttons on perps (intentional placeholders — not wired to a trade flow yet). The chart shows its existing no-data placeholder since perp pricing isn't available yet. - Pins `@metamask/social-controllers` to the perps preview build so the new `Position`/`Trade` perp fields are typed/available. **Motivation:** unblock the mobile Perps leaderboard/position UX (perp metadata was being dropped because the client types/UI didn't model it). **Perp PnL display corrections (audit follow-up — TSA-726)** - Position rows now render the **leveraged** size (`positionAmountWithLeverage`) for perps, so the displayed size, the leverage badge, and the (now leverage-correct) PnL coming from the API cohere. - `getPerpPositionDirection` no longer infers a side from the sign of `positionAmount` — Clicker reports perp size as a positive magnitude and conveys direction only via `perpPositionType`, so the sign is not a reliable signal (HL spot tokens can carry a negative amount with no side). It returns `null` when the side is absent, removing fabricated `LONG`/`SHORT` badges. Pairs with the server-side PnL fix in consensys-vertical-apps/va-mmcx-social-api#86. ## **Changelog** CHANGELOG entry: Added Hyperliquid perpetuals to the Social Leaderboard — trader profiles and position details now show leverage, long/short direction, and the Hyperliquid network badge. ## **Related issues** Fixes: TSA-628 Part of: TSA-726 (mobile display portion — perp PnL is computed server-side in consensys-vertical-apps/va-mmcx-social-api#86) Depends on: - MetaMask/core#9094 (`@metamask/social-controllers` perp fields — pinned here as a preview build until released) - consensys-vertical-apps/va-mmcx-social-api#86 (perp DTO passthrough + `chains=all` + gated perp notifications) ## **Manual testing steps** ```gherkin Feature: Hyperliquid perps in the Social Leaderboard Scenario: viewing a trader's perp positions Given a trader has open Hyperliquid perp positions When I open their profile in the Social Leaderboard Then each perp position shows the Hyperliquid network badge, its leverage (e.g. 5x), and LONG/SHORT And spot positions render unchanged Scenario: opening a perp position detail Given I am on a trader profile with a perp position When I tap that position Then the header shows the token with its leverage and long/short badges And the trades list shows "opened"/"closed" rows with leverage + direction And the footer shows Long and Short buttons (placeholders) instead of Buy And the chart shows the no-data placeholder ``` > Local setup: point `SOCIAL_API_URL` at a social-api running the perps branch (`va-mmcx-social-api#86`), which serves Hyperliquid positions via `chains=all`. ## **Screenshots/Recordings** ### **Before** Spot-only positions; no leverage/direction/HL badge. ### **After** _To be captured on-device before marking Ready for review_ — matches the approved designs (profile list with `5x LONG` / `8x SHORT` rows + HL badge, and the position detail with leverage/direction badges and Long/Short footer). ## **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 - [ ] 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. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Bigshmow <devin.stewart@consensys.net>
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
3 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
The mobile Perps leaderboard/position UX needs typed, validated access to the perp metadata that social-api now returns for Hyperliquid (and other perp) positions. Today
@metamask/social-controllersdrops those fields on the floor because they aren't declared on the response types or their superstruct schemas.This PR extends the
SocialServiceresponse types and validation schemas with the optional perp fields:Trade(andTradeStruct): addsclassification('spot' | 'perp' | 'send' | 'receive' | null),perpPositionType('long' | 'short' | null), andperpLeverage(number | null).Position(andPositionStruct): addsperpPositionType,perpLeverage, andpositionAmountWithLeverage(the leveraged/notional position size — Hyperliquid/perp only).All fields are optional and nullable, so spot responses validate exactly as before — this is a purely additive, non-breaking change. This is the client-side half of the Hyperliquid perps work; the matching server-side passthrough lives in social-api.
Audit follow-up (TSA-726): corrected the
positionAmountWithLeverageJSDoc — it is the leveraged/notional size as reported by Clicker (not necessarilypositionAmount × perpLeverage; the ratio varies across multi-fill positions) and is notional exposure, not capital at risk (the margin/capital at risk iscostBasis). This keeps consumers from mis-deriving leverage or risk from the field; the perp PnL fix that depends on this contract lives in consensys-vertical-apps/va-mmcx-social-api#86.References
positionAmountWithLeveragecontract used by the fix)Checklist
Note
Low Risk
Additive optional/nullable fields and stricter validation only when new perp keys are present; spot payloads without those fields behave as before.
Overview
Adds optional, nullable perp/Hyperliquid metadata to social position and trade models so
SocialServiceno longer strips fields the API already returns.Trade/TradeStructnow includeclassification(spot|perp|send|receive),perpPositionType, andperpLeverage.Position/PositionStructaddperpPositionType,perpLeverage, andpositionAmountWithLeverage(leveraged size / capital at risk). Matching superstruct rules onPositionStructvalidate these on open/closed positions andfetchPositionById.Tests cover passthrough of perp payloads, explicit
nullfor spot, and rejection of invalid enum values (e.g. badperpPositionType). Changelog documents the additive API surface for consumers (e.g. mobile Perps UI).Reviewed by Cursor Bugbot for commit a3e0ef7. Bugbot is set up for automated code reviews on this repo. Configure here.