102: EMC Perps: show liquidation risk and account health

2026-10-25 16:35:17 +01:00
parent 2f30712004
commit b4c7fe87d9
30 changed files with 1070 additions and 48 deletions
@@ -0,0 +1,40 @@
+## MODIFIED Requirements
+
+### Requirement: Perps overview displays a collapsible position hierarchy
+The Perps tab SHALL display Position, Risk, Direction, Margin, Collateral, Leverage, Exposure, Value, uPnL and TWAP beneath the visible Perpetual Contracts root. Isolated hierarchy SHALL be wallet → venue → position; each Phoenix Cross account SHALL add a Cross group above its positions. Groups SHALL show applicable totals and risk summaries, leave direction/aggregate ratios and TWAP blank, and be expanded by default.
+
+#### Scenario: Open either environment's Perps tab
+- **WHEN** the owner opens Perps in Production or Test
+- **THEN** all ten columns and the account-aware hierarchy are available with Risk near the position name
+
+#### Scenario: Collapse and expand groups
+- **WHEN** the owner collapses a wallet, venue or Cross account
+- **THEN** the group still shows its worst known risk and incomplete-observation counts without changing totals
+
+### Requirement: Polling preserves Perps view state
+The Perps table SHALL retain matching wallet, venue and position identities across snapshots. Repeated unchanged snapshots SHALL leave retained rows, expansion, selection and formatting untouched except when risk freshness changes, without flicker or table rebuild. New groups SHALL be expanded by default, and added or removed positions SHALL be reconciled by identity without resetting retained groups.
+
+#### Scenario: Poll unchanged positions
+- **WHEN** a user collapses a group or selects a position and repeated snapshots are unchanged
+- **THEN** the same rows remain with the same expansion and selection
+- **AND** only a changed risk freshness indication requires a row-value update
+
+## ADDED Requirements
+
+### Requirement: Risk cells distinguish distance and account health
+Risk cells SHALL show neutral isolated distance and red reached/crossed boundaries, while Phoenix tiers use their own severity colors. Cross account cells SHALL label MM utilization; their children SHALL indicate Shared scope. Missing risk SHALL be Unknown. Text, indicators and tooltips SHALL explain units, reference/liquidation prices, account scope, thresholds, original observation time and limitations without changing direction backgrounds.
+
+#### Scenario: Safe account without liquidation estimate
+- **WHEN** Phoenix reports a valid Safe account but a nonpositive liquidation-price sentinel
+- **THEN** account health remains available while the position price estimate is unavailable
+
+### Requirement: Risk freshness expires unchanged snapshots
+EMC SHALL mark risk stale after five minutes from its original observation, on read failure or for future timestamps. Existing UI polling SHALL update freshness even when the snapshot is unchanged, without additional venue calls/timers. Old critical states SHALL remain prominent with uncertainty; stale or incomplete noncritical observations SHALL NOT appear fresh green. Reconciliation SHALL preserve row identity, selection, expansion and TWAP state.
+
+#### Scenario: Unchanged successful snapshot grows old
+- **WHEN** time passes the five-minute risk age limit without new data or errors
+- **THEN** existing UI polling changes its freshness indication without resetting the tree
+
+#### Scenario: Retained critical risk
+- **WHEN** a previously critical observation fails to refresh
+- **THEN** its critical state and original time remain visible with stale/retained indication
@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Risk observations preserve scope and exact meaning
+Snapshots SHALL preserve isolated risk prices and Cross account tiers/thresholds with original observation times. Signed price distance SHALL use the current venue reference as denominator and preserve boundary crossing. Cross MM utilization SHALL use effective collateral, with nonpositive denominators unavailable. Group risk SHALL count each isolated position and shared account once and retain worst known severity plus unknown/stale counts without averaging.
+
+#### Scenario: Shared positions and incomplete data
+- **WHEN** a Cross account owns multiple positions and another scope has unknown risk
+- **THEN** account risk contributes once and the aggregate exposes the unknown count
+- **AND** its closing Value is not substituted for effective collateral
+
+#### Scenario: Boundary and zero denominator
+- **WHEN** isolated distance reaches/crosses zero or effective collateral is nonpositive
+- **THEN** the signed boundary is preserved or MM percentage is unavailable respectively
+- **AND** display rounding does not determine risk classification
@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: Report venue risk prices with observation time
+The overview SHALL expose the venue reference and liquidation prices in exact USD units with the original response observation time. Missing or nonpositive risk prices SHALL be unavailable, never zero safety or infinite distance. Stable position identity and the separate transaction/alarm read path SHALL remain unchanged.
+
+#### Scenario: Missing or sentinel price
+- **WHEN** a valid position has no actionable liquidation price
+- **THEN** its other metrics remain present and its liquidation distance is unavailable
@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Read venue account health independently of TWAP
+The reader SHALL resolve the official trader account for authority/PDA/subaccount and read its venue risk classification, effective collateral, maintenance margin and position liquidation prices. It SHALL validate identities and amounts, use venue reference prices with original observation times and normalize sentinel liquidation prices to unavailable. Existing pacing, cooldown, timeout and failure retention contracts SHALL apply without signing or TWAP dependence.
+
+#### Scenario: Same-symbol isolated and Cross accounts
+- **WHEN** the wallet holds the same market in multiple accounts without active TWAPs
+- **THEN** each visible account receives only its own reported risk and liquidation data
+- **AND** a mismatched trader identity or position size fails the observation
+
+#### Scenario: Missing or unsupported risk field
+- **WHEN** a response has missing optional risk values or an unknown tier
+- **THEN** those values remain unavailable without assuming a safe state
+- **AND** a nonpositive liquidation-price sentinel does not invalidate independent account health