VaultHistoricalRead

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

class VaultHistoricalRead

Bases: object

Vault share price and fee structure at the point of time.

Attributes summary

vault

Vault for this result is

block_number

block number of the reade

timestamp

Naive datetime in UTC

share_price

What was the share price in vault denomination token

total_assets

NAV / Assets under management in denomination token

total_supply

Number of share tokens

performance_fee

What was the vault performance fee around the time

management_fee

What was the vault management fee around the time

errors

Add RPC error messages and such related to this read

vault_poll_frequency

What dynamic read frequency was used at the time of taking this sample

max_deposit

Maximum deposit amount allowed at this point in time (ERC-4626 maxDeposit).

max_redeem

Maximum redeem amount allowed at this point in time (ERC-4626 maxRedeem).

deposits_open

Whether deposits were open at this point in time (protocol-specific logic)

redemption_open

Whether redemptions were open at this point in time (protocol-specific logic)

trading

Whether the vault was actively trading at this point in time.

available_liquidity

Available liquidity for immediate withdrawal.

utilisation

Utilisation percentage of the lending vault.

Methods summary

__init__(vault, block_number, timestamp, ...)

export()

Convert historical read for a Parquet/DataFrame export.

is_almost_equal(other[, epsilon])

Check if the read statistics match.

migrate_parquet_schema(existing_table)

Migrate an existing Parquet table to the current schema.

to_pyarrow_schema()

Get parquet schema for writing this data.

write_uncleaned_arrow_table(table, path[, ...])

Write a pre-aligned raw-price Arrow table with atomic verification.

write_uncleaned_parquet(df, path[, compression])

Write a DataFrame to the uncleaned parquet using proper PyArrow types.
vault: eth_defi.vault.base.VaultBase

Vault for this result is

block_number: int

block number of the reade

timestamp: datetime.datetime

Naive datetime in UTC

share_price: Optional[decimal.Decimal]

What was the share price in vault denomination token

None if the read failed (call execution reverted)

total_assets: Optional[decimal.Decimal]

NAV / Assets under management in denomination token

None if the read failed (call execution reverted)

total_supply: Optional[decimal.Decimal]

Number of share tokens

None if the read failed (call execution reverted)

performance_fee: Optional[float]

What was the vault performance fee around the time

management_fee: Optional[float]

What was the vault management fee around the time

errors: Optional[list[str]]

Add RPC error messages and such related to this read

Exported as empty string in Parquet if no errors, otherwise concat strings

vault_poll_frequency: Optional[str]

What dynamic read frequency was used at the time of taking this sample

Useful for diagnostics of scanning process

max_deposit: Optional[decimal.Decimal]

Maximum deposit amount allowed at this point in time (ERC-4626 maxDeposit).

In denomination token units.

max_redeem: Optional[decimal.Decimal]

Maximum redeem amount allowed at this point in time (ERC-4626 maxRedeem).

In share token units.

deposits_open: Optional[bool]

Whether deposits were open at this point in time (protocol-specific logic)

redemption_open: Optional[bool]

Whether redemptions were open at this point in time (protocol-specific logic)

trading: Optional[bool]

Whether the vault was actively trading at this point in time.

Currently only supported for D2 Finance vaults.

available_liquidity: Optional[decimal.Decimal]

Available liquidity for immediate withdrawal.

Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.) In denomination token units.

utilisation: Optional[float]

Utilisation percentage of the lending vault.

Only applicable to lending protocol vaults. Value between 0.0 and 1.0 (0% to 100%).

is_almost_equal(other, epsilon=0.001)

Check if the read statistics match.

  • Throttle with epsilon relative difference to get rid of small increment rows

Parameters
Return type

bool

export()

Convert historical read for a Parquet/DataFrame export.

The returned dict conforms to RawVaultPriceRow.

Return type

eth_defi.vault.base.RawVaultPriceRow

classmethod to_pyarrow_schema()

Get parquet schema for writing this data.

  • Write multiple chains, multiple vaults, to a single Parquet file

  • Column semantics are documented in RawVaultPriceRow

Return type

pyarrow.Schema

static migrate_parquet_schema(existing_table)

Migrate an existing Parquet table to the current schema.

When new columns are added to to_pyarrow_schema(), existing parquet files still have the old schema. This function adds missing columns as null arrays so incremental scans can write new data without losing columns.

Non-canonical columns (e.g. account_pnl, leader_fraction added by native protocol merges) are preserved so that the EVM scanner does not destroy data written by Hyperliquid/GRVT/Lighter.

Parameters

existing_table (pyarrow.Table) – Table read from an older parquet file.

Returns

Table with all canonical columns present (missing ones filled with nulls), legacy columns removed, extra columns preserved.

Return type

pyarrow.Table

static write_uncleaned_parquet(df, path, compression='zstd')

Write a DataFrame to the uncleaned parquet using proper PyArrow types.

Native protocol merge functions (Hyperliquid, GRVT, Lighter) must use this instead of pandas.DataFrame.to_parquet() to avoid type promotion (e.g. timestamp[ms] → timestamp[us]) that breaks migrate_parquet_schema() on the next EVM scan run.

Columns present in the canonical schema are cast to their canonical types. Extra columns (from native protocols) are kept with their pandas-inferred types. No pandas index is written.

Parameters

  • df (pd.DataFrame) – Combined DataFrame to write.

  • path (pathlib.Path) – Output parquet file path.

  • compression (str) – Parquet compression codec.

Return type

None

static write_uncleaned_arrow_table(table, path, compression='zstd')

Write a pre-aligned raw-price Arrow table with atomic verification.

Both the EVM-compatible pandas writer and the direct PyArrow native merge path use this method. The caller is responsible for aligning canonical column types before calling this method; the output is stamped with the current Docker metadata.version provenance, written beside the target, verified, and atomically replaced only on success.

Parameters

  • table (pyarrow.Table) – Raw price table with its final canonical and native-only schema.

  • path (pathlib.Path) – Target uncleaned parquet path.

  • compression (str) – Parquet compression codec.

Return type

None

__init__(vault, block_number, timestamp, share_price, total_assets, total_supply, performance_fee, management_fee, errors, vault_poll_frequency=None, max_deposit=None, max_redeem=None, deposits_open=None, redemption_open=None, trading=None, available_liquidity=None, utilisation=None)
Parameters
Return type

None