erc_4626.vault_protocol.wildcat.historical
Documentation for eth_defi.erc_4626.vault_protocol.wildcat.historical Python module.
Historical Multicall reads for Wildcat markets.
Follows eth_defi.erc_4626.vault.ERC4626HistoricalReader. Two
calls per sampled block are enough: currentState() holds the accrued scale
factor, scaled supply, deposit cap and pending withdrawals, and
totalAssets() holds the market’s cash.
Classes
Read a Wildcat market's share price, supply and liquidity at historical blocks. |
|
Adaptive reader state that reads a Wildcat market at most daily. |
- class WildcatMarketReaderState
Bases:
eth_defi.erc_4626.vault.VaultReaderStateAdaptive reader state that reads a Wildcat market at most daily.
- Parameters
vault – The vault we are reading historical data for
tvl_threshold_1d_read – If the TVL is below this threshold, we will not read it more than once per day, otherwise hourly.
down_hard – Stop reading the vault if the TVL is down by this percentage from the peak.
min_tvl_threshold – If the vault never reaches this TVL, we stop reading it after the traction period.
traction_period – How long we wait for the vault to get traction before we stop reading it.
- Parm peaked_tvl_threshold
The TVL value we first need to reach to trigger down hard condition.
- get_frequency()
Return the shared adaptive cadence, slowed to at most one read a day.
Weekly cadences for tiny, peaked and faded markets are kept.
- __init__(vault, tvl_threshold_1d_read=Decimal('10000'), tiny_tvl_threshold_rare_read=Decimal('1000'), peaked_tvl_threshold=Decimal('200000'), min_tvl_threshold=Decimal('1500'), down_hard=0.98, traction_period=datetime.timedelta(days=60))
- Parameters
vault (eth_defi.erc_4626.vault.ERC4626Vault) – The vault we are reading historical data for
tvl_threshold_1d_read – If the TVL is below this threshold, we will not read it more than once per day, otherwise hourly.
down_hard – Stop reading the vault if the TVL is down by this percentage from the peak.
min_tvl_threshold – If the vault never reaches this TVL, we stop reading it after the traction period.
traction_period (datetime.timedelta) – How long we wait for the vault to get traction before we stop reading it.
- Parm peaked_tvl_threshold
The TVL value we first need to reach to trigger down hard condition.
- property exchange_rate: decimal.Decimal
Estimate denomination units in USD using the scanner’s token rules.
Reader qualification and admission probes use this coarse estimate, not a live price oracle. Cache it for this reader instance so repeated historical rows do not repeat token preparation. Missing denomination metadata and an unrecognised symbol have separate sentinels: a temporary metadata outage must not erase prior verified qualification.
- Returns
Estimated USD per token, or an explicit unavailable/unknown sentinel. BTC/ETH estimates are fixed heuristics, not market quotes.
- property freshness_qualified: bool
Determine live-row eligibility from persisted estimated USD TVL.
The existing
last_tvlandmax_tvlvalues provide the $1,500 entry and $1,000 exit limits without another stored reader-state flag. An unknown denomination conversion cannot certify USD TVL.- Returns
Whether this vault meets the live price-row TVL limits.
- get_broken_calls()
Get all calls marked as broken.
- get_call_status(function_name)
Get the status of a function call.
- on_called(result, total_assets=None, share_price=None)
Update adaptive polling and USD TVL qualification from a real read.
The denomination-token total assets are converted using the existing
exchange_rateestimate. An unknown-rate sentinel does not certify a vault as having meaningful USD TVL. Entry is $1,500 and exit is below $1,000; eligibility is derived from persisted latest and peak TVL across scan cycles.- Parameters
result (eth_defi.event_reader.multicall_batcher.EncodedCallResult) – Result of convertToAssets() call
total_assets (Optional[decimal.Decimal]) – Vault assets in denomination-token units.
share_price (Optional[decimal.Decimal]) – Share price in denomination-token units.
- Returns
None.
- on_unpriced_call(result)
Update adaptive scan state for a successful supply-only read.
Some tokenised funds expose their share supply but no reviewed scalar NAV or TVL. They still need persistent reader state so the stateful scanner can cache token metadata, advance its last-read block and throttle historical calls. Zero values are internal scheduling sentinels only; the exported historical row must continue to expose
Nonefor its share price and total assets.- Parameters
result (eth_defi.event_reader.multicall_batcher.EncodedCallResult) – Successful supply call carrying a block number and timestamp.
- Return type
None
- requires_result_feedback()
Drain pending observations before choosing another low-frequency read.
Request feedback once for each new first/low-frequency observation. Remember the request locally so an unchanged failed reader cannot force every block into a separate flush. Unknown TVL keeps its existing hourly buffering after the first attempt. This marker never advances saved state.
- Returns
Whether the next sampled block needs this result first.
- Return type
- set_call_status(function_name, check_block, reverts)
Record the status of a function call.
- should_invoke(call, block_identifier, timestamp)
Check the condition if this multicall is good to go.
- Parameters
call (eth_defi.event_reader.multicall_batcher.EncodedCall) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) –
timestamp (datetime.datetime) –
- Return type
- should_skip_call(function_name)
Check if a specific function call should be skipped for this vault.
Part of the warmup system to detect and skip broken contract calls. See README-reader-states.md for documentation.
- first_seen_at_block
Passed from the vault discovery reader, pass the block number as args when we know this vault popped in to the existing
- first_read_at: datetime.datetime
Timestamp of the block of the first successful read of this vault.
- max_tvl: Decimal
Start with zero TVL
Start with zero share price
- last_call_at: datetime.datetime | None
When this vault received its last eth_call update
- peaked_at: datetime.datetime
Disable reading if the vault has peaked (TVL too much down) and is no longer active
- faded_at: datetime.datetime
Disable reading if the vault has never gotten any traction
- traction_period
How much time after deployment we allow to get traction
- min_tvl_threshold
Minimum TVL traction threshold to start reading the vault
- tiny_tvl_threshold_rare_read
Vaults we do no really care about
- entry_count
How many on_called() invocations have we had
- invoke_count_passed
How many should_invoke() invocations have we had
- invoke_count_first_read
How many should_invoke() invocations have we had
- invoke_count_missing_freq
How many should_invoke() invocations have we had
- invoke_count_throttled
How many should_invoke() invocations have we had
- rpc_error_count
Track RPCc errors
- denomination_token_address
Cache denomination token address when preparing readers
Cache share token address when preparing readers
One share in its raw units
- one
Cache denomination token address when preparing readers
- chain_id
Copy for state debuggin
- vault_poll_frequency
Cache for how often we are polling this vault, the mode name
- token_symbol
Cache for debuggin
- unsupported_token
Cache for debuggin
- class WildcatHistoricalReader
Bases:
eth_defi.vault.base.VaultHistoricalReaderRead a Wildcat market’s share price, supply and liquidity at historical blocks.
Create a historical Wildcat market reader.
- Parameters
vault – Wildcat market adapter to read.
stateful – Whether adaptive reader state should be retained.
- __init__(vault, stateful)
Create a historical Wildcat market reader.
- Parameters
vault (WildcatMarket) – Wildcat market adapter to read.
stateful (bool) – Whether adaptive reader state should be retained.
- Return type
None
- construct_multicalls()
Build the market state and cash reads.
- Returns
currentState()andtotalAssets()calls.- Return type
collections.abc.Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]
- process_result(block_number, timestamp, call_results)
Convert the market reads into a price row.
- Parameters
block_number (int) – Sampled EVM block.
timestamp (datetime.datetime) – Naive UTC timestamp of the sampled block.
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) – Responses from
construct_multicalls().
- Returns
Share price, lender value, scaled supply, deposit capacity, available liquidity and utilisation.
- Return type
- fetch_contextual_historical_reads(start_block, end_block, step)
Yield protocol-sourced historical rows outside the static call grid.
Contextual readers override this method and read an already-prefilled local cache. Network collection belongs before the common price scan.
- Parameters
- Returns
Ordinary
VaultHistoricalReadrows for the common writer.- Raises
NotImplementedError – If a reader opts into contextual history without implementing it.
- Return type
Return this reader’s sparse share-price comparison threshold.
Event-only readers may require every exact price change; ordinary readers retain the existing ten-basis-point suppression threshold.
- Returns
Non-negative relative suppression threshold.
- property uses_contextual_history: bool
Return whether this reader supplies protocol-sourced observations.
Most EVM vaults expose static calldata that the common multicaller can execute on a regular block grid. Protocols such as GMX instead expose sparse value events that are prefetched into a protocol-owned cache.
- Returns
Falsefor the ordinary static-multicall path.
Return whether cash flows must be ignored by the sparse filter.
Vault-like products without a standard share-price method can still expose a supply-normalised price equivalent. Their TVL and supply changes must not create false performance observations.
- Returns
Truewhen the vault carries theshare_price_equivalencefeature.