@exponent-labs/market-three-math 0.1.8

package/build/ytTradesLegacy.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulateSellYt = exports.simulateBuyYtWithSyIn = exports.simulateBuyYt = void 0;
+/**
+ * YT (Yield Token) trade simulations
+ *
+ * YT trades are multi-step operations that involve PT trades:
+ * - Buy YT: Strip SY → PT+YT, then sell PT back to pool
+ * - Sell YT: Merge PT+YT → SY, then buy PT from pool to repay
+ */
+const bisect_1 = require("./bisect");
+const swapV2_1 = require("./swapV2");
+const types_1 = require("./types");
+/**
+ * Helper function to convert PY to SY
+ * @param syExchangeRate - The SY exchange rate
+ * @param pyAmount - The PY (PT or YT) amount
+ * @returns The equivalent SY amount
+ */
+function pyToSy(syExchangeRate, pyAmount) {
+    if (syExchangeRate <= 0)
+        return 0;
+    return Math.floor(pyAmount / syExchangeRate);
+}
+/**
+ * Helper function to convert SY to PY
+ * @param syExchangeRate - The SY exchange rate
+ * @param syAmount - The SY amount
+ * @returns The equivalent PY amount
+ */
+function syToPy(syExchangeRate, syAmount) {
+    return Math.floor(syAmount * syExchangeRate);
+}
+/**
+ * Simulates buying YT tokens
+ *
+ * Process:
+ * 1. Calculate how much SY to strip to get desired YT
+ * 2. Strip SY → PT + YT (PT amount ≈ YT amount)
+ * 3. Sell PT to the pool (PtToSy direction)
+ * 4. Net cost = SY stripped - SY received from PT sale
+ *
+ * @param marketState - Current market state
+ * @param args - Simulation arguments
+ * @returns Simulation result with net SY cost
+ */
+function simulateBuyYt(marketState, args) {
+    const { ytOut, syExchangeRate, priceSpotLimit } = args;
+    // Calculate how much SY needs to be stripped to get the desired YT
+    // Add 1 to counter-act the flooring function when converting from PY to SY
+    const syToStrip = pyToSy(syExchangeRate, ytOut) + 1;
+    // Stripping gives approximately equal amounts of PT and YT
+    const ptFromStrip = ytOut;
+    // Simulate selling the PT to get SY back
+    // Note: We use ytOut as the amount because PT out = YT out from the strip
+    const swapResult = (0, swapV2_1.simulateSwap)(marketState, {
+        direction: types_1.SwapDirection.PtToSy,
+        amountIn: ytOut,
+        priceSpotLimit,
+        syExchangeRate,
+        isCurrentFlashSwap: true,
+    });
+    const syFromPtSale = swapResult.amountOut;
+    // Net cost is the difference between what was stripped and what was received
+    const netSyCost = syToStrip - syFromPtSale;
+    return {
+        ytOut,
+        netSyCost,
+        syToStrip,
+        ptFromStrip,
+        syFromPtSale,
+        lpFee: swapResult.lpFeeChargedOutToken,
+        protocolFee: swapResult.protocolFeeChargedOutToken,
+        finalSpotPrice: swapResult.finalSpotPrice,
+    };
+}
+exports.simulateBuyYt = simulateBuyYt;
+/**
+ * Simulates buying YT tokens given a SY input amount
+ *
+ * Process:
+ * 1. Strip syIn → PT + YT
+ * 2. Sell PT → get SY back (with price impact)
+ * 3. Strip SY again → more PT + YT
+ * 4. Repeat until convergence
+ * Total YT = YT₁ + YT₂ + YT₃ + ...
+ *
+ * Uses bisection search to find ytOut such that netSyCost = syIn
+ *
+ * @param marketState - Current market state
+ * @param args - Simulation arguments
+ * @returns Simulation result with calculated YT output
+ */
+function simulateBuyYtWithSyIn(marketState, args) {
+    const { syIn, syExchangeRate, priceSpotLimit } = args;
+    // Lower bound: Start very low since PT recycling allows buying much more YT than naive calculation
+    // The actual minimum depends on PT price (how much SY we get back from selling PT)
+    // If PT price is high (close to 1), we get most SY back, so we can buy much more YT
+    // Example: With 1000 SY and PT price 0.9:
+    //   - To get 5000 YT, strip 5000 SY → 5000 PT + 5000 YT
+    //   - Sell 5000 PT at 0.9 → 4500 SY back
+    //   - Net cost: 5000 - 4500 = 500 SY (way less than 1000!)
+    const minPossibleYt = 1;
+    // Better initial upper bound estimate based on market liquidity
+    // Maximum possible YT is constrained by available PT liquidity in the market
+    const marketPtLiquidity = Number(marketState.financials.ptBalance);
+    const marketSyLiquidity = Number(marketState.financials.syBalance);
+    // Conservative estimate: we can't buy more YT than there's PT in the market
+    // High multiplier needed because PT recycling amplifies buying power dramatically
+    // Formula: ytOut ≈ syIn / (1 - ptPrice)
+    // Examples: PT@0.99 → 100x, PT@0.95 → 20x, PT@0.90 → 10x, PT@0.80 → 5x
+    const liquidityBasedMax = Math.min(marketPtLiquidity * 0.9, // 90% of PT liquidity to be safe
+    syToPy(syExchangeRate, syIn) * 100);
+    // Start with a reasonable initial guess (10x covers most realistic scenarios)
+    let maxPossibleYt = Math.min(syToPy(syExchangeRate, syIn) * 10, liquidityBasedMax);
+    let foundUpperBound = false;
+    let lastValidCost = 0;
+    // Use exponential search with better growth rate
+    for (let attempt = 0; attempt < 12; attempt++) {
+        try {
+            const syToStrip = pyToSy(syExchangeRate, maxPossibleYt) + 1;
+            const swapResult = (0, swapV2_1.simulateSwap)(marketState, {
+                direction: types_1.SwapDirection.PtToSy,
+                amountIn: maxPossibleYt,
+                priceSpotLimit,
+                syExchangeRate,
+                isCurrentFlashSwap: true,
+            });
+            const syFromPtSale = swapResult.amountOut;
+            const netSyCost = syToStrip - syFromPtSale;
+            // If this costs more than syIn, we found our upper bound
+            if (netSyCost > syIn) {
+                foundUpperBound = true;
+                break;
+            }
+            lastValidCost = netSyCost;
+            // Use adaptive growth rate based on how far we are from target
+            const costRatio = syIn / Math.max(netSyCost, 1);
+            const growthFactor = attempt < 3 ? 2.0 : Math.min(1.5, 1 + costRatio * 0.3);
+            maxPossibleYt *= growthFactor;
+            // Don't exceed liquidity constraints
+            if (maxPossibleYt > liquidityBasedMax) {
+                maxPossibleYt = liquidityBasedMax;
+                foundUpperBound = true;
+                break;
+            }
+        }
+        catch (error) {
+            // If simulation fails, we've exceeded market capacity
+            // Use last valid value with small buffer, ensuring it's > minPossibleYt
+            if (lastValidCost > 0) {
+                // Interpolate to find better upper bound
+                const estimatedMax = maxPossibleYt * 0.7 * (syIn / lastValidCost);
+                maxPossibleYt = Math.max(estimatedMax, minPossibleYt * 1.2);
+            }
+            else {
+                // No valid cost yet, use a conservative upper bound
+                maxPossibleYt = Math.max(maxPossibleYt * 0.8, minPossibleYt * 1.5);
+            }
+            foundUpperBound = true;
+            break;
+        }
+    }
+    if (!foundUpperBound) {
+        throw new Error(`Could not find upper bound for YT amount. Market may have unusual price dynamics.`);
+    }
+    // Final safety check: ensure maxPossibleYt > minPossibleYt
+    if (maxPossibleYt <= minPossibleYt) {
+        maxPossibleYt = minPossibleYt * 2;
+    }
+    // Use bisection search to find the ytOut that results in netSyCost = syIn
+    // Adaptive epsilon based on input size for better precision scaling
+    const adaptiveEpsilon = Math.max(0.01, syIn * 0.0001);
+    // Reduce max iterations since we have better bounds
+    const maxIterations = 10000;
+    // Debug info for bounds validation
+    if (maxPossibleYt <= minPossibleYt) {
+        throw new Error(`Invalid bisection bounds for buy YT. ` +
+            `Min: ${minPossibleYt}, Max: ${maxPossibleYt}, ` +
+            `SyIn: ${syIn}, SyExchangeRate: ${syExchangeRate}, ` +
+            `MarketPtBalance: ${marketPtLiquidity}, MarketSyBalance: ${marketSyLiquidity}`);
+    }
+    const ytOut = (0, bisect_1.bisectSearch2)((ytGuess) => {
+        // Calculate the cost for this ytGuess
+        const syToStrip = pyToSy(syExchangeRate, ytGuess) + 1;
+        const swapResult = (0, swapV2_1.simulateSwap)(marketState, {
+            direction: types_1.SwapDirection.PtToSy,
+            amountIn: ytGuess,
+            priceSpotLimit,
+            syExchangeRate,
+            isCurrentFlashSwap: true,
+        });
+        const syFromPtSale = swapResult.amountOut;
+        const netSyCost = syToStrip - syFromPtSale;
+        // Return the difference between actual cost and target syIn
+        return netSyCost - syIn;
+    }, minPossibleYt, maxPossibleYt, adaptiveEpsilon, maxIterations);
+    if (ytOut === null) {
+        throw new Error(`Failed to converge on correct YT amount. ` +
+            `Search range: [${minPossibleYt}, ${maxPossibleYt}], ` +
+            `Epsilon: ${adaptiveEpsilon}`);
+    }
+    // Now calculate the full result with the found ytOut
+    return simulateBuyYt(marketState, {
+        ytOut,
+        syExchangeRate,
+        priceSpotLimit,
+    });
+}
+exports.simulateBuyYtWithSyIn = simulateBuyYtWithSyIn;
+/**
+ * Simulates selling YT tokens
+ *
+ * Process:
+ * 1. Merge PT + YT → SY (receive SY from the merge)
+ * 2. Buy PT from the pool to repay the borrowed PT (SyToPt direction)
+ * 3. Net received = SY from merge - SY spent on PT
+ *
+ * Note: The market must have at least 2x the YT amount in PT liquidity
+ * because the trader borrows PT, which is then bought back.
+ *
+ * @param marketState - Current market state
+ * @param args - Simulation arguments
+ * @returns Simulation result with net SY received
+ */
+function simulateSellYt(marketState, args) {
+    const { ytIn, syExchangeRate, priceSpotLimit } = args;
+    // Check if there's sufficient PT liquidity
+    // The market needs at least 2x the YT amount in PT
+    if (marketState.financials.ptBalance < ytIn * 2) {
+        throw new Error(`Insufficient PT liquidity in the market. Required: ${ytIn * 2}, Available: ${marketState.financials.ptBalance}`);
+    }
+    // Merging PT + YT gives back the original SY
+    // The amount of PT needed equals ytIn (1:1 ratio)
+    const syFromMerge = pyToSy(syExchangeRate, ytIn);
+    const ptNeeded = ytIn;
+    const upperBoundSwap = (0, swapV2_1.simulateSwap)(marketState, {
+        direction: types_1.SwapDirection.SyToPt,
+        amountIn: syFromMerge,
+        priceSpotLimit,
+        syExchangeRate,
+        isCurrentFlashSwap: true,
+    });
+    // Check that we can buy enough PT from CLMM
+    if (upperBoundSwap.amountOut < ptNeeded) {
+        throw new Error(`Cannot buy enough PT with available SY. Need ${ytIn} PT but can only afford ${upperBoundSwap.amountOut} PT`);
+    }
+    // Better initial bounds for bisection
+    // We know the upper bound from the check above, and we can estimate a better lower bound
+    // based on the current price
+    const estimatedLowerBound = Math.min(syFromMerge * 0.5, syFromMerge * 0.9); // Start from 50% of max, but not too close to upper
+    // Adaptive epsilon based on PT needed
+    const adaptiveEpsilon = Math.max(0.01, ptNeeded * 0.0001);
+    // Safety check: ensure lower bound is less than upper bound
+    const safeLowerBound = Math.min(estimatedLowerBound, syFromMerge * 0.95);
+    const safeUpperBound = syFromMerge;
+    if (safeLowerBound >= safeUpperBound) {
+        throw new Error(`Invalid bisection bounds for sell YT. Lower: ${safeLowerBound}, Upper: ${safeUpperBound}`);
+    }
+    const syToSpend = (0, bisect_1.bisectSearch2)((syGuess) => {
+        const swapResult = (0, swapV2_1.simulateSwap)(marketState, {
+            direction: types_1.SwapDirection.SyToPt,
+            amountIn: syGuess,
+            priceSpotLimit,
+            syExchangeRate,
+            isCurrentFlashSwap: true,
+        });
+        return swapResult.amountOut - ptNeeded;
+    }, safeLowerBound, safeUpperBound, adaptiveEpsilon, 100);
+    if (syToSpend === null) {
+        throw new Error("Failed to converge on correct SY amount using bisection search");
+    }
+    const swapResult = (0, swapV2_1.simulateSwap)(marketState, {
+        direction: types_1.SwapDirection.SyToPt,
+        amountIn: syToSpend,
+        priceSpotLimit,
+        syExchangeRate,
+        isCurrentFlashSwap: true,
+    });
+    const netSyReceived = syFromMerge - swapResult.amountInConsumed;
+    return {
+        ytIn,
+        netSyReceived,
+        syFromMerge,
+        sySpentOnPt: swapResult.amountInConsumed,
+        lpFee: swapResult.lpFeeChargedOutToken,
+        protocolFee: swapResult.protocolFeeChargedOutToken,
+        finalSpotPrice: swapResult.finalSpotPrice,
+    };
+}
+exports.simulateSellYt = simulateSellYt;
+//# sourceMappingURL=ytTradesLegacy.js.map

package/build/ytTradesLegacy.js.map

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

package/examples/.env.example

@@ -0,0 +1 @@
+RPC_URL=

package/examples/test-histogram-simple.ts

@@ -0,0 +1,172 @@
+/**
+ * Simple example: Testing liquidity histogram with mock data
+ */
+
+import { buildLiquidityHistogram, buildLiquidityHistogramSimple } from "../src"
+import { Ticks } from "@exponent-labs/exponent-fetcher"
+import { PublicKey } from "@solana/web3.js"
+
+// Mock ticks data simulating a market with liquidity at various price points
+export const mockTicks: Ticks = {
+  currentTick: 300,
+  currentSpotPrice: 0.03,
+  feeGrowthIndexGlobalPt: BigInt(0),
+  feeGrowthIndexGlobalSy: BigInt(0),
+  currentPrefixSum: BigInt(0),
+  market: new PublicKey("11111111111111111111111111111111"), // Dummy public key for testing
+  ticksTree: [
+    {
+      apyBasePoints: 50, // 0.5%
+      liquidityNet: BigInt(50000),
+      liquidityGross: BigInt(50000),
+      principalPt: BigInt(25000),
+      principalSy: BigInt(25000),
+      impliedRate: 1.005,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(50000),
+    },
+    {
+      apyBasePoints: 100, // 1%
+      liquidityNet: BigInt(100000),
+      liquidityGross: BigInt(100000),
+      principalPt: BigInt(50000),
+      principalSy: BigInt(50000),
+      impliedRate: 1.01,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(100000),
+    },
+    {
+      apyBasePoints: 200, // 2%
+      liquidityNet: BigInt(75000),
+      liquidityGross: BigInt(75000),
+      principalPt: BigInt(37500),
+      principalSy: BigInt(37500),
+      impliedRate: 1.02,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(75000),
+    },
+    {
+      apyBasePoints: 300, // 3%
+      liquidityNet: BigInt(80000),
+      liquidityGross: BigInt(80000),
+      principalPt: BigInt(40000),
+      principalSy: BigInt(40000),
+      impliedRate: 1.03,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(80000),
+    },
+    {
+      apyBasePoints: 400, // 4%
+      liquidityNet: BigInt(-60000),
+      liquidityGross: BigInt(60000),
+      principalPt: BigInt(30000),
+      principalSy: BigInt(30000),
+      impliedRate: 1.04,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(60000),
+    },
+    {
+      apyBasePoints: 500, // 5%
+      liquidityNet: BigInt(-50000),
+      liquidityGross: BigInt(50000),
+      principalPt: BigInt(25000),
+      principalSy: BigInt(25000),
+      impliedRate: 1.05,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(50000),
+    },
+    {
+      apyBasePoints: 600, // 6%
+      liquidityNet: BigInt(-50000),
+      liquidityGross: BigInt(50000),
+      principalPt: BigInt(15000),
+      principalSy: BigInt(15000),
+      impliedRate: 1.06,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(50000),
+    },
+    {
+      apyBasePoints: 700, // 7%
+      liquidityNet: BigInt(-40000),
+      liquidityGross: BigInt(40000),
+      principalPt: BigInt(20000),
+      principalSy: BigInt(20000),
+      impliedRate: 1.07,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(40000),
+    },
+    {
+      apyBasePoints: 800, // 8%
+      liquidityNet: BigInt(-30000),
+      liquidityGross: BigInt(30000),
+      principalPt: BigInt(15000),
+      principalSy: BigInt(15000),
+      impliedRate: 1.08,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(30000),
+    },
+    {
+      apyBasePoints: 1000, // 10%
+      liquidityNet: BigInt(-20000),
+      liquidityGross: BigInt(20000),
+      principalPt: BigInt(10000),
+      principalSy: BigInt(10000),
+      impliedRate: 1.1,
+      feeGrowthOutsidePt: BigInt(0),
+      feeGrowthOutsideSy: BigInt(0),
+      principalShareSupply: BigInt(20000),
+    },
+  ],
+}
+
+console.log("=== Mock Market Configuration ===")
+console.log(`Total Ticks: ${mockTicks.ticksTree.length}`)
+console.log(`Current Spot Price: ${mockTicks.currentSpotPrice}`)
+console.log()
+
+// Build simple histogram (no projection)
+console.log("=== Simple Histogram (Created Ticks Only) ===")
+const simpleHistogram = buildLiquidityHistogramSimple(mockTicks)
+console.log(`Bins: ${simpleHistogram.length}`)
+
+for (const bin of simpleHistogram) {
+  console.log(`  APY: ${bin.apy.toFixed(2)}%, PT: ${bin.principalPt}, SY: ${bin.principalSy}`)
+}
+console.log()
+
+// Build projected histogram (aligned to tickSpace)
+console.log("=== Projected Histogram (100bp bins) ===")
+const tickSpace = 100 // 1% = 100 basis points
+const projectedHistogram = buildLiquidityHistogram(mockTicks, tickSpace)
+console.log(`Bins: ${projectedHistogram.length}`)
+
+for (const bin of projectedHistogram) {
+  console.log(`  APY: ${bin.apy.toFixed(2)}%, PT: ${bin.principalPt.toFixed(0)}, SY: ${bin.principalSy.toFixed(0)}`)
+}
+console.log()
+
+// Verify totals
+const totalPtSimple = simpleHistogram.reduce((sum, bin) => sum + bin.principalPt, 0)
+const totalSySimple = simpleHistogram.reduce((sum, bin) => sum + bin.principalSy, 0)
+const totalPtProjected = projectedHistogram.reduce((sum, bin) => sum + bin.principalPt, 0)
+const totalSyProjected = projectedHistogram.reduce((sum, bin) => sum + bin.principalSy, 0)
+
+console.log("=== Totals Verification ===")
+console.log(`Simple: PT=${totalPtSimple}, SY=${totalSySimple}`)
+console.log(`Projected: PT=${totalPtProjected.toFixed(0)}, SY=${totalSyProjected.toFixed(0)}`)
+
+const ptDiff = Math.abs(totalPtSimple - totalPtProjected)
+const syDiff = Math.abs(totalSySimple - totalSyProjected)
+console.log(`Difference (due to rounding): PT=${ptDiff.toFixed(0)}, SY=${syDiff.toFixed(0)}`)
+
+console.log()
+console.log("✅ Histogram test completed successfully")

package/examples/test-histogram.ts

@@ -0,0 +1,112 @@
+/**
+ * Example: Testing liquidity histogram on live market data
+ *
+ * This script demonstrates how to build a liquidity distribution histogram
+ * from market ticks data.
+ */
+
+import { Connection, PublicKey } from "@solana/web3.js"
+import { ExponentFetcher } from "@exponent-labs/exponent-fetcher"
+import { buildLiquidityHistogram, buildLiquidityHistogramSimple } from "../src/liquidityHistogram"
+
+// Example market address (replace with actual market)
+const MARKET_ADDRESS = "5TSUipMkXQraAik8QVGkvvDFwhLxUjgfW7WqGpsfvG1C"
+const RPC_URL = process.env.RPC_URL || "https://api.mainnet-beta.solana.com"
+
+async function main() {
+  const connection = new Connection(RPC_URL, "confirmed")
+  const fetcher = new ExponentFetcher({ connection })
+
+  console.log("Fetching market data...")
+  const marketPubkey = new PublicKey(MARKET_ADDRESS)
+  const marketData = await fetcher.fetchMarketThree(marketPubkey)
+
+  console.log("Fetching ticks data...")
+  const ticksData = await fetcher.fetchMarketThreeTicks(marketData.ticks)
+
+  console.log(`\nMarket Configuration:`)
+  console.log(`  Tick Space: ${marketData.configurationOptions.tickSpace} basis points`)
+  console.log(`  Total Ticks: ${ticksData.ticksTree.length}`)
+  console.log(`  Current Spot Price: ${ticksData.currentSpotPrice.toFixed(4)}`)
+
+  // Convert to market-three-math types
+  const ticks = {
+    currentTick: ticksData.currentTick,
+    currentSpotPrice: ticksData.currentSpotPrice,
+    feeGrowthIndexGlobalPt: Number(ticksData.feeGrowthIndexGlobalPt),
+    feeGrowthIndexGlobalSy: Number(ticksData.feeGrowthIndexGlobalSy),
+    currentPrefixSum: Number(ticksData.currentPrefixSum),
+    market: ticksData.market.toBase58(),
+    ticks: ticksData.ticksTree.map((tick) => ({
+      apyBasePoints: tick.apyBasePoints,
+      liquidityNet: Number(tick.liquidityNet),
+      liquidityGross: Number(tick.liquidityGross),
+      principalPt: Number(tick.principalPt),
+      principalSy: Number(tick.principalSy),
+      impliedRate: tick.impliedRate,
+      feeGrowthOutsidePt: Number(tick.feeGrowthOutsidePt),
+      feeGrowthOutsideSy: Number(tick.feeGrowthOutsideSy),
+      principalShareSupply: Number(tick.principalShareSupply),
+    })),
+  }
+
+  // Build simple histogram (no projection)
+  console.log("\n=== Simple Histogram (Created Ticks Only) ===")
+  const simpleHistogram = buildLiquidityHistogramSimple(ticks)
+  console.log(`Bins: ${simpleHistogram.length}`)
+
+  for (const bin of simpleHistogram.slice(0, 5)) {
+    // Show first 5
+    console.log(`  APY: ${bin.apy.toFixed(2)}%, PT: ${bin.principalPt.toFixed(0)}, SY: ${bin.principalSy.toFixed(0)}`)
+  }
+  if (simpleHistogram.length > 5) {
+    console.log(`  ... and ${simpleHistogram.length - 5} more`)
+  }
+
+  // Build projected histogram (aligned to tickSpace)
+  console.log("\n=== Projected Histogram (TickSpace Aligned) ===")
+  const tickSpace = marketData.configurationOptions.tickSpace
+  const projectedHistogram = buildLiquidityHistogram(ticks, tickSpace)
+  console.log(`Bins: ${projectedHistogram.length}`)
+
+  for (const bin of projectedHistogram.slice(0, 10)) {
+    // Show first 10
+    console.log(`  APY: ${bin.apy.toFixed(2)}%, PT: ${bin.principalPt.toFixed(0)}, SY: ${bin.principalSy.toFixed(0)}`)
+  }
+  if (projectedHistogram.length > 10) {
+    console.log(`  ... and ${projectedHistogram.length - 10} more`)
+  }
+
+  // Verify totals
+  const totalPtSimple = simpleHistogram.reduce((sum, bin) => sum + bin.principalPt, 0)
+  const totalSySimple = simpleHistogram.reduce((sum, bin) => sum + bin.principalSy, 0)
+  const totalPtProjected = projectedHistogram.reduce((sum, bin) => sum + bin.principalPt, 0)
+  const totalSyProjected = projectedHistogram.reduce((sum, bin) => sum + bin.principalSy, 0)
+
+  console.log("\n=== Totals ===")
+  console.log(`Simple: PT=${totalPtSimple.toFixed(0)}, SY=${totalSySimple.toFixed(0)}`)
+  console.log(`Projected: PT=${totalPtProjected.toFixed(0)}, SY=${totalSyProjected.toFixed(0)}`)
+  console.log(`Difference: PT=${(totalPtSimple - totalPtProjected).toFixed(0)}, SY=${(totalSySimple - totalSyProjected).toFixed(0)}`)
+
+  // Calculate distribution stats
+  if (projectedHistogram.length > 0) {
+    const maxPt = Math.max(...projectedHistogram.map((b) => b.principalPt))
+    const maxSy = Math.max(...projectedHistogram.map((b) => b.principalSy))
+    const maxPtBin = projectedHistogram.find((b) => b.principalPt === maxPt)
+    const maxSyBin = projectedHistogram.find((b) => b.principalSy === maxSy)
+
+    console.log("\n=== Distribution Stats ===")
+    console.log(`Max PT: ${maxPt.toFixed(0)} at APY ${maxPtBin?.apy.toFixed(2)}%`)
+    console.log(`Max SY: ${maxSy.toFixed(0)} at APY ${maxSyBin?.apy.toFixed(2)}%`)
+  }
+}
+
+main()
+  .then(() => {
+    console.log("\n✅ Done")
+    process.exit(0)
+  })
+  .catch((err) => {
+    console.error("\n❌ Error:", err)
+    process.exit(1)
+  })

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@exponent-labs/market-three-math",
+  "version": "0.1.8",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "license": "AGPL-3.0",
+  "scripts": {
+    "build": "tsc --build",
+    "test": "jest",
+    "test:live": "ts-node examples/test-live-market.ts"
+  },
+  "dependencies": {
+    "@exponent-labs/exponent-fetcher": "0.1.8",
+    "@solana/web3.js": "^1.95.8"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.0.0",
+    "dotenv": "^16.4.5",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "ts-node": "10.9.2",
+    "typescript": "5.4.5"
+  },
+  "gitHead": "209b8847e9a0fadb5b5ec96b9b47f0ace4a3bf9d"
+}