hyperliquid.permission_recovery

Documentation for eth_defi.hyperliquid.permission_recovery Python module.

Backed-up, transactional recovery of HyperCore prices and permission evidence.

Old price-row flags have no independent response receipts. Recover their historical state from explicitly selected backups using the price timestamp as an inferred permission clock. Preserve provenance so an approximation is never labelled as an authenticated API receipt. See issue https://github.com/tradingstrategy-ai/web3-ethereum-defi/issues/1628.

Module Attributes

`DATABASE_NAMES`	Scanner databases affected by the historical HyperCore export repairs.
`BACKUP_DATES`	Retained pre-repair scanner archives in newest-first preference order.

Functions

`prepare_price_timestamp_permissions`(...)	Stage legacy permission snapshots with an explicitly inferred price clock.
`recover_permissions`(target, sources, ...[, ...])	Restore missing price keys and retain uncertain legacy permission evidence.
`restore_price_timestamp_permissions`(...)	Apply inferred legacy snapshots without rewriting prices or genuine receipts.

DATABASE_NAMES = ('hyperliquid-vaults', 'hyperliquid-vaults-hf'): Scanner databases affected by the historical HyperCore export repairs.

BACKUP_DATES = ('2026-10-05', '2026-10-04', '2026-10-03', '2026-10-02', '2026-10-01', '2026-09-30', '2026-09-29'): Retained pre-repair scanner archives in newest-first preference order.

prepare_price_timestamp_permissions(connection, table, time_column, archives, parquets)

Stage legacy permission snapshots with an explicitly inferred price clock.

Only operator-selected backup sources supply flags. Current target flags are excluded because this repair addresses their known corruption. Archive order resolves matching-key conflicts, with raw Parquet last. A source row with no flags supplies no permission evidence. HLP identity comes from its source metadata; capacity receives no inferred freshness clock.

Parameters

connection (_duckdb.DuckDBPyConnection) – Caller-owned connection; only TEMP tables are written.
table (str) – Allowlisted scanner price table name.
time_column (str) – Source price clock column, date or timestamp.
archives (list[tuple[str, str, str, str | None, str | None]]) – Price alias, immutable path, SHA-256, optional metadata and permission aliases.
parquets (list[tuple[str, str, str, set[str]]]) – Raw view alias, immutable path, SHA-256 and available columns.

Returns

None; prepares legacy_permission_candidates for dry/apply paths.

Return type

None

restore_price_timestamp_permissions(connection, table)

Apply inferred legacy snapshots without rewriting prices or genuine receipts.

The endpoint’s inferred annotations are rebuilt transactionally from the explicitly selected backup preference. Stable IDs retain their original annotation write clock, making reapplication idempotent. Raw source payloads and references remain auditable; permission_observed_at carries the inferred price clock only for records explicitly labelled legacy_price_timestamp.

Parameters

connection (_duckdb.DuckDBPyConnection) – Caller-owned connection inside the recovery transaction.
table (str) – Allowlisted price table defining this annotation scope.

Returns

None after applying prepared candidates.

Return type

None

recover_permissions(target, sources, backup_dir, *, dry_run=True, source_available_at=None, parquet_sources=None)

Restore missing price keys and retain uncertain legacy permission evidence.

Current target values win matching-key conflicts; every differing archive row is retained in an audit table. Sources must be immutable scanner DuckDB files. Never pass a live production database as a local rehearsal target. Recovered backup flags use their price timestamp as an explicitly inferred permission clock when no genuine receipt is available. Missing backup flags remain unknown. The corrupted target’s flags never supply this fallback. Mutation is backed up and committed atomically, including ART index removal.

Parameters

target (pathlib.Path) – Existing target database; stop its owner before applying.
sources (list[pathlib.Path]) – Earlier scanner database snapshots in preference order.
backup_dir (pathlib.Path) – Directory for verified pre-mutation backups.
dry_run (bool) – Read-only analysis; default True.
parquet_sources (Optional[list[pathlib.Path]]) – Optional raw published Parquets, restored after DuckDB sources. Cleaned Parquets are refused.
source_available_at (Optional[dict[str, datetime.datetime]]) – Optional verified archive availability bounds, keyed by absolute source filename. These are never API receipt clocks.

Returns

Counts, archive hashes, conflicts and optional own-backup receipt.

Return type

dict