SuperstateVault

Documentation for eth_defi.tokenised_fund.superstate.vault.SuperstateVault Python class.

class SuperstateVault

Bases: eth_defi.tokenised_fund.vault.TokenisedFundVault

Scan-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 VaultBase compatibility.

Attributes summary

`address`	Return the checksum fund-token address.
`chain_id`	Return the product chain id.
`chainlink_price_selector`
`denomination_token`	Get the token which denominates the vault valuation
`deposit_manager`	Deposit manager assocaited with this vault
`description`	Return a general product description.
`flow_manager`	Flow manager associated with this vault
`info`	Get info dictionary related to this vault deployment.
`manager_name`	Return the issuer platform used for curator attribution.
`name`	Return the issuer's ERC-20 name.
`share_token`	ERC-20 that presents vault shares.
`short_description`	Return a compact product description.
`symbol`	Return the issuer's ERC-20 symbol.
`synthetic_usd_denomination`	Whether NAV and historical total_assets already use synthetic USD units.
`vault_address`	Return scanner-compatible alias for the token address.
`whitelist_notes`	Optional qualification for the exported whitelist status.

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])	Read the adapter's available denomination-token liquidity.
`fetch_denomination_token`()	Return no ERC-20 denomination metadata.
`fetch_denomination_token_address`()	Return no ERC-20 denomination token.
`fetch_deposit_closed_reason`()	Return the reason public USTB subscription is unavailable.
`fetch_deposit_next_open`()	Get when deposits will next be open.
`fetch_deposit_open`()	Fetch the current protocol-defined deposit availability.
`fetch_info`()	Return Superstate scan 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])	Return the estimated USD NAV represented by outstanding shares.
`fetch_portfolio`(universe[, block_identifier])	Return no on-chain asset composition.
`fetch_redemption_closed_reason`()	Return the reason public USTB redemption is unavailable.
`fetch_redemption_next_open`()	Get when withdrawals/redemptions will next be open.
`fetch_scan_record_extra_data`()	Return Superstate-specific scanner diagnostics.
`fetch_share_price`([block_identifier])	Fetch the issuer-published USTB continuous NAV/share.
`fetch_share_token`()	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])	Read the adapter's lending or capital-deployment utilisation.
`get_deposit_fee`(block_identifier)	Deposit fee is set to zero by default as vaults usually do not have deposit fees.
`get_deposit_manager`()	Return a manager that explicitly refuses public fund operations.
`get_deposit_manager_capability`()	Report explicit lack of public deposit and redemption support.
`get_estimated_lock_up`()	Return unknown redemption timing.
`get_fee_data`()	Return unknown product-level fees.
`get_fee_mode`()	Get how this vault accounts its fees.
`get_flags`()	Return vault flags including the tokenised fund classification.
`get_flow_manager`()	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_notes`()	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.
`get_protocol_name`()	Return the name of the vault protocol.
`get_risk`()	Get risk profile of this vault.
`get_share_price_source`()	Return the source used for share-price observations.
`get_spec`()
`get_strategy_tags`()	Get the known investment strategy classifications for this vault.
`get_whitelist_notes`()	Return an export caveat for the vault-wide whitelist status.
`get_withdraw_fee`(block_identifier)	Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.
`get_withdrawal_period`()	Return binding withdrawal timing and optional settlement estimates.
`has_block_range_event_support`()	Return whether lifecycle event accounting is implemented.
`has_custom_fees`()	Does this vault have fees outside the shared fee model.
`has_deposit_distribution_to_all_positions`()	Return whether subscriptions distribute on-chain positions.
`is_account_whitelisted`(address)	Determine whether an account has completed the vault's KYC policy.
`is_whitelisted_deposit`()	Classify tokenised-fund subscriptions as permissioned.

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

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.

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

fetch_share_token()

Fetch USTB ERC-20 metadata.

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

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: Optional[eth_typing.evm.HexAddress]

fetch_denomination_token()

Return no ERC-20 denomination metadata.

Returns: Always None.
Return type: Optional[eth_defi.token.TokenDetails]

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

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

fetch_total_supply(block_identifier='latest')

Fetch outstanding human-readable fund shares.

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.
Returns: Total USTB supply.
Return type: decimal.Decimal

fetch_total_assets(block_identifier='latest')

Estimate fund value from outstanding shares and published NAV.

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.
Returns: USD-denominated supply times NAV/share.
Return type: decimal.Decimal

fetch_nav(block_identifier='latest')

Return the estimated USD NAV represented by outstanding shares.

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.
Returns: USD-denominated supply times NAV/share.
Return type: decimal.Decimal

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.

Returns: NAV source, compliance and denomination details.
Return type: dict[str, object]

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

eth_defi.vault.base.VaultPortfolio

has_block_range_event_support()

Return whether lifecycle event accounting is implemented.

Returns: Always False.
Return type: bool

has_deposit_distribution_to_all_positions()

Return whether subscriptions distribute on-chain positions.

Returns: Always False.
Return type: bool

get_flow_manager()

Reject unsupported public flow accounting.

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

fetch_deposit_closed_reason()

Return the reason public USTB subscription is unavailable.

Returns: Compliance and issuer-settlement warning.
Return type: Optional[str]

fetch_redemption_closed_reason()

Return the reason public USTB redemption is unavailable.

Returns: Compliance and issuer-settlement warning.
Return type: Optional[str]

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

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

get_management_fee(block_identifier)

Return no on-chain management-fee value.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored.
Returns: None.
Return type: Optional[float]

get_performance_fee(block_identifier)

Return no on-chain performance-fee value.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored.
Returns: None.
Return type: Optional[float]

get_estimated_lock_up()

Return unknown redemption timing.

Returns: None because issuer eligibility and redemption liquidity apply.
Return type: Optional[datetime.timedelta]

get_link(referral=None)

Return the USTB product documentation link.

Parameters: referral (Optional[str]) – Ignored.
Returns: USTB product 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')

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: 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_deposit_open()

Fetch the current protocol-defined deposit availability.

This is deliberately a tri-state value. True and False mean that the adapter read an authoritative vault-wide state; None means that the generic adapter cannot safely determine the state. It is separate from fetch_deposit_closed_reason(), because an absent human-readable reason does not prove that deposits are open.

Returns: True when deposits are open, False when they are closed, or None when the protocol does not expose a reliable global availability read.
Return type: Optional[bool]

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')

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

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().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: Optional[float]

get_deposit_manager()

Return a manager that explicitly refuses public fund operations.

The manager gives runtime callers a typed refusal, while get_deposit_manager_capability() provides the corresponding report metadata. Concrete issuer integrations must replace both only after implementing their complete permission-aware dealing lifecycle.

Returns: Non-operational tokenised-fund deposit manager.
Return type: eth_defi.tokenised_fund.vault.TokenisedFundDepositManager

get_deposit_manager_capability()

Report explicit lack of public deposit and redemption support.

Returns: A two-direction capability with both operations disabled.
Return type: eth_defi.vault.deposit_redeem.VaultDepositManagerCapability

get_fee_mode()

Get how this vault accounts its fees.

Return type: Optional[eth_defi.vault.fee.VaultFeeMode]

get_flags()

Return vault flags including the tokenised fund classification.

Preserve address- and protocol-specific flags supplied by the generic vault implementation, then add the descriptive flag used by tokenised fund listings. This base class is reserved for products with a legal fund structure, and must not be used merely because a DeFi vault issues epoch-settled shares.

Returns: A new set containing all generic flags and VaultFlag.tokenised_fund.
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_share_price_source()

Return the source used for share-price observations.

Vault integrations override this method when they expose a share price. Returning None distinguishes unsupported or unknown pricing from a known source classification.

Returns: Share-price source, or None when the adapter does not provide one.
Return type: Optional[eth_defi.vault.price_source.PriceSource]

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. None means 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; use StrategyTag.unknown only when research establishes that the strategy itself is unknown.

Returns: Strategy tag set, or None when the information is missing.
Return type: Optional[set[eth_defi.vault.strategy_tag.StrategyTag]]

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]

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().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

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 use min_period and max_period only for a binding smart-contract timing rule. An adapter may instead return a non-binding estimated_settlement for 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 None when unavailable.
Return type: Optional[eth_defi.vault.base.WithdrawalPeriod]

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, 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: True when the account has the required pre-approval.
Raises: NotImplementedError – If the adapter cannot safely query account membership.
Return type: bool

is_whitelisted_deposit()

Classify tokenised-fund subscriptions as permissioned.

Tokenised-fund adapters model issuer-operated products whose subscriptions require investor eligibility, issuer approval, or both. This is a vault-wide classification: individual adapters may expose different KYC, allow-list, transfer-agent, or offchain settlement mechanisms, so is_account_whitelisted() remains protocol-specific.

Returns: Always True because tokenised-fund deposits are permissioned.
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