100: Add Perps collateral, leverage, value, uPnL and gross-exposure totals in EMC

2026-10-24 14:52:12 +02:00
parent 7e36b7ef95
commit bcb6b435f2
29 changed files with 8965 additions and 180 deletions
@@ -0,0 +1,33 @@
+## MODIFIED Requirements
+
+### Requirement: Perps overview displays a collapsible position hierarchy
+The Perps tab SHALL display Position, Direction, Margin, Collateral, Leverage, Exposure, Value and uPnL in that order 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, leave direction/aggregate ratios blank, and be expanded by default.
+
+#### Scenario: Open either environment's Perps tab
+- **WHEN** the owner opens Perps in Production or Test
+- **THEN** all eight columns, root totals and the account-aware hierarchy are visible
+
+#### Scenario: Collapse and expand groups
+- **WHEN** the owner collapses and expands a wallet, venue or Cross account
+- **THEN** descendants hide and return without changing totals
+
+### Requirement: Jupiter positions communicate direction and USD size
+Positions SHALL show readable Long/Short direction and Isolated/Cross margin text. USD amounts SHALL use grouping and two decimals; leverage SHALL use a multiplication sign. Signed uPnL SHALL be green for positive, red for negative and neutral for rounded zero without negative zero. Existing faint direction backgrounds SHALL remain; groups SHALL have distinct weight and no direction color. Numeric columns SHALL be right-aligned with useful widths and tooltips.
+
+#### Scenario: Small or unavailable PnL
+- **WHEN** PnL rounds to zero or is unavailable
+- **THEN** zero has no negative sign/color and unavailable values show an em dash with an explanation
+
+#### Scenario: Inspect real positions
+- **WHEN** real Jupiter positions are displayed
+- **THEN** direction appears as readable text and background color, with formatted gross USD exposure and applicable valuation metrics
+
+## ADDED Requirements
+
+### Requirement: Definitions distinguish owned collateral and margin requirements
+Tooltips SHALL explain isolated collateral, exposure-based leverage, collateral-based ROI, estimated net Value and excluded slippage/swaps/rent. Cross position collateral SHALL be identified as initial margin required against shared collateral. Cross position Value SHALL be unavailable; unsupported Cross ROI/leverage SHALL be explained. Cross account leverage SHALL identify undiscounted equity before exit fees as its denominator.
+
+#### Scenario: Inspect a Cross position
+- **WHEN** the owner inspects a Cross row and its account group
+- **THEN** the position shows a USD margin requirement and the account shows shared capital once
+- **AND** no position-only metric is labeled account utilization
@@ -0,0 +1,53 @@
+## MODIFIED Requirements
+
+### Requirement: Wallet configuration belongs to service construction
+The Hub SHALL supply the six PROD wallet addresses and one TEST wallet address specified in issue #98, a read-only Jupiter overview reader and a read-only Phoenix integration at construction. Each service SHALL retain immutable configuration and own its snapshot. Wallet addresses SHALL be used as stable identities and display labels. EMC SHALL neither own nor pass wallet configuration; reads SHALL remain parameterless. Existing Jupiter trading/alarm services SHALL retain their behavior.
+
+#### Scenario: Separate configured instances
+- **WHEN** the Hub constructs and starts both instances
+- **THEN** each instance queries only its configured wallets through its injected integrations
+- **AND** the implementation does not define the wallet list internally
+
+### Requirement: Position mapping is stable and complete
+The service SHALL preserve Jupiter position-account identities and its existing USD position-size basis. Phoenix SHALL preserve PDA/subaccount/symbol identities and absolute current notional. Isolated positions SHALL remain directly under venues; Cross accounts SHALL own their positions and shared balances separately. Wallet and position ordering SHALL be deterministic. No account membership SHALL be inferred from instrument labels.
+
+#### Scenario: Same-market cross and isolated positions
+- **WHEN** a Phoenix wallet holds SOL in Cross and an isolated subaccount
+- **THEN** both positions retain distinct IDs and their actual account membership
+
+#### Scenario: Changed and unknown positions
+- **WHEN** a successful read returns newly opened positions including an unknown token mint
+- **THEN** all returned positions appear with stable IDs and exact USD sizes, and the unknown mint is displayed rather than dropped
+
+### Requirement: Background Jupiter refresh
+The service SHALL refresh immediately after startup and wait 60 seconds after completed cycles without overlap or dependence on EMC visibility. It SHALL use a dedicated read-only Jupiter overview and the Phoenix account reader. Snapshot reads SHALL make no integration calls. No signing or position-management operation SHALL occur; existing transaction/alarm reads SHALL retain their behavior.
+
+#### Scenario: Background update while EMC is hidden
+- **WHEN** EMC is hidden and the next refresh is due
+- **THEN** the service refreshes configured wallets and publishes immutable snapshots
+- **AND** all UI snapshot reads remain in-memory
+
+## ADDED Requirements
+
+### Requirement: Complete gross and account-aware totals
+Exposure and dollar price PnL SHALL sum through all levels. Exposure SHALL be gross, with positive absolute notionals. Capital and closing Value SHALL count isolated positions and shared Cross accounts once. Missing required components SHALL make only the affected total unavailable. Successfully read empty scopes SHALL total zero. Leverage and PnL percentages SHALL NOT be aggregated.
+
+#### Scenario: Opposite directions and shared collateral
+- **WHEN** two Cross positions have notionals 100 USD Long and 100 USD Short, shared collateral 80 USD, combined PnL 5 USD and closing fees 1 USD
+- **THEN** exposure totals 200 USD, collateral 80 USD and Value 84 USD at account, venue, wallet and root levels
+- **AND** collapsing any UI group does not change totals
+
+#### Scenario: First read fails
+- **WHEN** one configured venue has never been read successfully
+- **THEN** it remains unknown and cannot silently produce complete portfolio totals
+
+### Requirement: Retained observations communicate status
+Each venue SHALL carry its last-success time and whether the latest attempt failed. Failure SHALL preserve positions and account balances independently per wallet/venue. A valid funded empty Cross account SHALL remain visible. Retained data SHALL NOT be described as fresh.
+
+#### Scenario: Last Cross position closes
+- **WHEN** a successful refresh returns a Cross account with nonzero collateral and no positions
+- **THEN** its capital and Value remain included without synthetic positions
+
+#### Scenario: Retained last success
+- **WHEN** a subsequent read fails
+- **THEN** its previous observations remain available with their original success time and failure indication
@@ -0,0 +1,27 @@
+## Purpose
+
+Provide precise read-only Jupiter position metrics for capital and risk inspection without altering transaction or alarm behavior.
+
+## ADDED Requirements
+
+### Requirement: Coherent read-only position overview
+The overview SHALL read the official positions response for one wallet, validate completeness and unique stable identities, and return immutable results. USD integer amounts SHALL be converted from micro-USD without binary floating point. Requests SHALL be interruptible and have bounded timeouts; failed or malformed reads SHALL NOT become empty portfolios.
+
+#### Scenario: Incomplete response
+- **WHEN** count differs from the returned position count, or identities are duplicated
+- **THEN** the read fails and no partial portfolio is published
+
+#### Scenario: Valid empty response
+- **WHEN** the response contains count zero and an empty position list
+- **THEN** the successful result clears that wallet's Jupiter scope
+
+### Requirement: Verified metrics and unavailable valuations
+The overview SHALL preserve size basis, use post-fee USD collateral and price PnL before separate fees, and calculate leverage and ROI against positive collateral. Unverified closing valuations SHALL be unavailable with an explanation; placeholder zeros and double subtraction of settled fees SHALL NOT be used.
+
+#### Scenario: Unverified API closing value
+- **WHEN** API value subtracts opening fees already settled in collateral or does not establish profit-cap valuation
+- **THEN** closing Value is unavailable, while independently verified metrics remain available
+
+#### Scenario: Nonpositive collateral
+- **WHEN** a position's collateral is zero or negative
+- **THEN** its leverage and PnL percentage are unavailable
@@ -0,0 +1,20 @@
+## ADDED Requirements
+
+### Requirement: Separate account capital and precise position metrics
+The reader SHALL return immutable account balances separately from positions, including funded empty Cross accounts. Quote lots SHALL convert at 1e-6 USD. Price PnL SHALL use precise virtual quote and signed base amounts at mark. Initial position margin SHALL follow size-dependent tiers including venue interpolation and rounding. Unsupported non-USDC collateral SHALL make affected valuations unavailable instead of being ignored.
+
+#### Scenario: Size between margin tiers
+- **WHEN** a position lies between two leverage tiers
+- **THEN** its initial margin follows interpolated integer leverage and upward quote-lot rounding, rather than the market's maximum leverage
+
+#### Scenario: Unsupported spot collateral
+- **WHEN** an account has nonzero spot collateral that cannot be valued reliably
+- **THEN** collateral, equity and closing Value are unavailable while independent exposure and price PnL remain available
+
+### Requirement: Estimated account and isolated closing proceeds
+Equity SHALL include collateral, undiscounted price PnL and signed unsettled funding once. Estimated Value SHALL subtract estimated closing taker fees with account fee overrides. Settled fees/funding SHALL NOT be subtracted again. Isolated position leverage/ROI SHALL use actual collateral; Cross position leverage/ROI SHALL remain unavailable unless their venue convention is verified.
+
+#### Scenario: Funding signs and fee override
+- **WHEN** collateral is 100 USD, PnL 5 USD, unsettled funding -2 USD, and estimated exit fee 1 USD
+- **THEN** equity is 103 USD and estimated Value 102 USD
+- **AND** effective Cross leverage uses 103 USD as its denominator