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

WILDCAT_BLOCKED_FLOW_REASON

Reason for disabled generic transaction and flow adapters.

DEPOSIT_CLOSED_MARKET_CLOSED

Deposit closure reason for a market closed by its borrower.

REDEMPTION_CLOSED_FIXED_TERM

Redemption closure reason before a fixed-term market matures.

WILDCAT_DEFAULT_NOTE

Note shown for a market flagged delinquent_markets.

Classes

WildcatMarket

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.VaultBase

Expose 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 chain_id: int

Return the market chain.

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 name: str

Return the onchain market token name.

property symbol: str

Return the onchain market token symbol.

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_share_token()

Fetch the market token, which is the lender’s share.

Return type

eth_defi.token.TokenDetails

fetch_share_token_address(block_identifier='latest')

Return the market itself, which is the lender’s share token.

The historical price scanner reads this to prepare share-token metadata.

Parameters

block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored, because the identity is immutable.

Returns

Market address.

Return type

eth_typing.evm.HexAddress

fetch_denomination_token_address()

Read the lent asset from asset().

Return type

eth_typing.evm.HexAddress

fetch_denomination_token()

Fetch the lent asset.

Return type

Optional[eth_defi.token.TokenDetails]

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.

fetch_share_price(block_identifier='latest')

Return scaleFactor / 1e27 in units of the lent asset.

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

Asset value of one scaled market token.

Return type

decimal.Decimal

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.

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

Amount owed to lenders in asset units.

Return type

decimal.Decimal

fetch_nav(block_identifier='latest')

Return lender value, see fetch_total_assets().

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

Amount owed to lenders in asset units.

Return type

decimal.Decimal

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

decimal.Decimal

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.

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.

Return type

decimal.Decimal

fetch_utilisation_percent(block_identifier='latest')

Return the share of lender supply lent out to the borrower.

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

Utilisation from 0 to 1, or None when the market has no supply.

Return type

Optional[float]

fetch_deposit_open()

Return whether the market accepts deposits up to its cap.

Account admission is separate, see is_whitelisted_deposit().

Return type

bool

fetch_deposit_closed_reason()

Explain a closed or full market.

Return type

Optional[str]

property hooks_address: eth_typing.evm.HexAddress

Return the market’s hooks instance.

hooks() returns a packed HooksConfig whose top 160 bits are the hooks address.

property hooks_version: str

Return the hooks template name, OpenTermHooks or FixedTermHooks.

fetch_hooked_market()

Read the market’s access configuration from its hooks instance.

The OpenTermHooks and FixedTermHooks HookedMarket structs differ, so the template’s own ABI decodes the result.

Returns

Decoded HookedMarket tuple.

Raises

NotImplementedError – For an unrecognised hooks template.

Return type

tuple

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. The useOnDeposit hook bit is not an admission rule.

Returns

True when deposits require a credential.

Raises

NotImplementedError – For an unrecognised hooks template, recorded as unknown permission.

Return type

bool

fetch_fixed_term_end()

Return the fixed-term end for a fixed-term market.

Returns

Naive UTC term end, or None for an open-term market.

Return type

Optional[datetime.datetime]

fetch_redemption_closed_reason()

Explain withdrawals blocked until a fixed term ends.

Return type

Optional[str]

fetch_redemption_next_open()

Return when a fixed-term market’s withdrawals open.

Return type

Optional[datetime.datetime]

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 through fetch_redemption_next_open() instead.

Returns

Withdrawal timing bounds.

Return type

eth_defi.vault.base.WithdrawalPeriod

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

True when the penalty rate applies at the default block.

Return type

bool

is_test_market()

Return whether the market belongs to a reviewed Wildcat test borrower.

See WILDCAT_TEST_BORROWERS.

Returns

True for a Wildcat test market.

Return type

bool

get_flags()

Add Wildcat state flags to the manual flags.

A test market is unofficial, which hides it, and a defaulted market is delinquent_markets.

Return type

set[eth_defi.vault.flag.VaultFlag]

get_notes()

Prepend test-market and default warnings to the manual notes.

Return type

Optional[str]

get_strategy_tags()

Return the lending and unsecured credit tags and reviewed address-specific tags.

Return type

set[eth_defi.vault.strategy_tag.StrategyTag]

get_management_fee(block_identifier)

Return zero: the borrower pays the protocol fee on top of lender interest.

Parameters

block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored; the fee model is fixed.

Returns

Zero.

Return type

float

get_performance_fee(block_identifier)

Return zero: the borrower pays the protocol fee on top of lender interest.

Parameters

block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Ignored; the fee model is fixed.

Returns

Zero.

Return type

float

get_share_price_source()

Classify scaleFactor as smart-contract state.

Return type

eth_defi.vault.price_source.PriceSource

fetch_info()

Return the market identity and lent asset.

Return type

eth_defi.vault.base.VaultInfo

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

eth_defi.vault.base.VaultPortfolio

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

eth_defi.vault.base.VaultHistoricalReader

get_flow_manager()

Reject generic investor-flow accounting.

Return type

eth_defi.vault.base.VaultFlowManager

get_deposit_manager()

Reject generic transaction construction.

Return type

eth_defi.vault.deposit_redeem.VaultDepositManager

has_block_range_event_support()

Return that generic investor-flow replay is not implemented.

Return type

bool

has_deposit_distribution_to_all_positions()

Return that deposits do not map to spot positions.

Return type

bool

Return the market page in the Wildcat app.

Parameters

referral (Optional[str]) – Ignored; the app has no referral links.

Returns

Market page 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_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_minimum_deposit(block_identifier='latest')

Fetch a source-proven minimum deposit in decimal token units.

A None result 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 None when unknown.

Return type

Optional[decimal.Decimal]

fetch_minimum_redemption(block_identifier='latest')

Fetch a source-proven redemption minimum in decimal share units.

A None result 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 None when unknown.

Return type

Optional[decimal.Decimal]

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().

Returns

Mapping of private scan-row column names, usually prefixed with _. The default implementation returns no extra data.

Return type

dict[str, object]

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_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

eth_defi.vault.fee.FeeData

get_fee_mode()

Get how this vault accounts its fees.

Return type

Optional[eth_defi.vault.fee.VaultFeeMode]

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_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.

Returns

Export note, or None when the classification needs no caveat.

Return type

Optional[str]

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

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

True when the account has the required pre-approval.

Raises

NotImplementedError – If the adapter cannot safely query account membership.

Return type

bool

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

bool

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

  • User gets shares on deposit and burns them on redemption

first_seen_at_block: int | None

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.