erc_4626.vault_protocol.yearn.offchain_metadata

Documentation for eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata Python module.

Yearn-maintained offchain vault metadata.

Yearn stores frontend endorsement and inclusion decisions in versioned data/meta/vaults/{chain_id}.json files in its yDaemon repository. A contract can implement the Yearn V3 interface without being a Yearn product, so this metadata supplements ABI-based protocol detection.

The complete file is fetched once per chain and cached locally. It is neither onchain contract data nor an offline bundled data set: callers treat a failed fetch as unknown and do not exclude any vault on that basis.

Module Attributes

`YEARN_YDAEMON_METADATA_BASE_URL`	Raw GitHub directory containing Yearn's versioned yDaemon chain documents.
`YEARN_DETECTED_VAULTS_LIMIT`	Maximum record count requested from the public detected-vault endpoint.
`YEARN_DETECTED_VAULTS_URL`	Live catalogue that powers Yearn's public vault pages.
`DEFAULT_CACHE_DURATION`	Static catalogue metadata changes much less frequently than scanner cycles.
`UNAVAILABLE_RETRY_DELAY`	Retry unavailable source metadata without making every vault trigger an HTTP request.
`MAX_SHORT_DESCRIPTION_LENGTH`	A listing summary must remain suitable for a compact vault-table cell.

Functions

`extract_yearn_short_description`(description)	Extract a bounded first sentence from a Yearn description.
`fetch_yearn_detected_vaults`()	Fetch Yearn's public vault-page catalogue once per scanner worker.
`fetch_yearn_vault_endorsement`(chain_id, ...)	Fetch whether Yearn explicitly endorses a vault.
`fetch_yearn_vaults_file_for_chain`(chain_id)	Fetch and cache Yearn's complete metadata file for one chain.
`resolve_yearn_vault_endorsement`(chain_id, ...)	Combine the public website and static yDaemon endorsement evidence.

Classes

`CachedYearnDetectedVaultIndex`	One worker's cached public Yearn vault-page index.
`CachedYearnVaultIndex`	One worker's refreshable yDaemon metadata index.
`YearnDetectedVaultCache`	Hold the mutable per-process state for the public vault catalogue.
`YearnDetectedVaultCatalogue`	One public Yearn vault-page catalogue response.
`YearnDetectedVaultMetadata`	Public Yearn catalogue metadata for one vault.
`YearnVaultMetadata`	The normalised yDaemon fields used to decide Yearn frontend membership.

DEFAULT_CACHE_PATH = PosixPath('/home/runner/.tradingstrategy/cache/yearn'): Persistent per-chain cache for the complete Yearn yDaemon metadata files.

YEARN_YDAEMON_METADATA_BASE_URL = 'https://raw.githubusercontent.com/yearn/ydaemon/main/data/meta/vaults': Raw GitHub directory containing Yearn’s versioned yDaemon chain documents.

YEARN_DETECTED_VAULTS_LIMIT = 2000: Maximum record count requested from the public detected-vault endpoint.

YEARN_DETECTED_VAULTS_URL = 'https://ydaemon.yearn.fi/vaults/detected?limit=2000': Live catalogue that powers Yearn’s public vault pages. Unlike the static source repository, it contains recently launched vaults such as Flex USDC.

DEFAULT_CACHE_DURATION = datetime.timedelta(days=1): Static catalogue metadata changes much less frequently than scanner cycles.

UNAVAILABLE_RETRY_DELAY = datetime.timedelta(seconds=300): Retry unavailable source metadata without making every vault trigger an HTTP request.

MAX_SHORT_DESCRIPTION_LENGTH = 200: A listing summary must remain suitable for a compact vault-table cell.

class YearnVaultMetadata

Bases: object

The normalised yDaemon fields used to decide Yearn frontend membership.

yDaemon’s source document contains many free-form metadata fields. The scanner keeps only the two explicit boolean decisions required to distinguish official Yearn frontend vaults from third-party V3-compatible contracts.

Parameters

endorsed – Whether Yearn explicitly endorses the vault.
is_yearn – Whether Yearn explicitly includes the vault in its frontend.

endorsed: bool: True only when Yearn explicitly endorses the vault.

is_yearn: bool: True only when Yearn explicitly includes the vault in its frontend.

__init__(endorsed, is_yearn)

Parameters

endorsed (bool) –
is_yearn (bool) –

Return type

None

class CachedYearnVaultIndex

Bases: object

One worker’s refreshable yDaemon metadata index.

The scanner is a persistent process. Keep the time of the last attempted refresh beside the normalised index so the process cache preserves per-vault efficiency without making Yearn’s endorsement decisions stale until the scanner container restarts.

Parameters

vaults – Lowercase address-keyed normalised yDaemon metadata.
fetched_at – Naive UTC time when this worker last refreshed the index.

vaults: dict[str, eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnVaultMetadata]: Lowercase address-keyed normalised yDaemon metadata.

fetched_at: datetime.datetime: Naive UTC time when this worker last refreshed the index.

__init__(vaults, fetched_at)

Parameters

vaults (dict[str, eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnVaultMetadata]) –
fetched_at (datetime.datetime) –

Return type

None

class YearnDetectedVaultMetadata

Bases: object

Public Yearn catalogue metadata for one vault.

The detected-vault endpoint is used only as positive evidence that Yearn publishes a vault page. Its omission of a contract is deliberately not a classification decision: TokenizedStrategy and compounder adapters are not exhaustively represented by that endpoint.

Parameters: description – Optional Yearn-authored strategy description suitable for export.

description: Optional[str]: Optional Yearn-authored strategy description.

__init__(description)

Parameters: description (Optional[str]) –
Return type: None

YearnDetectedVaultRecords

Public catalogue records keyed by EVM chain ID and lowercase vault address.

alias of dict[tuple[int, str], eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultMetadata]

class YearnDetectedVaultCatalogue

Bases: object

One public Yearn vault-page catalogue response.

A page hit is always positive evidence. A miss can support a negative direct-V3 decision only when the response did not reach the requested endpoint limit.

Parameters

vaults – Chain ID and lowercase address keyed public vault metadata.
is_complete – Whether a catalogue miss is safe to use as negative evidence.

vaults: dict[tuple[int, str], eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultMetadata]: Chain ID and lowercase address keyed public vault metadata.

is_complete: bool: Whether a catalogue miss is safe to use as negative evidence.

get(chain_id, vault_address)

Look up one vault’s public-page metadata.

Parameters

chain_id (int) – EVM chain ID of the vault.
vault_address (eth_typing.evm.HexAddress) – Vault contract address.

Returns

Public metadata when Yearn lists a vault page, otherwise None.

Return type

Optional[eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultMetadata]

__init__(vaults, is_complete)

Parameters

vaults (dict[tuple[int, str], eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultMetadata]) –
is_complete (bool) –

Return type

None

class CachedYearnDetectedVaultIndex

Bases: object

One worker’s cached public Yearn vault-page index.

Parameters

catalogue – Public vault-page records and their completeness state.
fetched_at – Naive UTC time when this worker last fetched the endpoint.

catalogue: eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultCatalogue: Public vault-page records and their completeness state.

fetched_at: datetime.datetime: Naive UTC time when this worker last fetched the endpoint.

__init__(catalogue, fetched_at)

Parameters

catalogue (eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultCatalogue) –
fetched_at (datetime.datetime) –

Return type

None

class YearnDetectedVaultCache

Bases: object

Hold the mutable per-process state for the public vault catalogue.

Parameters

index – Most recently successful catalogue index.
retry_after – Naive UTC time before a failed request may be retried.

index: Optional[eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.CachedYearnDetectedVaultIndex]: Most recently successful catalogue index.

retry_after: Optional[datetime.datetime]: Naive UTC time before a failed request may be retried.

__init__(index=None, retry_after=None)

Parameters

index (Optional[eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.CachedYearnDetectedVaultIndex]) –
retry_after (Optional[datetime.datetime]) –

Return type

None

extract_yearn_short_description(description)

Extract a bounded first sentence from a Yearn description.

Yearn descriptions are free-form Markdown and do not consistently use a full stop followed by a space. A punctuation-aware split handles links and newline-separated sentences, while a length limit prevents a malformed or sentence-less source value from filling the website listing.

Parameters: description (Optional[str]) – Full description from Yearn’s detected-vault endpoint.
Returns: First sentence when it fits the compact listing field, otherwise None.
Return type: Optional[str]

fetch_yearn_vaults_file_for_chain(chain_id, cache_path=PosixPath('/home/runner/.tradingstrategy/cache/yearn'), github_base_url='https://raw.githubusercontent.com/yearn/ydaemon/main/data/meta/vaults', now_=None, max_cache_duration=datetime.timedelta(days=1))

Fetch and cache Yearn’s complete metadata file for one chain.

A temporary source failure preserves an older valid cache. When no valid document is available, return None so callers keep the vault’s existing classification rather than treating an operational failure as an exclusion.

Parameters

chain_id (int) – EVM chain ID represented by the yDaemon document.
cache_path (pathlib.Path) – Directory for persistent chain metadata caches.
github_base_url (str) – Raw GitHub directory containing the yDaemon chain JSON files.
now – Optional current UTC timestamp for deterministic cache-expiry tests.
max_cache_duration (datetime.timedelta) – Maximum cache age before a refresh is attempted.
now_ (Optional[datetime.datetime]) –

Returns

Lowercase address-keyed metadata, or None when no source is available.

Return type

Optional[dict[str, eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnVaultMetadata]]

fetch_yearn_detected_vaults()

Fetch Yearn’s public vault-page catalogue once per scanner worker.

This endpoint is intentionally a positive-only source. A matching entry confirms that the vault appears on Yearn’s website and can provide a description. A missing entry remains unknown, including when the response is capped at its server-side limit.

Returns: Public-page metadata keyed by chain ID and lowercase address, or None when the endpoint is temporarily unavailable.
Return type: Optional[eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultCatalogue]

resolve_yearn_vault_endorsement(chain_id, vault_address, *, static_endorsement, detected_vaults)

Combine the public website and static yDaemon endorsement evidence.

A live public-page entry always establishes that a vault is official, even if Yearn’s static repository has not caught up. Otherwise both sources must be available before a static non-endorsement can classify a direct V3 vault as unofficial. This helper intentionally does not decide whether an adapter family is eligible for negative classification.

Parameters

chain_id (int) – EVM chain ID of the vault.
vault_address (eth_typing.evm.HexAddress) – Vault contract address.
static_endorsement (Optional[bool]) – Static yDaemon endorsement result, or None when unavailable.
detected_vaults (Optional[eth_defi.erc_4626.vault_protocol.yearn.offchain_metadata.YearnDetectedVaultCatalogue]) – Public-page catalogue, or None when unavailable.

Returns

True for a website-listed or statically endorsed vault, False for a confirmed static non-endorsement, and None when either source is unavailable.

Return type

Optional[bool]

fetch_yearn_vault_endorsement(chain_id, vault_address)

Fetch whether Yearn explicitly endorses a vault.

False is returned only after successfully loading Yearn metadata and finding either no address entry or an entry without an explicit endorsement. An endorsed partner vault may be excluded from Yearn’s primary frontend (for example, a Yearn Juiced vault), but it remains an official Yearn product and must not be classified as unofficial.

None deliberately represents unavailable metadata, preventing a transient GitHub or cache problem from blacklisting a vault.

Parameters

chain_id (int) – EVM chain ID of the vault.
vault_address (eth_typing.evm.HexAddress) – Vault contract address.

Returns

True for a Yearn-endorsed vault, False for a known unendorsed contract, and None when metadata is unavailable.

Return type

Optional[bool]