SuperstateVault
Documentation for eth_defi.tokenised_fund.superstate.vault.SuperstateVault Python class.
- class SuperstateVault
Bases:
eth_defi.vault.base.VaultBaseScan-only adapter for reviewed Superstate tokenised fund shares.
The adapter deliberately has no deposit, redemption or flow manager. The USTB contract includes issuer-specific subscription and redemption paths, but certifying public use would require a complete eligibility-aware, funded lifecycle test against the issuer systems.
Create a Superstate fund adapter.
- Parameters
web3 – Web3 connection for the product chain.
spec – Chain and reviewed fund-token address.
token_cache – Shared ERC-20 metadata cache.
features – Shared classification flags.
default_block_identifier – Default block for direct metadata reads.
require_denomination_token – Retained for
VaultBasecompatibility.
Attributes summary
Return the checksum fund-token address.
Return the product chain id.
chainlink_price_selectorGet the token which denominates the vault valuation
Deposit manager assocaited with this vault
Return a general product description.
Flow manager associated with this vault
Get info dictionary related to this vault deployment.
Return the issuer platform used for curator attribution.
Return the issuer's ERC-20 name.
ERC-20 that presents vault shares.
Return a compact product description.
Return the issuer's ERC-20 symbol.
Return scanner-compatible alias for the token address.
Methods summary
__init__(web3, spec[, token_cache, ...])Create a Superstate fund adapter.
convert_oracle_price(raw_price)Convert reviewed USTB oracle units to USD/share.
fetch_available_liquidity([block_identifier])Get the amount of denomination token available for immediate withdrawal.
Return no ERC-20 denomination metadata.
Return no ERC-20 denomination token.
Return the reason public USTB subscription is unavailable.
Get when deposits will next be open.
Return Superstate scan metadata.
fetch_nav([block_identifier])Return the estimated USD NAV represented by outstanding shares.
fetch_portfolio(universe[, block_identifier])Return no on-chain asset composition.
Return the reason public USTB redemption is unavailable.
Get when withdrawals/redemptions will next be open.
Return Superstate-specific scanner diagnostics.
fetch_share_price([block_identifier])Fetch the issuer-published USTB continuous NAV/share.
Fetch USTB ERC-20 metadata.
fetch_share_token_address([block_identifier])Return the ERC-20 fund-token address.
fetch_total_assets([block_identifier])Estimate fund value from outstanding shares and published NAV.
fetch_total_supply([block_identifier])Fetch outstanding human-readable fund shares.
fetch_utilisation_percent([block_identifier])Get the percentage of assets currently lent out.
get_deposit_fee(block_identifier)Deposit fee is set to zero by default as vaults usually do not have deposit fees.
Reject unsupported public subscription/redemption execution.
Return static public transaction-adapter support, if any.
Return unknown redemption timing.
Return unknown product-level fees.
Get how this vault accounts its fees.
Get various vault state flags from the smart contract.
Reject unsupported public flow accounting.
get_historical_reader(stateful)Return the supply and continuous-price reader.
get_link([referral])Return the USTB product documentation link.
get_management_fee(block_identifier)Return no on-chain management-fee value.
Get a human readable message if we know somethign special is going on with this vault.
get_performance_fee(block_identifier)Return no on-chain performance-fee value.
Return the name of the vault protocol.
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.
Return whether lifecycle event accounting is implemented.
Does this vault have fees outside the shared fee model.
Return whether subscriptions distribute on-chain positions.
- __init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)
Create a Superstate fund adapter.
- Parameters
web3 (web3.main.Web3) – Web3 connection for the product chain.
spec (eth_defi.vault.base.VaultSpec) – Chain and reviewed fund-token address.
token_cache (Optional[dict]) – Shared ERC-20 metadata cache.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Shared classification flags.
default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Default block for direct metadata reads.
require_denomination_token (bool) – Retained for
VaultBasecompatibility.
- property chain_id: int
Return the product chain id.
- property address: eth_typing.evm.HexAddress
Return the checksum fund-token address.
- property vault_address: eth_typing.evm.HexAddress
Return scanner-compatible alias for the token address.
- property name: str
Return the issuer’s ERC-20 name.
- property symbol: str
Return the issuer’s ERC-20 symbol.
- property description: Optional[str]
Return a general product description.
- property short_description: Optional[str]
Return a compact product description.
- property manager_name: Optional[str]
Return the issuer platform used for curator attribution.
- fetch_share_token_address(block_identifier='latest')
Return the ERC-20 fund-token address.
- fetch_share_token()
Fetch USTB ERC-20 metadata.
- Returns
Cached token details.
- Return type
- fetch_denomination_token_address()
Return no ERC-20 denomination token.
USTB has a USD NAV and may accept configured stablecoins for approved subscriptions, but it does not expose a single ERC-4626-style asset. Reporting USDC as a denomination would incorrectly advertise a public transferable or redeemable asset relationship.
- Returns
Always
None.- Return type
- fetch_denomination_token()
Return no ERC-20 denomination metadata.
- Returns
Always
None.- Return type
- convert_oracle_price(raw_price)
Convert reviewed USTB oracle units to USD/share.
- Parameters
raw_price (int) – Raw value returned by
getChainlinkPrice().- Returns
Human-readable USD NAV/share.
- Return type
- fetch_share_price(block_identifier='latest')
Fetch the issuer-published USTB continuous 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]) – Archive block or
latest.- Raises
RuntimeError – If Superstate marks its oracle value stale or invalid.
- Returns
USD NAV/share.
- Return type
- fetch_total_supply(block_identifier='latest')
Fetch outstanding human-readable fund shares.
- fetch_total_assets(block_identifier='latest')
Estimate fund value from outstanding shares and published NAV.
- fetch_nav(block_identifier='latest')
Return the estimated USD NAV represented by outstanding shares.
- fetch_info()
Return Superstate scan metadata.
- Returns
Token and NAV-source metadata.
- Return type
eth_defi.tokenised_fund.superstate.vault.SuperstateVaultInfo
- fetch_scan_record_extra_data()
Return Superstate-specific scanner diagnostics.
- fetch_portfolio(universe, block_identifier=None)
Return no on-chain asset composition.
Fund holdings are administered off-chain and are not ERC-20 balances held by the token proxy.
- Parameters
universe (eth_defi.vault.base.TradingUniverse) – Ignored.
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Ignored.
- Returns
Empty spot portfolio.
- Return type
- has_block_range_event_support()
Return whether lifecycle event accounting is implemented.
- Returns
Always
False.- Return type
- has_deposit_distribution_to_all_positions()
Return whether subscriptions distribute on-chain positions.
- Returns
Always
False.- Return type
- get_flow_manager()
Reject unsupported public flow accounting.
- Raises
NotImplementedError – Always.
- Return type
- get_deposit_manager()
Reject unsupported public subscription/redemption execution.
- Raises
NotImplementedError – Always, until a fully eligibility-aware lifecycle is implemented and tested against the issuer’s settlement systems.
- Return type
- fetch_deposit_closed_reason()
Return the reason public USTB subscription is unavailable.
- fetch_redemption_closed_reason()
Return the reason public USTB redemption is unavailable.
- get_historical_reader(stateful)
Return the supply and continuous-price reader.
- Parameters
stateful (bool) – Whether to retain reader progress.
- Returns
Superstate historical reader.
- Return type
- get_fee_data()
Return unknown product-level fees.
- Returns
Broken fee sentinel because USTB’s token does not expose fund fee terms and the protocol matrix intentionally has no generic fee mode.
- Return type
- get_management_fee(block_identifier)
Return no on-chain management-fee value.
- get_performance_fee(block_identifier)
Return no on-chain performance-fee value.
- get_estimated_lock_up()
Return unknown redemption timing.
- Returns
Nonebecause issuer eligibility and redemption liquidity apply.- Return type
- get_link(referral=None)
Return the USTB product documentation link.
- 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')
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
- 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_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')
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
- 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().
- 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_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
- 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_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_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
- property share_token: eth_defi.token.TokenDetails
ERC-20 that presents vault shares.
User gets shares on deposit and burns them on redemption