fix(perps): use USD as source of truth for order precision and validation cp-7.59.0

[abretonc7s]

Description

This PR implements a major refactor of the Perps order handling system to address precision and validation issues. The changes establish USD as the primary source of truth for order amounts, replacing the complex findOptimalAmount optimization logic with a simpler, more robust approach that recalculates position sizes at execution time using fresh market prices.

Key Changes

1. Migration from findOptimalAmount to USD-as-Source-of-Truth

Previous Approach:

• Used findOptimalAmount function to find the "optimal" USD amount that maximized value while maintaining the same position size
• Performed complex calculations with position size increments and rounding
• Optimized order amounts on every input change (percentage, slider, keypad, etc.)
• Position size was calculated once in the UI and used directly for order placement

New Approach:

• USD amount is now the primary source of truth - stored and validated as entered by user
• Position size is recalculated at execution time with the freshest available price
• Eliminates complex optimization logic (~150 lines removed from orderCalculations.ts)
• Simplified order form handling (~71 lines removed from usePerpsOrderForm.ts)

Benefits:

• Eliminates edge cases where optimization could produce invalid orders
• Reduces computational overhead on every input change
• More predictable behavior - what user enters is what gets validated and executed
• Better handling of price volatility during order placement

2. Standardized Slippage Management

New Configuration:

export const ORDER_SLIPPAGE_CONFIG = {
  DEFAULT_SLIPPAGE_BPS: 100, // 100 basis points = 1%
} as const;

Improvements:

• Unified slippage configuration using basis points for consistency
• Added price staleness validation to prevent execution with stale prices
• New priceAtCalculation and maxSlippageBps fields in OrderParams
• Provider validates price hasn't moved beyond tolerance before execution
• Standardized slippage across market orders, position closing, and TP/SL orders

Slippage Validation Example:

// Provider checks price delta before order execution
const priceDeltaBps = Math.abs(
  ((currentPrice - priceAtCalculation) / priceAtCalculation) * 10000
);
if (priceDeltaBps > maxSlippageBps) {
  throw new Error(`Price moved too much: ${priceDeltaBps} bps`);
}

3. Enhanced Order Validation

Validation Improvements:

• USD as source of truth for minimum validation - validates user's exact USD input without recalculation
  • Example: User enters $10 → validates $10 directly (no rounding errors)
  • For full position closes (e.g., Close All), minimum validation is skipped
• Added skipValidation flag to prevent validation flash during keypad input
• Enhanced limit order validation to require price parameter

Type System Updates:

export type OrderParams = {
  // Existing fields...
  size: string; // Now derived, provider recalculates from usdAmount

  // New hybrid approach fields
  usdAmount?: string; // Primary source of truth
  priceAtCalculation?: number; // For slippage validation
  maxSlippageBps?: number; // Slippage tolerance (e.g., 100 = 1%)

  // Updated documentation
  slippage?: number; // Now defaults to ORDER_SLIPPAGE_CONFIG.DEFAULT_SLIPPAGE_BPS / 10000
};

4. Close Position Validation & Precision

Problem Addressed:

• Close positions were failing with "Minimum order size is $10" even when closing 100% of small positions (e.g., closing a $5.23 position)
• Close position calculations used hardcoded decimal precision (6 decimals) instead of asset-specific szDecimals
• As part of the USD-as-source-of-truth refactor, close position calculations needed the same precision improvements as order placement

Solution - Full vs Partial Close Distinction:

Full Position Close (100%):

• Added isFullClose flag to OrderParams type
• Set automatically when size parameter is omitted: isFullClose: !params.size
• Skips USD validation and $10 minimum entirely
• Allows closing positions of any size (e.g., $5.23 position)

Partial Position Close:

• Still enforces $10 minimum validation
• Uses same USD validation logic as new orders
• Requires currentPrice or usdAmount for validation

Close Amount Calculation Refactor:

• Migrated calculateCloseAmountFromPercentage to USD as source of truth
• Added required szDecimals parameter (removed dangerous defaults)
• Implemented post-rounding USD validation:

  const actualUsd = tokenAmount * currentPrice;
  if (actualUsd < usdValue) {
    tokenAmount += 1 / multiplier; // Add 1 minimum increment
  }

• Now matches calculatePositionSize logic for consistency

Type Changes:

export type OrderParams = {
  // ... existing fields
  isFullClose?: boolean; // Indicates closing 100% of position (skips validation)
};

// calculateCloseAmountFromPercentage now requires szDecimals
interface CloseAmountFromPercentageParams {
  percentage: number;
  positionSize: number;
  currentPrice: number;
  szDecimals: number; // REQUIRED - no longer optional
}

Files Changed:

• controllers/types/index.ts - Added isFullClose flag
• utils/positionCalculations.ts - Refactored to use USD as source of truth with asset-specific precision
• Views/PerpsClosePositionView/PerpsClosePositionView.tsx - Added szDecimals handling with loading state
• controllers/providers/HyperLiquidProvider.ts - Updated validation to skip minimum for full closes

5. Position Size Calculation Changes

Rounding Behavior:

• Changed from Math.floor to Math.round in calculatePositionSize
• More accurate position size calculation that rounds to nearest value
• Aligned with provider's recalculation logic for consistency

Provider-Side Recalculation:

// In HyperLiquidProvider.placeOrder()
if (params.usdAmount && parseFloat(params.usdAmount) > 0) {
  const usdAmount = parseFloat(params.usdAmount);

  // Recalculate with fresh price
  finalPositionSize = usdAmount / currentPrice;

  // Apply same rounding as UI
  const multiplier = Math.pow(10, assetInfo.szDecimals);
  finalPositionSize = Math.round(finalPositionSize * multiplier) / multiplier;
}

6. User Experience Improvements

Input Handling:

• Removed optimization calls from percentage/slider/max buttons
• Fixed input clamping to only apply for keypad input (not percentage/slider/max)
• Reduced unnecessary re-renders and calculations
• Skip validation during active input to prevent flickering error messages

Code Cleanup:

• Removed FinalizationRegistry polyfill from shim.js (no longer needed by updated dependencies)
• Removed unused findOptimalAmount and findHighestAmountForPositionSize functions
• Cleaned up debounced optimization logic from form handlers

Migration Path

Backward Compatibility:

• size field still present in OrderParams for backward compatibility
• Provider falls back to legacy size calculation if usdAmount is not provided
• Existing orders and integrations continue to work

Hybrid Approach:
Orders now pass both usdAmount (primary) and size (derived):

const orderParams: OrderParams = {
  coin: 'BTC',
  isBuy: true,
  size: positionSize, // Kept for compatibility, recalculated by provider
  usdAmount: orderForm.amount, // USD as source of truth
  priceAtCalculation: assetData.price, // For validation
  maxSlippageBps: 100, // 1% tolerance
  // ... other fields
};

Files Changed

Core Logic (276 additions, 290 deletions):

• app/components/UI/Perps/controllers/providers/HyperLiquidProvider.ts (+148 lines)
  • Hybrid USD-based order placement with price validation
  • Standardized slippage across all order types
  • Position size recalculation at execution time
• app/components/UI/Perps/utils/orderCalculations.ts (-149 lines)
  • Removed findOptimalAmount and findHighestAmountForPositionSize
  • Changed Math.floor to Math.round for position size calculation
• app/components/UI/Perps/hooks/usePerpsOrderForm.ts (-71 lines)
  • Removed optimizeOrderAmount function and related logic
  • Simplified amount initialization
• app/components/UI/Perps/hooks/usePerpsOrderValidation.ts (+28 lines)
  • Added skipValidation and originalUsdAmount parameters
  • Improved minimum order size validation with original USD input

UI Components:

• app/components/UI/Perps/Views/PerpsOrderView/PerpsOrderView.tsx (+/-54 lines)
  • Removed optimization calls from input handlers
  • Added skipValidation flag during input focus
  • Pass usdAmount and price validation params to provider
  • Fixed input clamping behavior

Configuration:

• app/components/UI/Perps/constants/perpsConfig.ts (+10 lines)
  • Added ORDER_SLIPPAGE_CONFIG constant
• app/components/UI/Perps/constants/hyperLiquidConfig.ts (-1 line)
  • Removed legacy slippage configuration

Types & Validation:

• app/components/UI/Perps/controllers/types/index.ts (+9 lines)
  • Updated OrderParams type with USD-based fields
• app/components/UI/Perps/utils/hyperLiquidValidation.ts (+9 lines)
  • Enhanced validation for limit orders
  • Added minimum order size tolerance
• app/components/UI/Perps/utils/hyperLiquidValidation.test.ts (+29 lines)
  • Added tests for limit order price validation

Cleanup:

• shim.js (-18 lines)
  • Removed FinalizationRegistry polyfill

Changelog

CHANGELOG entry: Improved Perps order precision and validation by using USD amounts as source of truth and standardizing slippage management

Related issues

Fixes: TAT-1902 - Investigate and resolve order placement issue for specific token pairs

How this PR fixes TAT-1902:
The USD-as-source-of-truth refactor directly addresses order placement failures for specific token pairs by:

• Recalculating position size at execution time with fresh market prices instead of using stale UI calculations
• Using asset-specific szDecimals precision throughout (no more hardcoded 6 decimals)
• Eliminating optimization logic that could produce invalid amounts near precision boundaries
• Validating orders with the exact USD amount entered by the user, preventing precision loss from multiple conversions

This ensures orders are calculated with the most current price and correct precision for each token pair, preventing the placement failures that occurred with the previous approach.

Manual testing steps

Feature: Perps Order Placement with USD as Source of Truth

  Scenario: User places a market order with precise USD amount
    Given user is on the Perps trading screen
    And user has sufficient balance

    When user enters "$100" USD amount via keypad
    And user selects "Market" order type
    And user taps "Place Order"

    Then order is placed with position size calculated from fresh market price
    And order execution succeeds without "insufficient margin" errors
    And no validation flickering occurs during input

  Scenario: User places order near minimum amount threshold
    Given user is on the Perps trading screen
    And market price causes calculated value to be near $10 minimum

    When user enters an amount that rounds to ~$9.99-$10.01
    And user places the order

    Then validation passes with 1% tolerance
    And no flickering validation errors appear

  Scenario: Price moves during order placement
    Given user has entered order details
    And calculated position size at price $50,000

    When market price moves to $50,500 (>1% move)
    And user places the order

    Then order is rejected with "Price moved too much" error
    And user is prompted to review and resubmit

  Scenario: User places limit order without price
    Given user is on the Perps trading screen
    And user selects "Limit" order type
    And user does not enter a limit price

    When user attempts to place order

    Then validation error displays "Price is required for limit orders"

  Scenario: User uses percentage buttons
    Given user is on the Perps trading screen
    And user has $1000 available balance

    When user taps "25%" button

    Then amount field shows "$250"
    And no optimization is triggered
    And position size is calculated correctly

  Scenario: User adjusts amount with slider
    Given user is on the Perps trading screen

    When user drags the amount slider

    Then amount updates in real-time
    And validation is skipped during interaction
    And validation applies after slider is released

  Scenario: User enters amount exceeding maximum
    Given user has $1000 available balance at 10x leverage
    And maximum possible order is $10,000

    When user enters "$15,000" via keypad
    And user dismisses the keypad

    Then amount is automatically clamped to "$10,000"
    And validation message explains the limit

  Scenario: User closes 100% of a position worth less than minimum
    Given user has an open position worth $5.23
    And minimum order size is $10

    When user taps "Close Position" button
    And selects "100%" (full close)
    And confirms the close

    Then position closes successfully
    And no minimum order size error appears
    And full position value is returned

  Scenario: User closes partial position below minimum
    Given user has an open position worth $100
    And minimum order size is $10

    When user attempts to close $8 worth of the position
    And confirms the close

    Then validation error displays "Minimum order size is $10"
    And close operation is prevented

Screenshots/Recordings

Before

• Orders occasionally failed with "insufficient margin" despite UI showing valid amounts
• Validation messages flickered during input on low-priced tokens
• Complex optimization logic ran on every input change
• Position size calculated once in UI, potentially stale at execution

After

• Consistent order execution with USD as source of truth
• No validation flickering with 1% tolerance on minimum amounts
• Simplified input handling without optimization overhead
• Position size recalculated with fresh price at execution time
• Price staleness validation prevents execution with stale prices

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). 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.

---

Technical Notes for Reviewers

Critical Changes to Review

1. Rounding Change in calculatePositionSize

   • Changed from Math.floor to Math.round
   • Verify this doesn't cause issues with existing positions or orders
   • Check that rounding behavior matches exchange requirements

2. Backward Compatibility

   • OrderParams.size still present but recalculated by provider
   • Verify existing integrations continue to work
   • Test with and without usdAmount parameter

3. Slippage Validation

   • Price staleness check may reject valid orders in volatile markets
   • Default 1% tolerance (100 bps) - verify this is appropriate
   • Check error messages are clear to users

4. Minimum Order Size Validation

   • USD as source of truth - validates exact user input ($10 ≥ $10)
   • No tolerance needed when using usdAmount parameter
   • Full position closes (100%) skip validation entirely via isFullClose flag
   • Partial position closes enforce $10 minimum validation
   • New positions enforce $10 minimum validation
   • Close position calculations use same USD validation logic as order placement

5. Input Clamping Logic

   • Now only clamps for keypad input, not percentage/slider/max
   • Verify this doesn't break max amount validation
   • Test with various input methods

Testing Recommendations

• Test with various token prices (low, medium, high)
• Test near minimum order size ($10) with price fluctuations
• Test with high leverage where rounding matters more
• Test order placement during price volatility
• Test limit orders with missing/invalid prices
• Verify no "insufficient margin" errors for valid amounts
• Check validation doesn't flicker during keypad input

---

Note

Switches order/close flows to USD-as-source-of-truth with provider-side size recalculation and unified slippage, improves validation/precision, removes optimization logic, and updates hooks/tests/docs.

• Core trading/provider:
  • Use USD as source of truth; provider recalculates size at execution with fresh price and asset szDecimals (HyperLiquidProvider.ts).
  • Add slippage config via ORDER_SLIPPAGE_CONFIG (default 100 bps) and price-staleness validation; pass usdAmount, priceAtCalculation, maxSlippageBps through OrderParams.
  • Refactor order build/format helpers into orderCalculations (calculateFinalPositionSize, calculateOrderPriceAndSize, buildOrdersArray).
  • Support full-close bypass of $10 minimum via isFullClose; propagate slippage params in close flows.
• Validation & precision:
  • calculatePositionSize/close calculations use asset precision, round to nearest, and ensure post-rounding USD meets target.
  • validateOrder now validates minimums from USD, requires price for limit orders, and tolerates full closes.
  • Remove findOptimalAmount/related logic and old slippage from hyperLiquidConfig.
• UI/hooks:
  • PerpsOrderView/PerpsClosePositionView: pass USD + slippage params; skip validation during input; clamp only for keypad; use market data with fallback decimals.
  • usePerpsMarketData accepts { asset, showErrorToast } and auto-toasts on errors; expose loading.
  • usePerpsOrderValidation/usePerpsClosePositionValidation: add skipValidation, use original USD for min checks.
• Types/constants:
  • Extend OrderParams/ClosePositionParams with USD/slippage/full-close fields; add DECIMAL_PRECISION_CONFIG.FALLBACK_SIZE_DECIMALS and ORDER_SLIPPAGE_CONFIG.
• Tests & docs:
  • Update extensive tests to new params, rounding, and hook signatures; adjust provider tests for price-required errors.
  • Refresh trading guide (market order/slippage sections) and fix reference paths.
• Cleanup:
  • Remove FinalizationRegistry polyfill from shim.js; simplify order form by dropping optimization APIs.

^{Written by Cursor Bugbot for commit fda1210. This will update automatically on new commits. Configure here.}

[github-actions]

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.

[cursor]

Bug: Rounding Inconsistency Breaks Position Sizing

findHighestAmountForPositionSize calculates the highest USD amount for a given position size, but its logic assumes calculatePositionSize uses Math.floor rounding. After changing to Math.round, the function returns incorrect values. For example, with position size 0.000210 at price $50000, it returns $10, but calculatePositionSize($10, $50000) yields 0.000200, not 0.000210. This breaks order amount optimization, potentially causing orders to fail validation or execute at incorrect sizes.

app/components/UI/Perps/utils/orderCalculations.ts#L177-L192

metamask-mobile/app/components/UI/Perps/utils/orderCalculations.ts

Lines 177 to 192 in 988b2c5

	}
	export function findHighestAmountForPositionSize(
	params: HighestAmountForPositionSizeParams,
	): number {
	const { positionSize, price, szDecimals = 6 } = params;
	// Calculate the exact USD value for this position size
	const exactUsdValue = parseFloat(positionSize.toFixed(szDecimals)) * price;
	// Calculate the increment that would bump to the next position size
	const multiplier = Math.pow(10, szDecimals);
	const usdIncrement = price / multiplier;
	// The highest amount is just before the next position size tier
	const highestAmount = exactUsdValue + usdIncrement;

 

---

[cursor]

Bug: Rounding Discrepancy: Exceeding Position Limits

findHighestAmountForPositionSize calculates the highest USD amount for a given position size assuming Math.floor rounding, but calculatePositionSize now uses Math.round. With symmetric rounding, the calculated highestAmount can produce a position size one increment higher than intended. For example, with Math.round, amounts near the midpoint between two position size tiers will round up, causing findOptimalAmount to return USD amounts that map to incorrect position sizes, potentially exceeding user balance or minimum order requirements.

app/components/UI/Perps/utils/orderCalculations.ts#L168-L182

metamask-mobile/app/components/UI/Perps/utils/orderCalculations.ts

Lines 168 to 182 in 2465f34

	positionSizeNum = incrementedPositionSize;
	highestAmount = findHighestAmountForPositionSize({
	positionSize: positionSizeNum,
	price,
	szDecimals,
	});
	}
	return highestAmount.toString();
	}
	export function findHighestAmountForPositionSize(
	params: HighestAmountForPositionSizeParams,
	): number {
	const { positionSize, price, szDecimals = 6 } = params;

 

---

[sonarqubecloud]

Quality Gate failed

Failed conditions
74.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud