erc_4626.vault_protocol.morpho.vault_v2

Documentation for eth_defi.erc_4626.vault_protocol.morpho.vault_v2 Python module.

Morpho Vault V2 support.

Morpho Vault V2 is an upgraded version of Morpho vaults that introduces an adapter-based architecture for flexible asset allocation across multiple yield sources.

Key features of Morpho Vault V2:

Adapter-based architecture for multi-protocol yield allocation
Granular ID & Cap system for risk management
Performance and management fees (up to 50% and 5% respectively)
Timelocked governance with optional abdication
Non-custodial exits via forceDeallocate

Classes

`MorphoV2Vault`	Morpho Vault V2 support.
`MorphoV2VaultHistoricalReader`	Read Morpho V2 vault core data + fees + utilisation.

class MorphoV2Vault

Bases: eth_defi.erc_4626.vault.ERC4626Vault

Morpho Vault V2 support.

Morpho Vault V2 is a newer version of Morpho vaults with an adapter-based architecture that allows flexible allocation across multiple yield sources.

Key differences from Morpho V1:

V2 uses adapters to allocate to multiple yield sources (not just Morpho markets)
V2 has both performance and management fees (V1 only had performance fee)
V2 uses adaptersLength() function while V1 uses MORPHO() function
V2 has timelocked governance with curator/allocator roles

See also eth_defi.erc_4626.vault_protocol.morpho.vault_v1.MorphoV1Vault for the original MetaMorpho architecture.

Parameters

web3 – Connection we bind this instance to
spec – Chain, address tuple
token_cache –
Cache used with fetch_erc20_details() to avoid multiple calls to the same token.

Reduces the number of RPC calls when scanning multiple vaults.
features – Pass vault feature flags along, externally detected.
default_block_identifier –
Override block identifier for on-chain metadata reads.

When None, use get_safe_cached_latest_block_number() (the default, safe for broken RPCs). Set to "latest" for freshly deployed vaults whose contracts do not exist at the safe-cached block.
require_denomination_token – If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

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

Parameters

web3 (web3.main.Web3) – Connection we bind this instance to
spec (eth_defi.vault.base.VaultSpec) – Chain, address tuple
token_cache (Optional[dict]) –
Cache used with fetch_erc20_details() to avoid multiple calls to the same token.

Reduces the number of RPC calls when scanning multiple vaults.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Pass vault feature flags along, externally detected.
default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]]) –
Override block identifier for on-chain metadata reads.

When None, use get_safe_cached_latest_block_number() (the default, safe for broken RPCs). Set to "latest" for freshly deployed vaults whose contracts do not exist at the safe-cached block.
require_denomination_token (bool) – If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

property address: eth_typing.evm.HexAddress: Get the vault smart contract address.

can_check_deposit()

Check if maxDeposit(address(0)) can be used to check global deposit availability.

Most ERC-4626 vaults implement maxDeposit in a way that returns meaningful values when called with address(0):

Returns 0 when deposits are globally closed/capped
Returns a positive value indicating maximum deposit allowed

Override to return False in subclasses where maxDeposit(address(0)) doesn’t provide meaningful global availability information.

Returns: True if maxDeposit(address(0)) returns meaningful values for global deposit availability checking.
Return type: bool

can_check_redeem()

Morpho V2 supports address(0) checks for redemption availability.

maxRedeem(address(0)) returns 0 when redemptions are blocked

Return type: bool

property chain_id: int: Chain this vault is on

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

property erc_7540: bool

Is this ERC-7540 vault with asynchronous deposits.

For example previewDeposit() function and other functions will revert

fetch_available_liquidity(block_identifier='latest')

Get the amount of denomination token available for immediate withdrawal.

Uses the idle assets pattern: asset().balanceOf(vault) returns unallocated assets.

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”.
Returns: Amount in denomination token units (human-readable Decimal).
Return type: Optional[decimal.Decimal]

fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type: Optional[eth_defi.token.TokenDetails]

fetch_denomination_token_address()

Get the asset() denomination token address of this vault.

Results are disk-cached per (chain_id, vault_address) via eth_defi.erc_4626.vault_token when the vault was constructed with a eth_defi.token.TokenDiskCache and no pinned default_block_identifier. The denomination token is immutable post-deployment, so the cached value is correct regardless of which block the caller would have asked for.

Only a definitive non-null answer is persisted. The None path taken on revert / broken contract is never cached, matching the behaviour of eth_defi.vault.base.VaultBase.denomination_token() which explicitly avoids memoising None so transient failures can be retried.

To disable the cache, pass token_cache=None (or any non- TokenDiskCache dict) when constructing the vault, or construct with a pinned default_block_identifier.

Returns: Denomination token address, or None if the vault contract is broken and did not return a valid address.
Return type: Optional[eth_typing.evm.HexAddress]

fetch_deposit_closed_reason()

Check maxDeposit to determine if deposits are closed.

Morpho vaults are utilisation-based.

Return type: Optional[str]

fetch_deposit_next_open()

Deposit timing is unpredictable - utilisation-based.

Return type: Optional[datetime.datetime]

fetch_info()

Use info() property for cached access.

Returns: See LagoonVaultInfo
Return type: eth_defi.erc_4626.vault.ERC4626VaultInfo

fetch_nav(block_identifier=None)

Fetch the most recent onchain NAV value.

In the case of Lagoon, this is the last value written in the contract with updateNewTotalAssets() and ` settleDeposit()`
TODO: updateNewTotalAssets() there is no way to read pending asset update on chain

Returns: Vault NAV, denominated in denomination_token()
Return type: decimal.Decimal

fetch_portfolio(universe, block_identifier=None, allow_fallback=True)

Read the current token balances of a vault.

SHould be supported by all implementations

Parameters

universe (eth_defi.vault.base.TradingUniverse) –
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]]) –
allow_fallback (bool) –

Return type

eth_defi.vault.base.VaultPortfolio

fetch_redemption_closed_reason()

Check maxRedeem to determine if redemptions are closed.

Morpho vaults are utilisation-based.

Return type: Optional[str]

fetch_redemption_next_open()

Withdrawal timing is unpredictable - utilisation-based.

Return type: Optional[datetime.datetime]

fetch_share_price(block_identifier)

Get the current share price.

Returns

The share price in underlying token.

If supply is zero return zero.

Parameters

block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) –

Return type

decimal.Decimal

fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

Return type: eth_defi.token.TokenDetails

fetch_share_token_address(block_identifier='latest')

Get share token of this vault.

Vault itself (ERC-4626)
share() accessor (ERC-7575)

Results are disk-cached per (chain_id, vault_address) via eth_defi.erc_4626.vault_token when the vault was constructed with a eth_defi.token.TokenDiskCache. Under normal circumstances the block_identifier argument is effectively ignored on cache hits — ERC-4626 share tokens are immutable post-deployment, so the cached value is correct regardless of which block the caller asked for.

Only a definitive answer from the chain is ever persisted: a successful call, or a revert matching KNOWN_SHARE_TOKEN_ERROR_MESSAGES (which positively classifies the contract as non-ERC-7575). Transient RPC failures (ProbablyNodeHasNoBlock, HTTP 502) fall back to self.vault_address but are not written to the cache, so a flaky node cannot poison a real ERC-7575 vault’s entry.

To disable the cache, pass token_cache=None (or any non- TokenDiskCache dict) when constructing the vault, or construct with a pinned default_block_identifier to force the uncached historical-read path on every call.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) – Block to query. Cache is only consulted/written when the caller passes the default "latest" and the vault instance has no pinned default_block_identifier.
Return type: eth_typing.evm.HexAddress

fetch_total_assets(block_identifier)

What is the total NAV of the vault.

Example:

assert vault.denomination_token.symbol == "USDC"
assert vault.share_token.symbol == "ipUSDCfusion"
assert vault.fetch_total_assets(block_identifier=test_block_number) == Decimal("1437072.77357")
assert vault.fetch_total_supply(block_identifier=test_block_number) == Decimal("1390401.22652875")

Parameters

Block number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

Optional[decimal.Decimal]

fetch_total_supply(block_identifier)

What is the current outstanding shares.

Example:

Parameters

Block number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

decimal.Decimal

fetch_utilisation_percent(block_identifier='latest')

Get the percentage of assets currently allocated to strategies.

Utilisation = (totalAssets - idle) / totalAssets

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”.
Returns: Utilisation as float between 0.0 and 1.0 (0% to 100%).
Return type: Optional[float]

fetch_vault_info()

Get all information we can extract from the vault smart contracts.

Return type: eth_defi.erc_4626.vault.ERC4626VaultInfo

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

get_adapters_count(block_identifier='latest')

Get the number of adapters configured for this vault.

Returns: Number of adapters, or None if reading fails
Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: Optional[int]

get_deposit_fee(block_identifier)

Deposit fee is set to zero by default as vaults usually do not have deposit fees.

Internal: Use get_fee_data().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: Optional[float]

get_deposit_manager()

Get deposit manager to deposit/redeem from the vault.

Return type: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

get_estimated_lock_up()

Morpho V2 vaults have no lock-up period.

Users can withdraw at any time using regular withdraw or forceDeallocate.

Return type: Optional[datetime.timedelta]

get_fee_data()

Get fee data structure for this vault.

Raises: ValueError – In the case of broken or unimplemented fee reading methods in the smart contract
Return type: eth_defi.vault.fee.FeeData

get_fee_mode()

Get how this vault accounts its fees.

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

get_flags()

Get vault flags, adding morpho_issues when RED warnings are detected.

Calls the Morpho GraphQL API (24h cached) to check for RED-level vault or market warnings. If any are found, adds morpho_issues to the flag set.

Returns: Set of VaultFlag values.
Return type: set[eth_defi.vault.flag.VaultFlag]

get_flow_manager()

Get flow manager to read indiviaul settle events.

Only supported if has_block_range_event_support() is True

Return type: eth_defi.vault.base.VaultFlowManager

get_historical_reader(stateful)

Get Morpho V2-specific historical reader with utilisation metrics.

Parameters: stateful (bool) –
Return type: eth_defi.vault.base.VaultHistoricalReader

get_link(referral=None)

Get link to the vault on Morpho app.

Parameters: referral (Optional[str]) – Optional referral code (not supported by Morpho)
Returns: URL to the vault page on app.morpho.org
Return type: str

get_management_fee(block_identifier)

Get Morpho V2 management fee.

Management fee is charged on total assets (up to 5% per year).

Returns: Management fee as a decimal (e.g. 0.02 for 2%), or None if reading fails
Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: Optional[float]

get_morpho_market_flags()

Return warning type strings from Morpho API warnings on underlying markets.

Returns: Set of warning type strings, e.g. {"bad_debt_unrealized"}. Empty set if no data available.
Return type: set[str]

get_morpho_vault_flags()

Return warning type strings from vault-level Morpho API warnings.

Returns: Set of warning type strings, e.g. {"short_timelock", "not_whitelisted"}. Empty set if no data available.
Return type: set[str]

get_notes()

Return a human-readable note about RED-level Morpho warnings, if any.

Checks the hardcoded flag table first (via the base class), then falls back to a dynamically generated note from the Morpho GraphQL API when RED warnings are present.

Returns: Note string, or None if no hardcoded note and no RED warnings.
Return type: Optional[str]

get_performance_fee(block_identifier)

Get Morpho V2 performance fee.

Performance fee is charged on yield generated (up to 50%).

Returns: Performance fee as a decimal (e.g. 0.1 for 10%), or None if reading fails
Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: Optional[float]

get_protocol_name()

Return the name of the vault protocol.

Return type: str

get_risk()

Get risk profile of this vault.

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

get_withdraw_fee(block_identifier)

Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.

Internal: Use get_fee_data().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

has_block_range_event_support()

Does this vault support block range-based event queries for deposits and redemptions.

If not we use chain balance polling-based approach

has_custom_fees()

Does this vault have custom fee structure reading methods.

Causes risk in the vault comparison.

E.g.

Withdraw fee
Deposit fee

Returns: True if custom fee reading methods are implemented
Return type: bool

has_deposit_distribution_to_all_positions()

Deposits go automatically to all open positions.

Deposits do not land into the vault as cash
Instead, smart contracts automatically increase all open positions
The behaviour of Velvet Capital

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

is_valid()

Check if this vault is valid.

Call a known smart contract function to verify the function exists

Return type: bool

property morpho_api_result: eth_defi.erc_4626.vault_protocol.morpho.offchain_metadata.MorphoVaultAPIResult

Vault lookup result from the Morpho GraphQL API.

V2 vaults use vaultV2ByAddress so valid V2 vaults are not mistaken for missing V1 vaults.

Returns: Three-way Morpho API lookup result.

property morpho_offchain_data: Optional[eth_defi.erc_4626.vault_protocol.morpho.offchain_metadata.MorphoVaultData]

Vault and market warnings from the Morpho GraphQL API (24h cached).

Fetches vault-level governance warnings via the Morpho public GraphQL API. V2 vaults do not expose V1-style market allocation warnings, so market_warnings is expected to be empty.

Returns: MorphoVaultData or None.

property name: str: Vault name.

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

property symbol: str: Vault share token symbol

property underlying_token: eth_defi.token.TokenDetails: Alias for denomination_token()

property vault_contract: web3.contract.contract.Contract: Get vault deployment.

class MorphoV2VaultHistoricalReader

Bases: eth_defi.erc_4626.vault.ERC4626HistoricalReader

Read Morpho V2 vault core data + fees + utilisation.

__init__(vault, stateful)

Parameters

vault (eth_defi.erc_4626.vault.ERC4626Vault) –
stateful (bool) –

construct_core_erc_4626_multicall()

Polling endpoints defined in ERC-4626 spec.

Does not include fee calls which do not have standard

Return type: Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

construct_fee_calls()

Add Morpho V2 fee calls.

Return type: Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

construct_multicalls()

Get the onchain calls that are needed to read the share price.

Return type: Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

construct_utilisation_calls()

Add idle assets call for utilisation calculation.

Morpho V2 uses idle assets pattern: asset().balanceOf(vault)

Return type: Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

dictify_multicall_results(block_number, call_results, allow_failure=True)

Convert batch of multicalls made for this vault to more digestible dict.

Assert that all multicalls succeed

Returns

Dictionary where each multicall is keyed by its EncodedCall.extra_data["function"]

Parameters

block_number (int) –
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –

Return type

dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]

get_warmup_calls()

Yield (function_name, callable, contract_call) tuples for warmup testing.

Each callable should execute a single contract call. If it raises, the function is marked as broken.

The optional contract_call is used for gas estimation to detect expensive calls before executing them. If provided, calls using excessive gas (>1M gas) will be marked as broken without execution.

Override in subclasses to add protocol-specific calls.

Returns: Iterable of (function_name, test_callable, contract_call) tuples. contract_call may be None if gas estimation is not needed.
Return type: Iterable[tuple[str, callable, Any]]

process_core_erc_4626_result(call_by_name)

Decode common ERC-4626 calls.

Parameters: call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –
Return type: tuple

process_fee_result(call_by_name)

Decode Morpho V2 fee data.

Parameters: call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –
Return type: tuple[float, float]

process_result(block_number, timestamp, call_results)

Process the result of mult

Calls are created in construct_multicalls()
This method combines result of this calls to a easy to manage historical record VaultHistoricalRead

Parameters

block_number (int) –
timestamp (datetime.datetime) –
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –

Return type

eth_defi.vault.base.VaultHistoricalRead

process_utilisation_result(call_by_name, total_assets)

Decode Morpho V2 utilisation data.

Utilisation = (totalAssets - idle) / totalAssets

Parameters

call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –
total_assets (Optional[decimal.Decimal]) –

Return type

tuple[decimal.Decimal | None, float | None]

should_skip_call(function_name)

Check if a specific function call should be skipped.

Uses the reader state’s call_status map if available.

Parameters: function_name (str) – The function name to check
Returns: True if the call should be skipped
Return type: bool