LighterDailyMetricsDatabase

Documentation for eth_defi.lighter.daily_metrics.LighterDailyMetricsDatabase Python class.

class LighterDailyMetricsDatabase

Bases: object

DuckDB database for storing Lighter pool daily metrics.

Stores three tables:

pool_metadata: Pool information (name, description, fees, TVL, etc.)
pool_daily_prices: Daily share price time series with returns
pool_snapshots: Append-only scan-time account, ownership, risk, and exposure observations

Parameters: path – Path to the DuckDB database file.

Methods summary

`__init__`(path)
`close`()	Close database connection.
`get_all_daily_prices`([deployment])	Retrieve all daily price data.
`get_all_pool_metadata`([deployment])	Retrieve all pool metadata ordered by TVL.
`get_latest_pool_snapshots`([deployment])	Retrieve the most recent point-in-time snapshot for every pool.
`get_pool_count`([deployment])	Get number of pools with daily price data.
`get_pool_daily_price_count`(account_index[, ...])	Get number of daily price records for a specific pool.
`get_pool_daily_prices`(account_index[, ...])	Get daily prices for a specific pool.
`get_pool_last_date`(account_index[, deployment])	Get the latest date with price data for a pool.
`get_pool_snapshot_history`(account_index[, ...])	Retrieve point-in-time snapshots for one Lighter pool.
`get_vault_count`([deployment])	Get number of pools with daily price data.
`insert_pool_snapshot`(snapshot[, deployment])	Insert one append-only Lighter pool snapshot.
`save`()	Force checkpoint to disk.
`upsert_daily_prices`(deployment, rows[, ...])	Bulk upsert daily price rows for a pool.
`upsert_pool_metadata`(deployment, ...[, ...])	Insert or update pool metadata.

__init__(path)

Parameters: path (pathlib.Path) –
Return type: None

upsert_pool_metadata(deployment, account_index, name, description=None, l1_address=None, is_llp=False, status=0, operator_fee=None, total_asset_value=None, annual_percentage_yield=None, sharpe_ratio=None, total_shares=None, operator_shares=None, created_at=None)

Insert or update pool metadata.

Parameters

deployment (str) – Stable deployment slug. Kept as the first positional argument for compatibility with the deployment-aware public API.
account_index (int) – Pool account index, unique within the deployment.
name (str) – Pool display name.
description (Optional[str]) – Pool description text.
l1_address (Optional[str]) – Operator address reported in the API’s legacy l1_address field.
is_llp (bool) – Whether this is the LLP protocol pool.
status (int) – Pool status code from the API (0 = active).
operator_fee (Optional[float]) – Operator fee percentage.
total_asset_value (Optional[float]) – Total value locked in the deployment’s collateral currency.
annual_percentage_yield (Optional[float]) – Current APY.
sharpe_ratio (Optional[float]) – Risk-adjusted return metric.
total_shares (Optional[int]) – Current outstanding pool shares.
operator_shares (Optional[int]) – Current shares owned by the pool operator.
created_at (Optional[datetime.datetime]) – Pool creation timestamp.

Return type

None

upsert_daily_prices(deployment, rows, cutoff_date=None)

Bulk upsert daily price rows for a pool.

Parameters

deployment (str) – Stable deployment slug applied to every row.
rows (list[eth_defi.lighter.daily_metrics.LighterDailyPriceRow | tuple[object, ...]]) – Daily price rows with source share and cumulative flow counters.
cutoff_date (Optional[datetime.date]) – If provided, only store rows up to this date (inclusive). Used for incremental scanning / testing.

Return type

None

insert_pool_snapshot(snapshot, deployment='ethereum')

Insert one append-only Lighter pool snapshot.

Stores queryable selection and risk metrics plus a complete JSON copy of the current account state. Historical price/return arrays are removed from that JSON because the daily table already stores them. The method does not backfill older dates: snapshots exist only from the time this collector starts, and earlier history remains missing/NaN in downstream joins.

Parameters

snapshot (eth_defi.lighter.vault.LighterPoolSnapshot) – Current account and pool state parsed from one public API response.
deployment (str) – Stable deployment slug. Defaults to Ethereum for compatibility.

Return type

None

get_pool_snapshot_history(account_index, deployment='ethereum')

Retrieve point-in-time snapshots for one Lighter pool.

Parameters

account_index (int) – Lighter pool account index.
deployment (str) – Stable deployment slug. Defaults to Ethereum for compatibility.

Returns

Snapshot rows ordered from oldest to newest. The result starts at the collection start date; no earlier values are fabricated.

Return type

pandas.DataFrame

get_latest_pool_snapshots(deployment=None)

Retrieve the most recent point-in-time snapshot for every pool.

Parameters: deployment (Optional[str]) – Optional deployment slug filter.
Returns: Latest snapshot per account, ordered by current TVL.
Return type: pandas.DataFrame

get_all_daily_prices(deployment=None)

Retrieve all daily price data.

Parameters: deployment (Optional[str]) – Optional deployment slug filter.
Returns: DataFrame with price, source-share, and cumulative-flow columns.
Return type: pandas.DataFrame

get_pool_daily_prices(account_index, deployment='ethereum')

Get daily prices for a specific pool.

Parameters

account_index (int) – Pool account index.
deployment (str) – Stable deployment slug. Defaults to Ethereum for compatibility.

Returns

DataFrame with daily price data for the pool.

Return type

pandas.DataFrame

get_all_pool_metadata(deployment=None)

Retrieve all pool metadata ordered by TVL.

Parameters: deployment (Optional[str]) – Optional deployment slug filter.
Returns: DataFrame with pool metadata.
Return type: pandas.DataFrame

get_pool_count(deployment=None)

Get number of pools with daily price data.

Parameters: deployment (Optional[str]) – Optional deployment slug filter.
Returns: Count of unique pools.
Return type: int

get_vault_count(deployment=None)

Get number of pools with daily price data.

Alias for get_pool_count() to unify the interface across Hyperliquid, GRVT, and Lighter scanners.

Parameters: deployment (Optional[str]) – Optional deployment slug filter.
Returns: Count of unique pools.
Return type: int

get_pool_daily_price_count(account_index, deployment='ethereum')

Get number of daily price records for a specific pool.

Parameters

account_index (int) – Pool account index.
deployment (str) – Stable deployment slug. Defaults to Ethereum for compatibility.

Returns

Count of daily price records.

Return type

int

get_pool_last_date(account_index, deployment='ethereum')

Get the latest date with price data for a pool.

Parameters

account_index (int) – Pool account index.
deployment (str) – Stable deployment slug. Defaults to Ethereum for compatibility.

Returns

Latest date or None if no data.

Return type

Optional[datetime.date]

save()

Force checkpoint to disk.

Return type: None

close()

Close database connection.

Return type: None