evelyn-perps-service Specification

Purpose

Provide a view-only source of current Evelyn perpetual positions independently of Mission Control presentation and refresh timing.

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, and SHALL make no Jupiter or Phoenix requests.

Scenario: Repeated reads

WHEN clients repeatedly retrieve the started service's snapshot
THEN they receive the same complete positions with stable identifiers and cannot mutate service-owned collections
AND no exchange requests or position-management operations occur

Requirement: Service owns the unchanged sample positions

The service SHALL own the existing eight sample positions grouped under Sample wallet A and Sample wallet B and their Jupiter and Phoenix venues, retaining every existing instrument, direction and decimal USD size. The snapshot SHALL remain unchanged for this task.

Scenario: Existing samples are retrieved

WHEN EMC retrieves the service snapshot
THEN wallet A contains Jupiter SOL Long 12500.00 and BTC Short 8250.50, Phoenix SOL Short 3200.75 and ETH Long 5400.00
AND wallet B contains Jupiter ETH Long 1875.25 and SOL Short 950.00, Phoenix BTC Long 21000.00 and SOL Short 640.50

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.

Scenario: Service starts

WHEN the Hub starts either registered Perps process
THEN its service view makes the complete sample snapshot available without starting a polling or integration worker

Requirement: Wallet configuration belongs to service construction

The Hub SHALL supply the same hardcoded wallet configuration to TEST and PROD at construction. Each service SHALL retain an immutable copy and own a separate snapshot. EMC SHALL neither own nor pass wallet configuration; snapshot reads SHALL remain parameterless.

Scenario: Separate configured instances

WHEN the Hub constructs and starts both instances using the shared sample wallet configuration
THEN each snapshot contains the configured wallet identities and existing sample positions
AND the two instances own separate snapshots without defining the wallet list internally

2.6 KiB Raw Blame History