USYCVault
Documentation for eth_defi.tokenised_fund.usyc.vault.USYCVault Python class.
- class USYCVault
Bases:
eth_defi.tokenised_fund.vault.TokenisedFundVaultRead-only adapter for Circle USYC on Ethereum.
The adapter derives USYC TVL from ERC-20 supply and the official, Chainlink-compatible NAV oracle. It intentionally does not expose public transaction support because subscriptions and redemptions are performed through the entitlement-gated Teller contract.
Create the USYC adapter.
- Parameters
web3 – Ethereum Web3 connection.
spec – Chain and USYC token address.
token_cache – ERC-20 metadata cache.
features – Shared classification flags.
default_block_identifier – Accepted for factory compatibility.
require_denomination_token – Whether a failed USDC lookup is fatal.
Attributes summary
Return the checksummed USYC ERC-20 address.
Return the Ethereum mainnet chain id.
Get the token which denominates the vault valuation
Deposit manager assocaited with this vault
Return a strategy description based on Circle's product page.
Flow manager associated with this vault
Get info dictionary related to this vault deployment.
Return the product administrator and platform name.
Return the USYC ERC-20 name.
Fetch the official oracle answer decimal scale.
Return the official Chainlink-compatible USYC Oracle contract.
ERC-20 that presents vault shares.
Return a concise USYC product description.
Return the USYC ERC-20 symbol.
Return the primary shared scanner identifier.
whitelist_notesOptional qualification for the exported whitelist status.
Methods summary
__init__(web3, spec[, token_cache, ...])Create the USYC adapter.
convert_raw_share_price(raw_price)Convert an oracle answer to USDC NAV per USYC.
fetch_available_liquidity([block_identifier])Get the amount of denomination token available for immediate withdrawal.
Fetch the USDC denomination token.
Return USYC's Ethereum USDC subscription denomination.
Explain why generic deposits are unavailable.
Get when deposits will next be open.
Export official USYC contract 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])Fetch total USYC NAV.
fetch_portfolio(universe[, block_identifier])Return no directly observable fund portfolio.
Explain why generic redemptions are unavailable.
Get when withdrawals/redemptions will next be open.
Return USYC NAV-source and permissioned-flow diagnostics.
fetch_share_price([block_identifier])Fetch USYC NAV per token from the official oracle.
Fetch USYC ERC-20 metadata.
fetch_share_token_address([block_identifier])Return the USYC ERC-20 token address.
fetch_total_assets([block_identifier])Fetch USYC TVL as supply times official NAV/share.
fetch_total_supply([block_identifier])Fetch total outstanding USYC supply.
fetch_utilisation_percent([block_identifier])Get the percentage of assets currently lent out.
get_deposit_fee(block_identifier)Return the published standard subscription fee.
Return a manager that explicitly refuses public fund operations.
Report explicit lack of public deposit and redemption support.
What is the estimated lock-up period for this vault.
Return USYC's published fee metadata.
Get how this vault accounts its fees.
Return vault flags including the tokenised fund classification.
Raise because Teller flow accounting is not implemented.
get_historical_reader(stateful)Create a USYC historical reader.
get_link([referral])Return Circle's USYC product page.
get_management_fee(block_identifier)Return unknown management fee because the product discloses a yield fee only.
Get a human readable message if we know somethign special is going on with this vault.
get_performance_fee(block_identifier)Return Circle's disclosed yield fee.
Return the name of the vault protocol.
get_risk()Get risk profile of this vault.
Return the source used for share-price observations.
get_spec()Return an export caveat for the vault-wide whitelist status.
get_withdraw_fee(block_identifier)Return the published standard redemption fee.
Return whether standard flow-event accounting is available.
Does this vault have fees outside the shared fee model.
Return whether deposits enter visible on-chain positions.
is_account_whitelisted(address)Determine whether an account has completed the vault's KYC policy.
Classify tokenised-fund subscriptions as permissioned.
- __init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)
Create the USYC adapter.
- Parameters
web3 (web3.main.Web3) – Ethereum Web3 connection.
spec (eth_defi.vault.base.VaultSpec) – Chain and USYC token address.
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]]) – Accepted for factory compatibility.
require_denomination_token (bool) – Whether a failed USDC lookup is fatal.
- property chain_id: int
Return the Ethereum mainnet chain id.
- property address: eth_typing.evm.HexAddress
Return the checksummed USYC ERC-20 address.
- property vault_address: eth_typing.evm.HexAddress
Return the primary shared scanner identifier.
- property price_oracle_contract: web3.contract.contract.Contract
Return the official Chainlink-compatible USYC Oracle contract.
- property oracle_decimals: int
Fetch the official oracle answer decimal scale.
- property name: str
Return the USYC ERC-20 name.
- property symbol: str
Return the USYC ERC-20 symbol.
- property description: str
Return a strategy description based on Circle’s product page.
- property short_description: str
Return a concise USYC product description.
- property manager_name: str
Return the product administrator and platform name.
- fetch_share_token_address(block_identifier='latest')
Return the USYC ERC-20 token address.
- fetch_share_token()
Fetch USYC ERC-20 metadata.
- Returns
USYC token details.
- Return type
- fetch_denomination_token_address()
Return USYC’s Ethereum USDC subscription denomination.
- Return type
- fetch_denomination_token()
Fetch the USDC denomination token.
- Returns
Ethereum USDC token details.
- Return type
- convert_raw_share_price(raw_price)
Convert an oracle answer to USDC NAV per USYC.
- Parameters
raw_price (int) – Raw Chainlink-compatible oracle answer.
- Returns
USDC NAV per human-readable USYC token.
- Return type
- fetch_share_price(block_identifier='latest')
Fetch USYC NAV per token from the official oracle.
- fetch_total_supply(block_identifier='latest')
Fetch total outstanding USYC supply.
- fetch_total_assets(block_identifier='latest')
Fetch USYC TVL as supply times official NAV/share.
- fetch_nav(block_identifier='latest')
Fetch total USYC NAV.
- fetch_info()
Export official USYC contract metadata.
- Returns
Token, oracle, Teller and denomination details.
- Return type
- fetch_scan_record_extra_data()
Return USYC NAV-source and permissioned-flow diagnostics.
- fetch_portfolio(universe, block_identifier=None)
Return no directly observable fund portfolio.
- Parameters
universe (eth_defi.vault.base.TradingUniverse) – Ignored because underlying holdings are off-chain.
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 holdings are not on-chain.
- Returns
Empty spot portfolio.
- Return type
- has_block_range_event_support()
Return whether standard flow-event accounting is available.
- Return type
- has_deposit_distribution_to_all_positions()
Return whether deposits enter visible on-chain positions.
- Return type
- get_flow_manager()
Raise because Teller flow accounting is not implemented.
- Return type
- fetch_deposit_closed_reason()
Explain why generic deposits are unavailable.
- Return type
- fetch_redemption_closed_reason()
Explain why generic redemptions are unavailable.
- Return type
- get_historical_reader(stateful)
Create a USYC historical reader.
- Parameters
stateful (bool) – Whether to retain shared scanner reader state.
- Returns
Supply and oracle historical reader.
- Return type
- get_management_fee(block_identifier)
Return unknown management fee because the product discloses a yield fee only.
- get_performance_fee(block_identifier)
Return Circle’s disclosed yield fee.
- get_deposit_fee(block_identifier)
Return the published standard subscription fee.
- get_withdraw_fee(block_identifier)
Return the published standard redemption fee.
- get_fee_data()
Return USYC’s published fee metadata.
- Returns
Externalised Teller entry and redemption fees with a yield fee.
- Return type
- get_link(referral=None)
Return Circle’s USYC product page.
- 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_minimum_deposit(block_identifier='latest')
Fetch a source-proven minimum deposit in decimal token units.
A
Noneresult 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
Nonewhen unknown.- Return type
- fetch_minimum_redemption(block_identifier='latest')
Fetch a source-proven redemption minimum in decimal share units.
A
Noneresult 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
Nonewhen unknown.- 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_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
- get_deposit_manager_capability()
Report explicit lack of public deposit and redemption support.
- Returns
A two-direction capability with both operations disabled.
- Return type
- get_estimated_lock_up()
What is the estimated lock-up period for this vault.
- Returns
None if not know
- Return type
- get_fee_mode()
Get how this vault accounts its fees.
- Return type
- 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.
- Returns
A new set containing all generic flags and
VaultFlag.tokenised_fund.- 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_share_price_source()
Return the source used for share-price observations.
Vault integrations override this method when they expose a share price. Returning
Nonedistinguishes unsupported or unknown pricing from a known source classification.- Returns
Share-price source, or
Nonewhen the adapter does not provide one.- Return type
- 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.
- 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
- is_account_whitelisted(address)
Determine whether an account has completed the vault’s KYC policy.
The result concerns KYC or manual identity-approval 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
Truewhen the account has the required KYC/identity approval.- Raises
NotImplementedError – If the adapter cannot safely query account membership.
- Return type
- 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
Truebecause tokenised-fund deposits are permissioned.- Return type
- property share_token: eth_defi.token.TokenDetails
ERC-20 that presents vault shares.
User gets shares on deposit and burns them on redemption