VaultStreetVault
Documentation for eth_defi.vault_street.vault.VaultStreetVault Python class.
- class VaultStreetVault
Bases:
eth_defi.vault.base.VaultBaseScan-only adapter for Vault Street’s primeUSD token.
The adapter reads primeUSD ERC-20 supply and combines it with the public price oracle to calculate USDC NAV. Public transaction support is excluded because Vault Street applies institutional allowlisting to its request flow.
Create the primeUSD adapter.
- Parameters
web3 – Web3 connection for Ethereum mainnet.
spec – Chain and primeUSD token address.
token_cache – Token metadata cache for ERC-20 reads.
features – Shared pipeline features, expected to include
vault_street_like.default_block_identifier – Accepted for the shared adapter factory. primeUSD token metadata is immutable, so the adapter has no block-pinned metadata reads.
require_denomination_token – Whether a missing denomination token must raise.
Attributes summary
Return the primeUSD ERC-20 token address.
Return Ethereum mainnet chain id.
Get the token which denominates the vault valuation
Deposit manager assocaited with this vault
Return the product's strategy description.
Flow manager associated with this vault
Get info dictionary related to this vault deployment.
Return the Vault Street platform name.
Return the primeUSD token name.
Return the Vault Street NAV/share oracle contract.
ERC-20 that presents vault shares.
Return a concise product summary.
Return the primeUSD token symbol.
synthetic_usd_denominationWhether NAV and historical total_assets already use synthetic USD units.
Return the primary vault identifier expected by shared scanner code.
whitelist_notesOptional qualification for the exported whitelist status.
Methods summary
__init__(web3, spec[, token_cache, ...])Create the primeUSD adapter.
convert_raw_share_price(raw_price)Convert the PriceStorage fixed-point value to USDC per primeUSD.
fetch_available_liquidity([block_identifier])Read the adapter's available denomination-token liquidity.
Fetch USDC denomination token metadata.
Return native Ethereum USDC as the primeUSD denomination token.
Explain why generic deposits are unavailable.
Get when deposits will next be open.
Fetch the current protocol-defined deposit availability.
Return Vault Street contract metadata.
fetch_minimum_deposit([block_identifier])Fetch a source-proven minimum deposit in decimal token units.
fetch_minimum_redemption([block_identifier])Fetch a source-proven redemption minimum in decimal share units.
fetch_nav([block_identifier])Fetch primeUSD total NAV.
fetch_portfolio(universe[, block_identifier])Return no directly observable strategy-token balances.
Explain why generic redemptions are unavailable.
Get when withdrawals/redemptions will next be open.
Return primeUSD scan diagnostics.
fetch_share_price([block_identifier])Fetch primeUSD NAV per token from the PriceStorage oracle.
Fetch primeUSD ERC-20 metadata.
fetch_share_token_address([block_identifier])Return the primeUSD ERC-20 address.
fetch_total_assets([block_identifier])Fetch primeUSD TVL from supply multiplied by NAV/share.
fetch_total_supply([block_identifier])Fetch total outstanding primeUSD supply.
fetch_utilisation_percent([block_identifier])Read the adapter's lending or capital-deployment utilisation.
get_deposit_fee(block_identifier)Return unknown deposit fee.
Raise because permissioned Vault Street transaction support is unavailable.
Return static public transaction-adapter support, if any.
What is the estimated lock-up period for this vault.
Return disclosed primeUSD fee metadata.
Get how this vault accounts its fees.
Get various vault state flags from the smart contract.
Raise because Vault Street request-flow accounting is unsupported.
get_historical_reader(stateful)Create a historical primeUSD reader.
get_link([referral])Return Vault Street's product page.
get_management_fee(block_identifier)Return the disclosed primeUSD protocol fee.
Get a human readable message if we know somethign special is going on with this vault.
get_performance_fee(block_identifier)Return the disclosed primeUSD performance fee.
Return the name of the vault protocol.
get_risk()Get risk profile of this vault.
Return the primeUSD NAV source classification.
get_spec()Get the known investment strategy classifications for this vault.
Return an export caveat for the vault-wide whitelist status.
get_withdraw_fee(block_identifier)Return unknown redemption fee.
Return binding withdrawal timing and optional settlement estimates.
Return whether standard flow-event accounting is available.
Does this vault have fees outside the shared fee model.
Return whether deposits are distributed to visible positions.
is_account_whitelisted(address)Determine whether an account has completed the vault's KYC policy.
Determine whether deposits require pre-approved recipient accounts.
- __init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)
Create the primeUSD adapter.
- Parameters
web3 (web3.main.Web3) – Web3 connection for Ethereum mainnet.
spec (eth_defi.vault.base.VaultSpec) – Chain and primeUSD token address.
token_cache (Optional[dict]) – Token metadata cache for ERC-20 reads.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Shared pipeline features, expected to include
vault_street_like.default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Accepted for the shared adapter factory. primeUSD token metadata is immutable, so the adapter has no block-pinned metadata reads.
require_denomination_token (bool) – Whether a missing denomination token must raise.
- property chain_id: int
Return Ethereum mainnet chain id.
- Returns
1for the primeUSD deployment.
- property address: eth_typing.evm.HexAddress
Return the primeUSD ERC-20 token address.
- Returns
Checksummed primeUSD address.
- property vault_address: eth_typing.evm.HexAddress
Return the primary vault identifier expected by shared scanner code.
- Returns
primeUSD token address.
- property price_oracle_contract: web3.contract.contract.Contract
Return the Vault Street NAV/share oracle contract.
- Returns
Contract exposing
getPrice().
- property name: str
Return the primeUSD token name.
- Returns
ERC-20 token name.
- property symbol: str
Return the primeUSD token symbol.
- Returns
ERC-20 token symbol.
- property description: str
Return the product’s strategy description.
- Returns
Human-readable primeUSD strategy summary.
- property short_description: str
Return a concise product summary.
- Returns
Short primeUSD description.
- property manager_name: str
Return the Vault Street platform name.
- Returns
Product manager display name.
- fetch_share_token_address(block_identifier='latest')
Return the primeUSD ERC-20 address.
- fetch_share_token()
Fetch primeUSD ERC-20 metadata.
- Returns
primeUSD token details.
- Return type
- fetch_denomination_token_address()
Return native Ethereum USDC as the primeUSD denomination token.
- Returns
USDC ERC-20 address.
- Return type
- fetch_denomination_token()
Fetch USDC denomination token metadata.
- Returns
Ethereum USDC token details.
- Return type
- convert_raw_share_price(raw_price)
Convert the PriceStorage fixed-point value to USDC per primeUSD.
- Parameters
raw_price (int) – Raw
getPrice()value with eight decimal places.- Returns
USDC NAV per one human-readable primeUSD token.
- Return type
- get_share_price_source()
Return the primeUSD NAV source classification.
The adapter reads the deployed
PriceStorageoracle at the requested block.- Returns
Smart-contract state source.
- Return type
- fetch_share_price(block_identifier='latest')
Fetch primeUSD NAV per token from the PriceStorage oracle.
- fetch_total_supply(block_identifier='latest')
Fetch total outstanding primeUSD supply.
- fetch_total_assets(block_identifier='latest')
Fetch primeUSD TVL from supply multiplied by NAV/share.
- fetch_nav(block_identifier='latest')
Fetch primeUSD total NAV.
- fetch_info()
Return Vault Street contract metadata.
- Returns
primeUSD token, oracle and request-manager information.
- Return type
- fetch_scan_record_extra_data()
Return primeUSD scan diagnostics.
- fetch_portfolio(universe, block_identifier=None)
Return no directly observable strategy-token balances.
primeUSD’s collateral and deployed positions are not represented as token balances held at the primeUSD ERC-20 address.
- Parameters
universe (eth_defi.vault.base.TradingUniverse) – Ignored because no on-chain portfolio is exposed by this product.
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Ignored because no on-chain portfolio is exposed by this product.
- Returns
Empty spot portfolio.
- Return type
- has_block_range_event_support()
Return whether standard flow-event accounting is available.
- Returns
Falsebecause primeUSD uses a separate request manager.- Return type
- has_deposit_distribution_to_all_positions()
Return whether deposits are distributed to visible positions.
- Returns
Falsebecause positions are not exposed by this adapter.- Return type
- get_flow_manager()
Raise because Vault Street request-flow accounting is unsupported.
- Raises
NotImplementedError – Always.
- Return type
- get_deposit_manager()
Raise because permissioned Vault Street transaction support is unavailable.
- Raises
NotImplementedError – Always.
- Return type
- fetch_deposit_closed_reason()
Explain why generic deposits are unavailable.
- Returns
Institutional allowlist requirement.
- Return type
- fetch_redemption_closed_reason()
Explain why generic redemptions are unavailable.
- Returns
Institutional allowlist requirement.
- Return type
- get_historical_reader(stateful)
Create a historical primeUSD reader.
- Parameters
stateful (bool) – Accepted for shared scanner compatibility.
- Returns
Historical reader using supply and PriceStorage oracle calls.
- Return type
- get_management_fee(block_identifier)
Return the disclosed primeUSD protocol fee.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored because the fee is currently static product metadata.
- Returns
Daily-accrued
0.5%protocol fee represented in the management-like fee field.- Return type
- get_performance_fee(block_identifier)
Return the disclosed primeUSD performance fee.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored because the fee is currently static product metadata.
- Returns
0because the product page lists no performance fee.- Return type
- get_deposit_fee(block_identifier)
Return unknown deposit fee.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Accepted for shared fee API compatibility.
- Returns
Nonebecause the permissioned request manager has no public fee accessor.- Return type
- get_withdraw_fee(block_identifier)
Return unknown redemption fee.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Accepted for shared fee API compatibility.
- Returns
Nonebecause the permissioned request manager has no public fee accessor.- Return type
- get_fee_data()
Return disclosed primeUSD fee metadata.
The product page states that the protocol fee accrues daily and is deducted from the vault. Model it as an internalised management-like fee. It does not disclose explicit entry or redemption fees.
- Returns
Fee data with disclosed protocol and performance fees.
- Return type
- get_link(referral=None)
Return Vault Street’s product page.
- 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
- fetch_available_liquidity(block_identifier='latest')
Read the adapter’s available denomination-token liquidity.
Single-market adapters report market liquidity. Multi-market adapters such as Morpho and IPOR currently report idle vault assets, which can understate redeemable liquidity in their underlying markets. A user’s withdrawal can also be limited by share ownership or protocol restrictions. Non-lending adapters should leave this method unimplemented.
maxRedeem(address(0))cannot measure market-wide liquidity because ERC-4626 caps redemptions by the owner’s share balance. The zero address normally holds no shares, so a zero result says nothing about 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
- 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
- fetch_deposit_open()
Fetch the current protocol-defined deposit availability.
This is deliberately a tri-state value.
TrueandFalsemean that the adapter read an authoritative vault-wide state;Nonemeans that the generic adapter cannot safely determine the state. It is separate fromfetch_deposit_closed_reason(), because an absent human-readable reason does not prove that deposits are open.
- fetch_minimum_deposit(block_identifier='latest')
Fetch a source-proven minimum deposit in decimal token units.
A
Noneresult means this adapter does not expose a known minimum; it does not prove the protocol accepts arbitrarily small deposits. A zero result means the adapter positively established that the vault has no minimum deposit.- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the protocol configuration.
- Returns
Decimal denomination-token minimum, or
Nonewhen unknown.- Return type
- fetch_minimum_redemption(block_identifier='latest')
Fetch a source-proven redemption minimum in decimal share units.
A
Noneresult means this adapter does not expose a known minimum; it does not prove the protocol accepts arbitrarily small redemptions. A zero result means the adapter positively established that the vault has no minimum redemption.- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block at which to read the protocol configuration.
- Returns
Decimal vault-share minimum, or
Nonewhen unknown.- Return type
- 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
- fetch_utilisation_percent(block_identifier='latest')
Read the adapter’s lending or capital-deployment utilisation.
Single-market adapters measure borrower utilisation. Multi-market adapters such as Morpho and IPOR currently measure allocation outside the vault, rather than aggregate utilisation by underlying borrowers. Non-lending adapters 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
- property flow_manager: eth_defi.vault.base.VaultFlowManager
Flow manager associated with this vault
- get_deposit_manager_capability()
Return static public transaction-adapter support, if any.
This method deliberately does not attempt to construct a manager or query live pause, cap, epoch, balance, allow-list, or liquidity state. Adapters opt in only after their complete deposit and redemption lifecycles have focused coverage.
Noneis therefore the safe default for unknown and protocol-specific vaults.- Returns
Adapter-specific capability object, or
Nonewhen unsupported.- Return type
Optional[eth_defi.vault.deposit_redeem.VaultDepositManagerCapability]
- get_estimated_lock_up()
What is the estimated lock-up period for this vault.
- Returns
None if not know
- Return type
- get_fee_mode()
Get how this vault accounts its fees.
- Return type
- 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
The vault metadata scan stores this result as
_flagsinvault-metadata-db.pickle.top_vaults_by_chain.jsonis generated from those stored values throughscripts/erc-4626/vault-analysis-json.py/eth_defi.vault.top_vaults_json.After editing manual flags in
eth_defi.vault.flag, rerun the vault metadata scan and top-vault JSON post-processing. Regenerating the JSON from an old metadata database will not pick up new manual flags.- Returns
Flag set.
Do not modify in place.
- Return type
- get_notes()
Get a human readable message if we know somethign special is going on with this vault.
- get_protocol_name()
Return the name of the vault protocol.
- Return type
- get_risk()
Get risk profile of this vault.
- Return type
- get_strategy_tags()
Get the known investment strategy classifications for this vault.
Override this method when an adapter or its metadata source can determine the vault’s strategy.
Nonemeans the strategy information is missing or has not yet been classified; it is distinct from an empty set, which would mean the strategy was evaluated but did not match any available tag. Maintained mappings normally omit an unclassified address; useStrategyTag.unknownonly when research establishes that the strategy itself is unknown.- Returns
Strategy tag set, or
Nonewhen the information is missing.- Return type
- get_whitelist_notes()
Return an export caveat for the vault-wide whitelist status.
Adapters may attach a concise, stable explanation when a classification is an explicitly requested operating assumption or excludes an integration-specific permission mechanism. The note describes the policy classification only; it must not be used to report temporary deposit availability.
- get_withdrawal_period()
Return binding withdrawal timing and optional settlement estimates.
Unlike
get_estimated_lock_up(), this reports the redemption lifecycle after a user submits a valid withdrawal request. Adapters usemin_periodandmax_periodonly for a binding smart-contract timing rule. An adapter may instead return a non-bindingestimated_settlementfor backtesting an offchain operating cadence or redemption wait; that estimate never establishes claimability and does not require a synthetic timing bound.- Returns
Withdrawal period details, or
Nonewhen unavailable.- Return type
- has_custom_fees()
Does this vault have fees outside the shared fee model.
Custom fees cause risk in vault comparison because the shared management/performance/deposit/withdraw fee fields cannot describe the full fee structure.
Do not return
Truemerely because a vault implements custom accessors for ordinary management, performance, deposit, or withdraw fees. ReturnTrueonly when some vault fee cannot be reflected in those standard fields as a fee-like value.- Returns
Trueif the vault has fees outside the shared fee model.- Return type
- 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_account_whitelisted(address)
Determine whether an account has completed the vault’s KYC policy.
The result concerns KYC, manual identity approval, or recipient allowlist membership only. A protocol may still require scheduling, a token balance, an allowance, available capacity, or an open epoch before a deposit can be submitted. Callers must use the relevant deposit manager pre-flight before broadcasting a transaction.
- Parameters
address (eth_typing.evm.HexAddress) – Account whose deposit-policy membership is queried.
- Returns
Truewhen the account has the required pre-approval.- Raises
NotImplementedError – If the adapter cannot safely query account membership.
- Return type
- is_whitelisted_deposit()
Determine whether deposits require pre-approved recipient accounts.
Protocol adapters override this predicate only when the deployed contract version has verified implementation source or a canonical application ABI that proves a reliable vault-wide policy read. An explicitly documented operating assumption may also override it, but must set
whitelist_notesso consumers can distinguish it from a source-proven result.Truemeans the vault requires KYC, manual identity approval, or a source-proven recipient allowlist;Falsemeans its policy is permissionless. An open date, lock-up, epoch, pause, cap, token balance, or other runtime eligibility condition must not affect the result. A source-proven override requires a fixed-block adapter test for every supported implementation generation. An operating assumption requires a unit test that asserts both its classification and its caveat. This is independent of a caller’s current balance, allowance, pause state, capacity, and request lifecycle.Inspect every supported deployment generation for optional account gates. A public app listing or one permissionless example must not become a protocol-wide
Falsedefault: Upshift’s USPC deployment configures a sender allow-list while other Upshift deployments do not. Keep account and accepted-token allow-lists separate. Permissionless strategy shortlists exclude aTrueresult even if one particular custody account is admitted. Repairs to this accessor need a numbered migration for the persisted_deposit_permissionfield and normal export publication; changing the adapter alone leaves stale labels.- Returns
Truewhen deposits require account pre-approval andFalsewhen they do not.- Raises
NotImplementedError – If the adapter cannot safely determine the policy.
- 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