VaultBase
Documentation for eth_defi.vault.base.VaultBase Python class.
- class VaultBase
Bases:
abc.ABCBase 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.LagoonVaultVelvet 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
- Get vault information with
- 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.TokenDiskCacheto speed up operations.
Attributes summary
Vault contract address.
Chain this vault is on
Get the token which denominates the vault valuation
Deposit manager assocaited with this vault
Flow manager associated with this vault
Get info dictionary related to this vault deployment.
Vault name.
ERC-20 that presents vault shares.
Vault share token symbol
Block number hint when this vault was deployed.
Methods summary
__init__([token_cache])- param token_cache
Read denomination token from onchain.
Get the address for the denomination token.
Get human-readable reason why deposits are closed.
Get when deposits will next be open.
Read vault parameters from the chain.
Fetch the most recent onchain NAV value.
fetch_portfolio(universe[, block_identifier])Read the current token balances of a vault.
Get human-readable reason why redemptions are closed.
Get when withdrawals/redemptions will next be open.
Read share token details onchain.
get_deposit_fee(block_identifier)Deposit fee is set to zero by default as vaults usually do not have deposit fees.
Get deposit manager to deposit/redeem from the vault.
What is the estimated lock-up period for this vault.
Get fee data structure for this vault.
Get how this vault accounts its fees.
Get various vault state flags from the smart contract.
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 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.
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.
Does this vault support block range-based event queries for deposits and redemptions.
Does this vault have custom fee structure reading methods.
Deposits go automatically to all open positions.
- __init__(token_cache=None)
- Parameters
token_cache (dict | None) –
Token cache for vault tokens.
Allows to pass
eth_defi.token.TokenDiskCacheto speed up operations.
- first_seen_at_block: int | None
Block number hint when this vault was deployed.
Must be set externally, as because of shitty Ethereum RPC we cannot query this. Allows us to avoid unnecessary work when scanning historical price data.
- abstract property chain_id: int
Chain this vault is on
- 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 name: str
Vault name.
- abstract property symbol: str
Vault share token symbol
- property flow_manager: eth_defi.vault.base.VaultFlowManager
Flow manager associated with this vault
- property deposit_manager: eth_defi.vault.deposit_redeem.VaultDepositManager
Deposit manager assocaited with this vault
- 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
- 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
- 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
- abstract fetch_info()
Read vault parameters from the chain.
Use
info()property for cached access.- Return type
- abstract get_flow_manager()
Get flow manager to read indiviaul settle events.
Only supported if
has_block_range_event_support()is True
- Return type
- abstract get_deposit_manager()
Get deposit manager to deposit/redeem from the vault.
- 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
- fetch_denomination_token_address()
Get the address for the denomination token.
Triggers RCP call
- Return type
- abstract fetch_denomination_token()
Read denomination token from onchain.
Use
denomination_token()for cached access.- Return type
- abstract fetch_nav()
Fetch the most recent onchain NAV value.
- Returns
Vault NAV, denominated in
denomination_token()- Return type
- property denomination_token: eth_defi.token.TokenDetails | None
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
- abstract fetch_share_token()
Read share token details onchain.
Use
share_token()for cached access.- Return type
- property share_token: eth_defi.token.TokenDetails
ERC-20 that presents vault shares.
User gets shares on deposit and burns them on redemption
- 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
- get_protocol_name()
Return the name of the vault protocol.
- Return type
- get_management_fee(block_identifier)
Get the current management fee as a percent.
Internal: Use
get_fee_data().
- get_performance_fee(block_identifier)
Get the current performance fee as a percent.
Internal: Use
get_fee_data().
- 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
- 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().
- 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().
- get_risk()
Get risk profile of this vault.
- Return type
- get_fee_mode()
Get how this vault accounts its fees.
- Return type
- 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
- get_estimated_lock_up()
What is the estimated lock-up period for this vault.
- Returns
None if not know
- Return type
datetime.timedelta | None
- 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
str | None
- 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
str | None
- 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
datetime.datetime | None
- 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
datetime.datetime | None
- 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
str | None