129 lines
10 KiB
Markdown
129 lines
10 KiB
Markdown
# evelyn-perps-overview Specification
|
|
|
|
## Purpose
|
|
|
|
Let the owner inspect Evelyn perpetual positions grouped by wallet and venue in Mission Control, with stable row identities across service snapshot updates.
|
|
|
|
## 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: Asynchronous polling follows window visibility
|
|
EMC SHALL request the current Perps snapshot from each environment's own service immediately on opening and every three seconds while visible, without blocking the UI thread. UI updates SHALL occur only on the JavaFX thread. Hiding the window SHALL stop polling; reopening SHALL create only one active polling loop and ignore results belonging to an earlier window session. Poll failures SHALL preserve the current view and allow subsequent attempts.
|
|
|
|
#### Scenario: Read takes time or fails
|
|
- **WHEN** a snapshot read is delayed or fails
|
|
- **THEN** the UI remains responsive and the existing view is retained
|
|
- **AND** later polling remains possible without overlapping scheduled reads
|
|
|
|
#### Scenario: Hide and reopen
|
|
- **WHEN** the owner hides and reopens EMC repeatedly
|
|
- **THEN** each visible session has only one polling loop and obsolete results cannot update its views
|
|
|
|
#### Scenario: Environment data stays separate
|
|
- **WHEN** TEST and PROD return different snapshots
|
|
- **THEN** each tab displays only its own service's data
|
|
- **AND** a failure reading one service does not prevent attempting the other service
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
### Requirement: EMC presents service data without sample notices
|
|
EMC SHALL obtain positions only from its environment's in-memory service snapshot and SHALL contain no sample positions, sample notices, illustrative-Phoenix notices, or Refresh button. EMC SHALL own UI components, colors and formatting; integration reads SHALL belong to the service.
|
|
|
|
#### Scenario: Snapshot changes
|
|
- **WHEN** positions are added or removed after refresh
|
|
- **THEN** EMC reconciles rows by identity while preserving retained selections and expansion state
|
|
- **AND** no sample labels or Phoenix examples appear
|
|
|
|
### 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
|
|
|
|
### Requirement: Venue visibility follows available child rows
|
|
EMC SHALL hide venue rows with neither positions nor Cross accounts and show them when children reappear. Funded empty Cross accounts SHALL keep their venue visible. Hidden venues SHALL remain in snapshots and totals, with read status available in wallet tooltips. Unknown scopes SHALL NOT become zero totals; failed reads SHALL preserve last-success totals. Wallet rows and the root SHALL remain visible.
|
|
|
|
#### Scenario: Empty venue
|
|
- **WHEN** Jupiter or Phoenix has no positions and no Cross accounts
|
|
- **THEN** its heading is absent from that wallet's displayed children
|
|
- **AND** a successful empty scope still contributes zero to totals
|
|
|
|
#### Scenario: Funded Cross account without positions
|
|
- **WHEN** Phoenix returns a Cross account with capital but no open positions
|
|
- **THEN** Phoenix and its Cross account remain visible with that capital counted once
|
|
|
|
#### Scenario: Positions disappear and return
|
|
- **WHEN** a venue loses its last child and later returns a position
|
|
- **THEN** its heading disappears and reappears with the correct child
|
|
- **AND** unrelated retained rows keep their selection and expansion state
|
|
|
|
#### Scenario: Hidden scope has not been read successfully
|
|
- **WHEN** a childless venue has never been read successfully and its first read is pending or failed
|
|
- **THEN** the heading is hidden and its read status is available on the wallet tooltip
|
|
- **AND** required totals remain unavailable rather than reporting zero
|
|
|
|
### Requirement: TWAP cells show execution progress and snapshot duration
|
|
Matching filled Phoenix TWAPs SHALL show a progressbar using executed/total child counts and an overlaid estimated duration to the next child in unbounded hours, minutes and seconds. Other cells SHALL be empty. Updates SHALL follow existing snapshots without a live timer. Failed retained observations SHALL be labeled retained; due or unknown schedules SHALL not show negative or wrapped times or imply execution.
|
|
|
|
#### Scenario: Long interval
|
|
- **WHEN** the snapshot's estimated wait is 28 hours 32 minutes 10 seconds, or 128 hours 32 minutes 10 seconds
|
|
- **THEN** the text is approximately 28:32:10 or 128:32:10 respectively
|
|
|
|
#### Scenario: Failed or due observation
|
|
- **WHEN** the venue read fails or the latest observed next slot is already due
|
|
- **THEN** the cell communicates retained or awaiting-update status without advancing progress
|
|
|
|
### Requirement: TWAP tooltip distinguishes estimates from fills
|
|
TWAP tooltips SHALL show executed/total progress, Estimated completion, total size, next child size, filled quantity and observation time. Sizes SHALL include their symbol and approximate USD values from Phoenix mark prices where available. Distinct regular/dust sizes and periodic nominal-slot timing assumptions SHALL be explained. Unknown values SHALL remain unknown; expiry SHALL never be presented as completion.
|
|
|
|
#### Scenario: Missing price or smaller next child
|
|
- **WHEN** the mark price is unavailable or the next child is a smaller rest order
|
|
- **THEN** token amounts remain visible with unknown USD values, or the next size reflects that rest order respectively
|
|
|
|
### 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
|