tokenised_fund.usyc.vault
Documentation for eth_defi.tokenised_fund.usyc.vault Python module.
Circle USYC tokenised-fund adapter.
USYC is a permissioned token representing a share in Hashnote International Short Duration Yield Fund Ltd. It is not an ERC-4626 vault: the ERC-20 token provides supply, while the official USYC Oracle publishes NAV/share.
See https://usyc.docs.hashnote.com/overview/token-price and https://usyc.docs.hashnote.com/overview/smart-contracts.
Module Attributes
Public integration restriction for USYC's entitlement-gated Teller flows. |
|
Official USYC performance fee: 10% of yield. |
|
Official standard subscription fee, waived for eligible daily volume up to $1m. |
|
Official standard redemption fee, waived for eligible daily volume up to $1m. |
Classes
Read-only adapter for Circle USYC on Ethereum. |
|
USYC product metadata exposed to scan consumers. |
- USYC_PERMISSIONED_FLOW_REASON = 'Circle USYC subscriptions, transfers and redemptions require approved non-U.S. institutional investors and Teller entitlement checks'
Public integration restriction for USYC’s entitlement-gated Teller flows.
- USYC_DEPOSIT_FEE: float = 0.0004
Official standard subscription fee, waived for eligible daily volume up to $1m.
- USYC_WITHDRAW_FEE: float = 0.0003
Official standard redemption fee, waived for eligible daily volume up to $1m.
- class USYCVaultInfo
Bases:
eth_defi.vault.base.VaultInfoUSYC product metadata exposed to scan consumers.
- __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.
- 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.
- __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.
- 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 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.
Return the USYC ERC-20 token address.
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 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 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 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.
- 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_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
ERC-20 that presents vault shares.
User gets shares on deposit and burns them on redemption