@liquid-af/sdk 0.10.3 → 0.10.4

package/src/index.ts

@@ -45,6 +45,8 @@ export type {
 	GlobalAmmVolume,
 	CashbackRange,
 	CashbackConfiguration,
+	CashbackBreakdown,
+	TierBreakdown,
 	FeeDistribution,
 	BondingCurveBuyResult,
 	BondingCurveSellResult,

package/src/math/cashback.ts

@@ -0,0 +1,124 @@
+import BN from "bn.js";
+import { BPS_DENOMINATOR } from "./constants.js";
+import type { CashbackRange } from "../types.js";
+
+/** Per-tier breakdown of cashback earnings */
+export interface TierBreakdown {
+	/** Index of this range in the config's ranges array */
+	rangeIndex: number;
+	/** Multiplier in basis points (10000 = 1x) */
+	multiplierBps: number;
+	/** Amount of cashback_credits attributed to this tier (post-multiplier) */
+	postMultiplierAmount: BN;
+	/** The base (1x-equivalent) earning that produced this tier's contribution */
+	baseAmount: BN;
+	/** Bonus from multiplier: postMultiplierAmount - baseAmount */
+	bonusAmount: BN;
+}
+
+/** Breakdown of a user's cashback balance into base earnings vs multiplier bonus */
+export interface CashbackBreakdown {
+	/** The user's total cashback_credits balance */
+	totalBalance: BN;
+	/** What the user would have earned at 1x multiplier across all tiers */
+	baseEarnings: BN;
+	/** Total bonus from multipliers: totalBalance - baseEarnings */
+	multiplierBonus: BN;
+	/** Per-tier breakdown (only tiers with non-zero contribution) */
+	tiers: TierBreakdown[];
+}
+
+const ZERO = new BN(0);
+const BPS = new BN(BPS_DENOMINATOR);
+
+/**
+ * Reverses the on-chain progressive multiplier to break down a cashback balance
+ * into base earnings vs multiplier bonus.
+ *
+ * The on-chain `apply_balance_multiplier` advances through ranges by pre-multiplier
+ * portions, so each tier of width W with multiplier M contributes W * M / 10000 to
+ * the stored balance. This function walks the same ranges in reverse to decompose
+ * the final balance.
+ *
+ * @param cashbackCredits - The user's current cashback_credits (post-multiplier balance)
+ * @param ranges - Balance-based multiplier ranges from CashbackConfiguration
+ * @returns Breakdown of base earnings vs multiplier bonus, with per-tier detail
+ */
+export function getCashbackBreakdown(
+	cashbackCredits: BN,
+	ranges: CashbackRange[],
+): CashbackBreakdown {
+	if (cashbackCredits.isZero() || ranges.length === 0) {
+		return {
+			totalBalance: cashbackCredits.clone(),
+			baseEarnings: cashbackCredits.clone(),
+			multiplierBonus: ZERO.clone(),
+			tiers: [],
+		};
+	}
+
+	const tiers: TierBreakdown[] = [];
+	let cumulativePostMult = ZERO.clone();
+	let totalBase = ZERO.clone();
+	let remaining = cashbackCredits.clone();
+
+	for (let i = 0; i < ranges.length && remaining.gt(ZERO); i++) {
+		const range = ranges[i];
+		const multiplierBps = range.multiplierBasisPoints;
+		const width = range.rangeEndExclusive.sub(range.rangeStartInclusive);
+
+		// Post-multiplier contribution if this tier is fully filled
+		const tierPostMult = width.mul(new BN(multiplierBps)).div(BPS);
+
+		if (remaining.gte(tierPostMult)) {
+			// Tier fully filled
+			tiers.push({
+				rangeIndex: i,
+				multiplierBps,
+				postMultiplierAmount: tierPostMult.clone(),
+				baseAmount: width.clone(),
+				bonusAmount: tierPostMult.sub(width),
+			});
+			totalBase = totalBase.add(width);
+			cumulativePostMult = cumulativePostMult.add(tierPostMult);
+			remaining = remaining.sub(tierPostMult);
+		} else {
+			// Partially filled — solve for pre-mult portion:
+			// postMultInTier = p * M / 10000, so p = postMultInTier * 10000 / M
+			const postMultInTier = remaining.clone();
+			const baseInTier = postMultInTier.mul(BPS).div(new BN(multiplierBps));
+
+			tiers.push({
+				rangeIndex: i,
+				multiplierBps,
+				postMultiplierAmount: postMultInTier,
+				baseAmount: baseInTier.clone(),
+				bonusAmount: postMultInTier.sub(baseInTier),
+			});
+			totalBase = totalBase.add(baseInTier);
+			remaining = ZERO.clone();
+		}
+	}
+
+	// Balance beyond all defined ranges — use last range's multiplier
+	if (remaining.gt(ZERO)) {
+		const lastMultiplier = ranges[ranges.length - 1].multiplierBasisPoints;
+		const baseRemaining = remaining.mul(BPS).div(new BN(lastMultiplier));
+
+		tiers.push({
+			rangeIndex: ranges.length,
+			multiplierBps: lastMultiplier,
+			postMultiplierAmount: remaining.clone(),
+			baseAmount: baseRemaining.clone(),
+			bonusAmount: remaining.sub(baseRemaining),
+		});
+		totalBase = totalBase.add(baseRemaining);
+	}
+
+	return {
+		totalBalance: cashbackCredits.clone(),
+		baseEarnings: totalBase,
+		multiplierBonus: cashbackCredits.sub(totalBase),
+		tiers,
+	};
+}

package/src/math/index.ts

@@ -38,3 +38,6 @@ export {
 	calculateFeesForPool,
 	WSOL_MINT,
 } from "./tiered-fees.js";
+
+export { getCashbackBreakdown } from "./cashback.js";
+export type { CashbackBreakdown, TierBreakdown } from "./cashback.js";

package/src/types.ts

@@ -259,6 +259,32 @@ export interface CashbackConfiguration {
 	traderCashbackBasisPoints: number;
 }
 
+/** Per-tier breakdown of cashback earnings */
+export interface TierBreakdown {
+	/** Index of this range in the config's ranges array */
+	rangeIndex: number;
+	/** Multiplier in basis points (10000 = 1x) */
+	multiplierBps: number;
+	/** Amount of cashback_credits attributed to this tier (post-multiplier) */
+	postMultiplierAmount: BN;
+	/** The base (1x-equivalent) earning that produced this tier's contribution */
+	baseAmount: BN;
+	/** Bonus from multiplier: postMultiplierAmount - baseAmount */
+	bonusAmount: BN;
+}
+
+/** Breakdown of a user's cashback balance into base earnings vs multiplier bonus */
+export interface CashbackBreakdown {
+	/** The user's total cashback_credits balance */
+	totalBalance: BN;
+	/** What the user would have earned at 1x multiplier across all tiers */
+	baseEarnings: BN;
+	/** Total bonus from multipliers: totalBalance - baseEarnings */
+	multiplierBonus: BN;
+	/** Per-tier breakdown (only tiers with non-zero contribution) */
+	tiers: TierBreakdown[];
+}
+
 /** Fee breakdown from a trade */
 export interface FeeDistribution {
 	protocolFee: BN;