vault_report.sections

Documentation for eth_defi.vault_report.sections Python module.

Vault rankings and tables for the monthly vault report.

Each report section is a ranked subset of the vault metrics loaded by eth_defi.vault_report.data.fetch_vault_report_data(). The post structure is described in eth_defi/vault_report/README-blog-post-outline.md.

Vaults are classified into groups; each group except Other is ranked in its own table:

Lending: strategy tagged as lending, or a known lending protocol, see LENDING_PROTOCOL_SLUGS
Real-world assets (RWA): strategy tagged as investing in, lending against or financing real-world assets, see RWA_STRATEGY_TAGS
Perpetual futures DEX: Hyperliquid, GRVT, Lighter and other native trading vaults
AMM pools: GMX GM and GLV pools and Curve-based YieldBasis pools
Tokenised funds: vaults flagged tokenised_fund, e.g. money market funds
Other: everything else, e.g. yield aggregators and trading vaults. It has no section of its own; its vaults appear in the new vaults, per-chain, yield and risk and return sections

Tables rank by the annualised one-month return, like the website’s vault pages, net of fees when fee data is known and gross otherwise, shown without a net or gross marker. Charts use the steadier annualised three-month return, CHART_RETURN.

How the universes are narrowed, see eth_defi.vault_report.report.generate_monthly_vault_report():

filter_eligible_vaults() drops blacklisted vaults, vaults without TVL or a one-month return, and stale vaults. The result feeds the report statistics and the inflows and outflows.
select_comparable_vaults() drops vaults whose protocol is not identified, because their returns are often artefacts. Every table and chart that compares returns starts from here.
The investability check (eth_defi.vault_report.vault_checks) removes vaults that are not investable in practice.
exclude_amm_pools() leaves AMM pools only in their own section.
The select_* and calculate_* functions apply per-section TVL, activity, risk and outlier thresholds from ReportCriteria.

TVL history charts, calculate_protocol_tvl_history() and friends, only drop blacklisted vaults, select_tvl_history_vaults(), so their totals match the website’s historical TVL charts.

Units: returns, volatilities and drawdowns are fractions (0.05 = 5%), as in the top vaults export; TVL is in USD; timestamps are naive UTC.

Module Attributes

`UNKNOWN_PROTOCOL_SLUG`	Protocol slug for vaults whose protocol we could not identify
`BLACKLISTED_RISK`	Technical risk label for vaults excluded from all listings
`MAX_DISPLAYED_SHARPE`	Sharpe ratios above this are displayed as `>100`.
`CAPPED_ANNUALISED_RETURN`	The top vaults export caps annualised returns at 10,000%, as the fraction 100.0 (`max_cagr` in `eth_defi.research.vault_metrics` period metrics).
`CAPPED_RETURN_LABEL`	Label of a capped annualised return, like on the website
`SPARKLINE_URL`	Public vault sparkline images, rendered by `eth_defi.research.sparkline_export` PNG rather than SVG, because email clients such as Gmail strip SVG images from newsletters
`LENDING_STRATEGY_TAGS`	Strategy tags that make a vault a lending vault
`RWA_STRATEGY_TAGS`	Strategy tags that make a vault a real-world asset (RWA) vault, see `eth_defi.vault.strategy_tag.StrategyTag`.
`LENDING_PROTOCOL_SLUGS`	Protocols whose vaults are lending vaults even without a strategy tag.
`AMM_POOL_FEATURE`	Vault feature of AMM liquidity-provider shares, set by the scanner for GMX GM and GLV pools and Curve-based YieldBasis LTs, see `eth_defi.erc_4626.core.ERC4626Feature.amm_pool_like`
`TOKENISED_FUND_FLAG`	Vault flag for tokenised funds, such as money market and treasury funds
`UNIDENTIFIED_PROTOCOL_SLUGS`	Protocol slugs that mean the vault's protocol has not been identified yet: generic ERC-4626 and ERC-7540 vaults and placeholders.
`UNIDENTIFIED_PROTOCOL_NAMES`	Protocol names, lower case, that mean the same.
`OTHER_PROTOCOL`	Label of the single pile of vaults whose protocol is not identified.
`LENDING`	Vault group labels, stored in the `group` column by `eth_defi.vault_report.data.prepare_vault_metrics()`, see `classify_vault()`.
`VAULT_TABLE_COLUMNS`	Default columns for vault tables, same as in the previous blog posts.
`CHAIN_TABLE_COLUMNS`	Columns for the per-chain table, chain first
`NUMERIC_COLUMNS`	Right-aligned numeric columns
`NOWRAP_COLUMNS`	Columns whose values must not wrap onto two lines, e.g.
`CHART_RETURN`	Column with the return used by all charts: the annualised three-month return, net of fees when known.
`LEGACY_VAULT_URLS`	Legacy vault page URLs and their current form.

Functions

`calculate_average_yields`(yield_vaults, ...)	Calculate the TVL-weighted average three-month yield per group.
`calculate_chain_tvl_changes`(eligible_df, ...)	Find the blockchains whose vault TVL changed the most over the last month, in dollars.
`calculate_chain_tvl_history`(tvl_history, ...)	Sum vault TVL history per blockchain.
`calculate_chain_yields`(yield_vaults, criteria)	Average yield of the largest blockchains by TVL.
`calculate_fund_nav_history`(tvl_history, funds_df)	Sum tokenised fund NAV history per fund.
`calculate_high_yield_protocols`(yield_vaults, ...)	Average yield of the highest-yielding vault protocols.
`calculate_protocol_tvl_history`(tvl_history, ...)	Sum vault TVL history per protocol.
`calculate_protocol_yields`(yield_vaults, criteria)	Average yield of the largest vault protocols by TVL.
`calculate_tvl_changes`(eligible_df, criteria)	Find the vaults with the largest TVL changes over the last month, in dollars.
`canonical_vault_urls`(text)	Rewrite legacy vault page URLs to the website's current `/vaults/` paths.
`classify_vault`(vault)	Classify a vault into one of the report's vault groups.
`exclude_amm_pools`(vaults_df, criteria)	Leave AMM pools out of the rankings and charts outside their own section.
`exclude_chart_risks`(vaults_df, criteria)	Leave out vaults whose risk rating is too high to feature in a chart.
`filter_eligible_vaults`(vaults_df, ...)	Remove vaults that must not appear in any listing.
`find_period`(period_results, period)	Find one period's results in a vault's `period_results`.
`format_return`(net, gross)	Format an annualised return, preferring the net value.
`format_sharpe`(value)	Format a Sharpe ratio.
`format_tvl`(current)	Format the current TVL for a table cell.
`format_vault_cells`(row[, sparkline_ids])	Format one vault as HTML table cells.
`group_min_tvl`(group, criteria)	Minimum TVL of a vault group's table and chart: higher for AMM pools.
`is_blacklisted`(vaults_df)	Find blacklisted vaults.
`is_identified_protocol`(protocol, protocol_slug)	Check whether a vault's protocol has been identified.
`rank_vaults`(df[, column])	Sort vaults by a metric, best first.
`render_section_table`(section)	Render a report section as a HTML table for the blog.
`select_average_yield_vaults`(eligible_df, ...)	Select the vaults counted in the average yield charts.
`select_chain_chart_vaults`(eligible_df, criteria)	Best vaults on each chain for the per-chain chart.
`select_comparable_vaults`(eligible_df)	Select the vaults that may appear in performance comparisons.
`select_group`(eligible_df, criteria, group, *)	Select the best vaults of a vault group.
`select_new_vaults`(eligible_df, criteria)	Best stablecoin yield vaults launched recently.
`select_risk_return_vaults`(yield_universe, ...)	Vaults of the risk and return chart: the yield vaults and the perp DEX vaults.
`select_tvl_history_vaults`(vaults_df)	Select vaults whose TVL history is counted in the market TVL chart.
`select_vaults_by_chain`(eligible_df, criteria)	Best vaults on each chain, including perpetual DEX chains.
`select_yield_vaults`(eligible_df, criteria)	Stablecoin yield vaults: every group except perpetual futures DEX vaults.
`web_link`(text, url)	Escaped HTML link, or the escaped text alone when the URL is not a web link.

Classes

`ReportCriteria`	Selection thresholds for the report sections.
`ReportSection`	One ranked vault table in the report.

UNKNOWN_PROTOCOL_SLUG = 'protocol-not-yet-identified': Protocol slug for vaults whose protocol we could not identify

BLACKLISTED_RISK = 'Blacklisted': Technical risk label for vaults excluded from all listings

MAX_DISPLAYED_SHARPE = 100

Sharpe ratios above this are displayed as >100.

Lending vaults with near-zero volatility get Sharpe ratios in the millions, which carry no information beyond “very smooth”.

CAPPED_ANNUALISED_RETURN = 100.0

The top vaults export caps annualised returns at 10,000%, as the fraction 100.0 (max_cagr in eth_defi.research.vault_metrics period metrics).

Annualising a large one-month gain, common for perp DEX vaults and broken share tokens, overflows to absurd numbers, so the exporter clamps it. Values at the cap are displayed as CAPPED_RETURN_LABEL, and rank_vaults() breaks the resulting ties.

CAPPED_RETURN_LABEL = '>9,999%': Label of a capped annualised return, like on the website

SPARKLINE_URL = 'https://vault-sparklines.tradingstrategy.ai/sparkline-table-90d-{vault_id}.png': Public vault sparkline images, rendered by eth_defi.research.sparkline_export PNG rather than SVG, because email clients such as Gmail strip SVG images from newsletters

LENDING_STRATEGY_TAGS = frozenset({'lending', 'lending_looping', 'lending_optimisation'}): Strategy tags that make a vault a lending vault

RWA_STRATEGY_TAGS = frozenset({'rwa', 'rwa_credit', 'rwa_lending', 'rwa_royalties'})

Strategy tags that make a vault a real-world asset (RWA) vault, see eth_defi.vault.strategy_tag.StrategyTag.

RWA lending vaults are RWA vaults, not lending vaults: their risk is the real-world borrowers and collateral. Tokenised funds and perp DEX vaults financing real-world credit keep their own groups.

LENDING_PROTOCOL_SLUGS = frozenset({'3jane', '40acres', 'aave', 'arcadia-finance', 'curvance', 'dolomite', 'euler', 'fluid', 'frax', 'gearbox', 'llama-lend', 'morpho', 'sentiment', 'silo-finance', 'spark', 'term-finance'})

Protocols whose vaults are lending vaults even without a strategy tag.

Not every protocol adapter sets strategy tags, so the report also recognises the lending markets it knows, matched against the export’s protocol_slug. Tagging these adapters would make this list unnecessary. Untagged RWA vaults of these protocols land in lending until tagged with the categorise-vault-strategy skill.

AMM_POOL_FEATURE = 'amm_pool_like': Vault feature of AMM liquidity-provider shares, set by the scanner for GMX GM and GLV pools and Curve-based YieldBasis LTs, see eth_defi.erc_4626.core.ERC4626Feature.amm_pool_like

TOKENISED_FUND_FLAG = 'tokenised_fund': Vault flag for tokenised funds, such as money market and treasury funds

UNIDENTIFIED_PROTOCOL_SLUGS = frozenset({'erc-4626', 'protocol-not-yet-identified', 'unknown', 'unknown-erc-7450'}): Protocol slugs that mean the vault’s protocol has not been identified yet: generic ERC-4626 and ERC-7540 vaults and placeholders. The same set as the website’s isUnknownVaultProtocol() in src/lib/top-vaults/helpers.ts.

UNIDENTIFIED_PROTOCOL_NAMES = frozenset({'', 'unknown', 'unknown vault protocol'}): Protocol names, lower case, that mean the same. Names starting with <, such as <unknown ERC-4626> placeholders, are also unidentified, see is_identified_protocol().

OTHER_PROTOCOL = 'Other': Label of the single pile of vaults whose protocol is not identified. Charts also sum their small protocols into it, so unidentified vaults never show as a protocol of their own.

LENDING = 'lending': Vault group labels, stored in the group column by eth_defi.vault_report.data.prepare_vault_metrics(), see classify_vault(). Each group except OTHER has its own best-performing section in eth_defi.vault_report.post.BEST_SECTIONS.

class ReportCriteria

Bases: object

Selection thresholds for the report sections.

One place for every editorial threshold, so a month’s post can be tuned with dataclasses.replace() without touching the selectors. The investability check reuses the same selectors with deeper top_n and chain_top_n values to collect replacement candidates, see eth_defi.vault_report.report.collect_top_lists().

The defaults reproduce the rules in README-blog-post-outline.md; the section notes in eth_defi.vault_report.report.make_criteria_notes() and the chart subtitles quote these values, so changing one changes the post text too.

Returns, volatilities and drawdowns are fractions (0.25 = 25%), TVL is in USD.

min_tvl: float

Minimum current TVL for the best-performing vault tables, the yield universe of the hero image and the risk and return chart.

Large vaults have no table of their own: this threshold and the TVL column cover them, see the outline’s change log.

min_events: int

Minimum lifetime deposit and redemption events (export event_count) for lending, RWA, other and new vaults.

Filters out inactive vaults, whose returns no depositors stand behind. Perp DEX vaults and tokenised funds have no comparable onchain ERC-4626 events and are exempt, see select_group().

top_n: int: Number of vaults in each best-performing table

max_data_age: datetime.timedelta

Exclude vaults whose latest metrics (export end_date) are older than this, relative to the report data date.

A vault the scanner stopped reading keeps its last, possibly flattering, returns in the export, which would otherwise keep ranking.

chain_min_tvl: float: Minimum TVL for the per-chain table and chart

chain_top_n: int: Vaults listed per chain

new_vault_min_tvl: float: Minimum TVL for the new vaults table, lower than min_tvl because a vault launched weeks ago has not had time to grow

include_amm_pools: bool: Include AMM pools in the rankings and charts outside their own section. AMM pools, such as GMX GM pools and YieldBasis, carry the market risk of the traded assets, so by default they are ranked only in the AMM pools section and counted only in the TVL summaries.

amm_min_tvl: float: Minimum TVL for the AMM pools table

new_vault_max_age: datetime.timedelta: Maximum age of a vault in the new vaults table

performance_chart_vaults: int: Number of vaults in each performance chart; more equity curves in one shared-axis chart become unreadable

crypto_benchmark_min_volatility: float

Vaults at or above this annualised three-month volatility are compared with BTC and ETH instead of the Treasury bill.

The report’s own extension of the website’s benchmark rules: a trading-like stablecoin vault is better judged against the crypto market it trades, see eth_defi.vault_report.benchmarks.select_benchmarks().

crypto_benchmark_max_drawdown: float: Vaults with a three-month drawdown, a negative fraction, at or below this are compared with BTC and ETH instead of the Treasury bill

chart_max_return: float: Leave vaults above this annualised three-month return, 400%, out of the hero image, where one outlier number would dwarf the others

chart_min_excluded_risk: int: Lowest technical risk level left out of the charts: the hero image, the performance charts and risk and return. Dangerous and above, see eth_defi.vault.risk.VaultTechnicalRisk. Charts get shared without the tables, so tables keep these vaults. Unrated vaults are shown.

hero_max_volatility: float: Leave vaults above this annualised three-month volatility out of the hero image

scatter_max_return: float: Clip the risk and return scatter’s y axis at most at this annualised return, 100%; vaults above are left out

yield_top_chains: int: Number of blockchains in the average yield chart, the largest by TVL

yield_top_protocols: int: Number of protocols in the average yield chart, the largest by TVL

yield_min_protocol_tvl: float: Minimum TVL of a protocol in the high TVL average yield chart

yield_high_yield_min_protocol_tvl: float

Minimum TVL of a protocol in the high yield average yield chart, which ranks protocols by yield.

Lower than yield_min_protocol_tvl so smaller, high-yield protocols can appear; the chart’s TVL column shows how much money earns the yield.

yield_min_vault_tvl: float

Minimum TVL per vault to be counted in the average yield charts.

Lower than the table minimum because the averages are TVL-weighted: small vaults barely move them but still show as dots.

yield_max_return: float: Exclude outlier vaults above this annualised three-month return, 400%, from the average yields

yield_max_volatility: float

Exclude vaults above this annualised three-month volatility from the average yields.

Keeps volatile crypto index funds and AMM liquidity positions out of the stablecoin yield figures.

yield_chart_max_return: float: Cap of the average yield charts’ x axis for the largest chains and protocols, 40%. The axis otherwise fits the data, see eth_defi.vault_report.charts.create_average_yield_figure(); vault dots beyond it are not drawn but still count in the averages. The high yield chart is capped at yield_max_return instead.

tvl_change_top_n: int: Number of largest inflows and of largest outflows in the TVL change chart

check_buffer_ratio: float: Investability check: extra candidates collected for each top list, as a share of the vaults it shows, see eth_defi.vault_report.vault_checks. Checking 50% deeper than shown lets excluded vaults be replaced without another agent round.

check_max_rounds: int: Investability check: rounds of refilling the top lists after exclusions. Each round runs the agent, minutes of LLM time, so the number is capped; unchecked in-scope vaults after the last round stop the report.

check_prescreen_min_tvl: float: Investability check: minimum TVL of an aggregate chart vault to prescreen

check_max_escalations: int: Investability check: maximum number of prescreened vaults sent to the agent

__init__(min_tvl=100000, min_events=10, top_n=20, max_data_age=datetime.timedelta(days=7), chain_min_tvl=100000, chain_top_n=3, new_vault_min_tvl=15000, include_amm_pools=False, amm_min_tvl=1000000, new_vault_max_age=datetime.timedelta(days=60), performance_chart_vaults=8, crypto_benchmark_min_volatility=0.25, crypto_benchmark_max_drawdown=- 0.1, chart_max_return=4.0, chart_min_excluded_risk=50, hero_max_volatility=0.5, scatter_max_return=1.0, yield_top_chains=10, yield_top_protocols=10, yield_min_protocol_tvl=1000000, yield_high_yield_min_protocol_tvl=150000, yield_min_vault_tvl=10000, yield_max_return=4.0, yield_max_volatility=0.5, yield_chart_max_return=0.4, tvl_change_top_n=10, check_buffer_ratio=0.5, check_max_rounds=3, check_prescreen_min_tvl=1000000, check_max_escalations=20)

Parameters

min_tvl (float) –
min_events (int) –
top_n (int) –
max_data_age (datetime.timedelta) –
chain_min_tvl (float) –
chain_top_n (int) –
new_vault_min_tvl (float) –
include_amm_pools (bool) –
amm_min_tvl (float) –
new_vault_max_age (datetime.timedelta) –
performance_chart_vaults (int) –
crypto_benchmark_min_volatility (float) –
crypto_benchmark_max_drawdown (float) –
chart_max_return (float) –
chart_min_excluded_risk (int) –
hero_max_volatility (float) –
scatter_max_return (float) –
yield_top_chains (int) –
yield_top_protocols (int) –
yield_min_protocol_tvl (float) –
yield_high_yield_min_protocol_tvl (float) –
yield_min_vault_tvl (float) –
yield_max_return (float) –
yield_max_volatility (float) –
yield_chart_max_return (float) –
tvl_change_top_n (int) –
check_buffer_ratio (float) –
check_max_rounds (int) –
check_prescreen_min_tvl (float) –
check_max_escalations (int) –

Return type

None

VAULT_TABLE_COLUMNS = ['Vault', '3M history', '1M ann.', '3M ann.', 'Lifetime ann.', '3M Sharpe', 'TVL', 'Age (y)', 'Token', 'Chain', 'Protocol']: Default columns for vault tables, same as in the previous blog posts. Cell values come from format_vault_cells(); there is deliberately no risk rating column, the rating only filters the charts.

CHAIN_TABLE_COLUMNS = ['Chain', 'Protocol', 'Vault', '1M ann.', '3M ann.', 'Lifetime ann.', 'TVL', 'Age (y)', 'Token']: Columns for the per-chain table, chain first

NUMERIC_COLUMNS = {'3M Sharpe', 'Age (y)'}: Right-aligned numeric columns

NOWRAP_COLUMNS = {'1M ann.', '3M ann.', 'Lifetime ann.', 'TVL'}: Columns whose values must not wrap onto two lines, e.g. >9,999% or $1.2M split at the comma or point

class ReportSection

Bases: object

One ranked vault table in the report.

Built by eth_defi.vault_report.report.build_report_sections(), rendered to HTML by render_section_table() and written to the bundle’s tables/*.csv.

vaults_df: pandas.DataFrame: Vaults in display order, rows from eth_defi.vault_report.data.VaultReportData.vaults_df, already truncated to the table length

columns: list[str]: Table columns, see VAULT_TABLE_COLUMNS

numbered: bool: Show a 1, 2, 3… rank column

sparkline_ids: frozenset[str]: Vault ids with a published sparkline image, see eth_defi.vault_report.data.fetch_available_sparklines(). Filled in after the tables are selected, so only their vaults are probed; other vaults get an empty “3M history” cell instead of a broken image.

__init__(vaults_df, columns=<factory>, numbered=True, sparkline_ids=frozenset({}))

Parameters

vaults_df (pandas.DataFrame) –
columns (list[str]) –
numbered (bool) –
sparkline_ids (frozenset[str]) –

Return type

None

filter_eligible_vaults(vaults_df, data_end_at, criteria)

Remove vaults that must not appear in any listing.

The first filter of every ranked section and of the inflows and outflows; the report statistics count its result as the vaults with up-to-date data. Drops:

blacklisted vaults, see is_blacklisted(): rated Blacklisted in the export, or given a bad flag in eth_defi.vault.flag since the export was made
vaults without a known TVL (current_nav, also NaN for broken share tokens above MAX_VALID_NAV) or one-month return, which cannot be ranked
stale vaults whose end_date is more than ReportCriteria.max_data_age before data_end_at

Staleness is measured against the report data date, the newest end_date in the export, not the wall clock, so regenerating an old report from a cached export gives the same result.

Parameters

vaults_df (pandas.DataFrame) – Vault metrics from eth_defi.vault_report.data.prepare_vault_metrics(), with risk, address, protocol, current_nav, one_month_cagr_best and end_date (naive UTC) columns.
data_end_at (datetime.datetime) – The report data date, eth_defi.vault_report.data.VaultReportData.data_end_at, naive UTC.
criteria (eth_defi.vault_report.sections.ReportCriteria) – Report thresholds.

Returns

Filtered vault metrics, the same columns.

Return type