VaultBase

Documentation for eth_defi.vault.base.VaultBase Python class.

class VaultBase

Bases: abc.ABC

Base class for vault protocol adapters.

• Allows automated interaction with different vault protocols.

• Contains various abstract methods that the implementation class must override

Supported protocols include

• Lagoon Finance: eth_defi.lagoon.vault.LagoonVault

• Velvet Capital: eth_defi.velvet.vault.VelvetVault

Code exists, but does not confirm the interface yet:

• Enzyme Finance: eth_defi.enzyme.vault.Vault

Vault covered functionality

• Fetching the current balances, deposits or redemptions

  • Either using naive polling approach with fetch_portfolio()

  • Listen to vault events for deposits and redemptions using get_flow_manager()

• Get vault information with fetch_info()

  • No standardised data structures or functions yet

• Build a swap through a vault

  • No standardised data structure yet

• Update vault position valuations

  • No standardised data structure yet

Integration check list

Integration tests needed for:

• ☑️ read vault core info

• ☑️ read vault investors

• ☑️ read vault share price

• ☑️ read vault share token

• ☑️ read all positions

• ☑️ read NAV

• ☑️ read pending redemptions to know how much USDC we will need for the next settlement cycles

• ☑️ deposit integration test

• ☑️ redemption integration

• ☑️ swap integration test

• ☑️ re-valuation integration test

• ☑️ only asset manager allowed to swap negative test

• ☑️ only valuation commitee allowed to update vault valuations (if applicable)

• ☑️ can redeem if enough USDC to settle

• ☑️ cannot redeem not enough USDC to settle

For code examples see tests/lagoon and tests/velvet on the Github repository.

Parameters

• token_cache –

  Token cache for vault tokens.

  Allows to pass eth_defi.token.TokenDiskCache to speed up operations.

• require_denomination_token –

  If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

  Use for deployment scripts and operational contexts where a missing denomination token is always a hard error.

Attributes summary

address	Vault contract address.
chain_id	Chain this vault is on
denomination_token	Get the token which denominates the vault valuation
deposit_manager	Deposit manager assocaited with this vault
description	Human-readable vault strategy description.
flow_manager	Flow manager associated with this vault
info	Get info dictionary related to this vault deployment.
name	Vault name.
share_token	ERC-20 that presents vault shares.
short_description	One-liner vault summary.
symbol	Vault share token symbol

Methods summary

__init__([token_cache, ...])	param token_cache
fetch_available_liquidity([block_identifier])	Get the amount of denomination token available for immediate withdrawal.
fetch_denomination_token()	Read denomination token from onchain.
fetch_denomination_token_address()	Get the address for the denomination token.
fetch_deposit_closed_reason()	Get human-readable reason why deposits are closed.
fetch_deposit_next_open()	Get when deposits will next be open.
fetch_info()	Read vault parameters from the chain.
fetch_nav()	Fetch the most recent onchain NAV value.
fetch_portfolio(universe[, block_identifier])	Read the current token balances of a vault.
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_share_token()	Read share token details onchain.
fetch_utilisation_percent([block_identifier])	Get the percentage of assets currently lent out.
get_deposit_fee(block_identifier)	Deposit fee is set to zero by default as vaults usually do not have deposit fees.
get_deposit_manager()	Get deposit manager to deposit/redeem from the vault.
get_estimated_lock_up()	What is the estimated lock-up period for this vault.
get_fee_data()	Get fee data structure for this vault.
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 flow manager to read indiviaul settle events.
get_historical_reader(stateful)	Get share price reader to fetch historical returns.
get_link([referral])	Get a link to the vault dashboard on its native site.
get_management_fee(block_identifier)	Get the current management fee as a percent.
get_notes()	Get a human readable message if we know somethign special is going on with this vault.
get_performance_fee(block_identifier)	Get the current performance fee as a percent.
get_protocol_name()	Return the name of the vault protocol.
get_risk()	Get risk profile of this vault.
get_spec()
get_withdraw_fee(block_identifier)	Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.
has_block_range_event_support()	Does this vault support block range-based event queries for deposits and redemptions.
has_custom_fees()	Does this vault have custom fee structure reading methods.
has_deposit_distribution_to_all_positions()	Deposits go automatically to all open positions.

__init__(token_cache=None, require_denomination_token=False)

Parameters

• token_cache (Optional[dict]) –

  Token cache for vault tokens.

  Allows to pass eth_defi.token.TokenDiskCache to speed up operations.

• require_denomination_token (bool) –

  If True, accessing denomination_token will raise RuntimeError when the on-chain lookup returns None.

  Use for deployment scripts and operational contexts where a missing denomination token is always a hard error.

abstract property address: eth_typing.evm.HexAddress

Vault contract address.

• Often vault protocols need multiple contracts per vault, so what this function returns depends on the protocol

abstract 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

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]

abstract fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type

eth_defi.token.TokenDetails

fetch_denomination_token_address()

Get the address for the denomination token.

Triggers RCP call

Return type

eth_typing.evm.HexAddress

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]

abstract fetch_info()

Read vault parameters from the chain.

Use info() property for cached access.

Return type

eth_defi.vault.base.VaultInfo

abstract fetch_nav()

Fetch the most recent onchain NAV value.

Returns

Vault NAV, denominated in denomination_token()

Return type

decimal.Decimal

abstract fetch_portfolio(universe, block_identifier=None)

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, int]]) –

Return type

eth_defi.vault.base.VaultPortfolio

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]

abstract fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

Return type

eth_defi.token.TokenDetails

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_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]

abstract get_deposit_manager()

Get deposit manager to deposit/redeem from the vault.

Return type

eth_defi.vault.deposit_redeem.VaultDepositManager

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_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 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]

abstract 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

abstract get_historical_reader(stateful)

Get share price reader to fetch historical returns.

Parameters

stateful (bool) – If True, use a stateful reading strategy.

Returns

None if unsupported

Return type

eth_defi.vault.base.VaultHistoricalReader

get_link(referral=None)

Get a link to the vault dashboard on its native site.

• By default, give RouteScan link

Parameters

referral (Optional[str]) – Optional referral code to append to the URL.

Returns

URL string

Return type

str

get_management_fee(block_identifier)

Get the current management fee as a percent.

Internal: Use get_fee_data().

Returns

0.1 = 10%

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

get_notes()

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

Return type

Optional[str]

get_performance_fee(block_identifier)

Get the current performance fee as a percent.

Internal: Use get_fee_data().

Returns

0.1 = 10%

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

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

abstract 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

Return type

bool

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

abstract 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

Return type

bool

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

abstract 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

abstract property symbol: str

Vault share token symbol