LP performance: APR and APY

Implemented off-chain calculations; synthetic inputs. The optional integrations/analytics module calculates fee APR and projected APY. There is no production indexer or live yield feed. A fee-growth checkpoint supports entitlement accounting; it does not provide a history of valuations, cash flows, collections, or time in range. See the analytics API.

Observed fee APRCopy Anchor Link

Use annualized observed fee APR for a historical window. The fees and window are observed; the annualized rate is a calculation, not a year of realized performance.

Let F be fees earned during the window, valued in one explicit quote unit. Let C_avg be time-weighted position principal value over that window, including time out of range. Let T be window seconds and Y = 31536000 seconds for a fixed 365-day year.

window_fee_return = F / C_avg
annualized_observed_fee_APR = (F / C_avg) × (Y / T)

Use the position's earnings and capital, not pool volume divided by its current liquidity. Do not exclude inactive hours from the denominator while still calling the result a full-window APR. Report missing valuations or zero denominators as unavailable, not zero.

Avoid double counting collectionsCopy Anchor Link

For a fixed position with no ownership changes, calculate the earned token increment as:

fees_earned = collected_during_window
           + uncollected_at_end
           - uncollected_at_start

Uncollected amounts include owed balances plus fees from growth not yet crystallized. Apply the same token valuation policy throughout. Subtract external deposits/withdrawals from return calculations; they are cash flows, not profit. Keep donations or incentives separate from organic swap-fee earnings when the evidence allows that classification.

Estimated APYCopy Anchor Link

APY models reinvestment. If annualized fee APR r is assumed constant, compounding occurs n times per year, and each reinvestment costs proportion c of then-current capital:

estimated_APY = (1 + r / n - c)^n - 1

This assumes fees can be collected and reinvested at that cadence, at the stated cost, with sufficient liquidity and continued earning conditions. grapl does not automatically compound. A short-window APR cannot establish future volume, in-range time, or a stable reinvestment rate.

The implementation accepts 1–365 periods, uses ppb fixed-point rates with downward rounding, and returns signed APY because costs can exceed earned fees. A native-token transaction fee must first be valued and converted into the proportional cost; it is not a ppb rate by itself.

Label compounding frequency, gross/net treatment, valuation source, observation window, and estimation time alongside the number. Do not call projected APY “observed yield.”

An illustrative calculationCopy Anchor Link

The following inputs are synthetic quote valuations, not market observations. Keep decimal quantities exact when reproducing the calculation.

Earned fees are 0.50 + 2.50 − 1.00 = 2.00. Dividing by 10,000 gives a daily return of 0.02%; annualizing over 365 days gives 7.30% APR. Daily reinvestment at that constant rate and zero cost gives the illustrated APY.

Fee yield is not total returnCopy Anchor Link

Principal can lose quote value while fees accumulate. Total position P&L must reconcile current principal, fee claims, collections, deposits, withdrawals, costs, and price changes using an explicit valuation policy. Divergence from holding the original assets is another comparison with its own benchmark. Neither is captured by fee APR alone.

A future indexer must provide slot/timestamped snapshots, complete fee and cash-flow history, token decimals, valuation sources, and reorg/finality handling. Synthetic fixtures validate arithmetic only; they do not supply those observations.