vault.protocol_metadata

Documentation for eth_defi.vault.protocol_metadata Python module.

Vault protocol metadata handling.

Read and export vault protocol metadata from YAML files to JSON format for upload to R2 storage.

Module Attributes

LINK_FIELDS

All link fields that should be present in the output

Functions

build_metadata_json(yaml_path, public_url)

Build a VaultProtocolMetadata dict from a YAML file.

get_available_logos(slug)

Check which logo variants are available for a protocol.

process_and_upload_protocol_metadata(slug, ...)

Process and upload a single protocol's metadata and logos to R2.

read_protocol_metadata(yaml_path)

Read and parse a protocol metadata YAML file.

Classes

VaultProtocolLinks

Links associated with a vault protocol.

VaultProtocolLogos

Logo URLs for a vault protocol.

VaultProtocolMetadata

Complete vault protocol metadata as exported to JSON.
VAULTS_DATA_DIR = PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi/eth_defi/data/vaults')

Base directory for vault data

METADATA_DIR = PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi/eth_defi/data/vaults/metadata')

Directory containing protocol metadata YAML files

FORMATTED_LOGOS_DIR = PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi/eth_defi/data/vaults/formatted_logos')

Directory containing formatted 256x256 PNG logos

All link fields that should be present in the output

Bases: TypedDict

Links associated with a vault protocol.

All fields are optional and may be None if not available.

homepage: str | None

Protocol homepage URL

app: str | None

Direct link to the dApp page for vaults

twitter: str | None

Link to Twitter/X account

github: str | None

Link to smart contracts GitHub repository

documentation: str | None

Link to developer documentation

defillama: str | None

Link to DefiLlama protocol page

audits: str | None

Link to security audits page or specific audit

fees: str | None

Link to fee structure documentation

trading_strategy: str | None

Link to TradingStrategy.ai protocol listing

integration_documentation: str | None

Link to this library’s integration documentation

__init__(*args, **kwargs)
__new__(**kwargs)
clear() → None.  Remove all items from D.
copy() → a shallow copy of D
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() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D'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() → an object providing a view on D's values
class VaultProtocolLogos

Bases: TypedDict

Logo URLs for a vault protocol.

Logo URLs point to 256x256 PNG files in R2 storage. None if the logo variant is not available.

dark: str | None

Logo for dark backgrounds (light-coloured logo)

light: str | None

Logo for light backgrounds (dark-coloured logo)

__init__(*args, **kwargs)
__new__(**kwargs)
clear() → None.  Remove all items from D.
copy() → a shallow copy of D
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() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D'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() → an object providing a view on D's values
class VaultProtocolMetadata

Bases: TypedDict

Complete vault protocol metadata as exported to JSON.

This structure is used for frontend consumption and API responses.

name: str

Human-readable protocol name

slug: str

Lowercase slug with dashes (e.g., “lagoon-finance”)

short_description: str | None

One-line description of the protocol

long_description: str | None

Multi-paragraph Markdown description

fee_description: str | None

Multi-paragraph Markdown description of fees

Protocol links

example_smart_contracts: list[str]

List of example vault contract URLs on blockchain explorers

logos: eth_defi.vault.protocol_metadata.VaultProtocolLogos

Logo URLs for different background themes

__init__(*args, **kwargs)
__new__(**kwargs)
clear() → None.  Remove all items from D.
copy() → a shallow copy of D
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() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D'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() → an object providing a view on D's values
read_protocol_metadata(yaml_path)

Read and parse a protocol metadata YAML file.

Parameters

yaml_path (pathlib.Path) – Path to the YAML file

Returns

Parsed YAML as a dictionary

Return type

dict

get_available_logos(slug)

Check which logo variants are available for a protocol.

Parameters

slug (str) – Protocol slug (e.g., “euler”, “lagoon-finance”)

Returns

Dictionary with ‘dark’ and ‘light’ keys indicating availability

Return type

dict[str, bool]

build_metadata_json(yaml_path, public_url)

Build a VaultProtocolMetadata dict from a YAML file.

Reads the YAML metadata, adds logo URLs based on available formatted logos, and ensures all fields are present (with None for missing values).

Parameters
Returns

Complete VaultProtocolMetadata dict ready for JSON export

Return type

eth_defi.vault.protocol_metadata.VaultProtocolMetadata

process_and_upload_protocol_metadata(slug, bucket_name, endpoint_url, access_key_id, secret_access_key, public_url, key_prefix='')

Process and upload a single protocol’s metadata and logos to R2.

Reads the YAML metadata file, builds the JSON with logo URLs, and uploads the JSON and any available logo files to R2.

Parameters

  • slug (str) – Protocol slug (e.g., “euler”, “lagoon-finance”)

  • bucket_name (str) – R2 bucket name

  • endpoint_url (str) – R2 API endpoint URL

  • access_key_id (str) – R2 access key ID

  • secret_access_key (str) – R2 secret access key

  • public_url (str) – Public base URL for constructing logo URLs in metadata

  • key_prefix (str) – Optional prefix for R2 keys (e.g., “test-” for testing)

Returns

The processed VaultProtocolMetadata dict

Return type

eth_defi.vault.protocol_metadata.VaultProtocolMetadata