98: Populate EvelynPerpsService with real Jupiter positions

2026-10-22 13:19:21 +02:00
parent 0ec22d5215
commit a3ce10a264
14 changed files with 286 additions and 78 deletions
@@ -0,0 +1,26 @@
+## REMOVED Requirements
+
+### Requirement: Sample positions communicate direction and USD size
+**Reason**: Sample data is replaced by real Jupiter positions.
+**Migration**: Keep existing formatting and colors for actual positions.
+
+### Requirement: Prototype is clearly labeled and entirely local
+**Reason**: Data now comes from real Jupiter reads performed by the service.
+**Migration**: Remove sample and illustrative-Phoenix notices; preserve EMC's snapshot-only boundary.
+
+## ADDED Requirements
+
+### Requirement: Jupiter positions communicate direction and USD size
+Position rows SHALL show Long or Short and USD sizes with grouping separators and two decimal places. Long rows SHALL have faint green backgrounds and Short rows faint red backgrounds; wallet and venue rows SHALL have no direction-based color. Existing columns and hierarchy SHALL be preserved.
+
+#### Scenario: Inspect real positions
+- **WHEN** real Jupiter positions are displayed
+- **THEN** direction appears as readable text and background color, with formatted USD size
+
+### 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
@@ -0,0 +1,57 @@
+## MODIFIED Requirements
+
+### Requirement: Read-only current positions snapshot
+The Perps service SHALL expose only a read operation returning its complete current in-memory snapshot. Wallets, venues within wallets, and positions within venues SHALL have stable identifiers across reads. Responses SHALL be immutable domain data without UI components, colors or formatting. Reading the snapshot SHALL make no Jupiter or Phoenix requests.
+
+#### Scenario: Repeated reads
+- **WHEN** clients repeatedly retrieve the started service's snapshot
+- **THEN** they receive the latest published positions with stable identifiers and cannot mutate service-owned collections
+- **AND** the reads trigger no exchange requests or position-management operations
+
+
+### Requirement: Hub owns Perps startup
+The service SHALL run as two separate Hub-managed processes registered as `evelyn.perps.test` and `evelyn.perps.prod`. The service API SHALL expose no lifecycle operations. Snapshot reads before process startup SHALL fail clearly. Startup SHALL schedule asynchronous retrieval without waiting for integration I/O.
+
+#### Scenario: Service starts
+- **WHEN** the Hub starts either registered Perps process
+- **THEN** its service view is available without waiting for retrieval, initially empty until data arrives
+- **AND** no placeholder positions are generated before successful retrieval
+
+### 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 and the corresponding existing Jupiter 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.
+
+#### Scenario: Separate configured instances
+- **WHEN** the Hub constructs and starts both instances
+- **THEN** each instance queries only its configured wallets through its corresponding integration
+- **AND** the implementation does not define the wallet list internally
+
+## REMOVED Requirements
+
+### Requirement: Service owns the unchanged sample positions
+**Reason**: Real Jupiter positions replace all sample data.
+**Migration**: Remove sample portfolios and Phoenix examples; configure real addresses in Hub.
+
+## ADDED Requirements
+
+### Requirement: Background Jupiter refresh
+The service SHALL refresh immediately after startup and wait 60 seconds between completed cycles, without overlapping cycles or depending on EMC visibility. It SHALL use only existing Jupiter position reads and respect their cache. Snapshot reads SHALL make no integration calls. No transaction signing or position-management operation SHALL occur.
+
+#### Scenario: Background update while EMC is hidden
+- **WHEN** EMC is hidden and the next refresh is due
+- **THEN** the service still refreshes configured wallets and publishes immutable snapshots
+- **AND** no freshness guarantee bypasses the existing 60-second integration cache
+
+### Requirement: Position mapping is stable and complete
+The service SHALL map position account to stable ID, mint to known instrument label or raw mint fallback, direction to Long/Short, and positionSize to USD size. Wallet order SHALL follow configuration, and positions SHALL be ordered deterministically by position account. Only Jupiter venues and actual positions SHALL be published.
+
+#### 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: Refresh failures are isolated per wallet
+A failed wallet read or mapping SHALL retain its last successful data, log the failure and allow other wallets to refresh. Successful empty results SHALL remove previous positions. Interruption SHALL stop the current cycle. Failed first reads SHALL not invent positions.
+
+#### Scenario: Failure followed by recovery
+- **WHEN** one wallet fails while another succeeds
+- **THEN** only the successful wallet's data is replaced
+- **AND** a later successful empty read clears the recovered wallet's previous positions