Repository navigation
feat(perps): mobile | Pro mode | Cross margin - #35831
Conversation
|
CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes. |
🧪 Flaky unit test detection✅ All previously detected unit test flakiness issues in this PR have been fixed. This check is informational only and does not block merging. |
|
Flaky-test detection triage for comment 5581571760, checked against
The separate typecheck failure remains the four missing |
## Explanation HyperLiquid order preparation currently always sends `isCross: false` when applying leverage. Add optional `OrderParams.marginMode: 'cross' | 'isolated'` and pass the explicit mode to standard and strategy order preparation. Callers that omit mode retain existing isolated behavior. Explicit requests require integer leverage and are checked before signing. Cross is rejected on isolated-only/restricted markets and HIP-3 markets while their collateral-transfer path assumes isolated margin. Fresh position/order reads reject changing an occupied asset's mode; matching-mode orders remain allowed. Lighter rejects explicit mode until it supports this contract. `MarketInfo.marginMode` preserves venue capability and new error codes let clients explain rejections. This is the controller prerequisite for a bounded Mobile position-display change, not completion of the TAT-3519 epic. Pro selection, account health/balance semantics, account-wide refresh, analytics and rollout remain follow-ups. No package version is preselected; a release containing this PR must be published before Mobile consumes it. Validation: full Core build and scoped ESLint passed; 692 tests passed across HyperLiquid advanced/strategy, Lighter and adapter suites, including coverage for explicit Cross, explicit isolated, omitted mode and rejection before signatures across trigger/TWAP/scale/chase orders. Scoped formatting and changelog validation passed. Standalone test-inclusive typecheck fails on project-reference/declaration resolution; it is not counted as passing. A fresh yalc build was linked into Mobile; its typecheck and 169 affected tests passed. On selected HyperLiquid testnet dev1, the Mobile controller opened real Cross ETH long/null and short/numeric liquidation positions. Pro/Lite recipes passed, including a recorded 37/37-action run. Both test positions were closed and ETH restored to isolated 3x. No mainnet mutation occurred. Independent cross-review completed after three rounds on `c99b20455291ff3247ff08b3cefd9fa6d0440fc4`: both reviewers approve with no remaining actionable nits. No new runtime validation bypass or omitted-mode regression was found. Keep this PR draft for operator review; release publication and consumer adoption remain separate steps. <!-- Thanks for your contribution! Take a moment to answer these questions so that reviewers have the information they need to properly understand your changes: * What is the current state of things and why does it need to change? * What is the solution your changes offer and how does it work? * Are there any changes whose purpose might not obvious to those unfamiliar with the domain? * If your primary goal was to update one package but you found you had to update another one along the way, why did you do so? * If you had to upgrade a dependency, why did you do so? --> ## References - Ticket: https://consensyssoftware.atlassian.net/browse/TAT-3519 - Dependent Mobile PR: MetaMask/metamask-mobile#35831 - Merge order: this PR → published `@metamask/perps-controller` release → Mobile dependency/lockfile update and release-package validation → Mobile merge. <!-- Are there any issues that this pull request is tied to? Are there other links that reviewers should consult to understand these changes better? Are there client or consumer pull requests to adopt any breaking changes? For example: * Fixes #12345 * Related to #67890 --> ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [x] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md) - [ ] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them **Breaking type change:** adding `ORDER_MARGIN_MODE_INVALID`, `ORDER_MARGIN_MODE_UNSUPPORTED`, `ORDER_MARGIN_MODE_POSITION_OPEN`, and `ORDER_MARGIN_MODE_ORDER_OPEN` expands `PerpsErrorCode`. Mobile and Extension consumers using exhaustive error maps must add all four entries when upgrading. The dependent Mobile draft includes these mappings; any other exhaustive consumers must migrate during release adoption. Runtime behavior for callers that omit `marginMode` is preserved. The checkbox remains unchecked because consumer migration beyond the prepared Mobile draft has not been completed. <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Changes HyperLiquid order preparation (leverage/margin mode) and adds venue-dependent validation on the signing path, plus a breaking expansion of `PerpsErrorCode` for consumers with exhaustive error maps. > > **Overview** > Adds optional **`OrderParams.marginMode`** (`'cross' | 'isolated'`, requires integer **`leverage`**) and exports **`MarginMode`**. Callers that omit **`marginMode`** keep prior isolated-leverage behavior; explicit requests run new pre-sign checks on HyperLiquid. > > **HyperLiquid** forwards the chosen mode to **`updateLeverage`** (`isCross`) for standard and strategy orders, exposes venue restriction on **`MarketInfo.marginMode`**, and validates unsupported Cross (isolated-only / restricted markets, HIP-3), open positions, resting orders, and active native TWAP schedules (including pre-first-fill) via fresh venue reads—failing closed when those reads fail. > > **Breaking:** four new **`PerpsErrorCode`** values for invalid/unsupported margin mode and blocked mode changes; exhaustive client error maps must add them. **Lighter** rejects any explicit **`marginMode`** with **`ORDER_MARGIN_MODE_UNSUPPORTED`** in validate and place paths. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit b52e623. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until this PR meets the canonical
Definition of Ready For Review in `docs/readme/ready-for-review.md`.
In short: the template must be materially complete (not just section
titles
present), all status checks must be currently passing, and the only
expected
follow-up commits must be reviewer-driven.
-->
<!--
mms-check directive vocabulary — read by
.github/scripts/shared/pr-template-checks.ts
at module load to build the validation plan. Directives are invisible in
rendered
markdown and must NOT be removed or edited without updating the
validator registry.
type=text Section must contain non-placeholder prose.
type=changelog Section must have a valid CHANGELOG entry: line.
type=issue-link Section must have a Fixes:/Closes:/Refs: line with a
value.
type=manual-testing Section must have real testing steps or an explicit
N/A.
type=screenshot Section must have evidence (image/URL) or an explicit
N/A.
type=checklist Section must have all checkboxes consciously checked.
required=true|false Whether a missing/invalid section runs the validator
at all.
blocking=true|false Whether a failure of this check fails the CI
workflow.
Default: false — failures are shown as warnings in the sticky
comment but do not block the PR.
Sections without a directive are checked for structural presence only.
-->
## **Description**
<!-- mms-check: type=text required=true -->
Bumps `@metamask/perps-controller` from 16.1.0 to 16.2.0 (Core release
1245.0.0).
16.2.0 adds optional HyperLiquid `OrderParams.marginMode`, four
`ORDER_MARGIN_MODE_*` error codes, a TWAP terminal-record fix, and
Lighter account/market fixes. Callers that omit `marginMode` stay on
isolated.
Mobile maps `PerpsErrorCode` exhaustively, so this PR adds the four new
codes to `ERROR_CODE_TO_I18N_KEY`, English copy, and
`translatePerpsErrorCoverage.test.ts`. It does not ship Pro cross-margin
UI (that is MetaMask#35831).
### Recipe validation
Verdict: pass
Proved:
- AC1: lockfile resolves `@metamask/perps-controller@16.2.0`
- AC2: bundled `perps.smoke` opened Perps Testnet, read positions/orders
(empty, no mutation), and `perps-market-list` was present
Gaps:
- iOS Runway only (`mm-1`). Android not run.
- First recipe run failed on Login/CDP after restart; relaunch +
fixtures recovered. Passing run is the proof.
## **Changelog**
<!-- mms-check: type=changelog required=true blocking=true -->
CHANGELOG entry: Added Perps error messages for invalid, unsupported,
and occupied-position/order margin modes
## **Related issues**
<!-- mms-check: type=issue-link required=true -->
Refs: MetaMask/core#10136
Jira: https://consensyssoftware.atlassian.net/browse/TAT-3519
## **Manual testing steps**
<!-- mms-check: type=manual-testing required=true -->
```gherkin
Feature: Perps controller 16.2.0 smoke
Scenario: Perps market list still loads after the bump
Given a Runway iOS build on mm-1 with the wallet fixture unlocked
And @metamask/perps-controller is 16.2.0
When the bundled perps.smoke recipe runs
Then the wallet unlocks if needed
And the Perps market list is present
And live positions and orders can be read without placing or cancelling anything
```
Platform: iOS simulator `mm-1`. Build: Runway expo-dev-client. Fixture:
existing 4-entry wallet. Perps testnet enabled.
## **Screenshots/Recordings**
<table>
<tr><td colspan="2"><strong>Recipe visual
evidence</strong><br/>Screenshots are grouped for quick reviewer
comparison.</td></tr>
<tr>
<td align="center" width="50%"><strong>Perps Testnet home after 16.2.0
smoke</strong><br/><img
src="https://raw.githubusercontent.com/abretonc7s/mm-mobile-artifacts/main/evidence/dev-update-perps-controller-smoke-2221/01-ui-screenshot-screenshot.png"
alt="Perps Testnet home after 16.2.0 smoke" width="400" /></td>
<td width="50%"></td>
</tr>
</table>
### **Before**
N/A. Dependency bump, no UI redesign.
### **After**
Perps Testnet home after the 16.2.0 smoke (recipe-backed).
## **Pre-merge author checklist**
<!-- mms-check: type=checklist required=true -->
- [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
- Considered; iOS Runway only for this bump
- [x] I've tested with a power user scenario
- Considered; not applicable (fixture wallet, non-mutating smoke)
- [x] I've instrumented key operations with Sentry traces for production
performance metrics
- Considered; not applicable (no new product operations)
For performance guidelines and tooling, see the [Performance
Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers).
## **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.
fc11c3e to
9e350ce
Compare
|
Rebased onto The Core dependency blocker is cleared. Post-rebase gate: scoped ESLint Flaky-detection findings from comment 5581571760 were re-verified independently against the rebased HEAD and the earlier dispositions hold: no empty The inherited runtime recipe was not re-run to completion: it gates on exactly one real open Cross position on the testnet account, and that account currently has none (the positions used for the original validation were closed at the end of that run). The gate fails before reaching any assertion on this PR's display code, and no branch commit touches the fixture, so it is environmental rather than a regression. |
|
Rebased onto Gate on the new base: scoped ESLint Review comments: no inline comments and no
Recipe re-validation: fails at the fixture precondition, before any assertion on this PR's code. The runtime verified healthy. The inherited recipe ran against the rebased HEAD: 5 of 6 nodes passed, confirming dev1, Hyperliquid and testnet, then
|
There was a problem hiding this comment.
Thanks for separating the existing position display work from Cross order entry. The Hyperliquid semantics are represented correctly: Cross collateral is shared, per position margin adjustment remains isolated only, and a null Cross liquidation price receives an explicit state.
I’m requesting changes for two user facing correctness issues and one false-positive privacy test: the new margin-mode error copy is shadowed by duplicate JSON keys, account and position margin values use the same label on one screen, and the Lite privacy test does not enable the Cross feature branch it claims to cover. I also left a nonblocking TypeScript comment where a double assertion bypasses an existing runtime validator.
After those items are addressed, the implementation and focused coverage support the intended Pro trader experience.
Cross position display had no feature flag of its own. It inherited only perpsEnabled, so the Lite and compact cards would have changed behaviour for every user on the existing Perps rollout as soon as this merged, with no way to roll back independently. There is no equivalent gate at the controller level either. Add selectPerpsCrossMarginEnabledFlag following the existing version-gated pattern (exported *_FLAG_KEY constant, validatedVersionGatedFeatureFlag, defaulting to false), and require it alongside the position type in all three components that branch on Cross. With the flag off, Cross positions render exactly as they did before this PR: no badge, no liquidation explanation, no "Margin used" label, and margin editing restored on the Lite card. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011r3KQHBoEwHLPXJutQ9uP4
The feature-flag registry check failed because perpsCrossMarginEnabled was referenced by the new selector but absent from the registry. Registered with inProd: false because the LaunchDarkly flag (perps-cross-margin-enabled) has not been created yet, and a disabled production default so E2E runs mirror the rolled-back state. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011r3KQHBoEwHLPXJutQ9uP4
…Darkly The flag now exists in LaunchDarkly with minimumVersion 8.11.0, not the 8.12.0 placeholder guessed before it was created. It is present in main/dev, main/rc and all flask environments, and still absent from main/prod, so inProd stays false and the production default stays disabled. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011r3KQHBoEwHLPXJutQ9uP4
- Deduplicate orderValidation marginMode* copy so the new strings reach users - Label Cross position collateral "Position margin used" to distinguish it from the account summary - Pass the raw flag value to validatedVersionGatedFeatureFlag without a double cast - Enable the Cross flag in the Lite privacy-masking test and assert unmasked text is absent Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2204c40 to
b111177
Compare
|
Addressed the review in
Validation: scoped ESLint Not covered this round: the numeric-liquidation fixture, Android, mixed-book grouping and account-wide refresh. |
main already registers perpsCrossMarginEnabled, so the branch entry made the registry object literal declare the key twice (TS1117) and failed lint:tsc. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
🔍 Smart E2E Test Selection
click to see 🤖 AI reasoning detailsE2E Test Selection: Performance Test Selection: |
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
❌ 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 322be6a. Configure here.
|
|
||
| return validatedVersionGatedFeatureFlag(remoteFlag) ?? false; | ||
| }, | ||
| ); |
There was a problem hiding this comment.
Cross flag selector lacks unit tests
Medium Severity
selectPerpsCrossMarginEnabledFlag is the client-only rollback gate for Cross UI, but it has no selector tests. Sibling flags such as selectPerpsMobileChaseEnabledFlag lock in default-off, version-gating, and malformed-payload behavior. Unit testing guidelines require happy-path and edge coverage for selectors; without that, a default flip to true would ship Cross badges, liquidation copy, and non-editable margin to the existing Perps rollout with no independent rollback.
Triggered by project rule: Unit Testing Guidelines
Reviewed by Cursor Bugbot for commit 322be6a. Configure here.
| ); | ||
|
|
||
| expect(queryByTestId('compact-margin-tag')).not.toBeOnTheScreen(); | ||
| }); |
There was a problem hiding this comment.
Compact Cross badge flag path untested
Medium Severity
PerpsCard shows a Cross badge when the flag is on and leverage.type === 'cross', but tests never turn the flag off for a Cross row. Pro and Lite detailed cards have that rollback case; the compact home/list row does not. Dropping the flag check would still pass both existing tests, so Cross badges could leak to the current Perps rollout with no independent rollback.
Additional Locations (1)
Triggered by project rule: Unit Testing Guidelines
Reviewed by Cursor Bugbot for commit 322be6a. Configure here.
|
|
| Platform | Device | Reason | Recording |
|---|---|---|---|
| Android | Google Pixel 8 Pro (v14.0) | no_performance_metrics | 📹 Watch |
🔬 App profiling check · Current run 35066221291 · Baseline (last green on main) run 34935384411 @ 4e14632
Summary:
ℹ️ API calls unavailable:
Network logs API error: Bad Request
Full metric table (+10% variance rules)
Disclaimer — allowed variance: a +10% margin over the baseline is permitted.
- If
Current <= Baseline + 10%, treated as acceptable noise.- If
Current > Baseline + 10%, Current and variance % are highlighted with⚠️ .
| Metric | Baseline | Current | Δ |
|---|---|---|---|
| CPU avg | 9.95% | 8.68% | -1.27 (-12.8%) |
| CPU max | 22.93% | 23.2% | +0.27 (+1.2%) |
| Memory avg | 702.75 MB | 709.49 MB | +6.74 (+1%) |
| Memory max | 877.25 MB | 813.35 MB | -63.9 (-7.3%) |
| Slow frames | 15.97% | 21.46% | +5.49 (+34.4%) |
| Frozen frames | 0% | 0% | 0 (0%) |
| ANRs | 0 | 0 | 0 (0%) |
| Issues | 2 | 2 | 0 (0%) |
| Critical issues | 1 | 1 | 0 (0%) |
| App size | 394.88 MB | 394.98 MB | +0.1 (+0%) |
Perps open position and close it
| Platform | Device | Reason | Recording |
|---|---|---|---|
| Android | Google Pixel 8 Pro (v14.0) | no_performance_metrics | 📹 Watch |
🔬 App profiling check · Current run 35066221291 · Baseline (last green on main) run 34966774120 @ acda9d8
Summary:
ℹ️ API calls unavailable:
Network logs API error: Bad Request
Full metric table (+10% variance rules)
Disclaimer — allowed variance: a +10% margin over the baseline is permitted.
- If
Current <= Baseline + 10%, treated as acceptable noise.- If
Current > Baseline + 10%, Current and variance % are highlighted with⚠️ .
| Metric | Baseline | Current | Δ |
|---|---|---|---|
| CPU avg | 8.17% | 8.82% | +0.65 (+8%) |
| CPU max | 25.69% | 23.05% | -2.64 (-10.3%) |
| Memory avg | 826.35 MB | 780.73 MB | -45.62 (-5.5%) |
| Memory max | 1069.37 MB | 988.09 MB | -81.28 (-7.6%) |
| Slow frames | 9.2% | 32% | +22.8 (+247.8%) |
| Frozen frames | 0% | 0% | 0 (0%) |
| ANRs | 0 | 0 | 0 (0%) |
| Issues | 2 | 3 | +1 (+50%) |
| Critical issues | 2 | 2 | 0 (0%) |
| App size | 394.9 MB | 394.98 MB | +0.08 (+0%) |
Branch: TAT-3519-feat-mobile-pro-cross-margin · Build: E2E · Commit: 97b6f6e · View full run





Description
Existing Cross positions now show an explicit "No liquidation price" state when Hyperliquid supplies null, and a shared-collateral explanation for both null and numeric prices. Lite and compact position cards gain a Cross badge, while detailed cards label collateral "Position margin used" and suppress margin editing.
What changes on screen
Perpetual positions can use isolated margin (collateral committed to that one position) or cross margin (collateral shared across all cross positions). Before this PR, existing Cross positions were rendered with isolated-position assumptions, which produced two concrete problems:
liquidationPrice: nullfor a cross position when, at the current account value, no liquidation price exists. That is meaningful information, not missing data.This PR makes both explicit:
CrossbadgemarginPress = isCross ? undefined : onMarginPressBoth explanations state that a liquidation can affect the entire cross balance, which is the risk that distinguishes cross from isolated.
Scope note: this is the existing-position display slice of TAT-3519. The Pro margin-mode picker stays disabled, so there is no user-facing Cross/isolated selector in this PR — the difference shipped here is how an already-open Cross position reads. Mixed-book grouping, compact rows and privacy masking are covered by component tests.
Core PR #10136 adds explicit
OrderParams.marginMode, validates venue capability and existing positions/orders before signing, and passes Cross toupdateLeverage. That dependency is now resolved: it merged and shipped in@metamask/perps-controller@16.2.0,mainpicked up the bump, and Mobile typecheck is clean against the released package — no yalc or file dependency is committed.Feature flag
Gated behind
perpsCrossMarginEnabled(LaunchDarkly:perps-cross-margin-enabled), version-gatedvia
validatedVersionGatedFeatureFlagand defaulting tofalse, consistent with the other perpsflags. There is no equivalent gate at the controller level, so the gate lives in the client.
Required in all three components that branch on Cross, alongside the position type:
With the flag off, a Cross position renders exactly as it did before this PR — no badge, no
liquidation explanation, no "Position margin used" label, and margin editing restored on the Lite card. Covered
by a dedicated flag-off test in both the Pro and Lite card suites.
This matters because
PerpsPositionCard/PerpsCardare the Lite/shared cards, not Pro-only:without their own flag they would have inherited just
perpsEnabledand changed behaviour foreveryone on the existing Perps rollout, with no independent rollback.
Changelog
CHANGELOG entry: Improved Cross position badges, liquidation explanations and margin labels.
Related issues
Refs: https://consensyssoftware.atlassian.net/browse/TAT-3519
Manual testing steps
Use current venue values for replay; funding can change numeric liquidation. Privacy masking, compact rows and isolated controls are covered by component tests. Android, mixed-book grouping and account-wide refresh were not exercised by this recipe.
Screenshots/Recordings
Live Hyperliquid testnet Cross ETH position (0.0051 @ 2394.1, leverage.type=cross, venue liquidationPx null) on dev1. Recipe passed 41/41 against the review-fix commit b111177, proving the renamed position-scoped label, the Cross badge, the explicit no-liquidation state and the shared-collateral explanation in both Pro and Lite. No before screenshot is claimed.
caption confidence: LOW — generic filename — no state-specific suffix
caption confidence: LOW — generic filename — no state-specific suffix
caption confidence: LOW — generic filename — no state-specific suffix
caption confidence: LOW — generic filename — no state-specific suffix
caption confidence: LOW — generic filename — no state-specific suffix
caption confidence: LOW — generic filename — no state-specific suffix
Validation Recipe
recipe.json, 42 nodes; validates live Cross display in Pro and Lite
{ "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json", "title": "Existing cross-position display in Lite and Pro", "description": "Requires exactly one real cross position on the selected account, so shared Pro selectors cannot match another market. Run separately for null and numeric liquidation fixtures. Asserts badges, venue liquidation display, explanation and non-editable Position margin used in Lite and Pro. No trades are created. Mixed-book, compact-row and privacy behavior require the later component tests; the remaining epic stays open. The null branch requires an existing falsy JSON field, excluding empty string, zero and false, because this pinned runner cannot express literal null in an atomic assertion.", "paramsSchema": { "type": "object", "additionalProperties": false, "properties": { "market": { "type": "string", "default": "ETH" }, "accountAddress": { "type": "string", "default": "0x8dc623e964475d4d669da601fd15ea9125469003" }, "liquidationPrice": { "type": "string", "default": "", "description": "Raw venue liquidation price; required to match the position when priceKind is numeric." }, "displayValue": { "type": "string", "default": "No liquidation price", "description": "The formatted venue price without distance, or No liquidation price. Pro matches the price within its distance-suffixed display; Lite matches exactly." }, "explanation": { "type": "string", "default": "At the current account value, this position has no liquidation price. This can change as the value of your other cross positions changes. A liquidation can affect your entire cross balance.", "description": "Exact localized tooltip copy for priceKind; supply the numeric explanation for numeric runs." }, "priceKind": { "type": "string", "enum": [ "null", "numeric" ], "default": "null" } } }, "workflow": { "entry": "wallet", "nodes": { "wallet": { "action": "metamask.wallet.read_state", "intent": "Verify the selected account before inspecting its positions", "next": "account" }, "account": { "action": "assert_output", "intent": "Require the intended account; never substitute another wallet", "source": "wallet", "assert": { "path": "$.account.address", "operator": "eq", "value": "{{params.accountAddress}}" }, "next": "unlock" }, "unlock": { "action": "metamask.wallet.ensure_unlocked", "intent": "Unlock the selected fixture wallet through its supported flow", "unlock_timeout_ms": 90000, "next": "environment" }, "positions": { "action": "command", "intent": "Read full live controller positions and compare their mode and liquidation price against the venue; the bundled read action omits these fields", "timeout_ms": 30000, "next": "require-cross" }, "require-cross": { "action": "assert_json", "intent": "Require exactly one live position so shared value selectors cannot match another market", "assert": { "path": "$.positions", "operator": "length_eq", "value": 1 }, "next": "require-cross-mode", }, "pro-open": { "action": "ui.navigate", "intent": "Open the cross market in pro mode", "page": "perps-market", "market": "{{params.market}}", "mode": "pro", "next": "pro-scroll" }, "pro-scroll": { "action": "ui.scroll", "intent": "Make the shared-collateral classification and margin amount visible for review", "test_id": "cross-margin-tag-pro-{{params.market}}", "scroll_into_view": true, "timeout_ms": 15000, "next": "pro-tag" }, "pro-tag": { "action": "ui.wait_for", "intent": "Require the cross margin badge in pro", "test_id": "cross-margin-tag-pro-{{params.market}}", "expected": "visible", "timeout_ms": 5000, "next": "pro-margin" }, "pro-price": { "action": "ui.wait_for", "intent": "Require the expected visible venue price or explicit no-price state", "text": "{{params.displayValue}}", "text_match": "contains", "expected": "visible", "timeout_ms": 5000, "next": "pro-position-capture", "test_id": "perps-pro-market-position-liq-price" }, "pro-margin": { "action": "ui.wait_for", "intent": "Require the position-scoped cross collateral label", "text": "Position margin used", "text_match": "contains", "expected": "visible", "timeout_ms": 5000, "next": "pro-no-edit" }, "pro-info": { "action": "ui.press", "intent": "Open the cross liquidation explanation", "test_id": "cross-liquidation-info-pro-{{params.market}}", "next": "pro-explanation" }, "pro-explanation": { "action": "ui.wait_for", "intent": "Require the shared-collateral explanation", "text": "{{params.explanation}}", "text_match": "exact", "expected": "visible", "timeout_ms": 5000, "next": "pro-capture", "test_id": "perps-bottom-sheet-tooltip-content" }, "pro-capture": { "action": "ui.screenshot", "intent": "Preserve the explanation that liquidation can affect the entire cross balance", "next": "pro-dismiss" }, "pro-dismiss": { "action": "ui.press", "intent": "Dismiss the explanation through its visible action", "test_id": "perps-bottom-sheet-tooltip-got-it-button", "next": "lite-open" }, "lite-open": { "action": "ui.navigate", "intent": "Open the cross market in lite mode", "page": "perps-market", "market": "{{params.market}}", "mode": "lite", "next": "lite-scroll" }, "lite-scroll": { "action": "ui.scroll", "intent": "Make the shared-collateral classification and margin amount visible for review", "test_id": "cross-margin-tag-lite-{{params.market}}", "scroll_into_view": true, "timeout_ms": 15000, "next": "lite-tag" }, "lite-tag": { "action": "ui.wait_for", "intent": "Require the cross margin badge in lite", "test_id": "cross-margin-tag-lite-{{params.market}}", "expected": "visible", "timeout_ms": 5000, "next": "lite-margin" }, "lite-price": { "action": "ui.wait_for", "intent": "Require the expected visible venue price or explicit no-price state", "text": "{{params.displayValue}}", "text_match": "exact", "expected": "visible", "timeout_ms": 5000, "next": "lite-position-capture", "test_id": "position-card-liquidation-price-value" }, "lite-margin": { "action": "ui.wait_for", "intent": "Require the position-scoped cross collateral label", "text": "Position margin used", "text_match": "contains", "expected": "visible", "timeout_ms": 5000, "next": "lite-no-edit" }, "lite-no-edit": { "action": "ui.wait_for", "intent": "Require the cross margin edit control to be absent from this single-position view", "test_id": "position-card-margin-chevron", "expected": "absent", "timeout_ms": 5000, "next": "lite-summary-capture" }, "lite-info": { "action": "ui.press", "intent": "Open the cross liquidation explanation", "test_id": "cross-liquidation-info-lite-{{params.market}}", "next": "lite-explanation" }, "lite-explanation": { "action": "ui.wait_for", "intent": "Require the shared-collateral explanation", "text": "{{params.explanation}}", "text_match": "exact", "expected": "visible", "timeout_ms": 5000, "next": "lite-capture", "test_id": "perps-bottom-sheet-tooltip-content" }, "lite-capture": { "action": "ui.screenshot", "intent": "Preserve the explanation that liquidation can affect the entire cross balance", "next": "lite-dismiss" }, "lite-dismiss": { "action": "ui.press", "intent": "Dismiss the explanation through its visible action", "test_id": "perps-bottom-sheet-tooltip-got-it-button", "next": "done" }, "done": { "action": "end", "status": "pass" }, "price-kind": { "action": "switch", "intent": "Choose the explicit no-price case or the supplied numeric venue-price case", "value": "{{params.priceKind}}", "equals": "null", "cases": { "match": "require-null-price" }, "default": "require-numeric-price" }, "require-null-price": { "action": "assert_json", "intent": "Require the venue liquidation field to be present", "assert": { "path": "$.positions[0].liquidationPrice", "operator": "exists" }, "next": "require-null-falsy", }, "require-numeric-price": { "action": "assert_json", "intent": "Require the expected venue liquidation value before comparing its UI rendering", "assert": { "path": "$.positions[0].liquidationPrice", "operator": "eq", "value": "{{params.liquidationPrice}}" }, "next": "pro-open", }, "pro-no-edit": { "action": "ui.wait_for", "intent": "Require the cross margin edit control to be absent from this single-position view", "test_id": "perps-pro-market-position-edit-margin", "expected": "absent", "timeout_ms": 5000, "next": "pro-summary-capture" }, "pro-scroll-price": { "action": "ui.scroll", "intent": "Make the liquidation value visible alongside its shared-collateral explanation control", "test_id": "cross-liquidation-info-pro-{{params.market}}", "scroll_into_view": true, "timeout_ms": 15000, "next": "pro-price" }, "pro-position-capture": { "action": "ui.screenshot", "intent": "Preserve the visible liquidation value and cross information affordance after their assertions", "next": "pro-info" }, "lite-scroll-price": { "action": "ui.scroll", "intent": "Make the liquidation value visible alongside its shared-collateral explanation control", "test_id": "cross-liquidation-info-lite-{{params.market}}", "scroll_into_view": true, "timeout_ms": 15000, "next": "lite-price" }, "lite-position-capture": { "action": "ui.screenshot", "intent": "Preserve the visible liquidation value and cross information affordance after their assertions", "next": "lite-info" }, "require-cross-mode": { "action": "assert_json", "intent": "Require shared collateral on the live position", "assert": { "path": "$.positions[0].leverage.type", "operator": "eq", "value": "cross" }, "next": "require-cross-market", }, "require-cross-market": { "action": "assert_json", "intent": "Require the live position to belong to the intended market", "assert": { "path": "$.positions[0].symbol", "operator": "eq", "value": "{{params.market}}" }, "next": "price-kind", }, "require-null-falsy": { "action": "assert_json", "intent": "Require an empty-valued liquidation field before ruling out non-null JSON values", "assert": { "path": "$.positions[0].liquidationPrice", "operator": "falsy" }, "next": "require-null-not-string", }, "require-null-not-string": { "action": "assert_json", "intent": "Reject an empty price string as a substitute for venue null", "assert": { "path": "$.positions[0].liquidationPrice", "operator": "ne", "value": "" }, "next": "require-null-not-zero", }, "require-null-not-zero": { "action": "assert_json", "intent": "Reject numeric zero as a substitute for venue null", "assert": { "path": "$.positions[0].liquidationPrice", "operator": "ne", "value": 0 }, "next": "require-null-not-false", }, "require-null-not-false": { "action": "assert_json", "intent": "Reject boolean false so only literal venue null passes", "assert": { "path": "$.positions[0].liquidationPrice", "operator": "ne", "value": false }, "next": "pro-open", }, "environment": { "action": "command", "intent": "Verify dev1, Hyperliquid and testnet before reading the real Cross fixture", "timeout_ms": 30000, "next": "positions" }, "pro-summary-capture": { "action": "ui.screenshot", "intent": "Preserve the visible Cross badge and Position margin used label after their assertions", "next": "pro-scroll-price" }, "lite-summary-capture": { "action": "ui.screenshot", "intent": "Preserve the visible Cross badge and Position margin used label after their assertions", "next": "lite-scroll-price" } } } }Validation Logs
Re-validated on the rebased branch (
origin/main@9e21342485). Both inherited fixtures werere-established as real testnet positions, because the recipe gates on one live Cross position and the
original validation closed its positions on completion.
leverage.typeliquidationPx59791500698crossnull59791614653cross125774.0984313725Cleanup: both closed (
59791593595,59791798948), leverage restored to theisolated 3xbaseline.Final inspect confirms 0 open positions.
Local gate (post-rebase): scoped ESLint
--max-warnings=0clean ·lint:tscexit 0 ·format:checkclean · working tree clean · Jest 5/5 suites, 110/110 tests.lint:tscpassing is the direct evidence the Core dependency is resolved: it is the first cleantypecheck since
mainbumped@metamask/perps-controllerto^16.2.0, which supplies the fourORDER_MARGIN_MODE_*constants that previously failed attranslatePerpsError.ts:77/79/81/83.Not covered: Android, mixed-book grouping, account-wide refresh, and the Pro margin-mode picker
(disabled in this slice).
Pre-merge author checklist
The performance items below were considered. This is an iOS display/controller prerequisite validation; Android and power-user performance profiling were not run, and no performance claim or new tracing was added. Draft status is retained pending Core release/dependency integration and operator review.
Performance checks (if applicable)
trace()for usage andaddTokenfor an exampleFor performance guidelines and tooling, see the Performance Guide.
Pre-merge reviewer checklist
Note
Medium Risk
User-facing perps risk and margin copy changes when the flag is on; rollout is gated and display-only, but incorrect liquidation messaging could mislead traders.
Overview
Adds Cross margin display for open cross positions behind the
perpsCrossMarginEnabledflag (defaults off). When the flag andleverage.type === 'cross'align, Lite (PerpsPositionCard), Pro (PerpsProPositionCard), and compact rows (PerpsCard) show a Cross badge, relabel collateral as Position margin used, and hide margin edit controls.Liquidation handling changes for cross positions: a null venue price shows No liquidation price instead of the generic fallback, and a new
PerpsCrossMarginInfoButtonopens bottom-sheet copy explaining shared cross collateral (with/without a numeric liquidation price). Tooltip keys, i18n, and stable test IDs (cross-margin-tag-*,cross-liquidation-info-*) support automation.Flag-off behavior is unchanged (isolated presentation). Tests and mocks cover cross vs isolated, privacy masking, and compact rows. Margin-mode validation error strings in
en.jsonare clarified.Reviewed by Cursor Bugbot for commit 322be6a. Bugbot is set up for automated code reviews on this repo. Configure here.