erc_4626.vault_protocol.wildcat.state

Documentation for eth_defi.erc_4626.vault_protocol.wildcat.state Python module.

Wildcat version 2 market state and the values derived from it.

Module Attributes

MARKET_STATE_ABI_TYPE

ABI type of the version 2 MarketState struct returned by currentState().

Classes

WildcatMarketState

Version 2 MarketState returned by currentState().

MARKET_STATE_ABI_TYPE = '(bool,uint128,uint128,uint128,uint104,uint104,uint32,bool,uint32,uint16,uint16,uint16,uint112,uint32)'

ABI type of the version 2 MarketState struct returned by currentState().

class WildcatMarketState

Bases: object

Version 2 MarketState returned by currentState().

Field order follows the MarketState struct, so the decoded tuple can be passed positionally. Amounts are raw integers in market token units, and scaled* amounts must be multiplied by scale_factor / 1e27.

https://github.com/wildcat-finance/v2-protocol/blob/main/src/libraries/MarketState.sol

is_closed: bool

Whether the borrower has closed the market.

max_total_supply: int

Deposit cap in normalised units.

accrued_protocol_fees: int

Protocol fees owed by the borrower and held in the market.

normalized_unclaimed_withdrawals: int

Paid withdrawals not yet claimed by lenders.

scaled_total_supply: int

Total lender supply in scaled units, including pending withdrawals.

scaled_pending_withdrawals: int

Queued, unpaid withdrawals in scaled units, across all unpaid batches.

pending_withdrawal_expiry: int

Expiry of the current withdrawal batch, or zero.

is_delinquent: bool

Delinquency flag stored at the last state update.

time_delinquent: int

Accumulated delinquent seconds, accrued to the read block.

protocol_fee_bips: int

Share of interest paid to the protocol by the borrower, in bips.

annual_interest_bips: int

Base lender APR in bips.

reserve_ratio_bips: int

Liquidity the borrower must keep in the market, in bips.

scale_factor: int

Ray-precision share price.

last_interest_accrued_timestamp: int

Timestamp of the last interest accrual.

classmethod decode(data)

Decode raw currentState() return data.

Parameters

data (bytes) – ABI-encoded MarketState struct.

Returns

Decoded state.

Return type

eth_defi.erc_4626.vault_protocol.wildcat.state.WildcatMarketState

normalise(scaled_amount)

Convert a scaled amount to market token units.

Uses the contract’s half-up rayMul rounding.

Parameters

scaled_amount (int) – Amount in scaled units.

Returns

Amount in raw market token units.

Return type

int

property total_supply: int

Raw lender supply, equal to the market’s totalSupply().

property share_price: decimal.Decimal

Underlying assets per scaled market token.

property max_deposit: int

Raw remaining deposit capacity, zero for a closed market.

calculate_lending_metrics(cash)

Calculate available liquidity and utilisation from market cash.

Paid-but-unclaimed withdrawals and accrued protocol fees sit in the market’s cash but belong to withdrawn lenders and the protocol. Utilisation is lent-out debt over lender supply, equal to the version 1 outstandingDebt() / totalSupply(). Pending withdrawals are deducted only from available liquidity, because older unpaid batches would otherwise pin utilisation at 100%.

Parameters

cash (int) – Raw totalAssets(), the market’s asset balance.

Returns

(available liquidity, utilisation). Liquidity is in raw market token units. Utilisation is None when the market has no supply.

Return type

tuple[int, float | None]

__init__(is_closed, max_total_supply, accrued_protocol_fees, normalized_unclaimed_withdrawals, scaled_total_supply, scaled_pending_withdrawals, pending_withdrawal_expiry, is_delinquent, time_delinquent, protocol_fee_bips, annual_interest_bips, reserve_ratio_bips, scale_factor, last_interest_accrued_timestamp)
Parameters
  • is_closed (bool) –

  • max_total_supply (int) –

  • accrued_protocol_fees (int) –

  • normalized_unclaimed_withdrawals (int) –

  • scaled_total_supply (int) –

  • scaled_pending_withdrawals (int) –

  • pending_withdrawal_expiry (int) –

  • is_delinquent (bool) –

  • time_delinquent (int) –

  • protocol_fee_bips (int) –

  • annual_interest_bips (int) –

  • reserve_ratio_bips (int) –

  • scale_factor (int) –

  • last_interest_accrued_timestamp (int) –

Return type

None