hyperliquid.permission

Documentation for eth_defi.hyperliquid.permission Python module.

Independent, auditable HyperCore deposit-permission observations.

The portfolio timestamp in vaultDetails describes prices, not permission. Keep successful response receipts, explicit unknown snapshots and historical uncertainty intervals independently of price updates. See the info endpoint.

Functions

append_permission_observation(connection, ...)	Append once by observation ID, refusing a conflicting reuse of an ID.
build_permission_observation(vault, info)	Capture the successful response before portfolio processing starts.
export_permission_history(database_paths, ...)	Export separate source observations from closed scanner databases.
initialise_permission_schema(connection)	Create unconstrained permission, error and source-reference tables.
project_permission_prices(prices, ...)	Attach a point-in-time convenience projection without creating prices.
read_permission_observations(connection)	Read exact observations and uncertainty boundaries without resampling.
select_permission_state(observations, decisions)	Select coherent permission snapshots available at each decision.

Classes

PermissionObservation

A coherent source response or a retrospective uncertainty interval.

class PermissionObservation

Bases: object

A coherent source response or a retrospective uncertainty interval.

Legacy availability bounds are separate from exact response receipt times. Unknown flags in a successful response supersede older known flags.

observation_id: str

Stable evidence identity; genuine new fetches receive distinct IDs.

vault_address: eth_typing.evm.HexAddress

Lowercase Hypercore vault address.

record_kind: str

observation or uncertainty_boundary.

permission_observed_at: Optional[datetime.datetime]

API receipt clock, or price clock for legacy_price_timestamp provenance.

written_at: Optional[datetime.datetime]

Persistence time, separate from permission freshness.

evidence_available_at: Optional[datetime.datetime]

Verified archive availability bound for deny-only evidence.

is_closed: Optional[bool]

Nullable closure flag from this same response.

allow_deposits: Optional[bool]

Nullable leader deposit-policy flag from this same response.

relationship_type: Optional[str]

Vault relationship used to interpret the same capacity input.

leader_fraction: Optional[float]

Recorded leader capital fraction, including recoverable archive values.

capacity_observed_at: Optional[datetime.datetime]

Independent capacity receipt clock, absent for inferred flags.

provenance: str

Clock/evidence quality, including observed and legacy_price_timestamp.

source_endpoint: str

Origin of the retained source response or archive evidence.

collector_version: str

Collector schema/behaviour version for this record.

payload_json: str

Original coherent policy inputs or complete recovered source row.

payload_sha256: str

Digest of the retained payload text.

correction_parent_id: Optional[str]

Earlier record superseded by an explicit correction, if supplied.

source_row_key: Optional[str]

Original scanner/raw price key for inferred archive evidence.

effective_from: Optional[datetime.datetime]

Start of a retrospective uncertainty interval, inclusive.

effective_to: Optional[datetime.datetime]

End of a retrospective uncertainty interval, if bounded.

reason: Optional[str]

Human-readable interpretation or uncertainty explanation.

max_deposit: Optional[float]

Recorded trading-policy cap in USDC; zero is distinct from missing.

__init__(observation_id, vault_address, record_kind='observation', permission_observed_at=None, written_at=None, evidence_available_at=None, is_closed=None, allow_deposits=None, relationship_type=None, leader_fraction=None, capacity_observed_at=None, provenance='observed_unknown', source_endpoint='POST /info vaultDetails', collector_version='2', payload_json='{}', payload_sha256='', correction_parent_id=None, source_row_key=None, effective_from=None, effective_to=None, reason=None, max_deposit=None)

Parameters

• observation_id (str) –

• vault_address (eth_typing.evm.HexAddress) –

• record_kind (str) –

• permission_observed_at (Optional[datetime.datetime]) –

• written_at (Optional[datetime.datetime]) –

• evidence_available_at (Optional[datetime.datetime]) –

• is_closed (Optional[bool]) –

• allow_deposits (Optional[bool]) –

• relationship_type (Optional[str]) –

• leader_fraction (Optional[float]) –

• capacity_observed_at (Optional[datetime.datetime]) –

• provenance (str) –

• source_endpoint (str) –

• collector_version (str) –

• payload_json (str) –

• payload_sha256 (str) –

• correction_parent_id (Optional[str]) –

• source_row_key (Optional[str]) –

• effective_from (Optional[datetime.datetime]) –

• effective_to (Optional[datetime.datetime]) –

• reason (Optional[str]) –

• max_deposit (Optional[float]) –

Return type

None

initialise_permission_schema(connection)

Create unconstrained permission, error and source-reference tables.

The owner serialises writes; application deduplication avoids ART indexes on large Python 3.14 file-backed ingestion tables.

Parameters

connection (_duckdb.DuckDBPyConnection) – Caller-owned DuckDB connection.

Returns

None.

Return type

None

build_permission_observation(vault, info)

Capture the successful response before portfolio processing starts.

The client retains trimmed raw flags and their receipt clock. Test doubles without this envelope use the immediately returned parsed response instead.

Parameters

• vault (eth_defi.hyperliquid.vault.HyperliquidVault) – Client that just fetched vaultDetails.

• info (Optional[eth_defi.hyperliquid.vault.VaultInfo]) – Parsed response, including nullable flags and policy inputs.

Returns

New immutable coherent observation, even without price history.

Return type

eth_defi.hyperliquid.permission.PermissionObservation

append_permission_observation(connection, observation, *, new_fetch=False)

Append once by observation ID, refusing a conflicting reuse of an ID.

Call under the database owner’s writer lock. New fetches use new IDs; persistence retries of the same observation are idempotent.

Parameters

• connection (_duckdb.DuckDBPyConnection) – Caller-owned cursor under a serialised writer.

• observation (eth_defi.hyperliquid.permission.PermissionObservation) – Complete response or migration annotation.

• new_fetch (bool) – Fresh collector UUID; skip an unnecessary full-table retry lookup.

Returns

None.

Return type

None

read_permission_observations(connection)

Read exact observations and uncertainty boundaries without resampling.

Inferred legacy price clocks remain distinguished by their provenance; migration/publication clocks never substitute for observation clocks.

Parameters

connection (_duckdb.DuckDBPyConnection) – Open scanner database, optionally read-only.

Returns

Frame with the columns of PermissionObservation.

Return type

pandas.DataFrame

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.

project_permission_prices(prices, observations, time_column)

Attach a point-in-time convenience projection without creating prices.

The independent sidecar is authoritative when a response arrives after the latest price or when several responses share one price timestamp.

Archived policy inputs use the last recorded price-row snapshot. Actual responses, including explicit unknowns, take precedence. Publication never supplies a new observation clock, and missing clocks do not erase values.

Parameters

• prices (pandas.DataFrame) – Scanner price frame with vault identity and source time.

• observations (pandas.DataFrame) – Independent source observations and migration intervals.

• time_column (str) – date or timestamp in the price frame.

Returns

Frame with nullable flags, retained policy inputs and original clocks.

Return type

pandas.DataFrame

export_permission_history(database_paths, destination, *, observations=None)

Export separate source observations from closed scanner databases.

Repeated backup copies deduplicate only identical observation IDs. A reused ID with different contents is a hard error instead of silent precedence.

Parameters

• database_paths (list[pathlib.Path]) – Existing daily/HF scanner files opened read-only.

• destination (pathlib.Path) – Sidecar Parquet path; replaced atomically.

• observations (Optional[pandas.DataFrame]) – Already-read observations from active scanner owners; avoids reopening with a different DuckDB configuration.

Returns

Combined exact observation frame, including explicit uncertainty.

Return type

pandas.DataFrame