IPORVault

Documentation for eth_defi.ipor.vault.IPORVault Python class.

class IPORVault

Bases: eth_defi.erc_4626.vault.ERC4626Vault

IPOR vault support.

Add specialised reader with fees support
See Fusion vaults here
Example contract and ` Example vault <https://app.ipor.io/fusion/base/0x45aa96f0b3188d47a1dafdbefce1db6b37f58216>`__
IPOR custom error codes like 0x1425ea42 ABI-decoded

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.

Attributes summary

`access_manager`	Get IPOR's contract managing vault access rules.
`address`	Get the vault smart 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.
`erc_7540`	Is this ERC-7540 vault with asynchronous deposits.
`flow_manager`	Flow manager associated with this vault
`info`	Get info dictionary related to this vault deployment.
`name`	Vault name.
`plasma_vault`	Get IPOR's proprietary PlasmaVault implementation.
`share_token`	ERC-20 that presents vault shares.
`short_description`	One-liner vault summary.
`symbol`	Vault share token symbol
`underlying_token`	Alias for `denomination_token()`
`vault_address`
`vault_address_checksumless`
`vault_contract`	Get vault deployment.

Methods summary

`__init__`(web3, spec[, token_cache, ...])	param web3
`can_check_deposit`()	Check if maxDeposit(address(0)) can be used to check global deposit availability.
`can_check_redeem`()	IPOR supports address(0) checks for redemption availability.
`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`()	Check maxDeposit to determine if deposits are closed.
`fetch_deposit_next_open`()	Deposit timing is unpredictable - utilisation-based.
`fetch_info`()	Use `info()` property for cached access.
`fetch_nav`([block_identifier])	Fetch the most recent onchain NAV value.
`fetch_portfolio`(universe[, ...])	Read the current token balances of a vault.
`fetch_redemption_closed_reason`()	Check maxRedeem to determine if redemptions are closed.
`fetch_redemption_next_open`()	Withdrawal timing is unpredictable - utilisation-based.
`fetch_share_price`(block_identifier)	Get the current share price.
`fetch_share_token`()	Read share token details onchain.
`fetch_share_token_address`([block_identifier])	Get share token of this vault.
`fetch_total_assets`(block_identifier)	What is the total NAV of the vault.
`fetch_total_supply`(block_identifier)	What is the current outstanding shares.
`fetch_utilisation_percent`([block_identifier])	Get the percentage of assets currently allocated to strategies.
`fetch_vault_info`()	Get all information we can extract from the vault smart contracts.
`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`()	ERC-4626 vaults do not have a lock up by fault.
`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 performancae fee as a percent.
`get_protocol_name`()	Return the name of the vault protocol.
`get_redemption_delay`()	Get the redemption delay for the vault.
`get_redemption_delay_over`(address)	Get the redemption delay left for an account.
`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.
`is_valid`()	Check if this vault is valid.

property plasma_vault: web3.contract.contract.Contract: Get IPOR’s proprietary PlasmaVault implementation.

property access_manager: web3.contract.contract.Contract | None

Get IPOR’s contract managing vault access rules.

Redemption delay, and such

get_historical_reader(stateful)

Get share price reader to fetch historical returns.

Parameters: stateful – If True, use a stateful reading strategy.
Returns: None if unsupported
Return type: eth_defi.vault.base.VaultHistoricalReader

get_management_fee(block_identifier)

Get the current management fee as a percent.

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, hexbytes.main.HexBytes, int]) –
Return type: float

get_performance_fee(block_identifier)

Get the current performancae fee as a percent.

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, hexbytes.main.HexBytes, int]) –
Return type: float

get_redemption_delay()

Get the redemption delay for the vault.

Returns: Redemption delay as a timedelta.
Return type: datetime.timedelta | None

get_redemption_delay_over(address)

Get the redemption delay left for an account.

Returns: When the account can redeem.
Parameters: address (str) –
Return type: datetime.datetime | None

get_estimated_lock_up()

ERC-4626 vaults do not have a lock up by fault.

Note

Because of so many protocol specific lockups, this must be explicitly set to zero.

Return type: datetime.timedelta | None

get_link(referral=None)

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

By default, give RouteScan link

Parameters: referral (str | None) – Optional referral code to append to the URL.
Returns: URL string
Return type: str

fetch_deposit_closed_reason()

Check maxDeposit to determine if deposits are closed.

IPOR vaults are utilisation-based.

Return type: str | None

fetch_redemption_closed_reason()

Check maxRedeem to determine if redemptions are closed.

IPOR vaults are utilisation-based.

Return type: str | None

fetch_deposit_next_open()

Deposit timing is unpredictable - utilisation-based.

Return type: datetime.datetime | None

fetch_redemption_next_open()

Withdrawal timing is unpredictable - utilisation-based.

Return type: datetime.datetime | None

can_check_redeem()

IPOR supports address(0) checks for redemption availability.

maxRedeem(address(0)) returns 0 when redemptions are blocked due to utilisation

Return type: bool

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, hexbytes.main.HexBytes, int]) – Block to query. Defaults to “latest”.
Returns: Amount in denomination token units (human-readable Decimal).
Return type: decimal.Decimal | None

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, hexbytes.main.HexBytes, int]) – Block to query. Defaults to “latest”.
Returns: Utilisation as float between 0.0 and 1.0 (0% to 100%).
Return type: float | None

__init__(web3, spec, token_cache=None, features=None, default_block_identifier=None)

Parameters

web3 (web3.main.Web3) – Connection we bind this instance to
spec (eth_defi.vault.base.VaultSpec) – Chain, address tuple
token_cache (dict | None) –
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 (set[eth_defi.erc_4626.core.ERC4626Feature] | None) – 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.

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

property chain_id: int: Chain this vault is on

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

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

property description: str | None

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_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type: eth_defi.token.TokenDetails | None

fetch_denomination_token_address()

Get the address for the denomination token.

Triggers RCP call

Return type: Optional[eth_typing.evm.HexAddress]

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

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: 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

decimal.Decimal | None

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_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_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: float | None

get_deposit_manager()

Get deposit manager to deposit/redeem from the vault.

Return type: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

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: eth_defi.vault.fee.VaultFeeMode | 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_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_notes()

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

Return type: str | None

get_protocol_name()

Return the name of the vault protocol.

Return type: str

get_risk()

Get risk profile of this vault.

Return type: eth_defi.vault.risk.VaultTechnicalRisk | None

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 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: str | None

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.

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.