tokenised_fund.superstate.vault

Documentation for eth_defi.tokenised_fund.superstate.vault Python module.

Read-only adapter for Superstate permissioned tokenised funds.

The adapter currently supports USTB on Ethereum. USTB is an allowlisted ERC-20 fund share, not an ERC-4626 vault. Its issuer-published continuous price is read from the token’s documented getChainlinkPrice() method while outstanding shares come from totalSupply(). This gives NAV/share and an estimated fund value, but does not imply that a holder can subscribe, transfer or redeem without Superstate eligibility and available redemption liquidity.

Authoritative references:

Module Attributes

`SUPERSTATE_HOMEPAGE`	Public Superstate platform link.
`USTB_HOMEPAGE`	USTB product documentation.
`SUPERSTATE_RESTRICTED_FLOW_REASON`	Public-action warning for USTB shares.

Functions

export_superstate_usd_denomination(chain_id)

Export non-transferable USD accounting metadata.

Classes

`SuperstateVault`	Scan-only adapter for reviewed Superstate tokenised fund shares.
`SuperstateVaultInfo`	Superstate fund metadata exposed to scan consumers.

SUPERSTATE_HOMEPAGE = 'https://superstate.com/': Public Superstate platform link.

USTB_HOMEPAGE = 'https://docs.superstate.com/superstate-funds/ustb': USTB product documentation.

SUPERSTATE_RESTRICTED_FLOW_REASON = 'USTB subscriptions, transfers and redemptions require Superstate eligibility checks and issuer-controlled settlement': Public-action warning for USTB shares.

CHAINLINK_PRICE_SELECTOR = HexBytes('0x3aeef3d3'): ERC-20 token selector for the documented USTB continuous NAV price method.

class SuperstateVaultInfo

Bases: eth_defi.vault.base.VaultInfo

Superstate fund metadata exposed to scan consumers.

token: eth_typing.evm.HexAddress: Fund-token address.

chain_id: int: EVM chain id.

synthetic_usd_denomination: bool: The adapter uses an accounting USD denomination, not a transferable ERC-20 asset.

nav_source: str: NAV source label.

nav_estimated: bool: Whether NAV is an adapter estimate.

nav_oracle: Optional[eth_typing.evm.HexAddress]: Reviewed continuous-price oracle.

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

export_superstate_usd_denomination(chain_id)

Export non-transferable USD accounting metadata.

Parameters: chain_id (int) – EVM chain id for the fund record.
Returns: Token-like USD metadata with no ERC-20 address.
Return type: dict[str, object]

class SuperstateVault

Bases: eth_defi.vault.base.VaultBase

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.

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

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

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: eth_defi.vault.deposit_redeem.VaultDepositManager

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

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

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