EMC Perps: show estimated Jupiter Value and mark affected totals with ≈ #104

New Issue

2026-10-26T08:44:32+01:00

minimons commented

2026-10-26 08:44:32 +01:00

Problem

EMC's Perps tab displays — for Jupiter position Value even though the existing GET /v2/positions response includes valueUsd. The overview reader does not preserve the field and the Evelyn mapping explicitly sets Value to null. As a result, group and portfolio Value totals containing those positions are also unavailable.

This was a deliberate limitation in #100: an observed API value subtracted opening fees despite collateral already being recorded after fees, and collateral valuation/profit-cap behavior was not fully verified. The owner now prefers to see Jupiter's own estimate, clearly identified as approximate. This improves Evelyn's capital overview without claiming verified closing proceeds. The possible difference is not known to be limited to small fees.

Agreed behavior

Preserve Jupiter's reported valueUsd through the read-only overview and immutable Perps snapshot. Convert integer micro-USD to USD exactly using decimal arithmetic (valueUsd / 10^6); do not pass through floating point.
Display the value as, for example, ≈$123.23, using the approximation sign ≈ (U+2248), USD formatting and two decimals. Keep legitimate zero and signed values; missing values must not become zero.
Explain in the position's Value tooltip: “Estimated position value reported by Jupiter. Actual proceeds on closing may differ.” Clarify the known fee-treatment uncertainty and unverified collateral/profit-cap semantics without asserting that the discrepancy is always small or that the API is necessarily wrong in every case.
Use the reported number as supplied. Do not add opening fees back, recalculate a supposedly corrected net value, or introduce a new closing-quote/on-chain calculation in this task.
Carry the estimate qualification into every applicable Value total containing a Jupiter estimate: Jupiter → wallet → Perpetual Contracts, independently of expansion state. Show ≈ once before the formatted total, and explain the estimated contribution in its tooltip. A mix of Phoenix and Jupiter values must preserve the qualification through the root.
Do not discard the existing approximate/estimated meaning of Phoenix closing Value; it must not be presented as a guaranteed exact payout. Preserve its existing account-aware calculations and count shared Cross capital once.
Preserve the existing completeness rule: if any required Value component is missing, the affected total remains —, rather than showing a partial sum. An unavailable amount has no misleading numeric approximation marker. A successfully read empty scope can still total zero.
Missing/null valueUsd leaves that position's Value unavailable while retaining its other valid fields. Present malformed amounts fail the observation under the existing validation/retention contract. Successful new observations replace previous values; failures retain the original observation and its existing status/timestamp instead of making estimates look fresh.

Scope and acceptance

Use the project OpenSpec workflow for implementation. Keep the existing read-only endpoint, polling, wallet configuration and request handling. No signing, transaction building, trading, new price feed or extra venue calls are required.
Verify exact micro-USD conversion, rounding, zero/signed/missing/malformed values, the position tooltip, Jupiter/wallet/root totals, mixed Phoenix/Jupiter totals, incomplete totals, collapsed groups and retained/recovered observations. Keep Exposure, Collateral, uPnL, Risk and TWAP behavior intact.
Update the relevant repository documentation and r35157_docs, replacing obsolete claims that Jupiter Value is always unavailable. Retain the real limitations and clearly distinguish a venue-reported estimate from guaranteed closing proceeds. Add only meaningful documentation.
Do not commit or push the implementation.

Sources and implementation starting points:

Official Jupiter CLI response type (valueUsd)
Jupiter position account: post-fee collateral and profit cap
src/main/tjava/com/r35157/libs/jupiter/perps/impl/ref/RestJupiterPerpsOverview.tjava
src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsOverviewPosition.tjava
src/main/tjava/com/r35157/evelyn/service/perps/impl/ref/EvelynPerpsServiceImpl.tjava
src/main/tjava/com/r35157/evelyn/service/perps/PerpsSnapshot.tjava
src/main/tjava/com/r35157/evelyn/emc/impl/ref/PerpsTab.tjava
docs/JupiterPerpsOverview.md documents the original observations and limitation.

Creating this issue records the agreed task; implementation requires a separate request.

## Problem EMC's Perps tab displays `—` for Jupiter position Value even though the existing `GET /v2/positions` response includes `valueUsd`. The overview reader does not preserve the field and the Evelyn mapping explicitly sets Value to null. As a result, group and portfolio Value totals containing those positions are also unavailable. This was a deliberate limitation in #100: an observed API value subtracted opening fees despite collateral already being recorded after fees, and collateral valuation/profit-cap behavior was not fully verified. The owner now prefers to see Jupiter's own estimate, clearly identified as approximate. This improves Evelyn's capital overview without claiming verified closing proceeds. The possible difference is not known to be limited to small fees. ## Agreed behavior - Preserve Jupiter's reported `valueUsd` through the read-only overview and immutable Perps snapshot. Convert integer micro-USD to USD exactly using decimal arithmetic (`valueUsd / 10^6`); do not pass through floating point. - Display the value as, for example, **`≈$123.23`**, using the approximation sign `≈` (U+2248), USD formatting and two decimals. Keep legitimate zero and signed values; missing values must not become zero. - Explain in the position's Value tooltip: **“Estimated position value reported by Jupiter. Actual proceeds on closing may differ.”** Clarify the known fee-treatment uncertainty and unverified collateral/profit-cap semantics without asserting that the discrepancy is always small or that the API is necessarily wrong in every case. - Use the reported number as supplied. Do not add opening fees back, recalculate a supposedly corrected net value, or introduce a new closing-quote/on-chain calculation in this task. - Carry the estimate qualification into every applicable Value total containing a Jupiter estimate: **Jupiter → wallet → Perpetual Contracts**, independently of expansion state. Show `≈` once before the formatted total, and explain the estimated contribution in its tooltip. A mix of Phoenix and Jupiter values must preserve the qualification through the root. - Do not discard the existing approximate/estimated meaning of Phoenix closing Value; it must not be presented as a guaranteed exact payout. Preserve its existing account-aware calculations and count shared Cross capital once. - Preserve the existing completeness rule: if any required Value component is missing, the affected total remains `—`, rather than showing a partial sum. An unavailable amount has no misleading numeric approximation marker. A successfully read empty scope can still total zero. - Missing/null `valueUsd` leaves that position's Value unavailable while retaining its other valid fields. Present malformed amounts fail the observation under the existing validation/retention contract. Successful new observations replace previous values; failures retain the original observation and its existing status/timestamp instead of making estimates look fresh. ## Scope and acceptance - Use the project OpenSpec workflow for implementation. Keep the existing read-only endpoint, polling, wallet configuration and request handling. No signing, transaction building, trading, new price feed or extra venue calls are required. - Verify exact micro-USD conversion, rounding, zero/signed/missing/malformed values, the position tooltip, Jupiter/wallet/root totals, mixed Phoenix/Jupiter totals, incomplete totals, collapsed groups and retained/recovered observations. Keep Exposure, Collateral, uPnL, Risk and TWAP behavior intact. - Update the relevant repository documentation and `r35157_docs`, replacing obsolete claims that Jupiter Value is always unavailable. Retain the real limitations and clearly distinguish a venue-reported estimate from guaranteed closing proceeds. Add only meaningful documentation. - Do not commit or push the implementation. Sources and implementation starting points: - [Official Jupiter CLI response type (`valueUsd`)](https://github.com/jup-ag/cli/blob/main/src/clients/PerpsClient.ts) - [Jupiter position account: post-fee collateral and profit cap](https://developers.jup.ag/docs/perps/position-account) - `src/main/tjava/com/r35157/libs/jupiter/perps/impl/ref/RestJupiterPerpsOverview.tjava` - `src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsOverviewPosition.tjava` - `src/main/tjava/com/r35157/evelyn/service/perps/impl/ref/EvelynPerpsServiceImpl.tjava` - `src/main/tjava/com/r35157/evelyn/service/perps/PerpsSnapshot.tjava` - `src/main/tjava/com/r35157/evelyn/emc/impl/ref/PerpsTab.tjava` - `docs/JupiterPerpsOverview.md` documents the original observations and limitation. Creating this issue records the agreed task; implementation requires a separate request.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: r35157/com_r35157_nenjim-hubd-impl_ref#104