USYCVault
Documentation for eth_defi.tokenised_fund.usyc.vault.USYCVault Python class.
- class USYCVault
Bases:
eth_defi.vault.base.VaultBaseRead-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.
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_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.
Raise because public USYC transactions are not supported.
Return static public transaction-adapter support, if any.
What is the estimated lock-up period for this vault.
Return USYC's published fee metadata.
Get how this vault accounts its fees.
Get various vault state flags from the smart contract.
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.
get_spec()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.
- __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
- get_deposit_manager()
Raise because public USYC transactions are not supported.
- 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_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_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_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()
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
- 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