erc_4626.vault_protocol.wildcat.vault
Documentation for eth_defi.erc_4626.vault_protocol.wildcat.vault Python module.
Read-only adapter for Wildcat Finance version 2 lending markets.
A Wildcat market lends one asset to one borrower, mostly without collateral. It is not an ERC-4626 vault: the market contract is itself the lender’s rebasing ERC-20 token, like an Aave aToken:
balanceOf = scaledBalanceOf * scaleFactor / 1e27
share price = scaleFactor / 1e27
scaleFactor grows with base interest and, while a borrower stays
delinquent beyond the grace period, with penalty interest. The market’s view
functions accrue interest to block.timestamp, so historical eth_call
reads return the accrued state. totalAssets() is the market’s idle cash,
not lender value; lender value is totalSupply().
The protocol fee is a share of interest paid by the borrower on top of lender interest, so lenders pay no fees. Withdrawals are queued into batches. When a batch expires, lenders can claim what the market’s cash covers; the rest stays queued until the borrower repays.
See the scale factor documentation and core behaviour.
Module Attributes
Reason for disabled generic transaction and flow adapters. |
|
Deposit closure reason for a market closed by its borrower. |
|
Redemption closure reason before a fixed-term market matures. |
|
Note shown for a market flagged |
Classes
Expose a Wildcat version 2 market as a read-only vault. |
- WILDCAT_BLOCKED_FLOW_REASON = 'Wildcat markets use queued withdrawal batches and per-lender access control, which the generic vault transaction adapter does not support'
Reason for disabled generic transaction and flow adapters.
- DEPOSIT_CLOSED_MARKET_CLOSED = 'Market closed by borrower'
Deposit closure reason for a market closed by its borrower.
- REDEMPTION_CLOSED_FIXED_TERM = 'Withdrawals open when the fixed term ends'
Redemption closure reason before a fixed-term market matures.
- WILDCAT_DEFAULT_NOTE = 'The borrower has kept less than the required reserve in the market for longer than its grace period, so a [penalty interest rate](https://docs.wildcat.finance/using-wildcat/delinquency) applies. The share price includes interest the borrower may never repay.'
Note shown for a market flagged
delinquent_markets.
- class WildcatMarket
Bases:
eth_defi.vault.base.VaultBaseExpose a Wildcat version 2 market as a read-only vault.
Generic transaction and investor-flow adapters are disabled.
Create an adapter for a registry-discovered Wildcat market.
- Parameters
web3 – Ethereum Web3 connection.
spec – Chain and market address.
token_cache – Optional shared token metadata cache.
features – Persisted scanner features.
default_block_identifier – Default block for metadata reads.
require_denomination_token – Whether denomination-token read failure is fatal.
- __init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)
Create an adapter for a registry-discovered Wildcat market.
- Parameters
web3 (web3.main.Web3) – Ethereum Web3 connection.
spec (eth_defi.vault.base.VaultSpec) – Chain and market address.
token_cache (Optional[dict]) – Optional shared token metadata cache.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Persisted scanner features.
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 metadata reads.
require_denomination_token (bool) – Whether denomination-token read failure is fatal.
- Return type
None
- property address: eth_typing.evm.HexAddress
Return the market and share-token address.
- property vault_address: eth_typing.evm.HexAddress
Return the scanner-compatible market identity.
- property borrower: eth_typing.evm.HexAddress
Return the market’s immutable borrower address.
- property delinquency_grace_period: int
Return the market’s immutable delinquency grace period in seconds.
- property wildcat_metadata: eth_defi.erc_4626.vault_protocol.wildcat.offchain_metadata.WildcatMarketMetadata
Offchain market description and borrower profile from the Wildcat app API.
Fetched and cached on first access, see
eth_defi.erc_4626.vault_protocol.wildcat.offchain_metadata.
- property description: Optional[str]
Return the market description, or the borrower’s profile description.
Both texts are supplied by the borrower and not verified by Wildcat.
- property short_description: Optional[str]
Return the first sentence of
description.Starts from the first line that ends a sentence, skipping heading, date and link lines, see
extract_summary_line().
- property manager_name: Optional[str]
Return the borrower’s KYB-verified legal name.
The unverified borrower alias and the borrower address are never used.
Fetch the market token, which is the lender’s share.
- Return type
Return the market itself, which is the lender’s share token.
The historical price scanner reads this to prepare share-token metadata.
- fetch_denomination_token_address()
Read the lent asset from
asset().- Return type
- fetch_denomination_token()
Fetch the lent asset.
- Return type
- fetch_market_state(block_identifier='latest')
Read the market state accrued to the requested block.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Requested EVM state block.
- Returns
Decoded
currentState().- Return type
eth_defi.erc_4626.vault_protocol.wildcat.state.WildcatMarketState
- property current_state: eth_defi.erc_4626.vault_protocol.wildcat.state.WildcatMarketState
Market state at the adapter’s default block, read once per adapter.
Return
scaleFactor / 1e27in units of the lent asset.
- fetch_total_assets(block_identifier='latest')
Return lender value, the market’s
totalSupply().The market’s own
totalAssets()is idle cash and is never used as TVL.
Return lender value, see
fetch_total_assets().
- fetch_total_supply(block_identifier='latest')
Return the scaled market token supply.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Requested EVM state block.
- Returns
Scaled supply, so that supply times share price equals lender value.
- Return type
- fetch_lending_metrics(block_identifier='latest')
Read available liquidity and utilisation from one state snapshot.
See
WildcatMarketState.calculate_lending_metrics().- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Requested EVM state block.
- Returns
(available liquidity in asset units, utilisation).- Return type
tuple[decimal.Decimal, float | None]
- fetch_available_liquidity(block_identifier='latest')
Return lender cash not reserved for queued withdrawals.
- fetch_utilisation_percent(block_identifier='latest')
Return the share of lender supply lent out to the borrower.
- fetch_deposit_open()
Return whether the market accepts deposits up to its cap.
Account admission is separate, see
is_whitelisted_deposit().- Return type
- property hooks_address: eth_typing.evm.HexAddress
Return the market’s hooks instance.
hooks()returns a packedHooksConfigwhose top 160 bits are the hooks address.
- fetch_hooked_market()
Read the market’s access configuration from its hooks instance.
The OpenTermHooks and FixedTermHooks
HookedMarketstructs differ, so the template’s own ABI decodes the result.- Returns
Decoded
HookedMarkettuple.- Raises
NotImplementedError – For an unrecognised hooks template.
- Return type
- is_whitelisted_deposit()
Return whether deposits require a lender credential.
Reads
HookedMarket.depositRequiresAccess. A market whose role provider grants credentials to anyone is still reported as whitelisted. TheuseOnDeposithook bit is not an admission rule.- Returns
Truewhen deposits require a credential.- Raises
NotImplementedError – For an unrecognised hooks template, recorded as unknown permission.
- Return type
- fetch_fixed_term_end()
Return the fixed-term end for a fixed-term market.
- Returns
Naive UTC term end, or
Nonefor an open-term market.- Return type
- fetch_redemption_closed_reason()
Explain withdrawals blocked until a fixed term ends.
- fetch_redemption_next_open()
Return when a fixed-term market’s withdrawals open.
- Return type
- get_withdrawal_period()
Return the withdrawal batch duration.
A withdrawal joins the current batch and becomes claimable when the batch expires, so the contract-enforced wait is at most one batch duration. Like every
WithdrawalPeriod, this excludes liquidity shortages: an unfunded part of a batch stays queued until the borrower repays. Closed markets use zero-length batches. A fixed term is reported throughfetch_redemption_next_open()instead.- Returns
Withdrawal timing bounds.
- Return type
- is_defaulted()
Return whether the borrower is delinquent beyond the grace period.
Wildcat applies the penalty rate while the accumulated delinquent time exceeds the grace period, including for a while after a cure.
- Returns
Truewhen the penalty rate applies at the default block.- Return type
- is_test_market()
Return whether the market belongs to a reviewed Wildcat test borrower.
- Returns
Truefor a Wildcat test market.- Return type
- get_flags()
Add Wildcat state flags to the manual flags.
A test market is
unofficial, which hides it, and a defaulted market isdelinquent_markets.- Return type
- get_notes()
Prepend test-market and default warnings to the manual notes.
- get_strategy_tags()
Return the lending and unsecured credit tags and reviewed address-specific tags.
- Return type
- get_management_fee(block_identifier)
Return zero: the borrower pays the protocol fee on top of lender interest.
- get_performance_fee(block_identifier)
Return zero: the borrower pays the protocol fee on top of lender interest.
Classify
scaleFactoras smart-contract state.- Return type
- fetch_info()
Return the market identity and lent asset.
- Return type
- fetch_portfolio(universe, block_identifier=None)
Return no spot portfolio; lender value is a claim on the borrower.
- Parameters
universe (eth_defi.vault.base.TradingUniverse) – Ignored trading universe.
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]]) – Ignored EVM state block.
- Returns
Empty portfolio.
- Return type
- get_historical_reader(stateful)
Create the static Multicall historical reader.
- Parameters
stateful (bool) – Whether to keep adaptive reader state, read at most daily.
- Returns
Wildcat historical reader.
- Return type
- get_flow_manager()
Reject generic investor-flow accounting.
- Return type
- get_deposit_manager()
Reject generic transaction construction.
- has_block_range_event_support()
Return that generic investor-flow replay is not implemented.
- Return type
- has_deposit_distribution_to_all_positions()
Return that deposits do not map to spot positions.
- Return type
- get_link(referral=None)
Return the market page in the Wildcat app.
- 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_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_scan_record_extra_data()
Fetch protocol-specific private scan row columns.
Some vault protocols expose structured metadata that is useful for the raw scanner output but does not fit the shared human-readable columns. Override this hook in protocol-specific subclasses instead of adding a separate branch to
eth_defi.erc_4626.scan.create_vault_scan_record().
- 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().
- 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_data(block_identifier='latest')
Get fee data structure for this vault.
Component fee reads share the requested block. Existing no-argument callers retain latest-state behaviour.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Common fee source block, default latest.
- Returns
Fee mode and component fractions.
- Raises
ValueError – In the case of broken or unimplemented fee reading methods in the smart contract
- Return type
- get_fee_mode()
Get how this vault accounts its fees.
- Return type
- get_risk()
Get risk profile of this vault.
- 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.
- 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().
- 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, manual identity approval, or recipient allowlist 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 pre-approval.- Raises
NotImplementedError – If the adapter cannot safely query account membership.
- Return type
- is_permissionless(owner)
Inspect the required deposit and exit route without investing capital.
This opt-in policy check is independent of whether an admitted account can trade. Adapters must verify the complete route before returning true. Unsupported policy remains unknown; ordinary trading is unaffected.
- Parameters
owner (eth_typing.evm.HexAddress) – Intended asset sender, share owner and payout recipient.
- Returns
Whether the supported route is permissionless.
- Raises
NotImplementedError – If complete-route policy is not established.
- Return type
ERC-20 that presents vault shares.
User gets shares on deposit and burns them on redemption