approximate_hypercore_share_prices_from_pnl_nav

Documentation for eth_defi.research.wrangle_vault_prices.approximate_hypercore_share_prices_from_pnl_nav function.

approximate_hypercore_share_prices_from_pnl_nav(prices_df, logger=<built-in function print>, max_positive_return=1.0)

Build an approximate Hypercore economic-performance index from PnL and NAV.

Hyperliquid does not expose historical vault share supply or an investable unit price through its vaultDetails API. Its rolling NAV and PnL windows can refresh at different timestamps, so the scanner-derived ERC-4626-like supply can change units between daily and HF reads. The July 2026 production investigation found that this left raw multi-hundred-percent moves in cleaned data and that a partial daily/HF repair itself created Order Block Hunter’s +275.4% clean return. Ledger flows prove NAV accounting for some intervals, but their intra-period ordering is unavailable and therefore cannot recover exact time-weighted investor returns.

The cleaned Hypercore price is consequently a conservative performance index. One freshest usable checkpoint is selected per fixed four-hour UTC bucket while retaining its original API timestamp. Missing buckets are not manufactured, and older history remains daily or weekly where Hyperliquid has already downsampled it. Between checkpoints, cumulative account-PnL change is divided by the larger of opening NAV, closing NAV, and one dollar; the resulting returns are compounded from 1.0 within each recapitalisation epoch. This denominator prevents unknown capital-flow timing and small NAV from manufacturing performance. Positive returns are capped at max_positive_return per selected checkpoint. A return at or below -100% is accepted only when NAV is zero and does not recover in the same epoch; otherwise the price is carried because applying one questionable negative PnL baseline would permanently zero the index. Non-checkpoint rows are also carried, avoiding duplicate daily/HF returns without interpolating future information backwards.

A July 2026 follow-up found a narrower timestamp problem in Fish Market. Cumulative PnL increased by $2,169.43 on 17 March while NAV remained unchanged; the same $2,169.43 appeared in NAV on 18 March with no additional PnL or capital flow. Treating the first half of this staggered API update as a complete checkpoint produced a clipped +100% return. When a checkpoint within 26 hours exhibits this exact PnL-then-NAV pattern, within a small numerical tolerance, this function carries the premature checkpoint and applies the return at the confirming checkpoint using the larger opening/confirmed NAV. Flat intermediate checkpoints may occur; any other economic change disqualifies the repair. This gives approximately +54.5% for Fish Market. The bounded, positive-only and value-matching conditions avoid suppressing large but reconciled gains in Magixbox, IKAGI and Satori Quantum HF Vault. Because confirmation arrives later, the most recent provisional checkpoint and prices compounded after it may be revised on the next cleaning run.

Input uses a timestamp index and requires id (string), chain (integer), share_price (float), total_assets (float), and cumulative PnL as either exported account_pnl (float) or scanner-shaped cumulative_pnl (float). Optional written_at timestamps select the freshest scanner batch, hypercore_source strings break otherwise equal ties in favour of HF, and boolean epoch_reset values separate performance epochs. The output preserves scanner values in raw_share_price, writes audit values to hypercore_repair_status, and recalculates Hypercore total_supply as synthetic index units so that total_assets == share_price * total_supply remains true. Hypercore total_supply is not an actual token supply.

Parameters

  • prices_df (pandas.DataFrame) – Timestamp-indexed cleaned-price input containing the columns described above. Rows must already be ordered by vault and timestamp.

  • logger (Callable[[str], None]) – Notebook, console, or structured-log adapter accepting one message.

  • max_positive_return (float) – Maximum approximate return applied at one four-hour checkpoint. The default is 1.0 (100%).

Returns

A copy with every Hypercore row expressed on its PnL/NAV performance index; all non-Hypercore rows are unchanged.

Return type

pandas.DataFrame