xerberus.vault_export

Documentation for eth_defi.xerberus.vault_export Python module.

Export helpers for Xerberus risk data into vault metrics JSON.

Builds:

Functions

build_xerberus_pool_lookup(db[, max_age_days])

Build a (chain_id, address) → score map for per-vault export.

build_xerberus_protocols_for_export(db, ...)

Build protocol-slug-keyed Xerberus records for top-level JSON export.

compute_xerberus_export_stats(vaults)

Compute coverage stats from exported vault records.

resolve_xerberus_vault_section(chain_id, ...)

Resolve compact per-vault Xerberus section using canonical lookup order.

Classes

XerberusExportStats

Optional coverage summary for the exported vault list.

XerberusPoolLookupRow

Preloaded per-vault score row for O(1) resolve during metrics export.

XerberusProtocolExportRecord

Top-level protocol metadata in xerberus_protocols (like Core3).

XerberusVaultSection

Compact per-vault Xerberus risk summary on each vault metrics row.
class XerberusPoolLookupRow

Bases: TypedDict

Preloaded per-vault score row for O(1) resolve during metrics export.

chain_id: int

EIP-155 chain id.

address: str

Lowercased EVM vault address.

score: Optional[float]

Composite score 0–100, or None if unscored.

entity_id: str

Xerberus entity id (registry pool id or vault_list vault_id).

name: Optional[str]

Display name; never used as join key.

fetched_at: str

ISO 8601 snapshot timestamp.

source: Literal['registry', 'vault_list']

Which table supplied this row.

report_url: Optional[str]

Optional dendrogram deep link when known.

__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.

class XerberusVaultSection

Bases: TypedDict

Compact per-vault Xerberus risk summary on each vault metrics row.

score: Optional[float]

Composite score 0–100, or None.

score_scale: str

Always XERBERUS_SCORE_SCALE.

entity_type: Literal['pool', 'protocol']

pool when vault-specific; protocol on fallback.

entity_id: str

Xerberus entity id.

name: Optional[str]

Display name.

protocol_slug: Optional[str]

Our protocol slug when entity_type is protocol.

report_url: Optional[str]

Dendrogram report URL when known.

fetched_at: str

ISO 8601 snapshot timestamp.

__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.

class XerberusProtocolExportRecord

Bases: TypedDict

Top-level protocol metadata in xerberus_protocols (like Core3).

protocol_slug: str

Our vault protocol slug (same as map key).

entity_id: str

Xerberus registry protocol id.

name: Optional[str]

Protocol display name.

score: Optional[float]

Composite score 0–100, or None.

score_scale: str

Always XERBERUS_SCORE_SCALE.

fetched_at: str

ISO 8601 snapshot timestamp.

__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.

class XerberusExportStats

Bases: TypedDict

Optional coverage summary for the exported vault list.

total_vaults: int

Number of vaults considered.

pool_matches: int

Vaults with a pool-level score.

protocol_fallbacks: int

Vaults that fell back to protocol score only.

unmatched: int

Vaults with no Xerberus section.

coverage_pct: float

Percentage of vaults with any Xerberus match (pool or protocol).

__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.

build_xerberus_pool_lookup(db, max_age_days=30)

Build a (chain_id, address) → score map for per-vault export.

Merge precedence:

  1. Registry pool with non-null score always wins.

  2. Vault list is used only when the key is missing or registry score is null.

Parameters
Returns

Lookup dict keyed by (chain_id, address_lower).

Return type

dict[tuple[int, str], eth_defi.xerberus.vault_export.XerberusPoolLookupRow]

build_xerberus_protocols_for_export(db, protocol_slugs, max_age_days=30)

Build protocol-slug-keyed Xerberus records for top-level JSON export.

Parameters
Returns

Dict mapping our protocol slug to export records. Unmapped / missing / stale slugs are excluded.

Return type

dict[str, eth_defi.xerberus.vault_export.XerberusProtocolExportRecord]

resolve_xerberus_vault_section(chain_id, address, protocol_slug, pools, protocols)

Resolve compact per-vault Xerberus section using canonical lookup order.

  1. Pool map hit with non-null score (or any pool hit with entity id)

  2. Protocol fallback via protocols[protocol_slug]

Parameters
Returns

Compact section, or None if nothing matched.

Return type

Optional[eth_defi.xerberus.vault_export.XerberusVaultSection]

compute_xerberus_export_stats(vaults)

Compute coverage stats from exported vault records.

Parameters

vaults (list[dict]) – Vault metric dicts that may contain a xerberus key.

Returns

Coverage statistics.

Return type

eth_defi.xerberus.vault_export.XerberusExportStats