VaultStreetVault

Documentation for eth_defi.vault_street.vault.VaultStreetVault Python class.

class VaultStreetVault

Bases: eth_defi.vault.base.VaultBase

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

`address`	Return the primeUSD ERC-20 token address.
`chain_id`	Return Ethereum mainnet chain id.
`denomination_token`	Get the token which denominates the vault valuation
`deposit_manager`	Deposit manager assocaited with this vault
`description`	Return the product's strategy description.
`flow_manager`	Flow manager associated with this vault
`info`	Get info dictionary related to this vault deployment.
`manager_name`	Return the Vault Street platform name.
`name`	Return the primeUSD token name.
`price_oracle_contract`	Return the Vault Street NAV/share oracle contract.
`share_token`	ERC-20 that presents vault shares.
`short_description`	Return a concise product summary.
`symbol`	Return the primeUSD token symbol.
`vault_address`	Return the primary vault identifier expected by shared scanner code.
`whitelist_notes`	Optional 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])	Get the amount of denomination token available for immediate withdrawal.
`fetch_denomination_token`()	Fetch USDC denomination token metadata.
`fetch_denomination_token_address`()	Return native Ethereum USDC as the primeUSD denomination token.
`fetch_deposit_closed_reason`()	Explain why generic deposits are unavailable.
`fetch_deposit_next_open`()	Get when deposits will next be open.
`fetch_info`()	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.
`fetch_redemption_closed_reason`()	Explain why generic redemptions are unavailable.
`fetch_redemption_next_open`()	Get when withdrawals/redemptions will next be open.
`fetch_scan_record_extra_data`()	Return primeUSD scan diagnostics.
`fetch_share_price`([block_identifier])	Fetch primeUSD NAV per token from the PriceStorage oracle.
`fetch_share_token`()	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])	Get the percentage of assets currently lent out.
`get_deposit_fee`(block_identifier)	Return unknown deposit fee.
`get_deposit_manager`()	Raise because permissioned Vault Street transaction support is unavailable.
`get_deposit_manager_capability`()	Return static public transaction-adapter support, if any.
`get_estimated_lock_up`()	What is the estimated lock-up period for this vault.
`get_fee_data`()	Return disclosed primeUSD fee metadata.
`get_fee_mode`()	Get how this vault accounts its fees.
`get_flags`()	Get various vault state flags from the smart contract.
`get_flow_manager`()	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_notes`()	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.
`get_protocol_name`()	Return the name of the vault protocol.
`get_risk`()	Get risk profile of this vault.
`get_share_price_source`()	Return the primeUSD NAV source classification.
`get_spec`()
`get_whitelist_notes`()	Return an export caveat for the vault-wide whitelist status.
`get_withdraw_fee`(block_identifier)	Return unknown redemption fee.
`has_block_range_event_support`()	Return whether standard flow-event accounting is available.
`has_custom_fees`()	Does this vault have fees outside the shared fee model.
`has_deposit_distribution_to_all_positions`()	Return whether deposits are distributed to visible positions.
`is_account_whitelisted`(address)	Determine whether an account has completed the vault's KYC policy.
`is_whitelisted_deposit`()	Determine whether deposits require KYC or identity approval.

__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: 1 for 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.

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 historical scanner compatibility.
Returns: primeUSD address.
Return type: eth_typing.evm.HexAddress

fetch_share_token()

Fetch primeUSD ERC-20 metadata.

Returns: primeUSD token details.
Return type: eth_defi.token.TokenDetails

fetch_denomination_token_address()

Return native Ethereum USDC as the primeUSD denomination token.

Returns: USDC ERC-20 address.
Return type: eth_typing.evm.HexAddress

fetch_denomination_token()

Fetch USDC denomination token metadata.

Returns: Ethereum USDC token details.
Return type: eth_defi.token.TokenDetails

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: decimal.Decimal

get_share_price_source()

Return the primeUSD NAV source classification.

The adapter reads the deployed PriceStorage oracle at the requested block.

Returns: Smart-contract state source.
Return type: eth_defi.vault.price_source.PriceSource

fetch_share_price(block_identifier='latest')

Fetch primeUSD NAV per token from the PriceStorage oracle.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Historical block number or block tag.
Returns: USDC NAV per primeUSD.
Return type: decimal.Decimal

fetch_total_supply(block_identifier='latest')

Fetch total outstanding primeUSD supply.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Historical block number or block tag.
Returns: Human-readable primeUSD supply.
Return type: decimal.Decimal

fetch_total_assets(block_identifier='latest')

Fetch primeUSD TVL from supply multiplied by NAV/share.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Historical block number or block tag.
Returns: Total USDC NAV.
Return type: decimal.Decimal

fetch_nav(block_identifier='latest')

Fetch primeUSD total NAV.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Historical block number or block tag.
Returns: Total USDC NAV.
Return type: decimal.Decimal

fetch_info()

Return Vault Street contract metadata.

Returns: primeUSD token, oracle and request-manager information.
Return type: eth_defi.vault_street.vault.VaultStreetVaultInfo

fetch_scan_record_extra_data()

Return primeUSD scan diagnostics.

Returns: Price-source and permissioned-flow fields.
Return type: dict[str, object]

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

eth_defi.vault.base.VaultPortfolio

has_block_range_event_support()

Return whether standard flow-event accounting is available.

Returns: False because primeUSD uses a separate request manager.
Return type: bool

has_deposit_distribution_to_all_positions()

Return whether deposits are distributed to visible positions.

Returns: False because positions are not exposed by this adapter.
Return type: bool

get_flow_manager()

Raise because Vault Street request-flow accounting is unsupported.

Raises: NotImplementedError – Always.
Return type: eth_defi.vault.base.VaultFlowManager

get_deposit_manager()

Raise because permissioned Vault Street transaction support is unavailable.

Raises: NotImplementedError – Always.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManager

fetch_deposit_closed_reason()

Explain why generic deposits are unavailable.

Returns: Institutional allowlist requirement.
Return type: str

fetch_redemption_closed_reason()

Explain why generic redemptions are unavailable.

Returns: Institutional allowlist requirement.
Return type: str

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: eth_defi.vault.base.VaultHistoricalReader

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: Optional[float]

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: 0 because the product page lists no performance fee.
Return type: Optional[float]

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: None because the permissioned request manager has no public fee accessor.
Return type: Optional[float]

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: None because the permissioned request manager has no public fee accessor.
Return type: Optional[float]

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: eth_defi.vault.fee.FeeData

get_link(referral=None)

Return Vault Street’s product page.

Parameters: referral (Optional[str]) – Ignored because the product URL has no referral parameter.
Returns: Vault Street primeUSD documentation page.
Return type: str

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

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]

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]

fetch_minimum_deposit(block_identifier='latest')

Fetch a source-proven minimum deposit in decimal token units.

A None result 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 None when unknown.
Return type: Optional[decimal.Decimal]

fetch_minimum_redemption(block_identifier='latest')

Fetch a source-proven redemption minimum in decimal share units.

A None result 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 None when unknown.
Return type: Optional[decimal.Decimal]

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]

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_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. None is therefore the safe default for unknown and protocol-specific vaults.

Returns: Adapter-specific capability object, or None when 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: Optional[datetime.timedelta]

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]

get_notes()

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

Return type: Optional[str]

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

Returns: Export note, or None when the classification needs no caveat.
Return type: Optional[str]

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 True merely because a vault implements custom accessors for ordinary management, performance, deposit, or withdraw fees. Return True only when some vault fee cannot be reflected in those standard fields as a fee-like value.

Returns: True if the vault has fees outside the shared fee model.
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

is_account_whitelisted(address)

Determine whether an account has completed the vault’s KYC policy.

The result concerns KYC or manual identity-approval 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: True when the account has the required KYC/identity approval.
Raises: NotImplementedError – If the adapter cannot safely query account membership.
Return type: bool

is_whitelisted_deposit()

Determine whether deposits require KYC or identity approval.

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_notes so consumers can distinguish it from a source-proven result. True means the vault requires KYC or comparable manual identity approval; False means its policy is permissionless. An open date, lock-up, epoch, pause, cap, token balance, or other non-identity 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.

Returns: True when deposits require KYC/identity approval and False when they do not.
Raises: NotImplementedError – If the adapter cannot safely determine the policy.
Return type: bool

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

User gets shares on deposit and burns them on redemption