DeriveV3VaultDatabase

Documentation for eth_defi.derive.v3_vault_metrics.DeriveV3VaultDatabase Python class.

class DeriveV3VaultDatabase

Bases: object

File-backed public vault metadata and daily performance observations.

Metadata is keyed by (network, subaccount_id); prices also include timestamp. Amounts are stored as decimal strings. Ingestion handles duplicate keys without unique constraints because large ART indexes have caused native DuckDB crashes under Python 3.14 in this repository.

Parameters: path – Destination DuckDB file.

Methods summary

`__init__`(path)
`close`()	Close the file-backed database connection.
`get_vault_metadata`(network)	Read current vault metadata for one deployment.
`get_vault_prices`(network)	Read sampled vault prices for one deployment.
`store_vault`(network, vault, prices)	Replace one vault's metadata and fetched history transactionally.

__init__(path)

Parameters: path (pathlib.Path) –

store_vault(network, vault, prices)

Replace one vault’s metadata and fetched history transactionally.

A fetched point replaces the stored point at the same timestamp. All other timestamps survive, including gaps within the fetched range. observed_at retains the first scan time when metadata is refreshed.

Parameters

network (str) – Source deployment name.
vault (eth_defi.derive.v3_vaults.DeriveV3Vault) – Fresh public vault metadata.
prices (list[eth_defi.derive.v3_vaults.DeriveV3VaultPrice]) – Fetched performance points.

Returns

None.

Return type

None

get_vault_metadata(network)

Read current vault metadata for one deployment.

Includes previously stored vaults that no longer appear in the API listing. first_price_at comes from the earliest stored price.

Parameters: network (str) – testnet or mainnet.
Returns: DataFrame with the vault_metadata columns and nullable first_price_at as a naive UTC timestamp. One row per vault.
Return type: pandas.DataFrame

get_vault_prices(network)

Read sampled vault prices for one deployment.

Rows are ordered by subaccount ID, then observation timestamp.

Parameters: network (str) – testnet or mainnet.
Returns: DataFrame with integer subaccount_id, naive UTC timestamp and written_at, string network, and decimal strings share_price, nav_usd (nullable) and total_shares.
Return type: pandas.DataFrame

close()

Close the file-backed database connection.

Returns: None.
Return type: None