RawVaultPriceRow

Documentation for eth_defi.vault.base.RawVaultPriceRow Python class.

class RawVaultPriceRow

Bases: TypedDict

Schema for a single row in the uncleaned vault price parquet file.

This is the format produced by VaultHistoricalRead.export() and written to vault-prices-1h.parquet by the historical scanner (scan_historical_prices_to_parquet()).

The canonical columns are defined by VaultHistoricalRead.to_pyarrow_schema(). Native protocol merges (Hyperliquid, GRVT, Lighter, Hibachi, ApeX) may add extra columns (e.g. account_pnl, leader_fraction) that are preserved across schema migrations but are not part of this TypedDict.

See CleanedVaultPriceRow in eth_defi.research.wrangle_vault_prices for the enriched schema produced by the cleaning pipeline.

Routine live scans aim to retain a genuine observation before its source timestamp is 14 days old for a vault with verified USD TVL of at least $1,500. A previously qualified vault remains covered down to $1,000. This applies to successfully observed vaults; failed source reads are reported as overdue rather than represented by copied rows. Historical backfills retain the existing change-based sampling behaviour.

Attributes summary

`chain`	EVM chain id (e.g.
`address`	Vault contract address, lowercase.
`block_number`	Block number of the on-chain read.
`timestamp`	Naive UTC timestamp of the real source observation, with one-second EVM block precision.
`share_price`	Share price in denomination token units.
`total_assets`	Total assets under management (TVL) in denomination token units.
`total_supply`	Total supply of vault share tokens.
`performance_fee`	Performance fee at time of read (e.g.
`management_fee`	Management fee at time of read (e.g.
`errors`	Comma-separated RPC error messages, or empty string if no errors.
`vault_poll_frequency`	Dynamic poll frequency used when taking this sample.
`max_deposit`	Maximum deposit amount allowed (ERC-4626 `maxDeposit`), in denomination token units.
`max_redeem`	Maximum redeem amount allowed (ERC-4626 `maxRedeem`), in share token units.
`deposits_open`	Whether deposits were open: `"true"`, `"false"`, or `""` (unknown).
`redemption_open`	Whether redemptions were open: `"true"`, `"false"`, or `""` (unknown).
`trading`	Whether the vault was actively trading: `"true"`, `"false"`, or `""` (unknown).
`available_liquidity`	Available liquidity for immediate withdrawal in denomination token units.
`utilisation`	Utilisation ratio (0.0–1.0) for lending vaults.
`written_at`	When the row was written (naive UTC), not when the source was observed.
`perp_long_notional`	Current long open-position notional for native perp vault accounts.
`perp_short_notional`	Current absolute short open-position notional for native perp vault accounts.
`perp_open_position_count`	Count of non-zero current perp positions for native vault accounts.
`perp_largest_position_notional`	Largest absolute current perp position notional.
`perp_quote_asset`	Exact source denomination for the perp notionals.
`perp_position_data_status`	Generic current position-data availability state.
`perp_metrics_observed_at`	Source position effective time for the materialised metrics.

Methods summary

`__init__`(args, *kwargs)
`clear`()	Remove all items from the dict.
`copy`()	Return a shallow copy of the dict.
`fromkeys`([value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`items`()	Return a set-like object providing a view on the dict's items.
`keys`()	Return a set-like object providing a view on the dict's keys.
`pop`(k[,d])	If the key is not found, return the default if given; otherwise, raise a KeyError.
`popitem`()	Remove and return a (key, value) pair as a 2-tuple.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`update`([E, ]**F)	If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`()	Return an object providing a view on the dict's values.

chain: int

EVM chain id (e.g. 1 for Ethereum, 8453 for Base).

Native (non-EVM) protocols use synthetic in-house chain ids:

9999 — Hypercore (native Hyperliquid vaults), see HYPERCORE_CHAIN_ID
9998 — Lighter DEX pools, see LIGHTER_CHAIN_ID
9997 — Hibachi native vaults, see HIBACHI_CHAIN_ID
9995 — ApeX native vaults, see APEX_CHAIN_ID
9993 — Derive v3 native vaults, see DERIVE_V3_CHAIN_ID
325 — GRVT (Gravity Markets), see GRVT_CHAIN_ID

The full mapping lives in CHAIN_NAMES.

address: str

Vault contract address, lowercase.

Address formats vary by protocol:

EVM vaults: 0x-prefixed hex (e.g. "0xabcd...")
Hypercore: 0x-prefixed hex (Hyperliquid vault addresses)
GRVT: platform-specific id (e.g. "vlt:xxx")
Lighter: synthetic id (e.g. "lighter-pool-281474976710654")
Hibachi: synthetic id (e.g. "hibachi-vault-2")
ApeX: synthetic id (e.g. "apex-vault-2044287989957394432")

See is_good_multichain_address() for the validation function that accepts all these formats.

block_number: int: Block number of the on-chain read. For native protocols without blocks this is a synthetic sequence number.

timestamp: ForwardRef('pd.Timestamp', module='eth_defi.vault.base')

Naive UTC timestamp of the real source observation, with one-second EVM block precision. This, not written_at, determines freshness.

Modern high-throughput chains, including Monad, can produce multiple blocks in the same second. This value may therefore repeat for the same vault; raw-row identity is (chain, address, block_number), not timestamp. The Parquet millisecond logical type is used only for compatibility, as one-second precision is sufficient for price scans.

share_price: float

Share price in denomination token units.

For ERC-4626 vaults this is read directly from the contract (convertToAssets(1e decimals)). GRVT, Lighter, and Hibachi provide native share prices from their respective APIs. Hypercore (native Hyperliquid vaults) does not expose a share price; it is internally calculated as total_assets / total_supply from reconstructed equity curves and deposit/withdrawal histories. See eth_defi.hyperliquid.combined_analysis for the Hypercore share price derivation.

total_assets: float: Total assets under management (TVL) in denomination token units. Eligibility for the 14-day live row limit uses the reader state’s existing denomination-to-USD estimate; this field is not USD for ETH/BTC-denominated EVM vaults. Native vaults use USD accounting.

total_supply: float: Total supply of vault share tokens.

performance_fee: float: Performance fee at time of read (e.g. 0.20 = 20%). NaN if unknown.

management_fee: float: Management fee at time of read (e.g. 0.02 = 2%). NaN if unknown.

errors: str

Comma-separated RPC error messages, or empty string if no errors.

Example values: "total_supply call failed", "total_assets zero: 0", "total_supply call missing".

vault_poll_frequency: str

Dynamic poll frequency used when taking this sample. Empty string if not set.

Example values: "large_tvl", "small_tvl", "tiny_tvl", "peaked", "faded", "first_read", "unverified_tvl" and "contextual". Unknown TVL polls hourly without certifying USD value. Peaked and faded vaults poll weekly; otherwise estimated USD TVL of at least $10,000 polls hourly, $1,000-$10,000 daily, and tiny vaults weekly after their initial two-week daily period.

max_deposit: float: Maximum deposit amount allowed (ERC-4626 maxDeposit), in denomination token units. NaN if unknown. ERC-4626 vaults only.

max_redeem: float: Maximum redeem amount allowed (ERC-4626 maxRedeem), in share token units. NaN if unknown. ERC-4626 vaults only.

deposits_open: str: Whether deposits were open: "true", "false", or "" (unknown). Stored as string for legacy reasons; see deposit_closed_reason in CleanedVaultPriceRow. ERC-4626 vaults only.

redemption_open: str: Whether redemptions were open: "true", "false", or "" (unknown). ERC-4626 vaults only.

trading: str: Whether the vault was actively trading: "true", "false", or "" (unknown). Currently only supported for D2 Finance vaults.

available_liquidity: float: Available liquidity for immediate withdrawal in denomination token units. Lending protocol vaults only (IPOR, Euler, Morpho, Gearbox, etc.). NaN otherwise.

utilisation: float: Utilisation ratio (0.0–1.0) for lending vaults. NaN if not applicable. Lending protocol vaults only.

Warning

This metric measures capital deployment efficiency (how much of the vault’s AUM is lent out), not redeemable liquidity. For single-market vaults (Euler EVK, Gearbox, Silo) high utilisation does mean low available liquidity. For multi-market aggregators (Morpho, Euler Earn, IPOR) a vault can show 95% utilisation yet have substantial instantly redeemable liquidity in low-utilisation underlying markets. See README-vault-redeemable.md and README-utilisation.md in eth_defi.erc_4626.vault_protocol for details.

written_at: ForwardRef('pd.Timestamp | None', module='eth_defi.vault.base'): When the row was written (naive UTC), not when the source was observed. A fresh written_at never makes an old timestamp current.

perp_long_notional: float: Current long open-position notional for native perp vault accounts.

perp_short_notional: float: Current absolute short open-position notional for native perp vault accounts.

perp_open_position_count: int: Count of non-zero current perp positions for native vault accounts.

perp_largest_position_notional: float: Largest absolute current perp position notional.

perp_quote_asset: str: Exact source denomination for the perp notionals.

perp_position_data_status: str: Generic current position-data availability state.

perp_metrics_observed_at: ForwardRef('pd.Timestamp | None', module='eth_defi.vault.base'): Source position effective time for the materialised metrics. Account-level data uses one-second resolution. The timestamp stays attached to stale and forward-aligned values so their age is explicit.

__init__(*args, **kwargs)

__new__(**kwargs)

clear(): Remove all items from the dict.

copy(): Return a shallow copy of the dict.

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items(): Return a set-like object providing a view on the dict’s items.

keys(): Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values(): Return an object providing a view on the dict’s values.