MellowVault

Documentation for eth_defi.mellow.vault.MellowVault Python class.

class MellowVault

Bases: eth_defi.vault.base.VaultBase

Mellow Core Vault adapter.

Create a Mellow vault adapter.

Parameters

web3 – Web3 connection.
spec – Chain/address vault identity. Address must be the Mellow Vault.
token_cache – Token metadata cache.
features – Shared scanner feature set. Expected to contain mellow_like.
default_block_identifier – Block used for metadata reads.
require_denomination_token – Whether missing denomination token should raise through the base cached property.
api_metadata – Optional offchain Mellow metadata enrichment.

Attributes summary

`address`	Canonical Mellow `Vault` address.
`chain_id`	Chain id for this vault.
`denomination_token`	Get the token which denominates the vault valuation
`deposit_manager`	Deposit manager assocaited with this vault
`description`	Human-readable vault strategy description.
`fee_manager_address`	Fetch the Mellow FeeManager address from the vault.
`fee_manager_contract`	Mellow FeeManager contract with minimal ABI.
`flow_manager`	Flow manager associated with this vault
`info`	Get info dictionary related to this vault deployment.
`manager_name`	Protocol-supplied vault manager or curator display name.
`name`	Vault share token name.
`oracle_address`	Fetch the Mellow oracle address from the vault.
`oracle_contract`	Mellow oracle contract with minimal ABI.
`share_manager_address`	Fetch the ShareManager address from the vault.
`share_manager_contract`	Tokenised ShareManager contract with ERC-20 ABI.
`share_token`	ERC-20 that presents vault shares.
`short_description`	One-liner vault summary.
`symbol`	Vault share token symbol.
`vault_address`	Canonical Mellow `Vault` address.
`vault_contract`	Mellow `Vault` contract with minimal ABI.

Methods summary

`__init__`(web3, spec[, token_cache, ...])	Create a Mellow vault adapter.
`fetch_assets`()	Fetch registered asset addresses.
`fetch_available_liquidity`([block_identifier])	Get the amount of denomination token available for immediate withdrawal.
`fetch_denomination_token`()	Fetch the denomination token metadata.
`fetch_denomination_token_address`()	Fetch the base asset used for initial valuation.
`fetch_deposit_closed_reason`()	Get human-readable reason why deposits are closed.
`fetch_deposit_next_open`()	Get when deposits will next be open.
`fetch_fee_configuration`([block_identifier])	Fetch Mellow FeeManager configuration.
`fetch_info`()	Fetch Mellow component graph metadata.
`fetch_nav`([block_identifier])	Fetch Mellow NAV.
`fetch_oracle_report`([asset, block_identifier])	Fetch the latest Mellow oracle report for an asset.
`fetch_portfolio`(universe[, block_identifier])	Fetch a partial portfolio.
`fetch_queues`(asset)	Fetch queues for a registered asset.
`fetch_redemption_closed_reason`()	Get human-readable reason why redemptions are closed.
`fetch_redemption_next_open`()	Get when withdrawals/redemptions will next be open.
`fetch_scan_record_extra_data`()	Fetch Mellow-specific private scan row columns.
`fetch_share_price`([block_identifier])	Fetch Mellow share price from the oracle report.
`fetch_share_token`()	Fetch tokenised ShareManager ERC-20 metadata.
`fetch_share_token_address`([block_identifier])	Return the tokenised ShareManager address.
`fetch_total_assets`([block_identifier])	Fetch Mellow denomination-token TVL from on-chain share accounting.
`fetch_total_supply`([block_identifier])	Fetch tokenised ShareManager total supply.
`fetch_utilisation_percent`([block_identifier])	Get the percentage of assets currently lent out.
`get_deposit_fee`(block_identifier)	Fetch deposit fee.
`get_deposit_manager`()	Get active deposit manager.
`get_deposit_manager_capability`()	Return static public transaction-adapter support, if any.
`get_estimated_lock_up`()	What is the estimated lock-up period for this vault.
`get_fee_data`()	Return Mellow fee data.
`get_fee_mode`()	Get how this vault accounts its fees.
`get_flags`()	Get various vault state flags from the smart contract.
`get_flow_manager`()	Get Mellow flow manager.
`get_historical_reader`(stateful)	Get the Mellow historical reader.
`get_link`([referral])	Get Mellow vault link.
`get_management_fee`(block_identifier)	Fetch management-like fee.
`get_notes`()	Get a human readable message if we know somethign special is going on with this vault.
`get_performance_fee`(block_identifier)	Fetch performance fee.
`get_protocol_name`()	Return protocol name.
`get_risk`()	Get risk profile of this vault.
`get_spec`()
`get_withdraw_fee`(block_identifier)	Fetch redeem fee.
`has_block_range_event_support`()	Whether queue event scanning is implemented.
`has_custom_fees`()	Whether Mellow has fees outside the shared fee model.
`has_deposit_distribution_to_all_positions`()	Whether deposits are automatically distributed to positions.

__init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False, api_metadata=None)

Create a Mellow vault adapter.

Parameters

web3 (web3.main.Web3) – Web3 connection.
spec (eth_defi.vault.base.VaultSpec) – Chain/address vault identity. Address must be the Mellow Vault.
token_cache (Optional[dict]) – Token metadata cache.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Shared scanner feature set. Expected to contain mellow_like.
default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Block used for metadata reads.
require_denomination_token (bool) – Whether missing denomination token should raise through the base cached property.
api_metadata (Optional[eth_defi.mellow.offchain_metadata.MellowApiVaultMetadata]) – Optional offchain Mellow metadata enrichment.

property chain_id: int: Chain id for this vault.

property address: eth_typing.evm.HexAddress: Canonical Mellow Vault address.

property vault_address: eth_typing.evm.HexAddress

Canonical Mellow Vault address.

ERC-4626 adapters expose this convenience property and shared historical scan code still uses it for blacklists and diagnostics. For Mellow this is intentionally the Core Vault proxy, not the ShareManager token.

property name: str: Vault share token name.

property symbol: str: Vault share token symbol.

property vault_contract: web3.contract.contract.Contract: Mellow Vault contract with minimal ABI.

property share_manager_address: eth_typing.evm.HexAddress: Fetch the ShareManager address from the vault.

property share_manager_contract: web3.contract.contract.Contract: Tokenised ShareManager contract with ERC-20 ABI.

property oracle_address: eth_typing.evm.HexAddress: Fetch the Mellow oracle address from the vault.

property oracle_contract: web3.contract.contract.Contract: Mellow oracle contract with minimal ABI.

property fee_manager_address: eth_typing.evm.HexAddress: Fetch the Mellow FeeManager address from the vault.

property fee_manager_contract: web3.contract.contract.Contract: Mellow FeeManager contract with minimal ABI.

fetch_share_token_address(block_identifier='latest')

Return the tokenised ShareManager address.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Accepted for compatibility with the shared historical multicaller.
Returns: ShareManager address.
Return type: eth_typing.evm.HexAddress

fetch_share_token()

Fetch tokenised ShareManager ERC-20 metadata.

Returns: Share token details.
Return type: eth_defi.token.TokenDetails

fetch_denomination_token_address()

Fetch the base asset used for initial valuation.

The initial adapter uses API/configured base token if present, otherwise falls back to the first registered asset. Mellow can be multi-asset, so all registered assets remain available in fetch_info().

Returns: Base asset address, or None if unavailable.
Return type: Optional[eth_typing.evm.HexAddress]

fetch_denomination_token()

Fetch the denomination token metadata.

Returns: Token details for the base asset, or None.
Return type: Optional[eth_defi.token.TokenDetails]

fetch_assets()

Fetch registered asset addresses.

Returns: List of registered assets.
Return type: list[eth_typing.evm.HexAddress]

fetch_queues(asset)

Fetch queues for a registered asset.

Parameters: asset (eth_typing.evm.HexAddress) – Registered asset address.
Returns: Deposit queues and redeem queues.
Return type: tuple[list[eth_typing.evm.HexAddress], list[eth_typing.evm.HexAddress]]

fetch_info()

Fetch Mellow component graph metadata.

Returns: Component graph metadata.
Return type: eth_defi.mellow.vault.MellowVaultInfo

fetch_total_supply(block_identifier='latest')

Fetch tokenised ShareManager total supply.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Human-readable share supply.
Return type: Optional[decimal.Decimal]

fetch_oracle_report(asset=None, block_identifier='latest')

Fetch the latest Mellow oracle report for an asset.

Parameters

asset (Optional[eth_typing.evm.HexAddress]) – Asset address. Defaults to denomination_token.
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.

Returns

Oracle report, or None if the report cannot be read.

Return type

Optional[eth_defi.mellow.vault.MellowOracleReport]

fetch_share_price(block_identifier='latest')

Fetch Mellow share price from the oracle report.

Mellow reports priceD18 as raw shares per raw asset: shares = assets * priceD18 / 1e18. This method converts it to the shared vault pipeline convention, denomination-token assets per one human-readable share token.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Denomination-token assets per share, or None if unavailable.
Return type: Optional[decimal.Decimal]

fetch_fee_configuration(block_identifier='latest')

Fetch Mellow FeeManager configuration.

Mellow stores all configured rates in D6 precision. protocolFeeD6 is the annual time-based fee; the adapter maps it to the shared management-fee field because the shared schema has no separate protocol fee column.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: FeeManager configuration, or None if the FeeManager cannot be read.
Return type: Optional[eth_defi.mellow.vault.MellowFeeConfiguration]

get_fee_data()

Return Mellow fee data.

Mellow fees are configured through FeeManager as D6 rates and paid in vault shares. protocolFeeD6 is an annual time-based fee, so it is mapped to the shared management-fee field. performanceFeeD6 maps to the performance-fee field, while deposit and redeem D6 rates map to the shared deposit and withdraw fee fields.

Returns: Fee data, or BROKEN_FEE_DATA if the FeeManager cannot be read.
Return type: eth_defi.vault.fee.FeeData

fetch_scan_record_extra_data()

Fetch Mellow-specific private scan row columns.

_mellow_info preserves the component graph that the initial Mellow-only scan branch exposed before Mellow was moved to the shared vault scan path.

Returns: Mellow component graph metadata for raw scan rows.
Return type: dict[str, object]

fetch_total_assets(block_identifier='latest')

Fetch Mellow denomination-token TVL from on-chain share accounting.

Mellow does not expose ERC-4626 totalAssets() on the canonical vault. For comparable scanner output we use the same on-chain accounting identity as the historical reader: oracle share price in the denomination token multiplied by tokenised ShareManager.totalSupply. The public API USD TVL is not used here.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Human-readable denomination-token TVL, or None if either price or supply is unavailable.
Return type: Optional[decimal.Decimal]

fetch_nav(block_identifier='latest')

Fetch Mellow NAV.

fetch_nav() is kept as the VaultBase-compatible alias for current scanner reads. It returns the same denomination-token value as fetch_total_assets(), not the public API USD TVL.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Human-readable denomination-token TVL, or None if unavailable.
Return type: Optional[decimal.Decimal]

fetch_portfolio(universe, block_identifier=None)

Fetch a partial portfolio.

The initial adapter does not reconstruct subvault balances. It returns an empty portfolio instead of pretending to know full Mellow holdings.

Parameters

universe (eth_defi.vault.base.TradingUniverse) – Trading universe.
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Block number or tag.

Returns

Empty portfolio placeholder.

Return type

eth_defi.vault.base.VaultPortfolio

has_block_range_event_support()

Whether queue event scanning is implemented.

Returns: False until Mellow queue flow reader is implemented.
Return type: bool

has_deposit_distribution_to_all_positions()

Whether deposits are automatically distributed to positions.

Returns: False because Mellow deposits settle through queues and curator/subvault allocation.
Return type: bool

get_flow_manager()

Get Mellow flow manager.

Returns: Placeholder flow manager that raises for all read methods.
Return type: eth_defi.vault.base.VaultFlowManager

get_deposit_manager()

Get active deposit manager.

Returns: Never returns until active queue transaction execution is implemented.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManager

get_historical_reader(stateful)

Get the Mellow historical reader.

Parameters: stateful (bool) – Whether to use shared adaptive reader state.
Returns: Mellow historical reader.
Return type: eth_defi.vault.base.VaultHistoricalReader

get_protocol_name()

Return protocol name.

Returns: Mellow.
Return type: str

has_custom_fees()

Whether Mellow has fees outside the shared fee model.

Mellow FeeManager fees are all represented by FeeData: protocolFeeD6 is management-like, performanceFeeD6 is performance-like, and depositFeeD6/redeemFeeD6 map to the standard deposit/withdraw fields.

Returns: False because no Mellow FeeManager fee is outside the shared fee fields.
Return type: bool

get_management_fee(block_identifier)

Fetch management-like fee.

Mellow calls this value protocolFeeD6: an annual time-based fee charged in vault shares. We expose it through the shared management fee column because the generic vault schema has no separate protocol-fee field.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Fractional fee, e.g. 0.01 for 1%.
Return type: Optional[float]

get_performance_fee(block_identifier)

Fetch performance fee.

Mellow stores performance fees in D6 precision and charges them in vault shares when oracle reports update the FeeManager state.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Fractional fee, e.g. 0.15 for 15%.
Return type: Optional[float]

get_deposit_fee(block_identifier)

Fetch deposit fee.

Mellow stores deposit fees in D6 precision and charges them in vault shares during deposit queue report handling.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Fractional fee, e.g. 0.005 for 0.5%.
Return type: Optional[float]

get_withdraw_fee(block_identifier)

Fetch redeem fee.

Mellow names this value redeemFeeD6. The shared vault interface uses the withdraw fee field for the same user-facing redemption charge.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number or tag.
Returns: Fractional fee, e.g. 0.003 for 0.3%.
Return type: Optional[float]

get_link(referral=None)

Get Mellow vault link.

Parameters: referral (Optional[str]) – Optional referral code, currently unused.
Returns: Mellow app link.
Return type: str

property denomination_token: Optional[eth_defi.token.TokenDetails]

Get the token which denominates the vault valuation

Used in deposits and redemptions
Used in NAV calculation
Used in profit benchmarks
Usually USDC

Returns

Token wrapper instance.

Maybe None for broken vaults like https://arbiscan.io/address/0x9d0fbc852deccb7dcdd6cb224fa7561efda74411#code

Note

None results are not cached — the next access will retry the on-chain call. This avoids permanently caching a transient RPC failure.

property deposit_manager: eth_defi.vault.deposit_redeem.VaultDepositManager: Deposit manager assocaited with this vault

property description: Optional[str]

Human-readable vault strategy description.

Fetched from protocol-specific offchain sources (e.g. Euler GitHub labels, Lagoon web app API)
Returns None if the protocol does not provide descriptions or the vault is not in the metadata source
Override in subclasses that support offchain metadata

fetch_available_liquidity(block_identifier='latest')

Get the amount of denomination token available for immediate withdrawal.

Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.

Note: maxRedeem(address(0)) does NOT work as a proxy for available liquidity because it requires a specific address that has already deposited shares. For address(0), balanceOf is always 0, so maxRedeem returns 0 regardless of actual liquidity.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
Raises: NotImplementedError – For non-lending protocol vaults.
Returns: Amount in denomination token units (human-readable Decimal).
Return type: Optional[decimal.Decimal]

fetch_deposit_closed_reason()

Get human-readable reason why deposits are closed.

Override in protocol-specific subclasses
Default behaviour: assume deposits are always open (return None)

Returns

Human-readable string explaining why deposits are closed, or None if deposits are open.

Example reasons:

”Epoch redemption window closed (opens in 14h)”
”Vault paused by admin”
”Max deposit cap reached”
”Vault utilisation too high”

Return type

Optional[str]

fetch_deposit_next_open()

Get when deposits will next be open.

For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses

Returns

Naive UTC datetime when deposits will next be available, or None if:

Deposits are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information

Return type

Optional[datetime.datetime]

fetch_redemption_closed_reason()

Get human-readable reason why redemptions are closed.

Override in protocol-specific subclasses
Default behaviour: assume redemptions are always open (return None)

Returns

Human-readable string explaining why redemptions are closed, or None if redemptions are open.

Example reasons:

”Epoch funding phase in progress (opens in 2d 5h)”
”Vault paused by admin”
”Vault utilisation too high - insufficient liquidity”

Return type

Optional[str]

fetch_redemption_next_open()

Get when withdrawals/redemptions will next be open.

For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses

Returns

Naive UTC datetime when withdrawals will next be available, or None if:

Withdrawals are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information

Return type

Optional[datetime.datetime]

fetch_utilisation_percent(block_identifier='latest')

Get the percentage of assets currently lent out.

Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
Raises: NotImplementedError – For non-lending protocol vaults.
Returns: Utilisation as float between 0.0 and 1.0 (0% to 100%).
Return type: Optional[float]

property flow_manager: eth_defi.vault.base.VaultFlowManager: Flow manager associated with this vault

get_deposit_manager_capability()

Return static public transaction-adapter support, if any.

This method deliberately does not attempt to construct a manager or query live pause, cap, epoch, balance, allow-list, or liquidity state. Adapters opt in only after their complete deposit and redemption lifecycles have focused coverage. None is therefore the safe default for unknown and protocol-specific vaults.

Returns: Adapter-specific capability object, or None when unsupported.
Return type: Optional[eth_defi.vault.deposit_redeem.VaultDepositManagerCapability]

get_estimated_lock_up()

What is the estimated lock-up period for this vault.

Returns: None if not know
Return type: Optional[datetime.timedelta]

get_fee_mode()

Get how this vault accounts its fees.

Return type: Optional[eth_defi.vault.fee.VaultFeeMode]

get_flags()

Get various vault state flags from the smart contract.

Override to add status flags
Also add flags from our manual flag list in eth_defi.vault.flag

Returns

Flag set.

Do not modify in place.

Return type

set[eth_defi.vault.flag.VaultFlag]

get_notes()

Get a human readable message if we know somethign special is going on with this vault.

Return type: Optional[str]

get_risk()

Get risk profile of this vault.

Return type: Optional[eth_defi.vault.risk.VaultTechnicalRisk]

property info: eth_defi.vault.base.VaultInfo

Get info dictionary related to this vault deployment.

Get cached data on the various vault parameters

Returns: Vault protocol specific information dictionary

property manager_name: Optional[str]

Protocol-supplied vault manager or curator display name.

Used when the vault name itself does not contain the curator brand
Returns None if the protocol does not expose separate manager metadata
Override in subclasses that support manager or operator metadata

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

User gets shares on deposit and burns them on redemption

property short_description: Optional[str]

One-liner vault summary.

Shorter version of description() suitable for listings and tables
Returns None if not available
Override in subclasses that support offchain metadata