Fee analytics API
Optional host-only valuation, observed APR, and projected APY functions.
Implemented: integrations/analytics/{apr,projection,valuation,errors}.rs, exported by grapl_amm::analytics under Cargo feature analytics. These are pure off-chain calculations. Do not enable this feature for the deployable program.
Units and rounding
Values use microdollars (usd_e6); rates use parts per billion (ppb). 100000000 ppb means 10%, not 100%. Annualization uses 31,536,000 seconds. Integer divisions round down, and width errors reject.
Value tokens
usd_value_e6(amount: u64, decimals: u8, price_usd_e6: u128)
-> AnalyticsResult<u128>price_usd_e6 is the external USD price per whole token. The function scales base units and accepts decimals through 38 because its decimal scale must fit u128. The caller provides price provenance, time consistency, freshness, and manipulation checks. This function is not an oracle.
Annualize earned LP fees
observed_fee_apr(observation: FeeObservation<'_>)
-> AnalyticsResult<u128>FeeObservation contains start, end, earned_fees_usd_e6, and a borrowed slice of CapitalInterval. Each interval has start, end, and capital_usd_e6. Intervals must be increasing, contiguous, and fully cover the nonempty observation window. Integrated capital must be positive.
The result is fees × year_seconds × RATE_SCALE / sum(capital × duration), rounded down. Deposits and withdrawals alter capital exposure. Collections move an earned claim and must not be counted again as income. Fee APR uses the LP's share, excluding protocol and creator revenue.
Project reinvestment
projected_fee_apy(apr_ppb: u128, periods: u16, cost_per_period_ppb: u128)
-> AnalyticsResult<i128>Supported periods are 1..=365. Cost is proportional to then-current capital per period. The result is signed and may be negative. A cost above the gross period capital factor rejects. Compounding applies the implementation's fixed-point downward rounding; a high-precision illustration can differ by small integer residues.
For example, 10% APR with two reinvestments and zero cost produces 10.25% projected APY. This excludes price changes, inventory P&L, divergence from holding, rewards, changing range activity, and changing liquidity share. No automatic reinvestment exists in the core.
Present the result
Label supplied observations, valuation currency, coverage, and compounding assumptions. A calculation over synthetic inputs is not a historical return. See LP performance before displaying a rate.