yield_basis.metrics
Documentation for eth_defi.yield_basis.metrics Python module.
YieldBasis fundamental, redemption and conversion calculations.
The primary share price uses the USD value returned by preview_withdraw;
fundamental pricePerShare remains available for comparison. Inputs stay as
raw onchain integers until these pure functions derive display values.
Stablecoin conversion is an endpoint cost, exposed separately through
estimate_usd_stablecoin_swap_cost() and never embedded in the historical
equity curve.
Module Attributes
Fixed-point scale used by LT |
|
Fixed-point scale used by Curve |
|
Decimal scale used by LT share balances. |
|
Assumed one-way conversion cost between a generic USD stablecoin and the YieldBasis underlying asset: 10 basis points, or 0.10%. |
|
Largest sensible ERC-20 decimal precision for a uint256 raw value. |
Functions
|
Convert raw LT |
|
Convert the Curve pool oracle to assumed USD per native asset. |
Estimate one generic USD-stablecoin/underlying conversion cost. |
|
|
Convert a protocol redemption preview to native asset per LT share. |
|
Convert a marginal redemption preview to USD per LT share. |
Return the assumed loss from an otherwise flat round trip. |
|
|
Return staked LT units divided by effective LT supply. |
|
Return temporary redemption discount relative to fundamental PPS. |
|
Return the native-asset endpoint return for one LT share. |
Calculate mint-to-redemption USD return after endpoint conversions. |
- YIELD_BASIS_USD_STABLECOIN_SWAP_COST: float = 0.001
Assumed one-way conversion cost between a generic USD stablecoin and the YieldBasis underlying asset: 10 basis points, or 0.10%.
- MAX_ASSET_DECIMALS: int = 78
Largest sensible ERC-20 decimal precision for a uint256 raw value. Ethereum’s uint256 decimal display has at most 78 decimal places.
- estimate_usd_stablecoin_swap_cost(underlying_token)
Estimate one generic USD-stablecoin/underlying conversion cost.
The current baseline is deliberately simple: every reviewed WBTC, cbBTC, tBTC and WETH market uses the same fixed 10-basis-point assumption. The underlying-token argument keeps the accounting boundary explicit and allows later token-specific estimates without changing the VaultBase fee interface or historical schema. This estimate excludes price impact, gas and MEV.
- Parameters
underlying_token (eth_typing.evm.HexAddress) – YieldBasis LT underlying ERC-20 address.
- Returns
One-way cost as a fraction, currently
0.001for every token.- Return type
- usd_stablecoin_investor_return(fundamental_entry_share_price, redemption_exit_share_price, underlying_token)
Calculate mint-to-redemption USD return after endpoint conversions.
YieldBasis mints new shares at fundamental PPS and redeems them at the current
preview_withdrawvalue. The entry value must therefore exclude TRD, while the exit value includes it. Each stablecoin conversion retains1 - costof value. The fixed cost is applied once at entry and once at exit, never at intermediate historical observations.- Parameters
fundamental_entry_share_price (decimal.Decimal) – Positive fundamental USD PPS used to mint at entry.
redemption_exit_share_price (decimal.Decimal) – Positive TRD-inclusive USD redemption value at exit.
underlying_token (eth_typing.evm.HexAddress) – YieldBasis LT underlying ERC-20 address.
- Returns
Net endpoint return where
0.1means 10%.- Return type
- round_trip_usd_stablecoin_swap_cost(underlying_token)
Return the assumed loss from an otherwise flat round trip.
- Parameters
underlying_token (eth_typing.evm.HexAddress) – YieldBasis LT underlying ERC-20 address.
- Returns
Positive loss fraction, currently
0.001999for two 10-bps legs.- Return type
Convert raw LT
pricePerShareto native asset units.- Parameters
- Returns
Native-asset value of one LT share.
- Return type
- asset_usd_price(raw_price, *, oracle_scale=1000000000000000000)
Convert the Curve pool oracle to assumed USD per native asset.
The reviewed pools quote coin 1, the BTC or ETH asset, in coin 0 crvUSD. The integration treats that stable-side quote as one USD for its generic USD comparison; crvUSD remains protocol plumbing, not the investor-facing denomination token.
- Parameters
- Returns
Assumed USD value of one whole native asset.
- Return type
- underlying_return(start_raw_price_per_share, end_raw_price_per_share, *, pps_scale=1000000000000000000)
Return the native-asset endpoint return for one LT share.
This diagnostic isolates the change in YieldBasis fundamental PPS from the BTC or ETH price move included in the primary USD return.
- Parameters
- Returns
Decimal endpoint return, where
0.1means 10%.- Return type
Convert a protocol redemption preview to native asset per LT share.
preview_withdrawreturns raw units of the market’s volatile asset, whereas LT shares use the protocol’s 18-decimal fixed-point scale.- Parameters
- Returns
Native-asset redemption value per whole LT share.
- Return type
Convert a marginal redemption preview to USD per LT share.
This is the primary gross YieldBasis share-price-equivalence formula used by the common vault pipeline. The first term incorporates the Temporary Redemption Discount (TRD); the second term incorporates BTC or ETH price volatility. Multiplying the two is equivalent to fundamental USD PPS multiplied by
1 + TRD, so callers must not subtract TRD a second time. Investor-specific conversion costs are not deducted here: useusd_stablecoin_investor_return()for a fee-adjusted investment period.- Parameters
raw_preview_shares (int) – Raw LT units supplied to
preview_withdraw.raw_redemption_assets (int) – Raw underlying units returned by the preview.
raw_asset_crvusd_price (int) – Raw Curve asset/crvUSD oracle value used as the USD proxy at the same block.
asset_decimals (int) – ERC-20 decimal precision of the underlying asset.
oracle_scale (int) – Curve oracle fixed-point scale.
share_scale (int) – LT share fixed-point scale.
- Returns
Gross marginal redemption value of one whole LT share in USD.
- Return type
- temporary_redemption_discount(raw_preview_shares, raw_redemption_assets, raw_price_per_share, *, asset_decimals, pps_scale=1000000000000000000, share_scale=1000000000000000000)
Return temporary redemption discount relative to fundamental PPS.
A negative value means the previewed exit is below fundamental value. The preview is required because the primary curve must not substitute fundamental value and mix two accounting bases.
- Parameters
raw_preview_shares (int) – Raw LT units supplied to
preview_withdraw.raw_redemption_assets (int) – Raw underlying units returned by the preview.
raw_price_per_share (int) – Raw fundamental LT PPS from the same block.
asset_decimals (int) – ERC-20 decimals of the underlying asset.
pps_scale (int) – LT PPS fixed-point scale.
share_scale (int) – LT share fixed-point scale.
- Returns
Redemption-to-fundamental relative difference.
- Return type
- staked_ratio(raw_effective_supply, raw_staked_supply)
Return staked LT units divided by effective LT supply.
The ratio is contextual market information only; staked gauge returns and YB incentives are outside the base LT performance curve.
- Parameters
- Returns
Ratio from zero to one, or
Nonefor zero supply.- Return type