erc_4626.vault_protocol.euler.offchain_metadata

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

Euler vault labelling.

  • Euler has put vault names offchain in Github, because of course Solidity programmers would do something like this

  • name() accessor in Euler vault returns just a running counter

  • Vault metadata is sourced from {chainId}/products.json in the euler-xyz/euler-labels repository

Metadata structure (as of 2026-04)

The old per-vault vaults.json was removed on 2026-04-14. Vault metadata is now organised at the product level in products.json. A product is a branded market grouping (e.g. Euler Prime, InfiniFi) that owns one or more vault addresses.

Each product entry contains:

  • name — product brand name (e.g. "Euler Prime")

  • description — long-form description of the product

  • entity — list of entity slugs (resolves against entities.json)

  • vaults — list of active vault addresses in this product

  • deprecatedVaults — formerly active vault addresses

  • vaultOverrides — sparse per-vault overrides; only set where a vault needs a different name or description from its parent product

When building the per-vault reverse index we:

  1. Use vaultOverrides[addr].name / .description when present.

  2. Fall back to the parent product’s name / description.

  3. Expose the first entity slug as entity for backward compatibility with the old vaults.json API; the full list is available as entities.

Reference:

Functions

fetch_euler_vault_metadata(web3, vault_address)

Fetch vault metadata from the offchain products.json source.

fetch_euler_vaults_file_for_chain(chain_id)

Fetch and cache Euler offchain vault metadata for a given chain.

Classes

EulerVaultMetadata

Metadata about an Euler vault derived from the offchain products.json source.
class EulerVaultMetadata

Bases: TypedDict

Metadata about an Euler vault derived from the offchain products.json source.

This TypedDict is the per-vault view built by fetch_euler_vaults_file_for_chain() from the product-level products.json file.

Backward-compatible fields (present in the old vaults.json too):

  • name — vault display name; falls back to the parent product name when no per-vault override exists.

  • description — vault description; falls back to the product description.

  • entity — first entity slug (e.g. "euler-dao"); kept as a plain string for backward compatibility with code that used the old vaults.json format.

New fields (not present in the old format):

  • entities — full list of entity slugs for the product (e.g. ["euler-dao", "gauntlet"]).

  • product — product slug key (e.g. "euler-prime").

  • product_name — product display name (e.g. "Euler Prime").

  • deprecated — True if this vault address appears in deprecatedVaults.

  • deprecation_reason — human-readable reason from vaultOverrides, or None.

Reference:

__init__(*args, **kwargs)
__new__(**kwargs)
clear()

Remove all items from the dict.

copy()

Return a shallow copy of the dict.

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items()

Return a set-like object providing a view on the dict’s items.

keys()

Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

Return an object providing a view on the dict’s values.

fetch_euler_vault_metadata(web3, vault_address)

Fetch vault metadata from the offchain products.json source.

Uses a two-level cache: an in-process dict and a disk cache populated by fetch_euler_vaults_file_for_chain().

Parameters

  • web3 (web3.main.Web3) – Connected Web3 instance (used to determine chain ID and checksum the address).

  • vault_address (eth_typing.evm.HexAddress) – Vault contract address.

Returns

EulerVaultMetadata for the vault, or None if no metadata is available (unrecognised vault or chain has no products.json).

Return type

Optional[eth_defi.erc_4626.vault_protocol.euler.offchain_metadata.EulerVaultMetadata]

fetch_euler_vaults_file_for_chain(chain_id, cache_path=PosixPath('/home/runner/.tradingstrategy/cache/euler'), github_base_url='https://raw.githubusercontent.com/euler-xyz/euler-labels/refs/heads/master', now_=None, max_cache_duration=datetime.timedelta(days=2))

Fetch and cache Euler offchain vault metadata for a given chain.

Fetches {chainId}/products.json from the euler-xyz/euler-labels GitHub repository, builds a flat per-vault reverse index via _build_vault_index(), and writes the result to a local JSON cache file.

The cache is per-chain and expires after max_cache_duration (default 2 days). The function is multiprocess-safe via wait_other_writers().

Parameters

  • chain_id (int) – EVM chain ID (e.g. 1 for Ethereum mainnet).

  • cache_path – Directory for the local JSON cache files.

  • github_base_url – Base URL for the euler-xyz/euler-labels raw GitHub files.

  • now – Override for “current time” used in cache-expiry checks (useful in tests).

  • max_cache_duration – How long to keep a cached file before re-fetching from GitHub.

Returns

Dict mapping checksummed vault address → EulerVaultMetadata. Returns an empty dict when the chain has no products file.

Return type

dict[str, eth_defi.erc_4626.vault_protocol.euler.offchain_metadata.EulerVaultMetadata]