@liquid-af/sdk 0.10.3 → 0.10.4

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { ReadonlyWallet, createReadonlyProvider, createStubProvider, } from "./p
 export { LiquidError, LiquidErrorCode } from "./errors.js";
 export type { LiquidConfig } from "./config.js";
 export { MAINNET_CONFIG, DEVNET_CONFIG, LOCALNET_CONFIG, WSOL_MINT, BPS_DENOMINATOR, NUM_FEE_RECIPIENTS, MAX_FEE_RECIPIENTS_FEES, MAX_QUOTE_MINTS, MAX_CASHBACK_RANGES, MIN_MULTIPLIER_BPS, MAX_MULTIPLIER_BPS, MIN_VAULT_BALANCE, LIMITS, } from "./config.js";
-export type { GlobalConfiguration, BondingCurveState, AmmConfig, FeeTier, PoolState, Observation, ObservationState, UnifiedFeeConfiguration, UserProperties, ReferrerInfo, UserSnapshot, Deal, AdminUpdateUserArgs, TokenVolumeAccumulator, GlobalCurveVolume, GlobalAmmVolume, CashbackRange, CashbackConfiguration, FeeDistribution, BondingCurveBuyResult, BondingCurveSellResult, SwapFees, AmmSellOutput, AmmBuyInput, LpTokenAmounts, DistributionResult, PoolInfo, BuyCurvePreview, SellCurvePreview, SwapPreview, FeeRecipient, FeeModeAnchor, CurveStatusAnchor, } from "./types.js";
+export type { GlobalConfiguration, BondingCurveState, AmmConfig, FeeTier, PoolState, Observation, ObservationState, UnifiedFeeConfiguration, UserProperties, ReferrerInfo, UserSnapshot, Deal, AdminUpdateUserArgs, TokenVolumeAccumulator, GlobalCurveVolume, GlobalAmmVolume, CashbackRange, CashbackConfiguration, CashbackBreakdown, TierBreakdown, FeeDistribution, BondingCurveBuyResult, BondingCurveSellResult, SwapFees, AmmSellOutput, AmmBuyInput, LpTokenAmounts, DistributionResult, PoolInfo, BuyCurvePreview, SellCurvePreview, SwapPreview, FeeRecipient, FeeModeAnchor, CurveStatusAnchor, } from "./types.js";
 export { FeeMode, toAnchorFeeMode, feeModeEquals, CurveStatus, curveStatusEquals, } from "./types.js";
 export * from "./pda/index.js";
 export * from "./math/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,kBAAkB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE3D,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACN,cAAc,EACd,aAAa,EACb,eAAe,EACf,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,GACN,MAAM,aAAa,CAAC;AAErB,YAAY,EACX,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,iBAAiB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,OAAO,EACP,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,GACjB,MAAM,YAAY,CAAC;AAEpB,cAAc,gBAAgB,CAAC;AAE/B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,yBAAyB,CAAC;AAExC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,aAAa,CAAC;AAE5B,cAAc,UAAU,CAAC;AAEzB,YAAY,EACX,MAAM,EACN,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,GACR,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,kBAAkB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE3D,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACN,cAAc,EACd,aAAa,EACb,eAAe,EACf,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,GACN,MAAM,aAAa,CAAC;AAErB,YAAY,EACX,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,iBAAiB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,OAAO,EACP,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,GACjB,MAAM,YAAY,CAAC;AAEpB,cAAc,gBAAgB,CAAC;AAE/B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,yBAAyB,CAAC;AAExC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,aAAa,CAAC;AAE5B,cAAc,UAAU,CAAC;AAEzB,YAAY,EACX,MAAM,EACN,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,GACR,MAAM,gBAAgB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,kBAAkB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG3D,OAAO,EACN,cAAc,EACd,aAAa,EACb,eAAe,EACf,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,GACN,MAAM,aAAa,CAAC;AAqCrB,OAAO,EACN,OAAO,EACP,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,GACjB,MAAM,YAAY,CAAC;AAEpB,cAAc,gBAAgB,CAAC;AAE/B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,yBAAyB,CAAC;AAExC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,aAAa,CAAC;AAE5B,cAAc,UAAU,CAAC;AASzB,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,GACR,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,kBAAkB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG3D,OAAO,EACN,cAAc,EACd,aAAa,EACb,eAAe,EACf,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,GACN,MAAM,aAAa,CAAC;AAuCrB,OAAO,EACN,OAAO,EACP,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,GACjB,MAAM,YAAY,CAAC;AAEpB,cAAc,gBAAgB,CAAC;AAE/B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,yBAAyB,CAAC;AAExC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,aAAa,CAAC;AAE5B,cAAc,UAAU,CAAC;AASzB,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,GACR,MAAM,gBAAgB,CAAC"}

package/dist/math/cashback.d.ts

@@ -0,0 +1,41 @@
+import BN from "bn.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[];
+}
+/**
+ * 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 declare function getCashbackBreakdown(cashbackCredits: BN, ranges: CashbackRange[]): CashbackBreakdown;
+//# sourceMappingURL=cashback.d.ts.map

package/dist/math/cashback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cashback.d.ts","sourceRoot":"","sources":["../../src/math/cashback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,OAAO,CAAC;AAEvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC7B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,oBAAoB,EAAE,EAAE,CAAC;IACzB,8EAA8E;IAC9E,UAAU,EAAE,EAAE,CAAC;IACf,+DAA+D;IAC/D,WAAW,EAAE,EAAE,CAAC;CAChB;AAED,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IACjC,gDAAgD;IAChD,YAAY,EAAE,EAAE,CAAC;IACjB,wEAAwE;IACxE,YAAY,EAAE,EAAE,CAAC;IACjB,gEAAgE;IAChE,eAAe,EAAE,EAAE,CAAC;IACpB,iEAAiE;IACjE,KAAK,EAAE,aAAa,EAAE,CAAC;CACvB;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CACnC,eAAe,EAAE,EAAE,EACnB,MAAM,EAAE,aAAa,EAAE,GACrB,iBAAiB,CA0EnB"}

package/dist/math/cashback.js

@@ -0,0 +1,86 @@
+import BN from "bn.js";
+import { BPS_DENOMINATOR } from "./constants.js";
+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, ranges) {
+    if (cashbackCredits.isZero() || ranges.length === 0) {
+        return {
+            totalBalance: cashbackCredits.clone(),
+            baseEarnings: cashbackCredits.clone(),
+            multiplierBonus: ZERO.clone(),
+            tiers: [],
+        };
+    }
+    const tiers = [];
+    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,
+    };
+}
+//# sourceMappingURL=cashback.js.map

package/dist/math/cashback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cashback.js","sourceRoot":"","sources":["../../src/math/cashback.ts"],"names":[],"mappings":"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"}

package/dist/math/index.d.ts

@@ -5,4 +5,6 @@ export { calculateBuyExpectation, calculateSellExpectation, } from "./bonding-cu
 export { calculateAmmSellOutput, calculateAmmBuyInput, calculateLpToTokens, } from "./amm.js";
 export type { AmmFeeRates } from "./amm.js";
 export { calculatePoolMarketCap, lookupFeeTier, calculateFeesForPool, WSOL_MINT, } from "./tiered-fees.js";
+export { getCashbackBreakdown } from "./cashback.js";
+export type { CashbackBreakdown, TierBreakdown } from "./cashback.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/math/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,eAAe,EACf,oBAAoB,EACpB,GAAG,EACH,eAAe,EACf,mCAAmC,EACnC,iBAAiB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACN,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EACN,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EACN,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,SAAS,GACT,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,eAAe,EACf,oBAAoB,EACpB,GAAG,EACH,eAAe,EACf,mCAAmC,EACnC,iBAAiB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACN,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EACN,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EACN,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,SAAS,GACT,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/math/index.js

@@ -3,4 +3,5 @@ export { calcBps, calculateFees, calculateDistribution, calculateTotalDistributi
 export { calculateBuyExpectation, calculateSellExpectation, } from "./bonding-curve.js";
 export { calculateAmmSellOutput, calculateAmmBuyInput, calculateLpToTokens, } from "./amm.js";
 export { calculatePoolMarketCap, lookupFeeTier, calculateFeesForPool, WSOL_MINT, } from "./tiered-fees.js";
+export { getCashbackBreakdown } from "./cashback.js";
 //# sourceMappingURL=index.js.map

package/dist/math/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,eAAe,EACf,oBAAoB,EACpB,GAAG,EACH,eAAe,EACf,mCAAmC,EACnC,iBAAiB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACN,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,GACrB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACN,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACN,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,SAAS,GACT,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,eAAe,EACf,oBAAoB,EACpB,GAAG,EACH,eAAe,EACf,mCAAmC,EACnC,iBAAiB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACN,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,GACrB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACN,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACN,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,SAAS,GACT,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/types.d.ts

@@ -220,6 +220,30 @@ export interface CashbackConfiguration {
     ranges: CashbackRange[];
     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;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liquid-af/sdk",
-	"version": "0.10.3",
+	"version": "0.10.4",
 	"description": "TypeScript SDK for the Liquid DeFi protocol on Solana",
 	"type": "module",
 	"publishConfig": {

package/src/client.ts

@@ -89,6 +89,11 @@ import {
 	fetchUserSnapshot as fetchUserSnapshotFn,
 	fetchDeal as fetchDealFn,
 } from "./accounts/liquid-state.js";
+import { fetchCashbackBreakdown as fetchCashbackBreakdownFn } from "./helpers/cashback.js";
+import {
+	getCashbackBreakdown as getCashbackBreakdownFn,
+	type CashbackBreakdown,
+} from "./math/cashback.js";
 
 // Preview helpers
 import {
@@ -844,6 +849,21 @@ export class LiquidClient {
 		return fetchCashbackConfigFn(this.connection, this.config);
 	}
 
+	/**
+	 * Breaks down a cashback balance into base earnings vs multiplier bonus.
+	 * Pure computation — use cached ranges to avoid RPC calls.
+	 */
+	getCashbackBreakdown(
+		...args: Parameters<typeof getCashbackBreakdownFn>
+	): CashbackBreakdown {
+		return getCashbackBreakdownFn(...args);
+	}
+
+	/** Fetches user state and config from chain, then computes cashback breakdown. */
+	fetchCashbackBreakdown(user: PublicKey) {
+		return fetchCashbackBreakdownFn(this.connection, user, this.config);
+	}
+
 	/** Fetches a user snapshot by user and index. */
 	fetchUserSnapshot(user: PublicKey, index: number) {
 		return fetchUserSnapshotFn(this.connection, user, index, this.config);

package/src/helpers/cashback.ts

@@ -0,0 +1,28 @@
+import type { Connection, PublicKey } from "@solana/web3.js";
+import type { LiquidConfig } from "../config.js";
+import type { CashbackBreakdown } from "../math/cashback.js";
+import { getCashbackBreakdown } from "../math/cashback.js";
+import { fetchUserProperties } from "../accounts/liquid-state.js";
+import { fetchCashbackConfig } from "../accounts/liquid-state.js";
+
+/**
+ * Fetches a user's cashback balance and config from chain, then computes
+ * the breakdown of base earnings vs multiplier bonus.
+ *
+ * @param connection - Solana RPC connection
+ * @param user - User's public key
+ * @param config - Liquid protocol configuration
+ * @returns Breakdown of the user's cashback balance
+ */
+export async function fetchCashbackBreakdown(
+	connection: Connection,
+	user: PublicKey,
+	config: LiquidConfig,
+): Promise<CashbackBreakdown> {
+	const [userProps, cashbackConfig] = await Promise.all([
+		fetchUserProperties(connection, user, config),
+		fetchCashbackConfig(connection, config),
+	]);
+
+	return getCashbackBreakdown(userProps.cashbackCredits, cashbackConfig.ranges);
+}

package/src/helpers/index.ts

@@ -22,3 +22,4 @@ export type {
 
 export { resolveTokenProgram } from "./user.js";
 export { buildEnsureAtaInstruction } from "./ata.js";
+export { fetchCashbackBreakdown } from "./cashback.js";