// This Util calculates the across realized LP fees. See https://gist.github.com/chrismaree/a713725e4fe96c531c42ed7b629d4a85 // gist for a python implementation of the logic in this file. This implementation is designed to work with both web3.js // and ethers BNs in the main entry point function calculateRealizedLpFeePct. import Decimal from "decimal.js"; import { BigNumberish, BN, toBN, toBNWei, fromWei, min, max, fixedPointAdjustment } from "../utils"; // note a similar type exists in the constants file, but are strings only. This is a bit more permissive to allow // backward compatibility for callers with a rate model defined with bignumbers and not strings. export interface RateModel { UBar: BigNumberish; // denote the utilization kink along the rate model where the slope of the interest rate model changes. R0: BigNumberish; // is the interest rate charged at 0 utilization R1: BigNumberish; // R_0+R_1 is the interest rate charged at UBar R2: BigNumberish; // R_0+R_1+R_2 is the interest rate charged at 100% utilization } // converts an APY rate to a one week rate. Uses the Decimal library to take a fractional exponent function convertApyToWeeklyFee(apy: BN): BN { // R_week = (1 + apy)^(1/52) - 1 const weeklyFeePct = Decimal.pow( new Decimal("1").plus(fromWei(apy)), new Decimal("1").dividedBy(new Decimal("52")) ).minus(new Decimal("1")); // Convert from decimal back to BN, scaled by 1e18. return toBN(weeklyFeePct.times(fixedPointAdjustment.toString()).floor().toString()); } export function truncate18DecimalBN(input: BN, digits: number): BN { const digitsToDrop = 18 - digits; const multiplier = toBN(10).pow(digitsToDrop); return input.div(multiplier).mul(multiplier); } export class LPFeeCalculator { constructor(private readonly rateModel: RateModel) {} /** * Compute area under curve of the piece-wise linear rate model. * @param rateModel Rate model to be used in this calculation. * @param utilization The current utilization of the pool. * @returns The area under the curve of the piece-wise linear rate model. */ public calculateAreaUnderRateCurve(utilization: BN): BN { // Area under first piecewise component const utilizationBeforeKink = min(utilization, this.rateModel.UBar); const rectangle1Area = utilizationBeforeKink.mul(this.rateModel.R0).div(fixedPointAdjustment); const triangle1Area = toBNWei("0.5") .mul(this.calculateInstantaneousRate(utilizationBeforeKink).sub(this.rateModel.R0)) .mul(utilizationBeforeKink) .div(fixedPointAdjustment) .div(fixedPointAdjustment); // Area under second piecewise component const utilizationAfter = max(toBN("0"), utilization.sub(this.rateModel.UBar)); const rectangle2Area = utilizationAfter .mul(toBN(this.rateModel.R0).add(this.rateModel.R1)) .div(fixedPointAdjustment); const triangle2Area = toBNWei("0.5") .mul(this.calculateInstantaneousRate(utilization).sub(toBN(this.rateModel.R0).add(this.rateModel.R1))) .mul(utilizationAfter) .div(fixedPointAdjustment) .div(fixedPointAdjustment); return rectangle1Area.add(triangle1Area).add(rectangle2Area).add(triangle2Area); } /** * Calculate the instantaneous rate for a 0 sized deposit (infinitesimally small). * @param utilization The current utilization of the pool. * @returns The instantaneous rate for a 0 sized deposit. */ public calculateInstantaneousRate(utilization: BigNumberish): BN { // Assuming utilization >= 0, if UBar = 0 then the value beforeKink is 0 since min(>=0, 0) = 0. const beforeKink = this.rateModel.UBar.toString() === "0" ? toBN(0) : min(utilization, this.rateModel.UBar).mul(this.rateModel.R1).div(this.rateModel.UBar); const afterKink = max(toBN("0"), toBN(utilization).sub(this.rateModel.UBar)) .mul(this.rateModel.R2) .div(toBNWei("1").sub(this.rateModel.UBar)); return toBN(this.rateModel.R0).add(beforeKink).add(afterKink); } /** * Calculate the realized LP Fee Percent for a given rate model, utilization before and after the deposit. * @param rateModel Rate model to be used in this calculation. * @param utilizationBeforeDeposit The utilization of the pool before the deposit. * @param utilizationAfterDeposit The utilization of the pool after the deposit. * @param truncateDecimals Whether to truncate the decimals to 6. * @returns The realized LP fee percent. */ public calculateRealizedLpFeePct( utilizationBeforeDeposit: BigNumberish, utilizationAfterDeposit: BigNumberish, truncateDecimals = false ): BN { const apy = this.calculateApyFromUtilization(toBN(utilizationBeforeDeposit), toBN(utilizationAfterDeposit)); // ACROSS UMIP requires that the realized fee percent is floor rounded as decimal to 6 decimals. return truncateDecimals ? truncate18DecimalBN(convertApyToWeeklyFee(apy), 6) : convertApyToWeeklyFee(apy); } /** * Calculate the realized yearly LP Fee APY Percent for a given rate model, utilization before and after the deposit. * @param rateModel Rate model to be used in this calculation. * @param utilizationBeforeDeposit The utilization of the pool before the deposit. * @param utilizationAfterDeposit The utilization of the pool after the deposit. * @returns The realized LP fee APY percent. */ public calculateApyFromUtilization(utilizationBeforeDeposit: BN, utilizationAfterDeposit: BN): BN { if (utilizationBeforeDeposit.eq(utilizationAfterDeposit)) return this.calculateInstantaneousRate(utilizationBeforeDeposit); // Get the area of [0, utilizationBeforeDeposit] and [0, utilizationAfterDeposit] const areaBeforeDeposit = this.calculateAreaUnderRateCurve(utilizationBeforeDeposit); const areaAfterDeposit = this.calculateAreaUnderRateCurve(utilizationAfterDeposit); const numerator = areaAfterDeposit.sub(areaBeforeDeposit); const denominator = utilizationAfterDeposit.sub(utilizationBeforeDeposit); return numerator.mul(fixedPointAdjustment).div(denominator); } } /** * Calculate the instantaneous rate for a 0 sized deposit (infinitesimally small). * @param rateModel Rate model to be used in this calculation. * @param utilization The current utilization of the pool. * @returns The instantaneous rate for a 0 sized deposit. */ export function calculateInstantaneousRate(rateModel: RateModel, utilization: BigNumberish): BN { return new LPFeeCalculator(rateModel).calculateInstantaneousRate(utilization); } /** * Calculate the realized yearly LP Fee APY Percent for a given rate model, utilization before and after the deposit. * @param rateModel Rate model to be used in this calculation. * @param utilizationBeforeDeposit The utilization of the pool before the deposit. * @param utilizationAfterDeposit The utilization of the pool after the deposit. * @returns The realized LP fee APY percent. */ export function calculateApyFromUtilization( rateModel: RateModel, utilizationBeforeDeposit: BN, utilizationAfterDeposit: BN ): BN { return new LPFeeCalculator(rateModel).calculateApyFromUtilization(utilizationBeforeDeposit, utilizationAfterDeposit); } /** * Calculate the realized LP Fee Percent for a given rate model, utilization before and after the deposit. * @param rateModel Rate model to be used in this calculation. * @param utilizationBeforeDeposit The utilization of the pool before the deposit. * @param utilizationAfterDeposit The utilization of the pool after the deposit. * @param truncateDecimals Whether to truncate the decimals to 6. * @returns The realized LP fee percent. */ export function calculateRealizedLpFeePct( rateModel: RateModel, utilizationBeforeDeposit: BigNumberish, utilizationAfterDeposit: BigNumberish, truncateDecimals = false ): BN { return new LPFeeCalculator(rateModel).calculateRealizedLpFeePct( utilizationBeforeDeposit, utilizationAfterDeposit, truncateDecimals ); }