select_permission_state

Documentation for eth_defi.hyperliquid.permission.select_permission_state function.

select_permission_state(observations, decisions, frequency=None, *, legacy_max_age=datetime.timedelta(days=2))

Select coherent permission snapshots available at each decision.

Round availability upwards before selection when a decision frequency is supplied. Retrospective uncertainty intervals override earlier open state irrespective of migration publication time. Explicit unknown responses remain in selection, preventing per-field filling across source snapshots. When no eligible genuine snapshot exists, recovered backup flags may use their price clock with legacy_price_timestamp provenance. They supply recorded leader shares and policy caps without requiring a capacity clock, and never override a genuine unknown response.

Parameters

  • observations (pandas.DataFrame) – Exact observation table with nullable flags and clocks.

  • decisions (pandas.DataFrame) – Frame with vault_address (string) and timestamp (naive UTC).

  • frequency (Optional[str]) – Optional Pandas decision frequency such as 4h.

  • legacy_max_age (datetime.timedelta) – Maximum carry-forward age of an inferred backup flag, measured from its original price clock.

Returns

Decision frame plus snapshot values, provenance and original clocks.

Return type

pandas.DataFrame

Performance and limitations:

  • All uncertainty boundaries of a vault are evaluated at once with numpy, so the boundary count adds little cost. Memory per vault is a few (boundaries, decisions) boolean matrices, e.g. 100 boundaries over 10,000 decisions take a few megabytes.

  • Vaults are still processed one at a time, with a few as-of joins and pandas assignments each. This costs roughly 10 milliseconds per vault, e.g. about 8 seconds for 600 HyperCore vaults with 3,000 decisions each.

  • The per-vault loop is kept because the output dtypes depend on it: each vault’s columns take the dtypes pandas assignment gives that vault’s data, e.g. None versus NaN in object columns, and pandas.concat() unifies them. A whole-frame implementation needs an explicit output dtype contract first, as consumers can treat NaN and None differently.