vault_street.vault

Documentation for eth_defi.vault_street.vault Python module.

Vault Street primeUSD vault adapter.

Vault Street’s first product, primeUSD, is a permissioned and yield-bearing USDC-denominated token for institutional participants. It is not an ERC-4626 vault: primeUSD supply is ERC-20 totalSupply(), while NAV/share is published by a separate PriceStorage.getPrice() contract.

Documentation: https://docs.vaultstreet.com/overview/primeusd.md
Contracts: https://docs.vaultstreet.com/resources/smart-contracts.md
Token: https://etherscan.io/token/0x7ea76108975ec0998b9bc2db04b4eca986400dd7

Module Attributes

`VAULT_STREET_PERMISSIONED_FLOW_REASON`	Public integration restriction for permissioned primeUSD flows.
`PRIME_USD_PROTOCOL_FEE`	primeUSD protocol fee, accrued daily and deducted from the vault.
`PRIME_USD_PERFORMANCE_FEE`	primeUSD performance fee.

Classes

`VaultStreetVault`	Scan-only adapter for Vault Street's primeUSD token.
`VaultStreetVaultInfo`	Vault Street primeUSD metadata and compatibility settings.

VAULT_STREET_PERMISSIONED_FLOW_REASON = 'Vault Street primeUSD deposits, transfers and redemptions require an approved KYB/KYC allowlist': Public integration restriction for permissioned primeUSD flows.

PRIME_USD_PROTOCOL_FEE: float = 0.005

primeUSD protocol fee, accrued daily and deducted from the vault.

https://app.vaultstreet.com/

PRIME_USD_PERFORMANCE_FEE: float = 0

primeUSD performance fee.

https://app.vaultstreet.com/

class VaultStreetVaultInfo

Bases: eth_defi.vault.base.VaultInfo

Vault Street primeUSD metadata and compatibility settings.

token: eth_typing.evm.HexAddress: ERC-20 primeUSD token address.

chain_id: int: EVM chain id.

denomination_token: eth_typing.evm.HexAddress: USDC denomination token.

price_oracle: eth_typing.evm.HexAddress: Contract publishing fixed-point NAV/share.

request_manager: eth_typing.evm.HexAddress: Contract receiving permissioned deposit and redemption requests.

nav_source: str: NAV source label.

__init__(*args, **kwargs)

__new__(**kwargs)

clear(): Remove all items from the dict.

copy(): Return a shallow copy of the dict.

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items(): Return a set-like object providing a view on the dict’s items.

keys(): Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values(): Return an object providing a view on the dict’s values.

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.

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

first_seen_at_block: Optional[int]

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.

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

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

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

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

User gets shares on deposit and burns them on redemption