com_r35157_nenjim-hubd-impl_ref/openspec/changes/archive/2026-10-22-98-live-jupiter-perps/design.md

Design

Context

See proposal.md and issue #98. Hub already has distinct Jupiter readers backed by a shared Solana cache (60-second TTL). The current Perps service creates samples; EMC already reconciles immutable snapshots by identity.

Goals / Non-Goals

Keep existing public snapshot reads and read-only behavior. No changes to Jupiter trading, its caching, new columns, Phoenix, or stale-data UI. System documentation in the sibling repository is explicitly within the user-authorized scope.

Decisions

• Replace sample wallet ID/name configuration with a SolanaWalletId address; use it for both row ID and label. Hub supplies separate fixed lists and the existing matching Jupiter dependency.
• One scheduled daemon worker per instance starts immediately, then uses a 60-second fixed delay after completion. This avoids overlap and catch-up bursts on slow RPCs. Window visibility does not affect it. Implementation-only close interrupts/shuts down the worker; the consumer interface remains read-only.
• Maintain last successful wallets in worker-owned state and publish a new immutable snapshot after each successful wallet, in configured order. Initial snapshot is empty; successful empty reads retain the wallet/Jupiter grouping with no positions. Errors preserve that wallet only; interruption ends the cycle.
• Reuse the three known Jupiter mint mappings already present in the alarm code (SOL/BTC/ETH); unknown mints display verbatim. No new currency registry entries are needed. Sort positions by account for deterministic results from unordered sets.
• Remove sample labels in PerpsTab; retain its existing identity reconciliation and polling. No new UI states.

Risks / Trade-offs

• Errors can leave old data visible → log per wallet and document this deliberate limitation; stale indicators remain out of scope.
• Existing Jupiter model has dummy PnL and prices → use only required mint, direction, account and actual positionSize.
• Live RPC availability may limit end-to-end verification → record actual outcomes without claiming live success from compilation alone.

Migration Plan

No process ID or autostart changes. Rebuild and restart through normal deployment to load the new wallet lists. Verification must not start the full Hub or any trading process. Leave all edits uncommitted for review.