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) 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.

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 block.
`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 this row was actually written/fetched (naive UTC).

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
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")

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 block.

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.

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: "1h", "4h", "24h". The scanner adjusts frequency based on vault TVL and activity; low-TVL vaults may be polled less frequently.

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 this row was actually written/fetched (naive UTC). None until stamped at write time.

__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.