TheoITokenVault

Documentation for eth_defi.tokenised_fund.theo.vault.TheoITokenVault Python class.

class TheoITokenVault

Bases: eth_defi.vault.base.VaultBase

Read-only adapter for the canonical Ethereum thBILL iToken.

This adapter deliberately leaves its denomination and price unset. The documented iToken accounting operates over arrays of basket assets, while the public direct mint/redeem lifecycle is KYC-restricted.

Create an address-scoped thBILL adapter.

Parameters

web3 – EVM JSON-RPC connection.
spec – Chain and thBILL token address.
token_cache – Shared ERC-20 metadata cache.
features – Shared classification flags.
default_block_identifier – Retained for factory compatibility.
require_denomination_token – Retained for VaultBase compatibility.

Raises

RuntimeError – If the address is not a reviewed Theo iToken.

Attributes summary

`address`	Return the iToken address.
`chain_id`	Return the canonical iToken chain id.
`denomination_token`	Get the token which denominates the vault valuation
`deposit_manager`	Deposit manager assocaited with this vault
`description`	Return the public product description.
`flow_manager`	Flow manager associated with this vault
`info`	Get info dictionary related to this vault deployment.
`manager_name`	Return the protocol-operated curator name.
`name`	Return the reviewed product name.
`share_token`	ERC-20 that presents vault shares.
`short_description`	Return a concise eligibility-aware description.
`symbol`	Return thBILL's symbol.
`vault_address`	Return the scanner-compatible share-token identifier.

Methods summary

`__init__`(web3, spec[, token_cache, ...])	Create an address-scoped thBILL adapter.
`fetch_available_liquidity`([block_identifier])	Get the amount of denomination token available for immediate withdrawal.
`fetch_denomination_token`()	Return no scalar denomination token.
`fetch_denomination_token_address`()	Return no surrogate denomination token.
`fetch_deposit_closed_reason`()	Explain why public deposits are unavailable.
`fetch_deposit_next_open`()	Get when deposits will next be open.
`fetch_info`()	Return explicit unpriced-product metadata.
`fetch_nav`([block_identifier])	Reject unreviewed basket valuation.
`fetch_portfolio`(universe[, block_identifier])	Return no inferred ERC-20 portfolio.
`fetch_redemption_closed_reason`()	Explain why public redemptions are unavailable.
`fetch_redemption_next_open`()	Get when withdrawals/redemptions will next be open.
`fetch_scan_record_extra_data`()	Return restricted-flow and valuation diagnostics.
`fetch_share_price`([block_identifier])	Reject a synthetic scalar NAV.
`fetch_share_token`()	Fetch ERC-20 metadata for thBILL.
`fetch_share_token_address`([block_identifier])	Return the thBILL token address.
`fetch_total_assets`([block_identifier])	Reject TVL calculation from supply alone.
`fetch_total_supply`([block_identifier])	Fetch human-readable thBILL supply.
`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.
`get_deposit_manager`()	Reject public dealing for this KYC-restricted product.
`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 unavailable fee data.
`get_fee_mode`()	Get how this vault accounts its fees.
`get_flags`()	Get various vault state flags from the smart contract.
`get_flow_manager`()	Reject unimplemented issuer-operated flow accounting.
`get_historical_reader`(stateful)	Return the supply-only historical reader.
`get_link`([referral])	Return the official thBILL product page.
`get_management_fee`(block_identifier)	Return the unavailable management 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 unavailable performance fee.
`get_protocol_name`()	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.
`has_block_range_event_support`()	Return whether public flow accounting is implemented.
`has_custom_fees`()	Does this vault have fees outside the shared fee model.
`has_deposit_distribution_to_all_positions`()	Return whether public deposits are distributed by this adapter.

__init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)

Create an address-scoped thBILL adapter.

Parameters

web3 (web3.main.Web3) – EVM JSON-RPC connection.
spec (eth_defi.vault.base.VaultSpec) – Chain and thBILL 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]]) – Retained for factory compatibility.
require_denomination_token (bool) – Retained for VaultBase compatibility.

Raises

RuntimeError – If the address is not a reviewed Theo iToken.

property chain_id: int

Return the canonical iToken chain id.

Returns: Ethereum mainnet id.

property address: eth_typing.evm.HexAddress

Return the iToken address.

Returns: Checksummed thBILL token address.

property vault_address: eth_typing.evm.HexAddress

Return the scanner-compatible share-token identifier.

Returns: thBILL token address.

property name: str

Return the reviewed product name.

Returns: On-chain name, with registry fallback.

property symbol: str

Return thBILL’s symbol.

Returns: On-chain symbol, with registry fallback.

property description: str

Return the public product description.

Returns: Product summary.

property short_description: str

Return a concise eligibility-aware description.

Returns: Compact product summary.

property manager_name: str

Return the protocol-operated curator name.

Returns: Theo.

fetch_share_token_address(block_identifier='latest')

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

fetch_share_token()

Fetch ERC-20 metadata for thBILL.

Returns: ERC-20 details for the canonical iToken.
Return type: eth_defi.token.TokenDetails

fetch_denomination_token_address()

Return no surrogate denomination token.

Returns: Always None because iToken accounting uses a basket.
Return type: Optional[eth_typing.evm.HexAddress]

fetch_denomination_token()

Return no scalar denomination token.

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

fetch_share_price(block_identifier='latest')

Reject a synthetic scalar NAV.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Requested historical block.
Raises: NotImplementedError – Always, until basket valuation is reviewed.
Return type: decimal.Decimal

fetch_total_supply(block_identifier='latest')

Fetch human-readable thBILL supply.

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

fetch_total_assets(block_identifier='latest')

Reject TVL calculation from supply alone.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Requested historical block.
Raises: NotImplementedError – Always, because supply is not NAV.
Return type: decimal.Decimal

fetch_nav(block_identifier='latest')

Reject unreviewed basket valuation.

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Requested historical block.
Raises: NotImplementedError – Always.
Return type: decimal.Decimal

fetch_info()

Return explicit unpriced-product metadata.

Returns: thBILL product metadata.
Return type: eth_defi.tokenised_fund.theo.vault.TheoITokenVaultInfo

fetch_scan_record_extra_data()

Return restricted-flow and valuation diagnostics.

Returns: Scan record extra data without a synthetic denomination.
Return type: dict[str, object]

fetch_portfolio(universe, block_identifier=None)

Return no inferred ERC-20 portfolio.

Parameters

universe (eth_defi.vault.base.TradingUniverse) – Ignored; basket assets are not a token balance list.
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 public flow accounting is implemented.

Returns: False.
Return type: bool

has_deposit_distribution_to_all_positions()

Return whether public deposits are distributed by this adapter.

Returns: False.
Return type: bool

get_flow_manager()

Reject unimplemented issuer-operated flow accounting.

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

get_deposit_manager()

Reject public dealing for this KYC-restricted product.

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

fetch_deposit_closed_reason()

Explain why public deposits are unavailable.

Returns: Restricted-flow reason.
Return type: str

fetch_redemption_closed_reason()

Explain why public redemptions are unavailable.

Returns: Restricted-flow reason.
Return type: str

get_historical_reader(stateful)

Return the supply-only historical reader.

Parameters: stateful (bool) – Requested scanner reader-state mode.
Returns: Theo iToken reader.
Return type: eth_defi.vault.base.VaultHistoricalReader

get_fee_data()

Return unavailable fee data.

Returns: Broken fee data because no official thBILL fee schedule was found.
Return type: eth_defi.vault.fee.FeeData

get_management_fee(block_identifier)

Return the unavailable management 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.
Returns: None.
Return type: Optional[float]

get_performance_fee(block_identifier)

Return the unavailable 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.
Returns: None.
Return type: Optional[float]

get_link(referral=None)

Return the official thBILL product page.

Parameters: referral (Optional[str]) – Ignored; Theo does not publish a referral URL.
Returns: Official product documentation URL.
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_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_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