erc_4626.vault_protocol.yearn.endorsement

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

Explicit Yearn primary-list exclusions used during vault scanning.

Yearn’s public vault registry is broader than Trading Strategy’s Yearn-operated vault catalogue. We classify a vault as not Yearn-operated when the registry explicitly sets inclusion.isSet without inclusion.isYearn, or when it supplies an empty inclusion object. Empty inclusion objects include the Katana Stablecoin Transformer depositors 0x63a028963907f5a0c1ceb7e47100f52dfc611117 and 0xbc64210d565aabca8eb6eb795833cc505ac3647f.

This scan-time check deliberately removes known uncurated strategy targets and wrappers from Yearn protocol and curated-vault lists. It does not treat an address missing from the registry as negative. Public export applies a separate positive-match rule in eth_defi.erc_4626.vault_protocol.yearn.export_cleanup to close that gap. A generic Yearn route may render for an arbitrary address; that is not catalogue evidence. Neither rule asserts contract ownership, safety, or code provenance.

The scanner preserves technical Yearn interface features for the appropriate vault adapter, but records a provenance marker so protocol and curator views do not attribute excluded contracts to Yearn. The live registry is cached per scanner worker for one day. A source outage is unknown, not exclusion evidence.

Module Attributes

`YEARN_VAULT_REGISTRY_URL`	Live Yearn frontend registry that provides vault-list membership decisions.
`YEARN_REGISTRY_CACHE_DURATION`	Refresh primary-list decisions daily in persistent scanner workers.
`YEARN_REGISTRY_UNAVAILABLE_RETRY_DELAY`	Avoid retrying a temporarily unavailable registry for every scanned vault.
`YEARN_REGISTRY_REQUEST_TIMEOUT`	Bound one registry request so an unavailable remote source cannot stall a scan.
`MINIMUM_YEARN_REGISTRY_EXCLUSION_COUNT`	Reject a valid-looking but truncated registry response.

Functions

`add_yearn_registry_exclusion`(chain_id, ...)	Add a Yearn primary-list exclusion marker to matching vault features.
`fetch_yearn_registry_exclusions`()	Fetch Yearn's primary-list exclusions once per scanner worker.
`is_yearn_registry_excluded_vault`(chain_id, ...)	Check whether Yearn excludes a vault from its primary product list.
`parse_yearn_registry_exclusions`(payload)	Parse primary-list exclusions from Yearn's public registry response.

Classes

`CachedYearnRegistryExclusions`	One worker's cached Yearn registry-exclusion index.
`YearnRegistryExclusionCache`	Hold mutable per-process state for primary-list exclusions.

YEARN_VAULT_REGISTRY_URL = 'https://kong.yearn.fi/api/rest/list/vaults': Live Yearn frontend registry that provides vault-list membership decisions.

YEARN_REGISTRY_CACHE_DURATION = datetime.timedelta(days=1): Refresh primary-list decisions daily in persistent scanner workers.

YEARN_REGISTRY_UNAVAILABLE_RETRY_DELAY = datetime.timedelta(seconds=300): Avoid retrying a temporarily unavailable registry for every scanned vault.

YEARN_REGISTRY_REQUEST_TIMEOUT = 30: Bound one registry request so an unavailable remote source cannot stall a scan.

MINIMUM_YEARN_REGISTRY_EXCLUSION_COUNT = 100: Reject a valid-looking but truncated registry response. The reviewed exclusion population is substantially larger; accepting a tiny index would reattribute migrated vaults to Yearn until the next refresh.

YearnRegistryExclusions

Chain/address keys for vaults excluded from Yearn’s primary product list.

alias of frozenset[tuple[int, eth_typing.evm.HexAddress]]

class CachedYearnRegistryExclusions

Bases: object

One worker’s cached Yearn registry-exclusion index.

exclusions: frozenset[tuple[int, eth_typing.evm.HexAddress]]: Registry entries excluded from Yearn’s primary product list.

fetched_at: datetime.datetime: Naive UTC time when the registry was successfully fetched.

__init__(exclusions, fetched_at)

Parameters

exclusions (frozenset[tuple[int, eth_typing.evm.HexAddress]]) –
fetched_at (datetime.datetime) –

Return type

None

class YearnRegistryExclusionCache

Bases: object

Hold mutable per-process state for primary-list exclusions.

index: Optional[eth_defi.erc_4626.vault_protocol.yearn.endorsement.CachedYearnRegistryExclusions]: Most recently successful registry 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.endorsement.CachedYearnRegistryExclusions]) –
retry_after (Optional[datetime.datetime]) –

Return type

None

parse_yearn_registry_exclusions(payload)

Parse primary-list exclusions from Yearn’s public registry response.

The API is an array of heterogeneous records. Invalid records are omitted, because a malformed source entry cannot safely determine product attribution. Valid entries use chainId and EIP-55 or lowercase addresses, which are normalised into compact lookup keys.

Parameters: payload (object) – Decoded JSON body returned by Yearn’s registry API.
Returns: Immutable chain/address keys for excluded vaults.
Return type: frozenset[tuple[int, eth_typing.evm.HexAddress]]

fetch_yearn_registry_exclusions()

Fetch Yearn’s primary-list exclusions once per scanner worker.

A successful index remains usable during a temporary source failure. When no successful index exists, the caller receives None and keeps the normal technical protocol classification rather than making a negative attribution decision from unavailable offchain data. A response below MINIMUM_YEARN_REGISTRY_EXCLUSION_COUNT is treated as unavailable so a truncated source cannot reverse existing attribution for one day.

Returns: Excluded chain/address keys, or None when Yearn’s registry is unavailable.
Return type: Optional[frozenset[tuple[int, eth_typing.evm.HexAddress]]]

is_yearn_registry_excluded_vault(chain_id, vault_address, *, exclusions=None)

Check whether Yearn excludes a vault from its primary product list.

The check normalises EIP-55 casing. Supplying an index lets migrations use one reviewed registry snapshot for their complete run. Omitting it may trigger a cached HTTP lookup in scanner callers.

Parameters

chain_id (Optional[int]) – EVM chain identifier for the vault deployment, if known.
vault_address (eth_typing.evm.HexAddress) – ERC-4626 vault contract address.
exclusions (Optional[frozenset[tuple[int, eth_typing.evm.HexAddress]]]) – Optional pre-fetched Yearn primary-list exclusion index. Omitting it may trigger a cached HTTP lookup.

Returns

True when the registry records a primary-list exclusion.

Return type

bool

add_yearn_registry_exclusion(chain_id, vault_address, features, *, exclusions=None)

Add a Yearn primary-list exclusion marker to matching vault features.

The marker changes protocol and curator attribution only. Technical Yearn interface features stay intact, allowing the scanner to select the correct Yearn adapter for deposit, fee, and permission handling.

Parameters

chain_id (Optional[int]) – EVM chain identifier for the vault deployment, if known.
vault_address (eth_typing.evm.HexAddress) – ERC-4626 vault contract address.
features (set[eth_defi.erc_4626.core.ERC4626Feature]) – Features returned by the generic ABI probe.
exclusions (Optional[frozenset[tuple[int, eth_typing.evm.HexAddress]]]) – Optional pre-fetched Yearn primary-list exclusion index.

Returns

Original features, with the exclusion marker added when applicable.

Return type

set[eth_defi.erc_4626.core.ERC4626Feature]