IPORVault
Documentation for eth_defi.ipor.vault.IPORVault Python class.
- class IPORVault
Bases:
eth_defi.erc_4626.vault.ERC4626VaultIPOR vault support.
Add specialised reader with fees support
Example contract and ` Example vault <https://app.ipor.io/fusion/base/0x45aa96f0b3188d47a1dafdbefce1db6b37f58216>`__
IPOR custom error codes like 0x1425ea42 ABI-decoded
IPOR Fusion uses
internalised_minting. Both the management fee and the performance fee are realised by minting new vault shares to dedicated technical holding accounts. Fees are therefore paid by existing share holders through dilution — the share price itself is never rewritten, and investors do not pay any explicit fee at deposit or redemption.Fee caps (from
PlasmaVaultLib.sol):Management fee: up to 5% per year on assets under management (
MANAGEMENT_MAX_FEE_IN_PERCENTAGE = 500, 2-decimal precision).Performance fee: up to 50% on gains above a high-water mark (
PERFORMANCE_MAX_FEE_IN_PERCENTAGE = 5000).
Share-minting mechanism (
contracts/vaults/PlasmaVault.sol):Every vault operation (deposit, mint, withdraw, redeem, execute, updateMarketsBalances) runs through fee hooks that call
_realizeManagementFee()and_addPerformanceFee()(see call sites at lines 417, 451, 677, 738, 758, 1258, 1275, 1364)._realizeManagementFee()at line 1413 — NatSpec: “Realizes management fees by minting shares to fee recipient”. Time-based accrual ongrossTotalAssetsis converted to shares viaconvertToShares()and those shares are minted directly toMANAGEMENT_FEE_ACCOUNT:_mint(recipient, unrealizedFeeInShares); // line 1437
The management-fee timestamp is only updated after a successful mint (IL-6959 fix) to prevent fee suppression by many small transactions.
_addPerformanceFee()at line 1381 — uses a high-water mark (HWM) model. IftotalAssetsAfter >= totalAssetsBefore, the gain above the HWM is multiplied by the performance-fee rate, converted to shares byPlasmaVaultFeesLib.prepareForAddPerformanceFee()and minted:_mint(recipient, feeShares); // line 1402
Both mint paths temporarily disable
totalSupplyCapvalidation so the fee mint cannot be blocked by the cap. The HWM is stored inHighWaterMarkPerformanceFeeStorageand can be auto-lowered on a configurable update interval (updateIntervalHighWaterMarkPerformanceFee).
Downstream distribution (
contracts/managers/fee/FeeManager.sol):harvestManagementFee()(line 194) andharvestPerformanceFee()(line 247) read the already-minted share balances via:IERC4626(PLASMA_VAULT).balanceOf(MANAGEMENT_FEE_ACCOUNT); IERC4626(PLASMA_VAULT).balanceOf(PERFORMANCE_FEE_ACCOUNT);
_transferDaoFee()(line 636) moves the IPOR DAO share viaPLASMA_VAULT.transferFrom(feeAccount, daoRecipient, amount)(line 650), and_transferRecipientFee()(line 682) distributes the remainder to atomist-defined recipients using the sametransferFrompattern (line 705).FeeAccount(contracts/managers/fee/FeeAccount.sol) is a tiny holding contract that only exposesapproveMaxForFeeManager()so theFeeManagercan pull the pre-minted shares — it never mints or burns anything itself.
Summary of why this is
internalised_mintingand not skimming or externalised:Skimming would transfer underlying assets out of the vault at the moment of profit. IPOR never moves assets for fees — it mints shares.
Externalised fees (e.g. Lagoon) would deduct from the investor at redemption, so the vault share price is fees-gross. IPOR share price is fees-net: the dilution has already happened on-chain by the time
totalAssets()/convertToAssets()are read.The
FeeManageris a distribution layer on top of already-minted fee shares, not a separate fee-collection mechanism.
Optional deposit fee:
FeeManager.setDepositFee()(line 508) allows an atomist to configure an explicit deposit fee with 18-decimal precision. NatSpec says the fee is “deducted from the user’s deposit amount before minting shares”, making it an externalised fee at deposit time. This is a per-vault optional add-on and is orthogonal to the management/performance fee mode.previewDeposit()already returns shares net of this fee.
References:
- 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, useget_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, accessingdenomination_tokenwill raiseRuntimeErrorwhen the on-chain lookup returnsNone.
Attributes summary
access_managerGet IPOR's contract managing vault access rules.
addressGet the vault smart contract address.
chain_idChain this vault is on
denomination_tokenGet the token which denominates the vault valuation
deposit_managerDeposit manager assocaited with this vault
descriptionFull vault strategy description from IPOR's offchain customisation API.
erc_7540Is this ERC-7540 vault with asynchronous deposits.
flow_managerFlow manager associated with this vault
infoGet info dictionary related to this vault deployment.
ipor_metadataOffchain metadata from IPOR's customisation API.
nameVault name.
plasma_vaultGet IPOR's proprietary PlasmaVault implementation.
share_tokenERC-20 that presents vault shares.
short_descriptionShort vault summary derived from the first sentence of the description.
symbolVault share token symbol
underlying_tokenAlias for
denomination_token()vault_addressvault_address_checksumlessvault_contractGet vault deployment.
Methods summary
__init__(web3, spec[, token_cache, ...])- param web3
call_raw_signature(address, function, ...)Call a raw IPOR selector.
can_check_deposit()Check if maxDeposit(address(0)) can be used to check global deposit availability.
can_check_redeem()IPOR maxRedeem check is unreliable, so we skip it.
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
asset()denomination token address of this vault.fetch_deposit_closed_reason()Check maxDeposit to determine if deposits are closed.
fetch_deposit_next_open()Deposit timing is unpredictable - utilisation-based.
fetch_fee_manager(block_identifier)Read the IPOR FeeManager address.
fetch_info()Use
info()property for cached access.fetch_nav([block_identifier])Fetch the most recent onchain NAV value.
fetch_performance_fee_account(block_identifier)Read the IPOR performance fee account address.
fetch_portfolio(universe[, ...])Read the current token balances of a vault.
fetch_redemption_closed_reason()IPOR maxRedeem check is unreliable, so we skip it.
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)Get the current deposit/onboarding fee as a percent.
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 vault flags, auto-flagging vaults missing from IPOR's customisation list.
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 notes for 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.
- __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, useget_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, accessingdenomination_tokenwill raiseRuntimeErrorwhen the on-chain lookup returnsNone.
- property access_manager: Optional[web3.contract.contract.Contract]
Get IPOR’s contract managing vault access rules.
Redemption delay, and such
- property address: eth_typing.evm.HexAddress
Get the vault smart contract address.
- call_raw_signature(address, function, signature, block_identifier)
Call a raw IPOR selector.
IPOR Fusion fee helpers live across PlasmaVault, FeeAccount and FeeManager contracts. Some helper ABIs are not bundled locally, so selector-level reads keep the dependency small.
- Parameters
address (str) – Contract address to call.
function (str) – Human-readable function name for diagnostics.
signature (bytes) – Four-byte selector.
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 read.
- Returns
Raw ABI-encoded result bytes.
- Return type
- 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
- can_check_redeem()
IPOR maxRedeem check is unreliable, so we skip it.
- Return type
- 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
Noneresults 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]
Full vault strategy description from IPOR’s offchain customisation API.
If the vault has a prospectus link, a markdown link is appended to the description text.
- 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, hexbytes.main.HexBytes, int]) – Block to query. Defaults to “latest”.
- Returns
Amount in denomination token units (human-readable Decimal).
- Return type
- fetch_denomination_token()
Read denomination token from onchain.
Use
denomination_token()for cached access.- Return type
- fetch_denomination_token_address()
Get the
asset()denomination token address of this vault.Results are disk-cached per
(chain_id, vault_address)viaeth_defi.erc_4626.vault_tokenwhen the vault was constructed with aeth_defi.token.TokenDiskCacheand no pinneddefault_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
Nonepath taken on revert / broken contract is never cached, matching the behaviour ofeth_defi.vault.base.VaultBase.denomination_token()which explicitly avoids memoisingNoneso transient failures can be retried.To disable the cache, pass
token_cache=None(or any non-TokenDiskCachedict) when constructing the vault, or construct with a pinneddefault_block_identifier.- Returns
Denomination token address, or
Noneif the vault contract is broken and did not return a valid address.- Return type
- fetch_deposit_closed_reason()
Check maxDeposit to determine if deposits are closed.
IPOR vaults are utilisation-based.
- fetch_deposit_next_open()
Deposit timing is unpredictable - utilisation-based.
- Return type
- fetch_fee_manager(block_identifier)
Read the IPOR FeeManager address.
- 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 read.
- Returns
FeeManager address, or
Noneif the fee account is unset.- Return type
- fetch_info()
Use
info()property for cached access.- Returns
See
LagoonVaultInfo- Return type
- 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
- fetch_performance_fee_account(block_identifier)
Read the IPOR performance fee account address.
The performance fee account is a
FeeAccountcontract that exposesFEE_MANAGER(). The FeeManager stores the deposit/onboarding fee.
- 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
- fetch_redemption_closed_reason()
IPOR maxRedeem check is unreliable, so we skip it.
- fetch_redemption_next_open()
Withdrawal timing is unpredictable - utilisation-based.
- Return type
- fetch_share_price(block_identifier)
Get the current share price.
- fetch_share_token()
Read share token details onchain.
Use
share_token()for cached access.- Return type
- 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)viaeth_defi.erc_4626.vault_tokenwhen the vault was constructed with aeth_defi.token.TokenDiskCache. Under normal circumstances theblock_identifierargument 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 toself.vault_addressbut 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-TokenDiskCachedict) when constructing the vault, or construct with a pinneddefault_block_identifierto 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 pinneddefault_block_identifier.- Return type
- 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_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 number to read.
Use web3.eth.block_number for the last block.
- Returns
The vault value in underlyinh token
- Return type
- fetch_total_supply(block_identifier)
What is the current outstanding shares.
Example:
- 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 number to read.
Use web3.eth.block_number for the last block.
- Returns
The vault value in underlyinh token
- Return type
- 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
- fetch_vault_info()
Get all information we can extract from the vault smart contracts.
- Return type
- property flow_manager: eth_defi.vault.base.VaultFlowManager
Flow manager associated with this vault
- get_deposit_fee(block_identifier)
Get the current deposit/onboarding fee as a percent.
IPOR stores this fee in
FeeManager.getDepositFee()using 18-decimal precision where1e18is 100%. PlasmaVaultpreviewDeposit()already returns shares after this fee.
- 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.
Note
Because of so many protocol specific lockups, this must be explicitly set to zero.
- 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_fee_mode()
Get how this vault accounts its fees.
- Return type
- get_flags()
Get vault flags, auto-flagging vaults missing from IPOR’s customisation list.
If the vault has no metadata in the customisation API, it is flagged as
unofficialManual flags from
VAULT_FLAGS_AND_NOTEStake precedence
- Return type
- get_flow_manager()
Get flow manager to read indiviaul settle events.
Only supported if
has_block_range_event_support()is True
- Return type
- 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
- get_link(referral=None)
Get a link to the vault dashboard on its native site.
By default, give RouteScan link
- get_management_fee(block_identifier)
Get the current management fee as a percent.
- get_notes()
Get notes for this vault.
Returns manual notes from the vault flags if set
If vault is missing from IPOR’s customisation list, returns the missing note
Otherwise falls back to the full description
- get_performance_fee(block_identifier)
Get the current performancae fee as a percent.
- get_protocol_name()
Return the name of the vault protocol.
- Return type
- get_redemption_delay()
Get the redemption delay for the vault.
- Returns
Redemption delay as a timedelta.
- Return type
- get_redemption_delay_over(address)
Get the redemption delay left for an account.
- Returns
When the account can redeem.
- Parameters
address (str) –
- Return type
- get_risk()
Get risk profile of this vault.
- Return type
- 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().
- 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
- 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
- property ipor_metadata: Optional[eth_defi.erc_4626.vault_protocol.ipor.offchain_metadata.IPORVaultMetadata]
Offchain metadata from IPOR’s customisation API.
Fetched from
api.ipor.io/fusion/vaults-customization-listCached on first access
Returns None if the vault’s atomist has not set a description
- is_valid()
Check if this vault is valid.
Call a known smart contract function to verify the function exists
- Return type
- property name: str
Vault name.
- property plasma_vault: web3.contract.contract.Contract
Get IPOR’s proprietary PlasmaVault implementation.
- 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]
Short vault summary derived from the first sentence of the description.
- 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.