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

2026-10-24 17:56:20 +02:00
parent 7e36b7ef95
commit 28640f3203
35 changed files with 9110 additions and 180 deletions
@@ -0,0 +1,29 @@
+# jupiter-perps-overview Specification
+
+## Purpose
+
+Provide precise read-only Jupiter position metrics for capital and risk inspection without altering transaction or alarm behavior.
+
+## 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